| name | surfacer |
| version | 0.1.0 |
| description | Compile a mapped surface into working interfaces and keep them alive as the target changes. Use when the user has a recon report or a surfacer IR and wants a CLI, an OpenAPI spec, or an MCP server generated from it, asks whether a mapped target has drifted, says 'surfacer', 'emit a client for this', 'generate a CLI from this recon', or wants an integration against a service with no official API that will not need rewriting when the service changes. Pairs with surface-recon, which produces the IR. |
| allowed-tools | Bash(surfacer:*) |
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:
surfacer skills get core
surfacer skills list
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
surfacer --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.
