@reticlehq/server 3.5.0 → 3.7.0

package/docs/tools/assert.mdx

@@ -6,14 +6,14 @@ icon: gavel
 
 `reticle_assert` evaluates a predicate against what the app actually did and returns a verdict: `verified` plus `pass`, evidence when it holds, and `expected` versus `observed` when it does not. Reach for it when you want a verdict on something you did not just cause, or on several actions at once.
 
-It is the second of the two tools that produce a verdict, the other being [`reticle_act_and_wait`](/tools/act-and-wait). It takes the same predicate grammar and evaluates it against what already happened.
+Verdicts come from [`reticle_act_and_wait`](/tools/act-and-wait), `reticle_assert`, `reticle_act { steps }` when a step declares `expect`, and `reticle_verify` (`change`/`flows`). Everything else moves or reads the app and proves nothing. Only `verified: "yes"` is a pass: `unknown` means Reticle could not tell, and `no-fault` means nothing was declared to prove. `reticle_assert` takes the same predicate grammar as `until` and evaluates it against what already happened.
 
 ## A real failure
 
-Failures are more instructive than passes, so here is one. I asserted a route change to `/` on a page that was already at `/`:
+Failures are more instructive than passes, so here is one. I asserted that signing in lands on `/dashboard`, after a click that did not navigate. The page was still on `/login`:
 
 ```json
-{ "predicate": { "kind": "route", "pathname": "/" } }
+{ "predicate": { "kind": "route", "pathname": "/dashboard" } }
 ```
 
 ```json
@@ -22,10 +22,10 @@ Failures are more instructive than passes, so here is one. I asserted a route ch
   "verifiedReason": "assertion_failed",
   "because": "the declared consequence did not hold",
   "pass": false,
-  "failureReason": "no route change observed",
-  "observed": "no route change in the window",
-  "expected": "a route change to /",
-  "assertion": "route.changed",
+  "failureReason": "current route (no route change in the window) '/login', expected '/dashboard'",
+  "observed": "current route (no route change in the window) '/login'",
+  "expected": "route '/dashboard'",
+  "assertion": "route.pathname",
   "source": "src/components/Login.tsx:81",
   "buffer": {
     "held": 536,
@@ -40,12 +40,12 @@ Failures are more instructive than passes, so here is one. I asserted a route ch
   `pathname` is what the published schema declares, so it is the one to write.
 </Note>
 
-<Warning>
-  Read `assertion: "route.changed"` carefully. The `route` predicate asserts that the route
-  **changed**, not that it currently equals a value. Asserting the route you are already on will
-  always fail. This catches people out, and the response says so in `expected` rather than leaving
-  you to work it out.
-</Warning>
+<Note>
+  A `route` predicate is decided by the last route change in the window. When there was none, it
+  reads the session's current URL instead, and `observed` says so ("current route (no route change
+  in the window)"). So asserting the route you are already on passes; on its own it does not prove
+  that anything navigated. Check `evidence.decidedBy` on a pass to see which of the two decided it.
+</Note>
 
 Note also `expected` and `observed` side by side. A verdict that says only "failed" makes you go digging; this one tells you what it wanted, what it saw, and where in your source the relevant element lives.
 
@@ -98,11 +98,12 @@ A presence-only predicate passes and tells you not to trust it much:
 
 ## Arguments
 
-| Argument                 | What it does                                                      |
-| ------------------------ | ----------------------------------------------------------------- |
+| Argument | What it does |
+| --- | --- |
+| `action` | `now` (the default) evaluates against the window that already exists; `wait` waits for it to hold |
 | `predicate` (or `until`) | `{ kind, ...fields }`. See the [predicate reference](/predicates) |
-| `timeout_ms`             | If above zero, wait this long before failing. Default `0`         |
-| `since`                  | Cursor from a prior act. Scope to events after that action        |
+| `timeout_ms` | `now`: if above zero, wait this long before failing (default `0`, capped at `55000`). `wait`: default `4000`, up to `600000`, resumed with `resume_ms` past one call's limit |
+| `since` | Cursor from a prior act. Scope to events after that action |
 
 ## Scope it with `since`
 

package/docs/tools/console.mdx

@@ -11,7 +11,7 @@ icon: terminal
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
 </Warning>
 
-`reticle_console` returns the app's console log, filtered by level, and tells you whether an empty result is a real reading or a missing one. Reach for it as the fast triage read after something goes wrong, and assert `{ "kind": "console", "absent": true }` when you want a clean console to be part of the pass.
+`reticle_observe { action: "console" }` returns the app's console log, filtered by level, and tells you whether an empty result is a real reading or a missing one. Reach for it as the fast triage read after something goes wrong, and assert `{ "kind": "console", "absent": true }` when you want a clean console to be part of the pass.
 
 ```json
 { "limit": 3 }
@@ -44,12 +44,12 @@ Read both fields together. `observed: true` with a non-zero `dropped` count mean
 
 ## Arguments
 
-| Argument          | What it does                                         |
-| ----------------- | ---------------------------------------------------- |
-| `level`           | `log` · `warn` · `error` · `info`                    |
-| `limit`           | Most recent N. Older matches are dropped and counted |
-| `actionId`        | Only lines attributed to one action                  |
-| `since` / `until` | Cursors from a prior act                             |
+| Argument          | What it does                                                       |
+| ----------------- | ------------------------------------------------------------------ |
+| `level`           | `log` · `warn` · `error` · `info`                                  |
+| `limit`           | Most recent N (default 200). Older matches are dropped and counted |
+| `actionId`        | Only lines attributed to one action                                |
+| `since` / `until` | Cursors from a prior act                                           |
 
 ## The check worth making by default
 
@@ -63,8 +63,8 @@ That fails if the click succeeds _and_ logs an error, which is exactly the case
 
 <Tip>
   `level: "error"` is the fast triage read. If it comes back empty with `observed: true`, stop
-  looking at the console and go look at [`reticle_network`](/tools/network) or
-  [`reticle_state`](/tools/state) instead. That is a real capture from this fixture:
+  looking at the console and go look at [`reticle_observe { action: "network" }`](/tools/network) or
+  [`reticle_look { action: "state" }`](/tools/state) instead. That is a real capture from this fixture:
   `{"logs":[],"observed":true,"cost":{"bytes":337,"tokens":85}}`, eighty-five tokens to rule out a
   whole class of bug.
 </Tip>

package/docs/tools/inspect.mdx

@@ -1,5 +1,5 @@
 ---
-title: reticle_inspect
+title: 'reticle_look { action: "element" }'
 description: Everything about one element. Accessibility properties, geometry, computed styles, design tokens, React component stack, and the exact source file and line.
 icon: crosshairs
 ---
@@ -11,12 +11,12 @@ icon: crosshairs
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
 </Warning>
 
-`reticle_query` finds elements. `reticle_inspect` tells you everything about one of them. It is the tool that turns a finding into an edit, because it ends with a file and a line number.
+`reticle_look { action: "find" }` finds elements. `reticle_look { action: "element" }` tells you everything about one of them. It is the tool that turns a finding into an edit, because it ends with a file and a line number.
 
 ## Example
 
 ```json
-{ "ref": "e120" }
+{ "action": "element", "ref": "e120" }
 ```
 
 Real response:
@@ -40,7 +40,16 @@ Real response:
     "display": "flex",
     "visibility": "visible"
   },
