@reticlehq/server 3.5.0 → 3.7.0

package/docs/install-manual.mdx

@@ -7,7 +7,7 @@ icon: screwdriver-wrench
 
 **Installing Reticle by hand is two independent halves: register the MCP server so your agent gets the `reticle_*` tools, then add the SDK to your app so there is something for those tools to talk to.** You need both, in that order.
 
-Do only the first half and the tools appear but every call reports no session. Do only the second and your app connects to a daemon nobody is asking questions.
+Do only the first half and the tools appear but every call reports no session. Do only the second and your app connects to a daemon nobody is asking questions. Stop after the first half and your agent's first Reticle call wires the app itself when you ask it to verify something, and offers to otherwise.
 
 <Warning>
   **You probably do not need this page.** Two commands do all of it:
@@ -19,7 +19,7 @@ npx @reticlehq/server init                      # in your project
 
 The first registers the MCP server with every agent it can reach. The second wires the app. See the [quickstart](/quickstart).
 
-This page is for the cases those cannot cover: a machine where piping a script is not allowed, an agent Reticle does not know, or a step the installer reported as needing a hand (Codex CLI is the usual one, because its config is TOML that Reticle will not rewrite).
+This page is for the cases those cannot cover: a machine where piping a script is not allowed, an agent Reticle does not know, or a step the installer reported as needing a hand (Codex CLI is the usual one when the `codex` command is not installed, because its config is TOML that Reticle will not rewrite itself).
 
 </Warning>
 
@@ -42,8 +42,8 @@ There is no config file that all agents share. Each harness has its own path and
 | Cursor | `~/.cursor/mcp.json` | `mcpServers` | no |
 | VS Code | `.vscode/mcp.json` | `servers` | no |
 | Windsurf | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` | no |
-| OpenCode | `opencode.json` | `mcp` | `"local"` required |
-| Codex CLI | `.codex/config.toml` | `[mcp_servers.reticle]` | no |
+| OpenCode | `~/.config/opencode/opencode.jsonc` | `mcp` | `"local"` required |
+| Codex CLI | `~/.codex/config.toml` | `[mcp_servers.reticle]` | no |
 | Zed | `~/.config/zed/settings.json` | `context_servers` | no |
 
 ### Claude Code
@@ -86,7 +86,7 @@ Same shape, different file and root key. Cursor and Windsurf use `mcpServers`; V
 
 ### Codex CLI
 
-TOML, in `.codex/config.toml`. This is the one `init` cannot write for you:
+TOML, in `~/.codex/config.toml`. With the `codex` command installed, `init` runs `codex mcp add reticle -- npx @reticlehq/server mcp` for you, and only when the file has no `reticle` entry yet, because that command replaces one without asking. Without the command, `init` cannot write it for you:
 
 ```toml
 [mcp_servers.reticle]
@@ -133,25 +133,33 @@ export default defineConfig({
 });
 ```
 
-That's the whole web install. The plugin stamps source locations onto elements. The thing that turns a DOM node into `src/components/Login.tsx:81`. And injects `connect()` so you can't forget it.
+That's the whole web install. The plugin stamps source locations onto elements. That is what turns a DOM node into `src/components/Login.tsx:81`. It also injects `connect()` with the pairing token, so you can't forget either.
 
 ### Anything without the plugin
 
-If you're not on Vite or Next, call `connect()` yourself, guarded so it never reaches production:
+Run `npx @reticlehq/server init` even here: it wires plain HTML, Angular, Remix, Astro, SvelteKit and the rest, and it is the part that gets the **pairing token** to the page without writing it into anything you ship.
+
+If you really are wiring `connect()` by hand, pass the token. The daemon writes it to `~/.reticle/pairing-token` on first start and refuses a page that does not present it, on localhost too. Without it the page console says `bridge refused the connection: authentication failed: no pairing token on the page…`.
 
 ```ts
-import { reticle } from '@reticlehq/browser';
+import { reticle, SESSION_AUTO } from '@reticlehq/browser';
 
