@reticlehq/server 2.8.0 → 2.10.0

package/docs/tools-overview.mdx

@@ -1,33 +1,35 @@
 ---
-title: Tools overview: 18 up front, 30 on call
+title: Reticle tools overview
 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.
+description: The tools your agent sees every turn, the many more it can reach on demand, and why the advertised surface is deliberately small.
 icon: wrench
 ---
 
-Reticle ships 48 tools. Your agent is shown **18** of them.
+Reticle ships 46 tools plus two meta-tools. On the default profile your agent is shown **19** of them: 17 that do the work, plus `reticle_tools` and `reticle_run`, which reach the other 29 on demand. Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.
 
 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.
+A wider surface costs tokens on every message. Less obviously, it makes the model wander: give it fifty 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.
+The other 29 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.
+  Measured off the real wire on 2026-08-16, by reading `tools/list` from a fresh daemon: the default
+  surface is **19 tools at 22,023 bytes**, against **48 tools at 134,992 bytes** when
+  `RETICLE_ADVERTISE_ALL_TOOLS` is set. That is 6.1x more, charged on every message.
+  [`bench/harness/schema-tax.mjs`](/token-efficiency) converts those bytes to tokens by putting
+  every server through one tokenizer in a single pass. Re-measure before quoting any of it; the
+  surface grows.
 </Note>
 
-## The default 18
+## The default 19
 
 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`
+    `reticle_snapshot` · `reticle_query` · `reticle_inspect` · `reticle_sessions` ·
+    `reticle_capabilities`
   </Card>
   <Card title="Act" icon="hand-pointer">
     `reticle_act` · `reticle_act_and_wait` · `reticle_act_sequence` · `reticle_navigate`
@@ -49,7 +51,7 @@ Grouped by the job they do in the verify loop.
   however many tools it used and however confident the summary sounds.
 </Warning>
 
-## Why these 18 and not others
+## Why these and not others
 
 Each one earned its slot, and a couple are there because of measured mistakes.
 
@@ -64,16 +66,16 @@ Those repeats were not retries. The calls succeeded and got repeated, because th
 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
+  Trimming further has a floor. An eight-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
+## Reaching the other 29
 
 ```json
-{ "name": "reticle_flow_verify", "args": {} }
+{ "tool": "reticle_verify", "args": { "action": "flows" } }
 ```
 
 `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.
@@ -85,10 +87,10 @@ Notable residents of the cold tail: flow recording and replay, visual diffing an
 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 }
+"cost": { "bytes": 944, "tokens": 236 }
 ```
 
-That is a real `reticle_query` response: seven buttons found, with source pointers, for 235 tokens.
+That is a real `reticle_query` response: seven buttons found, with source pointers, for 236 tokens.
 
 ## Every response tells you when not to trust it
 
@@ -104,8 +106,8 @@ When the event buffer has evicted old events, a negative result might be a false
 
 ```json
 "buffer": {
-  "held": 15,
-  "dropped": 529,
+  "held": 535,
+  "dropped": 10,
   "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."
 }
 ```
@@ -122,6 +124,7 @@ A tool that says "no requests found" when it actually means "I lost the ones you
 | [`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? |
+| [`reticle_capabilities`](/tools-tools-and-run) | What does this app say is testable? Testids, signals, stores, flows |
 
 ### Act
 
