@reticlehq/server 2.6.0 → 2.8.0

package/docs/telemetry.md

@@ -1,18 +1,22 @@
-# Telemetry
+---
+title: Telemetry
+description: 'The complete description of the anonymous usage data Reticle collects, what it is for, and how to turn it off.'
+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 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.
 
 This page is the complete description of what is collected. If something is not listed here, it is not sent.
 
 ## The short version
 
 - **Anonymous.** We cannot tell who you are, and we do not try.
-- **No code, no app data.** Nothing from the app under test — no DOM, no network traffic, no console output, no source, no file paths — ever leaves your machine.
+- **No code, no app data.** Nothing from the app under test (no DOM, no network traffic, no console output, no source, no file paths) ever leaves your machine.
 - **The one exception is feedback you deliberately send us**, and it is never collected passively. See [Feedback](#feedback) below.
 - **Opt out any time**, permanently, with one command:
 
   ```bash
-  reticle telemetry disable
+  npx @reticlehq/server telemetry disable
   ```
 
 ## What is sent
@@ -21,42 +25,51 @@ Thirteen kinds of events, each a single small JSON object:
 
 | Event | When | Extra data |
 | --- | --- | --- |
-| `reticle_installed` | The first time Reticle runs on a machine | — |
+| `reticle_installed` | The first time Reticle runs on a machine | n/a |
 | `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 | — |
-| `daemon_stopped` | The local daemon stops | A summary of the session — see below |
-| `verification_completed` | A verification produces a verdict | Whether it passed, and whether Reticle refused to call a passing check verified |
-| `project_profiled` | Once per daemon start | The shape of the project — see below |
+| `daemon_started` | The local daemon starts | n/a |
+| `daemon_stopped` | The local daemon stops | A summary of the session; see below |
+| `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 |
+| `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 |
-| `init_completed` | `reticle init` finishes | Whether it worked, and a classified reason when it did not |
-| `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 |
-| `feedback_submitted` | **Only** when you or your agent explicitly send feedback | The report — see [Feedback](#feedback). The AGENT's call does not wait for the network: the receipt says `accepted` (validated, redacted, queued), never `sent`, and a delivery that then fails is reported back on the agent's next tool result. `reticle feedback` typed by a human still waits, because a person at a terminal is owed the real answer |
-| `identified` | **Only** when you run `reticle identify` | What you chose to tell us — see [Telling us who you are](#telling-us-who-you-are) |
+| `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 |
+| `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 |
+| `feedback_submitted` | **Only** when you or your agent explicitly send feedback | The report; see [Feedback](#feedback). The AGENT's call does not wait for the network: the receipt says `accepted` (validated, redacted, queued), never `sent`, and a delivery that then fails is reported back on the agent's next tool result. `reticle feedback` typed by a human still waits, because a person at a terminal is owed the real answer |
+| `identified` | **Only** when you run `reticle identify` | What you chose to tell us; see [Telling us who you are](#telling-us-who-you-are) |
 
-**There is no per-tool-call event.** Tool usage is counted in memory and leaves once, inside `daemon_stopped`, as a histogram like `{"reticle_act": 40, "reticle_assert": 12}`. That is counts of tool NAMES from a fixed list we define — never arguments, results, selectors, or URLs.
+**There is no per-tool-call event.** Tool usage is counted in memory and leaves once, inside `daemon_stopped`, as a histogram like `{"reticle_act": 40, "reticle_assert": 12}`. That is counts of tool NAMES from a fixed list we define, never arguments, results, selectors, or URLs.
 
-**Parameter and flag NAMES are collected; their VALUES are not.** We record that `reticle_act` was called with `ref` and `action`, and that you ran `reticle serve --headed --port`. We do not record what you set them to. This distinction is the whole safety property, and it is absolute for CLI flags: `--http-token` holds a secret, `--drive` holds a URL, `--storage-state` holds a file path, so no flag value is ever sent. For tool parameters there is one narrow exception — a short, explicit allowlist of parameters whose values are enums _we_ defined (`action: "click"`), listed in [`argument-shape.ts`](../packages/server/src/telemetry/argument-shape.ts). A value outside that allowlist reports as `other`, so a future schema change cannot quietly start forwarding free text. `reticle_act`'s `args` — the text being typed into your app, which on a login form is a password — is **never** in that allowlist.
+**Parameter and flag NAMES are collected; their VALUES are not.** We record that `reticle_act` was called with `ref` and `action`, and that you ran `reticle serve --headed --port`. We do not record what you set them to. This distinction is the whole safety property, and it is absolute for CLI flags: `--http-token` holds a secret, `--drive` holds a URL, `--storage-state` holds a file path, so no flag value is ever sent. For tool parameters there is one narrow exception: a short, explicit allowlist of parameters whose values are enums _we_ defined (`action: "click"`), listed in [`argument-shape.ts`](../packages/server/src/telemetry/argument-shape.ts). A value outside that allowlist reports as `other`, so a future schema change cannot quietly start forwarding free text. `reticle_act`'s `args` (the text being typed into your app, which on a login form is a password) is **never** in that allowlist.
 
 `daemon_stopped` carries: how long the session ran, how many tool calls and of which tools, how long each tool took (total and worst case), how many failed, how many verifications ran, browser/lease connection attempts with their failure causes, and which MCP clients connected (`claude-code`, `cursor`).
 
-It also carries a snapshot of the **machine's** state — our own process's memory, free and total system RAM, load average and CPU count — taken at shutdown and again on any crash. This is what separates "your machine ran out of memory" from "Reticle has a bug", which otherwise produce identical-looking failures. No hostname, no username, no paths, no process list.
+It also carries a snapshot of the **machine's** state (our own process's memory, free and total system RAM, load average and CPU count), taken at shutdown and again on any crash. This is what separates "your machine ran out of memory" from "Reticle has a bug", which otherwise produce identical-looking failures. No hostname, no username, no paths, no process list.
+
+### 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`.
+
+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.
+
+When the clause is `unclean_capture`, one further name says which of our three losses caused it: `buffer_loss` (our server's event buffer), `transport_gap` (our browser-side queue), `blind_spot` (a boundary in the page, such as a cross-origin frame), or `other`. All four are facts about **Reticle's** ability to observe, not about what it observed. This field is how we found that Reticle was refusing to answer over windows that were completely intact.
 
 ### Bugs Reticle finds
 
-When Reticle catches a defect in the app it is verifying, it records **that a class of defect was found** — never what it was found in. The event carries the kind (`signal-contradicted`, `duplicate-request`, `console-error`, …) and how it surfaced, and nothing else: no selector, no URL, no element, no description of your app or its behaviour.
+When Reticle catches a defect in the app it is verifying, it records **that a class of defect was found**, never what it was found in. The event carries the kind (`signal-contradicted`, `duplicate-request`, `console-error`, …) and how it surfaced, and nothing else: no selector, no URL, no element, no description of your app or its behaviour.
 
-This is the number we use to say whether Reticle works at all, and the one we would publish. It is counted conservatively on purpose — a defect explained by a contradiction is not also counted as a failed assertion, because an inflated number would be worse than none.
+This is the number we use to say whether Reticle works at all, and the one we would publish. It is counted conservatively on purpose: a defect explained by a contradiction is not also counted as a failed assertion, because an inflated number would be worse than none.
 
 ### Errors and crashes
 
-The SDK that runs inside your page reports its own failures too — an observer that could not start, a patch that would not install. It does this over the **local bridge it is already connected to**; the SDK still makes no outbound request of its own, and the daemon decides what (if anything) is reported onward. What travels is our module name (`network_observer`), the error type, and the message with variables stripped — never your page's URL, and never anything from your app.
+The SDK that runs inside your page reports its own failures too: an observer that could not start, a patch that would not install. It does this over the **local bridge it is already connected to**; the SDK still makes no outbound request of its own, and the daemon decides what (if anything) is reported onward. What travels is our module name (`network_observer`), the error type, and the message with variables stripped, never your page's URL, and never anything from your app.
 
-Errors are grouped by a **hash of the error's shape**, with every variable part removed first — so `no baseline named 'checkout-v3'` and `no baseline named 'login'` become one anonymous group and neither flow name is sent. Alongside the hash we send that stripped shape (`no baseline named *`) and the tool that produced it, because a hash on its own can be counted but never understood.
+Errors are grouped by a **hash of the error's shape**, with every variable part removed first, so `no baseline named 'checkout-v3'` and `no baseline named 'login'` become one anonymous group and neither flow name is sent. Alongside the hash we send that stripped shape (`no baseline named *`) and the tool that produced it, because a hash on its own can be counted but never understood.
 
-A crash additionally carries **Reticle's own stack frames** — `resolveAnchor@act-tools.js:142` — plus the tool that was running, the preceding tool names, and the Node version and CPU architecture. Those frames are our published npm code, readable by anyone who unpacks the tarball.
+A crash additionally carries **Reticle's own stack frames** (`resolveAnchor@act-tools.js:142`), plus the tool that was running, the preceding tool names, and the Node version and CPU architecture. Those frames are our published npm code, readable by anyone who unpacks the tarball.
 
 **Stack frames belonging to your application are dropped entirely**, along with node internals. In the example below only the two Reticle frames survive; your file, your function, and your home directory do not:
 
@@ -65,11 +78,11 @@ at doCheckout (/Users/ada/secret-app/src/checkout.tsx:42:9)   ← dropped
 at resolveAnchor (…/@reticlehq/server/dist/tools/act-tools.js:142:19)   ← sent
 ```
 
-**One narrow exception, for the crash that otherwise says nothing.** A refused connection — `connect ECONNREFUSED` — has a stack that is _entirely_ node internals, so the rule above correctly keeps nothing and the report arrives with no location at all. Those crashes now also carry the failing **syscall** (`connect`), the **errno** (`ECONNREFUSED`), whether the target was **loopback** (one boolean), whether the port was **one of Reticle's own** (the enum `reticle` / `other`), and the innermost frame naming **Node's own source** (`node:net:1637`).
+**One narrow exception, for the crash that otherwise says nothing.** A refused connection (`connect ECONNREFUSED`) has a stack that is _entirely_ node internals, so the rule above correctly keeps nothing and the report arrives with no location at all. Those crashes now also carry the failing **syscall** (`connect`), the **errno** (`ECONNREFUSED`), whether the target was **loopback** (one boolean), whether the port was **one of Reticle's own** (the enum `reticle` / `other`), and the innermost frame naming **Node's own source** (`node:net:1637`).
 
-The address and the port number are used to compute those two answers and are then discarded — neither is ever sent. The Node frame is a line in Node's published source, not yours: it says a connect failed rather than a DNS lookup, and carries nothing about your machine, your app, or your directory layout. The frame is included **only** when the crash is a system error and no Reticle frame survived — the report that would otherwise be blind.
+The address and the port number are used to compute those two answers and are then discarded; neither is ever sent. The Node frame is a line in Node's published source, not yours: it says a connect failed rather than a DNS lookup, and carries nothing about your machine, your app, or your directory layout. The frame is included **only** when the crash is a system error and no Reticle frame survived: the report that would otherwise be blind.
 
-`project_profiled` carries: the framework and its major version, a size **bucket** (`tiny` … `huge`, never a file count), whether it is a monorepo, its age in whole **weeks**, how many saved flows/baselines/runs exist, and which Reticle feature families have been used. It also carries whether the project has git at all, whether it has ever been pushed (`none` / `local_only` / `remote`), and which forge hosts it — `github`, `gitlab`, `bitbucket`, `azure`, `sourcehut`, `codeberg`, or just `self_hosted` for anything else. A private git host is usually `git.<company>.com`, so self-hosted repos report **only** that they are self-hosted, never the hostname.
+`project_profiled` carries: the framework and its major version, a size **bucket** (`tiny` … `huge`, never a file count), whether it is a monorepo, its age in whole **weeks**, how many saved flows/baselines/runs exist, and which Reticle feature families have been used. It also carries whether the project has git at all, whether it has ever been pushed (`none` / `local_only` / `remote`), and which forge hosts it: `github`, `gitlab`, `bitbucket`, `azure`, `sourcehut`, `codeberg`, or just `self_hosted` for anything else. A private git host is usually `git.<company>.com`, so self-hosted repos report **only** that they are self-hosted, never the hostname.
 
 This is how we learn whether people are getting value from the whole product or only a corner of it. No file names, no paths, no flow names, no dependency list.
 
@@ -78,13 +91,13 @@ Every event carries the same few fields:
 | Field | What it is | What it is not |
 | --- | --- | --- |
 | `anonymousId` | A random UUID minted locally on first run, stored at `~/.reticle/telemetry-id` | Not derived from your name, email, hardware, or anything else about you |
-| `projectId` | A one-way SHA-256 hash of the git origin URL, or of the directory path outside a repo | Not reversible — we can count _distinct_ projects, but not learn any project's name, URL, or location. Hashing the origin means one repo counts once instead of once per teammate and per clone |
-| `actor` | Whether a person or an agent caused this — a typed `reticle` command is a person, an MCP tool call is the agent | Not a claim about _why_. Whether you asked your agent to verify, or it decided to, lives in a prompt Reticle never sees, and we do not guess |
-| `sessionId` | A random id for this daemon run, held in memory and never written to disk | Not a device id and not persistent — a restarted daemon gets a new one. It only groups one run's own events together |
-| `projectIdSource` | Whether `projectId` came from a shared git origin or from the local directory path | Not the origin or the path. It exists so we can tell when "how many people share this project" is a real measurement — outside a pushed repo there is nothing shared to hash, so those rows always show one user |
-| `version` | The Reticle version running | — |
+| `projectId` | A one-way SHA-256 hash of the git origin URL, or of the directory path outside a repo | Not reversible: we can count _distinct_ projects, but not learn any project's name, URL, or location. Hashing the origin means one repo counts once instead of once per teammate and per clone |
+| `actor` | Whether a person or an agent caused this: a typed `reticle` command is a person, an MCP tool call is the agent | Not a claim about _why_. Whether you asked your agent to verify, or it decided to, lives in a prompt Reticle never sees, and we do not guess |
+| `sessionId` | A random id for this daemon run, held in memory and never written to disk | Not a device id and not persistent: a restarted daemon gets a new one. It only groups one run's own events together |
+| `projectIdSource` | Whether `projectId` came from a shared git origin or from the local directory path | Not the origin or the path. It exists so we can tell when "how many people share this project" is a real measurement. Outside a pushed repo there is nothing shared to hash, so those rows always show one user |
+| `version` | The Reticle version running | n/a |
 | `os` | The platform (`darwin` / `linux` / `win32`) | Not the OS version, hostname, or hardware |
-| `ci` | Whether the run is inside CI | — |
+| `ci` | Whether the run is inside CI | n/a |
 
 There are no IP-based profiles, no cookies, no fingerprinting, and no person profiles: events are processed in "personless" mode, so they are never joined into an identity.
 
@@ -100,23 +113,23 @@ A few of these are worth being explicit about, because they are the ones a produ
 
 ## Feedback
 
-Reticle verifies apps for AI agents, and for a long time it had no way to hear when it got something wrong. An agent would hit a tool that misbehaved, work around it, and that knowledge would vanish at the end of the turn. The feedback channel is the fix — and because it is the only part of Reticle that transmits words someone wrote, it gets stricter rules than everything above.
+Reticle verifies apps for AI agents, and for a long time it had no way to hear when it got something wrong. An agent would hit a tool that misbehaved, work around it, and that knowledge would vanish at the end of the turn. The feedback channel is the fix, and because it is the only part of Reticle that transmits words someone wrote, it gets stricter rules than everything above.
 
 **It is never passive.** There is no code path that sends feedback on its own. A `feedback` event exists only because one of these happened:
 
 | Who | How | What it carries |
 | --- | --- | --- |
-| Your agent | Calls the `reticle_feedback` MCP tool — after a failure, **or to ask for a feature** | What it wrote: an analysis, or a request with the goal behind it, what would improve, and how it works around the gap today. Plus the model it is running, which it tells us because MCP cannot |
-| You | Run `reticle feedback [--rating 1-5] [--bug] "your words"` | Your words and your rating |
-| Your agent, before Reticle works | Runs `reticle feedback --agent --kind <bug\|gap\|ambiguity\|feature_request\|improvement> "what happened"` | The same words, filed from the shell. This exists for the phase where there is no daemon and no MCP tools — a failed `init`, half-finished wiring — which is the failure we are otherwise never told about |
+| Your agent | Calls the `reticle_feedback` MCP tool (after a failure, **or to ask for a feature**) | What it wrote: an analysis, or a request with the goal behind it, what would improve, and how it works around the gap today. Plus the model it is running, which it tells us because MCP cannot |
+| You | Run `npx @reticlehq/server feedback [--rating 1-5] [--bug] "your words"` | Your words and your rating |
+| Your agent, before Reticle works | Runs `reticle feedback --agent --kind <bug\|gap\|ambiguity\|feature_request\|improvement> "what happened"` | The same words, filed from the shell. This exists for the phase where there is no daemon and no MCP tools (a failed `init`, half-finished wiring), which is the failure we are otherwise never told about |
 
-Agents are instructed, in the tool description itself, never to include app source, secrets, or user data — to describe the failure in their own words instead.
+Agents are instructed, in the tool description itself, never to include app source, secrets, or user data, and to describe the failure in their own words instead.
 
-**It is redacted before it leaves your machine.** Emails, credentials in URLs, `Authorization` headers and API-key assignments, recognizable vendor tokens (`sk-…`, `ghp_…`, `AKIA…`, `xoxb-…`, JWTs), and home-directory paths are stripped and replaced with `[redacted]`. This runs client-side, in [`feedback.ts`](../packages/server/src/telemetry/feedback.ts), so you can read exactly what it removes rather than take our word for it. It is a safety net, not a guarantee — it cannot catch a secret that looks like an ordinary sentence, which is why the instruction above comes first.
+**It is redacted before it leaves your machine.** Emails, credentials in URLs, `Authorization` headers and API-key assignments, recognizable vendor tokens (`sk-…`, `ghp_…`, `AKIA…`, `xoxb-…`, JWTs), and home-directory paths are stripped and replaced with `[redacted]`. This runs client-side, in [`feedback.ts`](../packages/server/src/telemetry/feedback.ts), so you can read exactly what it removes rather than take our word for it. It is a safety net, not a guarantee: it cannot catch a secret that looks like an ordinary sentence, which is why the instruction above comes first.
 
 **It shows you what it sends.** `reticle feedback` prints the exact payload before transmitting, and names any redaction rule that fired.
 
-Alongside the report, a feedback event carries context about the environment it came from — never about you:
+Alongside the report, a feedback event carries context about the environment it came from, never about you:
 
 | Field | Example | Why |
 | --- | --- | --- |
@@ -136,26 +149,26 @@ Plus the `version`, `os`, and `ci` fields every event carries. No paths, no proj
 RETICLE_FEEDBACK=0
 ```
 
-Every switch in [Your choices](#your-choices) disables feedback too. If telemetry is off, feedback is off — and `reticle feedback` will tell you so rather than silently discard what you wrote.
+Every switch in [Your choices](#your-choices) disables feedback too. If telemetry is off, feedback is off, and `reticle feedback` will tell you so rather than silently discard what you wrote.
 
 ## Telling us who you are
 
-Everything above is anonymous, and stays that way unless you decide otherwise. If you want us to know who you are — to get support, to ask about an enterprise licence, or to be a design partner — there is one command, and running it is the only way it ever happens:
+Everything above is anonymous, and stays that way unless you decide otherwise. If you want us to know who you are (to get support, to ask about an enterprise licence, or to be a design partner), there is one command, and running it is the only way it ever happens:
 
 ```bash
-reticle identify --context company --company "Acme" --email you@acme.com
+npx @reticlehq/server identify --context company --company "Acme" --email you@acme.com
 ```
 
 `--context` is the only required part, and `company | side_project | open_source | learning` is the whole vocabulary. You can say "this is a company" without naming it, or name it without leaving an email.
 
 Before it sends anything, it prints what it will send and one thing worth reading carefully: **the identity is linked to this machine's anonymous id, so identifying yourself also connects the anonymous usage already recorded from this machine to what you enter.** That is what makes it useful to us, and it is why you are told before choosing rather than after.
 
-**One place mentions it to you.** After you send feedback as a human — never as an agent, and never if you have already identified or already declined — the receipt prints one line offering this command, because a bug report we cannot reply to is a conversation that ends after one sentence. Your feedback has already been sent by then: the line is an offer, not a question, and nothing is gated on it. **No address is ever attached to the feedback itself** — it would put personal data on the anonymous stream, which is exactly what the rest of this page promises not to do.
+**One place mentions it to you.** After you send feedback as a human (never as an agent, and never if you have already identified or already declined), the receipt prints one line offering this command, because a bug report we cannot reply to is a conversation that ends after one sentence. Your feedback has already been sent by then: the line is an offer, not a question, and nothing is gated on it. **No address is ever attached to the feedback itself**: it would put personal data on the anonymous stream, which is exactly what the rest of this page promises not to do.
 
 To undo it:
 
 ```bash
-reticle identify --forget
+npx @reticlehq/server identify --forget
 ```
 
 That deletes the local file and stops any further sends. To have what was already sent removed, email support@reticlehq.com.
@@ -166,10 +179,10 @@ Events are sent over HTTPS to [PostHog](https://posthog.com) (US cloud), a produ
 
 ## Your choices
 
-Telemetry is on by default and Reticle tells you so the first time it runs — once, in one line, with a pointer to this page. To see the current state at any time:
+Telemetry is on by default and Reticle tells you so the first time it runs: once, in one line, with a pointer to this page. To see the current state at any time:
 
 ```bash
-reticle telemetry status
+npx @reticlehq/server telemetry status
 ```
 
 Three ways to opt out, in whatever form fits your setup:
@@ -177,15 +190,15 @@ Three ways to opt out, in whatever form fits your setup:
 | Method | Scope |
 | --- | --- |
 | `reticle telemetry disable` | This machine, permanently (until `reticle telemetry enable`) |
-| `RETICLE_TELEMETRY=0` | Wherever the variable is set — handy for CI or a fleet-wide profile |
-| `DO_NOT_TRACK=1` | The [cross-tool convention](https://consoledonottrack.com) — Reticle honors it |
+| `RETICLE_TELEMETRY=0` | Wherever the variable is set; handy for CI or a fleet-wide profile |
+| `DO_NOT_TRACK=1` | The [cross-tool convention](https://consoledonottrack.com), which Reticle honors |
 
-Opting out changes nothing about how Reticle works. A failed or blocked telemetry send never delays, alters, or fails a command either — sends are best-effort and asynchronous by design.
+Opting out changes nothing about how Reticle works. A failed or blocked telemetry send never delays, alters, or fails a command either; sends are best-effort and asynchronous by design.
 
 To also remove the locally stored random id, delete `~/.reticle/telemetry-id`.
 
 ## A note on data protection
 
-The data described above is designed not to identify you: the only identifier is a locally minted random UUID, the project reference is a one-way hash, and no personal data is collected. We collect it on the basis of our legitimate interest in understanding and improving Reticle, we minimize what is collected to the fields listed here, and we honor every opt-out signal above. If you believe something in this design falls short of that intent, please open an issue — that is a bug, and we will treat it as one.
+The data described above is designed not to identify you: the only identifier is a locally minted random UUID, the project reference is a one-way hash, and no personal data is collected. We collect it on the basis of our legitimate interest in understanding and improving Reticle, we minimize what is collected to the fields listed here, and we honor every opt-out signal above. If you believe something in this design falls short of that intent, please open an issue. That is a bug, and we will treat it as one.
 
 Any change to what is collected will be listed on this page and called out in the release notes of the version that introduces it.

package/docs/testing.md

@@ -1,6 +1,10 @@
-# Testing with `@reticlehq/test` — declarative, signal-bound specs
+---
+title: Specs for CI
+description: 'Turn an interactive drive into a repeatable suite with @reticlehq/test: declarative specs bound to signals, never DOM structure.'
+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.
+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.
 
 ```ts
 import { reticleTest } from '@reticlehq/test';
@@ -20,7 +24,7 @@ reticleTest('ai chat edit', async (t) => {
 
 ## The test context `t`
 
-A thin, typed façade over Reticle's tools — it resolves testids → refs for you, so specs never touch refs or DOM:
+A thin, typed façade over Reticle's tools. It resolves testids → refs for you, so specs never touch refs or DOM:
 
 | Method | What it does |
 | --- | --- |
@@ -40,7 +44,7 @@ Any failed matcher throws with the structured evidence (near-miss, failure reaso
 ## Deterministic + honest
 
 - **`t.clock`** bakes `reticle_clock` into the spec, so time-gated UI (a 5s auto-dismiss, a 500ms hover dwell) is tested deterministically instead of racing real timers.
-- **`t.expectInputModeReal()`** — a hover/drag spec asserts native input is active; if it's running synthetic (no CDP), the spec is **skipped with a reason**, never silently passing on a no-op. Enable real input headless with `reticle drive` (see [usage §18](usage.md#18-real-input-mode--native-hover--drag)).
+- **`t.expectInputModeReal()`**: a hover/drag spec asserts native input is active; if it's running synthetic (no CDP), the spec is **skipped with a reason**, never silently passing on a no-op. Enable real input headless with `reticle drive` (see [usage §18](usage.md#18-real-input-mode-native-hover--drag)).
 
 ## Run a suite (headless, the same path CI uses)
 
@@ -70,7 +74,7 @@ import { toJUnitXml, writeJUnit } from '@reticlehq/test';
 
 ## Flows become specs
 
-`.reticle/` flows (see [Flows](flows.md)) can be executed directly as specs — replayed with their `expect`/`success` predicates and skipping `dynamic` (LLM-output) regions — so the recorded map and the suite can't drift apart:
+`.reticle/` flows (see [Flows](flows.md)) can be executed directly as specs, replayed with their `expect`/`success` predicates and skipping `dynamic` (LLM-output) regions, so the recorded map and the suite can't drift apart:
 
 ```ts
 import { flowsAsSpecs } from '@reticlehq/test';
@@ -79,4 +83,4 @@ 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.
+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.

package/docs/token-efficiency.md

@@ -1,24 +1,28 @@
-# Token efficiency: Reticle vs. a full-tree snapshot (Playwright MCP)
+---
+title: Token efficiency
+description: Why asking narrow questions costs a fraction of feeding the whole accessibility tree to the model every step.
+icon: coins
+---
 
 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)
 
-Measured against the bench dashboard (`apps/bench-app`) **with a 1,000-item list rendered**, after login. Token estimate = characters ÷ 4. Reproduce with the benchmark harness — see `bench/README.md`.
+Measured against the bench dashboard (`apps/bench-app`) **with a 1,000-item list rendered**, after login. Token estimate = characters ÷ 4. Reproduce with the benchmark harness; see `bench/README.md`.
 
-| Payload                                                                        |     Tokens |
-| ------------------------------------------------------------------------------ | ---------: |
-| **Playwright MCP** — with-refs snapshot (the real payload it sends every step) | **~7,300** |
-| Playwright MCP — bare accessibility tree (what we measured directly)           |     ~6,856 |
-| Reticle — `snapshot` `full` (whole page, incl. all 1,000 items)                |     ~4,144 |
-| Reticle — `snapshot` `interactive` (actionable elements only)                  |       ~110 |
-| Reticle — `snapshot` `status` (route / dialogs / counters)                     |        ~31 |
-| Reticle — `query` one element                                                  |        ~28 |
-| Reticle — `observe` (reaction after an action)                                 |        ~39 |
-| Reticle — `assert` verdict                                                     |        ~33 |
-| **Reticle — a full verify loop** (`query` + `observe` + `assert`)              |   **~100** |
+| Payload                                                                       |     Tokens |
+| ----------------------------------------------------------------------------- | ---------: |
+| **Playwright MCP**, with-refs snapshot (the real payload it sends every step) | **~7,300** |
+| Playwright MCP, bare accessibility tree (what we measured directly)           |     ~6,856 |
+| Reticle `snapshot` `full` (whole page, incl. all 1,000 items)                 |     ~4,144 |
+| Reticle `snapshot` `interactive` (actionable elements only)                   |       ~110 |
+| Reticle `snapshot` `status` (route / dialogs / counters)                      |        ~31 |
+| Reticle `query`, one element                                                  |        ~28 |
+| Reticle `observe` (reaction after an action)                                  |        ~39 |
+| Reticle `assert` verdict                                                      |        ~33 |
+| **Reticle, a full verify loop** (`query` + `observe` + `assert`)              |   **~100** |
 
-**Result on this page:** the common Reticle loop is **~73× leaner** than Playwright MCP's per-step snapshot (100 vs ~7,300 tokens). The bare a11y tree we measured directly is 6,856; Playwright MCP's actual payload adds a `[ref=…]` to every node, pushing it to ~7,300. On the complex pages Playwright's ecosystem cites (50k+), the gap widens to **~100–500×**.
+**Result on this page:** the common Reticle loop is **~73× leaner** than Playwright MCP's per-step snapshot (100 vs ~7,300 tokens). The bare a11y tree we measured directly is 6,856; Playwright MCP's actual payload adds a `[ref=…]` to every node, pushing it to ~7,300. On the complex pages Playwright's ecosystem cites (50k+), the gap widens to **~100× to 500×**.
 
 ## Diffed snapshots: pay once, then only for changes
 
@@ -32,26 +36,26 @@ Measured on a representative 150-row dashboard (the shipped regression benchmark
 | `diff:true` after a one-row change |    **60** |
 | `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 60–80K-token stale-context buildup that makes long-running agents start hallucinating selectors that no longer exist.
+**~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.
 
 Every `reticle_snapshot`/`reticle_query` result also carries `cost:{ bytes, tokens }` (estimated) so you can **re-scope before reading** a large body (`mode:interactive`/`status`, a tighter `scope`, or a narrower `query`) instead of paying for it first.
 
 ## The other tax: tool schemas, paid on every request
 
-Per-payload leanness is only half the token story. Before an agent reads a single result, it pays for the tool SCHEMAS injected into its context on every request — and this is the metric the field now organises around. A filed issue measures Playwright MCP's default tool list at 14.4k tokens = 7.2% of a Claude Code context window, and Microsoft's own README steers coding agents to the CLI over its MCP on exactly these grounds.
+Per-payload leanness is only half the token story. Before an agent reads a single result, it pays for the tool SCHEMAS injected into its context on every request, and this is the metric the field now organises around. A filed issue measures Playwright MCP's default tool list at 14.4k tokens = 7.2% of a Claude Code context window, and Microsoft's own README steers coding agents to the CLI over its MCP on exactly these grounds.
 
 Measured live, all servers in one run, same tokenizer (`bench/harness/schema-tax.mjs`):
 
-| MCP server                                | tools | schema tokens |
-| ----------------------------------------- | ----: | ------------: |
-| **Reticle — the tool surface**            |    17 |    **~4,500** |
-| Playwright MCP                            |    23 |         3,725 |
-| Chrome DevTools MCP                       |    29 |         5,116 |
-| Reticle — `RETICLE_ADVERTISE_ALL_TOOLS=1` |    48 |       ~32,000 |
+| MCP server                               | tools | schema tokens |
+| ---------------------------------------- | ----: | ------------: |
+| **Reticle, the tool surface**            |    18 |    **~4,930** |
+| Playwright MCP                           |    23 |         3,725 |
+| Chrome DevTools MCP                      |    29 |         5,116 |
+| Reticle, `RETICLE_ADVERTISE_ALL_TOOLS=1` |    48 |       ~30,200 |
 
 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 — 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.
+`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.)
 
 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.
 
@@ -60,7 +64,7 @@ The typed result object still travels as `structuredContent` either way; the def
 - **Full-tree vs full-tree, the gap is modest (~1.8×):** Reticle `full` (4,144) vs Playwright's with-refs snapshot (~7,300). Reticle collapses generic wrapper nodes, but both include every list item. If you force Reticle to dump the whole page each step, you don't save much.
 - **The savings come from _not needing_ the full tree.** Playwright MCP's primary perception primitive is "return the accessibility tree"; Reticle's is "answer a specific question" (`query`/`assert`/`observe`/scoped or interactive `snapshot`). The win is architectural, not a cleverer serializer.
 - **Cost scales with interactive elements + what you look at, not total DOM.** The 1,000 list items cost ~0 in `interactive` mode because they aren't interactive.
-- **This is tool-output tokens only.** The agent's own reasoning tokens dominate either way — which is the point: keep observation cheap so the budget goes to thinking.
+- **This is tool-output tokens only.** The agent's own reasoning tokens dominate either way, which is the point: keep observation cheap so the budget goes to thinking.
 
 ## Why it matters in practice
 
@@ -73,8 +77,8 @@ At scale (long flows, large dashboards, frequent re-runs for regression) that di
 
 ## Method & caveats
 
-- One page, one tool, char/4 token proxy — directional, not a benchmark suite. Absolute numbers vary by page; the _ratio_ is the point.
-- `_snapshotForAI()` (Playwright MCP's exact with-refs payload) was unavailable in the installed Playwright build, so we measured `body.ariaSnapshot()` — the same accessibility tree it serializes; the real MCP payload is equal or slightly larger (it adds `[ref=…]`).
+- One page, one tool, char/4 token proxy: directional, not a benchmark suite. Absolute numbers vary by page; the _ratio_ is the point.
+- `_snapshotForAI()` (Playwright MCP's exact with-refs payload) was unavailable in the installed Playwright build, so we measured `body.ariaSnapshot()`, the same accessibility tree it serializes; the real MCP payload is equal or slightly larger (it adds `[ref=…]`).
 - Playwright MCP is excellent and Microsoft-backed; this is not a knock on it. It optimizes for cross-browser _driving_; Reticle optimizes for cheap, in-app _verification_. They can coexist (drive with one, assert with the other).
 
 Run it yourself: the benchmark harness in `bench/` (see `bench/README.md`), with the demo + api running.

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

@@ -0,0 +1,123 @@
+---
+title: reticle_act_and_wait
+description: Act on an element and wait for a named consequence in one call. This is the tool that produces a verdict, and the one you should reach for by default.
+icon: circle-check
+---
+
+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.
+
+## Example
+
+```json
+{
+  "ref": "e5",
+  "action": "click",
+  "until": { "kind": "net", "method": "POST" }
+}
+```
+
+Real response, trimmed:
+
+```json
+{
+  "verified": "yes",
+  "verifiedReason": "proved",
+  "because": "assertion held at presence grade over a clean capture with no channel disagreeing",
+  "effect": {
+    "ok": true,
+    "testid": "login-submit",
+    "component": "Login",
+    "effect": { "domMutatedWithin": 7, "appeared": "Signing in…" },
+    "source": { "file": "src/components/Login.tsx", "line": 81, "column": 8 }
+  },
+  "verdict": {
+    "pass": true,
+    "evidence": {
+      "method": "POST",
+      "url": "http://localhost:8787/api/login",
+      "status": 200,
+      "durationMs": 67,
+      "requestBody": "{\"email\":\"admin@reticle.dev\",\"password\":\"[REDACTED]\"}"
+    }
+  },
+  "summary": {
+    "net": { "total": 1, "errors": 0 },
+    "consoleErrors": 0,
+    "stateDiffs": [{ "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}" }],
+    "signals": ["auth:granted"]
+  },
+  "honesty": {
+    "grade": "presence",
+    "coverage": { "pct": 100, "partial": false },
+    "integrity": { "clean": true, "issues": [] }
+  }
+}
+```
+
+## The predicate grammar
+
+`until` takes `{ kind, ...fields }`. The kinds:
+
+| Kind                      | Asserts                                                        |
+| ------------------------- | -------------------------------------------------------------- |
+| `signal`                  | The app fired a named signal, the strongest evidence available |
+| `state`                   | A store path reached a value                                   |
+| `net`                     | A request matched; `count` asserts an **exact** number         |
+| `route`                   | The route **changed**                                          |
+| `element`                 | An element appeared; `absent: true` asserts it went away       |
+| `text`                    | Text appeared or, with `absent`, disappeared                   |
+| `console`                 | Something logged; `absent: true` asserts a clean console       |
+| `animation`               | An animation ran or finished                                   |
+| `settled`                 | The page went quiet                                            |
+| `allOf` / `anyOf` / `not` | Combine the above                                              |
+
+### Predicates that catch real bugs
+
+```json
+{ "until": { "kind": "net", "method": "POST", "count": 1 } }
+```
+
+Exactly one request. Double-submit fails this at two, and no screenshot will ever tell you.
+
+```json
+{ "until": { "kind": "console", "absent": true } }
+```
+
+The action completed **and** logged nothing. "It worked but threw a warning" stops passing.
+
+```json
+{ "until": { "kind": "signal", "name": "deploy:created" } }
+```
+
+The app itself declared success. This is the highest grade of evidence, and it requires [instrumenting your app](/instrumentation). Which is the main reason to bother.
+
+## Reading `verified`
+
+<CardGroup cols={3}>
+  <Card title="yes" icon="circle-check">
+    The named consequence happened, with evidence attached.
+  </Card>
+  <Card title="no" icon="circle-xmark">
+    It did not. A finding, with a source pointer.
+  </Card>
+  <Card title="unknown" icon="circle-question">
+    Reticle could not tell. **Not a pass.** Report it as unknown.
+  </Card>
+</CardGroup>
+
+## The `honesty` block
+
+`grade` is how strong the evidence was. A fired signal outranks an element appearing. `coverage.partial: true` means Reticle did not observe the whole window. `integrity.clean: false` means something interfered with the capture and the verdict deserves less trust.
+
+A verification tool that cannot describe the quality of its own evidence is asking you to take its word for it, which is precisely the problem we started with.
+
+## 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 |