The curation workflow

A .sightmap/ directory is not written once and forgotten. It moves with the app: routes change, components get renamed, a quirk that justified a memory entry gets fixed, a new endpoint appears. The authoring tools are designed around three recurring jobs — bootstrap, audit, and update — and each official package targets one of them.

Bootstrap: get the structural skeleton in place

Most projects start with no .sightmap/ directory. The first job is to convert the routes and components that already exist in source into a YAML scaffold the team can iterate on. Doing this by hand is tedious; it is also the single most agent-friendly task in the whole curation process, because the answers are already in the code.

For React-Router projects, @sightmap/react ships a gen CLI that does the bootstrap in one shot:

npx sightmap-react gen

It walks the React-Router config, AST-scans for data-sightmap attributes, and writes per-feature YAML files under .sightmap/. Each file gets the structural fields the codegen owns — view name, route, selector — plus commented TODO blocks for the agent-authored fields it does not own (memory, intent, requests). The file parses cleanly until the curator (or, more often, an agent in pair-mode) fills in the TODOs.

Re-running gen is idempotent: structural fields refresh from source, agent-authored fields are preserved untouched, and the TODO scaffolding is not re-emitted into files that already exist.

Audit: surface what’s wrong now

Once the skeleton exists, an agent can inspect the running app and decide what’s missing. @sightmap/mcp is the MCP server for this loop. It wraps @playwright/mcp and adds:

• Browser tools — sightmap_snapshot (an ARIA snapshot enriched with sightmap awareness), sightmap_match, sightmap_act, sightmap_network_requests.
• Curation tools — sightmap_list_views, sightmap_get_view, sightmap_check (schema and quality validation), sightmap_update_view (patches description, intent, memory), sightmap_init_project.

The asymmetry matters. The agent can read everything, validate everything, and patch the agent-authored fields freely. It cannot rewrite selectors or routes through MCP — those stay codegen-owned, behind sightmap-react gen and a re-scan of source. This separation keeps the structural map honest while letting the agent capture quirks the moment it discovers them.

Update: keep the file aligned to the code

The third job is keeping the map current as the app evolves. Two lanes:

• Source-driven changes (a new route, a new data-sightmap attribute, a renamed component) → re-run sightmap-react gen. Use gen --check in CI to fail the build if the committed .sightmap/ is stale.
• Behavior-driven changes (a quirk discovered during a session, an intent clarification, a new endpoint to capture) → the agent calls sightmap_update_view through MCP, or hand-edits a memory entry.

@sightmap/plugin closes the loop inside Claude Code with session-start context loading and PreToolUse / PostToolUse advisory hooks. It nudges the agent to read the relevant .sightmap/ file before it edits the matching UI source, and to run a validate-and-cascade check after.

The shape of the loop, in one sentence: codegen scaffolds structure; MCP captures behavior; the plugin keeps the agent honest about both. None of these tools are required — .sightmap/ is plain YAML, hand-authoring is fine — but together they make sure curation costs stay close to zero as the app grows. See Curator vs. consumer for why all three sit on the curator side of the line.