@reticlehq/server 3.7.0 → 3.8.1

package/docs/packages/core.mdx

@@ -12,7 +12,7 @@ icon: cube
 
 Without one shared definition the browser and the server drift. One side renames a field, the other keeps reading the old one, and the failure is silent: a verdict that quietly stops carrying its evidence. Core makes that a type error instead.
 
-The narrow dependency list is the point. `open-verification` itself depends on `zod` alone, so the graph stays acyclic: everything can depend on core, and nothing core does can drag a filesystem call into the browser bundle. This page said "depends on `zod` and nothing else" until v3 extracted the protocol and nobody updated the sentence.
+The narrow dependency list is the point. `open-verification` itself depends on `zod` alone, so the graph stays acyclic: everything can depend on core, and nothing core does can drag a filesystem call into the browser bundle.
 
 ## Do you install it?
 
@@ -32,6 +32,7 @@ npm i @reticlehq/core
 | `./hooks` | What Reticle says happened, for hook consumers |
 | `./hud` | Constants shared by the daemon and the HUD panel |
 | `./tour` | The onboarding tour |
+| `./activation` | The signed activation ticket: `signActivationTicket` for the service that makes tickets, `verifyActivationTicket` for the page loader. See [Production mode](/production-mode) |
 | `./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/docs/packages/electron.mdx

@@ -73,13 +73,25 @@ The handler calls `webContents.capturePage()`, writes the PNG into a per-process
 
 ## Renderer wiring
 
-The renderer still needs the SDK. A packaged app is a production build, so the connect call has to opt in:
+The renderer still needs the SDK. Connect only in development, never in the app you ship. For example, send `!app.isPackaged` from the main process to the renderer, and connect only when it is true. An Electron renderer reports `NODE_ENV=production`, so the call also needs `allowInProduction`:
 
 ```ts
-reticle.connect({ allowInProduction: true });
+import { reticle } from '@reticlehq/browser';
+
+// isDevelopment is `!app.isPackaged`, sent from the main process.
+if (isDevelopment) {
+  // reticle.local.js holds this machine's pairing token. Do not commit it.
+  import('./reticle.local.js')
+    .catch(() => ({}))
+    .then((local) => reticle.connect({ allowInProduction: true, token: local.token }));
+}
 ```
 
-Or, with the Vite plugin, `reticle({ desktop: true })`.
+The bridge refuses a connect without the pairing token, also from a `file://` page. For an Electron app without the Vite plugin, `reticle init` does not write `reticle.local.js`. Make it from `~/.reticle/pairing-token` as the [browser page](/packages/browser) shows, and add it to `.gitignore`.
+
+Keep `reticle.local.js` out of the package: electron-builder `files: ["!reticle.local.js"]`, or Electron Forge `packagerConfig.ignore: [/reticle\.local\.js$/]`.
+
+With the Vite plugin, use `reticle({ desktop: true })` instead. The plugin passes the token and `allowInProduction`, and a production-mode build ships no Reticle code.
 
 <Card title="Desktop setup in full" icon="display" href="/desktop">
   Electron and Tauri wiring, and what `reticle doctor` checks for each.

package/docs/packages/eslint-plugin.mdx

@@ -4,7 +4,7 @@ description: Three lint rules that keep Reticle's signal layer and its comment h
 icon: shield-check
 ---
 
-`@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.
+`@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 want the linter to tell you when a new mutation has no signal.
 
 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.
 

package/docs/packages/next.mdx

@@ -70,24 +70,36 @@ An async webpack loader. It skips anything that is not `.jsx`, `.tsx` or a `.js`
 
 ## What it does not do
 
-It does not inject `connect()`. On Next you call it yourself, once, in a client component:
+It does not inject `connect()`. On Next you call it once, in a client component that your root layout renders. `reticle init` writes this component for you at `app/reticle-dev.tsx` (or `src/app/reticle-dev.tsx`). To write it by hand:
 
 ```tsx
 'use client';
 import { useEffect } from 'react';
-import { reticle, install } from '@reticlehq/react';
 
 export function ReticleDev() {
   useEffect(() => {
-    if (process.env.NODE_ENV !== 'production') {
+    if (process.env.NODE_ENV !== 'development') return;
+    void import('@reticlehq/react').then(({ reticle, install }) => {
       install();
-      reticle.connect();
-    }
+      // withReticle() in next.config sets these. The bridge refuses a connect without the token.
+      const token = process.env.NEXT_PUBLIC_RETICLE_TOKEN;
+      const url = process.env.NEXT_PUBLIC_RETICLE_URL;
+      const root = process.env.NEXT_PUBLIC_RETICLE_ROOT;
+      const sdkVersion = process.env.NEXT_PUBLIC_RETICLE_SDK_VERSION;
+      reticle.connect({
+        ...(url ? { url } : {}),
+        ...(token ? { token } : {}),
+        ...(root ? { root } : {}),
+        ...(sdkVersion ? { sdkVersion } : {}),
+      });
+    });
   }, []);
   return null;
 }
 ```
 
