> ## 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 Quickstart: Build a .sightmap/ From a Running App

> Install the CLI, start a browser session, and build a checked-in .sightmap/ against your running app.

Hand a running app to your agent and it builds a `.sightmap/` directory in your repo — driving the browser and running the CLI through the `sightmap-authoring` skill. The app can be a local dev server, preview deployment, or hosted URL. The agent writes the YAML; you review the diff before committing it.

<Steps>
  <Step title="Install the CLI and skills (once)">
    ```bash theme={null}
    npm install -g @sightmap/sightmap
    sightmap skills install
    ```

    `sightmap skills install` writes `sightmap-authoring` and `sightmap-browser` to `~/.agents/skills`. Pass `--target <dir>` to use another directory. See [Install](/start/install) for the `npx`, Go, and browser-install options.

    This is the one-time human setup. From here on, your agent runs the browser session and the CLI through these skills.
  </Step>

  <Step title="Hand your agent the app">
    Point your agent at the running app and give it a prompt like:

    > Build a sightmap for this app at `http://localhost:3000/`. Start a browser session, inspect the main routes with `sightmap snapshot --coverage`, verify each selector with `sightmap sel-probe`, and name components until every view has zero orphaned T3 nodes. Let me review the YAML before committing it.

    Through the `sightmap-authoring` skill, the agent starts the session itself:

    ```bash theme={null}
    sightmap browser start --url 'http://localhost:3000/'
    ```

    `browser start` launches Chrome and the local corpus server, which reloads the YAML whenever the agent changes it.

    <Note>
      Prefer to drive it yourself? Run `sightmap browser start` from your project root, leave it in the foreground, and use another terminal for the loop commands below.
    </Note>
  </Step>

  <Step title="The agent runs the edit-verify loop">
    For each route, the agent repeats this loop:

    ```bash theme={null}
    sightmap snapshot --coverage --url 'http://localhost:3000/'
    sightmap sel-probe -- '[data-testid="product-pod"]'
    ```

    `snapshot --coverage` reads the page, reports coverage, and suggests selectors for unattributed nodes. The agent probes a selector, updates `.sightmap/`, and runs it again.

    ```text theme={null}
    [View: ProductListPage "http://localhost:3000/products"]
    [Coverage] (visible only)
    87 interactive · 21 direct T1 (24%) · 61 scoped T2 (70%) · 5 orphaned T3 ✗

    Unlabeled clusters:
      5× button (no text)
           inside: div[data-testid="product-pod"]
           → [data-testid="product-pod"] button
    ```

    `T1` nodes have their own component name. `T2` nodes sit inside a named component. `T3` nodes have no named ancestor. The agent keeps iterating until each view reports `0 orphaned T3 ✓`.
  </Step>

  <Step title="Review and commit">
    The agent validates and lints as it works:

    ```bash theme={null}
    sightmap validate
    sightmap lint
    ```

    `validate` checks the YAML structure and exits nonzero on errors; `lint` reports advisory quality issues. When the agent reports the views clean, review the new or changed YAML and commit it:

    ```text theme={null}
    .sightmap/
      components.yaml      # global components, matched on every view
      views/
        home.yaml          # one file per view, with its route and url
        products.yaml
        account.yaml
    ```
  </Step>
</Steps>

## Keep the corpus current

If the app has no stable selector for a component, add `data-component="ComponentName"` to the source. This gives Sightmap an explicit runtime hook.

When a route or component changes, have your agent rerun `sightmap snapshot --coverage` on the affected pages. Existing selectors and `memory` entries remain in the corpus, while coverage exposes new orphaned nodes.

## Next steps

* [Authoring overview](/authoring/overview) for the curation model and workflow.
* [CLI reference](/cli/overview) for every command and flag.
* [`sightmap-authoring` skill](https://github.com/sightmap/sightmap/blob/main/go/skills/sightmap-authoring/SKILL.md) for the full agent playbook.
* [Schema reference](/reference/schema) for every version 1 field and constraint.