@reticlehq/server 2.8.0 → 2.10.0

package/docs/telemetry-events.mdx

@@ -4,7 +4,15 @@ description: Every Reticle telemetry event, its payload schema, where it is emit
 icon: database
 ---
 
-This is a contributor reference. If you just want to know what Reticle collects and how to turn it off, read [Telemetry](/telemetry) instead; that page is written for people who use Reticle, and this one is written for people who change it.
+<Warning>
+  **This page is for contributors, not users.** It documents the internal event *schema* so that
+  somebody changing Reticle's code emits the right shape. It contains no data and no measurements.
+
+If you want to know what Reticle collects about you and how to turn it off, read [Telemetry](/telemetry) instead. That is the user-facing page, and it is the one with the opt-out.
+
+</Warning>
+
+Every event Reticle emits is listed below with the same three things: **when it fires**, **what it carries**, and **why it exists**. The authoritative list is `TelemetryEventKind` in `packages/core/src/telemetry.ts`; if this page and that file disagree, the file wins and this page is a bug.
 
 Source of truth for everything below:
 
@@ -16,7 +24,7 @@ Source of truth for everything below:
 
 ## The shared envelope
 
-`TelemetryEventSchema` wraps every event. These fields are on all sixteen kinds.
+`TelemetryEventSchema` wraps every event. These fields are on every event kind, whatever it is.
 
 | Field | Type | Required | Meaning |
 | --- | --- | --- | --- |
@@ -24,7 +32,7 @@ Source of truth for everything below:
 | `anonymousId` | string, 1 to 128 | yes | Random UUID persisted at `~/.reticle/telemetry-id`. Distinct count of this is users |
 | `projectId` | string, 1 to 128 | no | One-way hash of the git remote, repo root, package root, or cwd. Counts distinct projects without revealing one |
 | `sessionId` | string, 1 to 64 | no | One daemon run. Present only on session-scoped events |
-| `event` | `TelemetryEventKind` | yes | Which of the sixteen |
+| `event` | `TelemetryEventKind` | yes | Which kind this is. The full list is `TelemetryEventKind` in `packages/core/src/telemetry.ts` |
 | `ts` | int, epoch ms | yes | Client time. The server stamps its own receive time too |
 | `version` | string, 1 to 64 | yes | The Reticle version emitting |
 | `ci` | boolean | yes | Running inside CI. Separates human activity from pipeline traffic |
@@ -33,7 +41,9 @@ Source of truth for everything below:
 | `tzOffsetMin` | int, -900 to 900 | no | Minutes offset from UTC. Turns a time-of-day chart from "which continent" into "9am or 11pm" |
 | `actor` | `TelemetryActor` | no | `human` or `agent`. Absent on events that are neither |
 
-Then exactly one payload block, keyed by event. The keys are `feedback`, `command` plus `flags`, `session`, `project`, `verification`, `versionChange`, `crash`, `identity`, `connection`, `init`, `bug`, `outage`, `instrumentation`.
+Then exactly one payload block, keyed by event. The keys are `feedback`, `command` plus `flags`, `session`, `project`, `verification`, `versionChange`, `crash`, `identity`, `connection`, `init`, `bug`, `refusal`, `outage`, `instrumentation`, `stall`.
+
+Plus `installSource`, which is not a block. It is resolved once per process and stamped on **every** event, so it is the one attribution field you can group any chart by.
 
 <Warning>
   `emit()` builds its wire event from an explicit allowlist of keys. A payload block that is not on
@@ -43,9 +53,11 @@ Then exactly one payload block, keyed by event. The keys are `feedback`, `comman
 
 ## Session scope
 
-`isSessionScoped(kind)` decides whether `sessionId` is attached. Eleven kinds are session-scoped:
+`isSessionScoped(kind)` decides whether `sessionId` is attached. Twelve kinds are session-scoped:
 
-`daemon_started`, `daemon_stopped`, `session_progress`, `mcp_client_connected`, `app_instrumented`, `project_profiled`, `verification_completed`, `bug_found`, `tool_refused`, `runtime_crashed`, `feedback_submitted`.
+`daemon_started`, `daemon_stopped`, `session_progress`, `mcp_client_connected`, `app_instrumented`, `instrumentation_stalled`, `project_profiled`, `verification_completed`, `bug_found`, `tool_refused`, `runtime_crashed`, `feedback_submitted`.
+
+`mcp_connection_lost` is deliberately **not** on that list even though it feels session-shaped. It fires from the proxy process rather than the daemon, so it carries no `sessionId` and cannot be joined to a session at all.
 
 The other six are one-shot. A per-process id on `reticle status` is not a session: it joins to nothing and inflates every session count that runs a distinct count over the field.
 
@@ -53,7 +65,7 @@ The other six are one-shot. A per-process id on `reticle status` is not a sessio
 
 ## reticle_installed
 
-**Wire name:** `reticle_installed`. **Emitted from:** `packages/server/src/telemetry/cli-telemetry.ts:50`. **Session-scoped:** no. **Payload block:** none.
+**Wire name:** `reticle_installed`. **Emitted from:** `packages/server/src/telemetry/cli-telemetry.ts:51`. **Session-scoped:** no. **Payload block:** none.
 
 Fires on the first ever run on a machine. Carries `installSource`.
 
@@ -61,7 +73,7 @@ Fires on the first ever run on a machine. Carries `installSource`.
 | --- | --- | --- |
 | `installSource` | `InstallSource`, optional | Which published route brought this install in: `skill_file`, `npx_skill`, `plugin`, `docs_site`, `readme`, `cli_direct`, `unknown` |
 
-`installSource` is **declared, never detected**. A channel sets `RETICLE_INSTALL_SOURCE` on the process that runs the install and anything unrecognised reports `unknown`, so `unknown` is expected to be the largest bucket while the marker spreads across four separately published artifacts. Read a small `unknown` as a marker that spread, never as success. Nothing infers it: `npm_config_user_agent` only says npx ran us and every route goes through npx; the presence of a plugin directory or a skill folder says a route exists rather than that it ran the install. The same field rides on `init_completed`.
+`installSource` is **declared, never detected**. A channel sets `RETICLE_INSTALL_SOURCE` on the process that runs the install and anything unrecognised reports `unknown`, so `unknown` is expected to be the largest bucket while the marker spreads across four separately published artifacts. Read a small `unknown` as a marker that spread, never as success. Nothing infers it: `npm_config_user_agent` only says npx ran us and every route goes through npx; the presence of a plugin directory or a skill folder says a route exists rather than that it ran the install. `installSource` is **not** limited to this event. It is resolved once per process (`packages/server/src/telemetry/telemetry.ts:392`) and stamped on every event that process sends (`:453`), so any chart can group by it. It is also sourced **config first, then environment**: `projectInstallSource()` prefers the value recorded in `.reticle.json`, because the environment variable exists for exactly one command and is gone by the next, which is why the field originally reached a handful of events and nothing else.
 
 **The question it answers:** how many machines have installed this, and what does the new-user curve look like? There is deliberately no uninstall event, because npm 7 and pnpm run no uninstall lifecycle script. Churn is inferred server-side from inactivity instead.
 
@@ -69,7 +81,7 @@ Fires on the first ever run on a machine. Carries `installSource`.
 
 ## cli_command_run
 
-**Wire name:** `cli_command_run`. **Emitted from:** `packages/server/src/telemetry/cli-telemetry.ts:52`. **Session-scoped:** no. **Payload:** two envelope fields.
+**Wire name:** `cli_command_run`. **Emitted from:** `packages/server/src/telemetry/cli-telemetry.ts:58`. **Session-scoped:** no. **Payload:** two envelope fields.
 
 | Field | Type | Meaning |
 | --- | --- | --- |
@@ -93,7 +105,7 @@ Fires on the first ever run on a machine. Carries `installSource`.
 
 ## daemon_started
 
-**Wire name:** `daemon_started`. **Emitted from:** `packages/server/src/telemetry/daemon-telemetry.ts:73`. **Session-scoped:** yes. **Payload block:** none.
+**Wire name:** `daemon_started`. **Emitted from:** `packages/server/src/telemetry/daemon-telemetry.ts:75`. **Session-scoped:** yes. **Payload block:** none.
 
 **The question it answers:** how many active daemon runs are there? This is the numerator of daily, weekly and monthly actives, and the first step of the install funnel.
 
@@ -101,7 +113,7 @@ Fires on the first ever run on a machine. Carries `installSource`.
 
 ## daemon_stopped
 
-**Wire name:** `daemon_stopped`. **Emitted from:** `packages/server/src/telemetry/daemon-telemetry.ts:120`. **Session-scoped:** yes. **Payload block:** `session`, a `SessionSummary` with `final: true`.
+**Wire name:** `daemon_stopped`. **Emitted from:** `packages/server/src/telemetry/daemon-telemetry.ts:138`. **Session-scoped:** yes. **Payload block:** `session`, a `SessionSummary` with `final: true`.
 
 The rich one. One event carries the entire session rolled up, replacing the hundreds a per-tool-call event would send. PostHog bills per ingested event and a single verification loop is a great many tool calls, so aggregation here is a design decision, not an optimisation.
 
@@ -150,7 +162,7 @@ The rich one. One event carries the entire session rolled up, replacing the hund
 
 ## session_progress
 
-**Wire name:** `session_progress`. **Emitted from:** `packages/server/src/telemetry/daemon-telemetry.ts:98`. **Session-scoped:** yes. **Payload block:** `session`, the same `SessionSummary` shape with `final: false` and no `exit`.
+**Wire name:** `session_progress`. **Emitted from:** `packages/server/src/telemetry/daemon-telemetry.ts:116`. **Session-scoped:** yes. **Payload block:** `session`, the same `SessionSummary` shape with `final: false` and no `exit`.
 
 A periodic roll-up from a daemon that is still running.
 
@@ -167,7 +179,7 @@ A periodic roll-up from a daemon that is still running.
 
 ## verification_completed
 
-**Wire name:** `verification_completed`. **Emitted from:** `packages/server/src/tools/invoke-tool.ts:125` and `packages/server/src/telemetry/run-telemetry.ts:38`. **Session-scoped:** yes. **Payload block:** `verification`.
+**Wire name:** `verification_completed`. **Emitted from:** `packages/server/src/tools/invoke-tool.ts:144` and `packages/server/src/telemetry/run-telemetry.ts:39`. **Session-scoped:** yes. **Payload block:** `verification`.
 
 ### `VerificationSchema`
 
@@ -189,7 +201,7 @@ A periodic roll-up from a daemon that is still running.
 
 ## project_profiled
 
-**Wire name:** `project_profiled`. **Emitted from:** `packages/server/src/telemetry/daemon-telemetry.ts:87`. **Session-scoped:** yes. **Payload block:** `project`. Once per daemon start, so it is cheap.
+**Wire name:** `project_profiled`. **Emitted from:** `packages/server/src/telemetry/daemon-telemetry.ts:91`. **Session-scoped:** yes. **Payload block:** `project`. Once per daemon start, so it is cheap.
 
 ### `ProjectProfileSchema`
 
@@ -307,7 +319,7 @@ The one kind that carries author-written free text, which is exactly why it is n
 | --- | --- | --- |
 | `reconnect` | boolean | False on the first attach to this daemon, true for every attach after |
 | `daemonAgeMs` | int | How long the daemon had been up first |
-| `client` | string, optional | From the handshake: `claude-code`, `cursor` |
+| `client` | string, optional | **Never populated today.** The schema defines it and `mcp-connection.ts:35` would spread it, but the only caller (`http-server.ts:202`) passes no argument, so it is absent on every event ever sent. The client name and version _are_ captured, at `mcp/mcp.ts:461` and `:471` on `oninitialized`, and land in `session.clients` / `session.clientVersions`. Per-connect client attribution is therefore only reachable by joining to the session summary on `sessionId`. |
 
 **The question it answers:** is somebody actually using this, as opposed to having it installed and running? A daemon can sit up for days with no agent attached. A large `daemonAgeMs` on the **first** connect is the interesting case: Reticle was started and then sat unused, which is an onboarding failure nobody would otherwise report. Reconnect churn is visible here too, and a client reattaching every few minutes looks identical to healthy usage in every other metric.
 
@@ -329,6 +341,39 @@ Fired **once per daemon run**, on the first connect only, so `daemon_started` to
 
 ---
 
+## instrumentation_stalled
+
+**Wire name:** `instrumentation_stalled`. **Emitted from:** `packages/server/src/telemetry/instrumentation-stall.ts:73`, called from `daemon-telemetry.ts:105`. **Session-scoped:** yes. **Payload block:** `stall`.
+
+The failure side of `app_instrumented`, and the reason the funnel has a denominator at all. A daemon that runs for ten minutes without a single SDK-carrying page is an install that half worked, and until this event existed that outcome was pure silence: indistinguishable from a machine nobody touched.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `initialized` | boolean | Has `init` run in this working directory (`readProjectId(cwd)` resolves). False means the daemon is running somewhere `init` never wrote a project id, which is usually a wrong-directory problem rather than a wiring one |
+| `agentAttached` | boolean | Was an agent connected at the moment the check ran. **This is the field that decides whether the row is a defect.** False means somebody installed and walked away, which is not a bug. True means an agent was sitting there with tools it could not use, which is the failure the product actually has |
+| `msWaited` | int | Milliseconds since the daemon started, from the clock marked at `daemon-telemetry.ts:84` |
+
+Deliberately the same three facts as `app_instrumented`, with `msWaited` standing in for `msToFirstApp`, so the success and failure rows are directly comparable without reshaping either.
+
+**When it fires:** on every flush tick, but only once all four guards at `instrumentation-stall.ts:64` pass: it has not already been reported this run, no app has ever connected, the clock was marked, and at least `STALL_AFTER_MS` (10 minutes) has elapsed. It is checked **before** the empty-window early return in `flushWindow`, which is not an accident: a stalled install produces an empty window by definition, so checking after the return would blind the event to the exact condition it exists to report.
+
+**The question it answers:** of the installs that never reach a verdict, how many had an agent present and waiting? That is the difference between a distribution problem and a wiring problem, and they need opposite responses.
+
+**What it is blind to:**
+
+- **Any diagnosis.** It never says whether a dev server is listening, because that is a live probe, and probing a user's machine to enrich a metric is collecting for the metric's sake.
+- **Slow starts.** A run that connects at minute eleven reports nothing at all, and neither does the recovery. The event answers "did this run stall", not "how long do installs take".
+- **The page side.** Every real cause (a non-localhost gate, a port mismatch, a stale build, a dev server never restarted) lives where the daemon cannot see. Attributing a stall needs the SDK to report its own refusals, and that is not built.
+- **Repeats.** Once per daemon run, so a user stuck for a week contributes one row per daemon start, not one per hour.
+
+<Warning>
+  This kind has no live check in `apps/e2e/specs/telemetry-events-test.mjs`, and neither do
+  `session_progress` and `app_instrumented`. Those three are the funnel, and the funnel is the part
+  of the wire nothing fires end to end. Adding one is the highest-value thing left in this file.
+</Warning>
+
+---
+
 ## mcp_connection_lost
 
 **Wire name:** `mcp_connection_lost`. **Emitted from:** `packages/server/src/mcp/mcp-outage.ts:53`. **Session-scoped:** no. **Payload block:** `outage`.
@@ -348,7 +393,7 @@ Fired **once per daemon run**, on the first connect only, so `daemon_started` to
 
 ## init_completed
 
-**Wire name:** `init_completed`. **Emitted from:** `packages/server/src/telemetry/init-telemetry.ts:31`. **Session-scoped:** no. **Payload block:** `init`.
+**Wire name:** `init_completed`. **Emitted from:** `packages/server/src/telemetry/init-telemetry.ts:32`. **Session-scoped:** no. **Payload block:** `init`.
 
 | Field | Type | Meaning |
 | --- | --- | --- |
@@ -363,7 +408,7 @@ Fired **once per daemon run**, on the first connect only, so `daemon_started` to
 
 ## bug_found
 
-**Wire name:** `bug_found`. **Emitted from:** `packages/server/src/tools/invoke-tool.ts:147` and `packages/server/src/telemetry/run-telemetry.ts:58`. **Session-scoped:** yes. **Payload block:** `bug`.
+**Wire name:** `bug_found`. **Emitted from:** `packages/server/src/tools/invoke-tool.ts:166` and `packages/server/src/telemetry/run-telemetry.ts:59`. **Session-scoped:** yes. **Payload block:** `bug`.
 
 | Field | Type | Meaning |
 | --- | --- | --- |
@@ -388,7 +433,7 @@ The payload never carries a selector, a URL, an element, or any description of t
 
 ## tool_refused
 
-**Wire name:** `tool_refused`. **Emitted from:** `packages/server/src/tools/invoke-tool.ts`, via `packages/server/src/telemetry/tool-refused.ts`. **Session-scoped:** yes. **Payload block:** `refusal`.
+**Wire name:** `tool_refused`. **Emitted from:** `packages/server/src/telemetry/tool-refused.ts:49`, reached from four call sites in `packages/server/src/tools/invoke-tool.ts` (`:285` a handler threw, `:325` the wrong-tab guard, `:346` a message-shaped refusal, `:376` the `{error}` return convention). **Session-scoped:** yes. **Payload block:** `refusal`.
 
 | Field | Type | Meaning |
 | --- | --- | --- |

package/docs/telemetry.md

@@ -4,7 +4,7 @@ description: 'The complete description of the anonymous usage data Reticle colle
 icon: chart-line
 ---
 
-Reticle collects a small amount of anonymous usage data to help us understand whether the tool is useful: which commands people run, which tools agents actually use, and whether people keep using Reticle after they try it. That's what this data is for, and all it is for: making the product better.
+Reticle sends anonymous usage counters (which commands ran, which tools an agent called, whether a verification produced a verdict) and nothing from the app under test. To turn it off permanently, run `npx @reticlehq/server telemetry disable`.
 
 This page is the complete description of what is collected. If something is not listed here, it is not sent.
 
@@ -21,7 +21,7 @@ This page is the complete description of what is collected. If something is not
 
 ## What is sent
 
-Thirteen kinds of events, each a single small JSON object:
+Eighteen kinds of events, each a single small JSON object. This is the whole list, and it is the same list the code enumerates:
 
 | Event | When | Extra data |
 | --- | --- | --- |
@@ -29,12 +29,15 @@ Thirteen kinds of events, each a single small JSON object:
 | `cli_command_run` | You run a `reticle` command | Which subcommand (`verify`, `status`, …) and which flags were present, by name |
 | `daemon_started` | The local daemon starts | n/a |
 | `daemon_stopped` | The local daemon stops | A summary of the session; see below |
+| `session_progress` | Periodically, from a daemon that is still running | The same summary as `daemon_stopped`, marked `final: false`. It exists so a long session is not invisible until it exits |
+| `app_instrumented` | The first time your app's SDK connects in a given daemon run | Nothing beyond the common fields. It is the second half of the install funnel: registering the MCP server is one thing, getting the SDK into a running page is another |
+| `instrumentation_stalled` | Ten minutes into a daemon run in which your app has still never connected | The same three facts as `app_instrumented`, with how long it waited instead of how long it took. It fires at most once per daemon run, and a run that starts slowly and then works reports nothing at all. It carries no diagnosis: whether a dev server is listening would need a live probe, and probing your machine to enrich a metric is collecting for the metric's sake |
 | `verification_completed` | A verification produces a verdict | Whether it passed, whether Reticle refused to call a passing check verified, and **why** the verdict came out that way; see below |
 | `project_profiled` | Once per daemon start | The shape of the project; see below |
 | `version_changed` | You update or roll back | The two version numbers, and which direction |
 | `runtime_crashed` | The daemon hits an uncaught error | The error's type, **Reticle's own** stack frames, and the message with variables stripped; see below |
 | `mcp_client_connected` | An agent attaches to the daemon | Whether it is a reconnect, and how long the daemon had been idle |
-| `mcp_connection_lost` | The agent's MCP tools go away | Which stage (`first`, or `budget_spent` when it stopped retrying), the cause, and the attempt count. **At most twice per session**: one measured afternoon produced 547 reconnects, and an event each would bill for the pathology instead of measuring it |
+| `mcp_connection_lost` | The agent's MCP tools go away | Which stage (`first`, or `budget_spent` when it stopped retrying), the cause, and the attempt count. **At most twice per session**, because a reconnect loop can fire many times in a row and an event each would bill for the pathology instead of measuring it |
 | `init_completed` | `reticle init` finishes | Whether it worked, a classified reason when it did not, and which published install route you came through, DECLARED by that route via `RETICLE_INSTALL_SOURCE` and never inferred, and `unknown` when nothing declared one |
 | `bug_found` | Reticle finds a defect in the app under test | The **kind** of defect (`signal-contradicted`, `console-error`, …) and how it was found, never what it was found in |
 | `tool_refused` | A tool cannot do what an agent asked | Which tool, why (one of six buckets: no session, no match, unsupported, bad arguments, not ready, other), and whether the same call was retried. **Never the message**, because a refusal interpolates whatever you asked for, so only the tool name and the bucket are sent. Capped at 50 per daemon run |
@@ -51,7 +54,7 @@ It also carries a snapshot of the **machine's** state (our own process's memory,
 
 ### Why a verdict came out that way
 
-`verification_completed` carries the **clause** that decided the verdict, from a fixed list we define: `proved`, `contradicted`, `assertion_failed`, `already_true`, `unclean_capture`, `vacuous_grade`, `outcome_pending`, `outcome_unread`, `unsettled`, `observation_lost`, `inconclusive`.
+`verification_completed` carries the **clause** that decided the verdict, from a fixed list we define: `proved`, `contradicted`, `assertion_failed`, `already_true`, `unclean_capture`, `vacuous_grade`, `outcome_pending`, `outcome_unread`, `unsettled`, `evidence_incomplete`, `observation_lost`, `inconclusive`.
 
 It exists because `verified: "unknown"` covered seven different situations belonging to three different owners (your app, your agent, and Reticle's own blind spots), and they arrived as one value. It is a **name from our own vocabulary**, never a description of your app: `contradicted` says two channels disagreed, not which ones, about what, or on which page.
 
@@ -139,7 +142,7 @@ Alongside the report, a feedback event carries context about the environment it
 | `driver` | `cdp`, `sdk` | Whether Reticle drove the page or observed your own browser |
 | `client` | `claude-code`, `cursor` | The MCP client's own name from its handshake |
 | `mcpScope` | `user`, `project` | How Reticle is registered |
-| `kind` | `bug`, `gap`, `ambiguity`, `experience` | A defect, a blind spot, an undecidable verdict, or an overall take |
+| `kind` | `bug`, `gap`, `ambiguity`, `feature_request`, `improvement`, `experience` | A defect, a blind spot, an undecidable verdict, a thing that does not exist, a thing that exists but is awkward, or a human's overall take |
 
 Plus the `version`, `os`, and `ci` fields every event carries. No paths, no project name, no dependency list, no user-agent string.
 

package/docs/testing.md

@@ -4,7 +4,9 @@ description: 'Turn an interactive drive into a repeatable suite with @reticlehq/
 icon: vial
 ---
 
-Driving Reticle interactively is reconnaissance. To turn it into a **repeatable, CI-runnable** suite, write declarative specs with `@reticlehq/test`. Specs bind to **signals and testids, never DOM structure**, so they inherit Reticle's refactor-resistance.
+To run Reticle checks in CI, install `@reticlehq/test`, write specs with `reticleTest(name, async (t) => …)`, then boot a headless session with `bootSession({ driveUrl, headless: true })` and run them with `runSpecs`. Exit non-zero when `summary.failed` is not `0`. Specs bind to **signals and testids, never DOM structure**, so they survive the refactors that break selector-based suites.
+
+Driving Reticle interactively is reconnaissance. This page is how you make it repeatable.
 
 ```ts
 import { reticleTest } from '@reticlehq/test';
