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

> ## Agent Instructions
> Reticle is a dev-only, localhost-only verification layer for AI coding agents. It reads program truth (network, state, console, routing, animations, framework state) from inside a running web app and returns a deterministic verdict with evidence. It is not a screenshot tool and not a browser automation library.
> Only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Every other tool moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.
> A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown; never weaken a check to make it pass.
> Package names are scoped `@reticlehq/*` and the CLI is `reticle`. Install with `npx reticle init`. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version.

# reticle_tools and reticle_run

> Discover the 30 tools that are not advertised, load their argument grammar on demand, and invoke any of them by name.

Reticle advertises 18 tools and ships 48. These two meta-tools are how your agent reaches the other 30 without paying for their schemas on every turn.

`reticle_tools` discovers. `reticle_run` invokes. Together they cost two tool definitions instead of thirty.

## Discovering what exists

```json theme={"dark"}
{}
```

Returns every tool with a one-line summary. A sample of what lives in the cold tail:

| Tool                    | What it does                                                           |
| ----------------------- | ---------------------------------------------------------------------- |
| `reticle_capabilities`  | The app's advertised testable surface, testids, signals, stores, flows |
| `reticle_flow_verify`   | Replay every saved flow, return one consolidated suite verdict         |
| `reticle_screenshot`    | Pixel screenshot of the driven page, saved as a visual baseline        |
| `reticle_visual_diff`   | Perceptually diff the live page against that baseline                  |
| `reticle_network_mock`  | Force a 500, go offline, or delay a response                           |
| `reticle_viewport`      | Pin the viewport so screenshots are reproducible across machines       |
| `reticle_crawl`         | Click every reachable control and report anomalies, with no script     |
| `reticle_clock`         | Freeze time or fast-forward timers, toasts, debounces, auto-dismiss    |
| `reticle_storage`       | localStorage, sessionStorage and readable cookies                      |
| `reticle_coverage`      | Which controls you have driven this session, and which you have not    |
| `reticle_verify_change` | Give it the files you edited; it replays the flows that cover them     |
| `reticle_reconcile`     | Compare what the API returned against what the page actually renders   |
| `reticle_scroll_to`     | Find a row in a virtualised list that has not rendered yet             |

The response also tells you which surface is active:

```json theme={"dark"}
{
  "profile": {
    "active": "default",
    "source": "the one tool surface (RETICLE_ADVERTISE_ALL_TOOLS unset when the daemon started)",
    "note": "The profile is read once at daemon startup — change it and restart the daemon, or it has no effect."
  },
  "next": "Load params with reticle_tools { names:[…] }, then call reticle_run { tool, args }."
}
```

<Warning>
  "Read once at daemon startup" is doing real work in that sentence. Setting the environment
  variable in a shell where a daemon is already running changes nothing, and the resulting "I set it
  and nothing happened" is very hard to debug from the outside.
</Warning>

## Loading argument grammar

Summaries are enough to choose a tool, not to call one. Load the full parameters for the ones you want:

```json theme={"dark"}
{ "names": ["reticle_network_mock", "reticle_clock"] }
```

This is the point of the design. Schemas arrive when they are needed, rather than on every turn forever.

## Invoking

```json theme={"dark"}
{ "tool": "reticle_capabilities" }
```

Real response from an instrumented app, trimmed:

```json theme={"dark"}
{
  "testids": [
    "nav-overview",
    "nav-deployments",
    "login-email",
    "login-password",
    "login-submit",
    "deploy-table",
    "new-deploy",
    "deploy-submit",
    "…"
  ],
  "signals": [
    "nav:changed",
    "auth:granted",
    "auth:denied",
    "deploy:created",
    "deploy:shipped",
    "modal:opened",
    "toast:shown",
    "…"
  ],
  "stores": ["app"],
  "flows": [
    {
      "name": "ship-a-deploy",
      "steps": ["nav-deployments", "new-deploy", "deploy-name", "deploy-submit"]
    },
    { "name": "generate-a-script", "steps": ["nav-compose", "compose-prompt", "compose-generate"] }
  ],
  "source": "live"
}
```

## Start here, not with a snapshot

That `reticle_capabilities` output is the single best first call on an unfamiliar app. It is the app telling you what it considers testable: the elements worth driving, the signals that mean success, and the flows somebody already thought were important.

Compared with snapshotting the page and guessing from element names, it is both cheaper and more truthful. `auth:granted` is what the app means by "logged in", and no amount of looking at the DOM will tell you that.

```json theme={"dark"}
{
  "tool": "reticle_network_mock",
  "args": { "mocks": [{ "urlContains": "/api/deploys", "status": 500 }] }
}
```

Then drive the flow and see whether your error state actually works. Most do not, which is the point.

<Note>
  `reticle_run` returns whatever the invoked tool returns, unchanged. It is a transport, not a
  wrapper. So a tool that produces a verdict still produces one through `run`.
</Note>