@reticlehq/server 3.3.0 → 3.4.0

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/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".
 
 ---
 
@@ -640,7 +640,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 +732,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 +858,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.

package/docs/vs-screenshots.mdx

@@ -80,11 +80,11 @@ Those are real bugs and structural reads can miss them. Reticle has `reticle_scr
 
 The argument is not "screenshots are bad". It is that a screenshot cannot answer "did the code work", and that is the question an AI coding agent needs answered on every change.
 
-## The honest limits
+## What is measured, and what is not
 
-We have not proven that Reticle makes agents _fix_ more bugs. A controlled test did not show a fix-rate improvement; the benchmark was confounded and we are still working on measuring it properly.
+What is measured is detection: 10 of 10 injected regressions caught with zero false alarms, against 9 and 8 for the alternatives, and one false green against a Playwright script's 29 over an 88-bug registry.
 
-What is measured is detection: 10 of 10 injected regressions caught with zero false alarms, against 9 and 8 for the alternatives.
+What is not established is that Reticle makes agents _fix_ more bugs. A fix-loop test on a small fixture found the same fix rate with and without it; [Why Reticle](/why-reticle#what-the-fix-rate-test-measured) says what that test could and could not show.
 
 ## FAQ
 

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 is sent anywhere until you run `reticle login` and `reticle link`. Without them there is nowhere for anything to go.
+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).)
 
 ## On your machine
 
@@ -31,7 +31,7 @@ Network bodies are **not** captured by default. Page content that reaches a verd
 
 ## 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, `reticle push` has nothing to talk to and the sync path is a no-op. The code calls this the no-phone-home default.
+`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.
 
 Once linked, you choose what syncs:
 

package/docs/what-is-reticle.mdx

@@ -1,7 +1,7 @@
 ---
 title: What is Reticle?
 sidebarTitle: What is Reticle
-description: Reticle is a verification layer for AI coding agents. It runs a dev-only SDK inside your running web app so an agent can prove a change works, instead of guessing. What it is, what it is not, and what it needs.
+description: Reticle is a verification layer for AI coding agents. It runs a dev-only SDK inside your running web app so an agent can prove a change works, instead of guessing. What it is, where it fits beside other tools, and what it needs.
 icon: circle-question
 ---
 
@@ -12,37 +12,33 @@ 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. 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.
+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.
 
-Everything stays on your machine. No application code, DOM, network traffic, or console output leaves it.
+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).
 
-## What Reticle is not
+## Where it fits
 
-This is the section most people need, because Reticle sits next to several familiar categories without being any of them.
+Reticle sits next to several familiar categories, and it works alongside each of them.
 
-**Not a browser automation framework.** Playwright, Cypress and Selenium drive a browser from the outside and are excellent at it. Reticle runs inside the page you already have open. If you want to script a browser, use Playwright. Reticle is what an agent uses to answer "did the thing I just changed actually work?"
+**Browser automation.** Playwright, Cypress and Selenium drive a browser from the outside. Reticle runs inside the page you already have open and answers "did the thing I just changed actually work?" Playwright remains the tool for sites you don't own and for a cross-browser matrix.
 
-**Not a replacement for your test suite.** Unit and integration tests still do their job. Reticle covers the layer they structurally cannot reach: behaviour that only exists when the whole application runs. Many teams use both, and Reticle is often the thing that catches a suite passing over a broken app.
+**Your test suite.** Unit and integration tests keep doing their job. Reticle covers the layer they cannot reach: behaviour that only exists when the whole application runs, which is often where a suite passes over a broken app.
 
-**Not a screenshot or visual regression tool.** It can take screenshots, but the point is that it does not need to. Verdicts come from predicates over real events, a request with a status, a state path, a signal your code fired, so they do not break when a button moves four pixels. If pixel-perfect visual diffing is your goal, a dedicated visual testing service fits better.
+**Visual testing.** Reticle can take screenshots, but its verdicts come from predicates over real events (a request with a status, a state path, a signal your code fired), so they do not break when a button moves four pixels. For pixel-level diffs, pair it with a visual testing tool.
 