@@ -84,3 +86,35 @@ import { flowsAsSpecs } from '@reticlehq/test';
 ## Authoring tip: record → prune → commit
 
 You don't have to hand-write steps. Drive the flow once (or record it via the panel), let Reticle emit the program, trim it, and commit it as a spec. The regression test is a byproduct of testing, not separate work.
+
+## FAQ
+
+### Do I need vitest or jest to run these?
+
+No. `runSpecs` is its own runner: it takes the specs registered by `reticleTest`, an `invoke` function, and a `print` callback, and returns `{ results, summary }`. You can call it from a plain `node script.mjs`. If you already have vitest, nothing stops you calling `runSpecs` from inside a test, but the runner does not depend on one.
+
+### How do I fail the CI job?
+
+`runSpecs` never throws on a failing spec, so you have to read the summary and exit yourself:
+
+```ts
+process.exit(summary.failed === 0 ? 0 : 1);
+```
+
+`summary` carries `{ total, passed, failed, skipped, ok }`. Note that **skipped is not failed**: a spec that skipped with a reason (see `t.expectInputModeReal()`) leaves `failed` at `0`.
+
+### Why did my hover or drag spec skip instead of running?
+
+Because native input was not active. `t.expectInputModeReal()` deliberately skips with a reason rather than passing on a synthetic no-op, since a synthetic hover cannot trigger a CSS `:hover` or a pointer-library drag. If you want those specs to actually run, drive the app with real input: `npx @reticlehq/server drive http://localhost:4310`, or point the server at a CDP endpoint with `RETICLE_CDP_URL`.
+
+### Does the app need to be running already?
+
+Yes. The spec runner is attach-only and never starts your dev server (that is the interactive agent's job, not CI's). Boot your app first, then pass its URL as `driveUrl`. If nothing is listening there, `bootSession` opens a headless tab against a URL that serves nothing and no session ever connects.
+
+### Can I emit JUnit for my CI's test reporter?
+
+Yes, `toJUnitXml` and `writeJUnit` are both exported from `@reticlehq/test`. Pass them the results array from `runSpecs`.
+
+### Do I have to write specs by hand if I already have flows?
+
+No. `flowsAsSpecs` registers one `reticleTest` per flow under `.reticle/flows/`, replayed with that flow's own `expect` and `success` predicates and skipping its `dynamic` regions. That keeps the recorded map and the CI suite from drifting apart, because they are the same artifact.