+`NEXT_PUBLIC_RETICLE_TOKEN` is empty when the daemon has not yet written `~/.reticle/pairing-token`. Start the daemon, then restart `next dev`.
+
 <Card title="Framework by framework" icon="layer-group" href="/frameworks">
   What each supported stack needs, and what it gets for free.
 </Card>

package/docs/packages/react.mdx

@@ -22,10 +22,16 @@ npm i -D @reticlehq/react
 
 ```ts
 import { reticle, install } from '@reticlehq/react';
+
 install();
-reticle.connect();
+// reticle.local.js holds this machine's pairing token. Do not commit it.
+import('./reticle.local.js')
+  .catch(() => ({}))
+  .then((local) => reticle.connect({ token: local.token }));
 ```
 
+The bridge refuses a connect without the pairing token, also on localhost. `reticle init` writes `reticle.local.js` and adds it to `.gitignore`. Without init, make it from `~/.reticle/pairing-token` as the [browser page](/packages/browser) shows.
+
 ## Exports
 
 ### Setup
@@ -72,6 +78,7 @@ The [Vite plugin](/packages/vite-plugin) injects `install()` and `reticle.connec
 One export, and the only module in the package that imports React:
 
 ```ts
+import { useState } from 'react';
 import { useReticleStore } from '@reticlehq/react/store';
 
 function Cart() {

package/docs/packages/server.mdx

@@ -20,13 +20,13 @@ Not into your project. Your agent launches it:
 npx @reticlehq/server mcp
 ```
 
-The `bin` entry is `reticle`, so `npx @reticlehq/server <command>` works once it is on disk.
+The `bin` entry is `reticle`. Run any command as `npx @reticlehq/server <command>`, or as `reticle <command>` after the one-line installer puts the package on your machine.
 
 ## Dependencies
 
 **Runtime:** `@modelcontextprotocol/sdk`, `@reticlehq/browser`, `@reticlehq/core`, `@reticlehq/engine`, `@reticlehq/init`, `open-verification`, `ws`, `zod`, `zod-to-json-schema`.
 
-**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.
+**Optional:** `playwright` (also a peer dependency, `>=1.50`), `pixelmatch`, `pngjs`. Optional on purpose: Reticle observes the browser you already have. You need Playwright only for the paths that launch or compare a browser: the zero-install lease, `reticle try`, `reticle drive`, `reticle verify` and visual baselines. `reticle open` uses your own browser and does not need it.
 
 ## Exports map
 
@@ -71,7 +71,7 @@ await server.close();
 
 ### `RunningServer`
 
-`bridge: Bridge`, `close(): Promise<void>`, and the optional `realInput`, `verifyPort`, `isIdle()`, `agentAttached()`, `token`, `announceShutdown()`.
+`bridge: Bridge`, `close(): Promise<void>`, and the optional `realInput`, `verifyPort`, `isIdle()`, `agentAttached()`, `token`, `announceShutdown()` and `onShutdownRequest(handler)`. The last one runs `handler` when an authenticated `POST /shutdown` asks the daemon to stop.
 
 ## What else the barrel exports
 

package/docs/packages/tauri.mdx

@@ -6,7 +6,7 @@ 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 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.**
+It is versioned in **lockstep** with the `@reticlehq/*` npm packages, so `3.8` here and `3.8` on npm is the same release. **MIT licensed, unlike the npm packages. Edition 2021.**
 
 ## Why it exists, and why it is small
 
@@ -16,7 +16,7 @@ Tauri IPC observation needs nothing on the Rust side. An `invoke('load_todos')`
 
 ```toml
 [dependencies]
-reticle-tauri = "3.7"
+reticle-tauri = "3.8"
 ```
 
 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.
@@ -29,7 +29,7 @@ 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"] }`.
+**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.8", 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.
 

package/docs/packages/vite-plugin.mdx

@@ -73,7 +73,7 @@ Plus a dynamic import of your dev module if one exists. It looks for `src/reticl
 | `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 |
+| `exposePresenter` | `boolean` | `false`. Contributors only: makes Reticle's own presenter visible to its tools. Also `VITE_RETICLE_EXPOSE_PRESENTER=1` |
 | `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:

package/docs/packages.mdx

@@ -33,7 +33,7 @@ It was versioned independently until 2.12.0, and that turned out to mean _stuck_
   </Card>
 </CardGroup>
 
-You never install `@reticlehq/server`. Your agent runs it with `npx`.
+You never add `@reticlehq/server` to your project. The one-line installer puts it on your machine, or your agent runs it with `npx`.
 
 ## The architecture in one rule
 
@@ -79,7 +79,20 @@ Those rules are why the browser SDK cannot accidentally pull in a filesystem cal
 
 ```ts
 import { reticle } from '@reticlehq/browser';
-if (import.meta.env.DEV) reticle.connect();
+
+if (import.meta.env.DEV) {
+  // reticle.local.js holds this machine's pairing token. Do not commit it.
+  import('./reticle.local.js')
+    .catch(() => ({}))
+    .then((local) => reticle.connect({ token: local.token }));
+}
+```
+
+The bridge refuses a connect without the pairing token, also on localhost. `reticle init` writes `reticle.local.js` at the project root and adds it to `.gitignore`. Change the import path so that it points to that file. If you did not run `reticle init`, make the file yourself from the token that the daemon keeps in `~/.reticle/pairing-token`:
+
+```bash
+printf "export const token = '%s';\n" "$(cat ~/.reticle/pairing-token)" > reticle.local.js
+echo reticle.local.js >> .gitignore
 ```
 
 ---
@@ -178,7 +191,7 @@ module.exports = withReticle({/* your config */});
 
 ## open-verification
 
