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, reconcile, and maintain — and each is agent-driven, against the running app.

.sightmap/ is curated authority, not a generated artifact. The runtime is the bridge: the live snapshot exposes what React actually rendered, and the agent reconciles the YAML against it.

Bootstrap: get an initial .sightmap/ from the running app

Most projects start with no .sightmap/ directory. Two pieces, in order:

1. sightmap init (@sightmap/sightmap) scaffolds an empty .sightmap/app.yaml, wraps your app entry with <SightmapProvider> via codemod, and wires the MCP server into your agent harness. No codegen — just enough scaffolding for the agent to start from.

2. An agent walks the running app. With your dev server up and the Vite plugin serving the live runtime snapshot, the agent calls sightmap_runtime_snapshot at each route, proposes views and components through sightmap_propose_view and sightmap_propose_component, and commits the accepted batch with sightmap_commit_proposals. The Claude Code plugin drives this loop through the /sightmap:bootstrap skill.

The structural fields come from runtime observation, not source parsing. Selectors are ranked from stable (data-sightmap, data-testid) to fragile (ARIA, semantic, id); if no stable candidate exists, the agent proposes adding data-sightmap to JSX as part of the bootstrap pass.

Reconcile: keep the YAML aligned to what the app actually does

Two surfaces, two checks.

• Corpus consistency — sightmap check validates .sightmap/ against itself: schema, key ordering, cross-file references, duplicates. It does not compare against React source.
• Runtime alignment — re-run the bootstrap skill. The agent re-takes runtime snapshots and surfaces new routes or components as proposals. Existing entries (memory, requests, selector overrides) are preserved.

There is no gen --check style CI gate. Static drift detection would require re-introducing the framework-shape AST adapters that the v0.6 pivot removed. Drift discovery is agent-driven instead — through the bootstrap skill, the /sightmap:reflect nudge when source files with data-sightmap markers have been edited, and the PostToolUse audit hook that surfaces cross-file inconsistencies after MCP writes.

Maintain: capture what only the running app knows

As the app evolves, the agent captures things that aren’t visible from source at all: a quirk discovered during a session, a clarifying description, a new endpoint observed in network traffic. These land through MCP — sightmap_update_view (patches description and memory), sightmap_add_view / sightmap_delete_view, plus sightmap_network_requests for request payload discovery.

The agent owns the entire corpus. Hooks and the structural linter keep it valid; the runtime keeps it honest about reality.

The loop in one sentence

The runtime exposes what’s real; the agent reconciles the YAML against it; the plugin and hooks keep both in step.

None of the 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 which packages sit on which side of the YAML format itself.