-**Not a monitoring or observability product.** Reticle is a development-time tool aimed at localhost. It is not an APM, not error tracking, and it does not watch production.
+**Security, accessibility, performance and SEO.** Reticle checks how your running app behaves in each: access control by role, calls that must never fire, focus and keyboard behaviour, request counts and long tasks, titles, links and redirects. It pairs with a vulnerability scanner, a full WCAG audit tool such as axe, and an SEO crawler. [Use cases](/use-cases) has what each check covers.
 
-**Not an accessibility auditor.** `reticle_snapshot` addresses elements by role and name, which is not the same as auditing contrast, focus order, or screen reader behaviour. Use a dedicated accessibility tool for that.
+**Monitoring.** Reticle runs against environments you control (a dev server, a staging or preview deployment) and replays saved flows in CI. The SDK refuses to connect in a production build, so it complements an APM or error tracker rather than watching live traffic.
 
-**Not an AI model, and not an agent.** Reticle has no model of its own and makes no decisions. It gives an agent you already use a way to see the running app. Your agent, your model, your keys.
+**Your agent.** Reticle has no model of its own for the verify loop. It gives the agent you already use a way to see the running app. Your agent, your model, your keys. (`explore` can drive a journey for you with a model inside the daemon; see [Autodrive](/autodrive).)
 
-**Not a hosted service that receives your application data.** The daemon runs on your machine and the SDK runs in your browser. Anonymous product analytics are sent unless you opt out, and they never include your code or your application's data. See the [Telemetry Policy](https://www.reticle.sh/legal/telemetry).
-
-**Not a way to make a failing check pass.** A verdict of `unknown` means Reticle drove the app and could not tell. It is deliberately not rounded up to a pass, because a verification tool that flatters you is worse than none.
+**The verdict.** A verdict of `unknown` means Reticle drove the app and could not tell. It is deliberately not rounded up to a pass.
 
 ## What Reticle needs
 
-Honest constraints, so you can tell in a minute whether it fits:
-
-- **A web application you can run locally**, with its dev server. Reticle attaches; it does not start one.
-- **A build step it can hook**, or two lines added by hand. Vite, Next.js, Remix and Astro are proven by gates in the repository. The SDK is framework agnostic and usually connects elsewhere, with reduced source mapping.
+- **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.**
 
@@ -59,5 +55,6 @@ Side by side with the tools people ask about most:
 ## Where to go next
 
 - [Quickstart](/quickstart) gets a real verdict out of your own app in about five minutes.
-- [Why Reticle](/why-reticle) is the argument, with the evidence and the cases where it loses.
+- [Why Reticle](/why-reticle) is the argument, with the evidence and what pairs well with it.
+- [Use cases](/use-cases) covers what people verify with it.
 - [For agents](/for-agents) is written for the agent rather than for you.

package/docs/why-reticle.mdx

@@ -63,37 +63,30 @@ Observing one real dashboard once, with no bug involved:
 That last column is the one that matters more than the token counts. The other tools can _describe_ what a page looks like. Only Reticle can check whether the thing the app itself considers success actually happened.
 
 <Card title="How every number was measured" icon="chart-column" href="/benchmarks">
-  The full method, the raw data, and the scenarios where Reticle comes second.
+  The full method, the raw data, and the scenarios where the tools tie.
 </Card>
 
-## Where Reticle loses
+On raw cost per glance, Chrome DevTools MCP is cheaper: 758 tokens against 815. It catches fewer bugs, which is why the efficiency column favours Reticle.
 
-A benchmark that only shows you the wins is an advertisement wearing a lab coat. Ours doesn't.
+## What the fix-rate test measured
 
-- **Sites you don't own.** Reticle needs a dev-only SDK inside the app. If you're driving a third party's website, use Playwright. That is what it's for, and it's excellent at it.
-- **Pixels.** Reticle reads the program, not the screen. If your bug is "the button is three pixels too far left", Reticle is the wrong instrument.
-- **Chrome DevTools MCP is cheaper per look.** 758 tokens against our 815. It catches fewer bugs, so the efficiency works out in our favour, but on raw cost per glance it wins.
+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.
 
-## What we have not proven
+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).
 