-**The specification, as a package.** The vocabulary a verification is described in (subject, channel, intent, claim, window, observation, evidence, coverage, verdict), plus `Realm`, the interface an implementation answers, and `adjudicate()`, the function that turns evidence into a verdict. It ships `SPEC.md`, a JSON Schema for every noun, and a conformance suite that scores an implementation against the rules.
+**The specification, as a package.** The vocabulary a verification is described in (subject, channel, intent, claim, window, observation, evidence, coverage, verdict), plus `Realm`, the interface an implementation answers, and `adjudicate()`, the function that turns evidence into a verdict. It ships `SPEC.md`, a JSON Schema for every noun, and test vectors that a second implementation can check itself against.
 
 **Why it exists:** Reticle's rules about what may buy a green were real and were scattered. The independence rule lived in a channel table, the four verdict values in an enum, the blind-spot idea in a coverage type, and nothing said they were one contract that something other than Reticle could implement. You do not need this package to use Reticle. You need it to write something else that can be checked the same way, or to check what Reticle's verdicts actually mean.
 
@@ -200,7 +213,7 @@ module.exports = withReticle({/* your config */});
 
 **The spec runner for CI.** `reticleTest` registers declarative specs and runs them against Reticle's tools directly, with no MCP or stdio in the loop.
 
-**Why it exists:** driving interactively is reconnaissance. At some point you want the same checks to run on every pull request without an agent. And without paying model tokens to re-derive them.
+**Why it exists:** driving interactively is reconnaissance. At some point you want the same checks to run on every pull request, without an agent and without paying model tokens to derive them again.
 
 **Depends on:** `@reticlehq/core`, `@reticlehq/server`. **Peer:** `vitest`.
 
@@ -234,13 +247,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 in lockstep with the npm packages, so `3.7` here and `3.7` there mean the same release.
+**The Rust crate**, on crates.io. Versioned in lockstep with the npm packages, so `3.8` here and `3.8` 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.7"
+reticle-tauri = "3.8"
 ```
 
 <Card title="Desktop setup in full" icon="display" href="/desktop">

package/docs/platform-integration.md

@@ -33,7 +33,7 @@ curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/inst
 irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex   # Windows
 ```
 
-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.
+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. To teach the agent the workflow, also add the skill: `npx skills add reticlehq/reticle --skill reticle`. 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)
 
