.sightmap/ directory is a curated authority: authored and maintained by coding agents and humans, curated against the running app. Nothing generates it from your code; there is no build step that writes YAML. That keeps the corpus honest about what the app actually does — including the quirks source can’t tell you.
The tool
Authoring runs through thesightmap CLI (Go), which drives a real Chrome session over the Chrome DevTools Protocol and layers your .sightmap/ corpus onto the live page. You get:
- Annotated snapshots — the page’s component tree with every matched node named
[ComponentName prop="val"]from your corpus. - Coverage — every interactive node scored T1 (directly matched), T2 (unnamed inside a matched ancestor), or T3 (orphaned), so you know what’s left to name.
The loop
Authoring is an edit-verify loop against a live page.1
Start a session
browser start launches Chrome and a local server that hot-reloads the corpus whenever you edit YAML — no restart between edits. The overlay browser extension is embedded in the binary and extracted automatically on first run. Session commands are documented in sightmap browser.2
Iterate a page
sightmap iterate navigates, snaps, and prints coverage in one step:iterate is built for speed: it suppresses the tree output and writes its capture to a temp file, leaving your saved view sets untouched. Reach for sightmap snapshot when you want the full annotated tree or a recorded capture — both are covered in Capture.3
Verify the suggested selector
Every unlabeled cluster ends with a
→ selector hint. Never write YAML from an unverified selector — probe it against the live page first:sel-probe reports the match count, each match’s key attributes, and the parent chain, marking the nearest already-known component with a ★. A wrong match count corrupts coverage; the right one becomes your selector: value. Selector tooling — including offline checks with sel-check — lives in Selector tools; selector strategy in Selectors & match strategy.4
Name what's unnamed
Add the component to the matching view file under The top-level The running session hot-reloads your edit immediately. The component shape — children, selectors, naming — is specified in Components;
.sightmap/views/ (or to components.yaml if it appears app-wide):.sightmap/views/products.yaml
url: matters beyond documentation — it is where report and snapshot --all learn which page represents this view.Then check the structure:validate and its companions in Corpus hygiene.5
Repeat until zero orphans
Re-run
iterate after every edit. The page is done when the coverage line reads 0 orphaned T3 ✓ — then move on to the T2 triage below.Triage what’s left: T2 quality
Zero T3 is necessary but not sufficient. A T2-tight node — the single interactive child of its named ancestor — is fine: events attribute cleanly. T2-loose scopes, where several unnamed siblings share one ancestor, are indistinguishable in event logs. They are your remaining authoring queue. Re-snap withsightmap snapshot --trace to include selector hints for every unlabeled interactive cluster, ranked by how many nodes share the scope (sightmap coverage --trace prints the same cluster detail offline from saved captures). Classify every multi-child scope — don’t just accept it — and record the verdict in the component’s or view’s memory::
While you are here, finish the quality pass: every T1 link or button should carry at least one property somewhere in its chain, and any component that matches zero nodes deserves investigation before you accept the result. Coverage commands are documented in Coverage.
Promote shared components
Once several views are mapped, look for components that recur:components.yaml when it appears in two or more views:
- 3+ views, same selector — always promote.
- 2 views, same selector — usually promote.
- 2 views, different selectors — keep it view-scoped.
Check corpus health and refresh captures
Close a session of authoring with the health pass:report prints one row per view, scored over the view’s whole view set — a view fails when any capture still has orphans, or when it has no captures at all. snapshot --all visits every URL your view files declare (the top-level url: plus any snapshots[].url variants) and appends timestamped captures to each view’s set. A novelty gate keeps dynamic pages from accumulating churn: a re-snap is saved only when it adds something structurally new; otherwise the CLI reports it as nothing new and skips the write. View sets, the novelty gate, and pruning are covered in View sets.
The skills are the authoritative playbook
The detailed loop — coverage tiers, the component model, property extraction, cross-page promotion, the quality checklist — lives in the bundled agent skills, which are the source of truth for how to author:sightmap-authoring— building and maintaining a corpus.sightmap-browser— driving a live session and acting on a finished corpus; the interaction commands it drives are documented in Interaction.
Maintaining a corpus
.sightmap/ moves with the app. When routes or components change, re-run the loop on the affected pages — existing memory:, properties:, and selector choices are preserved; newly orphaned nodes surface in coverage. Memory entries are written at use time, based on what an agent observed while working the app; where a quirk can be fixed in the app instead of memorized, prefer that. The wider process — bootstrap, maintenance triggers, CI — is the curation workflow.
Hand-authoring
None of this is required..sightmap/ is plain YAML validated against a public JSON Schema — hand-editing is always fine, and the spec defines every field. The CLI and skills exist to keep curation cost near zero as the app grows.