@reticlehq/server 3.3.0 → 3.5.0

package/docs/predicates.mdx

@@ -7,7 +7,7 @@ icon: filter
 
 A predicate declares what should be true, as `{ kind, ...fields }`. Reticle has twelve kinds: `signal`, `state`, `net`, `route`, `element`, `text`, `console`, `animation`, `settled`, and the combinators `allOf`, `anyOf` and `not`. Which one you pick decides whether a green means anything.
 
-It is the argument to `until` on [`reticle_act_and_wait`](/tools/act-and-wait), and to `predicate` on [`reticle_assert`](/tools/assert) and [`reticle_wait_for`](/tools/wait-for).
+It is the argument to `until` on [`reticle_act_and_wait`](/tools/act-and-wait), and to `predicate` on [`reticle_assert`](/tools/assert) and [`reticle_assert { action: "wait" }`](/tools/wait-for).
 
 Every predicate is `{ kind, ...fields }`.
 
@@ -35,6 +35,7 @@ Take the advice. `element` and `text` are convenient and weak; `signal`, `state`
 | `element` / `text` | weak      | Something rendered. A mock renders too                 |
 | `animation`        | weak      | An animation ran or finished                           |
 | `settled`          | timing    | The page went quiet. A precondition, not a proof       |
+| `compare`          | its sides | Two readings agree: the stronger side's grade          |
 
 ## The leaves
 
@@ -48,13 +49,13 @@ Take the advice. `element` and `text` are convenient and weak; `signal`, `state`
 }
 ```
 
-`query` accepts `role`, `name`, `text`, `label`, `placeholder`, `testid`, `alt`, `value`, `by`, `component`, `source`, `scope`, `self`, `attrs`. `state` is one of `visible`, `hidden`, `enabled`, `disabled`, `checked`, `expanded`, `focused`, `inViewport`, `present`.
+`query` accepts `role`, `name`, `text`, `label`, `placeholder`, `testid`, `alt`, `value`, `by`, `component`, `source`, `scope`, `self`, `attrs`. `state` is one of `visible`, `hidden`, `enabled`, `disabled`, `checked`, `expanded`, `pressed`, `focused`, `inViewport`, `present`.
 
 `value` is the one worth knowing about. `{ "role": "textbox", "name": "Amount" }` collapses to "a textbox called Amount exists", which passes against an empty field; adding `value` is what makes it an assertion about what the user will actually send. `by` selects the locator strategy explicitly, `component` and `source` match React component identity and source location, and `self` restricts a scoped match to the scope element itself rather than its descendants.
 
 `attrs` is a list of attribute **names**, such as `["href", "data-status"]`. It **projects** those attributes onto each match so you can read them back, and it does not filter. `["data-status=complete"]` is refused: it would otherwise look up an attribute literally named `data-status=complete`, find none, and leave the predicate resting on the locator alone, which is a green for any value the element happens to hold.
 
-To READ the values, call `reticle_query` with `attrs` and look at the `attrs` map on each match. To ASSERT one: a form field's value goes in the query as `value`, while a state expressed as a data attribute is better asserted as the consequence it stands for, such as a `signal`, a `net` call, or the text the user actually sees.
+To READ the values, call `reticle_look { action: "find" }` with `attrs` and look at the `attrs` map on each match. To ASSERT one: a form field's value goes in the query as `value`, while a state expressed as a data attribute is better asserted as the consequence it stands for, such as a `signal`, a `net` call, or the text the user actually sees.
 
 ```json
 { "kind": "element", "query": { "role": "textbox", "name": "Amount", "value": "274.58" } }
@@ -118,7 +119,7 @@ Two fields read the RESPONSE BODY, so a request that succeeded with the wrong nu
 { "kind": "net", "urlContains": "/api/job", "bodyMatches": { "status": "completed" } }
 ```
 
-`bodyMatches` is a shallow field match, keyed like `signal.dataMatches` and taking the same operators (`*`, `$gte`, `$contains`). Reach for it whenever the value is an enum, because that is the case a substring cannot decide: `bodyContains: "completed"` passes on a body carrying `"completedAt": null`, where the needle matched the KEY and the job was still queued. `completed`/`completedAt`, `success`/`successRate`, `sent`/`unsent` all have that shape.
+`bodyMatches` is a field match, keyed like `signal.dataMatches` and taking the same operators (`*`, `$gte`, `$contains`). A key can be a dotted path into a wrapped answer: `{ "data.status": "completed" }`, `{ "items.0.id": "a1" }`, `{ "items.length": 3 }`. A nested object written out as a value is compared whole, so use the path to match one field inside it. Reach for it whenever the value is an enum, because that is the case a substring cannot decide: `bodyContains: "completed"` passes on a body carrying `"completedAt": null`, where the needle matched the KEY and the job was still queued. `completed`/`completedAt`, `success`/`successRate`, `sent`/`unsent` all have that shape.
 
 Both require body capture, `reticle({ captureNetworkBodies: true })`, and say so when the body was never recorded rather than reporting an ordinary mismatch.
 
@@ -161,7 +162,7 @@ A passing route verdict quotes the transition itself:
 { "kind": "signal", "name": "webhook:received", "dataMatches": { "provider": "stripe", "id": "*" } }
 ```
 
-The app emitted a named signal via `reticle.signal()`. `dataMatches` is shallow JSON matching, and `*` means "present, any value".
+The app emitted a named signal via `reticle.signal()`. `dataMatches` matches field by field, a key can be a dotted path (`"order.total"`), and `*` means "present, any value".
 
 `count` works here exactly as it does on `net`:
 
@@ -303,6 +304,50 @@ This is the predicate that catches a UI-versus-store desync. A deploy that only
 
 Network and DOM idle. This is the deterministic replacement for a fixed sleep, not a proof of anything: combine it with a real consequence rather than asserting it alone. Omitting `until` on [`reticle_act_and_wait`](/tools/act-and-wait) waits for exactly this.
 
+### compare
+
+```json
+{
+  "kind": "compare",
+  "left": { "from": "text", "scope": "#refunded" },
+  "right": { "from": "net", "urlContains": "/api/refund", "path": "refunded" },
+  "as": "number"
+}
+```
+
+Two observed values must agree, and you do not have to know either one. Every other predicate checks one reading against a value you write down. That cannot catch a page that echoes the user's input instead of the server's answer unless you already know the right answer: a refund of `1187.01` that the server read as paise answered `{"refunded":11.87}`, the page showed `₹1,187.01`, and every other channel was green.
+
+Each side reads one value from a source:
+
+| `from` | Fields | Reads |
+| --- | --- | --- |
+| `net` | `urlContains`, `path`, `method?`, `body?` | A field of the LAST matching call's body. `body` is `response` (default) or `request` |
+| `signal` | `name`, `path` | A field of the last `name` signal's payload |
+| `state` | `path`, `store?` | A store value, as `state` reads it |
+| `text` | `scope` | The whole text of the element `scope` names (a CSS selector) |
+
+A `path` is a field name or a dotted path into nested data (`data.total`, `items.0.price`), and it must end on a single value, not an object.
+
+`as` is `value` (the default) or `number`:
+
+- `value` is strict equality. The text `"11.87"` and the number `11.87` are different, and the failure says so and suggests `as: "number"`.
+- `number` reads one number from each side. A JSON number is used as it is; a string contributes its only number, so `"Refunded ₹1,187.01"` reads as `1187.01`. A string holding two numbers is unknown rather than guessed at, so scope the text to the one value. Add `tolerance` for a band.
+
+A side nobody could read is never a pass. A call that never happened, a missing element or a missing field fails. A body that was not recorded, was truncated before the field, or had the field redacted is unknown. Comparing a source with itself is refused before it runs, because it would agree on every page.
+
+Two live sides (`text`, `state`) are also read before the action. If they already agreed, the result is `already_true`, because their agreement says nothing about what the action did. Put a `net` or `signal` side in the comparison to tie it to the action.
+
+Comparing request with response on the same call is legitimate, and it is the direct check for a unit mismatch:
+
+```json
+{
+  "kind": "compare",
+  "left": { "from": "net", "urlContains": "/api/refund", "body": "request", "path": "amount" },
+  "right": { "from": "net", "urlContains": "/api/refund", "path": "refunded" },
+  "as": "number"
+}
+```
+
 ## Asserting a failure on purpose
 
 A fault-injection test (mock a 500, check the error UI) is asserting that a request **fails**. Say so in the predicate, or the verdict will disagree with you:

package/docs/quickstart.mdx