-Being honest here costs us something, and we'd rather pay it than have you find out later.
+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.
 
-We ran a controlled test of whether an agent equipped with Reticle _fixes_ more bugs than one without it. **It did not show a fix-rate improvement.** The benchmark was confounded in ways we can point at, and we don't consider the question settled. But we are not going to claim a number we didn't measure.
+That is what Reticle is designed to improve: not the agent, but the verdict it reports. A broken build reads as broken, a failure arrives with the evidence and the `file:line`, and "I couldn't tell" is reported as that. In the 88-bug head-to-head against a Playwright script, Reticle reported one false green where the script reported 29.
 
-What Reticle demonstrably does is catch failures that are invisible to the alternatives, and hand back the file and line to go fix. Whether that translates into a better fix rate is a separate question, and we're still working on measuring it properly.
+## When to use it
 
-## When you should use it
+You own the app, an agent edits it, and you want the agent to prove its work rather than assure you of it. It needs a dev build it can instrument, and React (and any framework whose build plugin stamps source) adds source pointers on top. [Use cases](/use-cases) covers what people check with it beyond change verification, from access control to accessibility.
 
-<CardGroup cols={2}>
-  <Card title="A good fit" icon="circle-check">
-    You own the app. An agent edits it. You want the agent to prove its work rather than assure you
-    of it. React gets you source pointers on top.
-  </Card>
-  <Card title="A bad fit" icon="circle-xmark">
-    You're testing a site you don't control, you need pixel-level visual regression, or your app has
-    no dev build to instrument.
-  </Card>
-</CardGroup>
+## Pairs well with
+
+- **Playwright** for driving sites you don't own and a cross-browser matrix. Reticle needs its dev-only SDK inside the app.
+- **A visual testing tool** for pixel-level regression. Reticle reads the program, not the screen, so "the button is three pixels too far left" is a job for pixels.
+- **axe** for full WCAG audits, and **a security scanner** for vulnerability discovery.
 
 ## The one-sentence version
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@reticlehq/server",
-  "version": "3.3.0",
-  "description": "Reticle bridge + MCP server. Hosts the browser WS endpoint and exposes MCP tools to the coding agent.",
+  "version": "3.4.0",
+  "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",
   "types": "./dist/index.d.ts",
@@ -19,24 +19,24 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.30.1",
     "ws": "^8.21.3",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.24.0",
-    "@reticlehq/engine": "3.3.0",
-    "@reticlehq/browser": "3.3.0",
-    "@reticlehq/init": "3.3.0",
+    "@reticlehq/browser": "3.4.0",
+    "@reticlehq/init": "3.4.0",
+    "@reticlehq/engine": "3.4.0",
     "open-verification": "1.0.0",
-    "@reticlehq/core": "3.3.0"
+    "@reticlehq/core": "3.4.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
     "@types/ws": "^8.5.13",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.1"
   },
   "optionalDependencies": {
     "pixelmatch": "^7.2.0",
-    "playwright": "^1.62.1",
+    "playwright": "^1.63.0",
     "pngjs": "^7.0.0"
   },
   "license": "FSL-1.1-ALv2",
@@ -60,6 +60,7 @@
     "mcp",
     "ai-agents",
     "testing",
+    "verification",
     "cli"
   ],
   "reticle": {

package/dist/judgement/capsule/minimize.d.ts

@@ -1,12 +0,0 @@
-/**
- * Bug-capsule minimization — first cut: prefix-trim. A recorded flow that fails is often mostly setup;
- * the capsule should be the SMALLEST flow that still reproduces the failure, so a regression flow stays
- * fast and legible. Prefix-trim drops leading steps while the failure persists — the cheap, deterministic
- * v1 (delta-debugging over arbitrary subsets is a later refinement). The `stillFails` predicate is
- * injected (a real replay), so this stays pure and unit-testable.
- */
-/**
- * Return the shortest trailing sub-flow that still fails, by removing leading steps one at a time while
- * `stillFails` holds. Never trims below one step. Deterministic given a deterministic predicate.
- */
-export declare function prefixTrim<T>(steps: readonly T[], stillFails: (candidate: readonly T[]) => Promise<boolean>): Promise<T[]>;