@reticlehq/server 2.13.0 → 2.14.0

package/dist/update/sdk-sync.js

@@ -11,7 +11,7 @@
  * stale registry cache and reinstall the skew being fixed. Measured once as pnpm taking 2.2.1 while
  * npm took 2.3.0 in the next project over.
  */
-import { installCommandParts } from '../init/detect.js';
+import { installCommandParts } from '@reticlehq/init';
 export { reticleDepsOf } from './reticle-deps.js';
 /** The install to run, or null when this project has nothing of ours to sync. */
 export function sdkSyncCommand(pm, packages, version) {

package/dist/update/updater.js

@@ -6,7 +6,7 @@ import { dirname, join } from 'node:path';
 import { loadManifest, saveManifest } from './update-checker.js';
 import { RETICLE_NPM_PACKAGE, SERVER_VERSION } from '../version/server-version.js';
 import { log } from '../log.js';
-import { TelemetryEventKind } from '@reticlehq/core';
+import { TelemetryEventKind } from '@reticlehq/core/telemetry';
 import { getTelemetry } from '../telemetry/telemetry.js';
 import { wasNudged } from './nudge-credit.js';
 /** Which way the installed version moved. A rollback means a release hurt someone enough to retreat. */

package/dist/version/sdk-fix.d.ts

@@ -11,7 +11,7 @@
  * does not load the install plan.
  */
 /** What a project contributes to the remedy, when we were able to read one. */
-export interface SdkFixContext {
+interface SdkFixContext {
     /** `@reticlehq/*` packages declared in package.json. Empty / omitted means none yet. */
     packages?: readonly string[];
     packageManager: PackageManagerName;
@@ -45,3 +45,4 @@ export declare function sdkFixContextOf(pkgJson: unknown, lockfiles: ReadonlySet
  * `read` is injected so the decision is testable without a filesystem; the daemon uses the default.
  */
 export declare function sdkFixForDirectory(daemonVersion: string, directory: string, read?: (path: string) => string | undefined): string;
+export {};

package/dist/version/version-skew.d.ts

@@ -83,14 +83,6 @@ export declare function sdkFix(daemonVersion: string): string;
  * and the advice depends on which piece is behind, not on who noticed.
  */
 export declare function daemonFix(daemonVersion: string | undefined, agentVersion: string | undefined): string;
-/**
- * Playwright wording when a CDP call cannot bind to the page.
- *
- * Under SDK/daemon version skew this text is a LIE: the page is still connected (DOM tools work),
- * and the agent spends turns re-acquiring leases and asking a human to sign into a fresh profile
- * (#688). Matched only so we can replace it with the skew sentence already on the session.
- */
-export declare const PLAYWRIGHT_CLOSED_ERROR: RegExp;
 /** True when `error` is Playwright's closed-target class — not proof the tab is gone. */
 export declare function isPlaywrightClosedError(error: unknown): boolean;
 /**

package/dist/version/version-skew.js

@@ -130,7 +130,7 @@ export function daemonFix(daemonVersion, agentVersion) {
  * and the agent spends turns re-acquiring leases and asking a human to sign into a fresh profile
  * (#688). Matched only so we can replace it with the skew sentence already on the session.
  */
-export const PLAYWRIGHT_CLOSED_ERROR = /target (?:page|context|browser) has been closed|browser has been closed|browser has disconnected/i;
+const PLAYWRIGHT_CLOSED_ERROR = /target (?:page|context|browser) has been closed|browser has been closed|browser has disconnected/i;
 /** True when `error` is Playwright's closed-target class — not proof the tab is gone. */
 export function isPlaywrightClosedError(error) {
     const message = error instanceof Error ? error.message : String(error);

package/docs/README.md

@@ -50,6 +50,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [for-agents.md](for-agents.md) | how to fetch these docs as Markdown or `llms.txt` |
 | [architecture.md](architecture.md) | how it works, and why it is built this way |
 | [platform-integration.md](platform-integration.md) | Vite, Next, Remix, Astro, plain HTML |
+| [http-transport.md](http-transport.md) | driving the tools over plain HTTP/SSE, for clients that cannot reload MCP |
 | [desktop.mdx](desktop.mdx) | Electron and Tauri in full: setup, IPC, screenshots, headless, troubleshooting |
 | [frameworks.mdx](frameworks.mdx) | what is supported, what is wired-but-unverified, and the wiring |
 | [state-management.mdx](state-management.mdx) | zustand, Redux, and eight adapters |
@@ -75,7 +76,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 
 ## For people working on Reticle
 
-**Start:** [`CONTRIBUTING.md`](../CONTRIBUTING.md) → [gates.md](gates.md).
+**Start:** [`CONTRIBUTING.md`](https://github.com/reticlehq/reticle/blob/main/CONTRIBUTING.md) → [gates.md](gates.md).
 
 | Page | What it answers |
 | --- | --- |
@@ -84,13 +85,14 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [system-map.md](system-map.md) | how a tool call reaches the app, and which failures are silent |
 | [telemetry-contract.md](telemetry-contract.md) | required reading before touching anything that emits |
 | [telemetry-events.mdx](telemetry-events.mdx) | every event kind and its payload, and the question each one exists to answer |
+| [first-drive.md](first-drive.md) | clone to a real verdict in about fifteen minutes, and the traps on the way |
 | [debugging.md](debugging.md) | debugging Reticle itself: the four signals and what each answers |
 | [fixtures.md](fixtures.md) | the sibling `reticle-fixtures` repo: install complexity, not regressions |
-| [matrix/README.md](matrix/README.md) | submitting an MCP-client compatibility record, the best first contribution |
-| [matrix/MATRIX.md](matrix/MATRIX.md) | which clients are known to work (generated; do not hand-edit) |
-| [`../apps/README.md`](../apps/README.md) | what belongs in `apps/`, and what does not |
-| [`../apps/e2e/harness-rules.md`](../apps/e2e/harness-rules.md) | the four rules every gate obeys, and the incident behind each |
-| [`../bench/README.md`](../bench/README.md) | what in `bench/` is live and what is a kept one-off study |
+| [matrix/README.md](https://github.com/reticlehq/reticle/blob/main/docs/matrix/README.md) | submitting an MCP-client compatibility record, the best first contribution |
+| [matrix/MATRIX.md](https://github.com/reticlehq/reticle/blob/main/docs/matrix/MATRIX.md) | which clients are known to work (generated; do not hand-edit) |
+| [`../apps/README.md`](https://github.com/reticlehq/reticle/blob/main/apps/README.md) | what belongs in `apps/`, and what does not |
+| [`../apps/e2e/harness-rules.md`](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md) | the four rules every gate obeys, and the incident behind each |
+| [`../bench/README.md`](https://github.com/reticlehq/reticle/blob/main/bench/README.md) | what in `bench/` is live and what is a kept one-off study |
 
 `fixtures-dispatch-receiver.yml` is not a doc; it is the workflow template `reticle-fixtures` needs, kept in this repo so the two ends of the contract cannot drift apart.
 

package/docs/actions.mdx

@@ -24,7 +24,7 @@ Every action Reticle can perform takes the same shape: a `ref` from [`reticle_sn
 | `submit` | none | Submits the element's `<form>` |
 | `press` | `{ text }` | The key **name**: `Escape`, `Tab`, `Enter` |
 | `scrollIntoView` | none |  |
-| `upload` | `{ content?, name?, type? }` | Sets a file on `<input type="file">`. All three default, to `"reticle test file"`, `"file.txt"` and `"text/plain"` |
+| `upload` | `{ content?, name?, type?, path? }` | Sets a file on `<input type="file">`. Inline bytes default to `"reticle test file"` / `"file.txt"` / `"text/plain"`. `path` reads a file from disk, scoped to the project root plus any opt-in directories listed in `.reticle.json` as `"uploadRoots": ["~/Downloads", "/Volumes/fixtures"]`. A refusal names every allowed root. |
 | `drag` | `{ toRef }` | Pointer-based drag (dnd-kit, react-beautiful-dnd) plus HTML5 DnD. `target` is an alias |
 | `webmcp` | `{ tool, params }` | Calls a `navigator.modelContext` tool, if the site exposes one |
 

package/docs/agent-cheatsheet.md

@@ -113,9 +113,11 @@ The tools advertised DIRECTLY, i.e. what you'll use 90% of the time. Everything
 
 `reticle_sessions` · `reticle_navigate` · `reticle_snapshot` · `reticle_query` · `reticle_act` · `reticle_act_sequence` · `reticle_act_and_wait` · `reticle_observe` · `reticle_network` · `reticle_console` · `reticle_wait_for` · `reticle_assert` · `reticle_state` · `reticle_inspect` (DOM node → `src/App.tsx:104`) · `reticle_feedback` (tell the maintainers what is missing) · `reticle_session` (hand back: `{action:"yield"}` the moment you stop driving, `{action:"resume"}` after a human pause).
 
+- `reticle_verify`: **the only core tool that CONCLUDES.** `{ action:"crawl" }` drives every reachable control itself and reports the whole fault set in one call (destructive: it really clicks). `{ action:"flows" }` replays every saved flow with no model in the loop. Reach for it when you think you are done: every other tool here answers "here is more to look at".
+
 Frequently useful but NOT core, so reach them through `reticle_run({ tool, args })`: `reticle_capabilities` (the app's whole testable surface in one call; `{fromDisk:true}` needs no browser), `reticle_domain` (learn the app + gaps), `reticle_baseline {action:"diff"}`, `reticle_project` (run history).
 
-**Reach past core when…** you need to record/replay a journey (`reticle_record {action:"start"}/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_flow_heal`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_verify {action:"crawl"}` clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_query` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven mode), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session {action:"end"}` / `reticle_session {action:"resume"}` / `reticle_session {action:"messages"}`, and **`reticle_session {action:"review"}`** to drain + fix the bugs the human flagged from the panel).
+**Reach past core when…** you need to record/replay a journey (`reticle_record {action:"start"}/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_flow_heal`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_verify {action:"crawl"}` is now advertised directly, clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_query` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven or leased), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session {action:"end"}` / `reticle_session {action:"resume"}` / `reticle_session {action:"messages"}`, and **`reticle_session {action:"review"}`** to drain + fix the bugs the human flagged from the panel).
 
 ## flows vs baselines vs project.json (the persistence layers)
 
@@ -160,4 +162,4 @@ Recent additions, each of which answers a question agents were previously asking
 - **Cap broad reads.** `reticle_query` takes `limit` (caps descriptors; reports `total`/`truncated`) and `count_only` (just the match count). `reticle_network` / `reticle_console` take `limit` (most-recent-N, reports `droppedOldest`) and carry the same `cost` hint, so a busy page or wide window never floods your context unnoticed.
 - **A saved flow tells you if it's a real test.** `reticle_flow_save` returns `assertions.grade` (`asserted` / `presence-only` / `assertion-free`); if it's not `asserted`, add a consequence (`reticle_annotate` assert-signal/assert-net or a success-state) so it can't pass while broken. On replay, an ambiguous heal (two testids tie) is surfaced, never auto-applied. And an `apply` heal re-replays the rebound flow and **refuses to write** if the success consequence no longer fires (`status:consequence_broken`): it heals the locator, never the intent.
 - **Predicate schema is not bloated.** The recursive predicate DSL used by `reticle_assert` / `reticle_wait_for` / `reticle_act_and_wait` is **factored, not inlined**: when converted to the JSON Schema MCP sends, the predicate body is emitted **once** (~2.7k chars ≈ **~685 tokens** per tool) and recursion is handled by self-`$ref` (`#/properties/predicate`), with no per-recursion duplication. No action needed.
-- **One tool surface.** Reticle advertises the core set directly (sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state/inspect/feedback/session: the whole detect loop, plus the file-pointer, the feedback channel and the handback) PLUS two meta-tools that keep every other tool one call away: `reticle_tools` (discover; no args lists every tool name + summary, `names:[…]` loads full params on demand) and `reticle_run({ tool, args })` (invoke any tool by name; a top-level `sessionId` is forwarded to the target, so you need not nest it in `args`). So to record/replay/verify a flow, call `reticle_run({ tool:"reticle_verify", args:{ action:"flows" }, sessionId })` (or `reticle_tools` first to see params). There is nothing to pick. `RETICLE_ADVERTISE_ALL_TOOLS=1` (read by the daemon at startup, so restart it) advertises everything with output schemas: a verification switch for suites, not a way to run agents. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.
+- **One tool surface.** Reticle advertises the core set directly (sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state/inspect/feedback/session/verify: the whole detect loop, plus the file-pointer, the feedback channel, the handback, plus the one tool that CONCLUDES) PLUS two meta-tools that keep every other tool one call away: `reticle_tools` (discover; no args lists every tool name + summary, `names:[…]` loads full params on demand) and `reticle_run({ tool, args })` (invoke any tool by name; a top-level `sessionId` is forwarded to the target, so you need not nest it in `args`). So to record/replay a flow, call `reticle_run({ tool:"reticle_record", args:{ action:"start" }, sessionId })` (or `reticle_tools` first to see params). `reticle_verify` is advertised directly: `{ action:"flows" }` replays every saved flow with no model in the loop, and `{ action:"crawl" }` drives every reachable control itself and reports the whole fault set in one call. There is nothing to pick. `RETICLE_ADVERTISE_ALL_TOOLS=1` (read by the daemon at startup, so restart it) advertises everything with output schemas: a verification switch for suites, not a way to run agents. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.

package/docs/architecture.md

@@ -127,4 +127,4 @@ See [LICENSE](../LICENSE) and each package's own `LICENSE` file. The licensing _
 - [getting-started.md](getting-started.md) wires Reticle into your app in a couple of minutes.
 - [benchmarks.md](benchmarks.md) covers how we measure, and the honest results vs the alternatives.
 - [usage.md](usage.md) is the full tool reference and advanced modes.
-- [CONTRIBUTING.md](../CONTRIBUTING.md) has the development loop and the rules.
+- [CONTRIBUTING.md](https://github.com/reticlehq/reticle/blob/main/CONTRIBUTING.md) has the development loop and the rules.

package/docs/cli/mcp.mdx

@@ -31,6 +31,7 @@ The proxy **is** the MCP server the editor launched. Nothing respawns it, so an
 - Crash handlers write to the proxy's own log file, not just stderr, because the editor swallows stderr.
 - A daemon that is not there is not fatal. The proxy answers `initialize` itself, serves the cached tool catalog, and retries a daemon on every client request. Present and complaining beats absent, because absent needs a human.
 - Reconnect is self-healing: if the daemon exited, crashed, was stopped, or shut itself down as idle, the reconnect path spawns a new one rather than retrying a dead port until the budget runs out.
+- A proxy with no client traffic and no work in flight exits after 24 hours, so abandoned editor sessions do not leave process pairs behind forever. Set `RETICLE_MCP_PROXY_IDLE_MS=0` to disable that watcher, or set an explicit millisecond window.
 
 ## What it prints
 
@@ -41,10 +42,11 @@ Structured lines to the proxy log (`~/.reticle/`), not to your terminal, since s
 | `reticle_mcp_daemon_started` | It spawned a daemon |
 | `reticle_mcp_daemon_unavailable` | It could not, and is serving anyway |
 | `reticle_mcp_proxy_first_connect_failed` | The first connect was refused. Expected when the daemon is still coming up |
+| `reticle_mcp_proxy_idle_exit` | The client link stayed quiet for the full idle window and the proxy exited with no work in flight |
 
 ## Exit codes
 
-Runs for the life of the editor session.
+Runs for the life of an active editor session. A fully quiet, abandoned link exits after the idle window above.
 
 ## Worked example
 

package/docs/cli/watch.mdx

@@ -34,7 +34,7 @@ Real capture, the first two lines of a run in this repository:
 A save then produces a `reticle_watch_affected` line naming the changed files and the flows they put at risk, followed by a refreshed buddy line. Real capture, with both lists trimmed:
 
 ```json
-{"t":"2026-08-15T18:44:09.317Z","event":"reticle_watch_affected","changed":["packages/server/src/init/cursor.ts"],"affected":["WEB-flow","deploy-journey","verify-route"]}
+{"t":"2026-08-15T18:44:09.317Z","event":"reticle_watch_affected","changed":["packages/init/src/mcp-clients.ts"],"affected":["WEB-flow","deploy-journey","verify-route"]}
 {"t":"2026-08-15T18:44:09.355Z","event":"reticle_buddy","status":"✗ 39 deviations: ELECTRON-1LINE-flow, ELECTRON-COLD-flow +37 more · 0 nominal · 9 flaky quarantined"}
 ```
 

package/docs/cli.mdx

@@ -153,7 +153,7 @@ npx @reticlehq/server affected --since HEAD~1
 {
   "t": "2026-08-15T18:42:57.431Z",
   "event": "reticle_affected",
-  "changedFiles": ["SKILL.md", "docs/cli/doctor.mdx", "packages/server/src/init/agent-rules.ts"],
+  "changedFiles": ["SKILL.md", "docs/cli/doctor.mdx", "packages/init/src/agent-rules.ts"],
   "affected": ["WEB-flow", "deploy-journey", "verify-modal", "verify-route"],
   "unknownProvenance": ["WEB-flow", "deploy-journey", "verify-modal", "verify-route"]
 }

package/docs/desktop.mdx

@@ -214,7 +214,7 @@ Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-por
 
 ```toml
 [dependencies]
-reticle-tauri = "2.13"
+reticle-tauri = "2.14"
 ```
 
 ```rust

package/docs/docs.json

@@ -32,7 +32,7 @@
   "navigation": {
     "versions": [
       {
-        "version": "2.13.0",
+        "version": "2.14.0",
         "default": true,
         "tabs": [
           {
@@ -62,7 +62,12 @@
               },
               {
                 "group": "Working with agents",
-                "pages": ["multi-agent-testing", "human-control", "platform-integration"]
+                "pages": [
+                  "multi-agent-testing",
+                  "human-control",
+                  "platform-integration",
+                  "http-transport"
+                ]
               },
               {
                 "group": "When it goes wrong",
@@ -192,7 +197,7 @@
             "groups": [
               {
                 "group": "Working on Reticle",
-                "pages": ["gates", "gate-plan", "fixtures", "local-registry"]
+                "pages": ["first-drive", "gates", "gate-plan", "fixtures", "local-registry"]
               },
               {
                 "group": "Internals",

package/docs/faq.mdx

@@ -83,6 +83,15 @@ Anonymous usage telemetry is sent separately and can be turned off with `reticle
   </Card>
 </Accordion>
 
+<Accordion title="Does it work with WebGL / react-three-fiber?">
+  Partially. Reticle's model of an app is DOM + store + network. A WebGL or react-three-fiber
+  subtree is a single `<canvas>` to `reticle_query` / `reticle_snapshot`: Reticle cannot pick faces
+  or drive the camera inside the scene.
+
+DOM, registered store state, and network **around** the canvas still work, and that is often where the consequential bugs live (import counts, mesh stats, solver results that contradict the UI). `init` prints this limit when it detects react-three-fiber so an adopting team does not discover it only after trying to verify the feature they care about.
+
+</Accordion>
+
 <Accordion title="Is Reticle proven to make agents fix more bugs?">
   No, and we are not going to claim it. A controlled test of fix-rate did **not** show an improvement. The benchmark was confounded in ways we can point at, and we consider the question open.
 

package/docs/first-drive.md

@@ -0,0 +1,136 @@
+---
+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
+---
+
+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.
+
+Everything here is written from a run of these exact steps, including the places they bite.
+
+## Before you start
+
+```bash
+node --version   # 22 or newer
+pnpm --version   # this is a pnpm workspace; npm will not resolve it
+```
+
+```bash
+git clone https://github.com/reticlehq/reticle && cd reticle
+pnpm install
+pnpm build       # required: the specs and the CLI run from dist/, not src/
+```
+
+`pnpm build` is not optional. Several things below load `packages/server/dist`, and a stale or absent `dist` produces errors that read as code faults rather than as a missing build.
+
+## 1. Boot something to look at
+
+Two processes: a demo API and the bench app that talks to it.
+
+```bash
+node apps/api/server.mjs &
+RETICLE_PORT=4400 VITE_RETICLE_TOKEN="$(cat ~/.reticle/pairing-token)" \
+  pnpm --filter @reticlehq/bench-app exec vite --port 4310 --strictPort &
+```
+
+Check both answered before going on, because a readiness check now saves a confusing failure later:
+
+```bash
+curl -s -o /dev/null -w "api=%{http_code} app=%{http_code}\n" \
+  http://localhost:8787/api/saved-items http://localhost:4310/
+```
+
+If `~/.reticle/pairing-token` does not exist yet, run any `reticle` command once and it will be minted.
+
+## 2. Take a verdict from the command line
+
+This is the shortest path to seeing Reticle work, and it needs no MCP client at all.
+
+Open the app in a browser. Use a real one, or:
+
+```bash
+node -e "require('playwright').chromium.launch({headless:true})
+  .then(b=>b.newPage().then(p=>p.goto('http://localhost:4310/')
+  .then(()=>new Promise(r=>setTimeout(r,60000)))))" &
+```
+
+Then ask for a verdict:
+
+```bash
+node packages/server/dist/cli.js verify "" --port 4400 \
+  --expect '{"kind":"text","contains":"Reticle"}'
+```
+
+```
+verified: yes
+reason: proved
+exit=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:
+
+```bash
+node packages/server/dist/cli.js verify "" --port 4400 \
+  --expect '{"kind":"text","contains":"definitely not on this page"}'
+```
+
+## 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:
+
+- `reticle_snapshot`: what is on the page
+- `reticle_query { by: "testid", value: "..." }`: find one thing, cheaply
+- `reticle_act_and_wait { ref, action, until }` (**the one that produces a verdict**)
+- `reticle_observe`: everything the page did, when you need the evidence
+
+`reticle_act` moves the app and proves nothing. A drive that ends without `act_and_wait` or `reticle_assert` has no result, however many calls it made.
+
+## 4. Read a spec, then run one
+
+The end-to-end specs are the best documentation of what Reticle guarantees, because each one is a property somebody was burned by. Short and readable:
+
+```bash
+node apps/e2e/specs/awkward-controls-test.mjs      # a file upload, an unnamed button, a canvas
+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 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:
+
+```bash
+node -e "import('./apps/e2e/gate-harness.mjs').then(m=>m.freePortSafely(4400,{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`](fixtures.md).
+
+**Telemetry fails silently.** Nothing throws, no test reddens, the data is just permanently gone. Read [`telemetry-contract.md`](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.
+
+## Gate durations, measured
+
+Run the fast gate before every commit. The others only when you touch what they cover.
+
+| gate | when | measured |
+| --- | --- | --- |
+| `pnpm format:check && pnpm lint && pnpm typecheck && pnpm 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.
+
+## 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
+- 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/frameworks.mdx

@@ -1,11 +1,11 @@
 ---
 title: 'Frameworks: proven, wired, and the difference'
 sidebarTitle: Frameworks
-description: Which frameworks Reticle supports, which are wired but unverified, and the exact wiring for each one. React, Next.js, Remix, Astro, SvelteKit, Nuxt, Vue and plain HTML.
+description: Which frameworks Reticle supports, which are wired but unverified, and the exact wiring for each one. React, Next.js, Remix, Astro, SvelteKit, TanStack Start, Nuxt, Vue and plain HTML.
 icon: layer-group
 ---
 
-**React + Vite, Next.js, Remix and Astro are fully supported, each with an example app driven to a verdict in CI. SvelteKit, Nuxt, Vue, Preact, Create React App and plain HTML are wired and documented but not gated, so treat them as plausible rather than proven.** The exact wiring for each is below.
+**React + Vite, Next.js, Remix and Astro are fully supported, each with an example app driven to a verdict in CI. Astro, SvelteKit, Nuxt, React Router framework mode, Create React App and Vue have their INSTALL gated: the install gate scaffolds each from scratch on every change and requires a real session, but no gate drives them to a verdict. TanStack Start, Preact and plain HTML are wired and documented but not gated at all, so treat them as plausible rather than proven.** The exact wiring for each is below.
 
 Reticle is a verification layer that embeds a dev-only SDK in your running web app so an AI coding agent can prove a change works. Its core is framework-neutral: DOM, network, console, routing, animations and source mapping work anywhere JavaScript runs.
 
@@ -27,9 +27,11 @@ Two columns say different things and it is worth keeping them apart. **CI gate**
 | **Next.js** | yes | yes | yes | yes | Supported |
 | **Remix** | yes | yes | yes | yes | Supported |
 | **Astro** | yes | yes | yes | yes | Supported |
-| **SvelteKit** | yes | no | no | unproven | Wired, unverified |
-| **Nuxt** | yes | no | no | unproven | Wired, unverified |
-| **Create React App** | yes | no | no | unproven | Wired, unverified |
+| **SvelteKit** | yes | no | install only | unproven | Install gated, drive unverified |
+| **TanStack Start** | yes | no | no | unproven | Wired, unverified |
+| **Nuxt** | yes | no | install only | unproven | Install gated, drive unverified |
+| **React Router (framework mode)** | yes | no | install only | yes | Install gated, drive unverified |
+| **Create React App** | yes | no | install only | unproven | Install gated, drive unverified |
 | **Plain HTML** | yes | no | no | no | Wired, unverified |
 | **Vue (non-Nuxt)** | as Vite | no | install only | no | Install gated, drive unverified |
 | **Preact** | as Vite | no | no | unproven | Sensor, React adapter via `preact/compat` |
@@ -100,12 +102,32 @@ The Vite plugin still stamps `data-reticle-source` into `.svelte` components, so
 
 For state, use the `svelteStore` adapter. See [State management](/state-management).
 
+## TanStack Start
+
+TanStack Start SSRs `<html>` from `src/routes/__root.tsx` and never sends Vite's `index.html`, so the plugin cannot auto-connect. Keep the plugin with `inject: false`: only the injection half is inapplicable, and the stamping half is what puts `file:line` on a verdict.
+
+Connect from a client-only effect. A static import of the SDK on `__root.tsx` SSRs and 500s.
+
+```tsx
+useEffect(() => {
+  if (import.meta.env.DEV) {
+    const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+    void import('@reticlehq/react').then(({ reticle, install }) => {
+      install();
+      reticle.connect({ ...(token.length > 0 ? { token } : {}) });
+    });
+  }
+}, []);
+```
+
+`init` detects Start and prints this recipe. There is no example app and no CI gate, so treat a connected session as the proof, not the plan.
+
 ## Nuxt
 
-Nuxt owns its own Vite instance and renders its own HTML. There is no `vite.config` to patch and no `index.html` to inject into. The idiom is a dev-only client plugin.
+Nuxt owns its own Vite instance and renders its own HTML. There is no `vite.config` to patch and no `index.html` to inject into, so `reticle init` writes a dev-only client plugin and adds a `vite.define` block to `nuxt.config`. That block is the only place a Nuxt app can inline the pairing token, which the bridge requires even on localhost. What it writes is this, and the notes below are why each line is the way it is.
 
 ```ts
-// plugins/reticle.client.ts
+// app/plugins/reticle.client.ts (Nuxt 3: plugins/reticle.client.ts)
 export default defineNuxtPlugin(() => {
   if (!import.meta.dev) return;
   void import('@reticlehq/browser').then(({ reticle }) => {

package/docs/gate-plan.md

@@ -6,7 +6,7 @@ icon: list-check
 
 Two gates, not one: a **merge gate** that answers "does this PR break anything" and runs on every PR in minutes, and a **release gate** that answers "does this version work in the clients people use" and runs on a release candidate over hours. Phases 0, 1, 2 and 4 are built; Phase 3 (the client matrix) is blocked on `init` learning each client, and Tier 2 is blocked on a token that cannot be created from inside this repo.
 
-> What has to be true before a PR merges and before a release ships, why each piece exists, and what is built so far. Derived from [`system-map.md`](./system-map.md); the harness rules every tier obeys are in [`harness-rules.md`](../apps/e2e/harness-rules.md).
+> What has to be true before a PR merges and before a release ships, why each piece exists, and what is built so far. Derived from [`system-map.md`](./system-map.md); the harness rules every tier obeys are in [`harness-rules.md`](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md).
 
 ## Two gates, not one
 
@@ -85,7 +85,7 @@ Nothing below is trustworthy until a gate result can be distinguished from a gat
   - Codex is deliberately not auto-written. Editing TOML without a parser risks every _other_ server in the user's file; it returns MANUAL with an exact block.
 - [x] **Per-client compat script**: `apps/e2e/client-compat.mjs`. Extracts the command from the config **exactly the way that client would**, runs it, and speaks MCP to it. 7/7 clients, 23 assertions, each advertising the default surface (the count is asserted in `surface-sizes.test.ts`, never restated here).
   - It proves only the half a machine can prove, and the verdict is named `runnable-unverified` so the distinction survives into the matrix. Whether the client _reads_ that path needs the real client, which is the submitted half.
-- [x] **Submission flow**: `apps/e2e/matrix.mjs --validate`, run by CI's `matrix-records` job on every PR. The validator refuses what cannot be acted on: `works` without `checks.toolsVisible` (the self-report the flow exists to replace), `broken` without the client's verbatim error, or any record with no host or version. Its self-check runs first, because a validator that has never refused anything is not a validator. Contributor guide in [`docs/matrix/README.md`](./matrix/README.md).
+- [x] **Submission flow**: `apps/e2e/matrix.mjs --validate`, run by CI's `matrix-records` job on every PR. The validator refuses what cannot be acted on: `works` without `checks.toolsVisible` (the self-report the flow exists to replace), `broken` without the client's verbatim error, or any record with no host or version. Its self-check runs first, because a validator that has never refused anything is not a validator. Contributor guide in [`docs/matrix/README.md`](https://github.com/reticlehq/reticle/blob/main/docs/matrix/README.md).
 - [x] **Generated `MATRIX.md`**: built from submitted records, prettier-ignored because a generated file that fails `format:check` teaches people to skip the gate. **The current honest state is seven clients and ZERO ticks**: `◐` means a runnable entry was written where the client documents it and _nobody has run that client_, and the generated legend says so rather than rounding `◐` up to `✅`.
 
 ### Phase 4: rates, not booleans

package/docs/gates.md

@@ -16,22 +16,28 @@ If you changed anything at all, run `pnpm format:check && pnpm lint && pnpm type
 
 Every gate below was executed end to end against `main` on **2026-08-12** (macOS, M-series, `v2.6.0`). A green row means somebody watched it go green, not that it is supposed to be green.
 
+**Rows marked ↻ were re-measured on 2026-09-09** (macOS, M-series, this branch). The numbers they replace were wrong by a lot, and wrong in the way that is hardest to notice: `test:unit` was recorded here as "5,725 tests / 613 files" and, forty lines further down in the same file, as "4,315 tests". Two copies of one number, neither derived from anything. The battery was 33 in one row and 32 in another, against 38 spec files on disk.
+
+A ↻ row's COUNT was re-derived; a ↻ row's ✅ is still the August sweep unless the row says otherwise. `test:unit` was actually re-run (`turbo run test:unit test:guards --force`, then `pnpm test:bench`, summed from vitest's own per-package output). The battery's spec count was recounted from `ORDER` and `DESKTOP` in `apps/e2e/run.mjs` cross-checked against `ls apps/e2e/specs`; **it was not re-run**, so its ✅ and its wall clock are still August's.
+
 | Gate | Result | Wall clock |
 | --- | --- | --- |
 | `pnpm build` | ✅ | ~40s |
 | `pnpm lint` (+ both guard self-tests) | ✅ | ~15s |
 | `pnpm typecheck` | ✅ | ~10s |
-| `pnpm test:unit` | ✅ 5,725 tests / 613 files across 8 packages | ~45s |
+| ↻ `pnpm test:unit` | ✅ **9,210 tests / 934 files** across 10 packages plus the bench harness | ~70s |
 | `pnpm format:check` | ✅ | ~10s |
 | `pnpm test:integration` | ✅ 12/12 | 17s |
-| `pnpm test:e2e` | ✅ 33/33 specs + soak 60/60 answered | **490s** |
+| ↻ `pnpm test:e2e` | ✅ (Aug). **36 web specs**, counted 2026-09-09 | **490s** (Aug) |
 | `pnpm test:e2e:desktop` | ✅ 2/2 (Electron 20, Tauri 17) | 58s |
 | `node apps/e2e/soak.mjs --self-check` | ✅ | `<1s` |
 | `node apps/e2e/matrix.mjs --self-check` | ✅ | `<1s` |
 | `pnpm matrix:compat --only cursor` | ✅ 4/4 | ~10s |
 | `pnpm bench` | ✅ 10/10 (**was failing before this sweep**, see below) | 279s |
 
-**`pnpm bench` was broken and nobody knew.** `suite-rre.mjs` recorded four flows that asserted no observable consequence and then demanded a `pass` verdict from whole-suite replay, which correctly grades an assertion-free suite `unverifiable`. The product got more honest about false greens; the benchmark measuring it did not follow, so the whole run aborted at script 9 of 10 and `replay-determinism` never ran at all. Each flow now carries a success oracle. This is the failure mode `bench/` is most exposed to: **nothing in CI runs it**, so it can only rot silently.
+**`pnpm bench` was broken and nobody knew.** `suite-rre.mjs` recorded four flows that asserted no observable consequence and then demanded a `pass` verdict from whole-suite replay, which correctly grades an assertion-free suite `unverifiable`. The product got more honest about false greens; the benchmark measuring it did not follow, so the whole run aborted at script 9 of 10 and `replay-determinism` never ran at all. Each flow now carries a success oracle.
+
+That paragraph used to end "**nothing in CI runs it**, so it can only rot silently", and it is left here because it is the reason the `bench` job below exists. It is no longer true: `ci.yml` has a `bench` job that runs `pnpm bench:full` then `pnpm bench:gate`, path-routed on the files that can move token cost. What is still true is the narrower claim in section 4: `bench/` as a whole is measurement, and only the replay + observation-cost numbers are gated.
 
 `pnpm gate:install` (~15 min) and the Windows / Rust jobs were **not** run in this sweep; they are CI-only or network-bound. They are green on `main` per the last CI run, which is a weaker claim than every row above, and is stated that way on purpose.
 
@@ -64,15 +70,17 @@ Each gate exists because the ones above it are blind to something. That blindnes
 | **Build** | `pnpm build` | every package compiles and emits | anything at runtime | `verify` |
 | **Lint** | `pnpm lint` | style rules, plus the dependency-boundary and lossy-transform guards | anything not expressible as a rule | `verify` |
 | **Typecheck** | `pnpm typecheck` | types agree across package boundaries | runtime behaviour | `verify` |
-| **Unit** | `pnpm test:unit` | 4,315 tests, per-package, no browser | anything crossing a package boundary at runtime | `verify` |
+| **Unit** | `pnpm test:unit` | 9,210 tests, per-package, no browser | anything crossing a package boundary at runtime | `verify` |
+| **Repo guards** | `turbo run test:guards` | the 42 `@reticlehq/server` tests that scan OTHER trees (docs, `apps/`, `bench/`, the workflows, the skills), held apart from the unit suite so the wide cache key is 2 seconds rather than 40 | anything inside a package | `verify` (inside `pnpm test:unit`) |
 | **Format** | `pnpm format:check` | Prettier | n/a | `verify` |
 | **Integration** | `pnpm test:integration` | real headless Chromium: browser pool, crash isolation, framework adapters, `withReticle` | the MCP surface, the daemon | `e2e` |
-| **Web e2e battery** | `pnpm test:e2e` | 32 specs against 3 booted servers and a real browser (the tool surface, the daemon lifecycle, transport faults, telemetry, trace shape), plus the soak | desktop runtimes; the install | `e2e` |
-| **Desktop battery** | `pnpm test:e2e:desktop` | a real Electron main process and a **packaged** Tauri binary, driven headless | web-only paths | `desktop-e2e` |
-| **Install gate** | `pnpm gate:install` | scaffolds 3 pristine apps, publishes this checkout to a local Verdaccio, lets `init` install itself, boots each app in a real browser, polls for a session that advertised capabilities | install _complexity_; see [`fixtures.md`](./fixtures.md) | `install-gate` |
+| **Web e2e battery** | `pnpm test:e2e` | **39** specs against 3 booted servers and a real browser (the tool surface, the daemon lifecycle, transport faults, telemetry, trace shape), plus the soak | desktop runtimes; the install | `e2e` |
+| **Desktop battery** | `pnpm test:e2e:desktop` | two real Electron main processes (plain Vite + electron-vite) and a **packaged** Tauri binary, driven headless | web-only paths | `desktop-e2e` |
+| **Install gate** | `pnpm gate:install` | scaffolds **10** pristine apps across 2 OSes (20 cells), publishes this checkout to a local Verdaccio, lets `init` install itself, boots each app in a real browser, polls for a session that advertised capabilities | install _complexity_; see [`fixtures.md`](./fixtures.md) | `install-gate` |
 | **Matrix records** | `pnpm matrix:validate` | every submitted client-compat record is well-formed | whether the client actually works | `matrix-records` |
 | **Windows** | (CI only) | that the code runs at all on the majority platform | e2e; Windows is unit-only | `windows` |
-| **Rust** | `cargo fmt/clippy/check` | `packages/tauri` compiles and lints on Linux, macOS, and cross-checks Windows | everything JS | `rust`, `rust-macos` |
+| **macOS** | (CI only) | the POSIX-but-not-Linux surface (paths, spawn, `lsof`, temp/state dirs) plus a real daemon's lifecycle | everything Linux already covers; it deliberately no longer re-runs the unit tier at a 10x billing multiplier | `macos` |
+| **Rust** | `cargo fmt/clippy/check` | `packages/tauri` compiles and lints on Linux, macOS, and cross-checks Windows | everything JS | `rust` (always), `rust-macos` (only when Rust changes) |
 
 **The single required status check is `gate`.** It passes when every job above either succeeded or was deliberately skipped by path routing, and fails on anything else. Adding a job to `ci.yml` is half the work; adding it to `gate`'s `needs:` list is the other half. A job missing from that list runs, reports, and is structurally incapable of blocking a merge.
 
@@ -105,7 +113,7 @@ These are real and they work; they are not on the PR path, so they only run when
 
 ## 4. `bench/` is not a gate
 
-`bench/` is **measurement and research**, not a merge check. Nothing there blocks a PR, nothing runs in CI, and it is allowed to bit-rot in a way a gate is not. Read [`bench/README.md`](../bench/README.md) before touching it: it says which scripts are live and which are one-off studies kept as evidence for a published claim.
+`bench/` is **measurement and research**. Most of it blocks nothing and is allowed to bit-rot in a way a gate is not. But "nothing runs in CI" is no longer true, and was left standing here for a release after it stopped being: `ci.yml` has a `bench` job, gated on `changes.bench`, that runs `pnpm bench:full` and then `pnpm bench:gate`. It is the only thing in CI that measures TOKEN COST, which is how a release once shipped a measurable token regression with every other gate green. Read [`bench/README.md`](https://github.com/reticlehq/reticle/blob/main/bench/README.md) before touching it: it says which scripts are live and which are one-off studies kept as evidence for a published claim.
 
 The one exception worth knowing: `pnpm bench` + `pnpm bench:gate` is a working regression gate for the replay numbers, and it is run by hand before a release.
 
@@ -117,7 +125,7 @@ Sometimes it is. The specific failures worth recognising:
 
 - **`EADDRINUSE` / "died during boot".** A previous run left something on `:8787`, `:4310`, or `:3100`. `run-ci.sh` frees these on exit; if it was killed, free them by hand.
 - **Killing port 4400 with `lsof -ti tcp:4400 | xargs kill -9`.** This SIGKILLs the `reticle mcp` proxy too, because the proxy holds a _client_ socket on the bridge port. Always add `-sTCP:LISTEN`. This is the root cause of most "the MCP went down" reports.
-- **A timing assertion.** If a test asserts `Date.now() - t < N`, that is a bug in the test, not a flake to re-run. Assert the bound (output size, a truncation flag), or use a generous per-test timeout. See [`harness-rules.md`](../apps/e2e/harness-rules.md).
+- **A timing assertion.** If a test asserts `Date.now() - t < N`, that is a bug in the test, not a flake to re-run. Assert the bound (output size, a truncation flag), or use a generous per-test timeout. See [`harness-rules.md`](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md).
 - **An `INCONCLUSIVE` verdict.** The harness is telling you the transport did not stay up, so it is claiming nothing about the product. That is the harness working, not the product failing.
 
-The four rules every tier obeys, and the incident behind each, are in [`apps/e2e/harness-rules.md`](../apps/e2e/harness-rules.md).
+The four rules every tier obeys, and the incident behind each, are in [`apps/e2e/harness-rules.md`](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md).

package/docs/getting-started.md

@@ -88,7 +88,7 @@ Three flags carry what the command cannot work out for itself:
 | `--env KEY=VALUE` | What your app needs to reach a usable state: the key from `.env.example`, the mock backend, the variable that skips an auth wall. Repeatable. |
 | `--app <dir>` | Which app in a monorepo. It finds the servable ones; only you know which you are working in. |
 
-The rest are dials: `--license <key>` (writes it to `.env` and keeps `.env` out of git), `--json` (one object for an agent to read), `--files-only` (write, register, pre-approve, and stop, which is what `init` did before it learned to boot the app, and what an existing install re-runs to pick up new wiring), `--no-open`, `--no-drive`, `--dry-run`, `--port N`, `--no-mcp`, `--no-install`.
+The rest are dials: `--license <key>` (writes it to `.env` and keeps `.env` out of git), `--json` (one object for an agent to read), `--files-only` (write, register, pre-approve, and stop, which is what `init` did before it learned to boot the app, and what an existing install re-runs to pick up new wiring), `--relaunch` (prints the command that restarts the conversation you are in, with the tools loaded: the restart step most installs stall on, and it composes with `--files-only`), `--no-open`, `--no-drive`, `--dry-run`, `--port N`, `--no-mcp`, `--no-install`.
 
 Then restart your dev server and skip to [Step 4](#step-4-run-it-and-verify-the-connection). The manual steps below explain what `init` sets up, if you prefer to wire it yourself.
 
@@ -223,6 +223,12 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
+### Streamlit
+
+Streamlit owns the top-level HTML document, so it has no template where the plain script tag below can be added. Scripts passed through `st.markdown(..., unsafe_allow_html=True)` are rendered but do not execute.
+
+With Streamlit 1.63 or newer, run `npx @reticlehq/server init` from the project. It detects a `streamlit` dependency or import and prints a copy-pasteable `st.html(..., unsafe_allow_javascript=True)` helper that loads Reticle once in the app document. Keep that helper development-only and do not commit the pairing token printed inside it.
+
 ### Plain / other frameworks
 
 Anywhere your app boots in dev: