@reticlehq/server 2.11.0 → 2.13.0

package/dist/visual/visual-tools.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
-import { ReticleCommand, RETICLE_CAPTURE_FILE_PREFIX, VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason, } from '@reticlehq/core';
+import { AppRuntime, ReticleCommand, RETICLE_CAPTURE_FILE_PREFIX, VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
+import { ratioSchema } from '../tools/numeric-bounds.js';
 import { asNumber, asRecord, asString } from '../tools/tools-helpers.js';
 import { diffPng } from './visual-diff.js';
 import { VisualStore } from './visual-store.js';
@@ -148,19 +149,51 @@ function isCompletePng(bytes) {
  * `full-page-unsupported` — a viewport image returned as though it were the whole scroll height is a
  * baseline that says nothing about the content below the fold, and a later diff would call it green.
  */
+/**
+ * Which runtime this session is, for scoping a visual artifact.
+ *
+ * Undefined when the session cannot be resolved or its SDK never reported one — and undefined means
+ * the flat legacy path, so a baseline captured before any of this keeps matching.
+ */
+function runtimeOf(deps, sessionId) {
+    try {
+        return deps.sessions.resolve(sessionId).runtime;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function capture(deps, sessionId, args) {
     const provider = screenshotProvider(deps);
     if (provider !== undefined) {
         const session = deps.sessions.resolve(sessionId);
         const png = await provider.screenshot(session.url, await buildOpts(deps, sessionId, args));
+        // A driven browser renders the session's URL in a BROWSER — so the pixels are web even when the
+        // session named is a desktop window. Scoping those under the desktop runtime would corrupt that
+        // runtime's baseline with a picture of a different renderer.
         if (png !== undefined)
-            return { png };
+            return { png, runtime: AppRuntime.WEB };
     }
+    // The window's own backing store, via the Electron/Tauri adapter — the only route whose pixels
+    // really are the desktop app.
     const desktop = await desktopCapture(deps, sessionId, true === args['fullPage']);
     if (desktop.png !== undefined)
-        return { png: desktop.png };
+        return { png: desktop.png, runtime: runtimeOf(deps, sessionId) };
     if (desktop.reason !== undefined)
         return { reason: desktop.reason };
+    /*
+     * A LEASED page is a real browser page, so the pixels were always there — the visual tools simply
+     * had no route to them. Without this, `reticle_screenshot` answered "no provider" for every context
+     * an agent can actually acquire, which made visual regression impossible on exactly the isolated
+     * contexts the pool exists to hand out. Tried last: a CDP provider, when there is one, is driving
+     * the page the caller means, and a lease is the fallback rather than a competitor.
+     */
+    const leased = sessionId === undefined
+        ? undefined
+        : await deps.pool?.screenshotLease(sessionId, { fullPage: true === args['fullPage'] });
+    // A leased page is a real browser page, whatever the session is.
+    if (leased !== undefined)
+        return { png: leased, runtime: AppRuntime.WEB };
     return {
         reason: provider === undefined ? VisualReason.NO_PROVIDER : VisualReason.CAPTURE_FAILED,
     };
@@ -215,13 +248,16 @@ export const VISUAL_TOOLS = [
         },
         handler: async (deps, args) => {
             const sessionId = asString(args['sessionId']);
-            const { png, reason } = await capture(deps, sessionId, args);
+            const { png, reason, runtime } = await capture(deps, sessionId, args);
             if (png === undefined) {
                 return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
             }
             const name = asString(args['name']) ?? 'default';
             const store = new VisualStore(deps.fs, deps.reticleRoot);
-            const path = await store.saveBaseline(name, png);
+            // Scoped to the runtime that produced it: an Electron window, a Tauri webview and a browser
+            // tab do not render the same url the same way, and one shared baseline makes every
+            // cross-runtime diff wrong. See visualDir.
+            const path = await store.saveBaseline(name, png, runtime);
             return { ok: true, saved: true, name, path, bytes: png.length };
         },
     },
@@ -237,8 +273,10 @@ export const VISUAL_TOOLS = [
             ref: z.string().optional(),
             clip: rectShape.optional(),
             masks: z.array(rectShape).optional(),
-            maxRatio: z.number().optional(),
-            threshold: z.number().optional().describe('Pixel difference threshold (0–1). Default: 0.01.'),
+            maxRatio: ratioSchema.optional(),
+            threshold: ratioSchema
+                .optional()
+                .describe('Pixel difference threshold (0–1). Default: 0.01.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -255,14 +293,21 @@ export const VISUAL_TOOLS = [
         handler: async (deps, args) => {
             const baseline = asString(args['baseline']) ?? '';
             const store = new VisualStore(deps.fs, deps.reticleRoot);
-            const baselineBytes = await store.readBaseline(baseline);
-            if (baselineBytes === undefined)
-                return { ok: false, reason: VisualReason.BASELINE_MISSING };
+            // Capture FIRST, then fetch the baseline for the runtime that produced these pixels. Reading it
+            // by the session's runtime looked equivalent and is not: the route decides the renderer, so a
+            // desktop session captured through a driven browser must be compared against the WEB baseline,
+            // not the desktop one. Comparing across renderers is a confident wrong diff in one direction
+            // and a silently overwritten baseline in the other.
             const sessionId = asString(args['sessionId']);
-            const { png: current, reason } = await capture(deps, sessionId, args);
+            const { png: current, reason, runtime } = await capture(deps, sessionId, args);
             if (current === undefined) {
                 return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
             }
+            // A baseline from another runtime is not missing by accident — it is a different rendering, and
+            // "no baseline for this one" is the honest answer.
+            const baselineBytes = await store.readBaseline(baseline, runtime);
+            if (baselineBytes === undefined)
+                return { ok: false, reason: VisualReason.BASELINE_MISSING };
             const masks = rectsFrom(args['masks']);
             const threshold = asNumber(args['threshold']);
             const maxRatio = asNumber(args['maxRatio']);
@@ -276,7 +321,7 @@ export const VISUAL_TOOLS = [
             if (diffBytes === undefined) {
                 return { ok: false, ...verdict, reason: VisualReason.DIMENSION_MISMATCH };
             }
-            const diffPath = await store.saveDiff(baseline, diffBytes);
+            const diffPath = await store.saveDiff(baseline, diffBytes, runtime);
             return { ok: true, ...verdict, diffPath };
         },
     },

package/docs/README.md

@@ -26,7 +26,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [faq.mdx](faq.mdx) | production, frameworks, comparisons, and the honest limits |
 | [tools-overview.mdx](tools-overview.mdx) | the 18 advertised tools, the 30 in the cold tail, and why |
 | [tools-snapshot.mdx](tools-snapshot.mdx) | `reticle_snapshot`: three modes, from full tree to a 25-token route check |
-| [tools-query.mdx](tools-query.mdx) | `reticle_query` finds elements by testing-library semantics |
+| [tools-query.mdx](tools-query.mdx) | `reticle_query` finds elements by their reported roles, names and labels |
 | [tools-inspect.mdx](tools-inspect.mdx) | `reticle_inspect`: one element, down to source and design tokens |
 | [tools-navigate.mdx](tools-navigate.mdx) | `reticle_navigate`, and why `ok` does not mean the page arrived |
 | [tools-act.mdx](tools-act.mdx) | `reticle_act` acts, proves nothing, and says so |
@@ -46,6 +46,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [best-practices.mdx](best-practices.mdx) | the habits that make a verdict worth trusting |
 | [skill-file.mdx](skill-file.mdx) | the paste-one-URL skill that teaches an agent Reticle |
 | [agent-cheatsheet.md](agent-cheatsheet.md) | the condensed version an agent keeps in context |
+| [reticle-manual.md](reticle-manual.md) | GENERATED: what each tool actually returned when it was called, per argument shape |
 | [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 |

package/docs/cli/cloud.mdx

@@ -20,7 +20,7 @@ These are thin clients over the `/v1` API. The moat is the server, not the verbs
 | `~/.reticle/credentials.json` | Project-scoped API keys from `reticle link`, keyed by `projectId` | Yes |
 | `<repo>/.reticle/cloud.json` | `{ projectId, projectName, url, sync, verify }`. The non-secret binding | No, commit it |
 
-Auth for any command is `RETICLE_CLOUD_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` overrides the endpoint; the default is `http://localhost:8890`.
+Auth for any command is `RETICLE_CLOUD_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` overrides the endpoint; the default is `http://localhost:8890`. When a command falls back to that default without `RETICLE_CLOUD_URL` (or a saved session URL), it prints a one-line notice on stderr; stdout stays pure JSON for agents.
 
 ## The commands
 

package/docs/cli/doctor.mdx

@@ -51,8 +51,10 @@ When nothing has connected, the `sessions` line fails and the daemon's own diagn
 | `chromium` | Whether the exact Chromium revision the bundled Playwright wants is on disk. The most common silent failure |
 | `daemon` | Whether the port holds a Reticle daemon, a foreign process (named where possible), or nothing. Adds a `version` line when the daemon's version or contract fingerprint disagrees with the CLI's |
 | `sessions` | Whether any page has actually connected. Zero is a FAILING check rather than a neutral note, because it is the state the setup most often stalls in: wired correctly, daemon up, nothing dialled in. When it is zero the daemon's own no-session diagnosis prints below the checklist |
+| `agent link` | Whether an MCP client has listed Reticle's tools on this port **and actually called one**. Every other row here checks a component; this one checks the hop between your agent and the daemon. It is possible for the SDK to be injected, a session to be live, and your client to show every tool enabled, while no request has ever crossed from the agent. That state passes every other check and is the one people lose hours to |
 | `bridge port` | The port your app must dial, spelled out because mixing it up with the dev server port is the most common setup failure |
 | `port check` | Only when your project's configured port disagrees with the one the daemon is on. Prints the mismatch rather than leaving you to spot it across two lines |
+| `sibling` | Only when a well-known Reticle port other than this daemon's has a listener. An observation, not a diagnosis: that listener may or may not be related |
 | `daemon log` | Where the structured daemon log lives |
 | `tracing` | How to turn that log into a per-stage trace |
 | `desktop` | Only on a desktop project. Every Electron and Tauri misconfiguration here fails silently, so it is diagnosed explicitly |

package/docs/cli/serve.mdx

@@ -21,8 +21,10 @@ Most people never type this. Your agent runs [`reticle mcp`](/cli/mcp), which st
 | `--headless` | boolean | `true` for `serve` | Hide the browser |
 | `--headed` | boolean | `false` | Show it. `serve` owns the pooled browser behind leases, which is batch work, so it hides by default |
 | `--http` | boolean | `false` | Also expose the HTTP verify endpoint |
-| `--http-port N` | number | unset | Port for that endpoint |
-| `--http-token T` | string | unset | Bearer token the endpoint requires |
+| `--http-port N` | number | unset (`7331`) | Port for that endpoint. Requires `--http`. |
+| `--http-token T` | string | unset | Bearer token the endpoint requires. Requires `--http`. |
+
+The HTTP flags are honoured or refused, never silently dropped: against an already-running daemon that does not serve the requested verify port, `serve --http` exits 1 and names both ports. A running daemon keeps the flags it was started with, so `reticle stop`, then serve again. A verify port that cannot be bound fails the daemon start with a `reticle_daemon_start_failed` line naming that port.
 
 ## What it prints
 

package/docs/cli/verify.mdx

@@ -50,11 +50,10 @@ Call log:
 
 <Warning>
   `verify` binds the bridge port itself and has **no `--port` flag**: passing one is rejected as
-  `unknown argument '--port'`. If a daemon is already on the port, `verify` dies with a raw `Error:
-  listen EADDRINUSE: address already in use 127.0.0.1:4400` stack trace before it drives anything.
-  Stop the daemon first, or move `verify` with the `RETICLE_PORT` environment variable. This bites
-  most often on a developer machine, where an agent has usually left a daemon running; in CI the
-  port is normally free.
+  `unknown argument '--port'`. If a daemon is already on the port, `verify` does not start a second
+  one: it prints three ways out (ask the running daemon via `reticle_run`, stop it, or move with
+  `RETICLE_PORT`) rather than a raw listen error. This bites most often on a developer machine,
+  where an agent has usually left a daemon running; in CI the port is normally free.
 </Warning>
 
 ## Exit codes

package/docs/cli.mdx

@@ -4,7 +4,7 @@ description: Every reticle command. What it does, what it prints, and what it ex
 icon: terminal
 ---
 
-The `reticle` CLI wires Reticle into a project (`init`), runs and diagnoses the daemon your app connects to (`serve`, `status`, `doctor`, `kill`, `restart`), and gates a build on verification in CI (`verify`, `affected`, `gate`). This page is the index; each command has its own page with real captured output and measured exit codes.
+The `reticle` CLI installs Reticle into a project and proves the install works (`init`), runs and diagnoses the daemon your app connects to (`serve`, `status`, `doctor`, `kill`, `restart`), and gates a build on verification in CI (`verify`, `affected`, `gate`). This page is the index; each command has its own page with real captured output and measured exit codes.
 
 The CLI is mostly for you, not your agent. Your agent talks MCP; you use these to set things up, work out why nothing connected, and wire verification into CI.
 
@@ -32,12 +32,16 @@ npx @reticlehq/server <command>
 
 ### `reticle init`
 
-Wires Reticle into the project in the current directory.
+Wires Reticle into the project in the current directory, then boots the app, proves a session connected and drives one flow to a verdict. It exits non-zero if no verdict was produced, and prints what is left to do.
 
 ```
-reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
+reticle init  [--flow "<what to drive>"] [--env KEY=VALUE]... [--app <dir>] [--license <key>]
+              [--json] [--files-only] [--no-open] [--no-drive] [--dry-run]
+              [--port N] [--no-mcp] [--no-install] [--timeout S] [--drive-model M]
 ```
 
+`--flow`, `--env` and `--app` are the answers the command cannot work out for itself: which journey proves what you care about, what the app needs to reach a usable state, and which app in a monorepo. `--files-only` is what `init` did before it learned to boot the app: it still registers the MCP server and pre-approves Reticle's tools, so it doubles as the upgrade path for an existing install.
+
 <Card title="Full walkthrough with real output" icon="wand-magic-sparkles" href="/install-agentic">
   What it writes, and how to read its four status marks.
 </Card>

package/docs/desktop.mdx

@@ -214,7 +214,7 @@ Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-por
 
 ```toml
 [dependencies]
-reticle-tauri = "0.1"
+reticle-tauri = "2.13"
 ```
 
 ```rust

package/docs/docs.json

@@ -32,7 +32,7 @@
   "navigation": {
     "versions": [
       {
-        "version": "2.11.0",
+        "version": "2.13.0",
         "default": true,
         "tabs": [
           {
@@ -153,7 +153,7 @@
               },
               {
                 "group": "Long form",
-                "pages": ["agent-cheatsheet", "usage", "faq"]
+                "pages": ["agent-cheatsheet", "reticle-manual", "usage", "faq"]
               }
             ]
           },

package/docs/gates.md

@@ -69,7 +69,7 @@ Each gate exists because the ones above it are blind to something. That blindnes
 | **Integration** | `pnpm test:integration` | real headless Chromium: browser pool, crash isolation, framework adapters, `withReticle` | the MCP surface, the daemon | `e2e` |
 | **Web e2e battery** | `pnpm test:e2e` | 32 specs against 3 booted servers and a real browser (the tool surface, the daemon lifecycle, transport faults, telemetry, trace shape), plus the soak | desktop runtimes; the install | `e2e` |
 | **Desktop battery** | `pnpm test:e2e:desktop` | a real Electron main process and a **packaged** Tauri binary, driven headless | web-only paths | `desktop-e2e` |
-| **Install gate** | `pnpm gate:install` | scaffolds 3 pristine apps, publishes this checkout to a local Verdaccio, lets `init` install itself, boots each app in a real browser, polls for a session | install _complexity_; see [`fixtures.md`](./fixtures.md) | `install-gate` |
+| **Install gate** | `pnpm gate:install` | scaffolds 3 pristine apps, publishes this checkout to a local Verdaccio, lets `init` install itself, boots each app in a real browser, polls for a session that advertised capabilities | install _complexity_; see [`fixtures.md`](./fixtures.md) | `install-gate` |
 | **Matrix records** | `pnpm matrix:validate` | every submitted client-compat record is well-formed | whether the client actually works | `matrix-records` |
 | **Windows** | (CI only) | that the code runs at all on the majority platform | e2e; Windows is unit-only | `windows` |
 | **Rust** | `cargo fmt/clippy/check` | `packages/tauri` compiles and lints on Linux, macOS, and cross-checks Windows | everything JS | `rust`, `rust-macos` |

package/docs/getting-started.md

@@ -4,7 +4,7 @@ description: 'Zero to your agent verifying your real app, step by step, with wor
 icon: rocket
 ---
 
-**To get started with Reticle: run `npx @reticlehq/server init` in your project root, restart your dev server, restart your coding agent, then open your app in a browser and ask the agent to drive a flow.** Reticle is a verification layer that embeds a dev-only SDK in your running web app so an AI coding agent can prove a change works instead of guessing. It needs Node 20 or newer, an app you run locally, and an agent that speaks MCP.
+**To get started with Reticle: run `npx @reticlehq/server init --flow "<the journey worth proving>"` in your project root.** That one command wires your project, starts your dev server, opens the app, waits for it to connect, and drives that flow to a verdict. You do not restart anything and you do not drive it yourself. Reticle is a verification layer that embeds a dev-only SDK in your running web app so an AI coding agent can prove a change works instead of guessing. It needs Node 20 or newer, an app you run locally, and an agent that speaks MCP.
 
 > **Looking for the fast path?** [Quickstart](/quickstart) gets you to a real verdict in five minutes, and every response on it was captured live. [Agentic install](/install-agentic) and [Manual install](/install-manual) cover setup in detail, per agent and per framework.
 >
@@ -76,7 +76,19 @@ It detects your framework, package manager, and React version, then:
 
 The bridge + MCP server is a single process that serves all your projects, so it's registered at **user scope**, not in a per-project `.mcp.json`. Only the SDK (the `reticle()` plugin / connect call) is added per project.
 
-Re-running is safe (already-registered/already-patched steps are skipped). Preview without writing via `npx @reticlehq/server init --dry-run`. Flags: `--dry-run`, `--port N`, `--no-mcp`, `--no-install`, `--app <dir>`.
+Re-running is safe: already-registered and already-patched steps are skipped, and on a wired project it goes straight to proving the app still works. Preview without writing via `npx @reticlehq/server init --dry-run`.
+
+`init` does not stop at writing files. It starts your dev server (restarting one whose bundle predates the config edit), opens the app, waits for a session to connect from inside it, and drives one flow to a verdict, which it saves so later checks are a single call with no model involved. It exits non-zero if no verdict was produced and prints what is left to do.
+
+Three flags carry what the command cannot work out for itself:
+
+| Flag | What only you know |
+| --- | --- |
+| `--flow "<what>"` | Which journey proves the thing you care about. It can list the buttons on your page; it cannot know that checkout matters and the theme toggle does not. |
+| `--env KEY=VALUE` | What your app needs to reach a usable state: the key from `.env.example`, the mock backend, the variable that skips an auth wall. Repeatable. |
+| `--app <dir>` | Which app in a monorepo. It finds the servable ones; only you know which you are working in. |
+
+The rest are dials: `--license <key>` (writes it to `.env` and keeps `.env` out of git), `--json` (one object for an agent to read), `--files-only` (write, register, pre-approve, and stop, which is what `init` did before it learned to boot the app, and what an existing install re-runs to pick up new wiring), `--no-open`, `--no-drive`, `--dry-run`, `--port N`, `--no-mcp`, `--no-install`.
 
 Then restart your dev server and skip to [Step 4](#step-4-run-it-and-verify-the-connection). The manual steps below explain what `init` sets up, if you prefer to wire it yourself.
 
@@ -310,6 +322,8 @@ export default defineConfig({
 
 ## Step 4: Run it and verify the connection
 
+> `reticle init` does this for you: it starts the dev server, opens the app and waits for the session. Read on only if you are wiring by hand, or if it told you it could not.
+
 1. Start your app's dev server as usual (`npm run dev`).
 2. Open it in the browser (the SDK connects when the page loads).
 3. In your agent, ask it to confirm the connection:
@@ -328,6 +342,8 @@ If the list is empty, see [Troubleshooting](#troubleshooting).
 
 ## Step 5: Your first verification
 
+> `reticle init --flow "<what>"` drives this for you and saves the flow. This section is what it does, for when you want to do it yourself.
+
 Now just talk to your agent in plain language. For example:
 
 > "Add a 'Refresh' button to the header that re-fetches the dashboard data, then use Reticle to verify clicking it fires `GET /api/dashboard` and shows no console errors."
@@ -490,7 +506,7 @@ pnpm add @reticlehq/next
 
 ### What exactly does `reticle init` change in my project?
 
-Four things, and none of them are mysterious: a `.reticle.json` project config, your build config (the `reticle()` Vite plugin, or `withReticle` in `next.config`), a dev-only capabilities file at `src/reticle-dev.ts` (or `app/reticle-dev.tsx` on Next.js), and your agent's rule files. It also registers the MCP server globally, which is a once-per-machine step rather than a per-project one. Run `npx @reticlehq/server init --dry-run` first to see the exact plan before anything is written.
+Four files, and none of them are mysterious: a `.reticle.json` project config, your build config (the `reticle()` Vite plugin, or `withReticle` in `next.config`), a dev-only capabilities file at `src/reticle-dev.ts` (or `app/reticle-dev.tsx` on Next.js), and your agent's rule files. It then starts your dev server, opens the app and drives one flow, none of which changes your source: the dev server is left running for you afterwards, and the only file the drive may edit is the capabilities file, and only when your app registers none. It also registers the MCP server globally, which is a once-per-machine step rather than a per-project one. Run `npx @reticlehq/server init --dry-run` first to see the exact plan before anything is written.
 
 ### Do I have to re-register the MCP server for every project?
 

package/docs/index.mdx

@@ -14,7 +14,7 @@ It answers the only question that matters: did the change actually work? On Reac
 
 ## Install it: paste this into your coding agent
 
-You do not install Reticle by hand. Copy the block below into Claude Code, Cursor, Copilot, Codex, Windsurf, OpenCode, or any MCP agent, and let the agent wire its own workspace. It ends with the only definition of "installed" that counts: one real flow driven, one real verdict returned.
+You do not install Reticle by hand, and neither does your agent: it runs one command that does the whole thing. Copy the block below into Claude Code, Cursor, Copilot, Codex, Windsurf, OpenCode, or any MCP agent, and let it wire its own workspace. It ends with the only definition of "installed" that counts: one real flow driven, one real verdict returned.
 
 ```text
 Reticle is the proof layer for AI coding agents. It runs a dev-only SDK inside my
@@ -30,12 +30,15 @@ silent 500.
 
 Install it now:
 
-  RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server@latest init
+  RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server@latest init \
+    --flow "<pick the journey that matters in my app and name it here>"
 
-Then follow https://docs.reticle.sh/install-agentic.md and, if anything needs a
-manual edit, https://docs.reticle.sh/install-manual.md. Do not stop until you have
-driven one real flow in my app and produced a verdict. That, not a config file, is
-what "installed" means.
+That one command wires the project, starts the dev server, opens the app, waits
+for it to connect and drives that flow to a verdict. Do not walk it by hand: read
+what it prints, do anything it says is outstanding, and re-run it, which is safe.
+It exits non-zero until a verdict exists, and that, not a config file, is what
+"installed" means. Only if it could not run at all, follow
+https://docs.reticle.sh/install-manual.md.
 
 Afterwards, use it whenever you change any user-facing behaviour.
 ```

package/docs/install-agentic.mdx

@@ -1,7 +1,7 @@
 ---
 title: 'Agentic install: let the agent do it'
 sidebarTitle: Agentic install
-description: Run npx @reticlehq/server init and let your coding agent wire Reticle into the project. What it changes, what it asks, and how to read its report.
+description: One command wires Reticle into your project, boots the app, proves a session connected and drives one flow to a verdict. What it changes, what you pass it, and how to read what it returns.
 icon: wand-magic-sparkles
 ---
 
@@ -195,21 +195,47 @@ reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
               only make sense once the tools are reachable.
 ```
 
-| Flag           | When you want it                                                           |
-| -------------- | -------------------------------------------------------------------------- |
-| `--dry-run`    | Always, the first time.                                                    |
-| `--app <dir>`  | Monorepos. Without it, `init` finds several apps and asks which you meant. |
-| `--no-mcp`     | Your MCP config is managed elsewhere (dotfiles, a team template).          |
-| `--no-install` | You want to add the dependencies yourself, at your own versions.           |
-| `--port N`     | Something else already owns the default port.                              |
+Three of these are answers only the caller has. `init` reads your repository; it cannot read your request, and these live only there.
 
-## Then restart two things
+| Flag | When you want it |
+| --- | --- |
+| `--flow "<what>"` | **Name the journey worth proving.** `init` can list the buttons on a page; it cannot know that checkout matters and the theme toggle does not. Naming it is the difference between a drive that finishes and one that spends its budget looking for something to do. |
+| `--env KEY=VALUE` | What the app needs to reach a usable state: the key from `.env.example`, the mock backend, the variable that skips an auth wall. Repeatable, and a value may contain spaces and equals signs. Without it a real app sits on a login screen and there is no flow to drive. |
+| `--app <dir>` | Monorepos. `init` can find the apps that are servable; only your request says which one you are working in. |
+| `--license <key>` | Writes `RETICLE_LICENSE_KEY` to `.env` and keeps `.env` out of git. Do not do those two by hand. |
+| `--json` | One object on stdout: what was wired, what connected, the verdict, and an `agentTodo` array. For agents. |
+| `--files-only` | Write the files, register the MCP server with every agent on the machine, pre-approve Reticle's tools, and stop: no dev server, no drive. What `init` did before it learned to boot the app, and the upgrade path for a machine that installed Reticle on an earlier version. |
+| `--no-open` | Do not open a browser: CI, a container, an SSH session, or a tab you already have. |
+| `--no-drive` | Stop once a session connects and leave the verdict to you. The only honest way to skip it. |
+| `--dry-run` | See the plan before anything is written. |
+| `--no-mcp` | Your MCP config is managed elsewhere (dotfiles, a team template). |
+| `--no-install` | You want to add the dependencies yourself, at your own versions. |
+| `--port N` | Something else already owns the bridge port. Not the dev server's port. |
 
-This trips up almost everyone, so `init` says it twice and so will we.
+## Already installed? Mostly automatic
 
-**Restart your dev server.** The Vite plugin is new; the running process doesn't have it.
+The first time `reticle mcp` starts on a new version it applies the pre-approval rules for the agents it finds, once, and records that it did. You get that by upgrading. There is nothing to type.
 
-**Restart your agent.** Claude Code, or reload the window in Cursor, or hit Start in `.vscode/mcp.json` in VS Code. Your agent read its server list at startup, before Reticle existed, and no slash command re-reads it. `/mcp` manages servers already loaded, so it cannot pick up a new one. This is a once-per-machine annoyance: Reticle registers globally, so every later project starts with the tools already there.
+One case is deliberately left out. Creating Cursor's `permissions.json` when you do not already have one supersedes whatever you approved inside Cursor itself, so a version bump doing it silently would make your OTHER MCP servers start prompting again, with nothing to connect that to us. Reticle defers it and waits to be asked:
+
+```bash
+npx @reticlehq/server@latest init --files-only
+```
+
+That writes the files, registers the MCP server with every agent it finds, pre-approves Reticle's tools so the per-call Accept dialog stops, and stops there: no dev server, no browser, no drive. Every step is idempotent, so a repo that is already wired reports "already" and changes nothing.
+
+Two things to know afterwards:
+
+- **A GUI client reads its config at startup.** Cursor, Antigravity, Claude Desktop and VS Code need a window reload before the new rules take effect. The CLIs pick them up on their next run.
+- **The pre-approval is scoped to `reticle` alone**, never a blanket rule for every MCP server, and never a global auto-run switch. If a client's approval file did not exist before, `init` says so in a line, because in Cursor's case that file supersedes what you had approved inside the app.
+
+Drop `--files-only` to get the full run: boot the app, drive a flow, return a verdict.
+
+## The two restarts you no longer have to think about
+
+**Your dev server: `init` handles it.** A dev server that was already running read your build config before `init` edited it, so it keeps serving the old bundle and nothing connects. `init` restarts it and waits for the port to answer, rather than telling you to.
+
+**Your agent: not on the critical path any more.** Your agent read its MCP server list at startup, before Reticle existed, and no slash command re-reads it. `/mcp` manages servers already loaded, so it cannot pick up a new one. That used to mean stopping the install to restart. It does not now: the flow is driven by a child agent process started after registration, which reads the list `init` just wrote. Your own session picks the tools up whenever you next start it, and nothing is waiting on that. This is a once-per-machine annoyance in any case, because Reticle registers globally.
 
 ## Confirm it worked
 

package/docs/install-manual.mdx

@@ -159,7 +159,7 @@ Screenshots and headless mode need the Rust crate, which is versioned independen
 
 ```toml
 [dependencies]
-reticle-tauri = "0.1"
+reticle-tauri = "2.13"
 ```
 
 ```rust

package/docs/packages/browser.mdx

@@ -6,13 +6,13 @@ icon: window
 
 `@reticlehq/browser` is the Reticle SDK that runs inside your page. It installs the observers, builds semantic snapshots, executes actions, and talks to the bridge. Install it directly only if you are **not** on React or want to call `connect()` yourself, because [`@reticlehq/react`](/packages/react) already re-exports all of it.
 
-**Apache 2.0. Depends on `@reticlehq/core` and `@testing-library/dom`.**
+**Apache 2.0. Depends on `@reticlehq/core`.**
 
 ## Why it exists
 
 This is what makes Reticle different from a browser-automation tool. Because it runs _inside_ the app rather than driving it from outside, it can see a state mutation and a fired signal, not just a rendered pixel. It never imports a Node API; that boundary is enforced by the dependency graph.
 
-`@testing-library/dom` is why [`reticle_query`](/tools-query) speaks role, label and testid instead of CSS selectors.
+[`reticle_query`](/tools-query) speaks role, label and testid instead of CSS selectors through its own local accessibility engine: one engine computes both what elements are called and what they match by, so a reported identity always round-trips.
 
 ## When you need it directly
 

package/docs/packages/server.mdx

@@ -64,7 +64,7 @@ await server.close();
 | `reticleRoot` | `string` | `cwd()/.reticle` |
 | `pairingTokenDir` | `string` | `~/.reticle` |
 | `now` | `() => number` | `Date.now` |
-| `toolProfile` | `string` | `RETICLE_TOOL_PROFILE`, else `full`. `core` serves the lean surface |
+| `toolProfile` | `string` | retired names (`core`/`full`/…) still map. Live switch is `RETICLE_ADVERTISE_ALL_TOOLS=1`. Default is the lean surface |
 | `httpVerify` | `boolean` | `false` |
 | `httpVerifyPort` | `number` | `RETICLE_VERIFY_DEFAULT_PORT` (`7331`) |
 | `httpVerifyToken` | `string` | `RETICLE_VERIFY_TOKEN` |

package/docs/packages.mdx

@@ -8,9 +8,11 @@ icon: cubes
 Reticle is eleven packages, and most people install two. This page exists so you can tell which two, and so that the ones you skip stop looking mysterious.
 
 <Note>
-  The ten npm packages ship together at one version: whatever `npm view @reticlehq/core version`
-  says, every other `@reticlehq/*` package says too. The Rust crate `reticle-tauri` is versioned
-  **independently**. That is deliberate, not drift.
+  Everything ships together at one version: whatever `npm view @reticlehq/core version` says, every
+  other `@reticlehq/*` package says too, and so does the `reticle-tauri` crate on crates.io.
+
+It was versioned independently until 2.12.0, and that turned out to mean _stuck_: the crate sat at `0.1.0` from the day it was written, the publish job skipped it every release because that version already existed, and no Rust-side fix reached anybody. Lockstep costs one line in the bump script and cannot fail that way.
+
 </Note>
 
 ## Which ones do I need?
@@ -70,7 +72,7 @@ Those rules are why the browser SDK cannot accidentally pull in a filesystem cal
 
 **Why it exists:** this is the part that makes Reticle different from a browser-automation tool. Because it runs _inside_ the app rather than driving it from outside, it can see a state mutation and a fired signal, not just a rendered pixel.
 
-**Depends on:** `@reticlehq/core`, `@testing-library/dom`. The latter is why [`reticle_query`](/tools-query) speaks role, label and testid rather than CSS selectors.
+**Depends on:** `@reticlehq/core`. [`reticle_query`](/tools-query) speaks role, label and testid rather than CSS selectors through its own local accessibility engine, so what a snapshot reports is exactly what a query matches.
 
 **Install it directly when** you are not on React, or you want `connect()` under your own control:
 
@@ -199,13 +201,13 @@ A lint rule makes the signal layer self-enforcing, which is the only way a conve
 
 ## reticle-tauri
 
-**The Rust crate**, on crates.io. Versioned independently of the npm packages.
+**The Rust crate**, on crates.io. Versioned in lockstep with the npm packages, so `2.11` here and `2.11` there mean the same release.
 
 **Why it exists:** Tauri IPC observation needs nothing on the Rust side; an `invoke('load_todos')` already reaches Reticle as `ipc://load_todos`. You only need this crate for screenshots and headless mode.
 
 ```toml
 [dependencies]
-reticle-tauri = "0.1"
+reticle-tauri = "2.13"
 ```
 
 <Warning>

package/docs/platform-integration.md

@@ -93,6 +93,23 @@ Live, clickable demo of each: `apps/vibe-builder-demo/` (set `BUG_MODE=…`). Pr
 
 ---
 
+## The minimal attach contract (for a harness or MCP host)
+
+Reticle is a stdio MCP server. A host that wires it correctly does four things, and each one is a step Reticle can see:
+
+1. **Spawn it.** `npx @reticlehq/server mcp`, over stdio, one process per host. That process is the proxy: it starts the local daemon on demand, reconnects on its own when the stream drops, and answers from cache while a daemon comes back.
+2. **Complete `initialize`.** Reticle answers the handshake itself when the daemon is slow, so a host that waits for a reply gets one either way.
+3. **Send `tools/list`, and send it again on `notifications/tools/list_changed`.** This is the step hosts skip. Registering a server is not the same as enumerating it: a host can register Reticle and never ask for the tool list until the client is restarted, and the model then has no Reticle tools at all while the install looks healthy from every other angle. Reticle declares `tools.listChanged` so a host that honours the notification recovers without a restart.
+4. **Call the tools.** `tools/call`, with the tool name and its arguments.
+
+`reticle status` reports how far a host has got. `mcpClient: "never-attached"` means no client has started the server on this port. `mcpClient: "never-enumerated"` means one started it and never asked for the tool list, which is the state a client restart fixes. `mcpClient: "enumerated"` means the client side is done, and anything still missing is the app rather than the host. The record is per port rather than per client, and it begins the first time a client starts a Reticle version that keeps it, so `status` says both of those out loud instead of naming a client it cannot see.
+
+### Hosts that cap the number of tools
+
+Some editors cap the total tool count across every MCP server, which is why Reticle advertises a small surface instead of everything it can do. Nothing is out of reach: `reticle_tools { names: [...] }` lists the tools and returns the full argument grammar for the ones you name, and `reticle_run { tool, args }` invokes any of them, advertised or not. A host that is short on tool slots pays for the advertised handful and still reaches the whole surface through that pair. See [`reticle_tools` and `reticle_run`](/tools-tools-and-run).
+
+---
+
 ## Exact steps per platform
 
 The shape is identical (in-app SDK in the template → verify in the sandbox → act on the verdict); the specifics differ by where each platform runs the preview.

package/docs/predicates.mdx

@@ -115,6 +115,14 @@ A passing route verdict quotes the transition itself:
 
 The app emitted a named signal via `reticle.signal()`. `dataMatches` is shallow JSON matching, and `*` means "present, any value".
 
+`count` works here exactly as it does on `net`:
+
+```json
+{ "kind": "signal", "name": "order:placed", "count": 1 }
+```
+
+**Exactly once.** A handler wired twice fires the signal twice and leaves the store in the right shape either way, so every state-only check stays green. `count: 0` is a claim of its own (the signal never fired) and is not the same as leaving `count` out, which asserts presence.
+
 Nothing outranks this. A `200` proves the server was reachable; a rendered row proves React ran. A signal is the application itself saying the thing succeeded. See [instrumentation](/instrumentation) for how to emit them.
 
 ### state