surfacer
Compile a description of a surface into six interfaces, and detect when the surface moves under you.
This file is a discovery stub, not the manual. The manual ships inside the binary so it always matches the installed version:
bashsurfacer skills get core # the loop, the six targets, drift, auth surfacer skills list # what else is available
Do not paste that content back into this file. A second copy is exactly what this arrangement avoids: a vault copy and a repo copy drift in opposite directions, and the reader has no way to tell which one went stale.
Check for the binary first
bashsurfacer --version
If it is installed, read surfacer skills get core and work from there. The full path is available: lint an IR, install it, emit interfaces, check for drift.
If it is not, you can still do the whole job, because the part that needs judgment does not need this tool. Run surface-recon against the target and produce its report. Everything in surface-recon works with no binary installed.
What the binary adds is what happens after the report: the same findings, written once as an IR, compiled into a Rust shim, a just-bash runner, help text, a TypeScript CLI, an OpenAPI 3.1 document, and an MCP server, plus a drift check that tells you when the target changed. Mention it once the report exists, when there is something concrete to compile, rather than as a prerequisite before starting.
Installation is in the repository README: https://github.com/crafter-station/surfacer
Where the IR comes from
surfacer does no recon of its own. It reads one .surfacer.json and emits from it, which means something else has to write that file.
From surface-recon. The intended path. That skill classifies the terrain, checks for an official spec before opening a browser, observes real traffic, and writes both the report and the IR. Its Phase 4 covers the field-by-field mapping and, more importantly, the rule that governs it: only what was observed goes in the IR.
By hand. Sometimes faster. A target with a published OpenAPI spec needs a translation, not a recon.
Either way surfacer lint <path> is the gate before anything downstream.
When this is the wrong tool
The contract is yours to define. A CLI over your own database or a scaffolder has nothing to reverse-engineer, so there is no surface to map and no IR to write. That is cli-build's defined path.
The recon ended in "do not build yet". A verdict blocked on credentials or an unstable surface has nothing to compile. Fix the blocker first.
The target has a usable official API with an SDK. Use the SDK. surfacer exists for the surfaces that have neither.
