@reticlehq/server 2.7.0 → 2.8.0

package/docs/tools-overview.mdx

@@ -0,0 +1,157 @@
+---
+title: Tools overview: 18 up front, 30 on call
+sidebarTitle: Tools overview
+description: The 18 tools your agent sees every turn, the 30 more it can reach on demand, and why the surface is deliberately small.
+icon: wrench
+---
+
+Reticle ships 48 tools. Your agent is shown **18** of them.
+
+That is not a limitation, it's the design. MCP re-sends every advertised tool definition to the model on **every single turn**, so the tool list is not a menu you pay for once. It's rent.
+
+A wider surface costs tokens on every message. Less obviously, it makes the model wander: give it forty ways to look at a page and it will try several before doing anything useful.
+
+The other 30 tools are one call away, never unreachable. `reticle_tools` lists them and `reticle_run` invokes them.
+
+<Note>
+  Measured off the real wire on 2026-08-14, by reading `tools/list` from a fresh daemon: the default
+  surface is **18 tools at 21,468 bytes**, against **48 tools at 134,368 bytes**. That is 6.3x more,
+  charged on every message. In real tokenizer terms that is roughly **4,930** and **30,200** tokens
+  per turn ([measured by `bench/harness/schema-tax.mjs`](/token-efficiency), which puts every server
+  through one tokenizer in a single pass). Re-measure before quoting these; the surface grows.
+</Note>
+
+## The default 18
+
+Grouped by the job they do in the verify loop.
+
+<CardGroup cols={2}>
+  <Card title="Look" icon="magnifying-glass">
+    `reticle_snapshot` · `reticle_query` · `reticle_inspect` · `reticle_sessions`
+  </Card>
+  <Card title="Act" icon="hand-pointer">
+    `reticle_act` · `reticle_act_and_wait` · `reticle_act_sequence` · `reticle_navigate`
+  </Card>
+  <Card title="Observe" icon="satellite-dish">
+    `reticle_observe` · `reticle_network` · `reticle_console` · `reticle_state` · `reticle_wait_for`
+  </Card>
+  <Card title="Prove & discover" icon="circle-check">
+    `reticle_assert` · `reticle_tools` · `reticle_run`
+  </Card>
+  <Card title="Session & feedback" icon="comment">
+    `reticle_session` · `reticle_feedback`
+  </Card>
+</CardGroup>
+
+<Warning>
+  Only **`reticle_act_and_wait`** and **`reticle_assert`** produce a verdict. Everything else 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 and however confident the summary sounds.
+</Warning>
+
+## Why these 18 and not others
+
+Each one earned its slot, and a couple are there because of measured mistakes.
+
+`reticle_inspect` maps a DOM node to `src/components/Sidebar.tsx:41`. Finding a bug is half the job. Knowing which file to open is the half that makes an agent useful.
+
+It used to sit in the cold tail, which meant an agent had to already know it existed to use it. So essentially nobody did.
+
+`reticle_act_sequence` batches a multi-step interaction into one round trip. It was also in the cold tail, and the consequence showed up in the data: agents drove login forms one call at a time, over and over.
+
+Those repeats were not retries. The calls succeeded and got repeated, because the batching tool was invisible. A tool an agent must already know about is a tool that never gets called.
+
+Direct `reticle_network` and `reticle_console` stay advertised even though `reticle_observe` can filter for both, because two obvious tools beat one clever tool with a filter grammar.
+
+<Tip>
+  Trimming further has a floor. An 8-tool cut measurably dropped real-agent accuracy, because the
+  model loses scaffolding and wanders on harder flows. That reading is old enough to be dated
+  evidence rather than proof, and a fresh A/B against a leaner surface is still unrun. Small is
+  good; empty is not.
+</Tip>
+
+## Reaching the other 30
+
+```json
+{ "name": "reticle_flow_verify", "args": {} }
+```
+
+`reticle_run` takes a tool name and its arguments. `reticle_tools` lists what's available and returns the full argument grammar for any of them, so your agent can discover a tool mid-task without you having pre-loaded its schema.
+
+Notable residents of the cold tail: flow recording and replay, visual diffing and screenshots, network mocking, viewport pinning, coverage, autonomous crawling, and the human-in-the-loop session controls.
+
+## Every response carries its cost
+
+Reticle tells you what each answer cost, because a verification tool that quietly eats your context window is not saving you anything:
+
+```json
+"cost": { "bytes": 938, "tokens": 235 }
+```
+
+That is a real `reticle_query` response: seven buttons found, with source pointers, for 235 tokens.
+
+## Every response tells you when not to trust it
+
+This is the part we're proudest of and the part that makes demos slightly less shiny.
+
+When the browser tab is backgrounded, every response says so:
+
+```json
+"warning": "tab throttled; timer/rAF/pointer gestures may silently no-op; refocus before driving"
+```
+
+When the event buffer has evicted old events, a negative result might be a false negative, and it says that too:
+
+```json
+"buffer": {
+  "held": 15,
+  "dropped": 529,
+  "note": "event buffer evicted older events (age/size cap): a negative result here may be a false negative; the evidence may have expired. Grade sooner or widen the buffer."
+}
+```
+
+A tool that says "no requests found" when it actually means "I lost the ones you asked about" is worse than useless. It is confidently wrong. Reticle would rather tell you its memory is imperfect.
+
+## Reference
+
+### Look
+
+| Tool | Answers |
+| --- | --- |
+| [`reticle_snapshot`](/tools-snapshot) | What is on this page? Three modes, from full tree to a 25-token route check |
+| [`reticle_query`](/tools-query) | Where is the thing I mean? |
+| [`reticle_inspect`](/tools-inspect) | Everything about one element, down to source and design tokens |
+| [`reticle_sessions`](/tools-sessions) | Which tabs are connected, and can they actually be driven? |
+
+### Act
+
+| Tool | Answers |
+| --- | --- |
+| [`reticle_act`](/tools-act) | Do this. Proves nothing, and says so |
+| [`reticle_act_and_wait`](/tools-act-and-wait) | Do this, and prove the consequence. **Produces a verdict** |
+| [`reticle_act_sequence`](/tools-act-sequence) | Do these three things in one round trip |
+| [`reticle_navigate`](/tools-navigate) | Go here. Dispatched, not confirmed |
+
+### Observe
+
+| Tool                                  | Answers                                         |
+| ------------------------------------- | ----------------------------------------------- |
+| [`reticle_observe`](/tools-observe)   | Everything that happened in a window            |
+| [`reticle_network`](/tools-network)   | Which requests fired, with bodies and timings   |
+| [`reticle_console`](/tools-console)   | What was logged, and whether the read was real  |
+| [`reticle_state`](/tools-state)       | What the app believes, not what it drew         |
+| [`reticle_wait_for`](/tools-wait-for) | Block until something you did not cause happens |
+
+### Prove and discover
+
+| Tool | Answers |
+| --- | --- |
+| [`reticle_assert`](/tools-assert) | Did the named consequence hold? **Produces a verdict** |
+| [`reticle_tools`](/tools-tools-and-run) | What else is available, and what are its arguments? |
+| [`reticle_run`](/tools-tools-and-run) | Invoke any of the other 30 |
+| [`reticle_session`](/tools-session-and-feedback) | Hand control back to the human |
+| [`reticle_feedback`](/tools-session-and-feedback) | Tell the maintainers Reticle got something wrong |
+
+<Card title="The complete reference" icon="book" href="/usage">
+  Every tool, every argument, including the 30 in the cold tail.
+</Card>

