@reticlehq/server 3.7.0 → 3.8.1

package/dist/telemetry/session-metrics.js

@@ -15,12 +15,13 @@
  * URLs, no error messages — the accumulator has no way to hold them, which is a stronger guarantee
  * than a rule saying it shouldn't.
  */
-import { BrowserLaunchKind, coverageBucketOf, } from '@reticlehq/core/telemetry';
+import { BrowserLaunchKind, } from '@reticlehq/core/telemetry';
 import { errorSkeleton, fingerprintError } from './error-fingerprint.js';
 import { describeToolParams } from './argument-shape.js';
 import { machineSnapshot } from './machine-snapshot.js';
 import { classifyError } from './error-class.js';
 import { HudMetrics } from './hud-metrics.js';
+import { releaseVersionOf } from '../command/update/version-seen.js';
 /** Cap the distinct error shapes held in memory — a pathological loop must not grow unbounded. */
 const MAX_ERROR_KINDS = 40;
 /** Distinct tool names whose repeat-runs are tracked. Its own cap: the tool surface, not error shapes. */
@@ -143,7 +144,6 @@ export class SessionMetrics {
     /** Platform and Harness advisories shown to an agent this window, by kind. */
     #nudges = new Map();
     /** Harness drives refused for coverage this window, by coverage bucket. */
-    #harnessRefused = new Map();
     /** Error buckets by whose defect, this window. */
     #errorClasses = new Map();
     /**
@@ -160,6 +160,13 @@ export class SessionMetrics {
      */
     #appConnects = 0;
     #firstAppAt;
+    /**
+     * Tool calls before the first app connected, session-lifetime like `#appConnects`. An agent that
+     * works against a daemon with no app sends no verdict and often no refusal; this gives it a shape.
+     */
+    #toolCallsBeforeApp = 0;
+    /** The SDK version of the last page that connected, session-lifetime like `#appConnects`. */
+    #sdkVersion;
     #clients = new Set();
     /** Client name -> version, session-lifetime. Never cleared: who drove is a fact about the session. */
     #clientVersions = new Map();
@@ -267,6 +274,9 @@ export class SessionMetrics {
         }
         this.#toolCalls += 1;
         this.#lifetimeToolCalls += 1;
+        if (this.#firstAppAt === undefined) {
+            this.#toolCallsBeforeApp += 1;
+        }
         bump(this.#toolCounts, tool);
         this.#inFlight = tool;
         this.#breadcrumb.push(tool);
@@ -390,8 +400,9 @@ export class SessionMetrics {
      * Zero of these at shutdown means the daemon ran and no app ever connected — a broken install.
      * Non-zero with no tool calls is the opposite problem. See SessionSummary.appConnects.
      */
-    recordAppConnected() {
+    recordAppConnected(sdkVersion) {
         this.#appConnects += 1;
+        this.#sdkVersion = releaseVersionOf(sdkVersion) ?? this.#sdkVersion;
         this.#firstAppAt ??= this.#now();
     }
     /** One action driven at the page. Settled by the next verdict; see #unsettledActions. */
@@ -489,10 +500,6 @@ export class SessionMetrics {
     recordNudge(kind) {
         bump(this.#nudges, kind);
     }
-    /** A Harness drive was refused because the app's coverage is below the gate. */
-    recordHarnessRefused(percent) {
-        bump(this.#harnessRefused, coverageBucketOf(percent));
-    }
     /** Which tool surface was advertised to agents this session. */
     recordSurface(surface) {
         this.#surface = surface.slice(0, 32);
@@ -574,9 +581,6 @@ export class SessionMetrics {
                 : {}),
             ...(this.#feedbackPrompted > 0 ? { feedbackPrompted: this.#feedbackPrompted } : {}),
             ...(this.#nudges.size > 0 ? { nudgesShown: Object.fromEntries(this.#nudges) } : {}),
-            ...(this.#harnessRefused.size > 0
-                ? { harnessRefusedCoverage: Object.fromEntries(this.#harnessRefused) }
-                : {}),
             ...(this.#errorClasses.size > 0
                 ? { errorClasses: Object.fromEntries(this.#errorClasses) }
                 : {}),
@@ -588,6 +592,8 @@ export class SessionMetrics {
             ...(this.#firstAppAt === undefined
                 ? {}
                 : { msToFirstApp: Math.max(0, this.#firstAppAt - this.#startedAt) }),
+            ...(this.#sdkVersion === undefined ? {} : { sdkVersion: this.#sdkVersion }),
+            ...(this.#toolCallsBeforeApp > 0 ? { toolCallsBeforeApp: this.#toolCallsBeforeApp } : {}),
             ...this.#hud.summarize(),
             final,
             // Only on a real exit. A periodic flush carrying `exit: "unknown"` would read as a daemon that
@@ -649,7 +655,6 @@ export class SessionMetrics {
             0 === this.#postSocketFailures &&
             0 === this.#postRetriesSaved &&
             0 === this.#nudges.size &&
-            0 === this.#harnessRefused.size &&
             this.#hud.empty);
     }
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */
@@ -680,7 +685,6 @@ export class SessionMetrics {
         this.#bugKinds.clear();
         this.#hud.reset();
         this.#nudges.clear();
-        this.#harnessRefused.clear();
         // These five were never cleared, so every flush restated them and a sum over a session's
         // windows came out larger than its tool calls. Counts are windowed, all of them; only the
         // facts below (an app ever connected, which clients, which bug kinds seen) outlive a window.

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,4 @@
-import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type OnboardingStep, type InstallSource, type McpConnection, type McpOutage, type ToolRefusal, type AppInstrumentation, type HarnessRun, type HudEvent, type PlatformLink, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
+import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type OnboardingStep, type InstallSource, type McpConnection, type McpOutage, type DaemonDeath, type ProxyExit, type WakeRefusal, type DaemonSpawnMethod, type ToolRefusal, type AppInstrumentation, type HarnessRun, type HudEvent, type PlatformLink, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
 /**
  * Presence of this file marks the MACHINE as the Reticle team's own: every event carries
  * `internal: true`. The persistent twin of `RETICLE_INTERNAL=1`, for a dev machine where setting a
@@ -107,6 +107,14 @@ export interface TelemetryExtra {
     link?: PlatformLink;
     /** `harness_run`: one phase of one Harness run. */
     harness?: HarnessRun;
+    /** `mcp_proxy_exited`: why the proxy left, and what it saw in its life. */
+    proxyExit?: ProxyExit;
+    /** `daemon_died_unclean`: how old the dead daemon was when its pidfile was found. */
+    daemonDeath?: DaemonDeath;
+    /** `wake_refused`: what held the port. */
+    wakeRefusal?: WakeRefusal;
+    /** `daemon_started`: how the parent started the daemon. */
+    spawnMethod?: DaemonSpawnMethod;
     /**
      * `platform_linked`: the workspace just linked. Overrides the envelope's own reading, which looks
      * at the daemon's working directory and not at the project the HUD linked.

package/dist/telemetry/telemetry.js

@@ -49,6 +49,12 @@ const POSTHOG_KEY = 'phc_q4yCxKMXHfWQ43VAz4HxJXZFLqFi4nBbg5v3avemggYo';
  * still key on distinct_id.
  */
 const POSTHOG_PERSONLESS = { $process_person_profile: false };
+/**
+ * No address and no location leave with an event. `$geoip_disable` stops PostHog from looking up a
+ * city, a postal code and coordinates from the IP. PostHog also stores the request IP as `$ip` when
+ * the event leaves `$ip` empty (`null` counts as empty), so a fixed placeholder takes its place.
+ */
+const POSTHOG_NO_IP = { $geoip_disable: true, $ip: '0.0.0.0' };
 /**
  * PostHog's group type for a licensed customer. Sent as `$groups` so PostHog can aggregate a whole
  * organisation natively: per-company retention, "which orgs went quiet", one row per customer rather
@@ -461,6 +467,11 @@ export const createTelemetry = (opts) => {
             ...(extra?.hud !== undefined ? { hud: extra.hud } : {}),
             ...(extra?.link !== undefined ? { link: extra.link } : {}),
             ...(extra?.harness !== undefined ? { harness: extra.harness } : {}),
+            ...(extra?.proxyExit !== undefined ? { proxyExit: extra.proxyExit } : {}),
+            ...(extra?.daemonDeath !== undefined ? { daemonDeath: extra.daemonDeath } : {}),
+            ...(extra?.wakeRefusal !== undefined ? { wakeRefusal: extra.wakeRefusal } : {}),
+            // A SCALAR: the event build and the wire schema, no `blocks` entry.
+            ...(extra?.spawnMethod !== undefined ? { spawnMethod: extra.spawnMethod } : {}),
         };
         // The wire schema's caps are only real if something applies them. An event that fails is
         // DROPPED, never sent and never repaired: the payload is exactly what the caps exist to stop.
@@ -473,7 +484,7 @@ export const createTelemetry = (opts) => {
         // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
         // would be invisible to the exact "which stacks report the most bugs" question this exists to
         // answer. One prefix keeps them grouped in the UI without a nested path.
-        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, onboarding, bug, refusal, outage, instrumentation, hud, link, harness, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, onboarding, bug, refusal, outage, instrumentation, hud, link, harness, proxyExit, daemonDeath, wakeRefusal, ...rest } = event;
         // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
         // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
         // `sessionId` rides only on events that happened inside a daemon run. A one-shot CLI command
@@ -508,6 +519,9 @@ export const createTelemetry = (opts) => {
             hud,
             link,
             harness,
+            proxyExit,
+            daemonDeath,
+            wakeRefusal,
         };
         for (const [prefix, block] of Object.entries(blocks)) {
             for (const [key, value] of Object.entries(block ?? {})) {
@@ -521,6 +535,7 @@ export const createTelemetry = (opts) => {
             properties: {
                 ...properties,
                 ...POSTHOG_PERSONLESS,
+                ...POSTHOG_NO_IP,
                 // Only on a licensed build. An unlicensed event has no organisation to belong to, and an
                 // empty group key would mint a phantom "no org" bucket that every OSS install falls into.
                 ...(event.licenseId !== undefined

package/dist/telemetry/verification-of.d.ts

@@ -19,4 +19,6 @@ import { type BrowserBrand, type Verification } from '@reticlehq/core';
  */
 export declare function verificationOf(toolName: string, result: Record<string, unknown>, durationMs: number, brand?: BrowserBrand, 
 /** The call ran inside a Harness drive's async context (`currentDrivenBy()`), read by the caller. */
-drivenByHarness?: boolean): Verification | undefined;
+drivenByHarness?: boolean, 
+/** The page SDK version the session announced on HELLO. */
+pageSdkVersion?: string): Verification | undefined;

package/dist/telemetry/verification-of.js

@@ -13,6 +13,7 @@
 import { CaptureLoss, ReplayStatus, ReticleTool, VerificationDriver, Verified, VerifiedReason, } from '@reticlehq/core';
 import { VERDICT_TOOLS } from '../surface/tools/feedback-tools.js';
 import { getBrowserMode } from './browser-mode.js';
+import { releaseVersionOf } from '../command/update/version-seen.js';
 /**
  * The deciding clause, read off the result `decideVerified` wrote it onto.
  *
@@ -116,7 +117,9 @@ function passedOf(result, status) {
  */
 export function verificationOf(toolName, result, durationMs, brand, 
 /** The call ran inside a Harness drive's async context (`currentDrivenBy()`), read by the caller. */
-drivenByHarness = false) {
+drivenByHarness = false, 
+/** The page SDK version the session announced on HELLO. */
+pageSdkVersion) {
     if (!VERDICT_TOOLS.has(toolName))
         return undefined;
     // A paused session REFUSES the call — nothing driven, nothing asserted. The refusal carries a
@@ -141,6 +144,7 @@ drivenByHarness = false) {
         return undefined;
     const reason = reasonOf(result);
     const uncleanLoss = uncleanLossOf(result, reason);
+    const sdkVersion = releaseVersionOf(pageSdkVersion);
     return {
         via: toolName,
         verified: verified ?? (true === passed ? 'yes' : 'no'),
@@ -179,5 +183,7 @@ drivenByHarness = false) {
         // agent keeps calling tools, so a process-wide flag credited the agent's verdicts too. Absent is
         // the ordinary case — the agent called the tool itself.
         ...(drivenByHarness ? { driven: VerificationDriver.HARNESS } : {}),
+        // WHICH page SDK the verdict was judged on. A page older than the daemon misses newer fixes.
+        ...(sdkVersion === undefined ? {} : { sdkVersion }),
     };
 }

package/dist/wire-journal.js

@@ -14,6 +14,7 @@ import { originOf } from './portal/session/session-manager.js';
 import { Bridge } from './portal/bridge/bridge.js';
 import { FlowStore } from './language/flows/flows.js';
 import { makeJournalAttach } from './memory/journal/attach-journal.js';
+import { setEpisodeLogEnabled } from './memory/journal/episode-log.js';
 import { endLiveSessions, makeSessionEnd, recordDriveRun } from './memory/journal/session-end.js';
 import { attachDriveRunFlush } from './memory/journal/drive-run-flush.js';
 import { AmbientStore } from './memory/journal/ambient-store.js';
@@ -34,13 +35,15 @@ import { readBackgroundTraffic } from './portal/session/facts/background-traffic
  */
 export function attachJournal(bridge, deps) {
     const journalAttach = makeJournalAttach(deps);
+    // The episode log is part of the journal: the same switch turns both off.
+    setEpisodeLogEnabled(deps.enabled);
     const ambientStore = new AmbientStore(deps.fs, deps.reticleRoot);
     // Built once, not per session: the resolver walks config discovery and the user-level registry,
     // and neither changes between two tabs connecting a second apart.
     const resolveArtifactRoot = artifactRootResolver(deps.reticleRoot, {
         servingDirectory: servingDirectoryOf,
     });
-    bridge.attachSessionCreate((session) => {
+    const stampProject = (session) => {
         // Stamp the project's own `.reticle` before ANY counter fires for this session. Without it every
         // verdict is recorded against wherever the daemon was started, which is how one app's evidence
         // reached a different account's production dashboard.
@@ -58,9 +61,13 @@ export function attachJournal(bridge, deps) {
         // repository nor the root we were about to write into: it created `.reticle/` — holding nothing
         // but the ignore file — wherever the daemon was launched, coming back every boot after the user
         // deleted it, while the journals this ignore protects landed in another tree, uncovered.
-        if (deps.enabled)
+        if (deps.enabled) {
             void ensureWorkspaceGitignore(deps.fs, session.artifactRoot);
+        }
         journalAttach(session);
+    };
+    bridge.attachSessionCreate((session) => {
+        stampProject(session);
         // Seed the learned ambient map so a fresh session starts knowing which regions churn, instead of
         // re-learning from zero. Best-effort + async: a late seed still helps, a failure is silent.
         if (deps.enabled) {
@@ -70,6 +77,9 @@ export function attachJournal(bridge, deps) {
                 .catch(() => undefined);
         }
     });
+    // A page that connected without a project and names one later (an app's own connect() ran before
+    // the build plugin's) is stamped again, so its evidence leaves the unmatched bucket from now on.
+    bridge.attachProjectAdopted(stampProject);
     // Teardown: flush the journal tail to disk + persist what this session learned.
     const teardown = makeSessionEnd({
         ...deps,

package/docs/README.md

@@ -69,11 +69,13 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [multi-agent-testing.md](multi-agent-testing.md) | more than one agent on one app |
 | [human-control.md](human-control.md) | taking the wheel back from the agent |
 | [deploy-checks.md](deploy-checks.md) | running Reticle against a deployed build |
+| [production-mode.md](production-mode.md) | driving a live site under a policy that refuses payments, deletions and invites |
 | [token-efficiency.md](token-efficiency.md) | why it costs less than a screenshot loop |
 | [benchmarks.md](benchmarks.md) | how the numbers were measured, including where Reticle loses |
 | [vs-playwright-mcp.mdx](vs-playwright-mcp.mdx) | outside-in vs inside-out, and when Playwright is right |
 | [vs-chrome-devtools-mcp.mdx](vs-chrome-devtools-mcp.mdx) | cheaper per look, catches less: the trade, measured |
 | [vs-screenshots.mdx](vs-screenshots.mdx) | why a better vision model does not fix a non-visual bug |
+| [prompt-capture.md](prompt-capture.md) | the prompt hook `init` installs: what it keeps, what leaves, and every switch to turn it off |
 | [what-is-recorded.md](what-is-recorded.md) | what Reticle keeps, what is redacted, and what it takes for any of it to leave your machine |
 | [telemetry.md](telemetry.md) | what is collected, and how to turn it off |
 | [local-registry.md](https://github.com/reticlehq/reticle/blob/main/docs/local-registry.md) | installing an unpublished build |
@@ -92,8 +94,8 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [adapters.md](adapters.md) | what an adapter is, the three kinds, and how to write one |
 | [state-files.md](state-files.md) | what to do when a file on disk came from a different version of Reticle |
 | [system-map.md](system-map.md) | how a tool call reaches the app, and which failures are silent |
-| [telemetry-contract.md](https://github.com/reticlehq/reticle/blob/main/docs/telemetry-contract.md) | required reading before touching anything that emits |
-| [telemetry-events.mdx](https://github.com/reticlehq/reticle/blob/main/docs/telemetry-events.mdx) | every event kind and its payload, and the question each one exists to answer |
+| [contributing/telemetry/contract.md](https://github.com/reticlehq/reticle/blob/main/contributing/telemetry/contract.md) | required reading before touching anything that emits |
+| [contributing/telemetry/events.md](https://github.com/reticlehq/reticle/blob/main/contributing/telemetry/events.md) | every event kind and its payload, when it is sent, why, and an example |
 | [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](https://github.com/reticlehq/reticle/blob/main/docs/fixtures.md) | the sibling `reticle-fixtures` repo: install complexity, not regressions |

package/docs/actions.mdx

@@ -5,7 +5,7 @@ description: Every action reticle_act and reticle_act_and_wait can perform, with
 icon: hand-pointer
 ---
 
-Every action Reticle can perform takes the same shape: a `ref` from [`reticle_look { action: "page" }`](/tools/snapshot) or [`reticle_look { action: "find" }`](/tools/query), an `action` name, and an optional `args` object. The same actions are available on [`reticle_act`](/tools/act), which proves nothing, and on [`reticle_act_and_wait`](/tools/act-and-wait), which returns a verdict.
+Every action Reticle can perform takes the same shape: an element, an `action` name, and an optional `args` object. Give the element as a `ref` from [`reticle_look { action: "page" }`](/tools/snapshot) or [`reticle_look { action: "find" }`](/tools/query). Or give a `target` (`{ testid }`, `{ text }`, `{ role, name }` or `{ label }`) that Reticle finds in the same call. A press of Escape, Tab or a modifier shortcut goes to the document and needs neither. The same actions are available on [`reticle_act`](/tools/act), which proves nothing, and on [`reticle_act_and_wait`](/tools/act-and-wait), which returns a verdict.
 
 ```json
 { "ref": "e104", "action": "fill", "args": { "value": "reticle" } }
@@ -13,7 +13,7 @@ Every action Reticle can perform takes the same shape: a `ref` from [`reticle_lo
 
 | Action | Arguments | Notes |
 | --- | --- | --- |
-| `click` / `dblclick` | none | Dispatches a real click |
+| `click` / `dblclick` | none | Dispatches the full pointer and mouse sequence on the element. `args.native: true` forces a trusted native click |
 | `hover` | none | `mouseover` + `mouseenter`, so JS hover state triggers |
 | `focus` / `blur` | none |  |
 | `fill` | `{ value }` | Sets value via a React-safe native setter, then `input` and `change` |
@@ -53,7 +53,7 @@ Reticle blocks a control that looks destructive before acting on it:
 ```json
 {
   "error": "potentially destructive action blocked; retry with args.confirmDangerous=true",
-  "recovery": "Reticle blocked a potentially destructive control (delete, remove, revoke…) on purpose. If you mean it, retry the same action with args.confirmDangerous set to true. This is a deliberate refusal, not a defect: there is nothing to report."
+  "recovery": "Reticle blocked a control whose label reads as consequential (delete, remove, revoke, pay…) on purpose. If you mean it, send the SAME call again with `args: { confirmDangerous: true }`: it goes inside the `args` object, not beside it. This is a deliberate refusal, not a defect: there is nothing to report."
 }
 ```
 
@@ -96,13 +96,14 @@ Several actions in one round trip:
 
 <Warning>
   [`reticle_act { steps: [...] }`](/tools/act-sequence) returns `ok: true` when the steps were
-  **dispatched**, not when they worked. Batch the setup, then prove the outcome with
-  [`reticle_act_and_wait`](/tools/act-and-wait) on the final step.
+  **dispatched**, not when they worked. A step without `expect` proves nothing. Give the last step
+  an `expect` that names the end state, for example `"expect": { "kind": "signal", "name": "auth:granted" }`.
+  The sequence then returns a verdict and stops at the first `expect` that does not hold.
 </Warning>
 
 ## Real versus synthetic input
 
-`inputMode` in the response says which you got. `synthetic` means events dispatched programmatically. Correct for the overwhelming majority of apps. `real` means native CDP input, available under `reticle drive`, and needed by a few drag-and-drop and pointer-gesture libraries.
+`inputMode` in the response says which you got. `synthetic` means events dispatched programmatically. This is correct for most apps. `real` means native CDP input. You get it under `reticle drive`, and a few drag-and-drop and pointer-gesture libraries need it. On a leased tab (`reticle_lease`), a `press` uses the real keyboard: Tab moves focus, and a press with a `ref` focuses that element first, so Enter or Space presses it as a person would.
 
 <Warning>
   On a throttled tab, synthetic timers and pointer gestures can silently no-op. Pass

package/docs/adapters.md

@@ -1,6 +1,7 @@
 ---
 title: Writing an adapter
 description: What an adapter is, which kinds exist, and how to build one of your own.
+noindex: true
 ---
 
 Reticle watches an app from the inside. Most of what it does is the same everywhere: a click is a click, a failed request is a failed request. A few things are not, and those are what adapters are for.
@@ -13,7 +14,7 @@ There are three kinds, and they answer three different questions.
 | **build** | how does the SDK get into the page, and how does an element learn which file it came from? | `@reticlehq/vite-plugin` |
 | **realm** | how do we watch this kind of app's own traffic and take its picture? | `@reticlehq/electron` |
 
-You almost certainly want the first one. It is the only kind you can write today without changing Reticle itself, and it is the one that makes a failing check say `src/CartRow.tsx:42` instead of "something on the page".
+You almost certainly want the first one. It is one of two kinds you can write today without a change to Reticle itself (the other is a lint rule, see the end of this page). It is the kind that makes a failing check say `src/CartRow.tsx:42` instead of "something on the page".
 
 ## Writing a framework adapter
 

package/docs/agent-cheatsheet.md

@@ -6,7 +6,7 @@ icon: bolt
 
 The loop is **look → act → observe → assert**. Verdicts come from `reticle_act_and_wait`, `reticle_assert`, `reticle_act { steps }` when a step declares `expect`, and `reticle_verify` (`change`/`flows`). Everything else moves or reads the app and proves nothing. Only `verified: "yes"` is a pass: `unknown` means Reticle could not tell, and `no-fault` means nothing was declared to prove. Reach for `reticle_act_and_wait({ ref, action, until })` first: it names the expected consequence before the action, which is the difference between a check and a rationalisation.
 
-One screen to get fluent. Reticle is the **proof layer for AI agents**: no screenshots, no vision model, evidence not prose. Everything below returns structured data. Full guide: [usage.md](usage.md).
+One screen to get fluent. Reticle is the **proof layer for AI agents**: no screenshots, no vision model, evidence not prose. Everything below returns structured data. Full guide: [Usage](/usage).
 
 ## The core loop: look → act → observe → assert
 
@@ -48,6 +48,7 @@ Two consequences worth knowing:
 
 - **You can assert what a field contains.** Do not read the value with `reticle_look { action: "find" }` and compare it in prose: that produces no verdict and does not count as verification.
 - **`{ role, text }` checks the text,** so it does not match every button with that role.
+- **A `text` predicate reads rendered text, not a field's value.** Text typed into an `<input>` or a `<textarea>` is not on the page as text, so `{ kind: "text", contains }` does not see it. Assert it with `value` on an `element` predicate, as above.
 
 Fields that nothing can check are refused rather than ignored: `by` without a `value`, and `label`, `placeholder`, `testid` or `component` when a higher-precedence field already selected the element. `alt` is the one that can still be checked beside another locator: on an image it is compared with the image's `alt` attribute (so `alt: ""` passes on a decorative image but not on one missing its alt), and on anything that is not an image it is refused, with a hint to use `name`. An element query is a first-match dispatch, not a conjunction.
 
@@ -121,7 +122,7 @@ Most of what used to be a tool of its own is now an action on one of them:
 
 Call an old name and you are told the new one. `reticle_tools` prints the live surface and every mapping.
 
-- `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".
+- `reticle_verify`: **the tool that checks the whole app or the whole change in one call.** `{ 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".
 
 Not on this surface at all, but one hop away: `reticle_run { tool, args }` calls any registered tool by name, advertised or not, and `reticle_tools { names: [...] }` loads its arguments. That reaches `reticle_capabilities` (the app's whole testable surface in one call), `reticle_domain` (learn the app + gaps), `reticle_run { tool: "reticle_baseline", args: { action: "diff" } }`, `reticle_project` (run history), `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock` and `reticle_clock`. A daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises some of these directly (`reticle_capabilities`, `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock`, `reticle_clock`, plus `reticle_record`, `reticle_flow_save`, `reticle_flow_replay`, `reticle_intent` and `reticle_context`); the rest stay behind `reticle_run`. It also switches to the unmerged spelling: `reticle_snapshot`/`reticle_query`/`reticle_inspect`/`reticle_state` replace `reticle_look`, `reticle_network`/`reticle_console` replace `reticle_observe { action }`, `reticle_wait_for` replaces `reticle_assert { action: "wait" }`, `reticle_sessions`/`reticle_feedback` replace `reticle_session` list/feedback, and `reticle_act_sequence` replaces `reticle_act { steps }`. Examples on this page use the default spelling.
 
@@ -151,6 +152,8 @@ Recent additions, each of which answers a question agents were previously asking
 | `elided` | `reticle_act_and_wait` | Some diff arrays were capped. The count is real even when the list is trimmed, so a small array does not mean a quiet app. |
 | `colorTokens`, `themeScope` | `reticle_look { action: "element" }` | Every design token matching a colour, not one arbitrary winner, and which theme the reading was taken under. The singular `colorToken` is `null` when several tokens share a colour, because naming one of them was the defect. |
 | `why` | `reticle_session { action: "list" }`, when the list is empty | Why nothing is connected, and the next action. An empty list is never the end of the road. |
+| `engineBlindSpots` | `reticle_act_and_wait`, `reticle_assert` | What the engine could not see in this run: `pixels-unobserved` once an action ran with a `<canvas>` on screen, `claim-arithmetic-unchecked` while a claim states an amount and no verdict ran a `compare`. A clean verdict says nothing about these. |
+| `sdkVersion`, `sdkBehind` | `reticle_session { action: "list" }` | The Reticle SDK version in each tab. `sdkBehind` is present when the page is a minor release or more behind the daemon, and gives the update command. Each verdict on such a page carries a short `sdk_behind` note. |
 
 **When a verdict comes back `unsettled`,** it now names what it was waiting for and what the window actually held. Read those before retrying: an `unknown` that explains itself is a retry with a better `until`, and one that does not is a dead end.
 
@@ -158,15 +161,26 @@ Recent additions, each of which answers a question agents were previously asking
 
 ## Start here
 
-1. **First move, always:** `reticle_session { action: "list" }` finds the connected tab. Just ran `reticle init` or restarted the dev server? You do not need to poll: live tools wait briefly for a tab that is about to connect. Omit `sessionId` if there's only one tab. **An empty list is not a dead end: read the `why` field.** It names which case this is (no app running, an app running that has never dialled this daemon, a project that never went through `init`, or a tab that closed) and the fix for each. Do not fall back to static reasoning until you have read it.
+1. **First move, always:** `reticle_session { action: "list" }` finds the connected tab. Just ran `reticle init` or restarted the dev server? You do not need to poll: live tools wait briefly for a tab that is about to connect. Omit `sessionId` if there's only one tab. **An empty list is not a dead end: read `why`.** It names the case (no app running, an app that never dialled this daemon, a project that is not wired, or a tab that closed) and the fix for each. In a project that is not wired, `next_step` also names the next calls. `lease` (present when an app is running) is the zero-install check of the running app: do it first, because it changes no file. `consent` is the question for `init`, which changes `package.json`, the lockfile and the build config: ask the user, and run `init` only if they agree. Do not fall back to static reasoning until you have read `why`.
 2. `reticle_run({ tool: "reticle_domain", args: {} })` learns the app BEFORE testing: the saved flows, what each asserts, and the **gaps** (declared signals/testids that no flow verifies, i.e. untested intent). Tells you what to test and where the real risk is without crawling the whole app. Falls back to `reticle_run({ tool: "reticle_capabilities", args: {} })` for the raw testable surface (`testids`, `signals`, `stores`, `flows`).
 3. Run the loop: **look → act → observe → assert**, cross-checking the 4 layers on anything that matters.
 
+## No MCP tools in this host
+
+A cloud agent or a worker can have a shell and no MCP tools. Use the CLI. `verify --expect` asks a running daemon and never starts one, so start it first:
+
+```bash
+npx @reticlehq/server serve --headless
+npx @reticlehq/server verify http://localhost:5173/ --expect '{"kind":"text","contains":"Welcome"}'
+```
+
+It exits `0` only on `verified: "yes"`. `--expect-file <path>` reads the predicate from a file, and `--timeout N` sets how long it waits (default `4000` ms). To move a connected tab to another page first, run `npx @reticlehq/server open <url> --navigate`. For an action that `--expect` cannot do, use the [HTTP MCP transport](/http-transport).
+
 ## Token note
 
-- **Keep observation cheap.** Prefer `reticle_look { action: "find" }` / scoped or `interactive` `reticle_look { action: "page" }` / `reticle_assert` over dumping the full tree. A full verify loop is ~100 tokens; see [token-efficiency.md](token-efficiency.md) (~73× leaner than full-tree snapshots).
+- **Keep observation cheap.** Prefer `reticle_look { action: "find" }` / scoped or `interactive` `reticle_look { action: "page" }` / `reticle_assert` over dumping the full tree. A full verify loop is ~100 tokens; see [Token efficiency](/token-efficiency) (~73× leaner than full-tree snapshots).
 - **Re-look with `reticle_look({ action: "page", diff:true })`** after an action; it returns only what changed (`mode:delta`/`unchanged`), ~99% fewer tokens than a full re-snapshot and no stale tree to mis-read. Every snapshot/query result carries `cost:{ bytes, tokens }`, so re-scope before reading if it's large.
 - **Cap broad reads.** `reticle_look { action: "find" }` takes `limit` (caps descriptors; reports `total`/`truncated`) and `count_only` (just the match count). `reticle_observe { action: "network" }` / `reticle_observe { action: "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_assert { action: "wait" }` / `reticle_act_and_wait` is defined once (`PredicateSchema` in `@reticlehq/core`) and shared by all three tools. No action needed.
-- **One tool surface, and a hatch behind it.** Reticle advertises navigate/act/act_and_wait/assert/look/observe/session/verify, plus `reticle_tools` and `reticle_run`. That is the whole detect loop, the file-pointer, the feedback channel, the handback, and the one tool that CONCLUDES, reached by an `action` argument rather than by a name each. `reticle_tools` discovers: no args lists every registered tool name and summary, `names:[…]` loads full params on demand. `reticle_run { tool, args }` then calls any of them, advertised or not, which is what keeps recording a flow, screenshots, visual diff, storage, network mocking and the clock reachable without spending a slot on each. A daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read at startup, so restart it) advertises a wider set outright (the default tools plus the extra ones listed above), with output schemas, under the unmerged names listed above. It is not the whole registry: the count is capped because editors budget tools across every connected MCP server. `reticle_verify` is advertised: `{ 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. **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, and a hatch behind it.** Reticle advertises navigate/act/act_and_wait/assert/look/observe/session/verify, plus `reticle_tools` and `reticle_run`. That is the whole detect loop, the file-pointer, the feedback channel, the handback, and the tool that checks the whole app in one call, reached by an `action` argument rather than by a name each. `reticle_tools` discovers: no args lists every registered tool name and summary, `names:[…]` loads full params on demand. `reticle_run { tool, args }` then calls any of them, advertised or not, which is what keeps recording a flow, screenshots, visual diff, storage, network mocking and the clock reachable without spending a slot on each. A daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read at startup, so restart it) advertises a wider set outright (the default tools plus the extra ones listed above), with output schemas, under the unmerged names listed above. It is not the whole registry: the count is capped because editors budget tools across every connected MCP server. `reticle_verify` is advertised: `{ 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. **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

@@ -4,9 +4,9 @@ description: 'The moving parts, the data flow between them, and the design decis
 icon: sitemap
 ---
 
-Reticle has three moving parts: a dev-only **SDK** inside your page that instruments the DOM, network, console, routing and framework state; a local **server** that runs a WebSocket bridge to that SDK and an MCP server for your agent; and a git-checked **`.reticle/` workspace** holding flows, baselines and run artifacts. Your agent calls an MCP tool, the server turns it into a command over the WebSocket, the SDK runs it in the real page and streams structured events back.
+Reticle has three moving parts: a development **SDK** inside your page that instruments the DOM, network, console, routing and framework state; a local **server** that runs a WebSocket bridge to that SDK and an MCP server for your agent; and a git-checked **`.reticle/` workspace** holding flows, baselines and run artifacts. Your agent calls an MCP tool, the server turns it into a command over the WebSocket, the SDK runs it in the real page and streams structured events back.
 
-> For engineers evaluating Reticle, integrating it at scale, or contributing. It explains the moving parts, the data flow, and the design decisions behind them. If you just want to get running, start with [getting-started.md](getting-started.md); come back here when you want to know _why_.
+> For engineers evaluating Reticle, integrating it at scale, or contributing. It explains the moving parts, the data flow, and the design decisions behind them. If you just want to get running, start with [Getting started](/getting-started); come back here when you want to know _why_.
 
 ---
 
@@ -38,6 +38,9 @@ Reticle is a pnpm + Turborepo monorepo. The split is not cosmetic: each boundary
 | Package | Runs in | Responsibility | Hard rule |
 | --- | --- | --- | --- |
 | `@reticlehq/core` | both | The **wire contract**: every constant + zod schema crossing any boundary | Depends only on `zod` and `open-verification` |
+| `open-verification` | both | The Open Verification Protocol: vocabulary, rules, `adjudicate()` | Depends only on `zod` |
+| `@reticlehq/engine` | Node | The rules that decide a verdict | No browser, no daemon, no CLI |
+| `@reticlehq/init` | Node (build time) | `reticle init`: writes files and runs the package manager | Never opens a socket |
 | `@reticlehq/browser` | the browser | Instrument the page; execute commands; emit events | Never imports Node APIs |
 | `@reticlehq/server` | Node | The bridge, the MCP server, the `reticle` CLI, flow/run storage | Never imports DOM APIs |
 | `@reticlehq/react` | the browser | The SDK **kit** you install in a browser app: re-exports the browser sensor (so one install gives both `reticle` and `install`) and maps a DOM node → React component → source `file:line` | Core works without the source-mapping half |
@@ -57,7 +60,7 @@ The browser and server both import it; neither can invent a message the other do
 
 ## The data flow, end to end
 
-1. **Connect.** In dev, your app calls `reticle.connect({ session })`. The SDK opens a WebSocket to the bridge (`ws://localhost:4400/reticle` by default) and sends a `HELLO` carrying the session id, protocol version, and (if configured) a pairing token. Each browser tab uses `SESSION_AUTO` (a unique id), so multiple apps/tabs never collide.
+1. **Connect.** In dev, your app calls `reticle.connect({ session })`. The SDK opens a WebSocket to the bridge (`ws://localhost:4400/reticle` by default) and sends a `HELLO` carrying the session id, protocol version, and (if configured) a pairing token. Each browser tab uses `SESSION_AUTO` (a unique id), so multiple apps/tabs never collide. A second `connect()` on a live page does not open a second socket. If it names a `projectId` and the first call did not, the SDK sends `HELLO` again with the id, and the bridge moves the session to that project. An app that calls `connect()` itself, before the build plugin's `connect({ projectId })`, keeps its project this way.
 2. **Capture.** The SDK installs observers: a `MutationObserver` for DOM changes, wrappers around `fetch`/`XHR` for network, a console hook, a history hook for routing, and registries the app opts into (`registerStore`, `registerCapabilities`, `reticle.signal`). Events flow into a bounded **ring buffer**, so recent history is always available and memory is capped.
 3. **Look / act.** The agent calls an MCP tool. `reticle_look { action: "find" }` finds an element by role/text/testid/ component and returns a stable **ref**. `reticle_act` dispatches an action against that ref and returns an **effect** report (did it land, did the DOM mutate, did focus move…). The server sends the command over the WebSocket; the SDK runs it and replies.
 4. **Observe.** After an action, the agent reads what happened with `reticle_observe { action: "network" }`, `reticle_observe { action: "console" }`, `reticle_look { action: "state" }`, or the reaction digest from `reticle_act_and_wait`. The server pulls the relevant slice of the ring buffer (scoped to a cursor so stale events can't leak in) and returns a compact summary.
@@ -79,15 +82,15 @@ Reticle is honest about which tier a given assertion used, so "green" carries it
 
 ### 2. Structured reads, not screenshots
 
-A screenshot is ~1,365 image tokens per look, slow, non-deterministic, and **blind to everything non-visual**: the failed request, the console error, the route that didn't change. Reticle reads the accessibility tree, the network log, the console, and framework state as compact structured data. That's an order of magnitude cheaper _and_ it sees the bugs pixels can't. See [benchmarks.md](benchmarks.md) for the measured comparison.
+A screenshot is ~1,365 image tokens per look, slow, non-deterministic, and **blind to everything non-visual**: the failed request, the console error, the route that didn't change. Reticle reads the accessibility tree, the network log, the console, and framework state as compact structured data. That's an order of magnitude cheaper _and_ it sees the bugs pixels can't. See [Benchmarks](/benchmarks) for the measured comparison.
 
 ### 3. Record once, replay deterministically
 
 The same verification runs over and over, every commit, every CI run. Reticle records a **flow** once, then replays it with **no AI model**: it re-resolves each element's durable anchor against the live DOM and re-asserts the declared consequence. A CI gate diffs the verdict exactly, at ~0% flake, for a couple hundred tokens, versus an agent re-driving the whole flow with the model every time. Self- healing rebinds a drifted anchor **only if the consequence still fires**, so it never "heals to the wrong element and ships the regression."
 
-### 4. Dev-only, localhost-only, your app data stays local
+### 4. Development by default, your app data stays local
 
-The SDK is tree-shaken out of production builds and connects only to a local bridge. The bridge binds to loopback by default; exposing it beyond localhost _requires_ a pairing token (and the server refuses to start on a non-loopback host unless `RETICLE_ALLOWED_ORIGINS` names the app's origins). Every environment variable that gates a security control is a single named constant, so a typo can't silently disable auth. Nothing from the app under test leaves your machine unless you link a project: no DOM, network, console, state, or source. What a linked project syncs is set by `reticle config`; see [what is recorded](what-is-recorded.md). The CLI reports anonymous, opt-out usage metrics only (a random id + event names like `cli_command_run`/`daemon_started`; no code, no PII; see [telemetry](telemetry.md)); opt out with `reticle telemetry disable`, `RETICLE_TELEMETRY=0`, or `DO_NOT_TRACK=1`. The one thing that carries free text is feedback you or your agent deliberately send (`reticle feedback` / `reticle_session { action: "feedback" }`). It is never collected passively, it is redacted before sending, and it is disabled separately with `RETICLE_FEEDBACK=0`.
+By default the SDK is tree-shaken out of production builds and connects only to a local bridge. [Production mode](/production-mode) is the one exception: it is opt-in, and a page loads the SDK only with a signed, single-use activation ticket. The bridge binds to loopback by default. It refuses a connect without the pairing token, also on localhost. Exposing it beyond localhost also needs the token (and the server refuses to start on a non-loopback host unless `RETICLE_ALLOWED_ORIGINS` names the app's origins). Every environment variable that gates a security control is a single named constant, so a typo can't silently disable auth. Nothing from the app under test leaves your machine unless you link a project: no DOM, network, console, state, or source. What a linked project syncs is set by `reticle config`; see [what is recorded](/what-is-recorded). The CLI reports anonymous, opt-out usage metrics only (a random id + event names like `cli_command_run`/`daemon_started`; no code, no PII; see [telemetry](/telemetry)); opt out with `reticle telemetry disable`, `RETICLE_TELEMETRY=0`, or `DO_NOT_TRACK=1`. The one thing that carries free text is feedback you or your agent deliberately send (`reticle feedback` / `reticle_session { action: "feedback" }`). It is never collected passively, it is redacted before sending, and it is disabled separately with `RETICLE_FEEDBACK=0`.
 
 ---
 
@@ -107,7 +110,7 @@ This is plain, reviewable, version-controllable data, not a black box.
 ## Running at scale (multiple apps, multiple projects)
 
 - **Multiple apps / tabs on one bridge:** fine. Each connection has a unique `SESSION_AUTO` id; a tool call targets the focused/most-recent session, or you pass an explicit `sessionId`.
-- **Multiple isolated projects:** give each project its own bridge port via `RETICLE_PORT` (set it in the MCP config and dial the same port from the app). A port already in use fails fast with a clear error rather than hanging. See [getting-started.md → Running multiple apps](getting-started.md#running-multiple-apps-at-once).
+- **Multiple isolated projects:** give each project its own bridge port via `RETICLE_PORT` (set it in the MCP config and dial the same port from the app). A port already in use fails fast with a clear error rather than hanging. See [Getting started → Running multiple apps at once](/getting-started#running-multiple-apps-at-once).
 - **CI / no MCP:** `reticle verify <url>` replays the saved flows headlessly and exits non-zero on failure. It writes the same verdict artifact the MCP path produces, with no agent in the loop.
 
 ---
@@ -125,7 +128,7 @@ See [LICENSE](https://github.com/reticlehq/reticle/blob/main/LICENSE) and each p
 
 ## Where to go next
 
-- [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.
+- [Getting started](/getting-started) wires Reticle into your app in a couple of minutes.
+- [Benchmarks](/benchmarks) covers how we measure, and the honest results against the alternatives.
+- [Usage](/usage) is the full tool reference and advanced modes.
 - [CONTRIBUTING.md](https://github.com/reticlehq/reticle/blob/main/CONTRIBUTING.md) has the development loop and the rules.

package/docs/autodrive.md

@@ -56,7 +56,7 @@ Two arguments of the flow replay make the branches possible, and you can use the
 
 ## What it needs
 
-**A project on the Reticle platform.** Every plan includes the Harness. A new account gets 10 free credits (about two full drives of a small app), a card starts a 14-day trial with 500, and the paid plan includes 1,000 credits per seat each month. Run `reticle connect` once in your app's folder. The Harness runs on the platform: planning, personas, and every choice of what to press next. A model key of your own does not drive it, and a machine with no platform link gets the refusal and the way to fix it.
+**A project on the Reticle platform.** Every plan includes the Harness. A new account gets free credits to try it once, a card starts a 14-day trial with 500, and the paid plan includes 1,000 credits per seat each month. Run `reticle connect` once in your app's folder, then switch the Harness on for the project (`npx @reticlehq/server config --harness on`, or the switch in the HUD). The Harness runs on the platform: planning, personas, and every choice of what to press next. A model key of your own does not drive it, and a machine with no platform link gets the refusal and the way to fix it.
 
 | Variable | What it does |
 | --- | --- |
@@ -68,20 +68,21 @@ Two arguments of the flow replay make the branches possible, and you can use the
 
 ## How it decides
 
-The platform drives with Jev, a System One model that answers typed questions and cannot write. Every choice is a selection from candidates read off the page: which element, which tool, what consequence to claim. Three rules sit around those choices, because each one was a drive that stopped short or claimed nothing:
+The platform drives with Jev, a System One model that answers typed questions and cannot write. Every choice is a selection from candidates read off the page: which element, which tool, what consequence to claim. Four rules sit around those choices:
 
 - A journey that names a page it has not reached ("then turn on automatic refunds in Settings") is not finished. The Harness goes there instead of stopping.
 - A dialog whose destructive action already ran is closed rather than treated as the end of the journey.
 - A control the destructive-action gate refused is a write, so the Harness always claims a request or a signal for it. A save the server rejects then fails visibly instead of passing as nothing to prove.
+- The Harness takes an outward action (invite, send, share, delete, publish, revoke, sign out, change a role, create a key, change an item's state) only when the person's journey asks for it in so many words. Paying is not read from a button's words: "Start free trial", "Upgrade", "Subscribe" and "Place order" are pressed like any other control. Money moves when somebody types card or bank details (a field whose autocomplete is `cc-number`, `cc-csc` or `cc-exp`, or whose name or label says card number, CVC, expiry or IBAN) or leaves for a payment provider (Stripe, Dodo Payments checkout, Paddle, Lemon Squeezy, PayPal, Razorpay, Braintree). The Harness does those two only when the journey asks to pay.
 
 ## Turning it off, and who pays for it
 
 A project linked to a Reticle workspace reads two things from it before a drive starts, and honours both:
 
-- **The switch.** Autonomous driving can be turned off per project, from the HUD's Reticle Harness switch or the dashboard (Settings → Projects → Reticle Harness on <project>). A drive then refuses and says where to turn it back on. Switched off while a platform drive is running, the drive stops at its next turn with `stopReason: "stopped"`, keeps what it drove, and says so in the Agent Log. Everything else is unaffected, including the tools your own agent drives with.
-- **Credits.** Harness drives and dashboard chat checks spend Harness credits. The platform sets the amount for your plan (see above). The HUD shows how many are left; once they are spent a drive is refused with that number and the way to get more.
+- **The switch.** The Harness is off for a new project, because each drive spends credits. Switch it on for each project: use the Reticle Harness switch in the HUD, the dashboard (Settings → Projects), or run `npx @reticlehq/server config --harness on` in the project. While it is off, a drive refuses and tells you how to switch it on. If you switch it off while a platform drive runs, the drive stops at its next turn with `stopReason: "stopped"`, keeps what it drove, and says so in the Agent Log. The switch does not change the tools that your own agent drives with.
+- **Credits.** Harness drives and dashboard chat checks spend credits, the same credits that pay for the rest of the platform. The platform sets the amount for your plan (see above). The HUD shows how many are left; once they are spent a drive is refused with that number and the way to get more.
 
-If only the settings endpoint is unreachable, the on/off switch and the credit check do not block a drive: an unreachable settings endpoint is not a reason to lose a feature you were never told to stop using. The drive itself still needs the platform, so with no connection at all it is refused with the reason.
+If Reticle cannot read the project settings from the platform, the drive does not start. It needs a confirmed yes from the platform for the switch and the credits. Try again when the platform answers.
 
 ## What it will not do
 

package/docs/benchmarks.md

@@ -160,7 +160,7 @@ Measured on the observation-cost pass (numbers regenerate from `bench/raw/`). Th
 | Playwright MCP | 9 / 10 | 0.91 | 1,292 | 6.97 |
 
 - **Reticle is the only tool that caught every regression**, with zero false alarms on the control.
-- DevTools is a hair cheaper per look (758 vs 815 tokens), **but it's cheaper because it catches less.** On the metric that combines both (Verification Efficiency), Reticle leads at 12.27 vs 10.55.
+- DevTools is a little cheaper per look (758 against 815 tokens), **because it catches less.** Only Reticle passes the 100% catch gate, so only Reticle has a qualifying Verification Efficiency. The table shows the ungated value for the other two, for comparison only: 12.27 against 10.55 and 6.97.
 - Playwright catches a lot but is ~1.6× more expensive per look, so its efficiency is lowest here.
 
 ### 5c. A real production app (the Reticle dashboard)
@@ -284,7 +284,7 @@ Reticle is **most efficient exactly where big companies hurt most**: a large num
 - `bench/METRIC.md` holds the exact metric definitions.
 - `bench/METHODOLOGY.md`: full design (controls, scenarios, fairness).
 - `bench/history.jsonl`: every measured run over time.
-- `bench/raw/` holds raw payloads and per-scenario results (gitignored locally; regenerated by `pnpm bench`).
+- `bench/raw/` holds raw payloads and per-scenario results. `pnpm bench` regenerates them. Git ignores them, except the five files that a published number rests on (`schema-tax.json`, `compiled-suite-vs-replay.json`, `suite-rre.json`, `leak-stress.json`, `stress-tiers.json`).
 
 ---
 

package/docs/capabilities.mdx

@@ -4,7 +4,7 @@ description: Coverage, storage, fake clocks, autonomous crawling, visual diffing
 icon: sparkles
 ---
 
-These are the Reticle tools that do something other than look, act, observe and assert: control coverage, client storage, a fake clock, autonomous crawling, semantic and visual baselines, network mocking, flow recording and replay, and the CI artifact. Reach for them when the verify loop is not the shape of the question. They are **not advertised on the default tool surface, but they are reachable from it**: `reticle_run({ tool, args })` dispatches to any registered tool by name, advertised or not, which is the spelling used on this page. Starting the daemon with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read once at startup, so restart it) advertises some of them outright, with their output schemas: storage, clock, screenshot, visual diff, network mocking, recording, flow save and replay. The rest stay behind `reticle_run` on every surface.
+These are the Reticle tools that do something other than look, act, observe and assert: control coverage, client storage, a fake clock, autonomous crawling, semantic and visual baselines, network mocking, flow recording and replay, and the CI artifact. Reach for them when the verify loop is not the shape of the question. They are **not advertised on the default tool surface, but they are reachable from it**: `reticle_run({ tool, args })` dispatches to any registered tool by name, advertised or not, which is the spelling used on this page. Starting the daemon with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read once at startup, so restart it) advertises more tools outright, with their output schemas: capabilities, intent, context, storage, clock, screenshot, visual diff, network mocking, recording, flow save and replay. That surface uses the separate tool names (`reticle_sessions`, `reticle_snapshot`, `reticle_query`, `reticle_network`, `reticle_console`, `reticle_wait_for`), not `reticle_look` and the `action` forms that these docs use. The rest stay behind `reticle_run` on every surface.
 
 Most of the time you want the verify loop. Look, act, observe, assert. These are the tools for the times you want something else, and they are the ones people are most surprised exist.