@reticlehq/server 3.7.0 → 3.8.1

package/docs/cli.mdx

@@ -48,7 +48,7 @@ npx @reticlehq/server <command>
 | Command | What it does | Page |
 | --- | --- | --- |
 | `reticle status [--json]` | Is the daemon up, which pages connected, who is signed in, is this repo linked | [status](/cli/status) |
-| `reticle doctor` | Diagnose setup: Chromium, daemon, port | [doctor](/cli/doctor) |
+| `reticle doctor` | Find what is wrong with the setup (Chromium, daemon, port, agent link), and what is missing from coverage | [doctor](/cli/doctor) |
 | `reticle open [url]` | Show the app: reuse the connected tab, else open one | [open](/cli/open) |
 | `reticle stop [--force]` | Stop the daemon we started; `--force` frees the port by its listener, never the agent's MCP proxy | [stop](/cli/stop) |
 | `reticle restart` | Free the port, then start a daemon and wait for a real bind | [restart](/cli/restart) |
@@ -73,6 +73,7 @@ npx @reticlehq/server <command>
 | `reticle runs issues [--fix <fp>]` | The triage queue; `--fix` prints one issue's fix prompt | [cloud](/cli/cloud#reticle-runs-issues) |
 | `reticle runs memory` | What the linked project has learned | [cloud](/cli/cloud#reticle-runs-memory) |
 | `reticle config` | Choose what syncs: runs, memory, flows; where verification runs | [cloud](/cli/cloud#reticle-config) |
+| `reticle hook [status\|install\|uninstall]` | The prompt hook: is each prompt captured here, add it, or remove exactly what was added | [prompt capture](/prompt-capture#reticle-hook) |
 | `reticle setup mcp` | Register the MCP server with your coding agents (the installer's registration half) | [setup](/cli/setup) |
 | `reticle serve` | Start the daemon and wait for it to bind | [serve](/cli/serve) |
 | `reticle mcp` | The MCP stdio proxy your agent runs; starts the daemon if needed | [mcp](/cli/mcp) |
@@ -92,7 +93,7 @@ The old names below still work for one release and print one line naming the new
 | Old | Now |
 | --- | --- |
 | `reticle kill` | `reticle stop --force` |
-| `reticle login`, `reticle link` | `reticle connect` |
+| `reticle login`, `reticle link` | `reticle connect`. `reticle login --email` is gone: sign-in is only in the browser, with Google or GitHub. Without a browser, set `RETICLE_API_KEY` |
 | `reticle project` | `reticle connect --project <name\|id>` |
 | `reticle whoami` | `reticle status` |
 | `reticle push` | `reticle sync` |
@@ -121,7 +122,7 @@ reticle init  [--env KEY=VALUE]... [--app <dir>] [--license <key>]
               [--json] [--files-only] [--relaunch] [--no-open] [--no-agents]
               [--url <app url>] [--timeout S] [--dry-run] [--hooks]
               [--port N] [--no-mcp] [--no-install] [--start]
-              [--capture-bodies] [--no-first-run]
+              [--capture-bodies] [--no-first-run] [--new-id] [--no-prompt-capture]
 ```
 
 `--env` and `--app` are the answers the command cannot work out for itself: what the app needs to reach a usable state, and which app in a monorepo. Which journey proves what you care about is asked on the first run, as `--persona`. `--files-only` is what `init` did before it learned to boot the app: it still registers the MCP server and pre-approves Reticle's tools, so it doubles as the upgrade path for an existing install.
@@ -142,7 +143,7 @@ npx @reticlehq/server doctor
 reticle doctor
   node         v22.14.0
   chromium     ✓ installed (chromium-1234)
-  daemon       ✓ running on :4400 (pid 72698, v3.7.0)
+  daemon       ✓ running on :4400 (pid 72698, v3.8.0)
   sessions     ✓ 1 page connected
   bridge port  4400  (your app must dial THIS port, not your dev-server port)
   agent link   ✓ an MCP client attached here and called tools before (a record, not a live check)
@@ -162,7 +163,7 @@ reticle status
   daemon       ✓ running on :4400 (pid 90790)
   sessions     ✓ 1 page connected
                http://localhost:4310/
-  agent link   enumerated
+  agent link   ✓ your agent has read and used Reticle's tools
 ```
 
 Add `--json` for the same facts as one machine-readable event line. See [`reticle status`](/cli/status) for the fields.
@@ -232,7 +233,7 @@ Options:
 - `--storage-state <file>`: verify flows behind a login without scripting the login every time.
 - `--session-id <id>`: use a tab that is already connected.
 - `--select <label>`: verify only flows carrying this label. Repeatable.
-- `--expect '<json predicate>'` or `--expect-file <path>`: one verdict, no saved flows needed. Asks the running daemon; with none, it refuses. Exits `0` only on `verified: "yes"`.
+- `--expect '<json predicate>'` or `--expect-file <path>`: one verdict, no saved flows needed. Asks the running daemon; with none, it refuses. Waits up to `--timeout` ms (default `4000`) for the predicate to come true. Exits `0` only on `verified: "yes"`.
 - `--explore` with `--persona "<who does what>"`: no saved flows yet? The Harness drives the app and records them. Needs a linked project (`reticle connect`).
 - `--results-json <file>`: also write one verdict per journey as JSON, for CI.
 - `--confirm-dangerous`: let this run press what the replay guard holds as destructive.
@@ -308,6 +309,9 @@ Measured exit code: **`1`**, with the flow lists trimmed above. That run genuine
 # humans
 npx @reticlehq/server feedback "what worked, what didn't"
 
+# humans who want a reply: one email address, sent only when you give it
+npx @reticlehq/server feedback --contact you@example.com "what worked, what didn't"
+
 # agents, including from a setup that never finished
 npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> "what happened"
 ```

package/docs/debugging.md

@@ -100,7 +100,7 @@ Two things that trace makes visible and nothing else did. Planning is ~2ms, so i
 ### Adding a span
 
 ```ts
-import { span } from '../trace.js';
+import { span } from '@/trace.js';
 
 const result = await span('predicate.eval', { kind: predicate.kind }, () => evaluate(predicate));
 ```

package/docs/deploy-checks.md

@@ -4,9 +4,9 @@ description: 'Enforce verification at the moment code becomes a preview URL, as
 icon: circle-check
 ---
 
-To gate a PR on Reticle, run `npx @reticlehq/server verify <preview-url>` in CI when the preview deploy succeeds. It exits **0** when every saved flow passes and **1** otherwise, so the job's own pass/fail becomes the check on the PR. There is no workflow-level integration to write beyond that one command.
+To gate a PR on Reticle, run `npx @reticlehq/server verify <preview-url>` in CI when the preview deploy succeeds. It exits **0** when every saved flow passes and **1** otherwise, so the job's own pass/fail becomes the check on the PR.
 
-The strongest place to enforce verification is the moment code becomes a preview URL. Every deploy already produces one, and both Vercel and Netlify let a third party attach a **check** to it: pass/fail, shown on the PR, with no workflow file to write.
+The strongest place to enforce verification is the moment code becomes a preview URL. Every deploy already makes one. Today you run Reticle from a CI job on the deploy event (Recipe A). A hosted check provider that needs no workflow file does not exist yet (Recipe B).
 
 That makes the non-developer story complete: the SDK is auto-injected by the build plugin, flows are minted from toolbar recordings with auto-proposed consequences, and verification runs at publish, **without anyone writing a test.**
 
@@ -43,9 +43,11 @@ jobs:
           node-version: 22
           cache: pnpm
       - run: pnpm install --frozen-lockfile
-      - run: npx playwright install --with-deps chromium
+      - run: npm install -g @reticlehq/server
+      # Install the Chromium that Reticle's own Playwright uses, not the latest one.
+      - run: cd "$(npm root -g)/@reticlehq/server" && npx playwright install --with-deps chromium
       # Reticle drives the preview and owns its own browser + daemon.
-      - run: npx @reticlehq/server verify "${{ github.event.deployment_status.target_url }}" --timeout 60000
+      - run: reticle verify "${{ github.event.deployment_status.target_url }}" --timeout 60000
 ```
 
 The job's own pass/fail becomes the PR check. Nothing else is required.
@@ -71,7 +73,7 @@ The deploy check catches what reaches a preview. `reticle gate` catches it earli
 npx @reticlehq/server gate --since origin/main    # exit 1 unless passing artifacts cover the affected flows
 ```
 
-Use both: `gate` in the agent's Stop hook (see `agent-cheatsheet`), `verify` at the deploy. They read the same run artifacts, so a green gate locally and a green check on the PR mean the same thing.
+Use both: `gate` in the agent's Stop hook (see the [agent cheat sheet](agent-cheatsheet.md)), `verify` at the deploy. They read the same run artifacts, so a green gate locally and a green check on the PR mean the same thing.
 
 ## Honest limits
 
@@ -99,4 +101,4 @@ If you want an agent to be unable to call a change finished without re-verifying
 
 ### verify exited 1 but I cannot see which flow failed.
 
-The verdict is in the run artifact, not only in the log. Each run writes `.reticle/runs/<id>.json` with `repair.failurePackets[]` naming what broke and where; `reticle_run_export { format: "report" }` renders it legibly. The artifact is stable and versioned precisely so a CI surface can render it without parsing log lines.
+The verdict is in the run artifact, not only in the log. Each run writes `.reticle/runs/<id>.json` with `repair.failurePackets[]` naming what broke and where; `reticle_run({ tool: "reticle_run_export", args: { format: "report" } })` prints it as a ✓/✗ report. The artifact is stable and versioned precisely so a CI surface can render it without parsing log lines. Each entry in `checks[]` carries `intent`, a sentence a person can read: the agent's own `intent` when it gave one, else a sentence built from the predicate in the failure voice ("No PATCH request to /assignee was made"), marked `intentDerived: true`. A failed `allOf` also carries `failedPart`, the index of the part that failed, so a title can name the one thing that did not happen.

package/docs/desktop.mdx

@@ -122,7 +122,7 @@ The rows in **bold** are re-proven by a committed battery on every change, `pnpm
 
 Two steps. The first is the ordinary web setup; the second is the only desktop-specific part.
 
-**1. The renderer.** One line in `vite.config.ts`, exactly like a web app:
+**1. The renderer.** One line in `vite.config.ts`, exactly like a web app. With electron-vite, put it in the `renderer` block of `electron.vite.config`, not in `main` or `preload`:
 
 ```ts
 import { reticle } from '@reticlehq/vite-plugin';
@@ -135,7 +135,7 @@ export default defineConfig({
 
 `desktop: true` does two things a desktop shell needs: `connect()` is injected into the renderer's entry module, so a renderer loaded with no dev server still resolves it, and it is called with `allowInProduction`, because a packaged renderer reports `NODE_ENV=production` and the SDK's production backstop would otherwise refuse to start. It instruments the dev server, and a `vite build` **only when that build runs in a non-production mode**: `vite build --mode development`, for a packaged renderer you want to drive with no dev server. A production-mode build, which is what `vite build` and `electron-vite build` do by default, is stubbed exactly like a web bundle: it carries no SDK and never dials `ws://localhost`, so a release binary built the normal way is clean.
 
-Nothing to add in your app code. You can still call `reticle.connect()` by hand and pass `inject: false` if you want control.
+Nothing to add in your app code. You can still call `reticle.connect()` by hand and pass `inject: false` if you want control. Then pass the pairing token yourself: `reticle.connect({ token: __RETICLE_TOKEN__ })`. The plugin defines `__RETICLE_TOKEN__`, and the bridge refuses a connect without the token, also on localhost.
 
 **2. The preload.** One line, before you expose anything:
 
@@ -163,15 +163,21 @@ Working example: [`apps/electron-smoke`](https://github.com/reticlehq/reticle/tr
 
 **Electron Forge.** `reticle init` recognises Forge's Vite template (`vite.renderer.config.*` and no `vite.config.*`) and wires it the same three ways: `reticle()` in the renderer config, the preload shim, and `installReticleCapture` in main. The plugin goes in **without** `desktop: true`, because `electron-forge start` serves the renderer through a real Vite dev server, so the ordinary serve-time injection reaches the window and `electron-forge package` ships a renderer with no Reticle code. `init` starts the app with the script that runs `electron-forge start`, not the renderer's dev script. A vanilla renderer gets `@reticlehq/browser` rather than the React kit.
 
+**A static renderer (no Vite).** When the renderer is a plain `index.html`, `reticle init` does not write the connect snippet into it. A packaged Electron app can serve its renderer on `localhost`, so a localhost-only guard does not keep the SDK out of a release. Init prints a manual step instead. Connect only in development: for example, send `!app.isPackaged` from the main process to the renderer, and call `reticle.connect()` only when it is true. Pass the pairing token as `token`: the bridge refuses a connect without it. Use `@reticlehq/electron` for IPC and capture. If `reticle.local.js` is in the project, keep it out of the package: electron-builder `files: ["!reticle.local.js"]`, or Electron Forge `packagerConfig.ignore: [/reticle\.local\.js$/]`.
+
 ## Tauri setup
 
-Frontend side, nothing desktop-specific:
+Frontend side: add the Vite plugin with `desktop: true`, as for Electron. The plugin injects `connect()` with this machine's pairing token. Do not call `reticle.connect()` yourself.
 
 ```ts
-// src/main.tsx
-import { reticle } from '@reticlehq/browser';
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { reticle } from '@reticlehq/vite-plugin';
 
-if (import.meta.env.DEV) reticle.connect();
+export default defineConfig({
+  plugins: [react(), reticle({ desktop: true })],
+});
 ```
 
 Nothing else is needed for IPC. A Tauri `invoke` travels as a real `fetch` to Tauri's `ipc://` custom protocol, so Reticle already sees it; every `invoke('load_todos')` shows up as `ipc://load_todos`. Reticle also reads Tauri's `Tauri-Response` header, because the transport answers **HTTP 200 whether the Rust command returned `Ok` or `Err`**. Without that translation a failed command would be recorded as a successful request.
@@ -218,7 +224,7 @@ Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-por
 
 ```toml
 [dependencies]
-reticle-tauri = "3.7"
+reticle-tauri = "3.8"
 ```
 
 ```rust
@@ -227,7 +233,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 on the JavaScript side: the SDK invokes the command through Tauri's own internals, because Tauri has no preload stage where a shim could be installed.
 
@@ -273,16 +279,6 @@ The ordering is the whole trick. Hiding the window during `setup` hides it befor
 
 `xvfb-run -a pnpm tauri dev` also works on Linux and needs no app-side change at all.
 
-### A correction worth recording: the Tauri macOS "liveness constraint" was wrong
-
-Earlier versions of this document said a Tauri app on macOS is only drivable while its window is on the active Space and unoccluded, and that hiding it suspends the webview. **That is not true, and the mistake is worth recording because it cost three features.**
-
-Re-measured against the live app, a loaded Tauri webview answers Reticle commands at full speed while minimized, app-hidden with Cmd-H, fully occluded, on another Space behind a fullscreen app, and with no window on screen at all. A full 43-tool drive passes in every one of those states.
-
-What actually failed was narrower: **a webview that has never been presented never loads its page.** Every "suspension" experiment hid or moved the window from `setup`, meaning before the first present, so the page never ran and every command timed out at 8s. The timeouts were real; the diagnosis was not. The `alwaysOnTop` workaround was then built to fix a problem that did not exist, measured as "still broken" for the same reason, and deleted.
-
-The lesson generalises past this document: four experiments agreeing does not make a conclusion controlled, if all four share the same confound.
-
 ## Routing: use a hash router
 
 A packaged renderer runs on `file://`, where `pushState('/settings')` rewrites the URL to `file:///settings`, a path that does not exist, so the next reload lands on a blank page and the app is gone. This is why HashRouter is the standard choice for packaged Electron and Tauri apps. Reticle's route observer handles both, and a `{ kind: 'route', contains: ... }` assertion matches the fragment.

package/docs/enterprise.md

@@ -4,15 +4,15 @@ description: 'Premium access and activation, what is gated, the security and dat
 icon: building
 ---
 
-Enterprise features ship inside the open package and are unlocked by a signed license key you set as `RETICLE_LICENSE_KEY`. Activation is verified locally with Ed25519 and makes **no network call**, so nothing about your usage leaves your machine. Run `npx @reticlehq/server license` to see whether you are `active`, `eval`, `missing`, `expired` or `invalid`.
+Enterprise features ship inside the open package and are unlocked by a signed license key you set as `RETICLE_LICENSE_KEY`. Activation is verified locally with Ed25519 and makes **no network call**. Usage metrics are separate: they are on by default, and on a licensed build they carry your licence id. Turn them off with `RETICLE_TELEMETRY=0`. See [telemetry](/telemetry). Run `npx @reticlehq/server license` to see whether you are `active`, `eval`, `missing`, `expired` or `invalid`.
 
-> Premium access (how you get + activate it), what's gated, the security/data-handling posture, and the licensing model. Integration mechanics live in [`platform-integration.md`](./platform-integration.md).
+> For how to connect a platform to Reticle, see [Platform integration](/platform-integration).
 
 > **Already have a key and just need to switch it on?** [Activating a license key](./license-activation) is the step-by-step version: where to set it on each platform, the editor and CI cases, how to read every status, and what to do when it does not work.
 
 ## How premium access works (offline, no phone-home)
 
-Enterprise (`ee/`) features ship **inside the open package**; they're source-available (free for development, testing, and evaluation). A **license key activates them in production**. Activation is verified locally with Ed25519; nothing about your usage ever leaves your machine.
+Enterprise (`ee/`) features ship **inside the open package**; they're source-available (free for development, testing, and evaluation). A **license key activates them in production**. Activation is verified locally with Ed25519 and sends nothing. Usage metrics, which you can turn off, carry your licence id on a licensed build.
 
 **The flow, end to end:**
 
@@ -46,7 +46,7 @@ The licensing **mechanism** is open core (inspectable, FSL). Only the **features
 - **Today:** the activation gate + one gated feature (audit event recording, `audit-log`).
 - **Roadmap** (the reliably enterprise-only set): **SSO/SAML, SCIM, RBAC / team permissions, audit logs, multi-org management, verify-before-merge policy gates, and the hosted control-plane connectors.** These are the things a security/compliance org pays for; the core verification engine stays free forever.
 
-> What's premium vs free, and pricing, are business decisions for the owner; this doc describes the _mechanism_, not the price list.
+> For pricing, write to [hey@reticle.sh](mailto:hey@reticle.sh). This page describes the mechanism, not the price list.
 
 ## Security & data handling
 
@@ -54,9 +54,9 @@ The honest one-pager a security review needs. Reticle is built so the answer to
 
 | Question | Answer |
 | --- | --- |
-| Does the SDK ship to production? | **No.** Dev/preview-only, tree-shaken from production builds. |
+| Does the SDK ship to production? | **Not by default.** The dev SDK is dev/preview-only and tree-shaken from production builds. If you opt in to [production mode](/production-mode), the `@reticlehq/browser/activate` loader ships. A visitor's page load reads one query parameter and loads no SDK, opens no socket and writes nothing. Only a signed, single-use ticket loads the SDK. |
 | Where does the server run? | **Localhost.** The bridge binds `127.0.0.1`; the verify endpoint is localhost-bound + token-guarded (constant-time), with request/body-size/timeout limits. |
-| Does anything phone home? | **No app data unless you opt in.** Linking a project to the dashboard (`reticle connect`) sends its runs there; see [what is recorded](what-is-recorded.md) and `reticle config` for what it sends. License checks are offline (Ed25519). The CLI sends anonymous, opt-out usage metrics only (random id + event names, no code, no PII; see [telemetry](telemetry.md)); disable fleet-wide with `RETICLE_TELEMETRY=0` or per-machine with `reticle telemetry disable`. Feedback your team explicitly sends us (`reticle feedback`) is the only free text that ever leaves; it is never collected passively, is redacted client-side, and is disabled fleet-wide with `RETICLE_FEEDBACK=0`. |
+| Does anything phone home? | **No app data unless you opt in.** Linking a project to the dashboard (`reticle connect`) sends its runs there; see [what is recorded](/what-is-recorded) and `reticle config` for what it sends. License checks are offline (Ed25519). The CLI sends opt-out usage metrics only (random id + event names, no code, no PII; on a licensed build they carry your licence id; see [telemetry](/telemetry)); disable fleet-wide with `RETICLE_TELEMETRY=0` or per-machine with `reticle telemetry disable`. Feedback your team explicitly sends us (`reticle feedback`) is the only free text that ever leaves; it is never collected passively, is redacted client-side, and is disabled fleet-wide with `RETICLE_FEEDBACK=0`. |
 | Where do artifacts live? | Your disk: `.reticle/runs/<id>.json` (atomic writes, bounded retention), `.reticle/flows/`, `.reticle/contract.json`. You own them. |
 | What can the server read? | The DOM/network/console/routing/state of the app under test, locally. |
 | Leak risk downstream? | The **`prod-preview` profile** redacts source `file:line`, raw bodies, and app-state values. |

package/docs/environment.mdx

@@ -13,7 +13,7 @@ Reticle works with none of these set. Each one changes a single behaviour, and m
 | `RETICLE_PORT` | daemon, CLI, build plugins | The bridge and daemon port. `.reticle.json`'s `port` sets it per project; this overrides it. |
 | `RETICLE_HOST` | daemon | The bridge bind host. Loopback by default. Anything else exposes the bridge beyond this machine, so it is opt-in. |
 | `RETICLE_TOKEN` | daemon | A shared secret the page must present when it connects. The pairing token covers this automatically; set it only for a hand-wired setup. |
-| `RETICLE_PAIRING_TOKEN_DIR` | daemon, `init`, build plugins | Where the auto-provisioned pairing token lives. Defaults to `~/.reticle`. Relocate it for CI or a read-only home directory. |
+| `RETICLE_PAIRING_TOKEN_DIR` | daemon, `init`, `verify`, `try`, `open`, build plugins | Where the auto-provisioned pairing token lives. Defaults to `~/.reticle`. Move it for CI or a read-only home folder. Use an absolute path. A relative path is resolved against the folder the process runs in, and Reticle writes a warning. A Windows path such as `C:\Users\me\.reticle` on Linux, WSL or a container is not used: Reticle uses `~/.reticle` and writes a warning. |
 | `RETICLE_ALLOWED_ORIGINS` | daemon | Comma-separated WebSocket origins the bridge accepts. |
 | `RETICLE_STATE_DIR` | daemon, CLI | Daemon state: pid files, the discovery registry and logs. Defaults to `~/.reticle`. |
 | `RETICLE_DAEMON_READY_TIMEOUT_MS` | MCP proxy | How long the MCP proxy waits for a daemon to come up before reporting it unreachable. |
@@ -25,7 +25,7 @@ Reticle works with none of these set. Each one changes a single behaviour, and m
 | Variable | Read by | What it does |
 | --- | --- | --- |
 | `RETICLE_IDLE_SHUTDOWN_MS` | daemon | How long the daemon waits with no agent, no page and no lease before it exits. `0` keeps it running. |
-| `RETICLE_IDLE_ATTACHED_MS` | daemon | The same wait while an agent is attached, which is longer so a slow install or a thinking human is not cut off. Derived from the base when unset. |
+| `RETICLE_IDLE_ATTACHED_MS` | daemon | The same wait while an agent is attached, which is longer so a slow install or a thinking human is not cut off. Derived from the base when unset. An agent that attached in the last 30 minutes counts as attached, if the daemon has served a tool call. |
 | `RETICLE_MCP_PROXY_IDLE_MS` | MCP proxy | How long an abandoned MCP stdio proxy waits before it exits. `0` disables the watcher. |
 | `RETICLE_JOURNAL` | daemon | Turns the causal journal off (`0`, `false`, `off`) or on. On by default. |
 
@@ -63,6 +63,8 @@ Reticle works with none of these set. Each one changes a single behaviour, and m
 | `RETICLE_API_KEY` | CLI, daemon | The API key minted on the platform. |
 | `RETICLE_CLOUD_KEY` | CLI, daemon | The key's earlier name. Still honoured. |
 | `RETICLE_CLOUD_URL`, `RETICLE_URL` | CLI, daemon | The platform host. `RETICLE_CLOUD_URL` wins when both are set. |
+| `RETICLE_PROMPT_CAPTURE` | prompt hook | `0`, `false`, `off` or `no` stops the agent hooks on this machine from keeping anything: prompts, tool calls, the model and closing messages. `"promptCapture": false` in `.reticle.json` does the same for one project. See [prompt capture](/prompt-capture). |
+| `RETICLE_BACKGROUND_SYNC` | daemon | `0`, `false`, `off` or `no` stops the daemon's background sync on this machine. `"backgroundSync": false` in `.reticle.json` does the same for one project. `reticle sync` still sends. |
 | `RETICLE_SYNC_INTERVAL_MS` | `reticle sync --watch` | How often the watching sync runs. Every 60 seconds by default. |
 | `RETICLE_HARNESS_MAX_STEPS` | autonomous drive | A hard ceiling on steps in one drive. It bounds cost. The drive itself runs on the platform and needs a linked project; each drive spends credits from the workspace's allowance. |
 | `RETICLE_DRIVE_ID` | autonomous drive | The free drive the platform granted, sent with every Harness call. `reticle try` sets it; you do not need to. |
@@ -82,5 +84,5 @@ Reticle works with none of these set. Each one changes a single behaviour, and m
 | `RETICLE_TELEMETRY_FILE` | CLI, daemon | Write telemetry to a local JSONL file and send nothing, so you can read exactly what would be sent. |
 | `RETICLE_TELEMETRY_URL`, `RETICLE_TELEMETRY_KEY` | CLI, daemon | Send telemetry to a different host or project, such as an EU region or your own instance. |
 | `RETICLE_FEEDBACK` | daemon | Turns off the feedback channel only. Usage telemetry follows `RETICLE_TELEMETRY`. |
-| `RETICLE_INSTALL_SOURCE` | `init`, installer, plugin | Names the published route an install came through (`docs_site`, `skill_file`, `plugin`). Self-declared, carries nothing about you, and changes nothing about the install. |
+| `RETICLE_INSTALL_SOURCE` | `init`, installer, plugin | Names the published route an install came through: `skill_file`, `npx_skill`, `plugin`, `install_script`, `docs_site`, `readme`, `blog` or `cli_direct`. Any other value is sent as `unknown`. Self-declared, carries nothing about you, and changes nothing about the install. |
 | `RETICLE_TRACE` | daemon, CLI | Verbose internal tracing for people working on Reticle itself. Off by default. |

package/docs/faq.mdx

@@ -5,14 +5,17 @@ description: Does it run in production, does it need React, does it replace Play
 icon: circle-question
 ---
 
-Reticle is a dev-only, localhost-only verification layer an AI coding agent uses to prove a change actually worked in your running app. It does not run in production, it does not need React, and it does not replace Playwright. The rest of the questions people actually ask are below.
+Reticle is a verification layer that an AI coding agent uses to prove that a change worked in your running app. By default it runs only in development, on localhost. It does not need React, and it does not replace Playwright. The rest of the questions people actually ask are below.
 
 <AccordionGroup>
 
 <Accordion title="Does this run in production?">
-  No, and it is built so that it cannot easily be made to. Keep `reticle.connect()` behind a dev
-  guard; the SDK is side-effect-free and tree-shakes out of production builds. In a production `vite
-  build`, the Vite plugin swaps the SDK for an inert stub and injects nothing.
+  Not by default. Keep `reticle.connect()` behind a dev guard. The SDK has no side effects and
+  tree-shakes out of production builds. In a production `vite build`, the Vite plugin replaces the
+  SDK with an inert stub and injects nothing.
+
+To let an agent drive a staging or production deployment, use [production mode](/production-mode). It is opt-in. A visitor who did not activate it gets no SDK, no socket and no prompt.
+
 </Accordion>
 
 <Accordion title="Do I have to change my components?">
@@ -58,7 +61,7 @@ Reticle scopes to your project and prefers the active tab, and it **refuses rath
 
 </Accordion>
 
-<Accordion title="Why did I get `verified: \"unknown\"` on something that clearly worked?">
+<Accordion title='Why did I get `verified: "unknown"` on something that clearly worked?'>
   Because Reticle could not confirm it saw the whole story, and it will not call that a pass.
 
 The most common cause is a **throttled tab**: a backgrounded browser tab has its timers suppressed, which suppresses the quiescence detection used to decide the page has settled. Focus the tab, or drive a dedicated context.
@@ -68,7 +71,7 @@ If you believe an `unknown` is wrong, report it. Reticle's own response says as
 </Accordion>
 
 <Accordion title="Does my data leave the machine?">
-  Reticle is dev-only and localhost-only. Nothing from your app leaves the machine until you link a project (`reticle connect`, or `RETICLE_API_KEY` in CI). After that, what syncs is set by `reticle config`, and when the Harness drives, the platform sees the steps it drives. Secret values never leave. Credential-shaped values are redacted before they leave the page. You will see `[REDACTED]` in request bodies without configuring anything.
+  By default Reticle runs only in development, on localhost. Nothing from your app leaves the machine until you link a project (`reticle connect`, or `RETICLE_API_KEY` in CI). After that, what syncs is set by `reticle config`, and when the Harness drives, the platform sees the steps it drives. Secret values never leave. Credential-shaped values are redacted before they leave the page. You will see `[REDACTED]` in request bodies without configuring anything.
 
 Anonymous usage counts are sent by default, separately, and carry nothing from your app. `reticle telemetry disable`, `RETICLE_TELEMETRY=0` or `DO_NOT_TRACK=1` turns them off.
 

package/docs/first-drive.md

@@ -2,6 +2,7 @@
 title: Your first drive
 description: 'Clone to a real verdict in about fifteen minutes, and the traps that cost other people a debugging session.'
 icon: play
+noindex: true
 ---
 
 The goal of this page is narrow and deliberate: **end with a real verdict on screen**, produced by Reticle against a running app, in a checkout you just cloned. Not a passing unit test, the thing the project exists to do.
@@ -57,9 +58,11 @@ node server/dist/command/cli.js verify http://localhost:4310/ --port 4400 \
 ```
 verified: yes
 reason: proved
-exit=0
+{ …the verdict as JSON… }
 ```
 
+The command exits with code 0.
+
 That is the whole product in one line: a claim, checked against a running page, with an exit code you can put in CI. `verified: "yes"` is the only pass, `unknown` means Reticle could not tell, and it exits non-zero on purpose.
 
 Try making it fail, because a tool that only ever says yes is not telling you anything:
@@ -69,6 +72,13 @@ node server/dist/command/cli.js verify http://localhost:4310/ --port 4400 \
   --expect '{"kind":"text","contains":"definitely not on this page"}'
 ```
 
+On Windows PowerShell, `npx.cmd` re-parses `--expect '{...}'` and strips the inner quotes. Prefer `--expect-file`:
+
+```powershell
+'{"kind":"text","contains":"Saved"}' | Set-Content expect.json
+npx @reticlehq/server verify http://localhost:3000 --expect-file expect.json
+```
+
 ## 3. Drive it properly, with the tools
 
 If your editor has the Reticle MCP server, the same app is now drivable. The four calls worth knowing, in the order you actually use them:
@@ -89,23 +99,23 @@ node apps/e2e/specs/awkward-controls-test.mjs      # a file upload, an unnamed b
 node apps/e2e/specs/auth-retry-not-a-defect-test.mjs   # a 401 the app recovered from
 ```
 
-Both need step 1's processes running, and both need port 4400 free. See the traps below.
+The specs start their own bridge on port 14400 (`RETICLE_PORT`, default in `apps/e2e/gate-harness.mjs`), so the bench app must dial 14400, not the step-1 daemon on 4400. To run every spec, use `pnpm test:e2e`. It boots the API, the bench app and next-smoke on the correct ports, then runs the battery. To run one spec by hand, stop the bench app from step 1 and start it again with `RETICLE_PORT=14400`. Then run the spec. Your own daemon on 4400 can keep running.
 
 ## The things that will bite you
 
-**Port 4400 is the bridge, and something is probably on it.** Every spec binds it. If your editor has an MCP client open, its daemon owns that port and a spec dies with `EADDRINUSE`. Do **not** `kill -9` the holder: on 4400 that list includes the `reticle mcp` proxy, and killing it cuts your own agent's link with no log, because the process that writes the log is the one that dies. Use the harness, which spares the proxy:
+**The specs use port 14400, not 4400.** A daemon of your own on 4400 can keep running. If something holds 14400, a spec dies with `EADDRINUSE`. Do **not** `kill -9` whatever holds a Reticle port: on 4400 that can be the `reticle mcp` proxy, and killing it cuts your own agent's link with no log, because the process that writes the log is the one that dies. Use the harness, which spares the proxy:
 
 ```bash
-node -e "import('./apps/e2e/gate-harness.mjs').then(m=>m.freePortSafely(4400,{onNote:console.log}))"
+node -e "import('./apps/e2e/gate-harness.mjs').then(m=>m.freePortSafely(14400,{onNote:console.log}))"
 ```
 
 **The bench app self-assigns its session id.** Matching on a fixed name waits forever. Specs identify it by the URL it serves from. Copy that pattern.
 
 **The bench app shows a login first, and views are reached from the nav.** A query parameter does not select a view. Log in, click the nav item, then drive.
 
-**Fixtures are in a second repo.** The apps in `apps/` are all already instrumented, so none of them can tell you whether a fresh install still works. That question lives in [`reticle-fixtures`](https://github.com/reticlehq/reticle-fixtures), which keeps a pristine `clean` branch of real third-party apps plus `main` and `reticle/<version>`. See [`fixtures.md`](https://github.com/reticlehq/reticle/blob/main/docs/fixtures.md).
+**Fixtures are in a second repo.** The apps in `apps/` are all already instrumented, so none of them can tell you whether a fresh install still works. That question lives in `reticle-fixtures`, a private repository that the maintainers run. It keeps a pristine `clean` branch of real third-party apps plus `main` and `reticle/<version>`. See [Fixtures](/fixtures).
 
-**Telemetry fails silently.** Nothing throws, no test reddens, the data is just permanently gone. Read [`telemetry-contract.md`](https://github.com/reticlehq/reticle/blob/main/docs/telemetry-contract.md) before touching anything that emits.
+**Telemetry fails silently.** Nothing throws, no test reddens, the data is just permanently gone. Read [`contributing/telemetry/contract.md`](https://github.com/reticlehq/reticle/blob/main/contributing/telemetry/contract.md) before touching anything that emits.
 
 **`core` is the contract and may not gain dependencies.** Anything crossing browser ↔ bridge ↔ agent is defined there as a constant plus a zod schema. Never inline a wire string elsewhere.
 
@@ -115,15 +125,15 @@ Run the fast gate before every commit. The others only when you touch what they
 
 | gate | when | measured |
 | --- | --- | --- |
-| `pnpm format:check && pnpm lint && pnpm typecheck && pnpm test:unit` | always | ~2 min |
+| `pnpm verify` (`format:check`, `lint`, `typecheck`, `test:unit`) | always | ~2 min |
 | `pnpm test:e2e` | the tool surface, the wire contract, or an observer | ~8 min |
 | `pnpm test:e2e:desktop` | Electron, Tauri, the IPC observer, desktop capture | ~3 min, needs a Rust toolchain |
 | `pnpm gate:install` | `init`, `vite-plugin`, `next`, `babel-plugin` | ~15 min |
 
-`format:check` is first because CI enforces it and `pnpm lint` does not run it, a branch with all four heavy gates green locally can still turn CI red on formatting alone.
+`pnpm verify` runs `format:check` first, because CI enforces formatting and `pnpm lint` does not check it. Without it, a branch that passes the other gates locally can still fail CI on formatting.
 
 ## Where to go next
 
 - [`CONTRIBUTING.md`](https://github.com/reticlehq/reticle/blob/main/CONTRIBUTING.md): the rules, the layout, and the PR flow
-- [`architecture.md`](architecture.md): how the pieces fit
+- [Architecture](/architecture): how the pieces fit
 - Issues labelled **good first issue**. Each names the file to start in, how to reproduce, and how you will know you are done. If one is still too vague, say so on the issue; that feedback is worth more than a guess.

package/docs/flows.md

@@ -6,8 +6,6 @@ icon: repeat
 
 A **flow** is a recorded interactive run that Reticle stores as JSON under `.reticle/flows/` and replays forever with no AI model in the loop. Steps are anchored on **meaning** (a testid, a signal, or an auto-derived component + source location), never on a `eXX` ref or a coordinate, so they survive refactors; when an anchor does drift, `reticle_flow_replay` names what changed and `reticle_verify { action: "heal" }` can rebind it.
 
-Reticle turns an interactive run into a **git-checked, replayable program** stored under `.reticle/`. Flows are anchored on **meaning** (testid + signal), not volatile element refs or coordinates, so they survive refactors, and when an anchor does drift, Reticle tells you _why_ and can repair it. This is what makes Reticle "the project's living test suite a human seeds and an agent maintains."
-
 > All of this is on-disk and human-readable, so flows are reviewed in PRs and diffed like code.
 
 ## The `.reticle/` directory
@@ -82,7 +80,7 @@ reticle_run({ tool: "reticle_flow_save", args: { flowName: "create-task" } })
 }
 ```
 
-Each step binds to a **semantic anchor**, never a `eXX` ref: a `testid`/`signal` when available, else an auto-derived `component` anchor (component name + source `file:line`) for an element with no testid, so the flow stays stable with zero hand-added testids. Only when none of those resolve is a step kept `degraded: true` (a last-resort "add a testid here" marker) rather than silently dropped.
+Each step binds to a **semantic anchor**, never a `eXX` ref: a `testid`/`signal` when available, else an auto-derived `component` anchor (component name + source `file:line`) for an element with no testid, so the flow stays stable with zero hand-added testids. A press of a document key (Escape, Tab, a shortcut) with no target is aimed at no element, so it is saved with a `{ "kind": "role", "role": "document" }` anchor and replayed at the document, as it ran. Only when none of those resolve is a step kept `degraded: true` (a last-resort "add a testid here" marker) rather than silently dropped.
 
 ## Run a flow
 
@@ -106,6 +104,7 @@ There is no state to restore, so the steps before `from` run again quickly as se
 Every session's driving is saved as a flow at teardown when it declared a consequence. These flows:
 
 - are named from the `intent` you pass to `reticle_act_and_wait` (`drive-close-an-issue`), and carry it as the flow's `intent`;
+- without an `intent`, carry a sentence built from what the steps expect, in order ("A POST request to /api/login is made, then the page moves to /home"), as `intent` with `intentDerived: true`, and are named from it (`drive-a-post-request-to-api-login-is-made-login`). A built sentence never enters the intent ledger, and the flow still reports that it declares no intent. Flows saved before this keep their names;
 - merge: another drive that starts on the same page and takes the same steps updates the existing file instead of adding a copy. The existing flow keeps its name and everything it already says; the new drive only fills gaps. Flows you named yourself are never merged;
 - record, on every step, the `page` it ran on and the `endPage` it led to;
 - declare `requires` (the start page) and `ensures` (the end page) as route claims, so `canFollow` can tell which flows chain. Replay treats a required start page as met by navigating there;
@@ -187,7 +186,7 @@ With `apply: false` the flow file is **never modified**; you get the proposed di
 
 ## Flows are your test suite
 
-`.reticle/` flows can be executed as CI specs via `@reticlehq/test`'s `flowsAsSpecs`, replayed with their `expect`/`success` predicates and skipping `dynamic` regions. See [Testing with Reticle](testing.md).
+`.reticle/` flows can run as CI tests. `registerFlowSpecs('.reticle/flows', getSession)` from `@reticlehq/test` registers one vitest test for each flow. Each test replays the flow's `expect` and `success` predicates and skips its `dynamic` regions. To run the flows without vitest, call `flowsAsSpecs('.reticle/flows')`. It returns one spec for each flow, and you call `spec.run(session)` on each. See [Testing with Reticle](testing.md).
 
 ## Tool reference
 

package/docs/for-agents.md

@@ -32,7 +32,7 @@ Every Markdown page is prepended with two things before its content, so a single
 > Verdicts come from `reticle_act_and_wait`, `reticle_assert`, `reticle_act { steps }` when a step declares `expect`, and `reticle_verify`...
 > Package names are scoped `@reticlehq/*`. Run every CLI command as `npx @reticlehq/server <command>`...
 
-# reticle_query
+# Getting started
 ...
 ```
 

package/docs/frameworks.mdx

@@ -233,28 +233,38 @@ What is still missing on Preact is the enrichment above the DOM: `reticle_inspec
 
 No config file to patch, so `connect()` goes in your entry module.
 
-```ts
-// src/index.tsx
-import { reticle } from '@reticlehq/browser';
+```js
+// src/index.js
 if (process.env.NODE_ENV !== 'production') {
   // The bridge refuses a connect with no pairing token, even on localhost.
-  reticle.connect({ token: '<pairing token>' });
+  void Promise.all([
+    import('@reticlehq/browser'),
+    import('../reticle.local.js').catch(() => ({})),
+  ]).then(([{ reticle }, local]) => {
+    reticle.connect({ token: local.token });
+  });
 }
 ```
 
-The token is the contents of `~/.reticle/pairing-token`; do not commit it. On Create React App, `init` writes this for you: a dev-only connect module that reads the token from `REACT_APP_RETICLE_TOKEN`, which it puts in the gitignored `.env.development.local`. The same shape works for webpack, Parcel, and the Vue and Svelte CLIs.
+`reticle init` writes this machine's pairing token to `reticle.local.js` at the project root and adds that file to `.gitignore`. Point the import at that file from your entry module. Do not commit it: each teammate runs `reticle init` for their own. The same shape works for webpack, Parcel, and the Vue and Svelte CLIs. On Create React App, `init` writes the connect for you: a dev-only connect module that reads the token from `REACT_APP_RETICLE_TOKEN`, which it puts in the git-ignored `.env.development.local`.
 
 ## Plain HTML
 
-A directory with an `index.html` and no `package.json` is wired by `init` itself: it writes the connect snippet into `index.html`, before `</body>`, writes `.reticle.json`, and hands over to setup. The block is marked, so a re-run finds it and never writes a second one, and a re-run with a new `--port` rewrites the port inside it. It loads the SDK from a CDN and runs only when the page is opened on `localhost`, `127.0.0.1` or `[::1]`: a static file has no development build to strip it, so the host is the only line between the snippet and a published page. The page carries no pairing token: `init` writes it into `reticle.local.js` beside the page, which the snippet imports, and adds that file to `.gitignore`. Keep it out of anything you publish, and let each teammate run `reticle init` for their own. Several pages and no `index.html` is a choice `init` does not make for you: it prints the snippet, filled in with your project id and token, for you to paste:
+A directory with an `index.html` and no `package.json` is wired by `init` itself: it writes the connect snippet into `index.html`, before `</body>`, writes `.reticle.json`, and hands over to setup. The block is marked, so a re-run finds it and never writes a second one, and a re-run with a new `--port` rewrites the port inside it. It loads the SDK from a CDN and runs only when the page is opened on `localhost`, `127.0.0.1` or `[::1]`: a static file has no development build to strip it, so the host is the only line between the snippet and a published page. The page carries no pairing token: `init` writes it into `reticle.local.js` beside the page, which the snippet imports, and adds that file to `.gitignore`. Keep it out of anything you publish, and let each teammate run `reticle init` for their own. Several pages and no `index.html` is a choice `init` does not make for you: it prints the snippet, filled in with your project id, for you to paste. The snippet does not contain the token. It imports `reticle.local.js`, which `init` writes at the project root and adds to `.gitignore`. If your page is not served from the project root, change `./reticle.local.js` so that it points to that file:
 
 ```html
 <script type="module">
-  import { reticle } from 'https://cdn.jsdelivr.net/npm/@reticlehq/browser@<version>/+esm';
-  reticle.connect({ projectId: '<your-project-id>', token: '<pairing token>' });
+  Promise.all([
+    import('https://cdn.jsdelivr.net/npm/@reticlehq/browser@<version>/+esm'),
+    import('./reticle.local.js').catch(() => ({})),
+  ]).then(([{ reticle }, local]) =>
+    reticle.connect({ projectId: '<your-project-id>', token: local.token }),
+  );
 </script>
 ```
 
+An Electron app with a static `index.html` is the exception. Its packaged renderer can also run on `localhost`, so `init` writes neither the snippet nor `reticle.local.js`, and gives a manual step instead. Connect only in development, for example only when `!app.isPackaged`, and see [Desktop apps](/desktop).
+
 A bare `/node_modules/...` import does not work here: the SDK's own `dist` imports bare specifiers, which a browser cannot resolve without a bundler. A page with a `package.json` and a bundler takes the entry-module path above instead.
 
 ## Angular
@@ -282,14 +292,26 @@ Middleware is the Django-shaped answer: one place, runs for every page, no templ
 ```python
 # reticle_dev.py: add to MIDDLEWARE while DEBUG is on:
 #   MIDDLEWARE = [..., "reticle_dev.ReticleDevMiddleware"]
+import json
+import os
+from pathlib import Path
+
 from django.conf import settings
 
 _SNIPPET = """<script type="module">
   import { reticle } from 'https://cdn.jsdelivr.net/npm/@reticlehq/browser@<version>/+esm';
-  reticle.connect({ projectId: '<your-project-id>', token: '<pairing token>' });
+  reticle.connect({ ...{ projectId: '<your-project-id>' }, token: __RETICLE_PAIRING_TOKEN__ });
 </script>"""
 
 
+def _reticle_pairing_token():
+    folder = os.environ.get("RETICLE_PAIRING_TOKEN_DIR") or str(Path.home() / ".reticle")
+    try:
+        return (Path(folder) / "pairing-token").read_text().strip()
+    except OSError:
+        return ""
+
+
 class ReticleDevMiddleware:
     """Inject the Reticle SDK into HTML responses during development only."""
 
@@ -308,7 +330,8 @@ class ReticleDevMiddleware:
         body = response.content.decode(response.charset)
         if "</body>" not in body:
             return response
-        response.content = body.replace("</body>", _SNIPPET + "</body>", 1).encode(
+        snippet = _SNIPPET.replace("__RETICLE_PAIRING_TOKEN__", json.dumps(_reticle_pairing_token()))
+        response.content = body.replace("</body>", snippet + "</body>", 1).encode(
             response.charset
         )
         if response.has_header("Content-Length"):
@@ -316,7 +339,7 @@ class ReticleDevMiddleware:
         return response
 ```
 
-`reticle init` emits this with your real version, project id and pairing token filled in. Copy it from there rather than from this page: the placeholders above are the three things that have to be right.
+`reticle init` prints this with your real version and project id. Copy it from there, not from this page. The middleware reads this machine's pairing token from `~/.reticle/pairing-token` (or `RETICLE_PAIRING_TOKEN_DIR`) each time it serves a page, so the token is never in your code.
 
 Four details in that middleware are load-bearing, and each is there because the obvious version is wrong: