Authoring

You don’t author a sightmap by hand.

A sightmap describes how a web app behaves at runtime — its routes, components, network calls, and the institutional knowledge an agent needs to drive it. That description should be derived from source, not transcribed from it. The tools in this section are the derivation pipeline.

The mental model

Curation runs in two phases:

1. Bootstrap — once, when you first add Sightmap to a repo. The React adapter scans your router and source, finds data-sightmap attributes, and writes per-feature YAML files under .sightmap/. The structural skeleton (view names, routes, selectors) is generated. The agent-authored fields (memory, intent, requests) are seeded as commented TODO blocks for an agent — or you — to fill in.
2. Maintain — every time routes change, components move, or you learn something new about the app, you re-run the codegen. Structural fields refresh from source. Agent-authored fields, comments, and ordering survive untouched.

The codegen is idempotent. Running it against an unchanged repo writes nothing. Running it against a freshly emptied .sightmap/ rebuilds the skeleton and re-emits the TODO scaffolding. There is no separate “init” — gen is init when the directory is empty.

What writes what

Different surfaces own different fields:

• The React adapter (@sightmap/react) owns structural fields: name, route, selector, children. It writes them on every gen run.
• An agent (via the MCP server, the Claude Code plugin, or just an editor) owns descriptive fields: description, intent, memory, requests. The smart-merge writer preserves them across regenerations.
• You rarely touch YAML directly. When you do, the lint and validate tools tell you immediately if the file drifted from source.

Pages in this section

• @sightmap/react — the bootstrap path. Mount the provider, decorate with data-sightmap, run sightmap-react gen.
• @sightmap/cli — the sightmap command-line tool. validate, lint, match, explain. Used in CI and during day-to-day curation.
• @sightmap/core — the library API behind the CLI. For tool builders integrating sightmap into IDEs, MCP servers, or custom workflows.
• @sightmap/mcp — an MCP server combining browser introspection with .sightmap/ curation tools. The recommended way to let a host agent author for you.
• Plugin (Claude Code) — advisory hooks that nudge Claude Code toward MCP curation tools and validate every .sightmap/ mutation.

If you’re starting from scratch, follow the React quickstart — it walks the bootstrap-and-maintain loop end to end.