@reticlehq/server 2.8.0 → 2.10.0

package/docs/tools-wait-for.mdx

@@ -4,13 +4,15 @@ description: Block until a predicate holds. Or return immediately if it is alrea
 icon: hourglass
 ---
 
-`reticle_wait_for` takes the same predicate grammar as [`reticle_act_and_wait`](/tools-act-and-wait), without the action. Use it when the thing you are waiting for was triggered by something other than your own click. A timer, a websocket push, a background refresh.
+`reticle_wait_for` blocks until a predicate holds, or returns straight away if it is already satisfied in the recent event buffer. Reach for it when you are waiting on something you did not cause. It reads and waits; it does not produce a verdict, so finish with [`reticle_assert`](/tools-assert).
+
+It takes the same predicate grammar as [`reticle_act_and_wait`](/tools-act-and-wait), without the action. Use it when the thing you are waiting for was triggered by something other than your own click. A timer, a websocket push, a background refresh.
 
 ## Example
 
 ```json
 {
-  "predicate": { "kind": "text", "value": "Invalid email or password" },
+  "predicate": { "kind": "text", "contains": "Invalid email or password" },
   "timeout_ms": 3000
 }
 ```
@@ -22,12 +24,12 @@ Real response:
   "pass": true,
   "evidence": [
     {
-      "ref": "e104",
+      "ref": "e606",
       "role": "alert",
       "name": "Invalid email or password",
-      "visible": false,
+      "visible": true,
       "source": "src/components/Login.tsx:72",
-      "states": ["present", "hidden", "enabled"]
+      "states": ["present", "visible", "enabled"]
     }
   ]
 }
@@ -36,31 +38,48 @@ Real response:
 The evidence is the element itself, with the file and line that rendered it.
 
 <Note>
-  Look at `visible: false` and `states: ["present", "hidden", "enabled"]`. The alert exists in the
-  DOM and is not visible. `wait_for` on a `text` predicate matches presence, if you need it on
-  screen, that is a different question, and [`reticle_inspect`](/tools-inspect) answers it.
+  A `text` predicate matches **presence** by default, so an element that is in the DOM but hidden
+  satisfies it and comes back with `visible: false` and `states: ["present", "hidden", "enabled"]`.
+  If you need it on screen, say so: `{ "kind": "text", "contains": "…", "visible": true }`.
 </Note>
 
+The field is `contains`. `value` and `text` are accepted as aliases and rewritten to it, but `contains` is what the published schema declares.
+
 ## It checks the buffer first
 
 `wait_for` does not always wait. If the predicate is already satisfied in the recent event buffer, it returns immediately. This means you can act, then wait, without racing. The event that happened while you were composing the second call is not lost.
 
 ## Arguments
 
-| Argument | What it does |
-| --- | --- |
-| `predicate` (or `until`) | `{ kind, ...fields }`, see the [predicate grammar](/tools-act-and-wait) |
-| `timeout_ms` | Maximum wait |
-| `since` | Cursor from a prior act, to scope the wait |
+| Argument                 | What it does                                                      |
+| ------------------------ | ----------------------------------------------------------------- |
+| `predicate` (or `until`) | `{ kind, ...fields }`, see the [predicate reference](/predicates) |
+| `timeout_ms`             | Maximum wait. Default 4000                                        |
+| `since`                  | Cursor from a prior act, to widen or narrow the window explicitly |
+
+By default the wait only counts events since your last act, so a signal that fired before the action cannot satisfy it. A miss returns a near-miss diagnosis rather than a bare `false`:
+
+```json
+{
+  "pass": false,
+  "failureReason": "no element matched {\"text\":\"Deployments\"}",
+  "observed": "no matching element on the page",
+  "expected": "an element matching {\"text\":\"Deployments\"}",
+  "assertion": "element.present",
+  "evidence": { "presentTestids": ["login-email", "login-password", "login-submit"] }
+}
+```
+
+`presentTestids` there is the answer to the real question. The text was missing because the app had logged out, not because the render was slow.
 
 ## Prefer `act_and_wait` when you caused it
 
 If your own action is supposed to trigger the thing, put the predicate in the action:
 
 ```json
-{ "ref": "e103", "action": "click", "until": { "kind": "signal", "name": "auth:granted" } }
+{ "ref": "e605", "action": "click", "until": { "kind": "signal", "name": "auth:granted" } }
 ```
 
-One call instead of two, no gap for an event to slip through, and. The part that matters. The expectation is recorded _before_ the action rather than chosen after it.
+One call instead of two, no gap for an event to slip through, and, the part that actually matters, the expectation is recorded _before_ the action rather than chosen after it.
 
 Save `wait_for` for consequences you did not cause.

package/docs/troubleshooting.mdx

@@ -1,10 +1,14 @@
 ---
-title: Troubleshooting: it worked on my tab
+title: 'Troubleshooting: it worked on my tab'
 sidebarTitle: Troubleshooting
 description: Nothing connected, the click did nothing, the verdict says unknown. The failures people actually hit, and the diagnostic for each.
 icon: stethoscope
 ---
 
+**Run `npx @reticlehq/server doctor` first.** It checks Chromium, the daemon, the port and the connected sessions in one command, and it names the problem in most cases. If `sessions` reads zero, your app is not reaching the bridge, and a port mismatch is the usual reason.
+
+Reticle is a verification layer that runs a dev-only SDK inside your running web app. Two halves have to be working: your agent needs the MCP server registered, and your app needs the SDK connected to the local daemon. Almost every failure below is one of those two halves being absent.
+
 Most of these were hit while writing these docs. The diagnostics quoted are real output.
 
 ## Start here
@@ -17,7 +21,7 @@ npx @reticlehq/server doctor
 reticle doctor
   node         v22.14.0
   chromium     ✓ installed
-  daemon       ✓ running on :4400 (pid 24735, v2.8.0)
+  daemon       ✓ running on :4400 (pid 24735, v<the version you have>)
   sessions     ✓ 1 page connected
   bridge port  4400  (your app must dial THIS port, not your dev-server port)
   daemon log   /Users/you/.reticle/daemon-4400.log
@@ -35,30 +39,51 @@ By far the most common. Reticle's own diagnostic is unusually good here. It tell
 ```json
 {
   "sessionCount": 0,
-  "why": "no browser session connected, but one WAS connected to this daemon earlier, so the wiring is correct. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen the app (or run `reticle open`), or reload the tab. You do not have to wait for the human: reticle_lease {action:\"acquire\", url} opens a browser Reticle drives itself."
+  "why": "no browser session connected, but one WAS connected to this daemon earlier, so the wiring is correct. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen the app (or run `reticle open`), or reload the tab. You do not have to wait for the human: reticle_lease {action:\"acquire\", url} opens a browser Reticle drives itself, and returns a sessionId you can use immediately (reach it with reticle_run {tool:\"reticle_lease\"} if it is not advertised directly; release it when you finish). Then call reticle_sessions again."
 }
 ```
 
-Read the `why`. "One WAS connected earlier" means stop debugging your config, just reopen the tab.
+Read the `why`. If it says one **was** connected earlier, stop debugging your config and just reopen the tab. If it says nothing ever connected, the wiring itself is wrong, so work through the list below.
 
 If nothing ever connected:
 
