@reticlehq/server 3.6.0 → 3.7.0

package/docs/packages/browser.mdx

@@ -31,16 +31,17 @@ if (import.meta.env.DEV) reticle.connect();
 
 One instance, memoized on `globalThis` so hot module replacement does not create a second one.
 
-| Method         | Signature                                                |
-| -------------- | -------------------------------------------------------- |
-| `connect`      | `(options?: ReticleConnectOptions) => void`              |
-| `connected`    | `get connected(): boolean`                               |
-| `signal`       | `(name: string, data?: Record<string, unknown>) => void` |
-| `state`        | `(name: string, value: unknown) => void`                 |
-| `renderCommit` | `(commits: number) => void`                              |
-| `describe`     | `(input: CapabilitiesInput) => void`                     |
-| `endSession`   | `() => void`                                             |
-| `disconnect`   | `() => void`                                             |
+| Method              | Signature                                                  |
+| ------------------- | ---------------------------------------------------------- |
+| `connect`           | `(options?: ReticleConnectOptions) => void`                |
+| `connected`         | `get connected(): boolean`                                 |
+| `signal`            | `(name: string, data?: Record<string, unknown>) => void`   |
+| `state`             | `(name: string, value: unknown) => void`                   |
+| `renderCommit`      | `(commits: number) => void`                                |
+| `describe`          | `(input: CapabilitiesInput) => void`                       |
+| `endSession`        | `() => void`                                               |
+| `disconnect`        | `() => void`                                               |
+| `observeHotUpdates` | `(hot: unknown) => void` (called by the build integration) |
 
 Everything else on the class is private. `Reticle` itself is exported for typing.
 
@@ -56,8 +57,13 @@ Every field is optional.
 | `token` | `string` | Pairing token, required for a non-loopback page |
 | `allowNonLocalhost` | `boolean` | Opt in to connecting from a non-localhost origin |
 | `allowInProduction` | `boolean` | Opt in to connecting from a production build. Desktop apps need this |
+| `testIdAttribute` | `string` | The attribute the app marks controls with, when it is not `data-testid` |
 | `overlay` | `boolean` | The in-page overlay |
 | `captureNetworkBodies` | `boolean` | Record request and response bodies |
+| `networkBodyMaxChars` | `number` | Per-body cap for captured bodies (default 8192) |
+| `captureErrorBodies` | `boolean` | Keep the body of a failed request even with body capture off (default true) |
+| `sourceMapping` | `boolean` | Whether the build stamps source locations. Set by the build plugin |
+| `exposePresenter` | `boolean` | Make Reticle's own presenter visible to tools. For Reticle contributors only |
 | `root` | `string` | Repository root, so source paths come back relative |
 | `sdkVersion` | `string` | Reported on the handshake for skew detection |
 | `present` | `boolean` | Presenter mode |

package/docs/packages/core.mdx

@@ -27,7 +27,13 @@ npm i @reticlehq/core
 | Subpath | What it is |
 | --- | --- |
 | `.` | The ESM barrel. Types at `dist/index.d.ts` |
+| `./telemetry` | The analytics wire, for a Node-side importer that needs only that half |
+| `./artifacts` | The on-disk and registry formats |
+| `./hooks` | What Reticle says happened, for hook consumers |
+| `./hud` | Constants shared by the daemon and the HUD panel |
+| `./tour` | The onboarding tour |
 | `./desktop-contract` | A CommonJS shim, generated at build, for the strings the desktop adapters share |
+| `./source-constants` | A CommonJS shim, generated at build, for the source-stamp constants the build adapters share |
 | `./schema/*.json` | Generated JSON Schema for the wire types |
 | `./package.json` | The manifest |
 
@@ -38,7 +44,7 @@ npm i @reticlehq/core
 
 ## What the barrel exports
 
-`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:
+`src/index.ts` is a pure barrel: a stack of `export *` re-exports plus two named-export lines. Grouped by what they are for, and not exhaustive:
 
 ### Wire constants
 
@@ -83,19 +89,20 @@ Pure, isomorphic, and safe on both sides of the wire:
 import { RETICLE_IPC_GLOBAL, RETICLE_CAPTURE_CHANNEL } from '@reticlehq/core/desktop-contract';
 ```
 
-Six strings shared by the Electron preload and the Tauri crate, in CommonJS because a preload script is required before any ESM transform:
+Seven 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_WINDOW_CHANNEL`        | `__reticle:window`                                         |
 | `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 |
 
 <Warning>
-  The subpath exports those six constants individually and nothing else. The `DESKTOP_CONTRACT`
+  The subpath exports those seven 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.
@@ -103,9 +110,9 @@ Six strings shared by the Electron preload and the Tauri crate, in CommonJS beca
 
 ## The JSON schemas
 
-Seven files, generated at build from the zod definitions:
+Nine files, generated at build from the zod definitions:
 
-`reticle-message.json`, `reticle-event.json`, `hello-message.json`, `command-message.json`, `command-result.json`, `event-message.json`, `event-type.json`.
+`reticle-message.json`, `reticle-event.json`, `hello-message.json`, `command-message.json`, `command-result.json`, `event-message.json`, `event-type.json`, `command-name.json`, `event-payloads.json`.
 
 ```ts
 import schema from '@reticlehq/core/schema/reticle-message.json' with { type: 'json' };

package/docs/packages/electron.mdx

@@ -49,12 +49,13 @@ It patches three methods, and each IPC call then surfaces to Reticle as a networ
 | `ipcRenderer.sendSync` | Two-way, with its outcome            |
 | `ipcRenderer.send`     | One-way, dispatched, with no outcome |
 
-It then exposes `window.__reticleIpc` through the context bridge, with three members used by the SDK rather than by you:
+It then exposes `window.__reticleIpc` through the context bridge, with four members used by the SDK rather than by you:
 
 | Member | Signature | Notes |
 | --- | --- | --- |
 | `subscribe` | `(callback) => number` | Returns a token, or `-1` if the argument is not a function |
 | `unsubscribe` | `(token) => void` | Real removal |
+| `windowLabel` | `() => Promise<string \| undefined>` | The label the main process registered for this window, or `undefined` |
 | `capture` | `(fullPage) => Promise<string \| null>` | Resolves to a capture file path, `null` when no main handler is installed, and propagates the explicit full-page refusal |
 
 ## The main process
@@ -66,7 +67,7 @@ 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.
+`installReticleCapture(win, options?): 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. `{ label: 'settings' }` names the window in `reticle_session { action: "list" }`; without it the window is listed by url and title.
 
 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`.
 

package/docs/packages/engine.mdx

@@ -6,7 +6,7 @@ icon: gavel
 
 `@reticlehq/engine` is the part of Reticle that DECIDES. It reads what happened in a running app and says whether the declared consequence held. It has no browser, no daemon and no command line: evidence goes in, a verdict comes out.
 
-**Apache 2.0. Depends on [`@reticlehq/core`](/packages/core) and `zod`.**
+**Apache 2.0. Depends on [`@reticlehq/core`](/packages/core), [`open-verification`](/packages/open-verification) and `zod`.**
 
 ## Why it is a separate package
 

package/docs/packages/eslint-plugin.mdx

@@ -1,10 +1,10 @@
 ---
 title: '@reticlehq/eslint-plugin'
-description: Two lint rules that keep Reticle's signal layer and its comment hygiene self-enforcing.
+description: Three lint rules that keep Reticle's signal layer and its comment hygiene self-enforcing.
 icon: shield-check
 ---
 
-`@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.
+`@reticlehq/eslint-plugin` is three ESLint rules that keep Reticle's signal layer and its comments 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.
 
 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.
 
@@ -16,12 +16,13 @@ npm i -D @reticlehq/eslint-plugin
 
 ## Exports
 
-| Export                    | What it is                                                         |
-| ------------------------- | ------------------------------------------------------------------ |
-| `default`                 | The plugin object: `{ meta: { name: 'reticle' }, rules, configs }` |
-| `rules`                   | `{ 'require-signal-on-mutation': ..., 'no-internal-tags': ... }`   |
-| `requireSignalOnMutation` | The rule, exported individually                                    |
-| `noInternalTags`          | The rule, exported individually                                    |
+| Export | What it is |
+| --- | --- |
+| `default` | The plugin object: `{ meta: { name: 'reticle' }, rules, configs }` |
+| `rules` | `{ 'require-signal-on-mutation': ..., 'no-internal-tags': ..., 'no-runaway-comment': ... }` |
+| `requireSignalOnMutation` | The rule, exported individually |
+| `noInternalTags` | The rule, exported individually |
+| `noRunawayComment` | The rule, exported individually |
 
 ## The rules
 
@@ -49,10 +50,14 @@ The check is scoped per function: a mutation and its signal must live in the sam
 
 ### `reticle/no-internal-tags`
 
-Errors on internal design-doc reference codes and internal version strings appearing in comments, file names, directory names or test descriptions. **Message id:** `internalTag`, with a `{ tag }` placeholder. No options.
+Errors on internal design-doc reference codes and internal version strings appearing in comments, file names, directory names or test descriptions. **Message ids:** `internalTag` (in a comment or test description) and `pathTag` (in a file or directory name), each with a `{ tag }` placeholder. No options.
 
 This one is mostly for contributors to Reticle itself, but the `recommended` config turns it on for everyone.
 
+### `reticle/no-runaway-comment`
+
+Errors on a single block comment longer than 60 lines, which is usually pasted output rather than prose. **Message id:** `runawayComment`, with `{ lines }` and `{ max }` placeholders. No options.
+
 ## The recommended config
 
 One config, `recommended`:
@@ -71,14 +76,15 @@ Which is exactly:
   rules: {
     'reticle/require-signal-on-mutation': 'warn',
     'reticle/no-internal-tags': 'error',
+    'reticle/no-runaway-comment': 'error',
   },
 }
 ```
 
 <Warning>
-  `recommended` enables **both** rules, and `no-internal-tags` at `error`. An older README
-  documented only the first rule, so the second can arrive as a surprise. Enable the rules
-  individually if you want just the signal check.
+  `recommended` enables **all three** rules, and `no-internal-tags` and `no-runaway-comment` at
+  `error`. An older README documented only the first rule, so the other two can arrive as a
+  surprise. Enable the rules individually if you want just the signal check.
 </Warning>
 
 <Card title="Why signals are the strongest evidence" icon="tower-broadcast" href="/instrumentation">

package/docs/packages/next.mdx

@@ -10,7 +10,7 @@ icon: n
 
 ## Why it exists
 
-Next users are on SWC. Telling them to switch to Babel for a dev tool would be a rude trade, and it would slow down every build they run. This adds a dev-only pre-loader for `.jsx` and `.tsx` and leaves the rest of the pipeline alone.
+Next users are on SWC. Telling them to switch to Babel for a dev tool would be a rude trade, and it would slow down every build they run. This adds a dev-only pre-loader for `.jsx`, `.tsx` and `.js` files that contain JSX, and leaves the rest of the pipeline alone.
 
 ## Install and use
 
@@ -35,15 +35,16 @@ module.exports = withReticle({/* your config */});
 ### `.`
 
 ```ts
-function withReticle<T = unknown>(nextConfig?: T): T;
+function withReticle<T = unknown>(nextConfig?: T, options?: { sourceMapping?: boolean }): T;
 ```
 
-Returns the config unchanged when `NODE_ENV === 'production'`. Otherwise it merges in:
+Returns the config unchanged when `NODE_ENV === 'production'`, unless `RETICLE_DEV=1` is set (for `NODE_ENV=production next dev`). `sourceMapping: false` skips the loader rules, for an app that renders through a non-DOM React reconciler. Otherwise it merges in:
 
 | Addition | What it does |
 | --- | --- |
-| `webpack` | Pushes an `enforce: 'pre'` rule for `/\.(t\|j)sx$/`, excluding `node_modules`, using this package's loader. Your own `webpack` function still runs afterwards |
-| `turbopack` | On Next 15.3 and above only: rules for `*.tsx` and `*.jsx` pointing at `@reticlehq/next/loader` |
+| `webpack` | Pushes an `enforce: 'pre'` rule for `/\.(tsx\|jsx\|js)$/`, excluding `node_modules`, using this package's loader. Your own `webpack` function still runs afterwards |
+| `turbopack` | On Next 15.3 and above only: rules for `*.tsx` and `*.jsx` (and, on Next 16, the project's own `*.js`) pointing at `@reticlehq/next/loader` |
+| `allowedDevOrigins` | Your own list plus the loopback hosts a Reticle-opened tab arrives on, on a Next that accepts the key (15.2.2 and above) |
 | `env.NEXT_PUBLIC_RETICLE_URL` | The bridge URL: a valid `RETICLE_PORT` override, otherwise project daemon discovery and `.reticle.json` |
 | `env.NEXT_PUBLIC_RETICLE_TOKEN` | The pairing token, when one exists on disk |
 | `env.NEXT_PUBLIC_RETICLE_ROOT` | `process.cwd()`, so source paths come back repository-relative |
@@ -51,7 +52,7 @@ Returns the config unchanged when `NODE_ENV === 'production'`. Otherwise it merg
 
 Daemon discovery reads `RETICLE_STATE_DIR` (default `~/.reticle`). Pairing tokens use `RETICLE_PAIRING_TOKEN_DIR` independently. The generated `ReticleDev` component reads `NEXT_PUBLIC_RETICLE_URL`; restart the dev server after changing these settings.
 
-`readPairingToken()` is also exported at runtime. It is not declared in `index.d.ts`, so TypeScript will not see it.
+`readPairingToken()`, `discoverDaemonUrl()` and `knowsAllowedDevOrigins()` are also exported at runtime. They are not declared in `index.d.ts`, so TypeScript will not see them.
 
 ### `./loader`
 
@@ -60,7 +61,7 @@ declare function reticleNextLoader(this: unknown, source: string, inputMap?: unk
 export = reticleNextLoader;
 ```
 
-An async webpack loader. It skips anything that is not `.jsx` or `.tsx`, and anything under `node_modules`. It lazily imports `@reticlehq/babel-plugin` and runs `babel.transformAsync` with `configFile: false`, `babelrc: false`, `retainLines`, and source maps on.
+An async webpack loader. It skips anything that is not `.jsx`, `.tsx` or a `.js` file containing JSX, and anything under `node_modules`. It lazily imports `@reticlehq/babel-plugin` and runs `babel.transformAsync` with `configFile: false`, `babelrc: false`, `retainLines`, and source maps on.
 
 <Note>
   The loader never fails the build. Any error falls back to the original source, because a dev-only

package/docs/packages/open-verification.mdx

@@ -37,4 +37,4 @@ npm install open-verification
 
 ## Versioning
 
-The protocol has its own compatibility rules, stated in `VERSIONING.md` inside the package. It is versioned in lockstep with the `@reticlehq/*` packages today; that is a release convenience, not a promise that the protocol changes whenever Reticle does.
+The protocol has its own compatibility rules, stated in `VERSIONING.md` inside the package. It carries its own version, separate from the `@reticlehq/*` packages: the protocol does not change whenever Reticle does.

package/docs/packages/server.mdx

@@ -6,7 +6,7 @@ icon: server
 
 `@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`.
 
-**Licensed under `SEE LICENSE IN LICENSE`, not Apache 2.0 like the rest.** This is the package the enterprise terms apply to.
+**Licensed under `FSL-1.1-ALv2` (the Functional Source License, converting to Apache 2.0), not Apache 2.0 like the SDK packages.** This is the package the enterprise terms apply to.
 
 ## Why it exists
 
@@ -24,9 +24,9 @@ The `bin` entry is `reticle`, so `npx @reticlehq/server <command>` works once it
 
 ## Dependencies
 
-**Runtime:** `@modelcontextprotocol/sdk`, `@reticlehq/core`, `ws`, `zod`.
+**Runtime:** `@modelcontextprotocol/sdk`, `@reticlehq/browser`, `@reticlehq/core`, `@reticlehq/engine`, `@reticlehq/init`, `open-verification`, `ws`, `zod`, `zod-to-json-schema`.
 
-**Optional:** `playwright`, `pixelmatch`, `pngjs`. Optional on purpose: Reticle observes the browser you already have. You only need Playwright for the paths that launch or diff one, which is `reticle drive`, `reticle verify`, and visual baselines.
+**Optional:** `playwright` (also a peer dependency, `>=1.50`), `pixelmatch`, `pngjs`. Optional on purpose: Reticle observes the browser you already have. You only need Playwright for the paths that launch or diff one, which is `reticle drive`, `reticle verify`, and visual baselines.
 
 ## Exports map
 
@@ -50,7 +50,7 @@ await server.close();
 
 | Option | Type | Default |
 | --- | --- | --- |
-| `port` | `number` | `RETICLE_PORT`, else `4400` |
+| `port` | `number` | `4400`. The CLI resolves `RETICLE_PORT` before it calls `start` |
 | `host` | `string` | `RETICLE_HOST`, else loopback. A non-loopback host requires a token |
 | `token` | `string` | `RETICLE_TOKEN` |
 | `allowedOrigins` | `string[]` | `RETICLE_ALLOWED_ORIGINS` |
@@ -71,7 +71,7 @@ await server.close();
 
 ### `RunningServer`
 
-`bridge: Bridge`, `close(): Promise<void>`, and the optional `realInput`, `verifyPort`, `isIdle()`, `agentAttached()`, `token`.
+`bridge: Bridge`, `close(): Promise<void>`, and the optional `realInput`, `verifyPort`, `isIdle()`, `agentAttached()`, `token`, `announceShutdown()`.
 
 ## What else the barrel exports
 

package/docs/packages/tauri.mdx

@@ -6,22 +6,17 @@ icon: rust
 
 `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.
 
-It is versioned **independently** of the ten npm packages. **MIT licensed, unlike the Apache 2.0 npm packages. Edition 2021.**
+It is versioned in **lockstep** with the `@reticlehq/*` npm packages, so `3.7` here and there is the same release. **MIT licensed, unlike the 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 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
 
 ```toml
 [dependencies]
-reticle-tauri = "3.6"
+reticle-tauri = "3.7"
 ```
 
 Its own dependencies are `tauri = "2.12"` (the Windows backend must use the same `webview2-com` and `windows` versions Tauri does, so it follows Tauri's minor version) plus the per-platform capture backends: `objc2` and friends on macOS, `webview2-com` and `windows` on Windows, `webkit2gtk` and `cairo-rs` on Linux and the BSDs.
@@ -34,6 +29,8 @@ tauri::Builder::default()
     .on_page_load(reticle_tauri::on_page_load)
 ```
 
+**Dev builds only.** In a release build the crate is inert: `reticle_capture` refuses and `on_page_load` does nothing, so the binary you sign and ship carries no Reticle capability. A release build you test with Reticle (a CI fixture) turns it on with `reticle-tauri = { version = "3.7", features = ["in-release"] }`.
+
 Nothing is needed on the JavaScript side. Tauri has no preload stage, so the SDK reaches `reticle_capture` through Tauri's own internals.
 
 ## The public API
@@ -43,6 +40,9 @@ Nothing is needed on the JavaScript side. Tauri has no preload stage, so the SDK
 | `reticle_capture` | `#[tauri::command] pub async fn reticle_capture(window: tauri::WebviewWindow, full_page: Option<bool>) -> Result<String, String>` |
 | `on_page_load` | `pub fn on_page_load<R: Runtime>(webview: &Webview<R>, payload: &tauri::webview::PageLoadPayload<'_>)` |
 | `FULL_PAGE_UNSUPPORTED` | `pub const FULL_PAGE_UNSUPPORTED: &str = "full-page-unsupported"` |
+| `ACTIVE` | `pub const ACTIVE: bool`: true in a debug build, or a release build with `in-release` |
+| `INERT_IN_RELEASE` | `pub const INERT_IN_RELEASE: &str`: what `reticle_capture` answers when the crate is inert |
+| `inert_refusal` | `pub fn inert_refusal() -> Option<&'static str>` |
 
 There are no public traits and no macros.
 
@@ -52,7 +52,7 @@ Runs on a blocking thread, writes a PNG into a per-process `0700` directory unde
 
 ### `on_page_load`
 
-Hides the window on `PageLoadEvent::Finished` when the environment variable `RETICLE_HEADLESS=1` is set. That ordering matters: the window exists and renders, then it is hidden, so the capture path still works.
+Hides the window on `PageLoadEvent::Finished` when the environment variable `RETICLE_HEADLESS=1` is set. That ordering matters: the window exists and renders, then it is hidden, so the capture path still works. On macOS it also keeps every window's webview scheduling while it is behind other windows (macOS 14 and later); on older macOS, headless moves the window offscreen instead of hiding it.
 
 ## The silent failure to know about
 

package/docs/packages/test.mdx

@@ -6,7 +6,7 @@ icon: vial
 
 `@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.
 
-**Licensed under `SEE LICENSE IN LICENSE`. Depends on `@reticlehq/core` and `@reticlehq/server`. Optional peer dependency: `vitest ^3.2.6`.**
+**Licensed under `FSL-1.1-ALv2`. Depends on `@reticlehq/core` and `@reticlehq/server`. Optional peer dependency: `vitest ^3.2.6 || ^4.0.0`.**
 
 ```bash
 npm i -D @reticlehq/test
@@ -47,10 +47,9 @@ await run.close();
 ## Writing specs
 
 ```ts
-import { reticleTest, type TestContext } from '@reticlehq/test';
+import { reticleTest } from '@reticlehq/test';
 
-reticleTest('login grants a session', async (spec) => {
-  const t = spec as TestContext;
+reticleTest('login grants a session', async (t) => {
   await t.fill('email', 'user@example.com');
   await t.fill('password', 'hunter2');
   await t.actAndWait('login-submit', 'click', { kind: 'signal', name: 'auth:granted' });
@@ -61,12 +60,7 @@ reticleTest('login grants a session', async (spec) => {
 
 `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>
+`SpecFn` types its argument as `SpecContext`, which is `TestContext`, so the methods below are typed without a cast.
 
 ## The test context
 

package/docs/packages/vite-plugin.mdx

@@ -35,7 +35,7 @@ Set `RETICLE_PORT` in the dev server or desktop build environment to use the sam
 
 ## Why it exists
 
-`apply: 'serve'` means it never reaches a production build. That is the guarantee that lets you leave it in the config permanently: there is no way to ship Reticle to your users by forgetting to remove a line.
+In a production `vite build` the plugin injects nothing and swaps the browser SDK for an inert stub, so the bundle carries no Reticle runtime code. That is the guarantee that lets you leave it in the config permanently: there is no way to ship Reticle to your users by forgetting to remove a line.
 
 ## What it injects
 
@@ -45,8 +45,11 @@ A virtual module at `/@reticle-connect`, added to the HTML, whose contents are:
 import { reticle, install } from '@reticlehq/react';
 install();
 reticle.connect({/* resolved args */});