@@ -148,10 +151,10 @@ A tool that says "no requests found" when it actually means "I lost the ones you
 | --- | --- |
 | [`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_run`](/tools-tools-and-run) | Invoke any of the other 29 |
 | [`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.
+  Every tool, every argument, including the 29 in the cold tail.
 </Card>

package/docs/tools-query.mdx

@@ -12,14 +12,14 @@ icon: magnifying-glass
 { "by": "role", "value": "button", "limit": 6 }
 ```
 
-Real response from a running app:
+Real response from a running app, with four of the six elements trimmed out for length:
 
 ```json
 {
   "count": 7,
   "elements": [
     {
-      "ref": "e18",
+      "ref": "e118",
       "role": "button",
       "name": "Overview",
       "visible": true,
@@ -27,7 +27,7 @@ Real response from a running app:
       "states": ["present", "visible", "enabled"]
     },
     {
-      "ref": "e20",
+      "ref": "e120",
       "role": "button",
       "name": "Compose",
       "visible": true,
@@ -37,11 +37,11 @@ Real response from a running app:
   ],
   "total": 7,
   "truncated": true,
-  "cost": { "bytes": 938, "tokens": 235 }
+  "cost": { "bytes": 944, "tokens": 236 }
 }
 ```
 
-Seven buttons, each with a `ref` to act on and a source file to open, for 235 tokens.
+Seven buttons, each with a `ref` to act on and a source file to open, for 236 tokens.
 
 ## Arguments
 
@@ -63,16 +63,60 @@ Every argument also has a predicate spelling, so `{ "role": "button" }` works as
 "Are there still three rows?" does not require three row descriptors:
 
 ```json
-{ "by": "testid", "value": "todo-row", "count_only": true }
+{ "by": "testid", "value": "login-submit", "count_only": true }
 ```
 
+```json
+{ "count": 1, "cost": { "bytes": 11, "tokens": 3 } }
+```
+
+Three tokens. Note that `total` is not emitted on this path, because `count` already is the total.
+
+## A zero-match result tells you what _is_ there
+
+```json
+{ "by": "testid", "value": "compose-prompt" }
+```
+
+```json
+{
+  "count": 0,
+  "elements": [],
+  "hint": {
+    "route": "/hostile",
+    "knownEmptyState": true,
+    "presentTestids": [
+      "brand",
+      "nav-overview",
+      "nav-deployments",
+      "nav-compose",
+      "nav-diagnostics",
+      "nav-hostile",
+      "session-pill",
+      "cmdk-open",
+      "sign-out",
+      "hostile-view",
+      "hostile-ticker",
+      "hostile-feed-count"
+    ],
+    "presentRegions": [
+      { "role": "list", "childCount": 0, "name": "hostile-feed", "sample": [] },
+      { "role": "banner", "childCount": 0, "sample": [] }
+    ]
+  },
+  "cost": { "bytes": 402, "tokens": 101 }
+}
+```
+
+The testid existed, on another route. `hint.route` says where you actually are, `presentTestids` says what is on this page instead, and `presentRegions` distinguishes an empty list from a missing one. All of it without paying for a snapshot.
+
 ## 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.
+`source` appears when `@reticlehq/react` is installed. Note that both sidebar buttons above report `Sidebar.tsx:41`, and so do the three trimmed out of the example. That is the line where the component renders all five 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.
+`truncated: true` with `total: 7` means `limit` cut the list, not that Reticle ran out of room. Neither field is emitted when nothing was cut, so their absence is itself the signal that you are looking at every match.
 
 `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.
 

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

@@ -4,26 +4,36 @@ description: Hand the session back to the human, end it cleanly, and tell the ma
 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` manages the boundary between the agent and the human watching: hand control back, end the session, narrate what you are doing, and drain the bugs they pinned on elements. `reticle_feedback` is how you tell the Reticle maintainers that Reticle itself got something wrong. Neither tool touches your app, and neither produces a verdict.
 
 ## 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                    |
+| 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 `idleEndMs`, the idle-end window       |
+| `resume`   | Clear a pause the human applied                                          |
+| `messages` | Drain the human-to-agent inbox                                           |
+| `review`   | List, and with `resolve`, retire the mistakes a human pinned to elements |
+| `narrate`  | State your intent on the presenter panel, with an optional `level`       |
 
 ```json
 { "action": "yield", "mode": "waiting" }
 ```
 
-Reticle nudges you about this. Every response on a long-running session carries a reminder:
+`review` returns a real reading rather than a silent empty:
 
 ```json
-"session_age_warning": "Session s7fe3a790… has been open for 15 minutes. If your task is complete, call reticle_session{action:\"end\"} now."
+{ "marks": [], "pendingCount": 0 }
+```
+
+Reticle nudges you about all of this. Every response on a long-running session carries a reminder:
+
+```json
+"session_age_warning": "Session s223e0fad-e012-43f9-a23d-6d585470c90d has been open for 21 minutes. If your task is complete, call reticle_session{action:\"end\"} now."
 ```
 
 And each lease carries the rule in the payload itself:
@@ -60,6 +70,11 @@ Reticle is built for agents, which creates an unusual problem: the primary user'
 | `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                         |
+| `experience`      | Something worked notably well (pair it with `rating`, 1-5) |
+
+`experience` is the only kind here that is not a complaint, and that is why it exists. Every other row grows the corpus into a defect list, which says nothing about which parts are worth protecting when we change them. File it unprompted, when you actually notice it, and name the concrete moment: which call, what it saved you, what you would have done instead.
+
+The `rating` is secondary to that text on purpose. A score produced because something asked for one is indistinguishable from a score that was earned, and once both sit in the same column neither means anything. The text is the part that can be acted on or quoted.
 
 ### It will tell you when it cannot send
 
@@ -69,11 +84,22 @@ Feedback is not fire-and-forget, and it does not pretend to succeed:
 {
   "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.",
+  "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, or run from the app you are verifying.",
+  "redacted": [],
+  "context": {
+    "stack": "react",
+    "client": "claude-code",
+    "runtime": "web",
+    "engine": "blink",
+    "driver": "cdp",
+    "mcpScope": "user"
+  },
   "note": "NOT accepted (see reason). Tell the human what you found so it is not lost."
 }
 ```
 
+`redacted` names anything stripped from your report before it left the machine, so you can see what was and was not sent. `context` is the environment attached automatically, which is why a useful report costs one call and no boilerplate.
+
 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

package/docs/tools-sessions.mdx

@@ -4,34 +4,63 @@ description: List every connected browser tab, with the health fields that tell
 icon: list-check
 ---
 
+`reticle_sessions` lists every browser tab currently connected to the Reticle daemon, with the health fields that decide whether it can actually be driven. Reach for it first when a tool says no session is connected, and after every [`reticle_navigate`](/tools-navigate) that came back `confirmed: false`.
+
 ```json
 {}
 ```
 
-Real response, one session shown:
+Real response from a healthy session:
 
 ```json
 {
   "sessions": [
     {
-      "sessionId": "s7fe3a790-ab02-4ebb-82b2-24d08a76fd59",
-      "url": "http://localhost:4312/",
+      "sessionId": "sba6117a6-24ec-494d-8c2c-e2958cff2e7f",
+      "url": "http://localhost:4310/",
       "title": "Reticle · Mission Control",
       "adapters": ["react"],
       "hasCapabilities": true,
-      "hidden": true,
-      "throttled": true,
-      "focused": false,
-      "lastSeenMs": 21944,
+      "hidden": false,
+      "lastSeenMs": 155,
+      "throttled": false,
+      "focused": true,
+      "attachment": { "connectedSinceMs": 18654, "outages": 0 },
       "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"
+      "leased": false
     }
   ]
 }
 ```
 
+A backgrounded tab adds a `recommendation` telling you what to do about it, and `attachment` grows a `lastOutage` once the connection has dropped at least once:
+
+```json
+{
+  "hidden": false,
+  "throttled": true,
+  "attachment": {
+    "connectedSinceMs": 1217047,
+    "outages": 3,
+    "lastOutage": { "startedMs": 1786818483776, "durationMs": 967 }
+  },
+  "recommendation": "tab hidden/throttled and may be un-focusable from here; refocus it, or run `reticle drive <url>` for a guaranteed scriptable context"
+}
+```
+
+## When nothing is connected
+
+An empty list is not silent. It comes back with a `why` that separates the two causes, and refuses to guess between them:
+
+```json
+{
+  "sessions": [],
+  "why": "no browser session connected. Two things to weigh, and neither of them is proof. (1) Nothing is listening on the ports Reticle scans, so the dev server may not be running. That scan is narrow though: a server on any other port is invisible to it, so if the app IS running, ask for its URL rather than assuming it is down, and open it with `reticle open <url>`. (2) There is no `.reticle.json` in the directory this daemon is running in. That is the file `reticle init` writes, so the app may carry no Reticle SDK."
+}
+```
+
+That string is trimmed. The full text also lists the exact ports it scanned and warns that in a monorepo the daemon often runs at the root while the app lives in a subdirectory, so you should check the app's own directory before re-running `init`.
+
 ## The fields that decide whether driving will work
 
 | Field | Why it matters |

package/docs/tools-snapshot.mdx

@@ -24,6 +24,7 @@ icon: camera
 {
   "tree": "",
   "nodes": 0,
+  "truncated": false,
   "status": { "route": "/", "title": "Reticle · Mission Control" },
   "cost": { "bytes": 98, "tokens": 25 }
 }
@@ -39,7 +40,7 @@ Ninety-eight bytes to answer "where am I?". Use it after a navigation instead of
 
 ```json
 {
-  "tree": "- textbox \"Email\" (ref=e101) [value=\"admin@reticle.dev\"]\n- textbox \"Password\" (ref=e102) [value=\"[REDACTED]\"]\n- button \"Sign in\" (ref=e103)",
+  "tree": "- textbox \"Email\" (ref=e303) [value=\"admin@reticle.dev\"]\n- textbox \"Password\" (ref=e304) [value=\"[REDACTED]\"]\n- button \"Sign in\" (ref=e305)",
   "nodes": 3,
   "truncated": false,
   "status": { "route": "/deployments", "title": "Reticle · Mission Control" },
@@ -63,7 +64,45 @@ Everything you can act on, with a `ref` for each, for 65 tokens. Note the passwo
 { "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.
+When nothing moved since your last look of the same scope and mode, that costs 20 tokens and says so:
+
+```json
+{
+  "mode": "unchanged",
+  "status": { "route": "/", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 79, "tokens": 20 }
+}
+```
+
+When something did move, you get only what changed. This is the same call after a login replaced the form with the app shell:
+
+```json
+{
+  "mode": "delta",
+  "delta": {
+    "added": [
+      "- button \"Overview\" (ref=e17)",
+      "- button \"Deployments40\" (ref=e18)",
+      "- button \"Compose\" (ref=e19)",
+      "- button \"Diagnostics\" (ref=e20)",
+      "- button \"Hostile\" (ref=e21)",
+      "- button \"Search or jump to…⌘K\" (ref=e22)",
+      "- button \"Sign out\" (ref=e23)"
+    ],
+    "removed": [
+      "- textbox \"Email\" (ref=e4) [value=\"admin@reticle.dev\"]",
+      "- textbox \"Password\" (ref=e5) [value=\"[REDACTED]\"]",
+      "- button \"Sign in\" (ref=e3)"
+    ],
+    "addedCount": 7,
+    "removedCount": 3
+  },
+  "status": { "route": "/", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 545, "tokens": 137 }
+}
+```
+
+A route change resets it: the next call after one returns a full snapshot rather than a delta against a page that no longer exists.
 
 <Tip>
   Reach for [`reticle_query`](/tools-query) instead when you already know what you're looking for.
@@ -72,4 +111,19 @@ After the first snapshot, ask only for the delta. On a page where one row appear
 
 ## 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.
+Refs are stable while the element is in the DOM. A full navigation builds a new document, so refs are re-issued. Across the captures on this page the same "Sign in" button was `e105`, then `e305`, then `e3`, because each reload built a new document. Snapshot after navigating; don't reuse refs across one.
+
+Reticle refuses a stale ref rather than clicking whatever now occupies that slot:
+
+```json
+{
+  "error": "ref 'e303' no longer resolves to an element",
+  "recovery": "That ref is stale: refs are invalidated whenever the DOM re-renders, so any action that navigated, opened a modal, re-sorted a list or changed the page invalidates every ref taken before it. Call reticle_query again for a fresh ref and retry the action."
+}
+```
+
+<Note>
+  That `recovery` string is trimmed. The full text also recommends
+  [`reticle_act_and_wait`](/tools-act-and-wait) with `until`, so the next ref is taken after the
+  page settles.
+</Note>

package/docs/tools-state.mdx

@@ -4,6 +4,8 @@ description: Read live framework state directly from the running app. What it be
 icon: database
 ---
 
+`reticle_state` reads live framework state straight out of the running app, without the app broadcasting anything. Reach for it when the DOM looks right and you want to know whether the application actually accepted the change, which is where false greens live.
+
 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
@@ -46,6 +48,25 @@ Drill in once you know what you want:
 { "store": "app", "path": "auth" }
 ```
 
+```json
+{
+  "store": "app",
+  "path": "auth",
+  "found": true,
+  "value": { "email": "admin@reticle.dev" },
+  "storeNames": ["__reticle_renders", "app", "queries"]
+}
+```
+
+A wrong `path` comes back `{ "found": false, "availableKeys": [...] }` rather than an empty value, so a typo is diagnosable instead of looking like an empty store.
+
+<Warning>
+  `reticle_state` asks the page and waits. On a backgrounded tab the page may never answer, and you
+  get `"command 'state_read' timed out after 8000ms"` with a recovery note pointing at
+  [`reticle_sessions`](/tools-sessions). That is a fact about the tab, not a Reticle failure. Bring
+  it to the front, or drive your own browser.
+</Warning>
+
 ## 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.
@@ -71,7 +92,9 @@ A `POST` returning `200` proves the server was reachable. A row in the DOM prove
 State does. When [`reticle_act_and_wait`](/quickstart) reports
 
 ```json
-"stateDiffs": [{ "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}" }]
+"stateDiffs": [
+  { "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}", "atMs": 44403 }
+]
 ```
 
 that is the app itself saying the login took. A mock that returns `200` without touching state gets caught right there, and nowhere else.

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

@@ -1,12 +1,14 @@
 ---
 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.
+description: Discover the 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` lists every Reticle tool and, on request, returns the full argument grammar for the ones you name. `reticle_run` then invokes any of them. Reach for the pair whenever you need a capability that is not in the default advertised surface, which is most of what Reticle can do.
 
-`reticle_tools` discovers. `reticle_run` invokes. Together they cost two tool definitions instead of thirty.
+Reticle ships 46 tools plus these two meta-tools. On the default profile your agent is shown 17 of them plus the meta pair, so 29 sit in the cold tail. These two are how it reaches those 29 without paying for their schemas on every turn.
+
+`reticle_tools` discovers. `reticle_run` invokes. Together they cost two tool definitions instead of twenty-nine.
 
 ## Discovering what exists
 
@@ -16,35 +18,37 @@ Reticle advertises 18 tools and ships 48. These two meta-tools are how your agen
 
 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             |
+| Tool | What it does |
+| --- | --- |
+| `reticle_capabilities` | The app's advertised testable surface, testids, signals, stores, flows |
+| `reticle_verify` (`flows`) | 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_verify` (`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_verify` (`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."
+    "active": "all",
+    "source": "RETICLE_ADVERTISE_ALL_TOOLS set in the DAEMON's environment at startup",
+    "note": "The profile is read once at daemon startup: change RETICLE_TOOL_PROFILE and restart the daemon, or it has no effect. Under this profile every unadvertised tool is reachable through reticle_run; under `full` there are no meta-tools because every tool is advertised directly."
   },
   "next": "Load params with reticle_tools { names:[…] }, then call reticle_run { tool, args }."
 }
 ```
 
+That capture is from a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1`. On a default daemon, `active` reads `default` and names the environment variable as unset.
+
 <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
@@ -59,7 +63,27 @@ Summaries are enough to choose a tool, not to call one. Load the full parameters
 { "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.
+Each named tool comes back with its full description and a `params` array of `{ name, required, description }`. This is the point of the design. Schemas arrive when they are needed, rather than on every turn forever.
+
+<Warning>
+  Do this rather than guessing. `reticle_run` refuses an unknown parameter instead of running the
+  call, and hands you the real parameter list so the retry is one turn rather than three:
+
+```json
+{
+  "error": "unknown parameter for reticle_flow_save: name",
+  "tool": "reticle_flow_save",
+  "params": [
+    { "name": "flow", "required": false, "description": "Alias for `flowName`." },
+    { "name": "flowName", "required": true, "description": "Name for the flow file." }
+  ],
+  "hint": "fix the arguments and call reticle_run again"
+}
+```
+
+The full `error` string continues: _"NOT applied, so any result would be an answer to a different question."_
+
+</Warning>
 
 ## Invoking
 
@@ -98,12 +122,15 @@ Real response from an instrumented app, trimmed:
       "name": "ship-a-deploy",
       "steps": ["nav-deployments", "new-deploy", "deploy-name", "deploy-submit"]
     },
-    { "name": "generate-a-script", "steps": ["nav-compose", "compose-prompt", "compose-generate"] }
+    { "name": "generate-a-script", "steps": ["nav-compose", "compose-prompt", "compose-generate"] },
+    { "name": "find-old-deploy", "steps": ["nav-deployments", "scroll-to row-3600"] }
   ],
   "source": "live"
 }
 ```
 
+The full response on this fixture carries 49 testids and 16 signals. `source: "live"` means it was read from the running app; pass `{ "fromDisk": true }` to read the git-checked `.reticle/contract.json` instead, which works with no browser attached at all.
+
 ## 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.
@@ -117,7 +144,11 @@ Compared with snapshotting the page and guessing from element names, it is both
 }
 ```
 
-Then drive the flow and see whether your error state actually works. Most do not, which is the point.
+```json
+{ "applied": true, "count": 1 }
+```
+
+Then drive the flow and see whether your error state actually works. Most do not, which is the point. `{ "clear": true }` turns it off and answers `{ "applied": true, "count": 0 }`.
 
 <Note>
   `reticle_run` returns whatever the invoked tool returns, unchanged. It is a transport, not a