package/docs/tools-query.mdx

@@ -0,0 +1,82 @@
+---
+title: reticle_query
+description: Find elements by Testing-Library semantics. Role, text, label, placeholder, testid, alt, or React component, including inside open shadow roots.
+icon: magnifying-glass
+---
+
+`reticle_query` answers "where is the thing I mean?" without dumping the whole page into your context window. It queries the way a testing library does. By role, label, text, testid. So your agent binds to meaning rather than to DOM structure that a refactor will move.
+
+## Example
+
+```json
+{ "by": "role", "value": "button", "limit": 6 }
+```
+
+Real response from a running app:
+
+```json
+{
+  "count": 7,
+  "elements": [
+    {
+      "ref": "e18",
+      "role": "button",
+      "name": "Overview",
+      "visible": true,
+      "source": "src/components/Sidebar.tsx:41",
+      "states": ["present", "visible", "enabled"]
+    },
+    {
+      "ref": "e20",
+      "role": "button",
+      "name": "Compose",
+      "visible": true,
+      "source": "src/components/Sidebar.tsx:41",
+      "states": ["present", "visible", "enabled"]
+    }
+  ],
+  "total": 7,
+  "truncated": true,
+  "cost": { "bytes": 938, "tokens": 235 }
+}
+```
+
+Seven buttons, each with a `ref` to act on and a source file to open, for 235 tokens.
+
+## Arguments
+
+| Argument     | What it does                                                               |
+| ------------ | -------------------------------------------------------------------------- |
+| `by`         | `role` · `text` · `label` · `placeholder` · `testid` · `alt` · `component` |
+| `value`      | The query value for that strategy                                          |
+| `name`       | Accessible-name filter. Narrows a broad `role` query                       |
+| `scope`      | CSS selector or ref, to search inside a subtree                            |
+| `limit`      | Cap the descriptors returned. Cuts tokens hard on broad queries            |
+| `count_only` | Return just `{ count }`, around 30x smaller                                |
+| `attrs`      | Extra attributes per match, e.g. `['href']` to inventory links             |
+| `self`       | Return the `scope` element itself instead of searching inside it           |
+
+Every argument also has a predicate spelling, so `{ "role": "button" }` works as shorthand for `{ "by": "role", "value": "button" }`.
+
+## Use `count_only` when you only need a number
+
+"Are there still three rows?" does not require three row descriptors:
+
+```json
+{ "by": "testid", "value": "todo-row", "count_only": true }
+```
+
+## Reading the response
+
+`ref` is the handle for every other tool: `act`, `inspect`, `state`. It stays valid until the element leaves the DOM, so you do not need to re-snapshot between actions on the same element.
+
+`source` appears when `@reticlehq/react` is installed. Note that all five sidebar buttons above report `Sidebar.tsx:41`. That is the line where the component renders them in a loop, which is exactly the line you want to edit.
+
+`truncated: true` with `total: 7` means `limit` cut the list, not that Reticle ran out of room.
+
+`states` distinguishes `present` from `visible` from `enabled`. An element can be all three and still be covered by a modal. [`reticle_inspect`](/tools-inspect) reports `occluded` for that.
+
+<Tip>
+  Query by `testid` when you can. Role and text queries survive refactors well; testids survive
+  redesigns, translations, and the day someone rewrites your button labels for the marketing team.
+</Tip>