+if (import.meta.hot) reticle.observeHotUpdates(import.meta.hot);
 ```
 
+An app with `@reticlehq/browser` and no `@reticlehq/react` (Vue, Svelte, plain TypeScript) gets the same module importing `reticle` from `@reticlehq/browser`, without `install()`.
+
 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.
 
 ## Options
@@ -55,7 +58,7 @@ Plus a dynamic import of your dev module if one exists. It looks for `src/reticl
 
 | Option | Type | Default |
 | --- | --- | --- |
-| `port` | `number` | Discovered from the daemon registry for this project, falling back to `4400` |
+| `port` | `number` | Used only when the daemon registry and `.reticle.json` name no port; otherwise `4400`. `RETICLE_PORT` overrides all of them |
 | `root` | `string` | Vite's `root`, else `process.cwd()` |
 | `sdkVersion` | `string` | Read from the installed `@reticlehq/react` |
 | `session` | `string` | Omitted, so the SDK generates one |
@@ -66,6 +69,11 @@ Plus a dynamic import of your dev module if one exists. It looks for `src/reticl
 | `inject` | `boolean` | `true`. Set `false` to call `connect()` yourself |
 | `desktop` | `boolean` | `false`. When `true` the connect passes `allowInProduction: true`, which an Electron or Tauri renderer needs, and a `vite build` in a non-production mode (`--mode development`) is instrumented too. A production-mode build is stubbed like a web build |
 | `captureNetworkBodies` | `boolean` | `false`. Also enabled by `VITE_RETICLE_CAPTURE_BODIES=1` |
+| `networkBodyMaxChars` | `number` | `8192`, clamped to 256 to 262144. Also `VITE_RETICLE_BODY_MAX_CHARS` |
+| `captureErrorBodies` | `boolean` | `true`: a failed response keeps its body. `VITE_RETICLE_NO_ERROR_BODIES=1` turns it off |
+| `testIdAttribute` | `string` | `.reticle.json`'s `testIdAttribute`, else `data-testid` |
+| `allowNonLocalhost` | `boolean` | `false`. Lets Reticle run off localhost; a pairing token is still required. Also `VITE_RETICLE_ALLOW_NON_LOCALHOST=1` |
+| `exposePresenter` | `boolean` | `false`. Contributors only: makes Reticle's own presenter visible to its tools |
 | `onWarn` | `(message: string) => void` | `console.warn` |
 
 `reticle({ present: false })` still lets the plugin create and configure the connection; it only hides Reticle's visible presenter. `reticle({ inject: false })` disables that generated connection, so your application must call `connect()` itself. In that manual call, pass the pairing token explicitly:
@@ -86,7 +94,7 @@ declare const __RETICLE_ROOT__: string;
 declare const __RETICLE_SDK_VERSION__: string;
 ```
 
-Vite replaces these `define` identifiers in application source at build time; the declarations let TypeScript typecheck them and do not create runtime globals. The SDK does not discover the pairing token, so pass it explicitly in a hand-written connection:
+Vite replaces these `define` identifiers in application source at build time; the declarations let TypeScript typecheck them and do not create runtime globals. The SDK does not discover the pairing token, so pass it explicitly in a hand-written connection.
 
 ## Other exports
 
@@ -100,7 +108,6 @@ Vite replaces these `define` identifiers in application source at build time; th
 | `readPairingToken` | `() => string \| undefined` | Read the pairing token from disk |
 | `findDevModule` | `(root: string, exists: (p: string) => boolean) => string \| null` | Locate the dev module |
 | `connectModuleSource` | `(options: ReticleVitePluginOptions, devModule?: string \| null) => string` | Build the injected module source |
-| `cjsDepIncludes` | `(appRoot: string, canResolve?: (dep: string) => boolean) => string[]` | CommonJS deps to add to `optimizeDeps` |
 
 Types: `ReticleVitePluginOptions`, `ReticleVitePlugin`, `ViteDevServerLike`.
 

package/docs/packages.mdx

@@ -5,11 +5,12 @@ description: Every Reticle package. What it does, why it exists, when you actual
 icon: cubes
 ---
 
-Reticle is twelve 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.
+Reticle is fourteen packages (thirteen on npm, one Rust crate), 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>
   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.
+  other `@reticlehq/*` package says too, and so does the `reticle-tauri` crate on crates.io. The
+  one exception is `open-verification`, the specification, which carries its own version.
 
 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.
 
@@ -55,7 +56,7 @@ Those rules are why the browser SDK cannot accidentally pull in a filesystem cal
 
 **Why it exists:** without one shared definition, the browser and the server drift. One renames a field, the other keeps reading the old one, and the failure is silent. A verdict that quietly stops carrying evidence. Core makes that a type error instead.
 
-**Depends on:** `zod`, and nothing else. That is the whole point; it sits at the bottom of the graph so everything can depend on it without cycles.
+**Depends on:** `zod` and `open-verification`, which itself depends only on `zod`. That is the whole point; it sits at the bottom of the graph so everything can depend on it without cycles.
 
 **Do you install it?** No. It arrives as a dependency of whatever you did install.
 
@@ -89,7 +90,7 @@ if (import.meta.env.DEV) reticle.connect();
 
 **Why it exists:** agents speak MCP; browsers speak WebSocket; somebody has to be fluent in both and own the `.reticle/` directory where flows, baselines and runs are stored.
 
-**Depends on:** `@modelcontextprotocol/sdk`, `@reticlehq/core`, `@reticlehq/init`, `ws`, `zod`.
+**Depends on:** `@modelcontextprotocol/sdk`, `@reticlehq/browser`, `@reticlehq/core`, `@reticlehq/engine`, `@reticlehq/init`, `open-verification`, `ws`, `zod`, `zod-to-json-schema`. **Peer:** `playwright`.
 
 **Do you install it?** Not into your project. Your agent launches it:
 
@@ -129,7 +130,7 @@ npm i -D @reticlehq/react
 
 **One line in `vite.config.ts`, two jobs.** It stamps source locations onto your JSX and injects `connect()` so you cannot forget to.
 
-**Why it exists:** the two things everyone forgets are wiring the SDK and enabling source mapping. This does both, and `apply: 'serve'` guarantees it never reaches a production build.
+**Why it exists:** the two things everyone forgets are wiring the SDK and enabling source mapping. This does both, and in a production `vite build` it swaps the SDK for an inert stub, so it never reaches a production bundle.
 
 **Depends on:** `@babel/core`, `@reticlehq/babel-plugin`, `@reticlehq/core`. **Peer:** `vite`.
 
@@ -149,7 +150,7 @@ export default defineConfig({ plugins: [reticle(), react()] });
 
 **Why it exists:** React 19 dropped `_debugSource`, which is what source mapping used to rely on. This plugin puts the information back, at build time, in dev only. Without it, `reticle_look { action: "element" }` can still tell you the component name but not the file.
 
-**Depends on:** nothing. **Peer:** `@babel/core`.
+**Depends on:** `@reticlehq/core`. **Peer:** `@babel/core`.
 
 **Do you install it?** Only directly if you are wiring Babel yourself. The Vite and Next packages both pull it in.
 
@@ -191,7 +192,7 @@ module.exports = withReticle({/* your config */});
 
 **Why it exists:** the decision and the machinery that feeds it are different jobs with different reasons to change. Carved out of `@reticlehq/server` so the part that judges can be read, tested and reused without starting anything.
 
-**Depends on:** `@reticlehq/core`, `zod`.
+**Depends on:** `@reticlehq/core`, `open-verification`, `zod`.
 
 ---
 
@@ -211,7 +212,7 @@ module.exports = withReticle({/* your config */});
 
 ## @reticlehq/eslint-plugin
 
-**Two rules, the main one being: state changed, so a signal must fire.**
+**Three 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.
 