package/docs/token-efficiency.md

@@ -4,6 +4,8 @@ description: Why asking narrow questions costs a fraction of feeding the whole a
 icon: coins
 ---
 
+A full Reticle verify loop costs about **100 tokens**, against roughly **7,300** for a full-tree accessibility snapshot on the same page: about 73x leaner, because Reticle asks a narrow question instead of returning the page. If you re-look after an action with `reticle_snapshot({ diff: true })`, the re-read costs about 99% less again.
+
 Agent browser tools that feed the **whole accessibility tree** to the model every step get expensive fast. Playwright MCP's own ecosystem notes its snapshots _"can exceed 50,000 tokens on complex pages,"_ with a _typical task ~114,000 tokens through MCP._ Reticle is built to ask **narrow questions** instead, so the per-interaction cost stays tiny.
 
 ## Head-to-head (measured, same page, same moment)
@@ -33,7 +35,7 @@ Measured on a representative 150-row dashboard (the shipped regression benchmark
 | Payload                            |    Tokens |
 | ---------------------------------- | --------: |
 | Full re-snapshot (150-row table)   | **4,246** |
-| `diff:true` after a one-row change |    **60** |
+| `diff:true` after a one-row change |    **65** |
 | `diff:true` when nothing changed   |    **17** |
 
 **~99% fewer tokens** to re-look after an action, and because a `delta` carries no stale full tree, it also removes the 60K to 80K-token stale-context buildup that makes long-running agents start hallucinating selectors that no longer exist.
@@ -53,9 +55,13 @@ Measured live, all servers in one run, same tokenizer (`bench/harness/schema-tax
 | Chrome DevTools MCP                      |    29 |         5,116 |
 | Reticle, `RETICLE_ADVERTISE_ALL_TOOLS=1` |    48 |       ~30,200 |
 
+_Measured 2026-08-12 (`bench/raw/schema-tax.json`). Reticle's default surface has gained a tool since, so treat the first row as a floor._
+
 There is one tool surface: the verify loop advertised directly, plus two meta-tools (`reticle_tools`, `reticle_run`) that reach every other tool on demand. Nothing is unreachable; the cold tail simply is not re-sent every turn.
 
-`RETICLE_ADVERTISE_ALL_TOOLS=1` advertises everything WITH output schemas. It is a verification switch for suites that call by name, not a mode to run agents in. It is roughly 7x the per-turn cost, which is why it is opt-in: measured, carrying output schemas on the default surface takes it from 18,183 to 41,117 bytes. (That 18,183 was taken when the surface was 16 tools; a fresh `tools/list` read on 2026-08-14 puts the current 18-tool surface at **21,468 bytes**, and all 48 with output schemas at **134,368**. The shape of the gap holds; the absolute numbers move every time a tool is added, which is why they are asserted in `surface-sizes.test.ts` rather than trusted from prose.)
+`RETICLE_ADVERTISE_ALL_TOOLS=1` advertises everything WITH output schemas. It is a verification switch for suites that call by name, not a mode to run agents in. It is roughly 7x the per-turn cost, which is why it is opt-in.
+
+**Every absolute number in this section is a dated reading, not a current value.** The table above was measured on 2026-08-12; a later `tools/list` read on 2026-08-14 put the default surface at 21,468 bytes and the full one at 134,368. The surface has grown a tool since, so both readings are already low. The _shape_ of the gap is the durable claim; the counts themselves are asserted by `surface-sizes.test.ts`, which reads them off the live surface, and that is the only place to trust them.
 
 The typed result object still travels as `structuredContent` either way; the default surface simply does not advertise the output schema, which an agent reading the `text` block never consumed.
 

package/docs/tools-act-and-wait.mdx

@@ -4,6 +4,8 @@ description: Act on an element and wait for a named consequence in one call. Thi
 icon: circle-check
 ---
 
+`reticle_act_and_wait` performs one action on an element and waits for a named consequence, returning a verdict in the same call. Reach for it whenever an action is supposed to cause something: it is one of only two Reticle tools that produce a verdict, the other being [`reticle_assert`](/tools-assert).
+
 This is the tool Reticle exists for. It does the act, observe and assert steps in one round trip, and it makes you name the expected consequence **before** the action runs.
 
 That ordering is not a convenience. An agent that acts first and then decides what counts as success will always find something that counts. Naming the consequence up front is the difference between a check and a rationalisation.
@@ -12,13 +14,13 @@ That ordering is not a convenience. An agent that acts first and then decides wh
 
 ```json
 {
-  "ref": "e5",
+  "ref": "e105",
   "action": "click",
   "until": { "kind": "net", "method": "POST" }
 }
 ```
 
-Real response, trimmed:
+Real response. The `initiatorStack`, `storageDiffs` and per-event trace detail are trimmed out for length; nothing else is changed:
 
 ```json
 {
@@ -27,35 +29,73 @@ Real response, trimmed:
   "because": "assertion held at presence grade over a clean capture with no channel disagreeing",
   "effect": {
     "ok": true,
+    "ref": "e105",
+    "action": "click",
+    "dispatched": true,
+    "settled": true,
+    "settleReason": null,
     "testid": "login-submit",
     "component": "Login",
-    "effect": { "domMutatedWithin": 7, "appeared": "Signing in…" },
+    "role": "button",
+    "name": "Sign in",
+    "effect": { "focusMoved": "e104->null", "domMutatedWithin": 8, "appeared": "Signing in…" },
     "source": { "file": "src/components/Login.tsx", "line": 81, "column": 8 }
   },
   "verdict": {
     "pass": true,
     "evidence": {
+      "id": "n2",
       "method": "POST",
       "url": "http://localhost:8787/api/login",
       "status": 200,
-      "durationMs": 67,
-      "requestBody": "{\"email\":\"admin@reticle.dev\",\"password\":\"[REDACTED]\"}"
+      "ok": true,
+      "durationMs": 4,
+      "initiator": "fetch",
+      "statusText": "OK",
+      "contentType": "application/json; charset=utf-8",
+      "responseSize": 67,
+      "requestBody": "{\"email\":\"admin@reticle.dev\",\"password\":\"[REDACTED]\"}",
+      "responseBody": "{\"token\":\"[REDACTED]\",\"user\":{\"email\":\"admin@reticle.dev\"}}"
+    }
+  },
+  "trace": {
+    "window_ms": 31,
+    "summary": {
+      "total": 21,
+      "network": 1,
+      "domAdded": 0,
+      "domRemoved": 1,
+      "domChanged": 6,
+      "routeChanges": 0,
+      "consoleErrors": 0,
+      "animations": 0,
+      "signals": 1
     }
   },
   "summary": {
     "net": { "total": 1, "errors": 0 },
     "consoleErrors": 0,
-    "stateDiffs": [{ "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}" }],
-    "signals": ["auth:granted"]
+    "statePathsChanged": ["app"],
+    "storageKeysChanged": ["reticle.bench.authToken", "reticle.bench.sessionId"],
+    "stateDiffs": [
+      { "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}", "atMs": 44403 }
+    ],
+    "signals": ["auth:granted"],
+    "layoutShift": 0.016486682891845704,
+    "longTasks": 0
   },
   "honesty": {
     "grade": "presence",
+    "attribution": "window",
     "coverage": { "pct": 100, "partial": false },
     "integrity": { "clean": true, "issues": [] }
-  }
+  },
+  "since": 44395
 }
 ```
 
+`trace` is a digest of what the app did in the window. When the counts are not enough, pass the top-level `since` cursor to [`reticle_observe`](/tools-observe) for the per-event timeline.
+
 ## The predicate grammar
 
 `until` takes `{ kind, ...fields }`. The kinds:
@@ -115,9 +155,19 @@ A verification tool that cannot describe the quality of its own evidence is aski
 
 ## Arguments
 
-| Argument                | What it does                             |
-| ----------------------- | ---------------------------------------- |
-| `ref`, `action`, `args` | As [`reticle_act`](/tools-act)           |
-| `until`                 | The predicate to wait for                |
-| `timeout_ms`            | Maximum wait                             |
-| `refuseWhenThrottled`   | Throw rather than act on a throttled tab |
+| Argument | What it does |
+| --- | --- |
+| `ref`, `action`, `args` | As [`reticle_act`](/tools-act) |
+| `until` | The predicate to wait for. Omit it to wait for the page to settle |
+| `predicate` | Alias for `until`, the name `assert` and `wait_for` use |
+| `timeout_ms` | Maximum wait, defaulting to 4000. `0` evaluates the predicate once, no wait |
+| `refuseWhenThrottled` | Throw rather than act on a throttled tab |
+
+Omitting `until` waits for network and DOM idle, which is the deterministic replacement for a fixed sleep. To assert a consequence **and** settle, combine them:
+
+```json
+{
+  "kind": "allOf",
+  "predicates": [{ "kind": "signal", "name": "deploy:created" }, { "kind": "settled" }]
+}
+```

package/docs/tools-act-sequence.mdx

@@ -4,6 +4,8 @@ description: Run several actions in order in one round trip. Fill, fill, submit.
 icon: layer-group
 ---
 
+`reticle_act_sequence` runs several actions in order in a single round trip. Reach for it whenever a journey needs more than one step, such as fill, fill, submit, and then prove the outcome once with [`reticle_act_and_wait`](/tools-act-and-wait), because a sequence itself produces no verdict.
+
 A login is three actions. Driving it one call at a time costs three round trips and three turns of context. `reticle_act_sequence` does it in one.
 
 This tool exists because of a measured problem: agents were driving forms one call at a time, over and over. Those repeats were not retries. The calls succeeded and got repeated, because the batching tool was not advertised and so nobody knew it was there.
@@ -13,18 +15,18 @@ This tool exists because of a measured problem: agents were driving forms one ca
 ```json
 {
   "steps": [
-    { "ref": "e101", "action": "fill", "args": { "value": "admin@reticle.dev" } },
-    { "ref": "e102", "action": "fill", "args": { "value": "correct-horse-battery-staple" } },
-    { "ref": "e103", "action": "click" }
+    { "ref": "e603", "action": "fill", "args": { "value": "admin@reticle.dev" } },
+    { "ref": "e604", "action": "fill", "args": { "value": "correct-horse-battery-staple" } },
+    { "ref": "e605", "action": "click" }
   ]
 }
 ```
 
-Real response, trimmed:
+Real response. Each `effects[]` entry also carries `targetMatched`, `visible`, `enabled`, `defaultPrevented`, `occluded`, `occludedBy` and `scrolledIntoView`, and each `steps[]` entry also carries `dispatched`, `settled`, `settleReason`, `component`, `role` and `name`. Those are trimmed here for length:
 
 ```json
 {
-  "since": 13776,
+  "since": 3915,
   "dispatched": true,
   "result": {
     "ok": true,
@@ -32,38 +34,38 @@ Real response, trimmed:
     "effects": [
       {
         "dispatched": true,
-        "focusMoved": "null->e101",
+        "focusMoved": "null->e603",
         "valueChanged": false,
-        "domMutatedWithin": 6
+        "domMutatedWithin": 0
       },
       {
         "dispatched": true,
-        "focusMoved": "e101->e102",
+        "focusMoved": "e603->e604",
         "valueChanged": true,
-        "domMutatedWithin": 10
+        "domMutatedWithin": 9
       },
       {
         "dispatched": true,
-        "focusMoved": "e102->null",
+        "focusMoved": "e604->null",
         "domMutatedWithin": 15,
         "appeared": "Signing in… | Invalid email or password | Sign in"
       }
     ],
     "steps": [
       {
-        "ref": "e101",
+        "ref": "e603",
         "action": "fill",
         "testid": "login-email",
         "source": { "file": "src/components/Login.tsx", "line": 48 }
       },
       {
-        "ref": "e102",
+        "ref": "e604",
         "action": "fill",
         "testid": "login-password",
         "source": { "file": "src/components/Login.tsx", "line": 59 }
       },
       {
-        "ref": "e103",
+        "ref": "e605",
         "action": "click",
         "testid": "login-submit",
         "source": { "file": "src/components/Login.tsx", "line": 81 }
@@ -95,8 +97,8 @@ The honest pattern is: batch the setup, prove the outcome.
 ```json
 {
   "steps": [
-    { "ref": "e101", "action": "fill", "args": { "value": "admin@reticle.dev" } },
-    { "ref": "e102", "action": "fill", "args": { "value": "reticle" } }
+    { "ref": "e603", "action": "fill", "args": { "value": "admin@reticle.dev" } },
+    { "ref": "e604", "action": "fill", "args": { "value": "correct-password" } }
   ]
 }
 ```
@@ -104,10 +106,25 @@ The honest pattern is: batch the setup, prove the outcome.
 then
 
 ```json
-{ "ref": "e103", "action": "click", "until": { "kind": "signal", "name": "auth:granted" } }
+{ "ref": "e605", "action": "click", "until": { "kind": "signal", "name": "auth:granted" } }
+```
+
+which returns the verdict the sequence could not:
+
+```json
+{
+  "verified": "yes",
+  "verifiedReason": "proved",
+  "because": "assertion held at signal grade over a clean capture with no channel disagreeing",
+  "verdict": {
+    "pass": true,
+    "evidence": { "name": "auth:granted", "data": { "email": "admin@reticle.dev" } }
+  },
+  "honesty": { "grade": "signal", "coverage": { "pct": 100, "partial": false } }
+}
 ```
 
-Two calls instead of four, and the last one returns a verdict.
+Two calls instead of four, and the last one returns a verdict. Note `grade: "signal"`, the strongest Reticle awards, because the app said so itself.
 
 ## What each step reports