package/docs/tools-session-and-feedback.mdx

@@ -0,0 +1,91 @@
+---
+title: reticle_session and reticle_feedback
+description: Hand the session back to the human, end it cleanly, and tell the maintainers when Reticle got something wrong.
+icon: comments
+---
+
+Two tools that are not about your app at all. One manages the boundary between agent and human; the other is how Reticle finds out it is broken.
+
+## reticle_session
+
+The presenter panel in your app shows a live transcript of what the agent is doing. It reads "live" until the agent says otherwise. So an agent that wanders off without a word leaves a panel claiming work is in progress forever.
+
+| Action  | What it does                                                             |
+| ------- | ------------------------------------------------------------------------ |
+| `yield` | Hand control back between turns. `mode: "waiting"` or `"ask"`. Revivable |
+| `end`   | The task is done. Frees the session; revives on the next action          |
+| `tune`  | Adjust session behaviour, such as the idle-end window                    |
+
+```json
+{ "action": "yield", "mode": "waiting" }
+```
+
+Reticle nudges you about this. Every response on a long-running session carries a reminder:
+
+```json
+"session_age_warning": "Session s7fe3a790… has been open for 15 minutes. If your task is complete, call reticle_session{action:\"end\"} now."
+```
+
+And each lease carries the rule in the payload itself:
+
+```json
+"session_lease": {
+  "IMPORTANT": "When you stop driving, call reticle_session {action:\"yield\", mode:\"waiting\"|\"ask\"}. The panel reads \"live\" until you do."
+}
+```
+
+<Tip>
+  `yield` when you are pausing and might come back. `end` when you are finished. Both revive on your
+  next action, so neither is destructive. The difference is what the human watching the panel is
+  told.
+</Tip>
+
+## reticle_feedback
+
+Reticle is built for agents, which creates an unusual problem: the primary user's experience vanishes the moment its context does. If an agent hits a gap and works around it silently, nobody ever learns the gap existed.
+
+```json
+{
+  "kind": "bug",
+  "text": "What I called, what I expected, what I got, and why Reticle is at fault.",
+  "currentApproach": "How I am working around it today.",
+  "impact": "What measurably improves if this is fixed."
+}
+```
+
+| `kind`            | Use it when                                                |
+| ----------------- | ---------------------------------------------------------- |
+| `bug`             | A tool returned a wrong or broken result                   |
+| `gap`             | Reticle could not observe something you needed at all      |
+| `ambiguity`       | The check ran but you could not tell what the answer meant |
+| `feature_request` | You wished a capability existed                            |
+| `improvement`     | It works, but costs too many calls                         |
+
+### It will tell you when it cannot send
+
+Feedback is not fire-and-forget, and it does not pretend to succeed:
+
+```json
+{
+  "sent": false,
+  "accepted": false,
+  "reason": "this is a Reticle source checkout, where telemetry is disabled by design, so feedback has nowhere to go. Open an issue at https://github.com/reticlehq/reticle/issues instead.",
+  "note": "NOT accepted (see reason). Tell the human what you found so it is not lost."
+}
+```
+
+That is a real response, captured while writing these docs. The instruction in `note` is the important part: when the report cannot be delivered, say so in your answer to the human rather than letting the finding evaporate.
+
+### From the shell, when the tools are unreachable
+
+The setup that failed to finish is exactly the setup that most needs reporting, and in that state the MCP tools do not exist:
+
+```bash
+npx @reticlehq/server feedback --agent --kind gap "reticle init finished but no session ever connected"
+```
+
+<Note>
+  Report defects in **Reticle**. A bug you find in the app under test is Reticle working correctly,
+  and belongs in your answer to the user. Not in a bug report to us. We get a surprising number of
+  those, and each one is quietly a compliment.
+</Note>