-if (import.meta.env.DEV) reticle.connect();
+if (import.meta.env.DEV) {
+  // The contents of ~/.reticle/pairing-token, supplied at dev time (here as a Vite env var).
+  // Never commit it, and never let it reach a production build.
+  reticle.connect({ session: SESSION_AUTO, token: import.meta.env.VITE_RETICLE_TOKEN });
+}
 ```
 
+Start the dev server with `VITE_RETICLE_TOKEN="$(cat ~/.reticle/pairing-token)"`, or pin your own secret with `RETICLE_TOKEN=<secret>` in the MCP server's environment and give the page the same value. Set it on the dev command only, never in a `.env` file: a production build reads `.env` and would embed the token in the JavaScript it ships. Not on Vite? Do the same with your bundler's dev-only flag and its way of passing a value to the browser.
+
 <Note>
   `connect()` is dev-only by design. Guard it with whatever your bundler gives you:
   `import.meta.env.DEV`, `process.env.NODE_ENV !== 'production'`, or a build flag. Reticle also
   self-guards, but two locks on a door that leads to your users is a reasonable number.
 </Note>
 
-### Tauri. and the step whose failure is silent
+### Tauri, and the step whose failure is silent
 
 The frontend is identical to any web app. The CSP is not optional:
 
@@ -175,7 +183,7 @@ Screenshots and headless mode need the Rust crate, which is versioned independen
 
 ```toml
 [dependencies]
-reticle-tauri = "3.5"
+reticle-tauri = "3.7"
 ```
 
 ```rust
@@ -184,6 +192,8 @@ tauri::Builder::default()
     .on_page_load(reticle_tauri::on_page_load)
 ```
 
+**Dev builds only.** In a release build the crate is inert: `reticle_capture` refuses and `on_page_load` does nothing, so the binary you sign and ship carries no Reticle capability. A release build you test with Reticle (a CI fixture) turns it on with `reticle-tauri = { version = "3.7", features = ["in-release"] }`.
+
 IPC observation needs nothing on the Rust side. An `invoke('load_todos')` already reaches Reticle as `ipc://load_todos`.
 
 <Card title="Electron, and the rest of desktop" icon="display" href="/desktop">
@@ -196,9 +206,9 @@ IPC observation needs nothing on the Rust side. An `invoke('load_todos')` alread
 npx @reticlehq/server status
 ```
 
-A session in the output means the app connected. That. Not a tick in a checklist, is the install finished.
+A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.
 
-If it says nothing connected, the usual cause is a port disagreement between your app and the daemon. The browser console will carry `[Reticle] this page could not open a websocket to …` naming the exact address it tried; set it explicitly with `VITE_RETICLE_WS_URL=ws://localhost:4400/reticle` or `reticle.connect({ url })`.
+If it says nothing connected, the usual causes are a port disagreement between your app and the daemon, or a hand-wired `connect()` without the pairing token. The browser console will carry `[Reticle] this page could not open a websocket to …` naming the exact address it tried; set it explicitly with `RETICLE_PORT=4400 pnpm dev` (Vite plugin), `reticle({ port: 4400 })` in `vite.config`, or `reticle.connect({ url: 'ws://localhost:4400/reticle' })` by hand.
 
 Still stuck? `npx @reticlehq/server doctor` checks Chromium, the daemon and the port in one command.
 

package/docs/instrumentation.mdx

@@ -27,7 +27,9 @@ Every verdict carries an `honesty.grade`. How strong the evidence actually was.
   </Card>
 </CardGroup>
 
-Here is the same login, verified two ways. First with a network predicate and no instrumentation leaned on:
+The full ladder, strongest first, is `signal`, `net`, `state`, `presence`, `none`: a matched request grades `net`, between a signal and a store change.
+
+Here is the same login, verified two ways. First with an element predicate and no instrumentation leaned on:
 
 ```json
 "honesty": { "grade": "presence", "coverage": { "pct": 100 }, "integrity": { "clean": true } }
@@ -181,7 +183,7 @@ This is the one that surprises people, so here it is in full. A successful login
     "signals": ["auth:granted"]
   },
   "honesty": { "grade": "signal", "integrity": { "clean": true } },
-  "feedback_invite": "Reticle could not tell what happened here. If you expected otherwise, reticle_feedback. An unknown verdict is our defect, not yours"
+  "feedback_invite": "Reticle could not tell what happened here. If you expected otherwise, reticle_session { action: \"feedback\" }. An unknown verdict is our defect, not yours"
 }
 ```
 
