@reticlehq/server 2.8.0 → 2.10.0

package/docs/install-manual.mdx

@@ -1,11 +1,13 @@
 ---
-title: Manual install: by hand, on purpose
+title: 'Manual install: by hand, on purpose'
 sidebarTitle: Manual install
 description: Wire Reticle by hand. Register the MCP server for your agent, add the SDK, and connect it. Every step init automates, written out.
 icon: screwdriver-wrench
 ---
 
-Two halves, and they are independent. **Your agent** needs the MCP server registered so the `reticle_*` tools exist. **Your app** needs the SDK so there is something for those tools to talk to. Do one and the tools appear but every call reports no session. Do the other and your app connects to a daemon nobody is asking questions.
+**Installing Reticle by hand is two independent halves: register the MCP server so your agent gets the `reticle_*` tools, then add the SDK to your app so there is something for those tools to talk to.** You need both. `npx @reticlehq/server init` automates all of it, so use this page for the steps it marked `⚠`, or for an agent it does not know how to register.
+
+Do only the first half and the tools appear but every call reports no session. Do only the second and your app connects to a daemon nobody is asking questions.
 
 You want both. Take them in that order.
 
@@ -168,7 +170,7 @@ tauri::Builder::default()
 
 IPC observation needs nothing on the Rust side. An `invoke('load_todos')` already reaches Reticle as `ipc://load_todos`.
 
-<Card title="Electron, and the rest of desktop" icon="display" href="/desktop-apps">
+<Card title="Electron, and the rest of desktop" icon="display" href="/desktop">
   Main-process and renderer wiring, IPC observation, and what differs from the web install.
 </Card>
 
@@ -180,7 +182,7 @@ npx @reticlehq/server status
 
 A session in the output means the app connected. That. Not a tick in a checklist, is the install finished.
 
-If it says nothing connected, the usual cause is a port disagreement between your app and the daemon. The browser console will name the exact port it tried; set it explicitly with `VITE_RETICLE_WS_URL=ws://localhost:4400/reticle` or `reticle.connect({ url })`.
+If it says nothing connected, the usual cause is a port disagreement between your app and the daemon. The browser console will carry `[Reticle] this page could not open a websocket to …` naming the exact address it tried; set it explicitly with `VITE_RETICLE_WS_URL=ws://localhost:4400/reticle` or `reticle.connect({ url })`.
 
 Still stuck? `npx @reticlehq/server doctor` checks Chromium, the daemon and the port in one command.
 

package/docs/instrumentation.mdx

@@ -5,6 +5,8 @@ description: Register stores, emit signals, add testids. The three things that d
 icon: wrench
 ---
 
+**Three things raise a Reticle verdict from "something appeared" to "the app declared success": register your store, emit named signals, and add testids.** All three live in one dev-only file, `src/reticle-dev.ts`, which `npx @reticlehq/server init` creates for you.
+
 Reticle works with zero instrumentation. You get DOM, network, console and routing out of the box, and that is already more than a screenshot can tell you.
 
 But there is a ceiling, and this page is about raising it. Instrumentation is the difference between a verdict that says _something appeared_ and one that says _the application declared success_.
@@ -90,14 +92,18 @@ export const Sig = {
   TOAST_SHOWN: 'toast:shown',
 } as const;
 
+export type SigName = (typeof Sig)[keyof typeof Sig];
+
 const isDev = import.meta.env.DEV;
 
 /** Emit a Reticle signal (dev only, no-op in production). */
