/surface-recon

name: surface-recon
version: 0.8.0
description: "Map an authorized target into evidence-backed contracts and produce a recon report an implementer can build from. Use for web or mobile APIs, login portals, desktop apps, CLIs, SDKs, MCP servers, local daemons, file and project formats, USB/BLE/serial/HID devices, firmware packages, runtimes, and accelerators. Trigger when the user says recon, reverse engineer, map the interface or protocol, inspect an undocumented integration, discover what a device actually supports, or wants to build a client, CLI, MCP, SDK, adapter, or compatible implementation before its contract is verified."

surface-recon

Map what a target exposes, what it demands of you, and what will bite you. Produce a report someone else can build from without repeating your work.

This skill investigates. It does not design a command surface or write code: that is `cli-build`'s job. Stopping at a report is the point: recon tells you whether building is worth it.

The one rule

**Every claim in the report is either observed or labeled as unverified.** A recon report that guesses without saying so is worse than no report, because the implementer trusts it and loses a day. Mark inference as inference.

Concretely: an evidence row states its plane, claim, provenance, acceptance proof, and receipt. Anything inferred names the exact step that would verify it.

**Open `recon/friction.md` before Phase 0 and append to it as you go.** Every time a playbook is thin, a command fails for a reason its help text did not predict, or a gate does or does not hold, that is one line written at the moment it happens. It ships with the report and it is the only input that improves this skill. See [friction-log.md](references/friction-log.md).

Instrument router

Choose instruments after classifying the plane. A target can expose several planes, and each plane needs its own evidence.

| Plane | Start with | |---|---| | Network or web UI | Official specs, then `agent-browser` capture and independent replay | | Desktop or mobile UI | Screenshot and accessibility, then network, logs, and disposable artifacts | | CLI, SDK, MCP, daemon | Help or schema enumeration, controlled calls, exit/status and state fixtures | | File or project format | Real samples, metadata, schema inference, normalized round-trip | | USB, BLE, serial, HID | OS enumeration, descriptors, passive capture, differential sessions | | Firmware | Official update packages, hashes, extraction, trust-chain inventory | | Runtime or accelerator | Accepted and rejected workloads, tracing, per-unit placement metrics |

For network and interactive browser planes, `agent-browser` ships version-matched guides. Load them rather than guessing commands from memory:

agent-browser skills get core           # the workflow: snapshot, refs, waits, sessions, mocking
agent-browser skills list               # what else is available

Two specialized ones carry most of the recon weight:

• **`derive-client`** turns a recorded session into a working client. For a website with an internal JSON API, it often does the whole of Terrain B better than hand-rolling: `agent-browser skills get derive-client`
• **`electron`** automates desktop apps over their debugging port, which beats unpacking them: `agent-browser skills get electron`

This skill deliberately does not restate what those cover. When a capability is documented there, [agent-browser-recon.md](references/agent-browser-recon.md) points at it instead of copying it, so the two cannot drift apart.

When an instrument says the element is not there

**Screenshot first, and look at it with your own eyes.** If a page the user sees working reports "element not found", the capture comes before exhausting selectors, not after.

Three times in one project an indirect instrument said "does not exist" and the screenshot showed the element on screen: a login panel, a set of showtimes, a buy button. Each time the tooling was correctly built and pointed at the wrong thing. A login panel generates no traffic and contains no domain keywords, so it is invisible to a network tab and a DOM grep at the same time.

Two specifics worth knowing:

• **An open modal invalidates the entire accessibility tree.** A cookie banner returns as the whole snapshot, which reads as "the page has no content". Dismissing it is a precondition of any structural read, not a cleanup step.
• **Match on substrings, not equality.** A selector comparing against `19:20` finds nothing on a page rendering `19:20hs`.

The failure mode this prevents is not a missing tool. It is reaching for the instrument that represents you as someone who reads systems, over the one that answers the question.

Phase 0: profile the terrain

Before touching an instrument, classify four dimensions. Read [terrain-model.md](references/terrain-model.md).

| Dimension | Values | Why it matters | |---|---|---| | Access | `public`, `owned`, `granted`, `blocked`, `mixed` | Defines authority and whether meaningful observation can start | | Planes | `network`, `interactive`, `command`, `artifact`, `device`, `firmware`, `runtime` | Routes instruments and keeps evidence separated | | Acceptance | `enumeration`, `replay`, `state-transition`, `contract-conformance`, `round-trip`, `receipt-plus-poststate`, `execution-placement`, `boot-and-recovery` | Defines what proves the claim | | Maximum consequence | `passive`, `reversible`, `creative`, `persistent`, `destructive`, `external` | Defines approval, audit, cleanup, and recovery gates |

Record a profile before probing:

access: owned
planes: [device, network, artifact]
primary-plane: device
acceptance: [enumeration, replay, receipt-plus-poststate, round-trip]
maximum-consequence: persistent

**Done when:** access is established, all currently visible planes are listed, each intended claim has an acceptance proof, and the run has a consequence ceiling.

Two profiles are traps worth naming up f