@reticlehq/server 3.6.0 → 3.7.0

package/docs/usage.md

@@ -4,7 +4,7 @@ description: 'The full reference and cookbook: every tool, flag, and workflow, w
 icon: book
 ---
 
-Every Reticle drive is the same four steps: **look** (`reticle_look { action: "page" }` / `reticle_look { action: "find" }`), **act** (`reticle_act` / `reticle_act { steps: [...] }`), **observe** (`reticle_observe` / `reticle_observe { action: "network" }` / `reticle_look { action: "state" }`), **assert** (`reticle_assert`). Verdicts come from `reticle_act_and_wait`, `reticle_assert`, and `reticle_act { steps }` when a step declares `expect`, so a run that ends anywhere else proved nothing. This page is the full reference for every tool, predicate, action and flag in that loop.
+Every Reticle drive is the same four steps: **look** (`reticle_look { action: "page" }` / `reticle_look { action: "find" }`), **act** (`reticle_act` / `reticle_act { steps: [...] }`), **observe** (`reticle_observe` / `reticle_observe { action: "network" }` / `reticle_look { action: "state" }`), **assert** (`reticle_assert`). 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. This page is the full reference for every tool, predicate, action and flag in that loop. Tools outside the ten advertised by default are called through `reticle_run({ tool, args })`, and examples use the default tool names.
 
 If you haven't set up Reticle yet, start with [Getting Started](getting-started.md).
 
@@ -72,7 +72,7 @@ Who benefits most: anyone shipping **dashboards, internal tools, SaaS apps**. Be
 3. **Observe** with `reticle_observe({ since })`: everything the app did _after_ that action.
 4. **Assert** with `reticle_assert({ predicate })`. Verify it, get evidence.
 
-**Refs.** Elements are addressed by stable handles like `e7`. You get them from `snapshot` or `query`, then pass them to `act`/`inspect`. A ref re-resolves to its element across re-renders; if the element is gone, you get a clear error.
+**Refs.** Elements are addressed by stable handles like `e7`. You get them from `reticle_look { action: "page" }` or `reticle_look { action: "find" }`, then pass them to `act`/`inspect`. A ref re-resolves to its element across re-renders; if the element is gone, you get a clear error.
 
 **Evidence, not prose.** Every tool returns structured data (counts, the matching network call, the snapshot delta) so the agent reasons over facts, not a vibe.
 
@@ -132,7 +132,7 @@ Perform one action / several in order.
 - **`reticle_act { steps: [...] }` args:** `steps: [{ ref | target, action, args? }]`. Each step takes `ref` (from a snapshot/query) or `target` (`{ testid }` / `{ label }` / `{ role, name }` / `{ text }`). That is the same locator `reticle_act` accepts. → `{ since, dispatched, result }` where `result = { ok, count, effects: [...], steps: [...] }` (one `effect` per step; each step carries its own `dispatched`/`settled`/`settleReason`).
 - See [§5](#5-actions-full-list) for the action list.
 
-**Dispatch vs settle.** The action is two phases: the **dispatch** (the synchronous click/fill, which is what can fail) and the **settle** (waiting one animation frame so React's commit lands before we return). The settle is **bounded** (~200ms): in a throttled/background tab `requestAnimationFrame` never fires, so Reticle falls back to a timer and resolves anyway. A settle timeout is therefore **never an error**: `reticle_act` resolves with `settled:false, settleReason:"timeout"` and the dispatch (the click) has still landed. Only a real dispatch failure (stale ref, wrong element type) throws.
+**Dispatch vs settle.** (Settle means the page has stopped changing for now.) The action is two phases: the **dispatch** (the synchronous click/fill, which is what can fail) and the **settle** (waiting one animation frame so React's commit lands before we return). The settle is **bounded** (~200ms): in a throttled/background tab `requestAnimationFrame` never fires, so Reticle falls back to a timer and resolves anyway. A settle timeout is therefore **never an error**: `reticle_act` resolves with `settled:false, settleReason:"timeout"` and the dispatch (the click) has still landed. Only a real dispatch failure (stale ref, wrong element type) throws.
 
 | top-level field | meaning |
 | --- | --- |
@@ -184,11 +184,11 @@ The timeline + summary of what happened.
 Act, then wait for a predicate: the whole act→observe→assert loop in one hop.
 
 - **args:** `ref`, `action`, `args?`, `until: <predicate>`, `timeout_ms?` (default 4000; 0 = evaluate once), `refuseWhenThrottled?`, `intent?`, `durable?` (after a yes, reload and require `until`'s element/text/state parts to hold again), `sessionId?`.
-- **returns:** `{ effect, verdict, trace, session, warning? }`. `effect` is the action result (`{ ok, ref, action }`), `verdict` is `{ pass, evidence?, failureReason? }`, `trace` is the reaction report of everything the app did after the action, and `session` is the tab-health block `{ lastSeenMs, throttled, focused }` (with a `warning` when throttled). A failing `verdict` still returns `effect` + `trace` so you can see what _did_ happen. The predicate is automatically floored at this act's cursor, so it only matches events the action actually caused.
+- **returns:** `{ verified, because, effect, verdict, trace, summary, honesty, since, session, … }`. **Gate on `verified`** (`yes` / `no` / `unknown` / `no-fault`; only `yes` is a pass) and read `because` for the deciding evidence. `effect` is the action result (`{ ok, ref, action }`), `verdict` is `{ pass, evidence?, failureReason? }` plus `verifiedReason`, the clause that decided it, `trace` is the reaction report of everything the app did after the action, and `session` is the tab-health block `{ lastSeenMs, throttled, focused }` (with a `warning` when throttled). A failing `verdict` still returns `effect` + `trace` so you can see what _did_ happen. The predicate is automatically floored at this act's cursor, so it only matches events the action actually caused.
 
 ### `reticle_assert { action: "wait" }`
 
-Block until a predicate holds (or time out). Looks both backward (recent buffer) and forward.
+Block until a predicate holds (or time out). Looks both backward (recent buffer) and forward. It returns `pass` and evidence with no `verified`: a wait is not a verdict. Put the consequence on `reticle_act_and_wait` or `reticle_assert` to get one.
 
 - **args:** `predicate`, `timeout_ms?` (default 4000), `since?`, `sessionId?`.
 - **No stale-signal false passes.** By default the evaluation window is floored at your **last act's cursor**, so a signal/network/console/animation event buffered _before_ the action can never satisfy the predicate (the report's "validation 68 == 68 was a lie" footgun). Pass an explicit `since` (an act/observe cursor) to widen or narrow the window deliberately. Element/text predicates query the live DOM and are unaffected by `since`.
@@ -218,13 +218,13 @@ Fast targeted lookups without a full timeline.
 
 - `reticle_observe({ action: "network", since?, method?, urlContains?, status?, bodies? })` → `{ calls }`. Pass `bodies: false` for a body-free listing (method/url/status/timing only); bodies dominate the payload, so the common "did POST /x return 200?" read gets much cheaper.
 - `reticle_observe({ action: "console", level?, since? })` → `{ logs }`
-- `reticle_animations()` → running/recent animations.
+- `reticle_run({ tool: "reticle_animations", args: {} })` → running/recent animations.
 
 ### `reticle_capabilities`
 
 The app-advertised testable surface (registered via `reticle.describe`). Call this first to learn what to assert on without reading source.
 
-- `reticle_capabilities({ sessionId? })` → `{ testids, signals, stores, flows }`
+- `reticle_run({ tool: "reticle_capabilities", args: { sessionId? } })` → `{ testids, signals, stores, flows }`
 
 `reticle_session { action: "list" }` also surfaces a `hasCapabilities` flag per session so you know when it's worth calling. Returns empty arrays (never errors) if the app advertised nothing.
 
@@ -232,7 +232,7 @@ The app-advertised testable surface (registered via `reticle.describe`). Call th
 
 Read the app's domain model **before testing**: a synthesis of every saved flow + the registered capabilities. Tells you what to test and where the real risk is without crawling the app. Reads `.reticle/flows/` + `.reticle/contract.json`, no browser needed.
 
-- `reticle_domain({})` → `{ flowCount, flows: [{ name, steps, grade, asserts, signals, testids, warning?, risk? }], declared: { testids, signals, stores }, coverage: { asserted, presenceOnly, assertionFree }, gaps: { unassertedFlows, declaredUntestedSignals, declaredUntestedTestids }, riskRanked, summary }`
+- `reticle_run({ tool: "reticle_domain", args: {} })` → `{ flowCount, flows: [{ name, steps, grade, asserts, signals, testids, warning?, risk? }], declared: { testids, signals, stores }, coverage: { asserted, presenceOnly, assertionFree }, gaps: { unassertedFlows, declaredUntestedSignals, declaredUntestedTestids }, riskRanked, summary }`
 - **`gaps`** is the point: `declaredUntestedSignals` are intents the app emits that **no flow asserts** (untested behavior); `unassertedFlows` act but verify no consequence. Close them with a flow + a consequence assertion (`reticle_annotate`).
 - **`riskRanked`** orders flow names worst-first by combining run history (`.reticle/project.json`: recently failed/drifted, or passed-with-errors) with assertion quality (a green assertion-free flow is still risky). **Test these first.** Each flow's `risk` carries `{ level, reason, lastStatus? }`.
 
@@ -269,17 +269,17 @@ reticle_look({ action: "state", store: "__reticle_renders", path: "commits" })
 
 A render storm shows up as a commit count that climbs with no corresponding DOM mutation: a perf regression invisible to any outside-the-page tool.
 
-### `reticle_session {action:"narrate"}` / `reticle_clock`
+### `reticle_session { action: "narrate" }` / `reticle_clock`
 
 Show the agent's intent on the page, and control time (toasts/debounces/auto-dismiss). See [§16](#16-presenter-mode-narration--fake-clock-watch--control).
 
-### `reticle_baseline {action:"save"}` / `reticle_baseline {action:"list"}` / `reticle_baseline {action:"diff"}`
+### `reticle_run { tool: "reticle_baseline", args: { action: "save" } }` / `reticle_run { tool: "reticle_baseline", args: { action: "list" } }` / `reticle_run { tool: "reticle_baseline", args: { action: "diff" } }`
 
 Regression detection. See [§8](#8-regression-baselines--diff).
 
-### `reticle_record {action:"start"}` / `reticle_record {action:"stop"}` / `reticle_replay`
+### `reticle_run { tool: "reticle_record", args: { action: "start" } }` / `reticle_run { tool: "reticle_record", args: { action: "stop" } }` / `reticle_replay`
 
-Capture a flow's reaction report and compile it into a replayable program. See [§9](#9-recording-a-flow). `reticle_record {action:"stop"}` also returns a `cost:{ events, bytes }` hint alongside the reaction report so you can gauge the recording's size.
+Capture a flow's reaction report and compile it into a replayable program. See [§9](#9-recording-a-flow). `reticle_run { tool: "reticle_record", args: { action: "stop" } }` also returns a `cost:{ events, bytes }` hint alongside the reaction report so you can gauge the recording's size.
 
 ### `reticle_explore`
 
@@ -287,32 +287,32 @@ List interactive elements + console-error count for autonomous exploration. See
 
 ### Flows, recorder & self-healing (`.reticle/`)
 
-`reticle_contract_save`, `reticle_flow_save` / `reticle_flow_save_recorded` / `reticle_flow {action:"list"}` / `reticle_flow {action:"load"}` / `reticle_flow_replay` / `reticle_verify {action:"flows"}`, `reticle_verify { action: "heal" }`, `reticle_annotate`: record once, replay forever (anchored on testid/signal, or on an auto-derived component/source anchor when there's no testid), with legible drift + self-heal. Full guide: [Flows, the recorder & self-healing](flows.md).
+`reticle_contract_save`, `reticle_flow_save` / `reticle_flow_save_recorded` / `reticle_run { tool: "reticle_flow", args: { action: "list" } }` / `reticle_run { tool: "reticle_flow", args: { action: "load" } }` / `reticle_flow_replay` / `reticle_verify { action: "flows" }`, `reticle_verify { action: "heal" }`, `reticle_annotate`: record once, replay forever (anchored on testid/signal, or on an auto-derived component/source anchor when there's no testid), with legible drift + self-heal. Full guide: [Flows, the recorder & self-healing](flows.md).
 
 - **`reticle_verify({ action: "flows", names?, sessionId? })`** is the regression-suite call: it replays EVERY saved flow (or a subset) deterministically and returns one verdict `{ status, passed, failed, failures: [{ flow, verdict, whatChanged, whereInSource, nextAction }] }`. Passing flows are counted; only failures carry detail. Run it after any change: one call, no LLM per flow.
-- **Decision envelope:** on a drift/fail, `reticle_flow_replay` (and each `reticle_verify {action:"flows"}` failure) returns the actionable fix: `whatChanged`, `whereInSource` (`file:line`), and a one-line `nextAction` (e.g. "rebind the anchor to 'new-deploy', or update the flow if intended").
+- **Decision envelope:** on a drift/fail, `reticle_flow_replay` (and each `reticle_verify { action: "flows" }` failure) returns the actionable fix: `whatChanged`, `whereInSource` (`file:line`), and a one-line `nextAction` (e.g. "rebind the anchor to 'new-deploy', or update the flow if intended").
 
 ### Human-in-the-loop control
 
-`reticle_session {action:"end"}`, `reticle_session {action:"resume"}`, `reticle_session {action:"messages"}`: the human can pause the agent, send it a correction, or end the session from the floating panel; the agent receives guidance on its next tool call. Full guide: [Human-in-the-loop control](human-control.md).
+`reticle_session { action: "end" }`, `reticle_session { action: "resume" }`, `reticle_session { action: "messages" }`: the human can pause the agent, send it a correction, or end the session from the floating panel; the agent receives guidance on its next tool call. Full guide: [Human-in-the-loop control](human-control.md).
 
-### `reticle_session {action:"review"}`: drain the bugs the human flagged on the page
+### `reticle_session { action: "review" }`: drain the bugs the human flagged on the page
 
 The dev clicks **"Flag a bug"** in the running app, points at the element that looks wrong, and types what's wrong (⌘/Ctrl+Enter to send). Each flag becomes a **mark** the agent drains:
 
 ```
-reticle_session {action:"review"}({ sessionId })
+reticle_session({ action: "review", sessionId })
 → { marks: [{ id: "m1", note: "this button is misaligned", label: "button \"Pay\"",
               source: { file: "src/Checkout.tsx", line: 42 },
-              fix: "Open src/Checkout.tsx:42 and fix: this button is misaligned. Then reticle_session {action:"review"} { resolve: \"m1\" }" }],
+              fix: "Open src/Checkout.tsx:42 and fix: this button is misaligned. Then reticle_session { action: "review" } { resolve: \"m1\" }" }],
     pendingCount: 1 }
 ```
 
-Each pending mark carries the human note, the element label, the source **`file:line`** (when the framework stamped one), and a ready-to-act `fix` hint. Open the file, apply the fix, then `reticle_session {action:"review"}({ resolve: "m1" })`. The human watching the panel sees **"✓ fixed: …"** land. Reading never consumes a mark, so you can list → fix → verify → resolve. `reticle_session { action: "list" }` also reports `pendingMarks` so you notice flagged bugs during normal orientation.
+Each pending mark carries the human note, the element label, the source **`file:line`** (when the framework stamped one), and a ready-to-act `fix` hint. Open the file, apply the fix, then `reticle_session({ action: "review", resolve: "m1" })`. The human watching the panel sees **"✓ fixed: …"** land. Reading never consumes a mark, so you can list → fix → verify → resolve. `reticle_session { action: "list" }` also reports `pendingMarks` so you notice flagged bugs during normal orientation.
 
 ### `reticle_network_mock`: stub the network for error-state testing
 
-On a page Reticle drives (`reticle drive`) or a leased Playwright tab (`reticle_lease acquire`), make a request return a 500, force it offline, or delay it, so testing error/edge states is one declared rule, no backend changes:
+On a page Reticle drives (`reticle drive`) or a leased Playwright tab (`reticle_run { tool: "reticle_lease", args: { action: "acquire" } }`), make a request return a 500, force it offline, or delay it, so testing error/edge states is one declared rule, no backend changes:
 
 ```
 reticle_run({ tool: "reticle_network_mock", args: { mocks: [{ urlContains: "/api/pay", method: "POST", status: 500 }] } })
@@ -334,9 +334,9 @@ reticle_run({ tool: "reticle_viewport", args: { width: 1280, height: 800 } })
 
 This is one of three knobs for **CI-stable visual regression**. Set them together:
 
-1. **`reticle_viewport({ width, height })`** gives the same dimensions on every machine.
-2. **`reticle_clock({ freeze: true })`** kills animation/time jitter so the pixels are stable.
-3. **`reticle_visual_diff({ baseline, masks: [{ x, y, width, height }] })`** neutralizes volatile regions (clocks, avatars, ids) so only real changes fail.
+1. **`reticle_run({ tool: "reticle_viewport", args: { width, height } })`** gives the same dimensions on every machine.
+2. **`reticle_run({ tool: "reticle_clock", args: { freeze: true } })`** kills animation/time jitter so the pixels are stable.
+3. **`reticle_run({ tool: "reticle_visual_diff", args: { baseline, masks: [{ x, y, width, height }] } })`** neutralizes volatile regions (clocks, avatars, ids) so only real changes fail.
 
 ---
 
@@ -381,6 +381,8 @@ A **predicate** declares what should be true. `reticle_assert` / `reticle_assert
 { "kind": "state", "store": "app", "path": "deployments.0.status", "equals": "live" }
 ```
 
+`visible` excludes elements whose boxes are fully clipped by an ancestor's `overflow:hidden` or `overflow:clip`; a partly clipped element stays visible. Expanding a clamped card can therefore prove that its previously hidden paragraph became visible. `overflow:auto` and `overflow:scroll` keep their existing visibility semantics, including content beyond the scrollport. Ordinary document content outside the window remains visible; `inViewport` checks the window intersection after any hidden/clip ancestor clipping, without introducing scrollport clipping.
+
 A `state` assertion is graded as a **consequence** (a wrong element or stale render cannot fake it), and is usable the same three ways anywhere predicates flow: ad-hoc (`reticle_assert` / `reticle_act_and_wait` `until`), as a flow step invariant (`reticle_annotate { kind: "assert-state", statePath, store?, equals? }`), and as a flow's golden end-condition (`reticle_annotate { kind: "success-state", statePath, … }`). On a miss it names the real store value and the keys that were available: legible, not a blind fail.
 
 ### Combinators
@@ -393,7 +395,7 @@ A `state` assertion is graded as a **consequence** (a wrong element or stale ren
 
 ### Timing
 
-- `timeout_ms` (on `assert`/`wait_for`): wait up to N ms for it to become true.
+- `timeout_ms` (on `reticle_assert`, either action): wait up to N ms for it to become true.
 - `since` (on `net`/`console` leaves): only consider events after this cursor (from `act`).
 
 `dataMatches` matches field by field; a key can be a dotted path (`"order.total"`, `"items.0.id"`), and `*` means "present, any value".
@@ -415,9 +417,12 @@ A `state` assertion is graded as a **consequence** (a wrong element or stale ren
 | `select` | `{ value }` | `<select>` option |
 | `check` / `uncheck` | n/a | checkbox/radio |
 | `submit` | n/a | submits the element's `<form>` |
-| `press` | `{ key, modifiers?, holdMs?, keys?, code? }` | keydown/up (default `Enter`); `modifiers`: an array of `Meta` / `Control` / `Shift` / `Alt` for Cmd+K-style shortcuts. With a `ref` the key is dispatched AT that element; with NO ref it is a document key (Escape, Tab, a shortcut) and goes through the real keyboard, so it can actually move focus. `holdMs` keeps the key DOWN for that long (hold-to-confirm, hold-to-reveal). `keys` holds several keys together, pressed in order and released in reverse, and `code` names the physical key: both stay on the in-page dispatcher, which is the only path that can express them |
+| `press` | `{ text, modifiers?, holdMs?, keys?, code? }` | keydown/up (default `Enter`). `text` is the key name (`Escape`, `Tab`); `key` is an accepted alias; `modifiers`: an array of `Meta` / `Control` / `Shift` / `Alt` for Cmd+K-style shortcuts. With a `ref` the key is dispatched AT that element; with NO ref it is a document key (Escape, Tab, a shortcut) and goes through the real keyboard, so it can actually move focus. `holdMs` keeps the key DOWN for that long (hold-to-confirm, hold-to-reveal). `keys` holds several keys together, pressed in order and released in reverse, and `code` names the physical key: both stay on the in-page dispatcher, which is the only path that can express them |
 | `scrollIntoView` | n/a |  |
-| `upload` | `{ name, content?, type? }` | sets a file on `<input type=file>` |
+| `scroll` | `{ dy?, dx?, fraction? }` | Scrolls the nearest scrollable container (or the page, with no `ref`) by `dy`/`dx` pixels, either direction. `fraction` (0 to 1) jumps to that point of the height. No args steps down most of a screen |
+| `tap` | `{ holdMs? }` | A touch tap: pointer and touch events, then `click`. `holdMs` makes it a long press |
+| `zoom` | n/a | Page zoom. Refused inside the page, because CSS zoom changes how a page looks without changing its layout, and a passing check on it would be false |
+| `upload` | `{ path }` or `{ name, content?, type? }` | sets a file on `<input type=file>`: `path` is a file on disk (absolute or relative to the project root) whose real bytes the daemon delivers; `name`/`content` supply inline bytes |
 | `drag` | `{ toRef }` | pointer-based drag (dnd-kit / rbd) + HTML5 DnD |
 
 ---
@@ -491,7 +496,7 @@ reticle_assert({ timeout_ms: 3000, predicate: { kind: "element",
   query: { text: "Invoice #4821", scope: "[data-testid=item-list]" }, state: "visible" } })
 ```
 
-> Note: if your list is **virtualized** (react-window/virtuoso), an off-screen row is not in the DOM at all, so `reticle_look { action: "find" }` correctly finds nothing. Use **`reticle_scroll_to`** to scroll the windowed container until the row renders, then query it: `reticle_scroll_to({ by: "text", value: "Invoice #4821", container: "[data-testid=item-list]" })`. Asserting against the data with `reticle.signal` or `reticle_look { action: "state" }` also works and is cheaper.
+> Note: if your list is **virtualized** (react-window/virtuoso), an off-screen row is not in the DOM at all, so `reticle_look { action: "find" }` correctly finds nothing. Use **`reticle_scroll_to`** to scroll the windowed container until the row renders, then query it: `reticle_run({ tool: "reticle_scroll_to", args: { by: "text", value: "Invoice #4821", container: "[data-testid=item-list]" } })`. Asserting against the data with `reticle.signal` or `reticle_look { action: "state" }` also works and is cheaper.
 
 ### "Login form: does it actually authorize?"
 
@@ -568,7 +573,7 @@ reticle.describe({
 });
 ```
 
-The agent reads this back with `reticle_capabilities()`; see [§3](#3-the-tools-full-reference).
+The agent reads this back with `reticle_run({ tool: "reticle_capabilities", args: {} })`; see [§3](#3-the-tools-full-reference).
 
 ```jsonc
 reticle_assert({ timeout_ms: 30000, predicate: {
@@ -577,7 +582,7 @@ reticle_assert({ timeout_ms: 30000, predicate: {
 
 #### Keeping signals from drifting (lint)
 
-Signals only help if you actually emit one whenever user-visible state changes. The `@reticlehq/eslint-plugin` package ships `reticle/require-signal-on-mutation`, which flags any function that calls a configured store **mutator** but never fires the **signal callee** in the same body, so the signal map can't silently fall behind the store. (The package also ships `reticle/no-internal-tags`; both are on in its `recommended` config.)
+Signals only help if you actually emit one whenever user-visible state changes. The `@reticlehq/eslint-plugin` package ships `reticle/require-signal-on-mutation`, which flags any function that calls a configured store **mutator** but never fires the **signal callee** in the same body, so the signal map can't silently fall behind the store. (The package also ships `reticle/no-internal-tags` and `reticle/no-runaway-comment`; all three are on in its `recommended` config.)
 
 ```js
 // eslint.config.mjs
@@ -606,10 +611,10 @@ The "did anything silently break/disappear?" workflow.
 
 ```jsonc
 // after you've confirmed a screen is good:
-reticle_baseline {action:"save"}({ name: "checkout-ok" })
+reticle_run({ tool: "reticle_baseline", args: { action: "save", name: "checkout-ok" } })
 
 // later, after a change:
-reticle_baseline {action:"diff"}({ baseline: "checkout-ok" })
+reticle_run({ tool: "reticle_baseline", args: { action: "diff", baseline: "checkout-ok" } })
 // → { removed: ["- button \"Export\""], added: ["- alert \"Card declined\""],
 //     consoleErrors: 2, routeChanged: false }
 ```
@@ -618,7 +623,7 @@ reticle_baseline {action:"diff"}({ baseline: "checkout-ok" })
 
 ### Pixel-perfect visual regression that's stable in CI (driven mode)
 
-The semantic `reticle_baseline {action:"diff"}` above never flakes. For an actual **pixel** diff (`reticle_screenshot` + `reticle_visual_diff`, driven mode), three knobs make it CI-stable instead of flaky:
+The semantic `reticle_run { tool: "reticle_baseline", args: { action: "diff" } }` above never flakes. For an actual **pixel** diff (`reticle_screenshot` + `reticle_visual_diff`, driven mode), three knobs make it CI-stable instead of flaky:
 
 ```jsonc
 reticle_run({ tool: "reticle_viewport", args: { width: 1280, height: 800 } }) // 1. same size on every machine
@@ -638,9 +643,9 @@ Without all three, a pixel diff fails on a different window size, a mid-animatio
 Capture everything that happens across a span. Useful for "run my whole checkout flow and tell me what happened," or to keep a known-good trace.
 
 ```jsonc
-reticle_record {action:"start"}({ recordingName: "checkout" })
+reticle_run({ tool: "reticle_record", args: { action: "start", recordingName: "checkout" } })
 // …agent performs the flow (reticle_act, single or with steps)…
-reticle_record {action:"stop"}({ recordingName: "checkout" })
+reticle_run({ tool: "reticle_record", args: { action: "stop", recordingName: "checkout" } })
 // → {
 //     recordingName,
 //     program: { version, steps: [{ tool, args: { by:"testid", value, action, args }, stable }] },
@@ -650,7 +655,7 @@ reticle_record {action:"stop"}({ recordingName: "checkout" })
 //   }
 ```
 
-`reticle_record {action:"stop"}` returns a compiled, replayable `program`: the agent's `reticle_act` / `reticle_act { steps: [...] }` invocations captured during the span, with each ref normalized to its element's `data-testid` where resolvable. Re-run it later:
+`reticle_run { tool: "reticle_record", args: { action: "stop" } }` returns a compiled, replayable `program`: the agent's `reticle_act` / `reticle_act { steps: [...] }` invocations captured during the span, with each ref normalized to its element's `data-testid` where resolvable. Re-run it later:
 
 ```jsonc
 reticle_run({ tool: "reticle_replay", args: { recordingName: "checkout" } })
@@ -658,7 +663,7 @@ reticle_run({ tool: "reticle_replay", args: { recordingName: "checkout" } })
 // → { recordingName, ok, steps: [{ tool, ok, error?, note? }] }   // stops at the first failure
 ```
 
-**Limitation.** Normalization to a stable testid only works for elements that have a `data-testid`. A step whose element has none is stored in ref form (`stable: false`) and `reticle_record {action:"stop"}` returns a `warning`; replay best-effort re-uses the stored ref, which is only valid within the same live session and is not portable across reloads. Add `data-testid` to the elements you want replay-stable.
+**Limitation.** Normalization to a stable testid only works for elements that have a `data-testid`. A step whose element has none is stored in ref form (`stable: false`) and `reticle_run { tool: "reticle_record", args: { action: "stop" } }` returns a `warning`; replay best-effort re-uses the stored ref, which is only valid within the same live session and is not portable across reloads. Add `data-testid` to the elements you want replay-stable.
 
 ---
 
@@ -714,6 +719,7 @@ Reticle is cheap by design ([benchmark](token-efficiency.md)), but keep it that
 - **Always thread `since`.** Pass the cursor from `reticle_act` into `observe`/`assert` so you only consider what happened _after_ the action.
 - **Use `timeout_ms` for async.** Don't assert instantly on something that arrives over the network or after a re-render.
 - **Watch `session.throttled`.** Background tabs throttle timers/rAF/pointer gestures, so an act can silently no-op. Every `reticle_act` / `reticle_assert` / `reticle_act_and_wait` result carries `session: { lastSeenMs, throttled, focused }` and, when throttled, a `warning`. Refocus the tab (or run it foregrounded) before driving; pass `refuseWhenThrottled: true` to hard-fail instead.
+- **`ready` is connection, not hydration.** A session or lease answering `ready: true` has an SDK attached and answering; it does not mean the app finished hydrating. A slow-hydrating page (SvelteKit, Next) can still be mid-render, with controls not yet wired up, so an act issued immediately can miss. If reads come back empty (a `find` for buttons returns 0 matches and there are no console lines), that may mean not hydrated. Make the first act `reticle_act_and_wait` with an `until` on something hydration renders, or `reticle_assert { action: "wait" }`.
 - **Scope big pages.** On dashboards with hundreds of elements, scope queries to the panel you care about.
 - **Never breaks your app.** Observers are additive and reversible (`reticle.disconnect()` restores patched globals). It won't interfere with your app's behavior.
 
@@ -754,7 +760,7 @@ Each is a session; pass `sessionId` to any tool when more than one is connected
 ## 15. Security & privacy
 
 - **Dev-only, localhost-only by default.** The bridge binds `127.0.0.1`; the SDK is meant for dev builds.
-- **No app data leaves your machine.** Baselines/recordings are local. The CLI sends anonymous, opt-out usage metrics only (random id + event names, no code and no PII; see [telemetry](telemetry.md)); opt out with `reticle telemetry disable`, `RETICLE_TELEMETRY=0`, or `DO_NOT_TRACK=1`. Feedback you or your agent deliberately send (`reticle feedback` / `reticle_session { action: "feedback" }`) is the only free text that ever leaves the machine: never passive, redacted first, and separately disabled with `RETICLE_FEEDBACK=0`.
+- **No app data leaves your machine until you link a project.** Nothing from your app leaves the machine until you link a project (`reticle connect`, or `RETICLE_API_KEY` in CI). After that, what syncs is set by `reticle config`, and when the Harness (Reticle's model-driven explorer, which runs on the Reticle platform) drives, the platform sees the steps it drives. Secret values never leave. Baselines/recordings are local. The CLI sends anonymous, opt-out usage metrics only (random id + event names, no code and no PII; see [telemetry](telemetry.md)); opt out with `reticle telemetry disable`, `RETICLE_TELEMETRY=0`, or `DO_NOT_TRACK=1`. Feedback you or your agent deliberately send (`reticle feedback` / `reticle_session { action: "feedback" }`) is the only free text that ever leaves the machine: never passive, redacted first, and separately disabled with `RETICLE_FEEDBACK=0`.
 - **Network bodies aren't captured by default:** only method/url/status/timing. Body capture is opt-in and runs through a redactor (drop `password`/`token`/`secret`/… + your patterns).
 - **Additive & reversible.** Reticle patches `fetch`/History/console defensively and restores them on disconnect; it will not break the app under test.
 
@@ -809,21 +815,21 @@ All presenter DOM uses `data-reticle-*` and is excluded from snapshots/observers
 
 #### Session liveness: the HUD never gets stuck "running"
 
-A session starts on the agent's first activity and must reliably end even when the agent misbehaves. Reticle is an MCP tool, so the agent (Claude) can crash, disconnect, or simply forget to call `reticle_session {action:"end"}`, and a backgrounded tab's own timers are throttled by the browser. So **the Node server owns liveness, not the browser tab:**
+A session starts on the agent's first activity and must reliably end even when the agent misbehaves. Reticle is an MCP tool, so the agent (Claude) can crash, disconnect, or simply forget to call `reticle_session { action: "end" }`, and a backgrounded tab's own timers are throttled by the browser. So **the Node server owns liveness, not the browser tab:**
 
 - **Agent goes idle / forgets to end** → a server-side reaper (immune to tab throttling) ends the session after `idleEndMs` of no agent commands and pushes the end to the browser. A backgrounded tab still receives that push, so you can switch windows and come back to a correctly-ended HUD.
 - **Agent (MCP client) disconnects cleanly** → every active session ends at once.
 - **Agent kills the Reticle server process** (so no push can arrive) → the SDK self-ends the session after it can't reach the bridge for `BRIDGE_LOST_MS` (~15s), showing "lost connection to Reticle."
-- **Slow-but-alive agent** → if it goes quiet long enough to auto-end and then acts again, the session **revives** automatically (an explicit `reticle_session {action:"end"}` stays terminal).
+- **Slow-but-alive agent** → if it goes quiet long enough to auto-end and then acts again, the session **revives** automatically (an explicit `reticle_session { action: "end" }` stays terminal).
 
 Tune the idle window with `reticle_session({ action: "tune", idleEndMs })`; it updates both the browser timer and the server reaper. When the HUD covers a control you have to test, `reticle_session({ action: "tune", hud: "top-left" })` moves it (any corner), and `hud: "hidden"`, `"shown"` or `"removed"` (until the page reloads) take it out of the way; the call fails rather than pretending if the page could not apply it. The human keeps the panel (with Copy/Export of the run) after any end.
 
-### `reticle_session {action:"narrate"}`: show the agent's intent
+### `reticle_session { action: "narrate" }`: show the agent's intent
 
 So the human sees _what the agent is about to do and why_:
 
 ```jsonc
-reticle_session {action:"narrate"}({ text: "Adding a beat, then checking the section count goes up" })
+reticle_session({ action: "narrate", text: "Adding a beat, then checking the section count goes up" })
 ```
 
 It renders on the HUD. (The agent's private reasoning isn't visible to Reticle; narration is how it surfaces intent on the page.)
@@ -845,7 +851,7 @@ It does **not** freeze `requestAnimationFrame`/microtasks (React's scheduler kee
 ### Action refinements (from real-app use)
 
 - **`blur`** now fires a bubbling `focusout`, so React's commit-on-blur (`onBlur`) runs, and inline editors and form fields commit. `fill`/`type` focus first so a later `blur` commits.
-- **`hover`** accepts `{ holdMs }` to dwell, so timer-gated reveals mount; then `wait_for` the revealed nodes.
+- **`hover`** accepts `{ holdMs }` to dwell, so timer-gated reveals mount; then `reticle_assert { action: "wait" }` for the revealed nodes.
 - **`drag`** yields a frame between phases (React flushes between steps) and accepts `{ data: { mime, value } }` for custom `dataTransfer` payloads.
 
 ### Richer `dataMatches` (signals)
@@ -1027,7 +1033,7 @@ reticle_run({ tool: "reticle_capabilities", args: {} })   // → { testids, sign
 
 ### `reticle_replay`: recordings become re-runnable programs
 
-`reticle_record {action:"start"}` → drive the flow → `reticle_record {action:"stop"}` returns a **compiled program** (steps bound to testids/signals, not volatile refs). `reticle_replay({ recordingName })` re-executes it, so your flow becomes a deterministic regression run, not a checklist.
+`reticle_run { tool: "reticle_record", args: { action: "start" } }` → drive the flow → `reticle_run { tool: "reticle_record", args: { action: "stop" } }` returns a **compiled program** (steps bound to testids/signals, not volatile refs). `reticle_run({ tool: "reticle_replay", args: { recordingName } })` re-executes it, so your flow becomes a deterministic regression run, not a checklist.
 
 ---
 
@@ -1089,6 +1095,6 @@ That's it. Reticle correlates the CDP page to your SDK session by URL; pointer a
 
 > **SPA navigation is handled.** The URL correlation tracks client-side route changes (`pushState`/`replaceState`/`popstate`), so real input keeps working after your app navigates into a sub-route, e.g. the hover/quick-edit cluster on a `/workspace` view stays drivable. (If you see `inputModeReason:"page-not-correlated-to-a-cdp-target"`, the reported session URL isn't correlated to a CDP target and real input silently falls back to synthetic.)
 
-> **Watching the agent (presenter).** With `present: true` the activity border now glows once while the agent is busy and fades when idle (no per-action strobe); the HUD sits **bottom-center**, shows a **READING** vs **ACTING** chip so you can tell observation from action at a glance, and `reticle_session {action:"narrate"}` lines are **queued** with a minimum on-screen dwell so none flash by unread.
+> **Watching the agent (presenter).** With `present: true` the activity border now glows once while the agent is busy and fades when idle (no per-action strobe); the HUD docks **bottom-right** by default, shows a **READING** vs **ACTING** chip so you can tell observation from action at a glance, and `reticle_session { action: "narrate" }` lines are **queued** with a minimum on-screen dwell so none flash by unread.
 
-> **Limitation: un-scriptable tabs.** Reticle observes/drives a tab through the in-page SDK + (optionally) CDP; it **cannot bring to front or recover a browser tab the OS won't let it script** (e.g. a backgrounded or non-default-browser tab reporting `hidden:true`/`throttled:true`). When that happens, `reticle_session { action: "list" }` and every act/assert result carry a `session.recommendation` saying so and pointing to `reticle drive <url>` for a guaranteed scriptable context. Refocus the tab, or use `reticle drive`.
+> **Limitation: un-scriptable tabs.** Reticle observes/drives a tab through the in-page SDK + (optionally) CDP; it **cannot bring to front or recover a browser tab the OS won't let it script** (e.g. a backgrounded or non-default-browser tab reporting `hidden:true`/`throttled:true`). When that happens, `reticle_session { action: "list" }` and every act/assert result carry a `session.recommendation` saying so. For a hidden tab it points to `reticle_run { tool: "reticle_lease", args: { action: "acquire", url } }` (or `reticle drive <url>` for a human) for a guaranteed scriptable context. Refocus the tab, or lease one.

package/docs/use-cases.mdx

@@ -67,7 +67,7 @@ Reticle finds elements the way assistive technology does: by role and accessible
 - **The keyboard works.** `press` with `Enter` or `Escape` fires the control's action, not just a mouse click. The [verify-keyboard-access](https://github.com/reticlehq/reticle/tree/main/skills/verify-keyboard-access) skill walks through it.
 - **Visible, enabled, checked, expanded, pressed and in-viewport** are all element states you can assert.
 
-A synthetic Tab key does not move focus in a browser, so Reticle cannot verify Tab order, and it reports that as unknown rather than as a pass.
+A synthetic Tab key does not move focus in a browser, so Reticle cannot verify Tab order. Report Tab order as unknown, never as a pass.
 
 Open the "Delete project" dialog with `press` (`args: { "text": "Enter" }`) and require focus to move into it:
 
@@ -122,8 +122,8 @@ After navigating to the old `/plans` URL, require the redirect and the page's ma
 
 ## Personas and simulation
 
-- **Drive the app as a user.** `explore` takes a persona in plain words, drives that whole journey with a model inside the daemon, and saves what it drove as a flow that later replays with no model.
-- **One context per role.** `reticle_lease { action: "acquire" }` opens an isolated browser context (its own cookies, storage and DOM) and can seed storage or cookies first, so an admin and a viewer drive the same app side by side. Reach it with `reticle_run`, or use `reticle verify <url> --storage-state <file>` from a terminal.
+- **Drive the app as a user.** `explore` takes a persona in plain words, drives that whole journey with the Harness, Reticle's model-driven explorer, which runs on the Reticle platform (run `reticle connect` first; a new account gets 10 free credits), and saves what it drove as a flow that later replays with no model.
+- **One context per role.** `reticle_run { tool: "reticle_lease", args: { action: "acquire" } }` opens an isolated browser context (its own cookies, storage and DOM) and can seed storage or cookies first, so an admin and a viewer drive the same app side by side. Reach it with `reticle_run`, or use `reticle verify <url> --storage-state <file>` from a terminal.
 - **Reachability testing.** Signed in as a role, a control that role must not have is absent, and the call behind it never fires. `reticle_verify { action: "coverage" }` lists the controls you have and have not driven this session.
 - **Multi-agent runs.** Several agents lease contexts from one shared headless Chromium, capped and queued, instead of starting a browser each. See [Multi-agent](/multi-agent-testing).
 

package/docs/vs-chrome-devtools-mcp.mdx

@@ -17,6 +17,8 @@ Same app, same bugs, same moment:
 | Avg tokens per look     | 815       | **758**             |
 | Verification efficiency | **12.27** | 10.55               |
 
+Measured on 2026-06-22 against `chrome-devtools-mcp@1.3.0`; DevTools MCP has shipped since, and this pass has not been re-run.
+
 DevTools MCP genuinely wins the cost column. We are not going to bury that. 758 against 815 is a real 7% advantage per observation, and if you are making a very large number of trivial looks it adds up.
 
 But cost per look is only half a metric. Verification efficiency combines both. Regressions caught per 1,000 tokens spent, gated on catching **all** of them with zero false alarms on a known-good control. On that measure Reticle leads 12.27 to 10.55.
@@ -45,7 +47,7 @@ Note the flip. DevTools is cheaper on a small page and more expensive on a large
 
 DevTools MCP is DOM-and-network only. It can describe what a page looks like and what it requested; it cannot ask the application what it believes.
 
-That is why the misses cluster where they do. The scenarios that separate the tools are the ones where the page is fine and the program is not. A mutation that never reached the store, a success handler that fired for the wrong reason. There is nothing in the DOM or the network log that distinguishes those from working code.
+The benchmark record keeps per-tool totals, not which two scenarios DevTools MCP missed. The class it structurally cannot reach is the one where the page is fine and the program is not. A mutation that never reached the store, a success handler that fired for the wrong reason. There is nothing in the DOM or the network log that distinguishes those from working code.
 
 Reticle can require the app's own signal:
 
@@ -86,11 +88,12 @@ Neither tool forbids the other. A reasonable setup:
 <AccordionGroup>
 
 <Accordion title="Which two bugs did Chrome DevTools MCP miss?">
-  The ones where the page is fine and the program is not: a mutation that never reached the store,
-  and a success handler that fired for the wrong reason. DevTools MCP is DOM-and-network only, so it
-  can describe what the page looks like and what it requested, but it cannot ask the application
-  what it believes. There is nothing in the DOM or the network log that separates those cases from
-  working code.
+  The benchmark record keeps per-tool totals, not the two scenarios by name. The class it cannot
+  reach is the one where the page is fine and the program is not, such as a mutation that never
+  reached the store, or a success handler that fired for the wrong reason. DevTools MCP is
+  DOM-and-network only, so it can describe what the page looks like and what it requested, but it
+  cannot ask the application what it believes. There is nothing in the DOM or the network log that
+  separates those cases from working code.
 </Accordion>
 
 <Accordion title="If DevTools MCP is cheaper, why not just use it?">

package/docs/vs-playwright-mcp.mdx

@@ -15,6 +15,8 @@ That single architectural choice explains every difference below. An outside-in
 
 ## Measured, on the same app at the same moment
 
+These passes last ran on 2026-06-22, against `@playwright/mcp@0.0.76`. Both tools have shipped since, so treat the numbers as dated.
+
 |                         | Reticle   | Playwright MCP |
 | ----------------------- | --------- | -------------- |
 | Bugs caught (of 10)     | **10**    | 9              |
@@ -49,7 +51,7 @@ This is not a courtesy section. There are real cases where Playwright is the cor
 - **Assert on the app's own success signal.** When your app emits `auth:granted`, Reticle can require that exact signal. Playwright can check that a DOM element appeared, which a mock also does.
 - **Read application state.** `stateDiffs` shows `auth` moving from `null` to a real user. A POST that returns `200` without touching state is caught here and nowhere else.
 - **Map a DOM node to source.** `src/components/Login.tsx:81`, via the React fiber tree. Playwright can tell you the selector; it cannot tell you the file.
-- **Grade its own evidence.** Every verdict reports `honesty.grade`: `presence`, `state`, `net` or `signal`, weakest to strongest. Plus whether the capture was clean and complete.
+- **Grade its own evidence.** An `act_and_wait` verdict reports `honesty.grade`: `none`, `presence`, `state`, `net` or `signal`, weakest to strongest. Plus whether the capture was clean and complete.
 - **Say "unknown".** Reticle distinguishes "did not happen" from "I could not tell". That third state is the difference between a check and a coin flip.
 
 ## The false-green case

package/docs/what-is-recorded.md

@@ -5,7 +5,7 @@ description: What Reticle keeps on your machine, what is redacted, and what it t
 
 Reticle drives your app and reads what it did. That means it holds real content from real pages, so this page says exactly what it keeps, where it keeps it, and what it takes to make any of it leave.
 
-If you read one line: **a verdict is entirely local and needs no account.** Nothing from your project is sent anywhere until you run `reticle login` and `reticle link`. Without them there is nowhere for it to go. (Anonymous usage counts, which carry nothing from your app, are separate and described in [Telemetry](telemetry.md).)
+If you read one line: **a verdict is entirely local and needs no account.** Nothing from your app leaves the machine until you link a project (`reticle connect`, or `RETICLE_API_KEY` in CI). After that, what syncs is set by `reticle config`, and when the Harness drives, the platform sees the steps it drives. Secret values never leave. (Anonymous usage counts, which carry nothing from your app, are separate and described in [Telemetry](telemetry.md).)
 
 ## On your machine
 
@@ -27,11 +27,11 @@ Everything lands in `.reticle/` in your project, and it is yours. Three kinds of
 
 So: **drive staging.** Not because the risk is large, but because it is real and avoiding it is free.
 
-Network bodies are **not** captured by default. When you turn body capture on (`captureNetworkBodies: true`, or `VITE_RETICLE_CAPTURE_BODIES=1`), redaction runs **before each body is kept**. Built-in rules mask keys such as `password`, `apiKey` and `authorization`, selected token keys, and high-confidence secret shapes such as JWTs and `sk_live_…` keys. Other credential values can remain under names or in formats those rules do not recognize; add app-specific field names with `redact.keys` and use staging. Page content that reaches a verdict is the element text and attributes the assertion needed, not a copy of the DOM.
+Network bodies are **not** captured by default, with one exception: the response body of a failed request (HTTP 400 and up, at most 4 KB) is kept, because it says why the request failed. `captureErrorBodies: false` turns that off too. When you turn body capture on (`captureNetworkBodies: true`, or `VITE_RETICLE_CAPTURE_BODIES=1`), redaction runs **before each body is kept**. Built-in rules mask keys such as `password`, `apiKey` and `authorization`, selected token keys, and high-confidence secret shapes such as JWTs and `sk_live_…` keys. Other credential values can remain under names or in formats those rules do not recognize; add app-specific field names with `redact.keys` and use staging. Page content that reaches a verdict is the element text and attributes the assertion needed, not a copy of the DOM.
 
 ## What leaves, only if you ask
 
-`reticle login` signs this machine in. `reticle link` binds one repo to one cloud project. Until both have happened, or `RETICLE_API_KEY` is set in the environment, `reticle push` has nothing to talk to and the sync path is a no-op. The code calls this the no-phone-home default. A key in the environment is how CI syncs with no login and no link, and it goes to the hosted service unless `RETICLE_CLOUD_URL` names another host.
+`reticle connect` signs this machine in and binds one repo to one cloud project. Until that has happened, or `RETICLE_API_KEY` is set in the environment, `reticle sync` has nothing to talk to and the sync path is a no-op. The code calls this the no-phone-home default. A key in the environment is how CI syncs with no login and no link, and it goes to the hosted service unless `RETICLE_CLOUD_URL` names another host.
 
 Once linked, you choose what syncs:
 
@@ -43,9 +43,9 @@ npx @reticlehq/server config --runs on|off --flows on|off --memory on|off
 
 The Harness runs on the platform, so the platform sees what it drives: each step's result goes there so it can choose the next one. A secret field is sent by name only; its value is typed in on your machine.
 
-**Your apps, for the platform's chat.** While a project is linked, the daemon tells the platform every ten seconds, with or without an app open, which apps on this machine have Reticle connected, so the chat can list them and you can pick one instead of typing an address. For each app it sends: a key made from a hash of this machine and the project's folder (the folder path itself never leaves), the project's name (its package name, else its folder's name), the address the app is open at with Reticle's own query parameters removed, the page title, what it is built with (`react`, `vite`, `electron`, …), this machine's name, the Reticle version, and what this daemon can do for the platform. The platform keeps the last report for each app until the project is deleted. Its answer can ask this machine to open one of those apps again, or show you a short notice (for example, to update Reticle), which appears in the daemon's log and on the HUD.
+**Your apps, for the platform.** While a project is linked, the daemon tells the platform every ten seconds, with or without an app open, which apps on this machine have Reticle connected, so the dashboard can show which apps are live. For each app it sends: a key made from a hash of this machine and the project's folder (the folder path itself never leaves), the project's name (its package name, else its folder's name), the address the app is open at with Reticle's own query parameters removed, the page title, what it is built with (`react`, `vite`, `electron`, …), this machine's name, the Reticle version, and what this daemon can do for the platform. The platform keeps the last report for each app until the project is deleted. Its answer can ask this machine to open one of those apps again, or show you a short notice (for example, to update Reticle), which appears in the daemon's log and on the HUD.
 
-**Drives asked for from the platform's chat.** When someone in your workspace asks the chat to drive one of your apps, the daemon drives it here, on your machine: in the tab you have open, or in a browser of its own, headless or in a window, as the chat asked. It only opens addresses on this machine or apps already open here. On a recent platform, the platform decides each step: it sends Reticle tool calls from a fixed list (reading the page, acting on it, asserting, recording and replaying flows), the daemon runs them in that one tab, and sends back what each returned, which includes what the page showed. On an older platform, the daemon drives and sends back each step's result and how the drive ended. Either way the platform keeps the drive as a check you can open in Runs. Unless the request said not to record, the daemon also sends a picture of the tab it is driving, a JPEG about once a second, so the chat can show the drive live and replay it afterwards. Pictures are kept with that check (at most a few minutes' worth per drive) and deleted with the project. A tab the daemon opened, headless or in a window, can be pictured, with Reticle's own panel left out; so can the window `reticle drive` opened, which is pictured as you see it, panel included. A tab in your own browser sends steps only. Unlinking the project stops all of it.
+**Drives asked for from the platform (older platforms).** To test an app on your machine, press Run Harness in its HUD or ask your coding agent; the dashboard chat no longer starts drives here. An older platform can still ask: when someone in your workspace asked its chat to drive one of your apps, the daemon drives it here, on your machine: in the tab you have open, or in a browser of its own, headless or in a window, as the chat asked. It only opens addresses on this machine or apps already open here. On a recent platform, the platform decides each step: it sends Reticle tool calls from a fixed list (reading the page, acting on it, asserting, recording and replaying flows), the daemon runs them in that one tab, and sends back what each returned, which includes what the page showed. On an older platform, the daemon drives and sends back each step's result and how the drive ended. Either way the platform keeps the drive as a check you can open in Runs. Unless the request said not to record, the daemon also sends a picture of the tab it is driving, a JPEG about once a second, so the chat can show the drive live and replay it afterwards. Pictures are kept with that check (at most a few minutes' worth per drive) and deleted with the project. A tab the daemon opened, headless or in a window, can be pictured, with Reticle's own panel left out; so can the window `reticle drive` opened, which is pictured as you see it, panel included. A tab in your own browser sends steps only. Unlinking the project stops all of it.
 
 ## Telemetry, which is separate from all of the above
 
@@ -61,6 +61,8 @@ Telemetry carries no free text. Free text leaves in three ways, each one somethi
 
 The daemon also fetches a small public file, `https://reticle.sh/hud/notices.v1.json`, for the notices in the HUD's rail. The request carries nothing about you or your project. `RETICLE_TELEMETRY=0` or `DO_NOT_TRACK=1` stops it, and `RETICLE_HUD_NOTICES_URL` points it elsewhere.
 
+The one-line installer fetches one public file too, `https://reticle.sh/install/agent-prompt.v1.json`: the prompt it prints for you to paste into your coding agent. It is a plain GET with a three-second timeout that sends nothing about you, your machine or your project. The installer checks the file (a JSON object whose `prompt` is text of at most 4000 characters), removes every control character but the newline, and only prints it; nothing in it is ever run. If the fetch is off, fails or the file does not pass, it prints the copy it carries instead. The same `RETICLE_TELEMETRY=0` or `DO_NOT_TRACK=1` stops the fetch, and `RETICLE_AGENT_PROMPT_URL` points it elsewhere.
+
 ## What `init` writes to your project
 
 Run it with `--dry-run` and it prints the whole plan without writing anything:

package/docs/what-is-reticle.mdx

@@ -15,7 +15,7 @@ It exists because an agent that writes code cannot otherwise tell whether that c
 2. **A local bridge.** The SDK connects over a WebSocket to a daemon on your machine, bound to `127.0.0.1`. The daemon never manages your dev server; it attaches to the app that is running. On first setup, `npx @reticlehq/server init` starts the dev server with your project's own dev script and opens the app.
 3. **An MCP server.** The daemon exposes the app to your agent as tools. `reticle_look` to look, `reticle_act_and_wait` to act and prove in one call, `reticle_observe` to read what the app did, `reticle_assert` to check.
 
-Your app's data stays on your machine: no application code, DOM, network traffic, state or console output leaves it. Anonymous usage counts are sent by default and can be [turned off](/telemetry).
+Your app's data stays on your machine until you link a project: before that, no application code, DOM, network traffic, state or console output leaves it, and once linked, what syncs is your choice ([What is recorded](/what-is-recorded)). Anonymous usage counts are sent by default and can be [turned off](/telemetry).
 
 ## Where it fits
 
@@ -42,7 +42,7 @@ Reticle sits next to several familiar categories, and it works alongside each of
 - **A web application you can run**, with a dev build. `init` starts its dev server for you.
 - **A build step it can hook**, or two lines added by hand. [Frameworks](/frameworks) lists what is proven for each.
 - **An agent that speaks MCP.** Claude Code, Cursor, Codex, Copilot, Windsurf, OpenCode and others.
-- **Node 20 or newer.**
+- **Node 20.11 or newer.**
 
 Electron and Tauri desktop applications are supported, including the IPC boundary a browser-based tool cannot observe at all.
 

package/docs/why-reticle.mdx

@@ -72,7 +72,7 @@ On raw cost per glance, Chrome DevTools MCP is cheaper: 758 tokens against 815.
 
 We ran a fix-loop ablation: agents fixed 8 bugs injected into a small fixture app, with Reticle and without it, on a strong model and on a weaker one. **It did not show a fix-rate improvement at either tier.** The strong model fixed 8 of 8 in both conditions and the weaker one 7 of 8 in both, and the Reticle arm made roughly five to six times the tool calls, because driving an app costs more than reading a few short files.
 
-The test cannot settle the question in either direction, and the reasons are specific: the fixture is small enough to read whole, several injected bugs were labelled by a comment on the changed line, and "fixed" was checked by a string disappearing rather than by the app behaving. One case pointed each way. The weaker model without Reticle claimed a fix it never applied, and the live re-check caught that with Reticle; with Reticle, the same model over-edited a stylesheet the string check scored as a pass. The full log is in [`bench/fix-loop/results.md`](https://github.com/reticlehq/reticle/blob/main/bench/fix-loop/results.md).
+The test cannot settle the question in either direction, and the reasons are specific: the fixture is small enough to read whole, several injected bugs were labelled by a comment on the changed line, and "fixed" was checked by a string disappearing rather than by the app behaving. One case pointed each way. The weaker model without Reticle claimed a fix it never applied, and the live re-check caught that with Reticle; with Reticle, the same model over-edited a stylesheet the string check scored as a pass. The full log is in [`bench/fix-loop/results.md`](https://github.com/reticlehq/reticle/blob/ffe58e32a5b5860869be8b164ad68bb5d23d69e9/bench/fix-loop/results.md), kept in git history since the benchmark was retired.
 
 A separate, smaller measurement of the source pointer alone found the same fix rate with and without it (6 of 6) and fewer tool calls with it (12 against 22). The pointer removed the search; it did not make the agent more capable.
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@reticlehq/server",
-  "version": "3.6.0",
+  "version": "3.7.0",
+  "mcpName": "io.github.reticlehq/reticle",
   "description": "Reticle CLI, bridge and MCP server: a coding agent drives your running web app from the inside and gets a verdict with evidence, for change verification, access control, accessibility, performance and SEO checks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,11 +24,11 @@
     "ws": "^8.21.3",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.24.0",
-    "@reticlehq/browser": "3.6.0",
-    "@reticlehq/core": "3.6.0",
-    "@reticlehq/engine": "3.6.0",
+    "@reticlehq/browser": "3.7.0",
+    "@reticlehq/engine": "3.7.0",
     "open-verification": "1.0.0",
-    "@reticlehq/init": "3.6.0"
+    "@reticlehq/core": "3.7.0",
+    "@reticlehq/init": "3.7.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",