@@ -56,7 +56,7 @@ const { run } = await (
 if (run.verdict.status !== 'pass') {
   for (const p of run.repair?.failurePackets ?? []) fixerAgent.send(p.suggestedPrompt); // self-heal
   blockDeploy(run);
-} else attachToDeploy(run); // "verified ✓"; set profile:"prod-preview" to redact internals downstream
+} else attachToDeploy(run); // "verified ✓". POST /verify redacts internals by default (profile "prod-preview"); pass profile:"dev" for the full run.
 ```
 
 Or skip the HTTP server entirely with the one-shot CLI: `reticle verify <preview-url>` drives the preview, replays the saved flows, prints the verdict, and exits non-zero on fail (ideal for a CI step).
@@ -90,7 +90,7 @@ Copyable patterns: `apps/bench-app/src/reticle-dev.ts`, `apps/next-smoke/app/ret
 | UI-vs-store desync (the total lies) | reads the store, contradicts the display |
 | 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`.
+Proven in CI: `server/src/judgement/runs/generated-app-bugs.test.ts`.
 
 ---
 
@@ -140,10 +140,18 @@ The shape is identical (in-app SDK in the template → verify in the sandbox →
 
 ## The verdict artifact
 
-`POST /verify` (and `reticle_run_export`) return a stable, versioned `ReticleVerificationRun` (defined in `@reticlehq/core`): `verdict` (pass/fail/partial, confidence, blockingRisks), `flows[]`, `checks[]`, `risks[]` (auth/payment/db/…), `repair.failurePackets[]` (what + where to fix), `evidence`. Render a legible report with `renderRunReport()` or `reticle_run_export { format: "report" }`. Profiles: `dev` (full) vs `prod-preview` (source + state redacted for downstream sharing).
+`POST /verify` (and `reticle_run_export`) return a stable, versioned `ReticleVerificationRun` (defined in `@reticlehq/core`): `verdict` (pass/fail/partial, confidence, blockingRisks), `flows[]`, `checks[]`, `risks[]` (auth/payment/db/…), `repair.failurePackets[]` (what + where to fix), `evidence`. Render a legible report with `renderRunReport()` or `reticle_run({ tool: "reticle_run_export", args: { format: "report" } })`. Profiles: `dev` (full) and `prod-preview` (source and state redacted for sharing). `POST /verify` uses `prod-preview` unless you pass `profile: "dev"`.
 
 **Why trust it:** the verdict is mechanical, derived only from observed outcomes, so it can't report green for something it never ran (a severed backend reads as _fail_, never a confident pass). Proof: `server/src/judgement/runs/false-green.test.ts`.
 
+## Building a hosted verifier on the engine
+
+A service that drives apps it did not build uses these seams.
+
+- **Follow a drive to another origin.** `new Bridge({ ..., followNavigation })` lets a session continue on an origin the bridge was not built with. A page on a new origin can only continue a session the bridge already admitted, after the token or nonce check, and only when `followNavigation({ sessionId, from, to, url })` returns `true`. Return `true` only when your own browser's top frame is now on `to`. Without the option, nothing changes.
+- **Refuse `clean` over what the engine could not see.** Every `reticle_act_and_wait` and `reticle_assert` result carries `engineBlindSpots`: what this engine could not observe in the session so far. It is cumulative, so the last verdict result of a run is the run's list, and `[]` means none. `pixels-unobserved`: an action ran while a `<canvas>` was visible, and no canvas digest is recorded. `claim-arithmetic-unchecked`: a claim under test (the call's `intent`, or an intent declared in the run) states an amount, and no verdict ran a `compare`. Do not call a run clean while its list has an entry. The kinds and the schema are `EngineBlindSpotKind` and `EngineBlindSpotSchema` in `@reticlehq/core`.
+- **Say that you injected the SDK.** When your init script connects the SDK into a page that does not import it, call `reticle.connect({ ..., injected: true })`. The HELLO then carries `instrumentation: "injected"`, `Session.instrumentation` holds it, and the session listing shows it. Do not count such a session as an app with the SDK installed: signals, module-scope stores and file:line still need the app. To read React component state and provider-passed stores (Redux, TanStack Query) on such a page, bundle `install()` from `@reticlehq/react` into the same init script and call it before `connect`. That entry imports only `@reticlehq/browser` and `@reticlehq/core` at runtime, so the bundle holds no copy of React.
+
 ## Licensing for embedding
 
 The embeddable SDK is **Apache-2.0** (ship it in your customers' apps). The server/CLI is **FSL** (free, no competing resale). Enterprise features + the premium-access flow: [`enterprise.md`](./enterprise.md). OEM terms: **[hey@reticle.sh](mailto:hey@reticle.sh)**.

package/docs/predicates.mdx

@@ -71,7 +71,13 @@ Add `"absent": true` to assert something is **gone**. The predicate for a remova
 { "kind": "text", "contains": "Saved successfully", "visible": true }
 ```
 
-`contains` is the field the published schema declares. `value`, `text` and `query` are accepted as aliases and rewritten to it. The match is case-sensitive; `ignoreCase: true` relaxes that. `absent: true` asserts the text is not present, and `visible: true` requires it to be on screen rather than merely in the DOM.
+`contains` is the field the published schema declares. `value`, `text` and `query` are accepted as aliases and rewritten to it. The match is case-sensitive. `ignoreCase: true` relaxes that. Curly quotes (`‘ ’ “ ”`), the en dash and the em dash match their plain forms. So `It's saved - done` matches a page that shows `It’s saved – done`. Text that Reticle reports back keeps the page's own characters. `absent: true` asserts the text is not present, and `visible: true` requires it to be on screen rather than merely in the DOM.
+
+`text` reads the text that the page renders. It does not read what is typed into an `<input>` or a `<textarea>`, because that is the field's value, not text on the page. `value` on a `text` predicate is only an alias for `contains`, so it also reads rendered text. To assert what a field holds, use an `element` predicate with `value`:
+
+```json
+{ "kind": "element", "query": { "role": "textbox", "name": "Notes", "value": "Ship on Friday" } }
+```
 
 Use `scope` to restrict the search to a CSS selector or element ref. If Reticle reports that the text is split across the scope's children, retry its generated predicate with `"self": true`; that checks the scope root's combined subtree text while still enforcing `contains`.
 