@@ -214,7 +216,7 @@ Signals rot the way every convention rots: someone adds a mutation, forgets the
 npm i -D @reticlehq/eslint-plugin
 ```
 
-One rule. State changed, so a signal must fire, makes the signal layer self-enforcing. It is the only mechanism we have found that survives contact with a deadline.
+One rule, `require-signal-on-mutation` (state changed, so a signal must fire), makes the signal layer self-enforcing. It is the only mechanism we have found that survives contact with a deadline.
 
 ## Start with one flow
 

package/docs/integration-patterns.md

@@ -4,7 +4,7 @@ description: 'The recommended shape for a real codebase: a minimal production fo
 icon: shapes
 ---
 
-The recommended shape for a real codebase is three decisions: put `createReticleEmitter()` in one `app/emit.ts` so components depend on an interface and `@reticlehq/browser` never reaches your production bundle; emit signals from the **store layer** rather than from N call sites; and let each feature self-register its testids and signals with `registerReticleDomain`. Then turn on `reticle/require-signal-on-mutation` so the signal layer cannot silently rot.
+The recommended shape for a real codebase is three decisions: put `createReticleEmitter()` in one `app/emit.ts` so components depend on an interface and `@reticlehq/browser` is imported in exactly one place; emit signals from the **store layer** rather than from N call sites; and let each feature self-register its testids and signals with `registerReticleDomain`. Then turn on `reticle/require-signal-on-mutation` so the signal layer cannot silently rot.
 
 The basics in [Getting Started](getting-started.md) work with **zero app changes**. This doc is the _recommended_ shape for a real codebase: a minimal production footprint, a signal layer that can't silently drift, and an adoption path that starts paying off on day one, with no rewrite required.
 
@@ -24,7 +24,7 @@ Adoption is **free → cheap → targeted**. You don't instrument everything; yo
 
 **1. Reuse your existing `data-testid` (free).** If you already test with Playwright or Cypress, your testids work in Reticle unchanged; `reticle_look({ action: "find", by: 'testid', value: 'checkout' })` matches them exactly. No new markup, no new code.
 
-**2. Advertise the surface from your existing constants (cheap).** You already keep a `TestIds` constant object for your E2E suite. Pass it straight in. Now `reticle_capabilities()` tells a fresh agent your whole surface without reading source.
+**2. Advertise the surface from your existing constants (cheap).** You already keep a `TestIds` constant object for your E2E suite. Pass it straight in. Now `reticle_run({ tool: "reticle_capabilities", args: {} })` tells a fresh agent your whole surface without reading source.
 
 ```ts
 import { registerCapabilities } from '@reticlehq/browser';
@@ -49,7 +49,7 @@ That's day-one usefulness with no rewrite. The rest of this doc is how to do ste
 
 ## 2. Inject the emitter (zero prod bundle)
 
-The #1 objection: _"I don't want a test tool in my production bundle."_ The answer: components never import `@reticlehq/browser`. They depend on a tiny structural interface, `ReticleEmitter` (`{ signal, state }`), and the real emitter is injected once at the top. `createReticleEmitter()` returns an emitter that proxies to the connected `reticle` singleton and is a **safe no-op** until `reticle.connect()` runs, so nothing breaks in production or before connect, and **`@reticlehq/browser` stays out of the prod bundle.**
+The #1 objection: _"I don't want a test tool in my production bundle."_ The answer: components never import `@reticlehq/browser`. They depend on a tiny structural interface, `ReticleEmitter` (`{ signal, state }`), and the real emitter is injected once at the top. `createReticleEmitter()` returns an emitter that proxies to the connected `reticle` singleton and is a **safe no-op** until `reticle.connect()` runs, so nothing breaks in production or before connect. With the Vite plugin, a production build replaces `@reticlehq/browser` with an inert stub, so **the SDK stays out of the prod bundle**; with another bundler, `app/emit.ts` is the one import to gate.
 
 ```ts
 // app/emit.ts: the one place that touches @reticlehq/browser
@@ -133,7 +133,7 @@ import { registerReticleDomain } from '@reticlehq/browser';
 registerReticleDomain({ testids: ['search-input'], signals: ['search:ran'] });
 ```
 
-Importing both modules in dev makes `reticle_capabilities()` return the merged surface (`testids: ['section-list', 'section-add', 'search-input']`, `signals: ['section:reordered', 'search:ran']`, `stores: ['workspace']`). `registerReticleDomain` is a thin convenience over `registerCapabilities`, with the same merge-idempotent, HMR-safe semantics, so it composes with §1's "use your existing constants." (Named flows stay an explicit `registerCapabilities({ flows })` concern: their last-writer-wins semantics don't fit "accumulate from many domains.")
+Importing both modules in dev makes `reticle_run({ tool: "reticle_capabilities", args: {} })` return the merged surface (`testids: ['section-list', 'section-add', 'search-input']`, `signals: ['section:reordered', 'search:ran']`, `stores: ['workspace']`). `registerReticleDomain` is a thin convenience over `registerCapabilities`, with the same merge-idempotent, HMR-safe semantics, so it composes with §1's "use your existing constants." (Named flows stay an explicit `registerCapabilities({ flows })` concern: their last-writer-wins semantics don't fit "accumulate from many domains.")
 
 ## 5. Keep the signal layer from rotting (`@reticlehq/eslint-plugin`)
 