-  "scroll": { "scrollTop": 0, "scrollHeight": 36, "clientHeight": 36, "overflowY": "visible" },
+  "scroll": {
+    "scrollTop": 0,
+    "scrollHeight": 36,
+    "clientHeight": 36,
+    "overflowY": "visible",
+    "scrollLeft": 0,
+    "scrollWidth": 219,
+    "clientWidth": 219,
+    "overflowX": "visible"
+  },
   "theme": {
     "colorToken": "--muted",
     "backgroundToken": null,
@@ -65,7 +74,7 @@ Real response:
 
 Read `colorTokens` rather than `colorToken` when it matters. Design systems routinely give several tokens the same value, and the singular field is `null` whenever more than one matches, because naming an arbitrary winner is worse than admitting the palette cannot tell them apart. `themeScope` says which theme the reading was taken under, so two inspects either side of a theme toggle are comparable instead of quietly contradictory. It is `null`, as above, when the element sits under no scoped theme at all.
 
-**`scroll`** reports the element's own scroll box. `scrollHeight` above `clientHeight` means there is content below the fold inside this element, which is a different problem from the page being scrolled wrong.
+**`scroll`** reports the element's own scroll box on both axes. `scrollHeight` above `clientHeight` means there is content below the fold inside this element, which is a different problem from the page being scrolled wrong. `scrollWidth` above `clientWidth` means the content did not fit across, which is how a label clipped by `text-overflow: ellipsis` shows up.
 
 **`occluded`** is the difference between "visible" and "actually clickable". An element can be present, visible and enabled while sitting under a modal overlay. `states` will look perfect; `occluded: true` is the honest answer.
 
@@ -90,6 +99,6 @@ Read `colorTokens` rather than `colorToken` when it matters. Design systems rout
 </CardGroup>
 
 <Note>
-  `inspect` returns one element in detail. If you find yourself inspecting six things in a row, you
-  probably want [`reticle_query`](/tools/query) with `attrs` instead, one call, six answers.
+  `{ action: "element" }` returns one element in detail. If you find yourself inspecting six things in a row, you
+  probably want [`reticle_look { action: "find" }`](/tools/query) with `attrs` instead, one call, six answers.
 </Note>

package/docs/tools/look.mdx

@@ -0,0 +1,24 @@
+---
+title: reticle_look
+description: Read the page without changing it. The rendered tree, a locator resolved to refs, one element in full, or the app's store.
+icon: magnifying-glass
+---
+
+`reticle_look` reads the page and changes nothing. Pick what to read with `action`. With no `action`, it reads the page.
+
+```json
+{ "action": "find", "by": "testid", "value": "submit" }
+```
+
+| `action` | What it returns | Unmerged name | Details |
+| --- | --- | --- | --- |
+| `page` (default) | The semantic snapshot of what is rendered, with a `ref` for each control. `mode: "interactive"` keeps only what you can act on; `diff: true` returns only what changed since the last look | `reticle_snapshot` | [Snapshot](/tools/snapshot) |
+| `find` | A locator (testid, role, text, label, component) resolved to refs you can act on. `limit` caps the list; `count_only` returns just the count | `reticle_query` | [Query](/tools/query) |
+| `element` | Everything about one `ref`: geometry, scroll, design tokens, and on React the source `file:line` | `reticle_inspect` | [Inspect](/tools/inspect) |
+| `state` | A registered store's value. Scope it with `store`, `path` and `depth` | `reticle_state` | [State](/tools/state) |
+
+A `ref` like `e7` stays valid until its element leaves the DOM, so you do not re-look between actions.
+
+`reticle_look` never produces a verdict. Verdicts come from `reticle_act_and_wait`, `reticle_assert`, `reticle_act { steps }` when a step declares `expect`, and `reticle_verify` (`change`/`flows`). Everything else moves or reads the app and proves nothing. Only `verified: "yes"` is a pass: `unknown` means Reticle could not tell, and `no-fault` means nothing was declared to prove.
+
+With `RETICLE_ADVERTISE_ALL_TOOLS=1`, the daemon advertises the four unmerged names instead of `reticle_look`.

package/docs/tools/navigate.mdx

@@ -24,7 +24,7 @@ Real response, with the throttled-tab `session` and `warning` fields trimmed off
 
 ## `confirmed: true` when the page comes back in time
 
-The daemon waits up to `timeout_ms` (default 5000) for the SDK to re-announce itself. When it does, you are told so and can act immediately without a `reticle_sessions` round trip. This is a real reload response:
+The daemon waits up to `timeout_ms` (default 5000) for the SDK to re-announce itself. When it does, you are told so, with the `sessionId` it came back as, and can act immediately without a `reticle_session { action: "list" }` round trip. This is a real reload response:
 
 ```json
 {
@@ -42,6 +42,8 @@ A full navigation destroys the document the SDK was living in. Reticle cannot re
 
 Most tools would return `ok: true` and let you assume arrival. When the page then fails to load, or loads without instrumentation, you get a confusing cascade of "element not found" errors several calls later, with nothing pointing at the real cause.
 
+`confirmed: false` with a `landedOn` URL is a different case: the page arrived, but the app sent it somewhere else, such as a login or route-guard redirect. `landedOn` says where the browser actually is.
+
 `waitedMs` says which of two things you are looking at. Reticle stopped waiting at the budget it had, or the page never came back. The first is fixed by asking for more: a single-page app reattaching under HMR has been measured at 30–60s, which no default should wait for on every call, but which the caller who knows the app can grant.
 
 ```json
@@ -57,10 +59,10 @@ Most tools would return `ok: true` and let you assume arrival. When the page the
 then confirm a session reconnected:
 
 ```json
-{}
+{ "action": "list" }
 ```
 
-with [`reticle_sessions`](/tools/sessions), and only then snapshot. If no session appears at the new URL, the page did not load or is not instrumented. And you know that immediately rather than three calls later.
+with [`reticle_session`](/tools/sessions), and only then look at the page. If no session appears at the new URL, the page did not load or is not instrumented. And you know that immediately rather than three calls later.
 
 <Warning>
   **Refs do not survive a navigation.** A new document means new refs. Across one afternoon on the

package/docs/tools/network.mdx

@@ -1,6 +1,6 @@
 ---
 title: reticle_network
-description: A filtered log of every request the app made, with bodies, status, timing, automatic credential redaction, and an honest note when evidence has expired.
+description: A filtered log of every request the app made, with status, timing, bodies when capture is on, automatic credential redaction, and an honest note when evidence has expired.
 icon: satellite-dish
 ---
 
@@ -11,7 +11,7 @@ icon: satellite-dish
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
 </Warning>
 
-`reticle_network` returns a filtered log of every request the app made, with request and response bodies, status, timing, and automatic credential redaction. Reach for it to answer "did that call actually fire, and what came back?", which is the thing a screenshot fundamentally cannot show.
+`reticle_network` returns a filtered log of every request the app made, with status, timing, and automatic credential redaction. Request and response bodies are recorded only when the app connects with `captureNetworkBodies: true` (off by default); a failed response keeps its body either way. Reach for it to answer "did that call actually fire, and what came back?", which is the thing a screenshot fundamentally cannot show.
 
 ## Example
 

package/docs/tools/observe.mdx

@@ -6,7 +6,7 @@ icon: timeline
 
 `reticle_observe` returns the full timeline of everything the app did in a window: DOM, network, routing, console, animations and signals, in order, with a summary on top. Reach for it when you do not yet know what went wrong. It reads and diagnoses; it does not produce a verdict.
 
-It is the wide-angle lens. Where `reticle_network` and `reticle_console` answer one question each, `observe` returns everything.
+It is the wide-angle lens. Where `reticle_observe { action: "network" }` and `reticle_observe { action: "console" }` answer one question each, the default `events` action returns everything.
 
 ## Example
 
@@ -75,15 +75,15 @@ The `summary` block is the cheap answer. `consoleErrors: 0` and `network: 0` tel
 
 | Argument          | What it does                                                       |
 | ----------------- | ------------------------------------------------------------------ |
-| `window_ms`       | How far back to look                                               |
+| `window_ms`       | How far back to look. Default 2000, ignored when `since` is given  |
 | `since` / `until` | Cursors from a prior act. The precise way to scope                 |
 | `actionId`        | Only events attributed to one action: "what did that click cause?" |
 | `filters`         | Event-type allowlist. The cheapest way to shrink a big timeline    |
-| `max_events`      | Cap the timeline to the most recent N                              |
+| `max_events`      | Cap the timeline to the most recent N (default 200)                |
 
 ## Scope by cursor, not by clock
 
-Every `reticle_act` response includes a `since` cursor. Passing it to `observe` scopes the timeline to exactly what followed that action, with no guessing about how many milliseconds to look back:
+Every `reticle_act` and `reticle_act_and_wait` response includes a `since` cursor. Passing it to `observe` scopes the timeline to exactly what followed that action, with no guessing about how many milliseconds to look back:
 
 ```json
 { "since": 30224, "filters": ["signal", "net"] }
@@ -127,7 +127,7 @@ When two channels disagree, `observe` says so without being asked:
 
 Punctuation in that block is lightly normalised for the docs; the field names and values are verbatim.
 
-A successful write that moved nothing on the client is the exact shape of a false green. Note that this one was a false alarm caused by a narrow filter: the same window's DOM and state did change, and the filtered read simply could not see it. Widen the window before you act on a contradiction.
+A successful write that moved nothing on the client is the exact shape of a false green. `filters` and `max_events` shape what the call returns, never what it concludes: contradictions are computed over the whole window, so a narrow filter cannot manufacture one.
 
 ## When to use it
 
@@ -138,7 +138,7 @@ Use `observe` when you do not yet know what went wrong. Use the narrow tools whe
     "Something broke after that click, show me everything that happened."
   </Card>
   <Card title="Wasteful use" icon="circle-xmark">
-    "Did a POST fire?" [`reticle_network`](/tools/network) answers that far more cheaply.
+    "Did a POST fire?" [`reticle_observe { action: "network" }`](/tools/network) answers that far more cheaply.
   </Card>
 </CardGroup>
 

package/docs/tools/overview.mdx

@@ -5,7 +5,7 @@ description: The tools your agent sees every turn, the many more it can reach on
 icon: wrench
 ---
 
-Reticle's table holds 45 tools. Your agent is shown **nine**: `reticle_act`, `reticle_act_and_wait`, `reticle_assert`, `reticle_look`, `reticle_navigate`, `reticle_observe`, `reticle_session`, `reticle_tools` and `reticle_verify`. Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.
+Your agent is shown **ten** tools by default: `reticle_navigate`, `reticle_look`, `reticle_act`, `reticle_act_and_wait`, `reticle_observe`, `reticle_assert`, `reticle_session`, `reticle_verify`, `reticle_tools` and `reticle_run`. Verdicts come from `reticle_act_and_wait`, `reticle_assert`, `reticle_act { steps }` when a step declares `expect`, and `reticle_verify` (`change`/`flows`). Everything else moves or reads the app and proves nothing. Only `verified: "yes"` is a pass: `unknown` means Reticle could not tell, and `no-fault` means nothing was declared to prove.
 
 Most of the rest were not removed. They were **merged**. `reticle_snapshot` is `reticle_look { action: "page" }`; `reticle_console` is `reticle_observe { action: "console" }`. One tool, one action argument, same work. Calling a retired name returns the call that replaced it, and `reticle_tools` prints the whole mapping.
 
@@ -13,61 +13,60 @@ That is not a limitation, it's the design. MCP re-sends every advertised tool de
 
 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.
 
-What the verify loop does **not** advertise are the specialised tools: `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock`, `reticle_clock`. Each is one `reticle_run { tool, args }` hop away, and a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises them outright.
+What the verify loop does **not** advertise are the specialised tools: `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock`, `reticle_clock`. Each is one `reticle_run { tool, args }` hop away.
+
+A daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises 30 tools outright, and it **switches to the unmerged spelling**: `reticle_snapshot`, `reticle_query`, `reticle_inspect` and `reticle_state` replace `reticle_look`; `reticle_network` and `reticle_console` replace `reticle_observe { action }`; `reticle_wait_for` replaces `reticle_assert { action: "wait" }`; `reticle_sessions` and `reticle_feedback` replace `reticle_session` list and feedback; `reticle_act_sequence` replaces `reticle_act { steps }`. Examples in these docs use the default spelling. The counts are asserted by `server/src/surface/tools/surface-sizes.test.ts`.
 
 <Note>
-  Measured off the real wire on 2026-09-16, by reading `tools/list` from a fresh daemon: the default
-  surface is **9 tools at 17,663 bytes**, against **30 tools at 126,954 bytes** when
-  `RETICLE_ADVERTISE_ALL_TOOLS` is set, 7.2x more and 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, and the figures this note replaced were a year out of date and described a surface
-  that no longer existed.
+  Measured with [`bench/harness/schema-tax.mjs`](/token-efficiency) on 2026-10-08: the default
+  surface is **10 tools, about 4,650 schema tokens**, against **30 tools, about 35,000 tokens** with
+  `RETICLE_ADVERTISE_ALL_TOOLS=1`, charged on every message. Re-measure before quoting; the surface
+  grows.
 </Note>
 
-## The default 19
-
-Grouped by the job they do in the verify loop.
+## The ten, by job
 
 <CardGroup cols={2}>
   <Card title="Look" icon="magnifying-glass">
-    `reticle_snapshot` · `reticle_query` · `reticle_inspect` · `reticle_sessions` ·
-    `reticle_capabilities`
+    `reticle_look { action: "page" | "find" | "element" | "state" }`
   </Card>
   <Card title="Act" icon="hand-pointer">
-    `reticle_act` · `reticle_act_and_wait` · `reticle_act_sequence` · `reticle_navigate`
+    `reticle_act` · `reticle_act { steps }` · `reticle_act_and_wait` · `reticle_navigate`
   </Card>
   <Card title="Observe" icon="satellite-dish">
-    `reticle_observe` · `reticle_network` · `reticle_console` · `reticle_state` · `reticle_wait_for`
+    `reticle_observe` · `{ action: "network" }` · `{ action: "console" }`
+  </Card>
+  <Card title="Prove" icon="circle-check">
+    `reticle_act_and_wait` · `reticle_assert` · `reticle_verify`
   </Card>
-  <Card title="Prove & discover" icon="circle-check">
-    `reticle_assert` · `reticle_tools` · `reticle_run`
+  <Card title="Discover" icon="compass">
+    `reticle_tools` · `reticle_run`
   </Card>
   <Card title="Session & feedback" icon="comment">
-    `reticle_session` · `reticle_feedback`
+    `reticle_session { action: "list" | "feedback" | "yield" | … }`
   </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.
+  Verdicts come from `reticle_act_and_wait`, `reticle_assert`, `reticle_act {steps}` when a step
+  declares `expect`, and `reticle_verify` (`change`/`flows`). Everything else moves or reads the app
+  and proves nothing. Only `verified: "yes"` is a pass: `unknown` means Reticle could not tell, and
+  `no-fault` means nothing was declared to prove. A drive that ends without a verdict has no result,
+  however many tools it used.
 </Warning>
 
 ## Why these 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.
+`reticle_look { action: "element" }` (unmerged name `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 be reachable only through `reticle_run`, which meant an agent had to already know it existed to use it.
 
-`reticle_act_sequence` batches a multi-step interaction into one round trip. It was also reachable only through `reticle_run`, and the consequence is a login form driven one call at a time, over and over.
+`reticle_act { steps }` (unmerged name `reticle_act_sequence`) batches a multi-step interaction into one round trip. It was also reachable only through `reticle_run`, and the consequence is a login form driven 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 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
@@ -75,7 +74,7 @@ Direct `reticle_network` and `reticle_console` stay advertised even though `reti
   good; empty is not.
 </Tip>
 
-## Reaching the other 29
+## Reaching every other tool
 
 ```json
 { "tool": "reticle_verify", "args": { "action": "flows" } }
@@ -85,15 +84,15 @@ Direct `reticle_network` and `reticle_console` stay advertised even though `reti
 
 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
+## Read responses carry their cost
 
-Reticle tells you what each answer cost, because a verification tool that quietly eats your context window is not saving you anything:
+The read tools (`reticle_look` page and find, `reticle_observe` network and console) tell you what each answer cost, because a verification tool that quietly eats your context window is not saving you anything:
 
 ```json
 "cost": { "bytes": 944, "tokens": 236 }
 ```
 
-That is a real `reticle_query` response: seven buttons found, with source pointers, for 236 tokens.
+That is from a real `reticle_look { action: "find" }` response: seven buttons found, with source pointers, for 236 tokens.
 
 ## Every response tells you when not to trust it
 
@@ -119,6 +118,8 @@ A tool that says "no requests found" when it actually means "I lost the ones you
 
 ## Reference
 
+These pages are named for the unmerged tools. Each one gives the default spelling (`reticle_look { action: "page" }` for `reticle_snapshot`, and so on).
+
 ### Look
 
 | Tool | Answers |
@@ -154,10 +155,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 29 |
+| [`reticle_run`](/tools/tools-and-run) | Invoke any other registered tool by name |
 | [`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 |
+| [`reticle_session { action: "feedback" }`](/tools/session-and-feedback) | Tell the maintainers Reticle got something wrong (`reticle_feedback` is its unmerged name, not advertised by default) |
 
 <Card title="The complete reference" icon="book" href="/usage">
-  Every tool, every argument, including the 29 in the cold tail.
+  Every tool, every argument, including the cold tail.
 </Card>

package/docs/tools/query.mdx

@@ -11,7 +11,7 @@ icon: magnifying-glass
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
 </Warning>
 
-`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.
+`reticle_look { action: "find" }` 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
 
@@ -63,7 +63,7 @@ Seven buttons, each with a `ref` to act on and a source file to open, for 236 to
 | `attrs` | Attribute NAMES to project per match, e.g. `['href']` to inventory links. The values come back in each match's `attrs` map. It does not filter, so `name=value` is refused |
 | `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" }`.
+`role`, `text`, `label`, `placeholder`, `testid` and `alt` also have a predicate spelling, so `{ "role": "button" }` works as shorthand for `{ "by": "role", "value": "button" }`.
 
 ## Use `count_only` when you only need a number
 
@@ -119,13 +119,13 @@ The testid existed, on another route. `hint.route` says where you actually are,
 
 ## 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.
+`ref` is the handle for every other call: `reticle_act`, `reticle_look { action: "element" }`, `reticle_look { action: "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 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.
+`source` appears when the app is built in dev with the Reticle build plugin; production builds omit it. 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. 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.
+`states` distinguishes `present` from `visible` from `enabled`. An element can be all three and still be covered by a modal. [`reticle_look { action: "element" }`](/tools/inspect) reports `occluded` for that.
 
 <Tip>
   Query by `testid` when you can. Role and text queries survive refactors well; testids survive

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

@@ -10,15 +10,18 @@ icon: comments
 
 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 `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`       |
+| Action | What it does |
+| --- | --- |
+| `list` | Which tabs are connected, and whether they can be driven. Your first call. An empty list carries a `why` naming the cause |
+| `feedback` | Tell the maintainers Reticle got something wrong. Takes the fields described under [reticle_feedback](#reticle-feedback) below |
+| `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: `idleEndMs`, the idle-end window, or `hud`: `hidden`, `shown`, `removed` (until reload), or a corner (`top-left`, `top-right`, `bottom-left`, `bottom-right`) when the HUD covers a control you must test |
+| `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` |
+| `account` | Where the user stands: signed in or not, whether the project reports to the dashboard, plan and credits, whether the Harness is on, and the one thing to do next. Read it before telling the user anything about credits or the plan |
 
 ```json
 { "action": "yield", "mode": "waiting" }
@@ -40,7 +43,7 @@ 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."
+  "IMPORTANT": "When you stop driving, call reticle_session {action:\"yield\", mode:\"waiting\"|\"ask\"}. The panel reads \"live\" until you do. {action:\"end\"} only when the task is done: it is final."
 }
 ```
 
@@ -52,6 +55,10 @@ And each lease carries the rule in the payload itself:
 
 ## reticle_feedback
 
+<Note>
+  `reticle_feedback` is not advertised by default. Call `reticle_session { action: "feedback", kind, text }`: the same fields, routed on `action`. The old name answers with the new call.
+</Note>
+
 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
@@ -78,13 +85,15 @@ The `rating` is secondary to that text on purpose. A score produced because some
 
 ### It will tell you when it cannot send
 
-Feedback is not fire-and-forget, and it does not pretend to succeed:
+Feedback sends in the background so you are not kept waiting, but it does not pretend to succeed: `sent` stays `false` until delivery is confirmed, `accepted` says the report was validated and queued, and a send that later fails is reported on a later tool result. A report that is not accepted says why:
 
 ```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, or run from the app you are verifying.",
+  "reason": "this is a Reticle source checkout, where telemetry is disabled by design, so this could not be sent (it has been written to disk instead, and nothing was lost).",
+  "savedTo": "<project>/.reticle/feedback/<timestamp>-bug.md",
+  "fileWith": "gh issue create --repo reticlehq/reticle --title \"Reticle feedback: bug\" --body-file \"<project>/.reticle/feedback/<timestamp>-bug.md\"",
   "redacted": [],
   "context": {
     "stack": "react",
@@ -100,7 +109,7 @@ Feedback is not fire-and-forget, and it does not pretend to succeed:
 
 `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.
+When the report cannot be sent it is written to disk: `savedTo` is the file and `fileWith` is a ready-to-run command that turns it into an issue. 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

@@ -51,7 +51,7 @@ A backgrounded tab adds a `recommendation` telling you what to do about it, and
     "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"
+  "recommendation": "tab is not hidden but has not reported health recently ... Timing-sensitive work (animations, debounces, gestures) is what degrades: pass `refuseWhenThrottled: true` to refuse rather than act over events that may not land. Lease a separate context only if a drive here actually fails; ..."
 }
 ```
 
@@ -62,27 +62,27 @@ An empty list is not silent. It comes back with a `why` that separates the two c
 ```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."
+  "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: START IT YOURSELF, in the background, using the command in `next_action`, and tell the human in one line that it is running. (2) There is no `.reticle.json` in the directory this daemon is running in, which is the file `reticle init` writes, so the app may carry no Reticle SDK. Check the app's OWN directory before re-running it. ..."
 }
 ```
 
-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`.
+That string is trimmed. The full text also lists the exact ports it scanned, says a server on any other port is invisible to the scan (ask for the app's URL and open it with `reticle open <url>`), and warns that in a monorepo the daemon often runs at the root while the app lives in a subdirectory.
 
 ## 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 |
+| `throttled` | The tab is hidden, or has not reported health recently. A hidden tab clamps timers and animation frames, so an action can land on a page that never advances; a throttled tab that is not hidden is usually just quiet and often still driveable |
 | `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 |
+| `hasCapabilities` | Whether the app registered testids, signals and stores. `false` means [`reticle_look { action: "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.
+  A hidden tab (`hidden: true`, which also sets `throttled`) 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