@reticlehq/server 2.8.0 → 2.9.0

package/dist/tools/tools.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { NoSessionAction, QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { withSizeCost } from '../session/output-budget.js';
 import { applySnapshotDelta, SnapshotCache } from './snapshot-delta.js';
@@ -82,6 +82,15 @@ const RAW_TOOLS = [
                 .string()
                 .optional()
                 .describe('Present ONLY when `sessions` is empty: why nothing is connected, and the next action that fixes it. An empty list is never the end of the road — read this before concluding the app cannot be driven.'),
+            next_action: z
+                .object({
+                action: z.nativeEnum(NoSessionAction),
+                command: z.string().optional(),
+                port: z.number().optional(),
+                reason: z.string(),
+            })
+                .optional()
+                .describe("Present ONLY when `sessions` is empty: the same answer as `why`, executable. `command` is the LITERAL command to run, sourced from this project's own package.json scripts and lockfile — it is absent, never guessed, when the project declares no dev script. `action` is one of start_dev_server | run_init | open_app | reopen_app."),
         },
         handler: async (deps) => {
             const provider = deps.realInput;
@@ -97,7 +106,14 @@ const RAW_TOOLS = [
             // rather than only when a later tool fails for want of a session.
             if (0 === sessions.length) {
                 const why = deps.sessions.noSessionHint();
-                return { sessions, ...(why === undefined ? {} : { why }) };
+                // The executable half. `why` is for the human reading the transcript; this is the one the
+                // agent acts on, so it never has to parse a paragraph to find a command inside it.
+                const next = deps.sessions.noSessionNextAction();
+                return {
+                    sessions,
+                    ...(why === undefined ? {} : { why }),
+                    ...(next === undefined ? {} : { next_action: next }),
+                };
             }
             return { sessions };
         },
@@ -126,11 +142,18 @@ const RAW_TOOLS = [
                 .string()
                 .optional()
                 .describe('Indented ARIA tree of every element on the page (or the scoped subtree).'),
-            status: z.object({ route: z.string(), title: z.string().optional() }).optional(),
+            status: z
+                .object({
+                route: z.string(),
+                title: z.string().optional(),
+                visibleDialogs: z.array(z.string()).optional(),
+                overlayHidingPage: z.string().optional(),
+            })
+                .optional(),
             mode: z
                 .string()
                 .optional()
-                .describe('delta | unchanged when diff:true returned a change set.'),
+                .describe('full | delta | unchanged — which kind of diff response this is.'),
             delta: z
                 .object({
                 added: z.array(z.string()),
@@ -140,6 +163,15 @@ const RAW_TOOLS = [
             })
                 .optional()
                 .describe('Only present on a diff:true call that found changes.'),
+            changed: z
+                .array(z.string())
+                .optional()
+                .describe('Elements whose value changed in place (same ref, different content) — not a structural add/remove.'),
+            changedCount: z.number().optional().describe('Number of elements in `changed`.'),
+            reason: z
+                .string()
+                .optional()
+                .describe('Why mode is "full": first snapshot for this route, or route changed.'),
             cost: z
                 .object({ bytes: z.number(), tokens: z.number() })
                 .optional()
@@ -380,6 +412,15 @@ const RAW_TOOLS = [
              * Reticle build plugin in dev; absent in production builds.
              */
             source: z.string().optional(),
+            /**
+             * Why `source` is missing, when it is.
+             *
+             * Distinguishes "this element has no stamp" from "nothing on this page has one, so the
+             * stamping loader is not running" — the second means `file:line` is unavailable for the
+             * whole session and the fix is a build-config change, which used to be discoverable only by
+             * reading the adapter's own source.
+             */
+            sourceUnavailable: z.string().optional(),
             /**
              * Component identity from the framework adapter (@reticlehq/react).
              *

package/dist/tools/unadvertised-help.js

@@ -1,9 +1,10 @@
 /**
  * What to say when an agent calls a real Reticle tool that this profile does not advertise.
  *
- * The default profile advertises 16 of 46 tools. That is deliberate — every advertised tool's schema
- * is re-sent on every turn, and the trim is most of why `hybrid` is cheap — and the other 30 stay
- * fully callable through `reticle_run`, which `profile-reachability.test.ts` guards.
+ * The default surface advertises 18 of 48 tools, and the extended one 30. That is deliberate — every
+ * advertised tool's schema is re-sent on every turn, and editors budget MCP tools as a COUNT shared
+ * across every connected server — and everything omitted stays fully callable through `reticle_run`,
+ * which `surface-reachability.test.ts` guards.
  *
  * The gap was in the ERROR. The MCP SDK answers `Tool <name> not found`, which is indistinguishable
  * from "this tool does not exist", so an agent that trusts it stops trying. Reported from a real
@@ -14,7 +15,7 @@
  * and the switch that makes it stop being necessary.
  */
 import { ReticleTool } from './tool-names.js';
-import { TOOL_SURFACE, TOOL_PROFILE_ENV } from './tool-surface.js';
+import { ADVERTISE_ALL_ENV } from './tool-surface.js';
 import { mergedNameRedirect, mergedNameMessage } from './merged-name-redirect.js';
 /**
  * Guidance for `name`, or undefined when there is nothing useful to add — the tool IS advertised (so
@@ -34,6 +35,8 @@ export function unadvertisedToolHelp(name, advertised, known) {
         `away. It is NOT missing: invoke it with ` +
         `${ReticleTool.RUN} { tool: "${name}", args: { ... } }. ` +
         `Call ${ReticleTool.TOOLS} { names: ["${name}"] } for its parameters. ` +
-        `If you need it repeatedly, set ${TOOL_PROFILE_ENV}=${TOOL_SURFACE.ALL} to advertise ` +
-        `every tool directly.`);
+        `If you need it repeatedly, start the daemon with ${ADVERTISE_ALL_ENV}=1 for the extended ` +
+        `surface. That is read by the DAEMON at startup, so it takes effect on the next daemon, and it ` +
+        `advertises MORE tools rather than all of them — editors budget MCP tools as a shared count, so ` +
+        `${ReticleTool.RUN} stays the way to reach the rest.`);
 }

package/docs/README.md

@@ -49,8 +49,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [for-agents.md](for-agents.md) | how to fetch these docs as Markdown or `llms.txt` |
 | [architecture.md](architecture.md) | how it works, and why it is built this way |
 | [platform-integration.md](platform-integration.md) | Vite, Next, Remix, Astro, plain HTML |
-| [desktop.mdx](desktop.mdx) | why desktop is different, and what only Reticle does there |
-| [desktop-apps.md](desktop-apps.md) | Electron and Tauri, in full |
+| [desktop.mdx](desktop.mdx) | Electron and Tauri in full: setup, IPC, screenshots, headless, troubleshooting |
 | [frameworks.mdx](frameworks.mdx) | what is supported, what is wired-but-unverified, and the wiring |
 | [state-management.mdx](state-management.mdx) | zustand, Redux, and eight adapters |
 | [instrumentation.mdx](instrumentation.mdx) | stores, signals, testids, and how verdicts get stronger |

package/docs/actions.mdx

@@ -1,12 +1,14 @@
 ---
-title: Action reference: lights, camera, click
+title: 'Action reference: lights, camera, click'
 sidebarTitle: Actions
 description: Every action reticle_act and reticle_act_and_wait can perform, with its arguments and the one that has a history.
 icon: hand-pointer
 ---
 
+Every action Reticle can perform takes the same shape: a `ref` from [`reticle_snapshot`](/tools-snapshot) or [`reticle_query`](/tools-query), an `action` name, and an optional `args` object. The same seventeen actions are available on [`reticle_act`](/tools-act), which proves nothing, and on [`reticle_act_and_wait`](/tools-act-and-wait), which returns a verdict.
+
 ```json
-{ "ref": "e42", "action": "fill", "args": { "value": "hello" } }
+{ "ref": "e104", "action": "fill", "args": { "value": "reticle" } }
 ```
 
 | Action | Arguments | Notes |
@@ -22,10 +24,39 @@ icon: hand-pointer
 | `submit` | none | Submits the element's `<form>` |
 | `press` | `{ text }` | The key **name**: `Escape`, `Tab`, `Enter` |
 | `scrollIntoView` | none |  |
-| `upload` | `{ name, content?, type? }` | Sets a file on `<input type="file">` |
-| `drag` | `{ toRef }` | Pointer-based drag (dnd-kit, react-beautiful-dnd) plus HTML5 DnD |
+| `upload` | `{ content?, name?, type? }` | Sets a file on `<input type="file">`. All three default, to `"reticle test file"`, `"file.txt"` and `"text/plain"` |
+| `drag` | `{ toRef }` | Pointer-based drag (dnd-kit, react-beautiful-dnd) plus HTML5 DnD. `target` is an alias |
 | `webmcp` | `{ tool, params }` | Calls a `navigator.modelContext` tool, if the site exposes one |
 
+### Arguments that are not actions
+
+Three `args` keys apply across actions rather than belonging to one:
+
+| Key | What it does |
+| --- | --- |
+| `native` | Forces a trusted native click instead of the occlusion-honest synthetic path. For file pickers and clipboard access |
+| `holdMs` | Keeps the pointer **down** for that long between mousedown and mouseup. The only way to drive a hold-to-confirm control. `effect.heldMs` reports the hold actually achieved |
+| `confirmDangerous` | A permission gate for a control Reticle judged destructive. It is **not** a duration |
+
+<Warning>
+  `confirmDangerous` and `holdMs` are routinely confused because both show up around delete buttons.
+  `holdMs` is how long the button is held; `confirmDangerous` is permission to press it at all.
+  Passing the wrong one gets you either a refusal or a press that was never held.
+</Warning>
+
+### The refusal you will meet first
+
+Reticle blocks a control that looks destructive before acting on it:
+
+```json
+{
+  "error": "potentially destructive action blocked; retry with args.confirmDangerous=true",
+  "recovery": "Reticle blocked a potentially destructive control (delete, remove, revoke…) on purpose. If you mean it, retry the same action with args.confirmDangerous set to true. This is a deliberate refusal, not a defect: there is nothing to report."
+}
+```
+
+A stale ref is refused the same way, with `"ref 'e303' no longer resolves to an element"` and a recovery note telling you to re-query. Both refusals cost a turn and prevent a false green, which is the trade.
+
 ## `fill` versus `type`
 
 `fill` replaces. `type` appends. Reaching for `type` when you meant `fill` is how a field ends up containing `hellohello`, and neither call will complain.
@@ -54,9 +85,9 @@ Several actions in one round trip:
 ```json
 {
   "steps": [
-    { "ref": "e101", "action": "fill", "args": { "value": "admin@reticle.dev" } },
-    { "ref": "e102", "action": "fill", "args": { "value": "hunter2" } },
-    { "ref": "e103", "action": "click" }
+    { "ref": "e603", "action": "fill", "args": { "value": "admin@reticle.dev" } },
+    { "ref": "e604", "action": "fill", "args": { "value": "hunter2" } },
+    { "ref": "e605", "action": "click" }
   ]
 }
 ```
@@ -78,7 +109,9 @@ Several actions in one round trip:
 
 ## What every action reports
 
-`valueChanged`, `focusMoved`, `domMutatedWithin`, `defaultPrevented`, `occluded` and `occludedBy`. Plus the element's `testid`, `component` and `source` file and line.
+`dispatched`, `targetMatched`, `visible`, `enabled`, `valueChanged`, `focusMoved`, `domMutatedWithin`, `defaultPrevented`, `occluded`, `occludedBy` and `scrolledIntoView`. Plus the element's `testid`, `component`, `role`, `name` and `source` file and line.
+
+Fields sitting at their uninformative default are **omitted**, so a clean action collapses to its consequence. A missing `visible` means `true`, not `false`. Read an absence as "nothing to report" rather than as a failure.
 
 `occluded` is the answer to a large share of "the button doesn't work" reports: the click landed on the modal overlay sitting on top of it.
 

package/docs/agent-cheatsheet.md

@@ -4,6 +4,8 @@ description: 'One screen to get fluent: the look → act → observe → assert
 icon: bolt
 ---
 
+The loop is **look → act → observe → assert**, and only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Reach for `reticle_act_and_wait({ ref, action, until })` first: it names the expected consequence before the action, which is the difference between a check and a rationalisation. `verified: "unknown"` is not a pass.
+
 One screen to get fluent. Reticle is the **proof layer for AI agents**: no screenshots, no vision model, evidence not prose. Everything below returns structured data. Full guide: [usage.md](usage.md).
 
 ## The core loop: look → act → observe → assert
@@ -109,9 +111,9 @@ A claim is real only when the layers agree. Check more than the UI:
 
 The tools advertised DIRECTLY, i.e. what you'll use 90% of the time. Everything else is one `reticle_run` away (see Token note below).
 
-`reticle_sessions` · `reticle_navigate` · `reticle_snapshot` · `reticle_query` · `reticle_act` · `reticle_act_sequence` · `reticle_act_and_wait` · `reticle_observe` · `reticle_network` · `reticle_console` · `reticle_wait_for` · `reticle_assert` · `reticle_state` · `reticle_inspect` (DOM node → `src/App.tsx:104`) · `reticle_capabilities` (the app's whole testable surface in one call; `{fromDisk:true}` needs no browser) · `reticle_feedback` (tell the maintainers what is missing) · `reticle_session` (hand back: `{action:"yield"}` the moment you stop driving, `{action:"resume"}` after a human pause).
+`reticle_sessions` · `reticle_navigate` · `reticle_snapshot` · `reticle_query` · `reticle_act` · `reticle_act_sequence` · `reticle_act_and_wait` · `reticle_observe` · `reticle_network` · `reticle_console` · `reticle_wait_for` · `reticle_assert` · `reticle_state` · `reticle_inspect` (DOM node → `src/App.tsx:104`) · `reticle_feedback` (tell the maintainers what is missing) · `reticle_session` (hand back: `{action:"yield"}` the moment you stop driving, `{action:"resume"}` after a human pause).
 
-Frequently useful but NOT core, so reach them through `reticle_run({ tool, args })`: `reticle_domain` (learn the app + gaps), `reticle_capabilities` (the app's declared testable surface), `reticle_baseline {action:"diff"}`, `reticle_project` (run history).
+Frequently useful but NOT core, so reach them through `reticle_run({ tool, args })`: `reticle_capabilities` (the app's whole testable surface in one call; `{fromDisk:true}` needs no browser), `reticle_domain` (learn the app + gaps), `reticle_baseline {action:"diff"}`, `reticle_project` (run history).
 
 **Reach past core when…** you need to record/replay a journey (`reticle_record {action:"start"}/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_flow_heal`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_crawl` clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_query` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven mode), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session {action:"end"}` / `reticle_session {action:"resume"}` / `reticle_session {action:"messages"}`, and **`reticle_session {action:"review"}`** to drain + fix the bugs the human flagged from the panel).
 

package/docs/architecture.md

@@ -4,6 +4,8 @@ description: 'The moving parts, the data flow between them, and the design decis
 icon: sitemap
 ---
 
+Reticle has three moving parts: a dev-only **SDK** inside your page that instruments the DOM, network, console, routing and framework state; a local **server** that runs a WebSocket bridge to that SDK and an MCP server for your agent; and a git-checked **`.reticle/` workspace** holding flows, baselines and run artifacts. Your agent calls an MCP tool, the server turns it into a command over the WebSocket, the SDK runs it in the real page and streams structured events back.
+
 > For engineers evaluating Reticle, integrating it at scale, or contributing. It explains the moving parts, the data flow, and the design decisions behind them. If you just want to get running, start with [getting-started.md](getting-started.md); come back here when you want to know _why_.
 
 ---
@@ -40,6 +42,10 @@ Reticle is a pnpm + Turborepo monorepo. The split is not cosmetic: each boundary
 | `@reticlehq/server` | Node | The bridge, the MCP server, the `reticle` CLI, flow/run storage | Never imports DOM APIs |
 | `@reticlehq/react` | the browser | The SDK **kit** you install in a browser app: re-exports the browser sensor (so one install gives both `reticle` and `install`) and maps a DOM node → React component → source `file:line` | Core works without the source-mapping half |
 | `@reticlehq/babel-plugin`, `@reticlehq/next`, `@reticlehq/vite-plugin` | build time | Stamp `data-reticle-source` for source mapping (and, for Vite, inject `connect()`) | Plain tooling |
+| `@reticlehq/electron` | Electron main process | Adapter for the desktop runtime: IPC observer, main-process capture | Desktop-only, outside the web gates |
+| `packages/tauri` (`reticle-tauri`) | Tauri (Rust) | Capture backend for the Tauri desktop runtime | Rust, outside every JS gate; compiled by CI's `rust`/`rust-macos` jobs |
+| `@reticlehq/test` | Node (dev dependency) | Spec runner + matchers used by CI's own test suites | Peer dependency on `vitest` |
+| `@reticlehq/eslint-plugin` | dev tooling | Repo-internal lint rule: a state change must fire a signal | Dev-only, never shipped in a user's bundle |
 
 > Note: pre-2.0, `@reticlehq/core` was a single umbrella package that re-exported all of the above under subpaths. In 2.0 the umbrella was retired and `@reticlehq/core` became the bottom-of-graph wire contract.
 

package/docs/benchmarks.md

@@ -4,6 +4,14 @@ description: 'How we measure Reticle, what each number actually means, and the p
 icon: chart-column
 ---
 
+Two different measurements, because there are two different questions.
+
+Against a **Playwright script** over an 88-bug registry, each tool running its own native check deterministically with no model in the loop, Reticle caught **85 of 88** and Playwright **59 of 88**, both with zero false alarms on the clean build. The gap is not spread evenly: it is 26 bugs Playwright **structurally cannot** see, and on everything observable from outside the app the two tie exactly. See Part 5a.
+
+Against **Playwright MCP and Chrome DevTools MCP**, the agent-driven tools where cost per look matters, Reticle caught 10 of 10 injected regressions to Playwright MCP's 9 and DevTools' 8, averaging 815 tokens per look against 1,292 and 758. See Part 5b.
+
+Where Reticle loses is stated plainly in Part 5, and it loses in more places than these two tables show.
+
 > This page assumes **zero** testing background. By the end you'll understand what software testing is, why AI coding agents made it urgent, how to tell a good verification tool from a bad one, and exactly how Reticle measures up against the main alternatives, including the places Reticle loses. If a term looks like jargon, it's defined the first time it appears.
 >
 > _Where the pictures come from, stated accurately: the **SVG charts** (`bench/artifacts/`) are generated from measured raws by `bench/harness/charts.mjs`. The **headline PNG cards** (`assets/readme/`) are screenshots of hand-authored HTML in `assets/benchmarks/src/`, rendered by `assets/benchmarks/render.mjs`; their figures are typed in by a human and are **not** read from `history.jsonl`, which this line previously claimed. Treat a card as a design asset that has to be updated by hand when a number moves, and `bench/SCORECARD.md` (plus its freshness banner) as the source of truth._
@@ -59,7 +67,9 @@ We compare Reticle against the two most credible agent-native browser tools, bec
 - **Chrome DevTools MCP** is Google's tool exposing Chrome's DevTools to an agent.
 - **(Baseline) screenshot agents**, the common "let the model look at a picture" approach.
 
-Why not compare to traditional test frameworks (Playwright the library, Cypress, etc.)? Because those are written and maintained by humans; they don't answer "can an _agent_ verify its own work in the loop." The three above do, so it's an apples-to-apples agent comparison.
+Why not compare to traditional test frameworks (Playwright the library, Cypress, etc.) on the token passes? Because those are written and maintained by humans; they don't answer "can an _agent_ verify its own work in the loop," and a hand-written script has no token cost to compare. The three above do, so the cost comparison stays apples-to-apples.
+
+There **is** a comparison against a Playwright script, and it answers a different question: not "what does it cost an agent to look" but "what can each tool structurally SEE, at all." That one is in Part 5a. It runs no model, so nothing about it depends on how well an agent drives, which is what makes it the more durable of the two results.
 
 Tool versions are pinned in `bench/raw/run-meta.json` so any run is reproducible.
 
@@ -101,7 +111,45 @@ We ran this two ways on purpose: a **controlled toy app** (where we can inject e
 
 ![One honest test, two apps: Reticle has the highest Verification Efficiency on the controlled app and the lowest observation cost on the real dashboard](/images/bench-two-apps.png)
 
-### 5a. The controlled toy app (the demo)
+### 5a. The 88-bug head-to-head against a Playwright script
+
+The largest and least model-dependent measurement here. An **88-bug registry** (`bench/pw-vs-reticle/bugs.mjs`), each bug injected into the same app, each tool running its NATIVE check: a Playwright script doing what a Playwright script does, Reticle doing what Reticle does. **No LLM in the loop**, so nothing depends on how well an agent happened to drive.
+
+A tool "catches" a bug when its check correctly FAILS on the broken build **and** does not fail on the clean one. Failing on the clean build is a false alarm and is counted against the tool, not ignored.
+
+|                                        |     Reticle | Playwright script |
+| -------------------------------------- | ----------: | ----------------: |
+| Bugs caught                            | **85 / 88** |           59 / 88 |
+| Of what it can structurally catch      | **85 / 86** |           57 / 60 |
+| **False greens** (broken, reported OK) |       **1** |            **29** |
+| False alarms on the clean build        |           0 |                 0 |
+| Output bytes per bug                   |       9,261 |         **5,849** |
+
+Three things about that table are more important than the headline number.
+
+**Two of Reticle's three non-catches are not misses.** They are the registry's `false-positive-trap` cases, builds that look broken and are not: flagging them would itself be a false alarm, so 0 of 2 is the correct score and a tool that "caught" them would be worse. The third, `iframe-stale-data` (deep-dom), is a **genuine miss** and is counted as a false green above rather than explained away.
+
+**These figures were re-derived on the 2.9.0 branch and they moved.** The numbers first published here were recorded on 2026-07-24; 615 commits touched the harness, the fixture app, the SDK or the server before anybody re-ran it. Detection moved 86 → 85 and 60 → 59, and the per-bug output figure **inverted**: Reticle was published as the leaner of the two at 4,134 B against 7,899 B and measures 9,261 B against 5,849 B here. Reticle's own check being the more expensive one does not contradict the token-cost sections below. Those measure an AGENT-driven look against MCP tools, which is a different question. It does mean the earlier claim should not be repeated. Re-run `bench/pw-vs-reticle/run.mjs` before quoting any of this.
+
+**Reticle does not win everything, and the ties are the honest part.** On everything observable from outside the app the two are exactly level: console 6/6 against 6/6, network 8/8 against 8/8, storage 5/5 against 5/5, visual UI 16/16 against 16/16, plus routing, timing, paint and chart bugs. Any evaluate-capable tool matches Reticle on what the DOM, the network buffer or a screenshot can show.
+
+**The gap is one specific shape:** bugs where the screen is right and the app is wrong.
+
+| Category | Reticle | Playwright | The bug |
+| --- | --: | --: | --- |
+| state | 8/8 | **0/8** | the UI renders a plausible value that contradicts the app's own store |
+| business-logic | 6/6 | **0/6** | an action corrupts a field nothing renders. The record is wrong, the screen is fine |
+| signal | 4/4 | **0/4** | an event the app emits about itself (hydration done, error boundary caught) |
+| net-status | 4/4 | 1/4 | a swallowed 4xx/5xx. The request failed, a catch block ate it, the UI rendered |
+| streams | 3/3 | 0/3 | an SSE or WebSocket frame anomaly a request-level view cannot see |
+| perf | 3/3 | 1/3 | layout shift, or a render storm where the DOM is identical |
+| deep-dom | 2/3 | 2/3 | a break deep in a subtree a snapshot elides. The one both now miss is `iframe-stale-data` |
+
+That is the whole claim, stated as narrowly as it deserves: Reticle sees inside the running app, so it catches the class of bug where the outside looks correct. Outside that class it ties, and it says so.
+
+Bug registry: `bench/pw-vs-reticle/bugs.mjs`. Runner: `bench/pw-vs-reticle/run.mjs`, which regenerates `results.json` locally (run artifacts are not committed). Scorecard: `bench/FALSE-GREEN-SCORECARD.md`.
+
+### 5b. The controlled toy app (the demo)
 
 Measured on the observation-cost pass (numbers regenerate from `bench/raw/`):
 
@@ -115,7 +163,7 @@ Measured on the observation-cost pass (numbers regenerate from `bench/raw/`):
 - DevTools is a hair cheaper per look (758 vs 815 tokens), **but it's cheaper because it catches less.** On the metric that combines both (Verification Efficiency), Reticle leads at 12.27 vs 10.55.
 - Playwright catches a lot but is ~1.6× more expensive per look, so its efficiency is lowest here.
 
-### 5b. A real production app (the Reticle dashboard)
+### 5c. A real production app (the Reticle dashboard)
 
 A toy app is a fair lab, but it's small. The harder, more honest test is a **real, complex app**. Take the [Reticle](https://reticle.sh) dashboard itself: React 19, authentication, live data, ~15 routes, a node-graph view, virtualized lists. We embedded the SDK (the Vite plugin) and drove the authenticated app with all three tools. Observing it **once** (the primary snapshot + the network log):
 
@@ -129,13 +177,13 @@ A toy app is a fair lab, but it's small. The harder, more honest test is a **rea
 
 On a small page everything is cheap and the gap is modest. On a **big** page the structured read pulls ahead: Reticle is **2.1× leaner than Playwright MCP** and the cheapest overall. And only Reticle can read the app's own program state (`authenticated`, `userId`, `activeProjectId`) and assert the login _actually worked_ from a signal the app emits. The others can only look at the DOM and the network and **guess**.
 
-### 5c. The kicker: a real bug, caught live
+### 5d. The kicker: a real bug, caught live
 
 Here's what makes the real-app test matter. On the **very first run, before we instrumented anything**, Reticle's network observation flagged two endpoints returning **`500`**: `GET /api/v1/projects` and `/recovery/incidents`, both failing with `column "deleted_at" does not exist` (a database migration that hadn't been applied). **The page rendered fine.** The sidebar loaded, nothing looked broken; a screenshot agent would have called it _"done."_ Reticle saw the broken backend underneath, in one look.
 
 That is the whole thesis, demonstrated on a real app we didn't cherry-pick: **"looks done" ≠ "is done," and the difference is usually non-visual.** (We then fixed the migration; all endpoints 200.)
 
-### 5d. What each tool can actually do
+### 5e. What each tool can actually do
 
 Cost is half the story; capability is the other half. The marks below are what's **first-class and built-in** to each tool (all three are good tools, and they compose: drive with theirs, assert with Reticle):
 
@@ -153,10 +201,10 @@ Honesty is the point of this page, so here are the places Reticle does **not** w
 
 The numbers above are for **one** verification. But a test suite's real job is the **same** check, over and over, every commit, every CI run. Here the picture changes shape:
 
-- Reticle records a flow once, then **replays it with no AI model at all** (re-resolving each element and re-asserting the outcome) for **~175-210 tokens per run**.
+- Reticle records a flow once, then **replays it with no AI model at all** (re-resolving each element and re-asserting the outcome) for **~239 tokens per run** (re-measured 2026-08-11; it was ~175 before each flow started carrying a success oracle).
 - Playwright MCP and DevTools MCP have no replay: re-checking means an agent **re-drives the whole flow with the model every time**, costing tens of thousands of tokens per run.
 
-That's a **~128-184× cost difference per re-run**, and it grows with how often you run. This is where the "much cheaper than screenshots" claim becomes dramatic rather than incremental.
+That's a **~127× cost difference per re-run**, and it grows with how often you run. This is where the "much cheaper than screenshots" claim becomes dramatic rather than incremental.
 
 ![Re-run cost: Reticle replays with no model; competitors re-drive every time](/images/chart-avg-tokens.svg)
 
@@ -188,7 +236,7 @@ A fleet of agents (or a parallel suite) verifying the same app doesn't need a br
 ## Part 7: What this means for you
 
 - **If you're a developer using an AI agent:** Reticle lets the agent confirm its own change actually worked (across the network call, the console, the route, the state) for a few hundred tokens, not a screenshot's thousands. "Done" starts meaning done.
-- **If you run CI / a platform team:** the replay pass is the headline: deterministic re-verification with no model, so a known flow re-checks for ~200 tokens at ~0% flake, every commit.
+- **If you run CI / a platform team:** the replay pass is the headline: deterministic re-verification with no model, so a known flow re-checks for a couple of hundred tokens at ~0% flake, every commit.
 - **If you're evaluating tools:** the axis that matters is _bugs caught per token, gated on catching them all_. Cheapness that misses regressions is a false economy.
 
 You are now equipped to read any verification benchmark critically: ask "what's the catch rate, what's the false-positive rate, and what's the cost _per re-run_?" Then be suspicious of any vendor that won't show you where they lose.
@@ -204,15 +252,15 @@ A fair question from a large engineering org (think a Datadog- or Salesforce-siz
 The win is **regression re-runs**, because that cost is paid over and over. Take a mid-size surface:
 
 - **50 golden flows**, re-verified on **every PR**, at **200 PRs/day**.
-- Reticle replays each flow **deterministically, with no model**: ~**200 tokens/flow/run** (measured).
+- Reticle replays each flow **deterministically, with no model**: ~**240 tokens/flow/run** (measured).
 - The agent-driven alternative re-drives each flow with an LLM: ~**30,000 tokens/flow/run** (measured Layer-C comparison).
 
 |  | Per flow / run | 50 flows × 200 PRs/day | Per year (~250 working days) |
 | --- | --- | --- | --- |
-| Reticle replay (no model) | ~200 tok | ~2.0 M tok/day | ~0.5 B tok/yr |
+| Reticle replay (no model) | ~240 tok | ~2.4 M tok/day | ~0.6 B tok/yr |
 | Agent re-drive (LLM) | ~30,000 tok | ~300 M tok/day | ~75 B tok/yr |
 
-That's a **~150× difference on the recurring axis**, and it scales linearly with flows × runs, the two numbers an enterprise has _a lot_ of. The deterministic replay also means **~0% verdict flake** (measured over repeated identical runs), which at this scale is the difference between a trusted gate and one engineers learn to ignore (recall: flaky suites get abandoned; that's the documented failure mode Reticle is built to avoid). And because replay needs no model, it has **no per-run API spend and no rate-limit ceiling**. It runs in CI like any other deterministic check.
+That's a **~125× difference on the recurring axis**, and it scales linearly with flows × runs, the two numbers an enterprise has _a lot_ of. The deterministic replay also means **~0% verdict flake** (measured over repeated identical runs), which at this scale is the difference between a trusted gate and one engineers learn to ignore (recall: flaky suites get abandoned; that's the documented failure mode Reticle is built to avoid). And because replay needs no model, it has **no per-run API spend and no rate-limit ceiling**. It runs in CI like any other deterministic check.
 
 ### Where it does NOT help (stated plainly)
 
@@ -256,4 +304,4 @@ The same page is loaded in one browser under three conditions (full SDK, observe
 
 **Result: instrumentation overhead is smaller than the method can resolve. Report it as `< 1.2 percentage points`, inside the 3% budget.** The HUD is measured and reported separately, because it is a developer-visible affordance you can turn off, not a cost of observing.
 
-Getting here required correcting the method and then fixing a real bug. The two-condition version of this bench compared the full SDK against Reticle being absent, so it charged instrumentation for the HUD too, and reported **+5.85 pp (FAIL)**. Decomposing it showed almost none of that was instrumentation: a single `backdrop-filter: blur(24px)` on the HUD panel was costing **+4.03 pp** on its own, more than every observer combined, because a backdrop blur re-samples everything behind it whenever that content changes, and this fixture repaints at 60fps. Removing it took total main-thread time down 22%. Full history, including a fix that measured nothing and was reverted rather than kept, is in `bench/overhead/README.md`. Reproduce it yourself with `node bench/overhead/measure.mjs` (see `bench/overhead/README.md`, which records the ruled-out causes). causes).
+Getting here required correcting the method and then fixing a real bug. The two-condition version of this bench compared the full SDK against Reticle being absent, so it charged instrumentation for the HUD too, and reported **+5.85 pp (FAIL)**. Decomposing it showed almost none of that was instrumentation: a single `backdrop-filter: blur(24px)` on the HUD panel was costing **+4.03 pp** on its own, more than every observer combined, because a backdrop blur re-samples everything behind it whenever that content changes, and this fixture repaints at 60fps. Removing it took total main-thread time down 22%. Full history, including a fix that measured nothing and was reverted rather than kept, is in `bench/overhead/README.md`. Reproduce it yourself with `node bench/overhead/measure.mjs` (see `bench/overhead/README.md`, which records the ruled-out causes).

package/docs/best-practices.mdx

@@ -1,10 +1,12 @@
 ---
-title: Best practices: how to earn a green
+title: 'Best practices: how to earn a green'
 sidebarTitle: Best practices
 description: The habits that make a verdict worth trusting, and the specific mistakes that produce a confident, wrong pass.
 icon: star
 ---
 
+A green is worth trusting when you named the consequence **before** you acted, ended the run on `reticle_act_and_wait` or `reticle_assert` (nothing else produces a verdict), scoped the assertion with `since`, and read `verified` rather than `pass`. Everything below is one of those habits, or the specific mistake that breaks it.
+
 Everything here comes from driving Reticle against real apps and getting it wrong first. None of it is theoretical, and several entries exist because they bit us while writing these docs.
 
 ## Name the consequence before you act
@@ -87,11 +89,14 @@ Every `act` response returns a `since`. Use it.
 
 Every verdict reports `honesty.grade`. Aim for `signal`.
 
-| Grade      | What it means                | How much it proves       |
-| ---------- | ---------------------------- | ------------------------ |
-| `presence` | Something appeared           | A mock does this too     |
-| `state`    | A registered store changed   | The app accepted it      |
-| `signal`   | The app fired a named signal | The app declared success |
+| Grade      | What it means                 | How much it proves          |
+| ---------- | ----------------------------- | --------------------------- |
+| `presence` | Something appeared            | A mock does this too        |
+| `state`    | A registered store changed    | The app accepted it         |
+| `net`      | A request fired and came back | The app talked to the world |
+| `signal`   | The app fired a named signal  | The app declared success    |
+
+Ranked weakest to strongest, that is `presence` < `state` < `net` < `signal`. A predicate with no consequence at all grades `none`.
 
 Getting from `presence` to `signal` is roughly ten minutes of [instrumentation](/instrumentation) per flow, and it is the highest-leverage work available.