@@ -5,7 +5,7 @@ description: Install Reticle, connect your coding agent, and get a real verdict
 icon: rocket
 ---
 
-**Run the installer in a terminal, open your coding agent, then run `init` in your project.** Reticle is a verification layer for AI coding agents: it embeds a dev-only SDK in your running web app so an agent can prove a change works instead of guessing.
+**Run the installer once, then run `reticle connect --project "My App"` in your project.** Reticle embeds a dev-only SDK in your running app, signs you in through browser approval when needed, and syncs your checks to the project you name.
 
 By the end of this page your agent will click a button in your app and prove what happened: the request that fired, the state that changed, and the file to open if it didn't.
 
@@ -53,18 +53,20 @@ npm install -g @reticlehq/server
 npx @reticlehq/server setup mcp
 ```
 
-## Step 2. Open your coding agent, and wire the project
+## Step 2. Connect this project
 
-The `reticle_*` tools are already there. In your project directory:
+In your project directory, before opening your coding agent:
 
 ```bash
-npx @reticlehq/server init
+npx @reticlehq/server connect --project "My App"
 ```
 
-Like `npm init` or `git init`, this is the per-project step: it installs the SDK, wires it into your app's entry point, restarts your dev server and then opens your app to prove a session connected. It is idempotent. Run it twice and the second run reports what was already done rather than doing it again.
+This installs the SDK, wires your app, starts the dev server, and checks that a browser session connected. It then opens browser sign-in approval if needed, links this folder to the named cloud project, and sends existing local history. Approve the short code shown in the browser and terminal; the command resumes by itself. A saved sign-in is reused after the cloud accepts it. Open your coding agent once this command finishes; if it was already open during installation, restart it to load the new tools.
 
 Step 1 is once per machine. This step is once per project.
 
+Want local-only verification without an account? Run `reticle init` in this step instead. You can run `reticle connect` later to sync your history.
+
 Prefer to install the skill and let the agent run setup itself? On Claude Code the plugin registers the MCP server and the skill in one step:
 
 ```text
@@ -80,7 +82,7 @@ npx skills add reticlehq/reticle
 
 Then type `/reticle` and the agent runs the install from the skill.
 
-Useful flags, from `reticle init` itself:
+Useful flags for the local-only `reticle init` path:
 
 ```
 reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
@@ -90,7 +92,7 @@ reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
               only make sense once the tools are reachable.
 ```
 
-Start with `--dry-run` if you want to see the plan before anything is written.
+Start with `reticle init --dry-run` if you want to see the app changes before anything is written.
 
 <Tip>
   In a monorepo, `init` will find several apps and ask which one you mean. `--app packages/web`
@@ -107,9 +109,9 @@ npx @reticlehq/server doctor
 
 `doctor` diagnoses the whole setup in one command: Chromium, the daemon, the port. If something is wrong this is the page you want before you start debugging your app instead.
 
-## Step 4. Start your app and open it
+## Step 4. Open your app again when you need it
 
