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. The official tools cover the curation surface:

• @sightmap/sightmap is the unified CLI and library. sightmap init scaffolds an empty .sightmap/ and wires the agent harness; sightmap check validates the corpus.
• @sightmap/react is the React runtime — <SightmapProvider> and a Vite plugin that exposes the live fiber-tree at /__sightmap__/snapshot.json. The bridge between a running app and an agent.
• @sightmap/mcp is an MCP server that lets an agent walk the runtime, propose views and components from what it observes, review the batch, and commit it to .sightmap/. The agent owns the entire corpus; hooks and the structural linter keep it valid.
• @sightmap/plugin wires Claude Code skills (/sightmap:bootstrap, /sightmap:reflect, /sightmap:audit) plus session hooks that load the sightmap on startup and surface inconsistencies after every MCP write.

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, validate, 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.