@reticlehq/server 2.8.0 → 2.10.0

package/dist/tools/tool-surface.js

@@ -40,6 +40,36 @@ export const TOOL_SURFACE = {
     DEFAULT: 'default',
     /** Every tool advertised directly, WITH output schemas. A verification switch — see above. */
     ALL: 'all',
+    /**
+     * The smallest surface that can still produce a VERDICT. Not a profile — a cost switch.
+     *
+     * Measured on the wire: a verification that names its own target costs one `act_and_wait` call,
+     * and 5,480 of its 5,909 tokens are the advertised surface re-sent for that single turn. The
+     * answers cost 430. So on the path where the caller already knows what to assert, almost the
+     * entire bill is the menu, and the menu is the thing to cut.
+     *
+     * Deliberately NOT the default, and now MEASURED rather than inherited. Run over the same 30-bug
+     * set that the default surface scores 23/27 detection and 2/29 false alarms on:
+     *
+     *   detection      24/28   (held)
+     *   FALSE ALARMS   7/30    (was 2/29 — TRIPLED)
+     *   tokens         113,599 per run (was 179,959 — 37% cheaper)
+     *
+     * The five new false alarms are not scattered. They are `mutation-leak` and
+     * `generate-blast-filter` (state), `kpi-deploys-tamper` (business-logic), `debounce-broken`
+     * (timing) and `route-stuck-deployments` (routing) — precisely the classes whose evidence lives in
+     * `reticle_state`, `reticle_network` and `reticle_observe`, which this surface does not advertise.
+     * Strip the observation tools and the model stops observing: it reaches for the verdict without
+     * the evidence and calls a healthy build broken.
+     *
+     * So the retired `dynamic` finding is confirmed, with a sharper mechanism than "accuracy drops".
+     * 37% of the tokens is not worth trading for the one metric this product actually wins on, and
+     * this must not become the default on the strength of the token number alone.
+     *
+     * It remains correct for a caller who has ALREADY decided what to assert — there the assertion
+     * supplies the evidence the surface would otherwise have to go and find.
+     */
+    VERIFY: 'verify',
 };
 /**
  * The switch that turns on the full, output-schema-carrying surface. A boolean, not a menu.
@@ -48,6 +78,8 @@ export const TOOL_SURFACE = {
  * users to shop among alternatives that did not meaningfully differ.
  */
 export const ADVERTISE_ALL_ENV = 'RETICLE_ADVERTISE_ALL_TOOLS';
+/** Opt into the smallest verdict-capable surface. Read by the DAEMON at startup, like the others. */
+export const VERIFY_SURFACE_ENV = 'RETICLE_VERIFY_SURFACE';
 /**
  * The retired setting, still read so nobody's shell profile breaks.
  *
@@ -144,26 +176,51 @@ export const CORE_TOOL_NAMES = new Set([
     // deleting the instruction from the lease and the pause hint — deletes the handback protocol,
     // because there is nowhere else those two calls are ever named.
     ReticleTool.SESSION,
-    // CAPABILITIES is the highest orientation-per-token tool on the surface: one call returns the app's
-    // whole testable surface — its testids, signals, stores and named flows — and `{fromDisk:true}`
-    // returns the same from a checked-in contract with NO browser attached, so an agent with zero
-    // context starts oriented instead of exploring.
-    //
-    // Same argument as the four above, and it is the fifth time this file has made it: a tool an agent
-    // must already know about, and reach through reticle_run, is a tool that never gets called.
-    //
-    // The cost is real and is NOT the bargain #262 claimed. That issue argued the marginal cost sits
-    // "well below the 274-token average" because the input schema is small; measured, its description
-    // plus schema is closer to 325 tokens, which is above the average rather than below it. This is
-    // also a straight +1 rather than a swap: the tools that write-up proposed demoting (`project`,
-    // `domain`) were never in the default set to begin with.
-    //
-    // So it is a deliberate bet, taken with that correction on the table: that orientation replaces
-    // exploratory snapshots, which are among the most expensive calls an agent makes. The measurement
-    // that settles it is whether sessions calling this early take fewer and cheaper snapshots than
-    // those that do not. If that does not show up, this is the entry to revert.
+]);
+/**
+ * The extended surface: what `all` advertises BEYOND the default set.
+ *
+ * `all` used to mean "every tool in the registry", and that is no longer allowed to be true. Cursor
+ * enforces a limit of 40 tools across every connected MCP server COMBINED, so a server advertising
+ * 48 by itself can push a user's other servers out or be dropped wholesale. The budget is a count,
+ * so no amount of trimming parameter prose buys anything back — only advertising fewer names does.
+ *
+ * Everything omitted stays in the registry, stays catalogued by `reticle_tools`, and stays callable
+ * by name through `reticle_run { tool, args }`. The cost is one discovery hop on the cold tail, which
+ * is the same trade the default surface has always made, applied one level further out.
+ *
+ * What it costs that is NOT free: `all` is the only surface that carries `outputSchema`, which is
+ * what makes the MCP layer validate tool OUTPUT — the check that once caught `reticle_verify_change`
+ * returning a payload its own schema rejected. The tools left off this list no longer get that
+ * validation from the wire. That defect class is now uncovered for them, and it is written down here
+ * rather than discovered later.
+ *
+ * Chosen as the capabilities an agent plausibly reaches for once the verify loop is not enough:
+ * orientation, the record/replay flow loop, visual evidence, and the three fault-injection controls.
+ */
+export const EXTENDED_TOOL_NAMES = new Set([
+    // Demoted from the default set to make room under the cap. It was added as an explicit bet that
+    // orientation replaces exploratory snapshots, and the measurement that would have settled that
+    // bet was never run — so when the budget became a hard count, the unproven entry is the one that
+    // gives way. Still one `reticle_run` hop from any agent that wants it.
     ReticleTool.CAPABILITIES,
+    ReticleTool.FLOW_SAVE,
+    ReticleTool.FLOW_REPLAY,
+    ReticleTool.RECORD,
+    ReticleTool.SCREENSHOT,
+    ReticleTool.VISUAL_DIFF,
+    ReticleTool.CLOCK,
+    ReticleTool.NETWORK_MOCK,
+    ReticleTool.STORAGE,
+    // Merged change/flows/affected/coverage/crawl — one name where three of these used to sit.
+    ReticleTool.VERIFY,
 ]);
