Skip to main content
A sightmap is a directory of YAML files at the root of a project, under .sightmap/. It describes the app’s views, components, and requests, with optional memory entries that carry notes agents can use at runtime. These pages are the readable walk-through. The exhaustive field-by-field contract lives in the Schema reference and is generated from the canonical spec.

​
What’s in a sightmap

Four kinds of definitions, all optional:

Views

Named screens identified by URL routes.

Components

Named DOM subtrees identified by CSS selectors.

Requests

Named API endpoints identified by route patterns.

Memory

Short freeform notes attached to any of the above.
Every *.yaml and *.yml file under .sightmap/ is discovered recursively and merged. The directory layout is for authors; it has no semantic meaning.

​
Top-level fields

Every file begins with version: 1. All other top-level keys are optional.
components and requests at the file root are global — matched against every view. Nest them inside a view to scope. Scoped definitions are additive with globals. Entries in any components: array may also be $ref references to shared definitions. See Components and Requests for the matching rules.

​
Two versioning axes

The spec and the project that publishes it move independently.
  • The spec stream is the integer in the YAML version: field. It is currently 1 and bumps only on breaking changes to the format.
  • The project semver describes how settled stream 1 is. It is currently 0.1.0 — pre-1.0, so the spec may be tightened or clarified in place. Project releases are published on GitHub Releases. After 1.0.0, the rules in Versioning become commitments.
We aim to keep the spec at stream 1 for a long time. A version: 2 would mean a new spec/v2/ directory and a real, accepted breaking change.

​
A small example

.sightmap/home.yaml
That is the smallest file that does anything useful. Everything else in this section is layered onto this shape: more views, nested components, glob routes, request definitions, and memory entries.
Quote attribute selectors so YAML parses them as strings: selector: '[data-component="X"]'. Unquoted, the brackets are read as a YAML flow sequence and the entry fails validation.

​
Next

Start with Views for routes and view-level structure, then Components for selector semantics. The full schema reference, including every field on every type, is in Schema reference.