@@ -158,20 +158,20 @@ export default [
 ];
 ```
 
-Or turn it on with the shipped preset: `plugin.configs.recommended`, which sets `reticle/require-signal-on-mutation` to `warn` (with empty no-op defaults you then configure) and the plugin's other rule, `reticle/no-internal-tags`, to `error`. A function that calls a mutator and a signal together passes; a mutator with no signal reports `store mutation without a mapped Reticle signal`. The documented view-level exceptions from §3 simply don't list those view callees as `mutators`, so they never fire.
+Or turn it on with the shipped preset: `plugin.configs.recommended`, which sets `reticle/require-signal-on-mutation` to `warn` (with empty no-op defaults you then configure) and the plugin's other two rules, `reticle/no-internal-tags` and `reticle/no-runaway-comment`, to `error`. A function that calls a mutator and a signal together passes; a mutator with no signal reports `store mutation without a mapped Reticle signal`. The documented view-level exceptions from §3 simply don't list those view callees as `mutators`, so they never fire.
 
 ## 6. Limitation: un-scriptable tabs, use `reticle drive`
 
 Reticle observes and drives a tab through the in-page SDK plus (optionally) CDP. It **cannot bring to front or recover a browser tab the OS won't let it script**: a backgrounded tab, say, or a non-default browser (Dia, etc.) reporting `hidden:true` / `throttled:true`.
 
-When that happens, `reticle_session { action: "list" }` and every act/assert result carry a `session.recommendation` saying so. The escape hatch is **`reticle drive <url>`** (add `--headed` to watch). Reticle launches and owns a guaranteed-scriptable browser. See [usage §18](usage.md#18-real-input-mode-native-hover--drag) for the full note.
+When that happens, `reticle_session { action: "list" }` and every act/assert result carry a `session.recommendation` saying so. The escape hatch is **`reticle drive <url>`**, which opens in the foreground (`--headless` hides it). Reticle launches and owns a guaranteed-scriptable browser. See [usage §18](usage.md#18-real-input-mode-native-hover--drag) for the full note.
 
 ## Checklist
 
 - [ ] One `app/emit.ts` is the **only** module importing `@reticlehq/browser`; components import the emitter.
 - [ ] `reticle.connect()` is dev-gated; the prod bundle has no `@reticlehq/browser`.
 - [ ] Signals fire from the store layer (middleware or `commitAndSignal`); view-level exceptions are explicit.
-- [ ] Each domain self-registers via `registerReticleDomain`; `reticle_capabilities()` returns the full surface.
+- [ ] Each domain self-registers via `registerReticleDomain`; `reticle_run({ tool: "reticle_capabilities", args: {} })` returns the full surface.
 - [ ] Existing Playwright/Cypress testids are reused, not duplicated.
 - [ ] `reticle/require-signal-on-mutation` is enabled with your `mutators` + `signalCallee`.
 - [ ] The team knows `reticle drive <url>` for un-scriptable tabs.

package/docs/license-activation.mdx

@@ -78,7 +78,7 @@ You do not need `NODE_ENV` set, a project, a dev server, or a running app. This
 | `missing` | Reticle found no key in its environment. | The variable is not visible to this process. See below. |
 | `expired` | The key was valid and its term has ended. | Contact us to renew. |
 | `invalid` | The key was not accepted. | Usually a copy or paste problem. See below. |
-| `eval` | This build has no licensing configured. | You are on a build older than licensing. Update. |
+| `eval` | This build has no issuer key: a source build or a dev checkout. | Install the published `@reticlehq/server` package. |
 
 ## Over time
 

package/docs/multi-agent-testing.md

@@ -4,7 +4,7 @@ description: 'Several apps at once, ports that shift between runs, and many agen
 icon: users
 ---
 
-Many agents can drive the same app at once without a browser each: `reticle_lease {action:"acquire"}` hands each one an **isolated context** (its own cookies, storage and DOM) from a single shared headless Chromium. One daemon per machine, and identity is the **app** (a stable `projectId` stamped by the build plugin), not the port, so an app that boots on `:3001` today is still the same app.
+Many agents can drive the same app at once without a browser each: `reticle_run { tool: "reticle_lease", args: { action: "acquire" } }` hands each one an **isolated context** (its own cookies, storage and DOM) from a single shared headless Chromium. One daemon per machine, and identity is the **app** (a stable `projectId` stamped by the build plugin), not the port, so an app that boots on `:3001` today is still the same app.
 
 Reticle is built for the messy real world: several apps running at once, ports that shift between runs, and many agents driving different flows of the same app in parallel, without each one spinning up its own Chromium. This page explains how that works and how to use it.
 
@@ -20,27 +20,45 @@ Reticle is built for the messy real world: several apps running at once, ports t
 1. Add the plugin (Vite/Next) or one `reticle.connect()` call. (See [getting-started](./getting-started.md).)
 2. Start your app as you normally do.
 3. Open it in a browser; the in-page panel shows Reticle is connected.
-4. Click around; flag anything that looks wrong with the "Flag a bug" annotator. The agent drains those with `reticle_session {action:"review"}`.
+4. Click around; flag anything that looks wrong with the "Flag a bug" annotator. The agent drains those with `reticle_session { action: "review" }`.
 
 ## Agent testing: ~2 minutes
 
 With the app running and instrumented, an agent drives a flow end to end:
 
 ```text
