> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sightmap.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Sightmap: Runtime Context for Agents Using Your Web App

> An open YAML format and CLI for sharing runtime context about your app with Sightmap-enabled agents.

Sightmap is an open YAML format and CLI for sharing runtime context about a web app. A `.sightmap/` directory checked into your repo names views, components, and API requests; `memory` notes record runtime quirks, invariants, and shortcuts that source code does not explain. Agents curate the map against the running app. Definitions link back to source files, and Sightmap-enabled tools read the same checked-in context.

## What an agent sees

The same date picker appears differently in a bare accessibility snapshot and one enriched by Sightmap:

<CodeGroup>
  ```text Bare accessibility tree theme={null}
  uid=1_0  RootWebArea "Book a flight"
  uid=1_3  textbox "Departure date"
  uid=1_8  button "Previous Month"
  uid=1_9  button "Next Month"
  uid=1_10 generic "July 2025"
  uid=1_19 gridcell "Choose Tuesday, July 1st, 2025"
  uid=1_20 gridcell "Choose Wednesday, July 2nd, 2025"
  uid=1_21 gridcell "Choose Thursday, July 3rd, 2025"
           ...28 more gridcells...
  ```

  ```text With a sightmap theme={null}
  [View: FlightSearch "/search"]
  [Guide]
  - DepartureDatePicker accepts typed YYYY-MM-DD
    // skips opening the calendar
  - Arrow keys navigate the grid; Enter selects; Esc closes
  - Past dates render but are aria-disabled
  - Range: 1st click = start, 2nd = end, 3rd resets

  uid=1_0  RootWebArea "Book a flight"
  uid=1_1  FlightSearchForm visible
  uid=1_3    DepartureDatePicker [src: src/components/DatePicker.tsx] visible interactive
  uid=1_4      date-input visible interactive
  uid=1_8      prev-month visible interactive
  uid=1_9      next-month visible interactive
  uid=1_10     month-label "July 2025" visible
  uid=1_19     day "Choose Tuesday, July 1st, 2025" visible interactive
           ...30 more days...
  ```
</CodeGroup>

A bare accessibility snapshot has no view name, component identity, or indication that the textbox accepts typed dates. With Sightmap, the agent sees the current view, the picker's typed-input shortcut, the disabled state of past dates, and a link to the source file.

## Get started

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/start/quickstart">
    Install the CLI, then have your agent build a `.sightmap/` against any running web app.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/cli/overview">
    `sightmap` commands for browser sessions, snapshots, coverage, selectors, and corpus health.
  </Card>

  <Card title="The spec" icon="file-lines" href="/spec/overview">
    The version 1 YAML format for views, components, requests, and memory, with its JSON Schema and conformance fixtures.
  </Card>

  <Card title="Authoring" icon="map" href="/authoring/overview">
    How agents inspect the running app, verify selectors, and maintain `.sightmap/`.
  </Card>
</CardGroup>

## How Sightmap works

An agent does the mapping. You install the skills once and review the diff before it lands.

<Steps>
  <Step title="Install the skills (once)">
    Run `npm install -g @sightmap/sightmap`, then `sightmap skills install` to add the `sightmap-authoring` and `sightmap-browser` skills to your agent harness. This is the one-time human setup.
  </Step>

  <Step title="Point your agent at the running app">
    Give your agent the app's URL and ask it to build a sightmap. It runs `sightmap browser start` to launch Chrome and a local corpus server that reloads the YAML as it changes.
  </Step>

  <Step title="The agent maps each view">
    Through the `sightmap-authoring` skill, the agent runs `sightmap snapshot --coverage` on each route, names the interactive nodes that come back unattributed, and repeats until every view reports zero orphaned nodes.
  </Step>

  <Step title="Review and check in">
    The agent validates and lints as it goes. You review the diff and commit `.sightmap/` — Sightmap-enabled agents and tools then read the same checked-in context.
  </Step>
</Steps>

<Note>
  Sightmap is an MIT-licensed specification with one reference implementation: the `sightmap` CLI and Go library. The spec, implementation, conformance fixtures, and these docs live in one repo at [github.com/sightmap/sightmap](https://github.com/sightmap/sightmap).
</Note>