-- Is the app running, and open in a browser?
+- Is the app running, and open in a browser? If nothing is serving it, see [Who starts the dev server](#who-starts-the-dev-server): this is the agent's job, not a question to put to you.
 - Is `reticle.connect()` actually executing? Check the dev guard is true.
 - **Port mismatch.** This is the big one.
 
+### Who starts the dev server
+
+**The agent does.** If no dev server is listening, the agent reads your project's own dev script out of `package.json`, runs it in the background, tells you in one line that it is running and how to stop it, and carries on. It used to be told the opposite, "Reticle never starts the dev server for you, that's your job", and agents obeyed it exactly: they read the rule, declined to start anything, and ended the turn with nothing verified.
+
+The daemon still does not do it, on purpose. A build process started by a long-lived background daemon is invisible to whoever's machine it is running on, was never consented to, cannot easily be stopped, and orphans when the daemon exits. It would also mean a piece of standing infrastructure runs arbitrary `package.json` scripts. An agent already has shell access in your repo, already runs install and build commands, and runs inside a host that asks you before it does. A dev server the agent starts is in the transcript, attributable to a step you approved, and stoppable.
+
+The agent does not have to work out the command. When `reticle_sessions` comes back with nothing connected, it carries a `next_action` naming which of four cases this is and, where one applies, the literal command and port: start the dev server, run `reticle init`, open the app, or reopen a tab that went away. The command is read from this project's own scripts, so a project with no recognisable dev script gets no command rather than a guess.
+
+The guards, which apply wherever this instruction appears:
+
+1. **Never start a second one.** If something is already listening on the app's port, it is adopted.
+2. **Never guess the command.** It comes from `package.json` scripts. If there is no recognisable dev script, the agent says so and stops rather than inventing one.
+3. **Never kill anything**: not a dev server, not a daemon, not a port holder, including one it started.
+4. **Background it, and say so.** You must know a server is running and how to stop it. A dev server you do not know about is the same failure one step later.
+5. **The permission prompt is your agent host's.** Nothing in Reticle bypasses or auto-approves it, and you can always decline.
+
+The corollary matters as much: if a dev server IS already running and nothing connects, the cause is the SDK not loading in the page. An agent that answers this state by asking you to start a server you are already running has ended the conversation with nothing fixed. Work the checklist above instead.
+
 ### The port mismatch
 
 Your app dials a port; the daemon listens on one. When they disagree, the app runs perfectly and silently never connects. The browser console says so:
 
 ```
-[Reticle] could not reach the bridge at ws://localhost:4460/reticle after 3 attempts.
-Is the Reticle daemon running on that port? If your app runs in a container/devcontainer/WSL,
-the daemon is on a different host, so set the WS URL explicitly
-(Vite: VITE_RETICLE_WS_URL, or reticle.connect({ url })). Still retrying…
+[Reticle] this page could not open a websocket to ws://localhost:4460/reticle. 3 attempts, all
+failed. That is everything the page can see: from inside the browser it cannot tell a daemon that
+is not there from one it is not allowed to reach, so this is not evidence about the daemon. What
+answers it: run `npx @reticlehq/server status` to see whether one is listening and on which port.
+If your app runs in a container, devcontainer or WSL, the daemon is on a different host, so set
+the URL explicitly (Vite: VITE_RETICLE_WS_URL, or reticle.connect({ url })). An https page cannot
+open a ws:// socket at all. Still retrying…
 ```
 
-That message names the exact port it tried. Compare it with `bridge port` from `doctor` and set the one that is wrong:
+That message names the exact address it tried. Compare its port with `bridge port` from `doctor` and set whichever is wrong:
 
 ```bash
 VITE_RETICLE_WS_URL=ws://localhost:4400/reticle pnpm dev
@@ -188,6 +213,51 @@ Stale sessions pointing at dev servers you restarted an hour ago look completely
 
 `reticle_session { action: "end" }` when you are done, `{ action: "yield" }` when pausing. Both revive on your next action.
 
+## Frequently asked questions
+
+<AccordionGroup>
+  <Accordion title="Why does reticle_sessions return nothing when my app is clearly running?">
+    Your app running is not the same as your app being connected. The SDK has to dial the daemon's
+    bridge port over a WebSocket. If `npx @reticlehq/server doctor` shows the daemon up and
+    `sessions` at zero, either `reticle.connect()` never executed (check the dev guard is actually
+    true) or the app dialled the wrong port. The browser console names the exact address it tried.
+  </Accordion>
+
+<Accordion title="Which port should my app dial?">
+  The bridge port, which defaults to `4400`. It is **not** your dev-server port. A dev server on
+  4312 and a daemon on 4400 is the normal, correct arrangement. `doctor` prints the bridge port
+  under `bridge port`.
+</Accordion>
+
+<Accordion title="I restarted my agent and the reticle tools still are not there.">
+  If you registered the MCP server while the agent was running, restart the agent process itself:
+  quit and reopen Claude Code, reload the window in Cursor, or press Start in `.vscode/mcp.json` in
+  VS Code. `/mcp` only manages servers that were already loaded, so it cannot discover a new one. If
+  the tools are still missing, run `claude mcp list` and check `reticle` is present.
+</Accordion>
+
+<Accordion title="Does a verdict of unknown mean the test failed?">
+  No, and it does not mean it passed either. `verified: "unknown"` means Reticle drove the app and
+  could not tell what happened, usually because the page never settled inside the observation
+  window. Report it as unknown. If you hit one on an unthrottled context and believe it is wrong,
+  that is a Reticle defect worth sending with `reticle_feedback`.
+</Accordion>
+
+<Accordion title="Is it safe to kill port 4400 to restart things?">
+  No. `lsof -ti tcp:4400 | xargs kill -9` matches your agent's MCP proxy as well as the daemon and
+  takes the connection down with it. Use `npx @reticlehq/server stop`, or at minimum add
+  `-sTCP:LISTEN` so only the listener matches.
+</Accordion>
+
+  <Accordion title="Why does my agent click a button and nothing happens?">
+    Check the response for a `warning` about a throttled tab. A backgrounded browser tab has its
+    timers suppressed, so synthetic pointer gestures can silently no-op while the action still
+    reports success. Drive a lease instead, which is a context Reticle owns and never backgrounds.
+    If the tab is fine, check `occluded` on the element: a click landing on a modal overlay looks
+    identical from the outside.
+  </Accordion>
+</AccordionGroup>
+
 <Card title="Still stuck?" icon="comments" href="/tools-session-and-feedback">
   `reticle feedback --agent` works even when nothing is installed and the daemon will not start.
 </Card>

package/docs/usage.md

@@ -4,7 +4,9 @@ description: 'The full reference and cookbook: every tool, flag, and workflow, w
 icon: book
 ---
 
-The full reference and cookbook. If you haven't set up Reticle yet, start with [Getting Started](getting-started.md).
+Every Reticle drive is the same four steps: **look** (`reticle_snapshot` / `reticle_query`), **act** (`reticle_act` / `reticle_act_sequence`), **observe** (`reticle_observe` / `reticle_network` / `reticle_state`), **assert** (`reticle_assert`). Only `reticle_act_and_wait` and `reticle_assert` produce a verdict, 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.
+
+If you haven't set up Reticle yet, start with [Getting Started](getting-started.md).
 
 > **Start here instead, unless you want the long form.** This page predates the focused reference and still holds the fullest single narrative, but almost everything in it now has a page of its own that is shorter, searchable and verified against a running app:
 >
@@ -41,6 +43,9 @@ The full reference and cookbook. If you haven't set up Reticle yet, start with [
 13. [Best practices & gotchas](#13-best-practices--gotchas)
 14. [FAQ](#14-faq)
 15. [Security & privacy](#15-security--privacy)
+16. [Presenter mode, narration & fake clock](#16-presenter-mode-narration--fake-clock-watch--control)
+17. [Evidence-of-effect, act+await, state, capabilities, replay](#17-evidence-of-effect-actawait-state-capabilities-replay)
+18. [Real input mode: native hover & drag](#18-real-input-mode-native-hover--drag)
 
 ---
 
@@ -86,7 +91,7 @@ List connected tabs. → `{ sessions: [{ sessionId, url, title, lastSeenMs, hidd
 A semantic, accessibility-tree view of the page.
 
 - **args:** `mode?: 'full' | 'interactive' | 'status'` (default `full`), `scope?` (CSS selector or ref), `diff?: boolean`, `sessionId?`.
-- **returns:** `{ tree, status: { route, title, visibleDialogs }, nodes, truncated, cost: { bytes, tokens } }`.
+- **returns:** `{ tree, status: { route, title, visibleDialogs, overlayHidingPage }, nodes, truncated, cost: { bytes, tokens } }`.
 - **`diff: true`** returns only what changed since your last snapshot of the same scope/mode: `{ mode: 'delta', delta: { added, removed, addedCount, removedCount } }` or `{ mode: 'unchanged' }` (no full tree). The first call (and any call after a route change) still returns the full tree. ~99% fewer tokens to re-look after an action; see [token-efficiency.md](token-efficiency.md).
 - **`cost`** is an estimated size of the result. Re-scope (`mode`/`scope`) before reading if large.
 
@@ -123,11 +128,11 @@ Deep detail on one element, including the signals a snapshot/a11y tree omits, so
 
 Perform one action / several in order.
 
-- **`reticle_act` args:** `ref`, `action`, `args?`, `refuseWhenThrottled?`, `sessionId?`. → `{ since, dispatched, settled, settleReason, result, session, warning? }` where `result = { ok, ref, action, dispatched, settled, settleReason, effect }`. The `session` block `{ lastSeenMs, throttled, focused }` (F2) reports tab health on every act; when `throttled` is true a `warning` string is also attached. Pass `refuseWhenThrottled: true` to hard-fail instead of warning (opt-in; default is warn-only so background testing never breaks).
+- **`reticle_act` args:** `ref`, `action`, `args?`, `refuseWhenThrottled?`, `sessionId?`. → `{ since, dispatched, settled, settleReason, result, session, warning? }` where `result = { ok, ref, action, dispatched, settled, settleReason, effect }`. The `session` block `{ lastSeenMs, throttled, focused }` reports tab health on every act; when `throttled` is true a `warning` string is also attached. Pass `refuseWhenThrottled: true` to hard-fail instead of warning (opt-in; default is warn-only so background testing never breaks).
 - **`reticle_act_sequence` args:** `steps: [{ ref, action, args? }]`. → `{ 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 (F1).** 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.** 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 |
 | --- | --- |
@@ -179,7 +184,7 @@ 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?`, `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` (F2) 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:** `{ 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.
 
 ### `reticle_wait_for`
 
@@ -210,7 +215,7 @@ Compare what the API **returned** against what the page **renders**.
 
 Fast targeted lookups without a full timeline.
 
-- `reticle_network({ since?, method?, urlContains?, status? })` → `{ calls }`
+- `reticle_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_console({ level?, since? })` → `{ logs }`
 - `reticle_animations()` → running/recent animations.
 
@@ -281,10 +286,10 @@ 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_flow_verify`, `reticle_flow_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_flow {action:"list"}` / `reticle_flow {action:"load"}` / `reticle_flow_replay` / `reticle_verify {action:"flows"}`, `reticle_flow_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_flow_verify({ 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_flow_verify` 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").
+- **`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").
 
 ### Human-in-the-loop control
 
@@ -344,11 +349,14 @@ A **predicate** declares what should be true. `reticle_assert` / `reticle_wait_f
 // An element exists / is in a state
 { "kind": "element", "query": { "role": "dialog", "name": "Confirm" }, "state": "visible" }
 // query supports: role, name, text, label, placeholder, testid, alt, scope
-// state: visible | hidden | enabled | disabled | checked | expanded | focused | present
+// state: visible | hidden | enabled | disabled | checked | expanded | focused | present | inViewport
+// inViewport asserts the element is in the viewport NOW (not just in the DOM), so a scrollIntoView is gradeable
 // add "absent": true to assert it is NOT there (regression / removal)
 
-// Visible text anywhere (optionally scoped via an element query instead)
+// Visible text: page-wide, or `scope` it to a subtree (CSS selector or ref) so a match
+// in a background tab can't satisfy an assertion about the dialog that just opened
 { "kind": "text", "contains": "Saved successfully", "visible": true }
+{ "kind": "text", "contains": "Floor 3", "scope": "[role=dialog]" }
 
 // A network call happened
 { "kind": "net", "method": "POST", "urlContains": "/api/order", "status": 200, "since": 1820 }
@@ -406,7 +414,7 @@ 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 }` | keydown/up (default `Enter`) |
+| `press` | `{ key, modifiers? }` | keydown/up (default `Enter`); `modifiers`: an array of `Meta` / `Control` / `Shift` / `Alt` for Cmd+K-style shortcuts |
 | `scrollIntoView` | n/a |  |
 | `upload` | `{ name, content?, type? }` | sets a file on `<input type=file>` |
 | `drag` | `{ toRef }` | pointer-based drag (dnd-kit / rbd) + HTML5 DnD |
@@ -483,7 +491,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), off-screen rows aren't in the DOM yet. Scroll-to-find support is on the roadmap; for now scroll the container or assert against the data via an `reticle.signal`.
+> Note: if your list is **virtualized** (react-window/virtuoso), an off-screen row is not in the DOM at all, so `reticle_query` 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_state` also works and is cheaper.
 
 ### "Login form: does it actually authorize?"
 
@@ -560,7 +568,7 @@ reticle.describe({
 });
 ```
 
-The agent reads this back with `reticle_capabilities()`; see [§3](#3-tool-reference).
+The agent reads this back with `reticle_capabilities()`; see [§3](#3-the-tools-full-reference).
 
 ```jsonc
 reticle_assert({ timeout_ms: 30000, predicate: {
@@ -569,7 +577,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 one rule, `reticle/require-signal-on-mutation`, that flags any function which 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.
+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.)
 
 ```js
 // eslint.config.mjs
@@ -705,7 +713,7 @@ Reticle is cheap by design ([benchmark](token-efficiency.md)), but keep it that
 - **Stable handles for controls.** Prefer `data-testid` over names that include dynamic counts (e.g. "Notifications (3)"); the count changes the accessible name.
 - **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` (F2).** 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.
+- **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.
 - **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.
 
@@ -713,19 +721,33 @@ Reticle is cheap by design ([benchmark](token-efficiency.md)), but keep it that
 
 ## 14. FAQ
 
-**Does this run in production?** No. Keep `reticle.connect()` behind a dev guard. The SDK is side-effect-free and tree-shakes out of prod builds.
+### Does this run in production?
+
+No. Keep `reticle.connect()` behind a dev guard. The SDK is side-effect-free and tree-shakes out of prod builds.
+
+### Do I have to change my components?
+
+No, for basic look/act/observe. You'll get better results by adding `data-testid`s and labels where the agent needs precision.
+
+### Does it work without React?
+
+The core (DOM/network/route/console/animation/snapshot/actions) is framework-agnostic and is gated against a vanilla-TS app. React, Next.js, Remix and Astro each have an app and a CI gate. SvelteKit is wired end-to-end. `reticle init` writes the client hook and the Vite plugin, and the plugin stamps `data-reticle-source` into `.svelte` components so verdicts carry `file:line`. But there is still no SvelteKit app in CI, so it is unverified rather than supported. Vue has a Pinia store adapter and nothing else: no detection, no `.vue` stamping, no gate. See [what Svelte support is and is not](getting-started.md#what-svelte-support-is-and-what-it-is-not).
+
+### Can it judge whether my UI looks good?
+
+No. Reticle verifies behavior, not aesthetics. Visual/pixel correctness and "does it feel right" remain human (or a visual-diff tool).
 
-**Do I have to change my components?** No, for basic look/act/observe. You'll get better results by adding `data-testid`s and labels where the agent needs precision.
+### Does it replace Playwright/Cypress?
 
-**Does it work without React?** The core (DOM/network/route/console/animation/snapshot/actions) is framework-agnostic and is gated against a vanilla-TS app. React, Next.js, Remix and Astro each have an app and a CI gate. SvelteKit is wired end-to-end. `reticle init` writes the client hook and the Vite plugin, and the plugin stamps `data-reticle-source` into `.svelte` components so verdicts carry `file:line`. But there is still no SvelteKit app in CI, so it is unverified rather than supported. Vue has a Pinia store adapter and nothing else: no detection, no `.vue` stamping, no gate. See [what Svelte support is and is not](getting-started.md#what-svelte-support-is-and-what-it-is-not).
+No. Those are your scripted CI suite. Reticle is for in-loop verification while the agent codes, and for the cases you never automated. They compose.
 
-**Can it judge whether my UI _looks_ good?** No. Reticle verifies behavior, not aesthetics. Visual/pixel correctness and "does it feel right" remain human (or a visual-diff tool).
+### How does it compare to Playwright MCP / Chrome DevTools MCP?
 
-**Does it replace Playwright/Cypress?** No. Those are your scripted CI suite. Reticle is for in-loop verification while the agent codes, and for the cases you never automated. They compose.
+Those let an agent drive/ inspect a _separate_ browser; Reticle verifies your _own running app_ (real session/auth) with assertions + regression as first-class, far more cheaply. See [Reticle vs Playwright MCP](vs-playwright-mcp.mdx) and [Reticle vs Chrome DevTools MCP](vs-chrome-devtools-mcp.mdx).
 
-**How does it compare to Playwright MCP / Chrome DevTools MCP?** Those let an agent drive/ inspect a _separate_ browser; Reticle verifies your _own running app_ (real session/auth) with assertions + regression as first-class, far more cheaply. See the README comparison.
+### Multiple tabs/apps?
 
-**Multiple tabs/apps?** Each is a session; pass `sessionId` to any tool when more than one is connected (`reticle_sessions` lists them).
+Each is a session; pass `sessionId` to any tool when more than one is connected (`reticle_sessions` lists them).
 
 ---
 
@@ -794,7 +816,7 @@ A session starts on the agent's first activity and must reliably end even when t
 - **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).
 
-Tune the idle window with `reticle_session({ idleEndMs })`; it updates both the browser timer and the server reaper. The human keeps the panel (with Copy/Export of the run) after any end.
+Tune the idle window with `reticle_session({ action: "tune", idleEndMs })`; it updates both the browser timer and the server reaper. The human keeps the panel (with Copy/Export of the run) after any end.
 
 ### `reticle_session {action:"narrate"}`: show the agent's intent
 

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

@@ -80,3 +80,44 @@ Neither tool forbids the other. A reasonable setup:
     handlers, double submits, silent validation.
   </Card>
 </CardGroup>
+
+## FAQ
+
+<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.
+</Accordion>
+
+<Accordion title="If DevTools MCP is cheaper, why not just use it?">
+  Because it is cheaper partly by looking at less. Cost per look is half a metric; the other half is
+  whether the look catches the bug. Verification Efficiency combines them and gates on catching
+  every bug with zero false alarms, and on that measure Reticle leads 12.27 to 10.55. The 7%
+  per-look advantage also inverts on a real app: on the production dashboard measured here DevTools'
+  snapshot was 1,105 tokens against Reticle's 678.
+</Accordion>
+
+<Accordion title="Can I run both MCP servers at once?">
+  Yes. They are independent servers with distinct tool names. A reasonable split is DevTools MCP for
+  performance traces, deep Chrome internals and real screenshots, and Reticle for the verify loop
+  and the source pointer.
+</Accordion>
+
+<Accordion title="Do I have to instrument my app to use Reticle?">
+  You have to add the dev-only SDK, which is what `npx @reticlehq/server init` does. Beyond that,
+  look, act and observe work with zero component changes. Signals and registered stores are
+  optional, and they are what buys the assertions DevTools MCP structurally cannot make. If
+  instrumenting is off the table entirely, DevTools MCP is the correct choice.
+</Accordion>
+
+<Accordion title="Does Reticle give me performance traces?">
+  Not in the way Chrome's own tooling does, and it does not pretend to. It can tell you a React
+  render storm is happening (commit rate climbing with no DOM mutation), which DevTools MCP does not
+  surface. For flame charts and deep tracing, use Chrome's.
+</Accordion>
+
+</AccordionGroup>

package/docs/vs-playwright-mcp.mdx

@@ -1,5 +1,5 @@
 ---
-title: Reticle vs Playwright MCP: outside in, inside out
+title: 'Reticle vs Playwright MCP: outside in, inside out'
 sidebarTitle: vs Playwright MCP
 description: Playwright MCP drives any website from the outside. Reticle verifies an app you own from the inside. They solve different problems, and they compose.
 icon: masks-theater
@@ -49,7 +49,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` or `signal`. Plus whether the capture was clean and complete.
+- **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.
 - **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
@@ -83,3 +83,43 @@ Reticle also has a driven mode (`reticle drive`) that provides real CDP input an
     that looks fine.
   </Card>
 </CardGroup>
+
+## FAQ
+
+<AccordionGroup>
+
+<Accordion title="Can I use Reticle and Playwright MCP at the same time?">
+  Yes, and it is a common setup. They are separate MCP servers with separate tool namespaces, so
+  nothing collides. Drive with Playwright where it is stronger (a third-party OAuth hop, a
+  cross-browser pass, a genuine pixel diff) and assert with Reticle where the question is "did my
+  app actually do the thing".
+</Accordion>
+
+<Accordion title="Does Reticle work on a site I do not own?">
+  No. Reticle reads the program from inside the page, which requires a dev-only SDK in the app. No
+  SDK, no Reticle. That is the single hardest boundary between these two tools, and it is why
+  Playwright MCP is the right answer for anything you cannot instrument.
+</Accordion>
+
+<Accordion title="Is Reticle actually cheaper, or only on the pages you chose?">
+  On a full-tree-vs-full-tree comparison the gap is modest, roughly 1.8x. The large gap comes from
+  not needing the full tree: Playwright MCP's primary perception primitive returns the accessibility
+  tree, Reticle's answers a specific question. On a small page both are cheap. On the real
+  production dashboard measured here Reticle was about 2.1x leaner. Force Reticle to dump the whole
+  page every step and you save very little.
+</Accordion>
+
+<Accordion title="Does Reticle support Firefox or WebKit?">
+  Not meaningfully. The always-on in-page SDK is browser-agnostic, but the driven paths that provide
+  real pointer input and screenshots go through CDP and are Chromium-oriented. If cross-browser is a
+  requirement, that is a Playwright job.
+</Accordion>
+
+<Accordion title="Do I have to give up my existing Playwright suite?">
+  No, and you should not. A scripted Playwright or Cypress suite is what gates your releases.
+  Reticle is the in-loop check while an agent is coding and the safety net for the flows nobody ever
+  got round to automating. Your existing `data-testid` attributes work in Reticle unchanged, so the
+  two share the same anchors.
+</Accordion>
+
+</AccordionGroup>

package/docs/vs-screenshots.mdx

@@ -1,5 +1,5 @@
 ---
-title: Screenshots lie: why pixels cannot verify AI-generated code
+title: 'Screenshots lie: why pixels cannot verify AI-generated code'
 sidebarTitle: vs screenshots
 description: The failures that AI coding agents actually produce are invisible in a rendered frame. Here is why a better vision model does not fix that.
 icon: image
@@ -86,6 +86,47 @@ We have not proven that Reticle makes agents _fix_ more bugs. A controlled test
 
 What is measured is detection: 10 of 10 injected regressions caught with zero false alarms, against 9 and 8 for the alternatives.
 
+## FAQ
+
+<AccordionGroup>
+
+<Accordion title="Would a better vision model fix this?">
+  No, and this is the single most expensive misconception on the page. Model quality improves the
+  _reading_ of evidence; it cannot create evidence that was never captured. A screenshot of a page
+  whose bug is non-visual contains no signal about that bug at any resolution, so a stronger model
+  produces a more confident version of the same wrong answer.
+</Accordion>
+
+<Accordion title="So screenshots are useless?">
+  No. They are the correct instrument for a specific class of bug: a font that failed to load, a GPU
+  or compositing glitch, layout that breaks only at one viewport, and anything where the rendered
+  frame _is_ the thing under test. Reticle ships `reticle_screenshot` and `reticle_visual_diff` for
+  exactly those. If pixel regression is your primary concern, a dedicated visual tool will serve you
+  better.
+</Accordion>
+
+<Accordion title="What does Reticle read instead of pixels?">
+  The program: the network log (did the request fire, how many times, what did it return), the
+  console, client-side routing, registered store state, and any signal the app itself emits. A
+  response carrying `net.total: 1` rules out a double submit; a non-empty `stateDiffs` rules out
+  mock data; `consoleErrors: 0` rules out "it worked but threw".
+</Accordion>
+
+<Accordion title="Does that mean Reticle catches every bug?">
+  No. It has not been shown to make agents _fix_ more bugs; a controlled fix-rate test did not show
+  an improvement and we consider that question open. What is measured is detection: 10 of 10
+  injected regressions caught with zero false alarms, against 9 and 8 for the alternatives. And a
+  purely visual regression still needs the opt-in visual diff.
+</Accordion>
+
+<Accordion title="Can I keep using screenshots alongside Reticle?">
+  Yes, and for a visual product you probably should. The argument here is not that screenshots are
+  bad, it is that a screenshot cannot answer "did the code work", which is the question an AI coding
+  agent needs answered on every change.
+</Accordion>
+
+</AccordionGroup>
+
 <CardGroup cols={2}>
   <Card title="See a real verdict" icon="rocket" href="/quickstart">
     Five minutes, and the output on that page was captured live.

package/docs/what-is-reticle.mdx

@@ -12,7 +12,7 @@ It exists because an agent that writes code cannot otherwise tell whether that c
 ## How it works, in three parts
 
 1. **An SDK inside the app.** Dev-only, stripped from production builds, added by a build plugin. It instruments the DOM, network, routing, console, animations, and your state library.
-2. **A local bridge.** The SDK connects over a WebSocket to a daemon on your machine. Reticle never starts or manages your dev server; it attaches to the app you are already running.
+2. **A local bridge.** The SDK connects over a WebSocket to a daemon on your machine. The daemon never starts or manages your dev server. It attaches to the app that is running. If none is, the agent is the one told to start it, using your project's own dev script, in the background, and saying so.
 3. **An MCP server.** The daemon exposes the app to your agent as tools. `reticle_snapshot` to look, `reticle_act_and_wait` to act and prove in one call, `reticle_state` and `reticle_network` to observe, `reticle_assert` to check.
 
 Everything stays on your machine. No application code, DOM, network traffic, or console output leaves it.

package/docs/why-reticle.mdx

@@ -1,10 +1,12 @@
 ---
-title: Why Reticle: seeing is not believing
+title: 'Why Reticle: seeing is not believing'
 sidebarTitle: Why Reticle
 description: AI-written code fails by looking correct. Reticle reads the running program instead of the pixels, so a silent failure stops being invisible.
 icon: lightbulb
 ---
 
+**Use Reticle because AI-written code fails by looking correct.** A screenshot cannot show you whether a request fired, what status it returned, whether application state changed, or whether one click sent one request or two. Reticle reads the running program instead of the pixels, so those silent failures stop being invisible.
+
 Software has always had bugs. What changed is the _kind_ of bug that reaches you.
 
 A human writing code by hand produces errors that announce themselves: a stack trace, a red screen, a test that goes red. An agent writing code produces something more dangerous: a change that looks completely correct, renders beautifully, and does nothing. The page is fine. The data never saved.