@@ -178,7 +184,7 @@ A passing route verdict quotes the transition itself:
 { "kind": "signal", "name": "webhook:received", "dataMatches": { "provider": "stripe", "id": "*" } }
 ```
 
-The app emitted a named signal via `reticle.signal()`. `dataMatches` matches field by field, a key can be a dotted path (`"order.total"`), and `*` means "present, any value".
+The app emitted a named signal via `reticle.signal()`. `dataMatches` matches field by field, a key can be a dotted path (`"order.total"`), and `*` means "present, any value". Without `name`, the check matches any signal from the app. It ignores Reticle's own signals, such as `reticle:busy`. To match one of those, name it.
 
 `count` works here exactly as it does on `net`:
 
@@ -186,7 +192,7 @@ The app emitted a named signal via `reticle.signal()`. `dataMatches` matches fie
 { "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.
+**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` is exact on `signal` and on `net`. Leave it out to ask for at least one. `count: 0` means never, and Reticle holds it like every other absence: for at least one second, and until the page goes quiet. A signal or a request that comes late still fails it.
 
 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.
 
@@ -219,7 +225,7 @@ Omit `equals` entirely to assert presence. A real `$length` check against this f
 }
 ```
 
-Note `grade: state` in the `because` line, and that the evidence collapses each row to a size marker rather than returning forty objects.
+The `because` line names the grade ("at state grade"). The evidence shows each row as a size marker, not as forty objects.
 
 #### satisfies: asserting a property instead of exact bytes
 
@@ -318,7 +324,12 @@ This is the predicate that catches a UI-versus-store desync. A deploy that only
 { "kind": "settled", "quietMs": 500 }
 ```
 
-Network and DOM idle. This is the deterministic replacement for a fixed sleep, not a proof of anything: combine it with a real consequence rather than asserting it alone. Omitting `until` on [`reticle_act_and_wait`](/tools/act-and-wait) waits for exactly this.
+The page is quiet: no request in flight, no response body still streaming, no work that the app declared with `reticle.busy()` still pending, and no network or DOM activity for `quietMs` (default 500). This is the deterministic replacement for a fixed sleep, not a proof of anything. Combine it with a real consequence. Do not assert it alone. If you omit `until` on [`reticle_act_and_wait`](/tools/act-and-wait), it waits for exactly this.
+
+`channel` changes what counts as activity:
+
+- `"network"`: requests only. No request in flight, and no request completed in the last `quietMs`. DOM changes, such as a running animation, do not hold it open. A saved `net` check with a `count` uses this, so a late duplicate request is still counted.
+- `"app"`: the default activity plus every framework render commit. Use it for an app whose renders are its work. The default ignores render commits, because on many pages a clock or a counter renders every second, and the page would never go quiet.
 
 ### compare
 
@@ -380,7 +391,7 @@ A fault-injection test (mock a 500, check the error UI) is asserting that a requ
 
 Asserting only the error text is not enough, and this is the most common way to get a confusing `verified: "no"`. Reticle watches for "the UI moved forward while a request failed", a swallowed rejection, and one of the most expensive bugs it catches. A fault-injection test looks **exactly** like that bug from the outside: a request failed, the screen changed, nothing said that was the plan.
 
-Naming the failing call is what tells the two apart. A `net` clause with `status` of 400 or more, or `"ok": false`, which is the honest field for IPC, where there is no status code, marks that call as expected to fail, and a failure there stops being a disagreement.
+Naming the failing call is what tells the two apart. A `net` clause with `status` of 400 or more, or `"ok": false` (the field for IPC, which has no status code), marks that call as expected to fail. A failure there is then not a disagreement. The same rule applies to the `expect` of each step in `reticle_act { steps }` and in a replayed flow: each step declares its own expected failures. A failure that no step declared is still reported.
 
 <Warning>
   Declare it in the top level or inside `allOf`. A declaration inside `anyOf` is deliberately
@@ -452,7 +463,7 @@ On a failure each child reports separately too, so you can see which one broke:
 | `timeout_ms` | `reticle_assert` (both actions), `reticle_act_and_wait` | Wait up to N ms for it to become true |
 | `since` | `net`, `route`, `console`, `animation` and `signal` leaves, and the call itself | Only consider events after this cursor |
 
-The `since` cursor comes from a prior `reticle_act` or `reticle_observe` response. Use it whenever you are asserting something an action was supposed to cause. Without it, an assertion can pass on an event from two clicks ago. That applies to every one of the five kinds above, not only to network calls: an unscoped `signal` matches a fire from an earlier action just as readily.
+The `since` cursor comes from a prior `reticle_act` or `reticle_observe` response. When you leave it out, the window starts at your last act, so a signal from an earlier action cannot pass the check. Give `since` when the cause is not your last act, for example when you assert on a cursor that you took before two actions. Before your first act there is no last act, and the window is the whole buffer.
 
 <Card title="Where predicates get used" icon="circle-check" href="/tools/act-and-wait">
   Naming the consequence before the action is the whole point.

package/docs/production-mode.md