@@ -233,20 +234,15 @@ 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 in lockstep with the npm packages, so `2.11` here and `2.11` there mean the same release.
+**The Rust crate**, on crates.io. Versioned in lockstep with the npm packages, so `3.7` here and `3.7` 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 = "3.6"
+reticle-tauri = "3.7"
 ```
 
-<Warning>
-  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">
   Electron and Tauri wiring, including the Tauri CSP whose failure is silent.
 </Card>

package/docs/platform-integration.md

@@ -4,7 +4,7 @@ description: 'Adopt Reticle on your own codebase, or embed it inside an AI app-b
 icon: plug
 ---
 
-Two ways in. **A team** runs `npx @reticlehq/server init` once and points its coding agent at the MCP server. **A platform** adds the dev-only SDK to its generated-app template, runs `npx @reticlehq/server serve --http --drive <preview-url>` beside each preview, and `POST`s to `/verify` after every generate or edit, gating the ship on `run.verdict.status === 'pass'` and feeding `run.repair.failurePackets[]` back to a fixer agent.
+Two ways in. **A team** runs the install script once, which registers the MCP server with its coding agents, and follows the next steps it prints. **A platform** adds the dev-only SDK to its generated-app template, runs `npx @reticlehq/server serve --http --drive <preview-url>` beside each preview, and `POST`s to `/verify` after every generate or edit, gating the ship on `run.verdict.status === 'pass'` and feeding `run.repair.failurePackets[]` back to a fixer agent.
 
 > The one guide for adopting Reticle, both for a team using a coding agent on its own app and for an AI app-builder platform (Lovable / Emergent / Bolt) embedding Reticle in its generation pipeline. Reticle reads the program from _inside_ a running app and returns a **verdict with evidence** ("did it actually work?"), not a screenshot. Enterprise/premium access lives in [`enterprise.md`](./enterprise.md).
 
@@ -29,10 +29,11 @@ One call replays the app's key journeys and asserts **program truth** (network c
 ### A. A team, agent on your own app (~10 min)
 
 ```bash
-npx @reticlehq/server init   # auto-detects your framework, installs the kit + build plugin
+curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh
+irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex   # Windows
 ```
 
-Paste to your agent (Claude Code / Cursor / any MCP agent): `Follow https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md` It runs the wizard once (Vite/Next plugin + SDK init + MCP config), then verifies on every change. Run your dev server, then ask the agent to _"verify it with Reticle."_
+It puts the CLI on the machine and registers the MCP server with the coding agents it finds. Then do what it prints: restart your coding agent so it loads Reticle's tools, and paste the prompt the script prints into it. The agent runs `reticle init` in your app (build plugin, SDK connect file, agent rules), then proves one flow. No agent? Run `reticle init` in the app yourself.
 
 ### B. A platform / CI, driven from your pipeline (no MCP, no human)
 
@@ -87,7 +88,7 @@ Copyable patterns: `apps/bench-app/src/reticle-dev.ts`, `apps/next-smoke/app/ret
 | Missing validation (`"abc"` becomes data) | flow oracle (error shown AND nothing created) |
 | Silent console error (logged, UI still renders) | `console { absent: true }` |
 | UI-vs-store desync (the total lies) | reads the store, contradicts the display |
-| Blast-radius (an action corrupts unrelated state) | `state { hold:true }` invariant |
+| Blast-radius (an action corrupts unrelated state) | a `state { path, equals }` invariant on the unrelated value |
 
 Live, clickable demo of each: `apps/vibe-builder-demo/` (set `BUG_MODE=…`). Proven in CI: `server/src/judgement/runs/generated-app-bugs.test.ts`.
 
@@ -133,7 +134,7 @@ The shape is identical (in-app SDK in the template → verify in the sandbox →
 2. Since the runtime is in-browser, drive via the connected session (the SDK dials the bridge) rather than `--drive`; call verify from the Bolt agent after a build.
 3. Same act-on-verdict: gate + self-heal with the repair packets. (Bolt already detects terminal/compile errors; Reticle adds the _runtime program-truth_ layer it's blind to.)
 
-> Honest note: a platform can build a verification step itself. Reticle's case is the depth (program-state and source mapping), the determinism (0% flake, no LLM in the loop), the un-hallucinatable verdict, and a stable drop-in artifact. The reproducible benchmark in [`bench/`](https://github.com/reticlehq/reticle/blob/main/bench/README.md) measures the observation-cost and detection differences against other browser-automation MCPs.
+> Honest note: a platform can build a verification step itself. Reticle's case is the depth (program-state and source mapping), the determinism (no LLM in the loop), the un-hallucinatable verdict, and a stable drop-in artifact. The reproducible benchmark in [`bench/`](https://github.com/reticlehq/reticle/blob/main/bench/README.md) measures the observation-cost and detection differences against other browser-automation MCPs.
 
 ---