-Start your dev server as usual, then:
+`connect` already started the dev server and opened the app. On a later day, start your dev server as usual, then:
 
 ```bash
 npx @reticlehq/server open
@@ -236,7 +238,7 @@ That third state is the one that matters. Most tools have two outcomes and quiet
   <Accordion title="How long does it actually take to install Reticle?">
     Two commands, and no restart if you run them in order. The installer registers the MCP server
     with every agent on the machine, so opening your agent afterwards is all that is needed. Then
-    `npx @reticlehq/server init` wires the project and restarts your dev server for you. The MCP
+    `npx @reticlehq/server init` wires the project, starts your dev server and opens the app for you. The MCP
     registration is global, so every later project starts with the tools already there.
   </Accordion>
 

package/docs/recipes.mdx

@@ -5,7 +5,7 @@ description: Worked examples for the situations you are actually in, with the re
 icon: book-open
 ---
 
-Each recipe is a situation, the call that verifies it, and what came back. Every response on this page was captured from a running app on 2026-08-16. Refs like `e605` are session-specific: take your own from [`reticle_query`](/tools/query) before copying a call.
+Each recipe is a situation, the call that verifies it, and what came back. Every response on this page was captured from a running app on 2026-08-16. Refs like `e605` are session-specific: take your own from [`reticle_look { action: "find" }`](/tools/query) before copying a call.
 
 ## "Did the login actually work?"
 
@@ -135,7 +135,7 @@ The right predicate was sitting in the response the whole time:
 
 ## "Nothing matched, and I do not know why"
 
-An empty `reticle_query` result tells you what _is_ there:
+An empty `reticle_look { action: "find" }` result tells you what _is_ there:
 
 ```json
 {

package/docs/state-management.mdx

@@ -179,7 +179,7 @@ worker.onmessage = (e) => push(e.data);
 { "store": "app", "path": "cart.items.0.qty" }
 ```
 
-`reticle_state` walks a dot-path with numeric array indices. `depth` collapses anything deeper to a size marker, which is the difference between a cheap look and a very expensive one on a large store.
+`reticle_look { action: "state" }` walks a dot-path with numeric array indices. `depth` collapses anything deeper to a size marker, which is the difference between a cheap look and a very expensive one on a large store.
 
 You can also assert on it directly, which is stronger than reading it afterwards:
 
@@ -190,7 +190,7 @@ You can also assert on it directly, which is stronger than reading it afterwards
 That catches a UI-versus-store desync, a deploy that only looks shipped, deterministically and with no model involved.
 
 <CardGroup cols={2}>
-  <Card title="reticle_state" icon="database" href="/tools/state">
+  <Card title='reticle_look { action: "state" }' icon="database" href="/tools/state">
     Arguments, depth control, and reading a component's hook state.
   </Card>
   <Card title="Instrument your app" icon="wrench" href="/instrumentation">

package/docs/system-map.md

@@ -66,7 +66,7 @@ These three were each wrong by the time somebody checked: the table read 68 / 48
 
 | Token | Produced by | Consumed by | Invalidated by |
 | --- | --- | --- | --- |
-| `sessionId` | `reticle_sessions`, HELLO | ~every tool | tab close; **survives reload** via `sessionStorage` |
+| `sessionId` | `reticle_session { action: "list" }`, HELLO | ~every tool | tab close; **survives reload** via `sessionStorage` |
 | `ref` (`e115`) | `snapshot`, `query`, `scroll_to` | `inspect`, `act`, `act_and_wait`, `state` | any re-render; refuses cleanly rather than clicking the new occupant |
 | `actionId` (`a2`) | `act`, `act_and_wait` | `observe`, `network`, `console` filters | window expiry |
 | `since` cursor | every read | every read | ring-buffer eviction |

package/docs/telemetry.md

@@ -122,7 +122,7 @@ Reticle verifies apps for AI agents, and for a long time it had no way to hear w
 
 | Who | How | What it carries |
 | --- | --- | --- |
-| Your agent | Calls the `reticle_feedback` MCP tool (after a failure, **or to ask for a feature**) | What it wrote: an analysis, or a request with the goal behind it, what would improve, and how it works around the gap today. Plus the model it is running, which it tells us because MCP cannot |
+| Your agent | Calls the `reticle_session { action: "feedback" }` MCP tool (after a failure, **or to ask for a feature**) | What it wrote: an analysis, or a request with the goal behind it, what would improve, and how it works around the gap today. Plus the model it is running, which it tells us because MCP cannot |
 | You | Run `npx @reticlehq/server feedback [--rating 1-5] [--bug] "your words"` | Your words and your rating |
 | Your agent, before Reticle works | Runs `reticle feedback --agent --kind <bug\|gap\|ambiguity\|feature_request\|improvement> "what happened"` | The same words, filed from the shell. This exists for the phase where there is no daemon and no MCP tools (a failed `init`, half-finished wiring), which is the failure we are otherwise never told about |
 

package/docs/token-efficiency.md

@@ -4,7 +4,7 @@ description: Why asking narrow questions costs a fraction of feeding the whole a
 icon: coins
 ---
 
-A full Reticle verify loop costs about **100 tokens**, against roughly **7,300** for a full-tree accessibility snapshot on the same page: about 73x leaner, because Reticle asks a narrow question instead of returning the page. If you re-look after an action with `reticle_snapshot({ diff: true })`, the re-read costs about 99% less again.
+A full Reticle verify loop costs about **100 tokens**, against roughly **7,300** for a full-tree accessibility snapshot on the same page: about 73x leaner, because Reticle asks a narrow question instead of returning the page. If you re-look after an action with `reticle_look({ action: "page", diff: true })`, the re-read costs about 99% less again.
 
 Agent browser tools that feed the **whole accessibility tree** to the model every step get expensive fast. Playwright MCP's own ecosystem notes its snapshots _"can exceed 50,000 tokens on complex pages,"_ with a _typical task ~114,000 tokens through MCP._ Reticle is built to ask **narrow questions** instead, so the per-interaction cost stays tiny.
 
@@ -28,7 +28,7 @@ Measured against the bench dashboard (`apps/bench-app`) **with a 1,000-item list
 
 ## Diffed snapshots: pay once, then only for changes
 
-After the first snapshot, pass `reticle_snapshot({ diff: true })` to get back **only what changed** since your last look of the same scope/mode (`mode:delta` with added/removed lines, or `mode:unchanged`). A route change auto-resets to a full snapshot, so you never read a misleading cross-page diff.
+After the first snapshot, pass `reticle_look({ action: "page", diff: true })` to get back **only what changed** since your last look of the same scope/mode (`mode:delta` with added/removed lines, or `mode:unchanged`). A route change auto-resets to a full snapshot, so you never read a misleading cross-page diff.
 
 Measured on a representative 150-row dashboard (the shipped regression benchmark `server/src/surface/tools/snapshot-cost.test.ts`, char/4 proxy):
 
@@ -40,7 +40,7 @@ Measured on a representative 150-row dashboard (the shipped regression benchmark
 
 **~99% fewer tokens** to re-look after an action, and because a `delta` carries no stale full tree, it also removes the 60K to 80K-token stale-context buildup that makes long-running agents start hallucinating selectors that no longer exist.
 
-Every `reticle_snapshot`/`reticle_query` result also carries `cost:{ bytes, tokens }` (estimated) so you can **re-scope before reading** a large body (`mode:interactive`/`status`, a tighter `scope`, or a narrower `query`) instead of paying for it first.
+Every `reticle_look { action: "page" }`/`reticle_look { action: "find" }` result also carries `cost:{ bytes, tokens }` (estimated) so you can **re-scope before reading** a large body (`mode:interactive`/`status`, a tighter `scope`, or a narrower `query`) instead of paying for it first.
 
 ## The other tax: tool schemas, paid on every request
 

package/docs/tools/act-and-wait.mdx

@@ -162,6 +162,7 @@ A verification tool that cannot describe the quality of its own evidence is aski
 | `predicate` | Alias for `until`, the name `assert` and `wait_for` use |
 | `timeout_ms` | Maximum wait, defaulting to 4000. `0` evaluates the predicate once, no wait |
 | `refuseWhenThrottled` | Throw rather than act on a throttled tab |
+| `durable` | After a `yes`, reload the page and require the element, text and state parts of `until` to hold again. A consequence that is gone after the reload turns the verdict into `no`: the UI advanced, the change did not persist |
 
 Omitting `until` waits for network and DOM idle, which is the deterministic replacement for a fixed sleep. To assert a consequence **and** settle, combine them:
 

package/docs/tools/act-sequence.mdx

@@ -5,7 +5,7 @@ icon: layer-group
 ---
 
 <Warning>
-  **reticle_act_sequence is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_act_sequence is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_act { steps: [...] }`** instead: the same call, routed on the steps array. Everything below describes what that call does;
   only the spelling changed. A call to the old name is answered with the new one, but an
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.

package/docs/tools/act.mdx

@@ -59,7 +59,7 @@ Real response:
 
 ## Actions
 
-`click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `drag` · `webmcp`
+`click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `drag`
 
 | Action           | Arguments                                                       |
 | ---------------- | --------------------------------------------------------------- |

package/docs/tools/console.mdx

@@ -5,7 +5,7 @@ icon: terminal
 ---
 
 <Warning>
-  **reticle_console is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_console is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_observe { action: "console" }`** instead. Everything below describes what that call does;
   only the spelling changed. A call to the old name is answered with the new one, but an
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.

package/docs/tools/inspect.mdx

@@ -5,7 +5,7 @@ icon: crosshairs
 ---
 
 <Warning>
-  **reticle_inspect is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_inspect is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_look { action: "element" }`** instead. Everything below describes what that call does;
   only the spelling changed. A call to the old name is answered with the new one, but an
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.

package/docs/tools/network.mdx

@@ -5,7 +5,7 @@ icon: satellite-dish
 ---
 
 <Warning>
-  **reticle_network is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_network is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_observe { action: "network" }`** instead. Everything below describes what that call does;
   only the spelling changed. A call to the old name is answered with the new one, but an
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.

package/docs/tools/query.mdx

@@ -5,7 +5,7 @@ icon: magnifying-glass
 ---
 
 <Warning>
-  **reticle_query is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_query is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_look { action: "find" }`** instead. Everything below describes what that call does;
   only the spelling changed. A call to the old name is answered with the new one, but an
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.

package/docs/tools/sessions.mdx

@@ -5,7 +5,7 @@ icon: list-check
 ---
 
 <Warning>
-  **reticle_sessions is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_sessions is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_session { action: "list" }`** instead. Everything below describes what that call does;
   only the spelling changed. A call to the old name is answered with the new one, but an
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.

package/docs/tools/snapshot.mdx

@@ -5,7 +5,7 @@ icon: camera
 ---
 
 <Warning>
-  **reticle_snapshot is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_snapshot is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_look { action: "page" }`** instead. Everything below describes what that call does;
   only the spelling changed. A call to the old name is answered with the new one, but an
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.

package/docs/tools/state.mdx

@@ -5,7 +5,7 @@ icon: database
 ---
 
 <Warning>
-  **reticle_state is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_state is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_look { action: "state" }`** instead. Everything below describes what that call does;
   only the spelling changed. A call to the old name is answered with the new one, but an
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.

package/docs/tools/wait-for.mdx

@@ -5,7 +5,7 @@ icon: hourglass
 ---
 
 <Warning>
-  **reticle_wait_for is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_wait_for is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_assert { action: "wait" }`** instead. Everything below describes what that call does;
   only the spelling changed. A call to the old name is answered with the new one, but an
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.

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`). 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.
+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.
 
 If you haven't set up Reticle yet, start with [Getting Started](getting-started.md).
 
@@ -183,7 +183,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?`, `intent?`, `sessionId?`.
+- **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.
 
 ### `reticle_assert { action: "wait" }`
@@ -350,7 +350,7 @@ A **predicate** declares what should be true. `reticle_assert` / `reticle_assert
 // 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 | inViewport
+// state: visible | hidden | enabled | disabled | checked | expanded | pressed | 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)
 
@@ -396,7 +396,7 @@ A `state` assertion is graded as a **consequence** (a wrong element or stale ren
 - `timeout_ms` (on `assert`/`wait_for`): wait up to N ms for it to become true.
 - `since` (on `net`/`console` leaves): only consider events after this cursor (from `act`).
 
-`dataMatches` uses shallow JSON matching; `*` means "present, any value".
+`dataMatches` matches field by field; a key can be a dotted path (`"order.total"`, `"items.0.id"`), and `*` means "present, any value".
 
 ---
 
@@ -419,7 +419,6 @@ A `state` assertion is graded as a **consequence** (a wrong element or stale ren
 | `scrollIntoView` | n/a |  |
 | `upload` | `{ name, content?, type? }` | sets a file on `<input type=file>` |
 | `drag` | `{ toRef }` | pointer-based drag (dnd-kit / rbd) + HTML5 DnD |
-| `webmcp` | `{ tool, params }` | calls a `navigator.modelContext` tool if the site exposes one |
 
 ---
 
@@ -640,7 +639,7 @@ Capture everything that happens across a span. Useful for "run my whole checkout
 
 ```jsonc
 reticle_record {action:"start"}({ recordingName: "checkout" })
-// …agent performs the flow (reticle_act / reticle_act_sequence)…
+// …agent performs the flow (reticle_act, single or with steps)…
 reticle_record {action:"stop"}({ recordingName: "checkout" })
 // → {
 //     recordingName,
@@ -732,7 +731,7 @@ No, for basic look/act/observe. You'll get better results by adding `data-testid
 
 ### 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).
+The core (DOM/network/route/console/animation/snapshot/actions) is framework-agnostic and is gated against a vanilla-TS app. What is proven for each framework, from driven to a verdict in CI to install-gated to wired but unverified, is listed once in [Frameworks](frameworks.mdx). See also [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?
 
@@ -858,6 +857,7 @@ It does **not** freeze `requestAnimationFrame`/microtasks (React's scheduler kee
   "dataMatches": { "count": { "$gte": 1 }, "sections": { "$contains": "hook" } },
 }
 // operators: $gte $lte $gt $lt $contains (array/substring) $length ; "*" = present
+// keys: a field name, or a dotted path into nested data ("order.total", "items.0.id")
 ```
 
 On a failed signal assert, the result includes a **near-miss**: the signals that _did_ fire with that name + their data. And `reticle_observe`'s summary now includes `domChanged` (in-place text/attribute re-renders, not just added/removed nodes).

package/docs/use-cases.mdx

@@ -0,0 +1,157 @@
+---
+title: 'Use cases: what people verify with Reticle'
+sidebarTitle: Use cases
+description: 'Verifying agent-built changes, security behaviour, accessibility and UX, performance, SEO basics, and driving the app as different users. What Reticle checks in each, with a call you can run.'
+icon: list-check
+---
+
+Reticle runs inside your app while it is running, so anything the app does (a request, a state change, a console line, a focus move, a route change, a performance entry) is something an agent can check and get a verdict on. People use it for more than "did my change work". This page covers the main uses. Each section lists what Reticle checks and gives one call you can run.
+
+Every predicate below is a `json` value you pass as `until` to `reticle_act_and_wait` (the consequence of an action) or as `predicate` to `reticle_assert` (a check with no action). The URLs, names and store paths are placeholders for your own. The full grammar is in [Predicates](/predicates).
+
+## Verifying agent-built changes
+
+This is what Reticle was built for: an agent says a change works, and Reticle checks it against the running app.
+
+- The request fired, returned the status you expected, and fired **once** (a double-submit is a `count` of 2).
+- Application state moved the way the UI says it did. A total on screen that disagrees with the store is a failure.
+- No console error appeared during the action.
+- A failure names the `file:line` to open (on React, and on any framework whose build plugin stamps source; see [Frameworks](/frameworks)).
+
+Click "Place order", then check all three at once:
+
+```json
+{
+  "kind": "allOf",
+  "predicates": [
+    { "kind": "net", "method": "POST", "urlContains": "/api/orders", "status": 201, "count": 1 },
+    { "kind": "state", "store": "cart", "path": "count", "equals": 0 },
+    { "kind": "console", "level": "error", "absent": true }
+  ]
+}
+```
+
+Once a journey has been driven, it is saved as a flow and replays with no model in the loop. `npx @reticlehq/server gate --since HEAD~1` fails unless a passing run covers every saved flow your edit touched.
+
+## Security checks
+
+This proves how your app behaves around security. It does not search for vulnerabilities, so it complements a vulnerability scanner rather than replacing one.
+
+- **Access control.** Signed in as a role that should be refused, the protected call returns `403` and the app shows the denial, not a success toast.
+- **Forbidden calls.** An endpoint that must not fire (an analytics beacon before consent, an admin API from a viewer's page) fires zero times: `{ "kind": "net", "urlContains": "/collect", "count": 0 }`.
+- **Secrets not rendered.** A value that must never reach the page is absent from its text. Separately, the SDK redacts credential-shaped values (tokens, API keys, passwords, card numbers) from captured request and response bodies, storage and state before they reach the agent, and shows them as `[REDACTED]`.
+- **CSP violations.** A Content Security Policy violation shows up as a console error (as a warning for report-only policies), so a CSP check needs nothing extra.
+
+As a viewer, click "Delete user" and require the refusal:
+
+```json
+{
+  "kind": "allOf",
+  "predicates": [
+    { "kind": "net", "method": "DELETE", "urlContains": "/api/admin/users", "status": 403 },
+    { "kind": "element", "query": { "role": "alert" }, "state": "visible" },
+    { "kind": "text", "contains": "sk_live_", "absent": true },
+    { "kind": "console", "contains": "Content Security Policy", "absent": true }
+  ]
+}
+```
+
+To check reachability for each role, see [Personas and simulation](#personas-and-simulation) below.
+
+## Accessibility and UX
+
+Reticle finds elements the way assistive technology does: by role and accessible name. That makes some accessibility behaviour directly checkable. For contrast, full screen-reader behaviour and complete WCAG coverage, pair it with an audit tool such as axe.
+
+- A control is reachable by its **role and accessible name**. An icon button with no name cannot be found with `{ "role": "button", "name": "Close" }`.
+- **Focus lands where it should.** When a dialog opens, focus moves into it (`state: "focused"`), and Reticle records focus dropping to `<body>` when a dialog closes.
+- **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.
+
+Open the "Delete project" dialog with `press` (`args: { "text": "Enter" }`) and require focus to move into it:
+
+```json
+{
+  "kind": "allOf",
+  "predicates": [
+    {
+      "kind": "element",
+      "query": { "role": "dialog", "name": "Delete project" },
+      "state": "visible"
+    },
+    { "kind": "element", "query": { "role": "button", "name": "Cancel" }, "state": "focused" }
+  ]
+}
+```
+
+## Performance and monitoring
+
+- **Request cardinality.** One keystroke in a debounced search sends one request, not one per character. The `duplicate-request` finding flags a write that fired more than once in a single action.
+- **Page performance entries.** The SDK records largest-contentful-paint, a running layout-shift total and long tasks as `perf` events, which you read with `reticle_observe { filters: ["perf"] }`. The layout-shift figure is a running sum without the windowing a Core Web Vitals CLS score uses, so it works for "no layout shift on load" and trends, not as an exact CWV number.
+- **Request timing.** Every captured request carries its duration in `reticle_observe { action: "network" }`.
+- **React render rate.** With the React adapter, the commit count is readable as the `__reticle_renders` store, so a component that re-renders continuously while the screen looks idle shows up.
+- **Recurring re-verification.** `npx @reticlehq/server verify <url>` replays your saved flows against a dev server or a staging/preview deployment and exits non-zero on a failure, so it runs in CI or on a schedule. The SDK refuses to connect in a production build, so this covers environments you control, not live production traffic.
+
+Type "shoes" into a debounced search box and require exactly one request:
+
+```json
+{ "kind": "net", "method": "GET", "urlContains": "/api/search", "count": 1 }
+```
+
+## SEO checks
+
+Reticle sees the rendered page and the routes, so it covers the behavioural half of SEO. It does not read `<head>` meta tags or score a page, so pair it with an SEO crawler for those.
+
+- `reticle_look { action: "page" }` reports the document `title` and the current route.
+- **Headings and links.** The page's heading exists under its accessible name, and `reticle_look { action: "find", by: "role", value: "link", attrs: ["href"] }` lists every link with its `href`.
+- **Redirects and routing.** A legacy URL lands on the right path: `{ "kind": "route", "pathname": "/pricing" }`.
+- **Broken links and dead controls.** `reticle_verify { action: "crawl" }` drives every reachable control and reports failed requests, console errors and controls that do nothing.
+
+After navigating to the old `/plans` URL, require the redirect and the page's main heading:
+
+```json
+{
+  "kind": "allOf",
+  "predicates": [
+    { "kind": "route", "pathname": "/pricing" },
+    { "kind": "element", "query": { "role": "heading", "name": "Pricing" }, "state": "visible" }
+  ]
+}
+```
+
+## 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.
+- **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).
+
+Have Reticle drive a first-time user's journey and record it:
+
+```bash
+npx @reticlehq/server verify http://localhost:3000 --explore --persona "a new user who signs up and creates a first project"
+```
+
+Then, signed in as a viewer, check what that role can reach:
+
+```json
+{
+  "kind": "allOf",
+  "predicates": [
+    { "kind": "element", "query": { "role": "button", "name": "Invite member" }, "absent": true },
+    { "kind": "net", "urlContains": "/api/billing", "count": 0 }
+  ]
+}
+```
+
+## Pairs well with
+
+Reticle checks what your app does from inside it. Some jobs belong to other tools, and it works alongside them:
+
+- **Pixel-level visual diffs:** a visual testing tool. Reticle can take screenshots, but its verdicts come from behaviour, not pixels.
+- **Driving sites you don't own, or a cross-browser matrix:** Playwright. Reticle needs its dev-only SDK in the app, and its driven browser is Chromium.
+- **Full WCAG audits:** axe or a similar audit tool.
+- **Vulnerability discovery:** a security scanner.
+
+What Reticle cannot see yet: IndexedDB, Web Workers, closed shadow roots and cross-origin iframes. When part of the page was out of reach, the verdict carries a `coverage` note, so a pass reads as "nothing failed in the part I could see". When the evidence cannot decide, the verdict is `unknown`, which is never counted as a pass.