package/docs/tools-sessions.mdx

@@ -0,0 +1,65 @@
+---
+title: reticle_sessions
+description: List every connected browser tab, with the health fields that tell you whether it can actually be driven.
+icon: list-check
+---
+
+```json
+{}
+```
+
+Real response, one session shown:
+
+```json
+{
+  "sessions": [
+    {
+      "sessionId": "s7fe3a790-ab02-4ebb-82b2-24d08a76fd59",
+      "url": "http://localhost:4312/",
+      "title": "Reticle · Mission Control",
+      "adapters": ["react"],
+      "hasCapabilities": true,
+      "hidden": true,
+      "throttled": true,
+      "focused": false,
+      "lastSeenMs": 21944,
+      "realInputAvailable": false,
+      "leased": false,
+      "attachment": { "connectedSinceMs": 827874, "outages": 0 },
+      "recommendation": "tab hidden/throttled and may be un-focusable from here; refocus it, or run `reticle drive <url>` for a guaranteed scriptable context"
+    }
+  ]
+}
+```
+
+## The fields that decide whether driving will work
+
+| Field | Why it matters |
+| --- | --- |
+| `throttled` | The browser is deprioritising a background tab. Synthetic timers and pointer gestures may silently no-op |
+| `hidden` / `focused` | Why it's throttled, and what to do about it |
+| `hasCapabilities` | Whether the app registered testids, signals and stores. `false` means [`reticle_state`](/tools-state) has nothing to read |
+| `adapters` | `["react"]` means you get component names and source pointers |
+| `realInputAvailable` | `true` when native CDP input is available, under `reticle drive` |
+| `outages` | How often the connection has dropped. Non-zero is worth investigating |
+
+<Warning>
+  `throttled: true` is the most common cause of "the click did nothing". Focus the tab, or drive a
+  dedicated context. It is not your app being broken. It is the browser saving battery on a tab
+  nobody is looking at.
+</Warning>
+
+## Confirm after navigating
+
+[`reticle_navigate`](/tools-navigate) can only report that a navigation was dispatched. `sessions` is how you confirm one arrived: a session at the new URL means the page loaded **and** is instrumented. No session means one of those two is false, and you find out now rather than after three confusing failures.
+
+## Scoping
+
+You rarely need to pass `sessionId` to other tools. Reticle scopes to your project, prefers the active tab, and refuses rather than guesses when the choice is ambiguous. A refusal you can act on beats a silent pick of the wrong tab.
+
+Pass it explicitly when you genuinely mean one specific tab, such as when testing two apps at once.
+
+<Note>
+Sessions accumulate. A stale entry pointing at a dev server you have since restarted will sit there
+looking plausible. `reticle_session { action: "end" }` clears one out.
+</Note>