-export function emit(name: Sig, data: Record<string, unknown> = {}): void {
+export function emit(name: SigName, data: Record<string, unknown> = {}): void {
   if (isDev) reticle.signal(name, data);
 }
 ```
 
+`Sig` is a value, so it cannot be used as a type directly. `SigName` is the union of its values, which is what makes `emit(Sig.AUTH_GRANTED)` check and `emit('auth:granded')` fail at compile time rather than at 2am.
+
 Then call `emit(Sig.AUTH_GRANTED, { email })` where the thing actually succeeds. Not where you _think_ it succeeds. In the success branch, after the state update, not in the click handler.
 
 **Emit the failures too.** `auth:denied` is as valuable as `auth:granted`, for a reason the next section demonstrates.

package/docs/integration-patterns.md

@@ -4,6 +4,8 @@ description: 'The recommended shape for a real codebase: a minimal production fo
 icon: shapes
 ---
 
+The recommended shape for a real codebase is three decisions: put `createReticleEmitter()` in one `app/emit.ts` so components depend on an interface and `@reticlehq/browser` never reaches your production bundle; emit signals from the **store layer** rather than from N call sites; and let each feature self-register its testids and signals with `registerReticleDomain`. Then turn on `reticle/require-signal-on-mutation` so the signal layer cannot silently rot.
+
 The basics in [Getting Started](getting-started.md) work with **zero app changes**. This doc is the _recommended_ shape for a real codebase: a minimal production footprint, a signal layer that can't silently drift, and an adoption path that starts paying off on day one, with no rewrite required.
 
 - [1. Start here: reuse what you already have](#1-start-here-reuse-what-you-already-have)
@@ -156,7 +158,7 @@ export default [
 ];
 ```
 
-Or turn it on with the shipped preset (warns, with empty no-op defaults you then configure): `plugin.configs.recommended`. A function that calls a mutator and a signal together passes; a mutator with no signal reports `store mutation without a mapped Reticle signal`. The documented view-level exceptions from §3 simply don't list those view callees as `mutators`, so they never fire.
+Or turn it on with the shipped preset: `plugin.configs.recommended`, which sets `reticle/require-signal-on-mutation` to `warn` (with empty no-op defaults you then configure) and the plugin's other rule, `reticle/no-internal-tags`, to `error`. A function that calls a mutator and a signal together passes; a mutator with no signal reports `store mutation without a mapped Reticle signal`. The documented view-level exceptions from §3 simply don't list those view callees as `mutators`, so they never fire.
 
 ## 6. Limitation: un-scriptable tabs, use `reticle drive`
 

package/docs/local-registry.md

@@ -4,6 +4,8 @@ description: 'Exercise local, unpublished Reticle changes in a real external app
 icon: box
 ---
 
+To test unpublished `@reticlehq/*` changes in a real external app, publish the workspace to a local Verdaccio with `bash scripts/local-registry.sh`, then point that app's `.npmrc` at `http://localhost:4873/` for the `@reticlehq` scope. That is the whole procedure; the rest of this page is the detail.
+
 > **For normal use, Reticle is on public npm.** Just `npm i -D @reticlehq/react @reticlehq/vite-plugin` (see [Getting Started](getting-started.md)). You only need this guide to test **local, unpublished changes** to the Reticle packages in a real external app before they ship.
 
 Because the `@reticlehq/*` packages depend on each other via the workspace protocol, plain `npm pack` tarballs don't resolve cleanly. The reliable way to exercise your in-progress changes in a real app is a tiny **local registry** (Verdaccio), the same path CI uses to validate a publish.
@@ -35,7 +37,7 @@ For a browser app, install `@reticlehq/react` plus the build plugin for your fra
 
 ## 2. Point your app at the local registry
 
-In your app's project root, add an `.npmrc` (scopes only `@reticle` to the local registry; everything else still comes from npm):
+In your app's project root, add an `.npmrc`. The scope is **`@reticlehq`**, not `@reticle`: a scope typo here does not error, it silently resolves the PUBLISHED packages from npm, so you measure shipped code and think you tested your branch. Everything outside that scope still comes from npm:
 
 ```ini
 @reticlehq:registry=http://localhost:4873/
@@ -53,7 +55,7 @@ npm i -D @reticlehq/react @reticlehq/vite-plugin
 
 Then follow [Getting Started](getting-started.md): embed `reticle.connect()` (dev only) from `@reticlehq/react`, add the MCP server to your agent, and (React) `install()` the adapter from `@reticlehq/react`. For the fastest agent loop, also do [Step 6: make your app agent-legible](getting-started.md) (testids, `reticle.signal`, `registerStore`, `registerCapabilities`) and the [integration patterns](integration-patterns.md) (`createReticleEmitter` for zero prod-bundle cost).
 
-> **Upgrading.** The packages are currently **1.2.0**; new tools land as minor bumps. `scripts/local-registry.sh` resets Verdaccio and republishes the current version, so pull the latest in your app explicitly with `npm install @reticlehq/react@latest`:
+> **Upgrading.** `scripts/local-registry.sh` resets Verdaccio and republishes at whatever version the workspace is on right now, so your app will not pick up a rebuild on its own. Pull it explicitly with `@latest`:
 >
 > ```bash
 > npm i -D @reticlehq/react@latest @reticlehq/vite-plugin@latest @reticlehq/eslint-plugin@latest

package/docs/multi-agent-testing.md

@@ -4,6 +4,8 @@ description: 'Several apps at once, ports that shift between runs, and many agen
 icon: users
 ---
 
+Many agents can drive the same app at once without a browser each: `reticle_lease {action:"acquire"}` hands each one an **isolated context** (its own cookies, storage and DOM) from a single shared headless Chromium. One daemon per machine, and identity is the **app** (a stable `projectId` stamped by the build plugin), not the port, so an app that boots on `:3001` today is still the same app.
+
 Reticle is built for the messy real world: several apps running at once, ports that shift between runs, and many agents driving different flows of the same app in parallel, without each one spinning up its own Chromium. This page explains how that works and how to use it.
 
 ## The mental model
@@ -11,7 +13,7 @@ Reticle is built for the messy real world: several apps running at once, ports t
 - **One daemon per machine.** `reticle mcp` discovers a running daemon (via `~/.reticle`) or starts one. A crashed daemon's stale pidfile is reclaimed automatically, so you never chase "port already in use" or a zombie server.
 - **Identity is the app, not the port.** The build plugin stamps a stable `projectId` that travels in every connection. If your Next app usually runs on `:3000` but boots on `:3001` today, Reticle still knows which app it is, and an agent scoped to project A will never accidentally drive project B's tab. Origin is only a fallback hint.
 - **One browser, many contexts.** When agents need their own headless tabs, the daemon's **browser pool** launches a single Chromium and hands out isolated contexts (one per flow). They are cheap, and capped so a big fan-out can't exhaust the machine. Over-cap requests queue.
-- **Attach-only.** Reticle never starts your dev server. It connects to an app you're already running (or opens a headless tab pointed at it).
+- **Attach-only daemon.** The daemon never starts your dev server. It connects to an app that is running (or opens a headless tab pointed at it). When nothing is running, the agent starts your project's own dev script in the background and tells you. A build process spawned by a background daemon would be invisible, unconsented, and orphaned when the daemon exits.
 
 ## Manual testing: ~5 minutes
 

package/docs/packages/babel-plugin.mdx

@@ -4,22 +4,31 @@ description: A Babel plugin that stamps data-reticle-source on JSX host elements
 icon: file-code
 ---
 
-`@reticlehq/babel-plugin` puts the source location back. React 19 dropped `_debugSource`, which is what source mapping used to rely on, so without this the tools can tell you the component name but not the file.
+`@reticlehq/babel-plugin` stamps `data-reticle-source="file:line:col"` onto your JSX at build time, in dev only, so Reticle can name the file a DOM node came from. **You probably do not install this one directly**: [`@reticlehq/vite-plugin`](/packages/vite-plugin) and [`@reticlehq/next`](/packages/next) both pull it in. Reach for it only if you drive Babel yourself.
 
-**Version 2.8.0. Apache 2.0. CommonJS. No runtime dependencies. Peer dependency: `@babel/core ^7`.**
+React 19 dropped `_debugSource`, which is what source mapping used to rely on, so without this the tools can tell you the component name but not the file.
+
+**Apache 2.0. CommonJS. No runtime dependencies. Peer dependency: `@babel/core ^7`.**
 
 ## What it stamps
 
 ```jsx
-<button onClick={submit}>Sign in</button>
+// src/components/Login.jsx
+export function Login({ submit }) {
+  return <button onClick={submit}>Sign in</button>;
+}
 ```
 
 becomes, in dev only:
 
 ```jsx
-<button onClick={submit} data-reticle-source="src/components/Login.tsx:81:6">
-  Sign in
-</button>
+export function Login({ submit }) {
+  return (
+    <button onClick={submit} data-reticle-source="src/components/Login.jsx:2:9">
+      Sign in
+    </button>
+  );
+}
 ```
 
 The path is relative to `process.cwd()`, with backslashes normalized to forward slashes. A file with no name stamps `unknown`.

package/docs/packages/browser.mdx

@@ -4,9 +4,9 @@ description: The Reticle instrumentation SDK that runs inside your page, observi
 icon: window
 ---
 
-`@reticlehq/browser` is the half of Reticle that lives in your app. It installs the observers, builds semantic snapshots, executes actions, and talks to the bridge.
+`@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.
 
-**Version 2.8.0. Apache 2.0. Depends on `@reticlehq/core` and `@testing-library/dom`.**
+**Apache 2.0. Depends on `@reticlehq/core` and `@testing-library/dom`.**
 
 ## Why it exists
 

package/docs/packages/core.mdx

@@ -1,12 +1,12 @@
 ---
-title: "@reticlehq/core"
-description: The shared wire contract for Reticle: constants, zod schemas, and the isomorphic kernel every other package imports.
+title: '@reticlehq/core'
+description: 'The shared wire contract for Reticle: constants, zod schemas, and the isomorphic kernel every other package imports.'
 icon: cube
 ---
 
-`@reticlehq/core` is the bottom of the dependency graph. Every message that crosses a boundary, browser to bridge, bridge to agent, is defined here as a named constant plus a zod schema.
+`@reticlehq/core` is the shared wire contract at the bottom of Reticle's dependency graph. Every message that crosses a boundary, browser to bridge, bridge to agent, is defined here as a named constant plus a zod schema. **You almost certainly do not need to install it**: it arrives with whatever Reticle package you did install, and you only reach for it directly if you are building your own integration against the wire format.
 
-**Version 2.8.0. Apache 2.0. Depends on `zod` and nothing else.**
+**Apache 2.0. Depends on `zod` and nothing else.**
 
 ## Why it exists
 
@@ -27,7 +27,7 @@ npm i @reticlehq/core
 | Subpath | What it is |
 | --- | --- |
 | `.` | The ESM barrel. Types at `dist/index.d.ts` |
-| `./desktop-contract` | A CommonJS shim, generated at build, for the five strings the desktop adapters share |
+| `./desktop-contract` | A CommonJS shim, generated at build, for the strings the desktop adapters share |
 | `./schema/*.json` | Generated JSON Schema for the wire types |
 | `./package.json` | The manifest |
 
@@ -38,7 +38,7 @@ npm i @reticlehq/core
 
 ## What the barrel exports
 
-`src/index.ts` is a pure barrel: 26 `export *` re-exports plus one named export. Grouped by what they are for:
+`src/index.ts` is a pure barrel: a stack of `export *` re-exports plus one named export. Grouped by what they are for, and not exhaustive:
 
 ### Wire constants
 
@@ -50,7 +50,9 @@ npm i @reticlehq/core
 
 ### Enum-like frozen objects
 
-`EventType`, `ActionType`, `ElementState`, `QueryBy`, `MessageKind`, `ReticleCommand`, `PhenomenonType`, `SettleReason`, `ComponentStateReason`, `ComponentStateResult`, `InputMode`, `InputModeReason`, `ActionWarning`, `DriveErrorCode`, `TruncationChannel`, `EventAttribution`, `PerfMetric`, `PresenterMode`, `SnapshotMode`, `VisualReason`, `CONSOLE_LEVELS`, `Verified`.
+`EventType`, `ActionType`, `ElementState`, `QueryBy`, `MessageKind`, `ReticleCommand`, `PhenomenonType`, `SettleReason`, `ComponentStateReason`, `InputMode`, `InputModeReason`, `ActionWarning`, `DriveErrorCode`, `TruncationChannel`, `EventAttribution`, `PerfMetric`, `PresenterMode`, `SnapshotMode`, `VisualReason`, `CONSOLE_LEVELS`, `Verified`.
+
+`ComponentStateResult` is an interface, not one of these: it is a type-only export, so importing it as a value fails with `'ComponentStateResult' only refers to a type, but is being used as a value here`.
 
 ### Zod schemas
 
@@ -78,18 +80,26 @@ Pure, isomorphic, and safe on both sides of the wire:
 ## The desktop contract
 
 ```ts
-import { DESKTOP_CONTRACT, RETICLE_IPC_GLOBAL } from '@reticlehq/core/desktop-contract';
+import { RETICLE_IPC_GLOBAL, RETICLE_CAPTURE_CHANNEL } from '@reticlehq/core/desktop-contract';
 ```
 
-Five strings shared by the Electron preload and the Tauri crate, in CommonJS because a preload script is required before any ESM transform:
+Six strings shared by the Electron preload and the Tauri crate, in CommonJS because a preload script is required before any ESM transform:
+
+| Constant                        | Value                                                      |
+| ------------------------------- | ---------------------------------------------------------- |
+| `RETICLE_IPC_GLOBAL`            | `__reticleIpc`                                             |
+| `RETICLE_CAPTURE_CHANNEL`       | `__reticle:capture`                                        |
+| `RETICLE_CAPTURE_FILE_PREFIX`   | `reticle-capture-`                                         |
+| `RETICLE_TAURI_CAPTURE_COMMAND` | `reticle_capture`                                          |
+| `RETICLE_FULL_PAGE_UNSUPPORTED` | `full-page-unsupported`, for a refused full-page capture   |
+| `RETICLE_NOT_COMPOSITED`        | `window-not-composited`, for a window that had not painted |
 
-| Constant                        | Value                                                    |
-| ------------------------------- | -------------------------------------------------------- |
-| `RETICLE_IPC_GLOBAL`            | `__reticleIpc`                                           |
-| `RETICLE_CAPTURE_CHANNEL`       | `__reticle:capture`                                      |
-| `RETICLE_CAPTURE_FILE_PREFIX`   | `reticle-capture-`                                       |
-| `RETICLE_TAURI_CAPTURE_COMMAND` | `reticle_capture`                                        |
-| `RETICLE_FULL_PAGE_UNSUPPORTED` | The `VisualReason` value for a refused full-page capture |
+<Warning>
+  The subpath exports those six constants individually and nothing else. The `DESKTOP_CONTRACT`
+  record they are collected into exists on the ESM side only, so importing it here fails with
+  `Module '"@reticlehq/core/desktop-contract"' has no exported member 'DESKTOP_CONTRACT'`. Import
+  `DESKTOP_CONTRACT` from `@reticlehq/core` instead.
+</Warning>
 
 ## The JSON schemas
 

package/docs/packages/electron.mdx

@@ -4,9 +4,9 @@ description: The Reticle adapter for Electron, making main-process IPC observabl
 icon: display
 ---
 
-`@reticlehq/electron` reaches the two places the renderer cannot: the IPC boundary, and `capturePage()`.
+`@reticlehq/electron` reaches the two places the renderer-side SDK cannot: the IPC boundary, and `capturePage()`. Install it if your app is Electron and you want main-process IPC observable or the window screenshottable. A web app never needs it.
 
-**Version 2.8.0. Apache 2.0. Depends on `@reticlehq/core`. Peer dependency: `electron >= 22`. No build step.**
+**Apache 2.0. Depends on `@reticlehq/core`. Peer dependency: `electron >= 22`. No build step.**
 
 ## Why it exists
 
@@ -62,15 +62,13 @@ It then exposes `window.__reticleIpc` through the context bridge, with three mem
 ```js
 const { installReticleCapture } = require('@reticlehq/electron/main');
 
-const win = new BrowserWindow({
-  /* ... */
-});
+const win = new BrowserWindow({/* ... */});
 installReticleCapture(win);
 ```
 
 `installReticleCapture(win): void` is a no-op on `null` or `undefined`, tracks the window until it closes, and registers the capture handler once for the whole app.
 
-The handler calls `webContents.capturePage()`, writes the PNG into a per-process `0700` captures directory as `reticle-capture-<n>.png`, and **returns the file path rather than the bytes**, because the transport has a 64KB cap. It returns `null` on an empty image or any error, and it refuses `fullPage: true` explicitly rather than silently returning a viewport shot.
+The handler calls `webContents.capturePage()`, writes the PNG into a per-process `0700` captures directory as `reticle-capture-<n>.png`, and **returns the file path rather than the bytes**, because the transport has a 64KB cap. It refuses `fullPage: true` explicitly rather than silently returning a viewport shot, and it throws named reasons rather than one blanket silence: `full-page-unsupported` for that refusal, `window-not-composited` when the window had nothing painted yet, `no usable webContents to capture` when the window is gone. The preload re-throws the full-page refusal and turns everything else into `null`.
 
 ## Renderer wiring
 
@@ -82,6 +80,6 @@ reticle.connect({ allowInProduction: true });
 
 Or, with the Vite plugin, `reticle({ desktop: true })`.
 
-<Card title="Desktop setup in full" icon="display" href="/desktop-apps">
+<Card title="Desktop setup in full" icon="display" href="/desktop">
   Electron and Tauri wiring, and what `reticle doctor` checks for each.
 </Card>

package/docs/packages/eslint-plugin.mdx

@@ -4,9 +4,11 @@ description: Two lint rules that keep Reticle's signal layer and its comment hyg
 icon: shield-check
 ---
 
-`@reticlehq/eslint-plugin` exists because conventions rot. Someone adds a mutation, forgets the signal, and every verdict for that flow quietly drops a grade. Nothing breaks, the tests still pass, the evidence just gets weaker. A lint rule is the only way a convention survives contact with a deadline.
+`@reticlehq/eslint-plugin` is two ESLint rules that keep Reticle's signal layer self-enforcing. It is entirely optional: nothing in Reticle needs it, and you want it only once your app emits signals and you would like the compiler to notice when a new mutation forgets one.
 
-**Version 2.8.0. Apache 2.0. Depends on `@typescript-eslint/utils`. Peer dependency: `eslint >= 9`.**
+It exists because conventions rot. Someone adds a mutation, forgets the signal, and every verdict for that flow quietly drops a grade. Nothing breaks, the tests still pass, the evidence just gets weaker. A lint rule is the only way a convention survives contact with a deadline.
+
+**Apache 2.0. Depends on `@typescript-eslint/utils`. Peer dependency: `eslint >= 9`.**
 
 ```bash
 npm i -D @reticlehq/eslint-plugin