@@ -0,0 +1,108 @@
+---
+title: 'Production mode'
+description: 'Let an agent drive your live site under a policy that refuses payments, deletions, invites and role changes.'
+icon: shield
+---
+
+Production mode lets an agent drive a live site, not only a development build. It is opt-in. It is dormant until you activate it for one drive. A visitor who did not activate it gets no SDK, no socket and no prompt.
+
+## What you need
+
+- A Reticle service that issues activation tickets (`POST /v1/production-mode/tickets`). A service without this route answers 404, and the lease says "the server does not offer production mode".
+- This project linked to that service: `reticle connect`, or `RETICLE_API_KEY`.
+- The loader in your site's staging and production builds (below). It checks the ticket in the page, with the service's public key.
+- A browser that is signed in to the site, as the person whose API key asks for the ticket. The service issues a ticket only for that person, in that workspace. A leased browser starts signed out, so give the lease your session cookies in `seedStorage` (see below).
+
+## Install the loader on staging and production
+
+Call `activate` once, at startup, with the public key that the dashboard shows you:
+
+```ts
+import { activate } from '@reticlehq/browser/activate';
+
+void activate({ publicKey: '<the public key from the dashboard>' });
+```
+
+In Vite, put it in `main.ts`. In Next.js, put it in a client component that the root layout renders, inside a `useEffect`.
+
+A visitor's page load reads one query parameter and stops. It loads no SDK, opens no socket, and writes no storage and no DOM. Only a URL with a valid `reticle_activate` ticket loads the SDK. The loader then removes the parameter from the address bar and connects with the ticket's nonce, bridge and scope. The loader refuses a ticket that has a bad signature, that expired, that is for another origin, or whose bridge is not `wss://` (`ws://` only on a loopback host). A refused ticket loads nothing and writes one `console.warn` line.
+
+The session reads as an installed SDK, not an injected one.
+
+### The ticket
+
+The ticket is `<payload>.<signature>`, both base64url. The payload is JSON: `{ v: 1, nonce, origin, bridge, scope, exp }`, where `exp` is epoch ms. The signature is Ed25519 over the ASCII bytes of the payload part. A service mints tickets with `signActivationTicket(privateKey, payload)` from `@reticlehq/core`. The page checks them with `verifyActivationTicket`.
+
+## Activate a drive
+
+One `reticle_lease` call does it:
+
+```json
+{
+  "action": "acquire",
+  "url": "https://app.example.com/",
+  "seedStorage": { "cookies": { "<session cookie name>": "<value>" } },
+  "production": {
+    "workspaceId": "ws_123",
+    "scope": "act",
+    "intent": "create a project, then delete it"
+  }
+}
+```
+
+The daemon then does three things:
+
+1. It mints a single-use session nonce for the site's origin. The nonce expires after 60 minutes.
+2. It asks the service for a ticket with the linked API key: `{ workspaceId, nonce, bridgePort, scope, origin, bridge }`. `origin` is the site's origin and `bridge` is the bridge the page dials (`ws://127.0.0.1:<port>/reticle`). The service signs the ticket for exactly those two values. It also decides who may activate.
+3. It opens `https://app.example.com/?reticle_activate=<ticket>` in a leased browser.
+
+A host that embeds the engine and runs its own bridge passes its cloud link as `ToolDeps.linkedCloud`, and its bridge as `bridgePort` and `nonces`. It needs no `cloud.json`. Such a host must not inject the SDK into a production lease's browser context. An injected copy connects first, as a development session, and the loader's `connect` then does nothing.
+
+If no page connects, the lease answers `ready: false`. The usual cause is a signed-out browser: the service refused the ticket, and the page loaded without an activation. Release the lease, then acquire again with your session cookies in `seedStorage`.
+
+The page connects with the nonce. The daemon accepts a production HELLO only with a live production nonce, never with the machine's pairing token. The first tab that presents the nonce owns it. That tab can reconnect after a reload. Another tab is refused.
+
+## What the policy refuses
+
+The daemon enforces the policy where it sends commands, not in the page.
+
+**Scope `observe`** refuses every act. The agent can still look, observe, assert and navigate.
+
+**Scope `act`** refuses these actions, unless the drive's `intent` names the action:
+
+| Rule                          | Examples                                             |
+| ----------------------------- | ---------------------------------------------------- |
+| payment or checkout           | Upgrade, Pay, Add card; `POST /billing`, `/checkout` |
+| delete a workspace or project | Delete project; `DELETE /projects/:id`               |
+| revoke or rotate a key        | Revoke key, Rotate secret; `DELETE /keys/:id`        |
+| send an invite or email       | Send invite, Resend; `POST /invites`                 |
+| cancel a subscription         | Cancel subscription; `DELETE /subscriptions/:id`     |
+| change a member's role        | Make admin, a Role picker; `PATCH /members/:id`      |
+
+The daemon recognises an action in two ways:
+
+- **The control.** Its name, text, value, test id, link and form target.
+- **The request.** Its method and path, from a policy list. The service can send its own list with the ticket. Without one, the daemon uses `DEFAULT_PRODUCTION_POLICY` from `@reticlehq/core`.
+
+In a leased browser, each request the page sends passes the policy before it leaves the browser. A refused request gets a 403 and never reaches the site.
+
+A key press on a production drive runs in the page, never on the native keyboard. A native key goes to the control that has focus, so the policy could not see it. The policy judges a key press by the control it names. A key press that names no control is judged only by the requests it sends.
+
+These are always allowed:
+
+- navigation on the activated origin (leaving the origin is refused);
+- reading, filters, tabs and panels;
+- deleting something the drive itself created. The daemon notes the ids that the drive's own creates returned (a 2xx `POST` or `PUT` whose body has an `id`).
+
+An intent with a negation asks for nothing: "she does not invite anybody" does not allow an invite.
+
+## What a refusal looks like
+
+A refusal is never a silent no-op. The act fails, and its error names the rule:
+
+```
+refused: production policy: send an invite or email. A production drive does this only when its
+declared intent names it (reticle_lease production.intent).
+```
+
+The drive ends when the nonce expires. After that, every act is refused with `the session nonce expired`, and the page cannot reconnect.