-reticle_lease {action:"acquire"} { url: "http://localhost:3000/dashboard" }
+reticle_run { tool: "reticle_lease", args: { action: "acquire", url: "http://localhost:3000/dashboard" } }
   → { sessionId: "lease-…", ready: true, leased: 1, queued: 0 }
 reticle_act    { sessionId, ... }      # drive the flow
 reticle_assert { sessionId, ... }      # verify intent
-reticle_lease {action:"release"} { sessionId }    # free the slot
+reticle_run { tool: "reticle_lease", args: { action: "release", sessionId } }    # free the slot
 ```
 
-`reticle_lease {action:"acquire"}` opens a fresh isolated headless context against your **already-running** app, stamps the lease identity into the URL so the app's own SDK registers under a sessionId you can target, and waits until that tab has connected (`ready: true`) before returning, so the sessionId is usable immediately. Release when the flow finishes.
+`reticle_run { tool: "reticle_lease", args: { action: "acquire" } }` opens a fresh isolated headless context against your **already-running** app, stamps the lease identity into the URL so the app's own SDK registers under a sessionId you can target, and waits until that tab has connected (`ready: true`) before returning, so the sessionId is usable immediately. Release when the flow finishes.
+
+## Permissions
+
+A lease starts with every permission undecided. Pass `permissions` to grant some on the app's origin before the first navigation, so the first render already sees them:
+
+```text
+reticle_run { tool: "reticle_lease", args: { action: "acquire", url: "http://localhost:3000/map", permissions: ["geolocation"] } }
+```
+
+Acquiring again on an origin that already has a lease returns that lease, and its grants never change there, because it may be another agent's live tab. The same list is a plain reuse and a different one is refused. To change them, release the lease and acquire again. Names are Playwright's, such as `geolocation`, `clipboard-read`, `clipboard-write` and `notifications`; one the browser does not know is refused with its reason.
+
+| What the page reads | Without `permissions` | After a grant |
+| --- | --- | --- |
+| `navigator.permissions.query({ name })` | `prompt` | `granted` |
+| `Notification.permission`, in Playwright's headless shell (the default) | `denied` | still `denied` |
+| `Notification.permission`, in an installed Chrome the pool falls back to | `default` | `granted` |
+
+The headless shell has no notification support, so a notifications grant never reaches `Notification.permission` there. When you ask for `notifications`, the lease reads the value back from the page and says so in `hint` whenever the page cannot see the grant.
 
 ## 10 agents, 10 flows, one dashboard
 
 This is the design target, and it needs no special setup:
 
-- Each agent calls `reticle_lease {action:"acquire"}` for the same dashboard URL → its own isolated context (own cookies/storage) in the **one** shared Chromium.
+- Each agent calls `reticle_run { tool: "reticle_lease", args: { action: "acquire" } }` for the same dashboard URL → its own isolated context (own cookies/storage) in the **one** shared Chromium.
 - The pool caps simultaneous contexts (`RETICLE_MAX_CONTEXTS`, default scales with CPU under a ceiling); extra acquires queue and proceed as slots free.
 - Flows can't bleed into each other: contexts are isolated and every session is scoped by `projectId`.
 - A single crashed page is reclaimed on its own, and if an agent crashes or hangs its lease stops being touched and the **lease reaper** reclaims the context after a TTL, freeing the slot. One dead agent never starves the others.

package/docs/packages/babel-plugin.mdx

@@ -8,7 +8,7 @@ icon: file-code
 
 React 19 dropped `_debugSource`, which is what source mapping used to rely on, so without this the tools can tell you the component name but not the file.
 
-**Apache 2.0. CommonJS. No runtime dependencies. Peer dependency: `@babel/core ^7`.**
+**Apache 2.0. CommonJS. One runtime dependency, `@reticlehq/core` (for the attribute name). Peer dependency: `@babel/core ^7`.**
 
 ## What it stamps
 
@@ -36,6 +36,8 @@ The path is relative to `process.cwd()`, with backslashes normalized to forward
 ## What it skips
 
 - Component tags. Only lowercase host elements are stamped, because a component's own JSX gets stamped where it is defined.
+- Lowercase tags that are not HTML or SVG elements, such as react-three-fiber's `<mesh>`. Only known DOM tags are stamped, because a custom renderer can crash on the attribute.
+- Files whose first non-empty line is a comment holding exactly `@reticle-ignore`.
 - Elements that already carry the attribute.
 - Nodes with no location information.
 - Anything whose tag name is not a plain `JSXIdentifier`.
@@ -56,7 +58,7 @@ One export, via `export =`. There are no named exports and no `default` interop
 function reticleSourcePlugin({ types }: { types: typeof BabelTypes }): PluginObj<PluginPass>;
 ```
 