@@ -33,7 +35,7 @@ Warns when a store mutation happens without a mapped Reticle signal.
 
 | Option | Type | Default |
 | --- | --- | --- |
-| `mutators` | `string[]` | `[]`. With the default the rule is a no-op, which is deliberate: name your own mutators |
+| `mutators` | `string[]` | `[]`. With the default the rule is a no-op, which is deliberate: name your own mutators. Matched by BARE NAME, so `set` also matches `map.set()` and `headers.set()`; prefer an unambiguous name |
 | `signalCallee` | `string \| string[]` | `['reticleSignal', 'signal']` |
 
 ```js

package/docs/packages/next.mdx

@@ -4,9 +4,9 @@ description: Next.js source mapping for Reticle without giving up SWC, via a dev
 icon: n
 ---
 
-`@reticlehq/next` gives Next.js users the same `data-reticle-source` stamping the Vite plugin does, without asking them to migrate to Babel.
+`@reticlehq/next` gives a Next.js app the same `data-reticle-source` stamping the Vite plugin does, without asking it to migrate off SWC to Babel. Install it if your app is Next.js; on Vite use [`@reticlehq/vite-plugin`](/packages/vite-plugin) instead. Unlike the Vite plugin it does **not** inject `connect()`, so you still call that yourself.
 
-**Version 2.8.0. Apache 2.0. CommonJS, no build step. Depends on `@babel/core` and `@reticlehq/babel-plugin`. Peer dependency: `next >= 13`.**
+**Apache 2.0. CommonJS, no build step. Depends on `@babel/core` and `@reticlehq/babel-plugin`. Peer dependency: `next >= 13`.**
 
 ## Why it exists
 
@@ -22,9 +22,7 @@ npm i -D @reticlehq/next @reticlehq/react
 // next.config.js
 const { withReticle } = require('@reticlehq/next');
 
-module.exports = withReticle({
-  /* your config */
-});
+module.exports = withReticle({/* your config */});
 ```
 
 <Note>