package/docs/tools-snapshot.mdx

@@ -0,0 +1,75 @@
+---
+title: reticle_snapshot
+description: A semantic accessibility snapshot of the page or a subtree, in three sizes. From the full tree down to a 25-token route check.
+icon: camera
+---
+
+`reticle_snapshot` is how an agent gets its bearings. It returns the page as semantic structure, not pixels and not raw HTML, and it comes in three sizes so you can pay for only what you need.
+
+## Three modes, three prices
+
+| Mode          | Returns                               | Real cost on one page |
+| ------------- | ------------------------------------- | --------------------- |
+| `status`      | Route and title only                  | **25 tokens**         |
+| `interactive` | Only clickable and focusable elements | **65 tokens**         |
+| `full`        | Every element                         | Depends on the page   |
+
+### `status`. the cheapest possible check
+
+```json
+{ "mode": "status" }
+```
+
+```json
+{
+  "tree": "",
+  "nodes": 0,
+  "status": { "route": "/", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 98, "tokens": 25 }
+}
+```
+
+Ninety-eight bytes to answer "where am I?". Use it after a navigation instead of re-reading the page.
+
+### `interactive`. the default working view
+
+```json
+{ "mode": "interactive" }
+```
+
+```json
+{
+  "tree": "- textbox \"Email\" (ref=e101) [value=\"admin@reticle.dev\"]\n- textbox \"Password\" (ref=e102) [value=\"[REDACTED]\"]\n- button \"Sign in\" (ref=e103)",
+  "nodes": 3,
+  "truncated": false,
+  "status": { "route": "/deployments", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 260, "tokens": 65 }
+}
+```
+
+Everything you can act on, with a `ref` for each, for 65 tokens. Note the password arrives `[REDACTED]` without anyone configuring it.
+
+## Arguments
+
+| Argument | What it does                                                                 |
+| -------- | ---------------------------------------------------------------------------- |
+| `mode`   | `full` · `interactive` · `status`                                            |
+| `scope`  | CSS selector or ref, to snapshot one subtree                                 |
+| `diff`   | Return only what changed since your last snapshot of the same scope and mode |
+
+## `diff` is how you keep a long session cheap
+
+```json
+{ "mode": "interactive", "diff": true }
+```
+
+After the first snapshot, ask only for the delta. On a page where one row appeared, you get one row rather than the whole list again.
+
+<Tip>
+  Reach for [`reticle_query`](/tools-query) instead when you already know what you're looking for.
+  Snapshot is for orientation; query is for retrieval, and it's almost always cheaper.
+</Tip>
+
+## Refs change across documents
+
+Refs are stable while the element is in the DOM. A full navigation builds a new document, so refs are re-issued. The same "Sign in" button was `e5` before a navigation and `e103` after. Snapshot after navigating; don't reuse refs across one.

package/docs/tools-state.mdx

@@ -0,0 +1,81 @@
+---
+title: reticle_state
+description: Read live framework state directly from the running app. What it believes, not just what it rendered, without the app broadcasting anything.
+icon: database
+---
+
+The DOM tells you what the app _drew_. `reticle_state` tells you what it _believes_. The gap between those two is where false greens live: a row appears in the table, the store never changed, and a reload makes the row vanish.
+
+## Example
+
+```json
+{ "depth": 2 }
+```
+
+Real response:
+
+```json
+{
+  "found": true,
+  "value": {
+    "stores": {
+      "__reticle_renders": "{…1 keys}",
+      "app": "{…30 keys}",
+      "queries": "{…0 keys}"
+    },
+    "storeNames": ["__reticle_renders", "app", "queries"]
+  },
+  "storeNames": ["__reticle_renders", "app", "queries"]
+}
+```
+
+`depth: 2` collapsed the contents to size markers: `{…30 keys}` rather than thirty keys of JSON. On a large store this is the difference between a cheap look and a very expensive one.
+
+## Arguments
+
+| Argument | What it does                                                 |
+| -------- | ------------------------------------------------------------ |
+| `store`  | A registered store name, e.g. `app`                          |
+| `path`   | Dot-path into a store, e.g. `cart.items.0.qty`               |
+| `depth`  | Collapse anything deeper than N levels to a size marker      |
+| `ref`    | Best-effort read of the nearest React component's hook state |
+
+Drill in once you know what you want:
+
+```json
+{ "store": "app", "path": "auth" }
+```
+
+## You have to register stores first
+
+`reticle_state` reads what your app registered in `src/reticle-dev.ts`. With nothing registered, `storeNames` comes back empty and this tool has nothing to say.
+
+```ts
+registerCapabilities({
+  stores: [{ name: 'app', store: appStore }],
+});
+```
+
+<Warning>
+Pass the **store**, not `() => store.getState()`. The store form wires `subscribe` too, so every
+mutation emits a state diff. The getter form is read-only and silently produces empty diffs, which
+looks like "nothing changed" and is really "I was never watching".
+</Warning>
+
+That distinction is the single most common instrumentation mistake, and its failure mode is a verdict that passes when it should not.
+
+## Why this is the strongest evidence you have
+
+A `POST` returning `200` proves the server was reachable. A row in the DOM proves React rendered something. Neither proves your application accepted the change.
+
+State does. When [`reticle_act_and_wait`](/quickstart) reports
+
+```json
+"stateDiffs": [{ "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}" }]
+```
+
+that is the app itself saying the login took. A mock that returns `200` without touching state gets caught right there, and nowhere else.
+
+<Card title="Instrument your app" icon="wrench" href="/instrumentation">
+  Registering one store for your most important flow is the highest-value line you can write.
+</Card>

package/docs/tools-tools-and-run.mdx

@@ -0,0 +1,125 @@
+---
+title: reticle_tools and reticle_run
+description: Discover the 30 tools that are not advertised, load their argument grammar on demand, and invoke any of them by name.
+icon: boxes-stacked
+---
+
+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
+{}
+```
+
+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
+{
+  "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
+{ "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
+{ "tool": "reticle_capabilities" }
+```
+
+Real response from an instrumented app, trimmed:
+
+```json
+{
+  "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
+{
+  "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>