-The Babel plugin name is `reticle-source`. Its visitor handles `JSXOpeningElement` only.
+The Babel plugin name is `reticle-source`. Its visitor handles `Program` (to read the ignore marker) and `JSXOpeningElement`.
 
 **It takes no options.** The plugin reads nothing from `state.opts`.
 

package/docs/packages/browser.mdx

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

package/docs/packages/core.mdx

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

package/docs/packages/electron.mdx

@@ -49,12 +49,13 @@ It patches three methods, and each IPC call then surfaces to Reticle as a networ
 | `ipcRenderer.sendSync` | Two-way, with its outcome            |
 | `ipcRenderer.send`     | One-way, dispatched, with no outcome |
 
-It then exposes `window.__reticleIpc` through the context bridge, with three members used by the SDK rather than by you:
+It then exposes `window.__reticleIpc` through the context bridge, with four members used by the SDK rather than by you:
 
 | Member | Signature | Notes |
 | --- | --- | --- |
 | `subscribe` | `(callback) => number` | Returns a token, or `-1` if the argument is not a function |
 | `unsubscribe` | `(token) => void` | Real removal |
+| `windowLabel` | `() => Promise<string \| undefined>` | The label the main process registered for this window, or `undefined` |
 | `capture` | `(fullPage) => Promise<string \| null>` | Resolves to a capture file path, `null` when no main handler is installed, and propagates the explicit full-page refusal |
 
 ## The main process
@@ -66,7 +67,7 @@ const win = new BrowserWindow({/* ... */});
 installReticleCapture(win);
 ```
 
-`installReticleCapture(win): void` is a no-op on `null` or `undefined`, tracks the window until it closes, and registers the capture handler once for the whole app.
+`installReticleCapture(win, options?): void` is a no-op on `null` or `undefined`, tracks the window until it closes, and registers the capture handler once for the whole app. `{ label: 'settings' }` names the window in `reticle_session { action: "list" }`; without it the window is listed by url and title.
 
 The handler calls `webContents.capturePage()`, writes the PNG into a per-process `0700` captures directory as `reticle-capture-<n>.png`, and **returns the file path rather than the bytes**, because the transport has a 64KB cap. It refuses `fullPage: true` explicitly rather than silently returning a viewport shot, and it throws named reasons rather than one blanket silence: `full-page-unsupported` for that refusal, `window-not-composited` when the window had nothing painted yet, `no usable webContents to capture` when the window is gone. The preload re-throws the full-page refusal and turns everything else into `null`.
 

package/docs/packages/engine.mdx

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

package/docs/packages/eslint-plugin.mdx

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

package/docs/packages/next.mdx

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

package/docs/packages/open-verification.mdx

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

package/docs/packages/server.mdx

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