package/docs/packages/react.mdx

@@ -4,9 +4,9 @@ description: The React kit for Reticle, mapping a DOM node to its component stac
 icon: react
 ---
 
-`@reticlehq/react` is the package most React users install, and usually the only SDK package they need. It re-exports the whole browser SDK and adds the fiber-tree work on top.
+`@reticlehq/react` is the Reticle kit for React apps, and usually the only SDK package a React user needs: it re-exports the whole browser SDK and adds fiber-tree work that maps a DOM node to its component stack, its hook state, and its source file. If your app is React, install this one and not `@reticlehq/browser`.
 
-**Version 2.8.0. Apache 2.0. Depends on `@reticlehq/browser` and `@reticlehq/core`. Peer dependency: `react >= 18`.**
+**Apache 2.0. Depends on `@reticlehq/browser` and `@reticlehq/core`. Peer dependency: `react >= 18`.**
 
 ## Why it exists
 
@@ -34,7 +34,7 @@ reticle.connect();
 | --- | --- | --- |
 | `install` | `(): void` | Idempotent. Registers the `react` adapter and installs the render meter. Call it once, before `connect()` |
 
-The [Vite plugin](/packages/vite-plugin) injects exactly these two lines for you, so a Vite user never writes them.
+The [Vite plugin](/packages/vite-plugin) injects `install()` and `reticle.connect()` for you, so a Vite user never writes either line.
 
 ### Mapping a node to its component
 

package/docs/packages/server.mdx

@@ -4,9 +4,9 @@ description: The Reticle bridge, MCP server, and the reticle CLI, all in one Nod
 icon: server
 ---
 
-`@reticlehq/server` hosts the WebSocket your app dials into, exposes the MCP tools your agent calls, and ships the `reticle` binary.
+`@reticlehq/server` is the Reticle bridge, MCP server and CLI in one Node package. It hosts the WebSocket your app dials into, exposes the MCP tools your agent calls, and ships the `reticle` binary. **You do not add it to your project**: your agent runs it with `npx @reticlehq/server mcp`.
 
-**Version 2.8.0. Licensed under `SEE LICENSE IN LICENSE`, not Apache 2.0 like the rest.** This is the package the enterprise terms apply to.
+**Licensed under `SEE LICENSE IN LICENSE`, not Apache 2.0 like the rest.** This is the package the enterprise terms apply to.
 
 ## Why it exists
 

package/docs/packages/tauri.mdx

@@ -4,17 +4,17 @@ description: The Rust crate that gives a Tauri app Reticle screenshots and headl
 icon: rust
 ---
 
-`reticle-tauri` is a Rust crate on crates.io, not an npm package. It is versioned **independently** of the ten npm packages, and is currently **0.1.0**.
+`reticle-tauri` is a Rust crate on crates.io, not an npm package. You need it only if your Tauri app should answer `reticle_screenshot`, or run headless in CI. Everything else about a Tauri app, including IPC observation, works without it.
 