package/docs/prompt-capture.md

@@ -0,0 +1,99 @@
+---
+title: Prompt capture
+description: How Reticle keeps each prompt you send and the agent's own tool calls, where they go, and every way to turn them off.
+---
+
+A verdict is checked against what the user asked for. An agent tells Reticle the request only when it remembers to, so `reticle init` installs a hook that hands over each prompt before the agent reads it.
+
+## What `init` installs
+
+`reticle init` adds a prompt-submit hook to the project-level config of each agent it finds that has one:
+
+| Agent | Config file |
+| --- | --- |
+| Claude Code | `.claude/settings.json` |
+| Cursor | `.cursor/hooks.json` |
+| Codex CLI | `.codex/hooks.json` |
+| Gemini CLI | `.gemini/settings.json` |
+| Windsurf | `.windsurf/hooks.json`, or `.devin/hooks.json` when it is there |
+| VS Code Copilot and Copilot CLI | `.github/hooks/reticle-prompt-capture.json` |
+| Factory Droid | `.factory/hooks.json` |
+
+Each hook runs `node "<bin>" hook prompt --agent <id> || npx -y @reticlehq/server@<version> hook prompt --agent <id>`. `<bin>` is the CLI that ran `init`, written as `$HOME/…` when it is under your home folder. When that file is not there, `node` stops before it reads the prompt and `npx` runs instead. On Windows, and in Copilot's `powershell` field, the hook runs the `npx` command alone. The version is pinned to the one that ran `init`. Run `init` or `reticle hook install` again after an upgrade to move the pin. These files are in your repository, so a teammate who commits them shares the hook. Codex runs these hooks only after you trust them: open `codex` in the project, type `/hooks` and trust the Reticle entries.
+
+Agents with no prompt hook, such as Claude Desktop, get an instruction in the MCP server's instructions: declare the request with `reticle_intent` once for each user request.
+
+## What it writes
+
+The hook writes two files in the project's `.reticle/` folder:
+
+| File | What is in it |
+| --- | --- |
+| `request.json` | the newest prompt, split into statements and classified |
+| `requests.jsonl` | every prompt, one JSON line each, oldest first. At 2 MB it moves to `requests.1.jsonl` |
+
+Secrets are removed before anything is written: credential assignments (`password: …`, `STRIPE_SECRET_KEY=…`), vendor keys (`sk_live_…`, `ghp_…`, `AKIA…`, `AIza…`, `glpat-…`, `xoxb-…`), JWTs, emails, card numbers, phone numbers, home paths and hostnames. This is a pattern match, not a proof: a secret that looks like an ordinary word stays. A prompt is capped at 20,000 characters.
+
+`request.json`, `requests.jsonl` and `requests.1.jsonl` are in `.reticle/.gitignore`. Reticle adds them to an older ignore file that does not have them, and keeps every line you wrote.
+
+The hook makes no network call of its own and never blocks a prompt: a failure is exit 0 and nothing written. It answers the agent at once and writes the prompt in a separate background process. `npx` downloads the pinned version once when its cache does not have it. Nothing about a prompt reaches telemetry.
+
+## The agent's own tool calls
+
+The same config files also get hooks for the agent's own work: the shell commands, file edits and web calls that do not go through Reticle's tools, the model the agent runs, and the message that ends each turn. Each of these hooks runs `reticle hook tool --agent <id>` in the same two forms as the prompt hook.
+
+| Agent | Hooks | What they keep |
+| --- | --- | --- |
+| Claude Code | `PostToolUse`, `PostToolUseFailure`, `SessionStart`, `PostModelSwitch`, `Stop` | `Bash`, `Edit`, `Write`, `MultiEdit`, `NotebookEdit`, `WebFetch` and `WebSearch` calls; the model; the closing message |
+| Cursor | `postToolUse`, `postToolUseFailure`, `afterAgentResponse` | `Shell`, `Write` and `Delete` calls; the closing message |
+| Codex CLI | `PostToolUse`, `Stop` | `Bash` and `apply_patch` calls; the closing message; web searches, read from Codex's own session transcript |
+| Gemini CLI | `AfterTool`, `AfterAgent` | `run_shell_command` calls; the closing message |
+| Windsurf | `post_run_command`, `post_write_code`, `post_cascade_response` | commands and edits, with no result; the closing message |
+| Copilot CLI | `postToolUse` | `bash` and `edit` calls |
+| Factory Droid | `PostToolUse` | `Execute`, `Edit`, `ApplyPatch`, `Create`, `FetchUrl` and `WebSearch` calls |
+
+Cursor and Codex send the model with each call, and Windsurf sends it unless it is "Unknown". VS Code Copilot gets no tool hook.
+
+Each record goes to `.reticle/episodes/agent-<session>.jsonl`. A tool record holds the tool, its arguments, the first 4,000 characters of its result and the result's full size, whether it failed, its exit code, and its timing. A closing-message record holds the first 4,000 characters of the message and its full size. Secrets are removed from every string with the same patterns as a prompt, and paths inside the project are made relative. Reticle's own tools are skipped, because the episode log below already keeps them. The prompt-capture switch stops these records too: `"promptCapture": false` or `RETICLE_PROMPT_CAPTURE=0` stops the prompts, the tool calls, the model and the closing messages together.
+
+The daemon also keeps every call to Reticle's own tools in `.reticle/episodes/<connection>.jsonl`, one file for each agent connection. The first line holds the git HEAD, the uncommitted change for each file, and the request. Each line after it holds one call: the tool, its arguments with typed values removed, its whole result or error, its timing, the tab, the agent, and the page events it caused. A field longer than 200,000 characters keeps its start and is named in `truncated`.
+
+The `episodes/` folder is in `.reticle/.gitignore`, and retention removes old files with the other evidence. No file in it leaves the machine. `"sync": { "episodes": true }` in `.reticle/cloud.json` is kept for a later upload, which also needs a workspace that agreed to share its data. Nothing uploads the files today.
+
+## What leaves the machine
+
+**Requests are shared by default for a linked project.** A project is linked by `reticle connect` (`.reticle/cloud.json`) or by `RETICLE_API_KEY` in the environment. A run written soon after a prompt carries that prompt, and the run goes to your own workspace when it syncs. The Harness also sends the newest request to the platform planner as a goal. An unlinked project sends the request nowhere.
+
+A synced run also carries two values from the agent's hook records. `agent.model` is the model the agent ran. `context.closingClaim` is the first closing message the agent wrote at or after the run's last Reticle call, with secrets removed. The closing message follows the same rule as the request: it leaves only when the project shares requests.
+
+To keep requests on the machine, set `"shareRequests": false` in `.reticle.json`. Capture goes on, and nothing about a request or a closing message leaves: not with a run, and not to the Harness.
+
+A run syncs through `reticle sync`, through the daemon's background sync, or when `reticle verify` closes in CI. Background sync runs only for a project linked by its own `cloud.json`, and only while somebody is signed in to that address or `RETICLE_API_KEY` is the key for that link.
+
+## Turn it off
+
+Agent capture is the prompts, the tool calls, the model and the closing messages that the agent hooks keep. One switch stops all of it. The episode log is the daemon's record of calls to Reticle's own tools. The journal switch stops it, and the agent's tool calls, model and closing messages, but not the prompts.
+
+| What                                     | How                                          |
+| ---------------------------------------- | -------------------------------------------- |
+| Do not install the hooks                 | `reticle init --no-prompt-capture`           |
+| Stop all agent capture in one project    | `"promptCapture": false` in `.reticle.json`  |
+| Stop all agent capture on this machine   | `RETICLE_PROMPT_CAPTURE=0`                   |
+| Stop the episode log in one project      | `"journal": false` in `.reticle.json`        |
+| Stop the episode log on this machine     | `RETICLE_JOURNAL=0`                          |
+| Keep requests and closing messages local | `"shareRequests": false` in `.reticle.json`  |
+| Stop background sync in one project      | `"backgroundSync": false` in `.reticle.json` |
+| Stop background sync on this machine     | `RETICLE_BACKGROUND_SYNC=0`                  |
+| Remove every hook                        | `reticle hook uninstall`                     |
+
+## `reticle hook`
+
+```bash
+npx @reticlehq/server hook status      # per agent: is each prompt captured here
+npx @reticlehq/server hook install     # add the hook for the agents this project uses
+npx @reticlehq/server hook uninstall   # remove exactly what was added
+```
+
+`hook install` writes a config only for an agent this project already uses (its folder is in the project, or the Claude Code CLI is on this machine). It also rewrites an older entry that runs only `npx` to the `node … || npx …` form. `hook prompt --agent <id>` and `hook tool --agent <id>` are what the agent's hooks run; you do not run them yourself. `reticle doctor` prints the same rows as `hook status`, and whether background sync is on. `hook status` names an entry that still runs only `npx`.
+
+`npx @reticlehq/server hook export --structure` writes the page structure of each snapshot step in `.reticle/episodes/` to stdout, one JSON line for each step. A line holds the roles, refs, layout and states of the nodes. It holds no page text: a node says only whether it had a name, a value or text.