+/**
+ * The verify surface: one acting tool that returns a verdict, plus the two meta-tools that reach
+ * everything else. `act_and_wait` can resolve its own target, so no query tool is needed to name an
+ * element — that round trip was half the token cost of a verification.
+ */
+export const VERIFY_TOOL_NAMES = new Set([ReticleTool.ACT_AND_WAIT]);
 /** Is the truthy form of a boolean env var set? `1`, `true`, `yes` — anything else is off. */
 function envFlagOn(raw) {
     if (raw === undefined)
@@ -178,6 +235,8 @@ function envFlagOn(raw) {
  * switch decides, and the retired setting is honoured last so an old shell profile still works.
  */
 export function resolveToolSurface(explicit) {
+    if (explicit === TOOL_SURFACE.VERIFY)
+        return TOOL_SURFACE.VERIFY;
     if (explicit === TOOL_SURFACE.ALL)
         return TOOL_SURFACE.ALL;
     if (explicit === TOOL_SURFACE.DEFAULT)
@@ -185,6 +244,8 @@ export function resolveToolSurface(explicit) {
     const retiredExplicit = explicit === undefined ? undefined : RETIRED_PROFILE_VALUES[explicit];
     if (retiredExplicit !== undefined)
         return retiredExplicit;
+    if (envFlagOn(process.env[VERIFY_SURFACE_ENV]))
+        return TOOL_SURFACE.VERIFY;
     if (envFlagOn(process.env[ADVERTISE_ALL_ENV]))
         return TOOL_SURFACE.ALL;
     const retiredEnv = RETIRED_PROFILE_VALUES[process.env[TOOL_PROFILE_ENV] ?? ''];
@@ -230,7 +291,11 @@ export function describeToolSurface(active, requested) {
 export function filterTools(tools, surface) {
     // CORE_TOOL_NAMES is what it always really was: the set advertised directly. It was never the
     // interesting thing about the `core` PROFILE, whose only distinction was a second name for this.
+    if (surface === TOOL_SURFACE.VERIFY)
+        return tools.filter((t) => VERIFY_TOOL_NAMES.has(t.name));
     if (surface === TOOL_SURFACE.DEFAULT)
         return tools.filter((t) => CORE_TOOL_NAMES.has(t.name));
-    return tools;
+    // `all` is the extended surface, not the whole registry — the cap is a hard budget shared with
+    // every other MCP server the user has connected. surface-sizes.test.ts enforces it.
+    return tools.filter((t) => CORE_TOOL_NAMES.has(t.name) || EXTENDED_TOOL_NAMES.has(t.name));
 }

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).
              *
@@ -467,7 +508,7 @@ export const MERGE_PLANS = [
     },
     {
         name: ReticleTool.FLOW,
-        description: 'Saved-flow management: { action: "list" } names every saved flow, "load" reads+validates one by flowName, "delete" removes one. The hot verbs (flow_save, flow_replay, flow_verify, flow_heal) stay separate.',
+        description: 'Saved-flow management: { action: "list" } names every saved flow, "load" reads+validates one by flowName, "delete" removes one. The hot verbs (flow_save, flow_replay, flow_heal) stay separate; whole-suite replay is reticle_verify { action: "flows" }.',
         members: {
             list: ReticleTool.FLOW_LIST,
             load: ReticleTool.FLOW_LOAD,
@@ -490,6 +531,21 @@ export const MERGE_PLANS = [
         // is the one that must not need a schema lookup first.
         example: { action: 'yield', mode: 'waiting' },
     },
+    {
+        name: ReticleTool.VERIFY,
+        description: 'What is proved, and what is not — by action. Start from a change: { action: "affected" } names which saved flows must re-verify for the files you edited (pass `files`, and/or `since` for a git ref), and "change" goes further and actually replays them, answering with one `verified` plus `because`. `unknown` there is the honest answer when NO saved flow covers the change: nothing ran, so nothing was proved, and it is never reported as green. Without a change to start from: "flows" replays every saved flow for one consolidated suite verdict (deterministic, no LLM per flow), and "coverage" lists the interactive controls you have and have NOT driven this session — an untouched list still holding the controls your change affects means you are not done. "crawl" is the no-script option: it drives every reachable control itself and reports single-channel faults (console errors, failed requests, dead controls) and CONTRADICTIONS, two channels disagreeing about the same click — the false greens a human cannot see, because a human watches the screen and the screen looks correct. DESTRUCTIVE: crawl really clicks, and may navigate or mutate state.',
+        members: {
+            change: ReticleTool.VERIFY_CHANGE,
+            flows: ReticleTool.FLOW_VERIFY,
+            affected: ReticleTool.AFFECTED,
+            coverage: ReticleTool.COVERAGE,
+            crawl: ReticleTool.CRAWL,
+        },
+        // No default action ON PURPOSE. The name implies no single member, and one of them really
+        // clicks: a fallthrough that guessed wrong would drive the app rather than read it. Every action
+        // is explicit, which for `crawl` is the whole safety story.
+        example: { action: 'change', files: ['src/App.tsx'] },
+    },
     {
         name: ReticleTool.LEASE,
         description: 'Isolated headless contexts from the shared pool: { action: "acquire" } leases one and navigates it to the app URL, "release" closes it and frees the slot.',

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,11 +111,11 @@ 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).
+**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_verify {action:"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).
 
 ## flows vs baselines vs project.json (the persistence layers)
 
@@ -158,4 +160,4 @@ Recent additions, each of which answers a question agents were previously asking
 - **Cap broad reads.** `reticle_query` takes `limit` (caps descriptors; reports `total`/`truncated`) and `count_only` (just the match count). `reticle_network` / `reticle_console` take `limit` (most-recent-N, reports `droppedOldest`) and carry the same `cost` hint, so a busy page or wide window never floods your context unnoticed.
 - **A saved flow tells you if it's a real test.** `reticle_flow_save` returns `assertions.grade` (`asserted` / `presence-only` / `assertion-free`); if it's not `asserted`, add a consequence (`reticle_annotate` assert-signal/assert-net or a success-state) so it can't pass while broken. On replay, an ambiguous heal (two testids tie) is surfaced, never auto-applied. And an `apply` heal re-replays the rebound flow and **refuses to write** if the success consequence no longer fires (`status:consequence_broken`): it heals the locator, never the intent.
 - **Predicate schema is not bloated.** The recursive predicate DSL used by `reticle_assert` / `reticle_wait_for` / `reticle_act_and_wait` is **factored, not inlined**: when converted to the JSON Schema MCP sends, the predicate body is emitted **once** (~2.7k chars ≈ **~685 tokens** per tool) and recursion is handled by self-`$ref` (`#/properties/predicate`), with no per-recursion duplication. No action needed.
-- **One tool surface.** Reticle advertises the core set directly (sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state/inspect/feedback/session: the whole detect loop, plus the file-pointer, the feedback channel and the handback) PLUS two meta-tools that keep every other tool one call away: `reticle_tools` (discover; no args lists every tool name + summary, `names:[…]` loads full params on demand) and `reticle_run({ tool, args })` (invoke any tool by name; a top-level `sessionId` is forwarded to the target, so you need not nest it in `args`). So to record/replay/verify a flow, call `reticle_run({ tool:"reticle_flow_verify", sessionId })` (or `reticle_tools` first to see params). There is nothing to pick. `RETICLE_ADVERTISE_ALL_TOOLS=1` (read by the daemon at startup, so restart it) advertises everything with output schemas: a verification switch for suites, not a way to run agents. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.
+- **One tool surface.** Reticle advertises the core set directly (sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state/inspect/feedback/session: the whole detect loop, plus the file-pointer, the feedback channel and the handback) PLUS two meta-tools that keep every other tool one call away: `reticle_tools` (discover; no args lists every tool name + summary, `names:[…]` loads full params on demand) and `reticle_run({ tool, args })` (invoke any tool by name; a top-level `sessionId` is forwarded to the target, so you need not nest it in `args`). So to record/replay/verify a flow, call `reticle_run({ tool:"reticle_verify", args:{ action:"flows" }, sessionId })` (or `reticle_tools` first to see params). There is nothing to pick. `RETICLE_ADVERTISE_ALL_TOOLS=1` (read by the daemon at startup, so restart it) advertises everything with output schemas: a verification switch for suites, not a way to run agents. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.

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).