Curator vs. consumer

A sightmap has two sides. Someone has to write .sightmap/, and something has to read it. The spec is deliberately shaped so these two jobs stay separate, because they are not equally hard.

Curator: the side with the work

The curator writes and maintains .sightmap/. They name the views, pick the selectors, decide which components matter, and capture the memory entries that turn the file from a structural skeleton into something an agent can actually use.

In practice, curation is almost never done by hand. The curator is a human working with an agent — and the agent is doing most of the typing. Three official tools cover the curation surface:

• @sightmap/react scaffolds .sightmap/ from a React-Router project. It scans routes, finds data-sightmap attributes in source, and writes per-feature YAML files with structural fields filled in and TODO blocks where the human-or-agent still has work to do.
• @sightmap/mcp is an MCP server that lets an agent read the running app, validate the sightmap, and patch agent-authored fields like memory and intent — without granting it free write access to selectors and routes.
• @sightmap/plugin wires Claude Code session hooks so the agent loads the sightmap on startup and gets advisory checks when it touches UI source.

Curation is the hard problem because it is judgment work. What’s the right granularity for a component? Is this quirk worth capturing as memory or is it noise? Should this selector be one string or three? Did refactoring just break a selector silently? No tool answers those questions for you, but the right tools give an agent enough leverage to draft, drift-check, and iterate alongside the human.

Consumer: the side that should stay small

The consumer reads .sightmap/ and uses it. Examples: a coding agent (Claude Code, Cursor, Codex) that loads the file as repo context; an IDE plugin that surfaces components in a sidebar; a runtime like Subtext that injects names, memory, and source paths into live browser snapshots; a CI check that validates the file.

Consumers should be small because the spec does most of the work. Match a URL against views[].route. Pull the active components and requests. Try selector strings in order until one matches. Surface memory in a [Guide] block. That’s the shape of every consumer. The library does the heavy lifting — the integration is mostly plumbing.

This asymmetry is intentional. Anyone wanting to consume a sightmap should be able to do it in an afternoon with @sightmap/sightmap (or a re-implementation in their language of choice — see the conformance fixtures). Curation is where the time goes, and where tooling pays for itself.

If you’re building something that reads .sightmap/, start at the JSON Schema and the conformance fixtures. If you’re filling one in, start at the curation workflow.