-**MIT licensed, unlike the Apache 2.0 npm packages. Edition 2021.**
+It is versioned **independently** of the ten npm packages. **MIT licensed, unlike the Apache 2.0 npm packages. Edition 2021.**
 
 ## Why it exists, and why it is small
 
 Tauri IPC observation needs nothing on the Rust side. An `invoke('load_todos')` already reaches Reticle as `ipc://load_todos` through the SDK in the webview. You only need this crate for two things: screenshots, and headless mode.
 
 <Warning>
-  Do not expect this to be version `2.7`. Matching the npm version would imply a release cadence the
-  crate does not have, and it would make every npm release a crates.io release for no reason.
+  Do not expect this to match the npm version. Doing so would imply a release cadence the crate does
+  not have, and it would make every npm release a crates.io release for no reason.
 </Warning>
 
 ## Install
@@ -48,7 +48,7 @@ There are no public traits and no macros.
 
 ### `reticle_capture`
 
-Runs on a blocking thread, writes a PNG into a temporary directory as `reticle-capture-<nanos>.png`, and returns the **path**, not the bytes. Full-page capture is supported on Linux only; elsewhere it returns `FULL_PAGE_UNSUPPORTED`, which is pinned to core's `VisualReason` value so the refusal is the same string everywhere.
+Runs on a blocking thread, writes a PNG into a per-process `0700` directory under the OS temp dir as `reticle-capture-<nanos>.png`, and returns the **path**, not the bytes. Full-page capture is supported on Linux only; elsewhere it returns `FULL_PAGE_UNSUPPORTED`, which is pinned to core's `VisualReason` value so the refusal is the same string everywhere.
 
 ### `on_page_load`
 
@@ -58,6 +58,6 @@ Hides the window on `PageLoadEvent::Finished` when the environment variable `RET
 
 A Tauri app with the default CSP runs perfectly and never connects to Reticle, with nothing said anywhere. [`reticle doctor`](/cli/doctor) diagnoses this explicitly on a desktop project, because it is invisible otherwise.
 
-<Card title="Desktop setup in full" icon="display" href="/desktop-apps">
+<Card title="Desktop setup in full" icon="display" href="/desktop">
   The CSP entry, the headless flag, and how capture differs from a browser screenshot.
 </Card>

package/docs/packages/test.mdx

@@ -4,9 +4,9 @@ description: The Reticle spec runner for CI, driving the tools directly with no
 icon: vial
 ---
 
-`@reticlehq/test` turns an interactive session into a suite that runs on every pull request, without an agent and without paying model tokens to re-derive the same checks.
+`@reticlehq/test` is Reticle's spec runner for CI. It turns an interactive session into a suite that runs on every pull request, without an agent and without paying model tokens to re-derive the same checks. Install it when you want unattended verification; skip it if you only ever drive Reticle interactively through MCP.
 
-**Version 2.8.0. Licensed under `SEE LICENSE IN LICENSE`. Depends on `@reticlehq/core` and `@reticlehq/server`. Optional peer dependency: `vitest ^3.2.6`.**
+**Licensed under `SEE LICENSE IN LICENSE`. Depends on `@reticlehq/core` and `@reticlehq/server`. Optional peer dependency: `vitest ^3.2.6`.**
 
 ```bash
 npm i -D @reticlehq/test
@@ -27,7 +27,7 @@ const { results, summary } = await runSpecs({
   buildContext: (invoke) => createTestContext(invoke),
   now: () => Date.now(),
 });
-printSummary(summary);
+printSummary(summary, results, (line) => process.stdout.write(`${line}\n`));
 await run.close();
 ```
 
@@ -47,9 +47,10 @@ await run.close();
 ## Writing specs
 
 ```ts
-import { reticleTest } from '@reticlehq/test';
+import { reticleTest, type TestContext } from '@reticlehq/test';
 
-reticleTest('login grants a session', async (t) => {
+reticleTest('login grants a session', async (spec) => {
+  const t = spec as TestContext;
   await t.fill('email', 'user@example.com');
   await t.fill('password', 'hunter2');
   await t.actAndWait('login-submit', 'click', { kind: 'signal', name: 'auth:granted' });
@@ -60,6 +61,13 @@ reticleTest('login grants a session', async (t) => {
 
 `reticleTest(name: string, fn: SpecFn): void` registers into a module-level registry. `register`, `getRegistered` and `clearRegistry` are exported for anyone driving it themselves.
 
+<Note>
+  `SpecFn` types its argument as `SpecContext`, which declares only `invoke`. The runner actually
+  hands the spec whatever `buildContext` returned, which is a `TestContext`. In plain JavaScript
+  this is invisible; in TypeScript you get `Property 'fill' does not exist on type 'SpecContext'`
+  unless you narrow it as above.
+</Note>
+
 ## The test context
 
 `createTestContext(invoke: ToolInvoker, options?: TestContextOptions): TestContext`, where `TestContextOptions` is `{ sessionId?: string; defaultTimeoutMs?: number }` and the timeout defaults to `DEFAULT_ASSERT_TIMEOUT_MS`.
@@ -86,7 +94,8 @@ reticleTest('login grants a session', async (t) => {
 | --- | --- |
 | `runOne` | `(spec: ReticleSpec, opts: RunnerOptions) => Promise<SpecResult>` |
 | `runSpecs` | `(opts: RunnerOptions) => Promise<{ results: SpecResult[]; summary: RunSummary }>` |
-| `summarize` / `printSummary` | Build and print the summary |
+| `summarize` | `(results: readonly SpecResult[]) => RunSummary` |
+| `printSummary` | `(summary: RunSummary, results: readonly SpecResult[], print: (line: string) => void) => void`. The sink is injected, never `console` |
 | `toJUnitXml` / `writeJUnit` | JUnit output for CI |
 
 `RunnerOptions` is `{ invoke; buildContext; now; print?; specs? }`. `RunSummary` is `{ total, passed, failed, skipped, ok }`.
@@ -101,7 +110,9 @@ A recorded flow becomes a spec without being rewritten:
 
 `ReticleSkip` and `isSkip` for skipping, `ReticleAssertionError` with an `AssertionDetail`, `ReticleQueryEmptyError` when a query matched nothing.
 
-Constants: `TestStatus`, `SpecKind`, `SpecOutcome`, `SpecMessage`, `PredicateKind`, `STATUS_GLYPH`, `JUnit`, `SKIP_REASON_REAL_INPUT`, `PROBE_TESTID`.
+Constants: `TestStatus`, `SpecKind`, `SpecOutcome`, `SpecMessage`, `PredicateKind`, `STATUS_GLYPH`, `SUMMARY_FOOTER_PREFIX`, `JUnit`, `DEFAULT_JUNIT_SUITE_NAME`, `SKIP_REASON_REAL_INPUT`, `PROBE_TESTID`, `FLOW_LOAD_ERROR_PREFIX`, `DEFAULT_ASSERT_TIMEOUT_MS`.
+
+Also exported: `resolveTestid`, and the standalone `expectInputModeReal`, `InputModeTracker` and `readInputMode`.
 
 <Card title="Turning a session into a suite" icon="flask" href="/testing">
   Writing specs that bind to signals rather than DOM structure.

package/docs/packages/vite-plugin.mdx

@@ -4,9 +4,9 @@ description: One line in vite.config.ts that stamps source locations on your JSX
 icon: bolt
 ---
 
-`@reticlehq/vite-plugin` does the two things everyone forgets: wiring the SDK, and enabling source mapping.
+`@reticlehq/vite-plugin` is one line in `vite.config.ts` that does the two things everyone forgets: injecting `reticle.connect()` and enabling source mapping. Install it if your app builds with Vite. On Next.js use [`@reticlehq/next`](/packages/next) instead; on any other bundler, wire [`@reticlehq/browser`](/packages/browser) by hand.
 
-**Version 2.8.0. Apache 2.0. Depends on `@babel/core`, `@reticlehq/babel-plugin` and `@reticlehq/core`. Optional peer dependency: `vite >= 4`.**
+**Apache 2.0. Depends on `@babel/core`, `@reticlehq/babel-plugin` and `@reticlehq/core`. Optional peer dependency: `vite >= 4`.**
 
 ## Install and use
 
@@ -42,9 +42,7 @@ A virtual module at `/@reticle-connect`, added to the HTML, whose contents are:
 ```ts
 import { reticle, install } from '@reticlehq/react';
 install();
-reticle.connect({
-  /* resolved args */
-});
+reticle.connect({/* resolved args */});
 ```
 
 Plus a dynamic import of your dev module if one exists. It looks for `src/reticle-dev.ts`, `.js`, `.tsx` or `.jsx`, in that order, and leaves the file alone if you have one: that file is yours to edit.
@@ -91,6 +89,6 @@ reticle({ desktop: true });
 
 A packaged Electron or Tauri renderer is a production build loaded from a custom protocol, so the default guards would refuse. This one flag drops `apply: 'serve'` and opts the connect call into production.
 
-<Card title="Desktop wiring in full" icon="display" href="/desktop-apps">
+<Card title="Desktop wiring in full" icon="display" href="/desktop">
   Including the Tauri CSP whose failure is completely silent.
 </Card>

package/docs/packages.mdx

@@ -1,5 +1,5 @@
 ---
-title: Packages: what is in the box
+title: 'Packages: what is in the box'
 sidebarTitle: Packages
 description: Every Reticle package. What it does, why it exists, when you actually need it, and what it depends on.
 icon: cubes
@@ -8,9 +8,9 @@ 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>
-  Ten npm packages ship together at the same version, all at **2.8.0**, verified against the
-  registry. The Rust crate is versioned **independently** and is currently **0.1.0**. That is
-  deliberate, not drift.
+  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.
 </Note>
 
 ## Which ones do I need?
@@ -99,7 +99,7 @@ npx @reticlehq/server mcp
 
 ## @reticlehq/react
 
-**The kit most React users install.** It re-exports the browser sensor. So one install gives you both `reticle` and `registerCapabilities`. And maps a DOM node to its React component and source file through the fiber tree.
+**The kit most React users install.** It re-exports the browser sensor, so one install gives you `reticle`, `registerCapabilities` and everything else, and it maps a DOM node to its React component and source file through the fiber tree.
 
 **Why it exists:** this is the package that turns "the button is broken" into `src/components/Login.tsx:81`. Finding a bug is half the job. Reticle's answer to the other half lives here.
 
@@ -120,7 +120,10 @@ npm i -D @reticlehq/react
 **Depends on:** `@babel/core`, `@reticlehq/babel-plugin`, `@reticlehq/core`. **Peer:** `vite`.
 
 ```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
 import { reticle } from '@reticlehq/vite-plugin';
+
 export default defineConfig({ plugins: [reticle(), react()] });
 ```
 
@@ -148,9 +151,7 @@ export default defineConfig({ plugins: [reticle(), react()] });
 
 ```js
 const { withReticle } = require('@reticlehq/next');
-module.exports = withReticle({
-  /* your config */
-});
+module.exports = withReticle({/* your config */});
 ```
 
 <Note>
@@ -176,7 +177,7 @@ module.exports = withReticle({
 
 ## @reticlehq/eslint-plugin
 
-**One rule: state changed, so a signal must fire.**
+**Two rules, the main one being: state changed, so a signal must fire.**
 
 **Why it exists:** signals are the strongest evidence Reticle can use, and they rot the way all conventions rot. Someone adds a mutation, forgets the signal, and every verdict for that flow quietly drops a grade. Nothing breaks. The tests still pass. The evidence just gets weaker.
 
@@ -198,7 +199,7 @@ A lint rule makes the signal layer self-enforcing, which is the only way a conve
 
 ## reticle-tauri
 
-**The Rust crate**, on crates.io, currently **0.1.0**. Versioned independently of the npm packages.
+**The Rust crate**, on crates.io. Versioned independently of the npm packages.
 
 **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.
 
@@ -208,10 +209,10 @@ reticle-tauri = "0.1"
 ```
 
 <Warning>
-  Do not expect this to be `2.7`. Matching the npm version would imply a release cadence the crate
-  does not have, and it would make every npm release a crates.io release for no reason.
+  Do not expect this to match the npm version. Doing so would imply a release cadence the crate does
+  not have, and it would make every npm release a crates.io release for no reason.
 </Warning>
 
-<Card title="Desktop setup in full" icon="display" href="/desktop-apps">
+<Card title="Desktop setup in full" icon="display" href="/desktop">
   Electron and Tauri wiring, including the Tauri CSP whose failure is silent.
 </Card>