@reticlehq/server 2.14.0 → 3.2.0

package/docs/platform-integration.md

@@ -89,7 +89,7 @@ Copyable patterns: `apps/bench-app/src/reticle-dev.ts`, `apps/next-smoke/app/ret
 | UI-vs-store desync (the total lies) | reads the store, contradicts the display |
 | Blast-radius (an action corrupts unrelated state) | `state { hold:true }` invariant |
 
-Live, clickable demo of each: `apps/vibe-builder-demo/` (set `BUG_MODE=…`). Proven in CI: `packages/server/src/runs/generated-app-bugs.test.ts`.
+Live, clickable demo of each: `apps/vibe-builder-demo/` (set `BUG_MODE=…`). Proven in CI: `server/src/judgement/runs/generated-app-bugs.test.ts`.
 
 ---
 
@@ -106,7 +106,7 @@ Reticle is a stdio MCP server. A host that wires it correctly does four things,
 
 ### Hosts that cap the number of tools
 
-Some editors cap the total tool count across every MCP server, which is why Reticle advertises a small surface instead of everything it can do. Nothing is out of reach: `reticle_tools { names: [...] }` lists the tools and returns the full argument grammar for the ones you name, and `reticle_run { tool, args }` invokes any of them, advertised or not. A host that is short on tool slots pays for the advertised handful and still reaches the whole surface through that pair. See [`reticle_tools` and `reticle_run`](/tools-tools-and-run).
+Some editors cap the total tool count across every MCP server, which is why Reticle advertises a small surface instead of everything it can do. Nothing is out of reach: `reticle_tools { names: [...] }` lists the tools and returns the full argument grammar for the ones you name, and `reticle_run { tool, args }` invokes any of them, advertised or not. A host that is short on tool slots pays for the advertised handful and still reaches the whole surface through that pair. See [`reticle_tools` and `reticle_run`](/tools/tools-and-run).
 
 ---
 
@@ -141,7 +141,7 @@ The shape is identical (in-app SDK in the template → verify in the sandbox →
 
 `POST /verify` (and `reticle_run_export`) return a stable, versioned `ReticleVerificationRun` (defined in `@reticlehq/core`): `verdict` (pass/fail/partial, confidence, blockingRisks), `flows[]`, `checks[]`, `risks[]` (auth/payment/db/…), `repair.failurePackets[]` (what + where to fix), `evidence`. Render a legible report with `renderRunReport()` or `reticle_run_export { format: "report" }`. Profiles: `dev` (full) vs `prod-preview` (source + state redacted for downstream sharing).
 
-**Why trust it:** the verdict is mechanical, derived only from observed outcomes, so it can't report green for something it never ran (a severed backend reads as _fail_, never a confident pass). Proof: `packages/server/src/runs/false-green.test.ts`.
+**Why trust it:** the verdict is mechanical, derived only from observed outcomes, so it can't report green for something it never ran (a severed backend reads as _fail_, never a confident pass). Proof: `server/src/judgement/runs/false-green.test.ts`.
 
 ## Licensing for embedding
 

package/docs/predicates.mdx

@@ -7,7 +7,7 @@ icon: filter
 
 A predicate declares what should be true, as `{ kind, ...fields }`. Reticle has twelve kinds: `signal`, `state`, `net`, `route`, `element`, `text`, `console`, `animation`, `settled`, and the combinators `allOf`, `anyOf` and `not`. Which one you pick decides whether a green means anything.
 
-It is the argument to `until` on [`reticle_act_and_wait`](/tools-act-and-wait), and to `predicate` on [`reticle_assert`](/tools-assert) and [`reticle_wait_for`](/tools-wait-for).
+It is the argument to `until` on [`reticle_act_and_wait`](/tools/act-and-wait), and to `predicate` on [`reticle_assert`](/tools/assert) and [`reticle_wait_for`](/tools/wait-for).
 
 Every predicate is `{ kind, ...fields }`.
 
@@ -76,6 +76,22 @@ The one that catches the expensive bug:
 
 **Exactly one.** Double-submit fails at two, and nothing on screen would have told you.
 
+Two fields read the RESPONSE BODY, so a request that succeeded with the wrong number is still a failure:
+
+```json
+{ "kind": "net", "urlContains": "/api/refund", "bodyContains": "\"refunded\":11.87" }
+```
+
+`bodyContains` is a substring test over the response body. It is deliberately not a JSON path: the string above is the whole assertion, it needs no schema, and it behaves the same on JSON, form encoding and plain text.
+
+```json
+{ "kind": "net", "urlContains": "/api/job", "bodyMatches": { "status": "completed" } }
+```
+
+`bodyMatches` is a shallow field match, keyed like `signal.dataMatches` and taking the same operators (`*`, `$gte`, `$contains`). Reach for it whenever the value is an enum, because that is the case a substring cannot decide: `bodyContains: "completed"` passes on a body carrying `"completedAt": null`, where the needle matched the KEY and the job was still queued. `completed`/`completedAt`, `success`/`successRate`, `sent`/`unsent` all have that shape.
+
+Both require body capture, `reticle({ captureNetworkBodies: true })`, and say so when the body was never recorded rather than reporting an ordinary mismatch.
+
 ### route
 
 ```json
@@ -189,7 +205,7 @@ This is the predicate that catches a UI-versus-store desync. A deploy that only
 { "kind": "settled", "quietMs": 500 }
 ```
 
-Network and DOM idle. This is the deterministic replacement for a fixed sleep, not a proof of anything: combine it with a real consequence rather than asserting it alone. Omitting `until` on [`reticle_act_and_wait`](/tools-act-and-wait) waits for exactly this.
+Network and DOM idle. This is the deterministic replacement for a fixed sleep, not a proof of anything: combine it with a real consequence rather than asserting it alone. Omitting `until` on [`reticle_act_and_wait`](/tools/act-and-wait) waits for exactly this.
 
 ## Combinators
 
@@ -253,6 +269,6 @@ On a failure each child reports separately too, so you can see which one broke:
 
 The `since` cursor comes from a prior `reticle_act` response. Use it whenever you are asserting something an action was supposed to cause. Without it, an assertion can pass on an event from two clicks ago.
 
-<Card title="Where predicates get used" icon="circle-check" href="/tools-act-and-wait">
+<Card title="Where predicates get used" icon="circle-check" href="/tools/act-and-wait">
   Naming the consequence before the action is the whole point.
 </Card>

package/docs/protocol.mdx

@@ -0,0 +1,60 @@
+---
+title: The Open Verification Protocol
+description: The specification Reticle implements, why it is a separate package with its own licence, and how to build something else that answers the same rules.
+icon: scale-balanced
+---
+
+Reticle decides whether a change worked. **The rules it decides by are not Reticle's.** They live in a separate package, `open-verification`, under Apache-2.0, depending on nothing but `zod`.
+
+That separation is the point. A verification tool that defines its own standard of proof grades its own homework, and there is no way for you to tell the difference between a rule that is sound and a rule that happens to suit the vendor. Publishing the rules means you can read them, argue with them, and implement them yourself.
+
+## What the protocol defines
+
+A vocabulary for describing a verification, and one normative decision procedure that turns evidence into a verdict.
+
+Four verdicts, and only four: `yes`, `no`, `unknown` and `no-fault`. The third is the one that matters. `unknown` means the system could not tell what happened, and it MUST NOT collapse into either neighbour, because a tool that reports "could not tell" as "fine" is the failure this whole protocol exists to prevent.
+
+Alongside the verdict comes a **ground**: a code naming which clause decided. `no` is returned by two different clauses, so the verdict alone is too coarse to compare implementations, and the English sentence is too fine. The ground is the join key between a sentence in the specification, a JSON Schema, and a conformance test.
+
+Two rules carry most of the weight:
+
+- **Independence.** Evidence for a consequence must not come from the channel that performed the action. The thing that clicked the button does not get to testify that the button worked.
+- **Grade.** Only `consequence`-grade evidence can buy a `yes`. Seeing that an element is present is not seeing that something happened.
+
+## The documents
+
+The specification and its supporting documents ship inside the package, so `npm i open-verification` puts them in `node_modules/open-verification/` next to the schemas they describe.
+
+| Document | What it answers |
+| --- | --- |
+| `SPEC.md` | The normative specification. Every requirement carries a stable identifier such as `OVP-CHAN-2`. |
+| `CONFORMANCE.md` | What conforming means, the classes and profiles, and the exact claim an implementation may truthfully make. |
+| `SECURITY.md` | The trust model, and what this version does and does not defend against. |
+| `VERSIONING.md` | What a minor version may add, what a major may change, and which artifact is authoritative for what. |
+| `EXTENSIONS.md` | Which vocabularies are open, the naming rule, and what a receiver does with a member it does not recognise. |
+| `GOVERNANCE.md` | How it changes, and the vendor conflict it does not hide. |
+| `docs/GLOSSARY.md`, `docs/IMPLEMENTERS.md` | Non-normative. Terms of art, and a practical guide to building an implementation. |
+
+Thirty JSON Schemas are generated from the source into `dist/schema/`. Implement the protocol in any language by validating against those; you need none of the TypeScript.
+
+## Checking an implementation in an afternoon
+
+`vectors/adjudication.json` publishes one worked input and expected verdict for **every** ground the decision procedure can return. They are generated from the reference adjudicator and pinned to it by a test, so they cannot drift from the implementation they describe.
+
+Running them needs no browser, no transport and no conformance harness. If your adjudication logic agrees with all of them, it agrees with the order. If it does not, the ground names the exact clause you differ on.
+
+The full conformance suite is the next step up. Its core is deliberately vendor-neutral: the driver, the scoring and the scenarios import nothing from Reticle.
+
+## Where Reticle fits, honestly
+
+Reticle is one implementation, and today it is the only one. The specification says so in its own section 11 rather than leaving you to find out.
+
+One gap is worth stating plainly here, because it is the first thing a serious reader will check: the protocol's reference decision function, `adjudicate()`, is currently called by Reticle's conformance binding rather than by its product verdict path, which has its own implementation of the same rules. Two implementations of one decision procedure inside one repository is exactly the drift the protocol exists to prevent, and reconciling them is open work rather than a finished claim.
+
+<Card
+  title="Read the specification"
+  icon="github"
+  href="https://github.com/reticlehq/reticle/blob/main/open-verification/SPEC.md"
+>
+  The normative document, with requirement identifiers and the adjudication order.
+</Card>

package/docs/quickstart.mdx

@@ -5,7 +5,7 @@ description: Install Reticle, connect your coding agent, and get a real verdict
 icon: rocket
 ---
 
-**Run `npx @reticlehq/server init` in your project, restart your dev server and your agent, then ask your agent to drive a flow.** That is the whole install. Reticle is a verification layer for AI coding agents: it embeds a dev-only SDK in your running web app so an agent can prove a change works instead of guessing.
+**Run the installer in a terminal, open your coding agent, then run `init` in your project.** Reticle is a verification layer for AI coding agents: it embeds a dev-only SDK in your running web app so an agent can prove a change works instead of guessing.
 
 By the end of this page your agent will click a button in your app and prove what happened: the request that fired, the state that changed, and the file to open if it didn't.
 
@@ -20,15 +20,50 @@ By the end of this page your agent will click a button in your app and prove wha
 - A web app you can run locally, and its dev server
 - A coding agent that speaks MCP (Claude Code, Cursor, Codex, OpenCode, Windsurf, VS Code)
 
-## Step 1. Let your agent install it
+## Step 1. Install it on this machine
 
-The fastest path is to hand the job to the agent that will use it. In your project directory:
+In a terminal, before you open your coding agent:
+
+<CodeGroup>
+
+```bash macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh
+```
+
+```powershell Windows
+irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex
+```
+
+</CodeGroup>
+
+This puts `reticle` on your PATH and registers the MCP server with every coding agent it can reach: Claude Code, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Copilot CLI, OpenCode, Warp, Kiro, Amazon Q, Cline, Amp, Continue and Factory Droid. Nothing is asked.
+
+Codex CLI keeps a TOML config that Reticle will not rewrite, so the installer prints the lines to paste and the file to paste them into.
+
+<Note>
+  **Run this before opening your agent, and there is nothing to restart.** A coding agent reads its
+  MCP server list once at startup. Install while it is closed and the tools are simply there when
+  you open it. If it was already open, quit and reopen it once.
+</Note>
+
+Prefer not to pipe a script into a shell? The two commands it runs are:
+
+```bash
+npm install -g @reticlehq/server
+npx @reticlehq/server setup mcp
+```
+
+## Step 2. Open your coding agent, and wire the project
+
+The `reticle_*` tools are already there. In your project directory:
 
 ```bash
 npx @reticlehq/server init
 ```
 
-This registers the MCP server, installs the SDK, wires it into your app's entry point, and writes the agent rule files. It is idempotent. Run it twice and the second run reports what was already done rather than doing it again.
+Like `npm init` or `git init`, this is the per-project step: it installs the SDK, wires it into your app's entry point, restarts your dev server and then opens your app to prove a session connected. It is idempotent. Run it twice and the second run reports what was already done rather than doing it again.
+
+Step 1 is once per machine. This step is once per project.
 
 Prefer to install the skill and let the agent run setup itself? On Claude Code the plugin registers the MCP server and the skill in one step:
 
@@ -64,7 +99,7 @@ Start with `--dry-run` if you want to see the plan before anything is written.
 
 Prefer to wire it yourself? See [Manual install](/install-manual). It is about ten lines, and worth reading once even if you let the agent do it, because it explains what the agent actually changed.
 
-## Step 2. Check the setup
+## Step 3. Check the setup
 
 ```bash
 npx @reticlehq/server doctor
@@ -72,7 +107,7 @@ npx @reticlehq/server doctor
 
 `doctor` diagnoses the whole setup in one command: Chromium, the daemon, the port. If something is wrong this is the page you want before you start debugging your app instead.
 
-## Step 3. Start your app and open it
+## Step 4. Start your app and open it
 
 Start your dev server as usual, then:
 
@@ -89,7 +124,7 @@ This reuses the tab you already have open, or opens one if you don't. The SDK co
   the single most common setup problem, and the console message names the exact address it tried.
 </Warning>
 
-## Step 4. Look at the page
+## Step 5. Look at the page
 
 Ask your agent to take a snapshot. This is what came back from a real app:
 
@@ -111,7 +146,7 @@ The whole snapshot cost **61 tokens**. This is `mode: "interactive"`, which retu
 
 Each control has a `ref` like `e5`. That's the handle for the next step, and it stays valid until the element leaves the DOM, so you don't re-snapshot between actions.
 
-## Step 5. Act, and prove it
+## Step 6. Act, and prove it
 
 Here is the whole idea of Reticle in one call. Your agent names the expected consequence **before** it acts:
 
@@ -199,10 +234,10 @@ That third state is the one that matters. Most tools have two outcomes and quiet
 
 <AccordionGroup>
   <Accordion title="How long does it actually take to install Reticle?">
-    One command and two restarts. `npx @reticlehq/server init` registers the MCP server, installs
-    the SDK, wires your build config and writes the agent rules. Then restart your dev server, so it
-    picks up the new build plugin, and restart your agent, so it re-reads its MCP server list. The
-    MCP registration is global, so every later project starts with the tools already there.
+    Two commands, and no restart if you run them in order. The installer registers the MCP server
+    with every agent on the machine, so opening your agent afterwards is all that is needed. Then
+    `npx @reticlehq/server init` wires the project and restarts your dev server for you. The MCP
+    registration is global, so every later project starts with the tools already there.
   </Accordion>
 
 <Accordion title="Do I need to write tests or learn a query syntax?">
@@ -245,7 +280,7 @@ That third state is the one that matters. Most tools have two outcomes and quiet
   <Card title="Instrument your app" icon="wrench" href="/instrumentation">
     Emit signals like `auth:granted` so your verdicts get stronger than "the DOM changed".
   </Card>
-  <Card title="Every tool" icon="list" href="/tools-overview">
+  <Card title="Every tool" icon="list" href="/tools/overview">
     The 18 tools your agent sees by default, and the 30 more it can reach on demand.
   </Card>
   <Card title="Run it in CI" icon="circle-check" href="/testing">

package/docs/recipes.mdx

@@ -5,7 +5,7 @@ description: Worked examples for the situations you are actually in, with the re
 icon: book-open
 ---
 
-Each recipe is a situation, the call that verifies it, and what came back. Every response on this page was captured from a running app on 2026-08-16. Refs like `e605` are session-specific: take your own from [`reticle_query`](/tools-query) before copying a call.
+Each recipe is a situation, the call that verifies it, and what came back. Every response on this page was captured from a running app on 2026-08-16. Refs like `e605` are session-specific: take your own from [`reticle_query`](/tools/query) before copying a call.
 
 ## "Did the login actually work?"
 

package/docs/required-checks.md

@@ -0,0 +1,37 @@
+---
+title: Which checks can block a merge
+description: A workflow that runs on every pull request does not necessarily stop anything being merged. Here is which ones do.
+---
+
+A workflow running on every pull request does not, on its own, stop anything being merged. GitHub only blocks a merge on checks the repository's **branch protection** setting names as required. That setting lives in the GitHub interface, not in this repository.
+
+That gap is the difference between a gate and a decoration. A decoration still costs the same machine time on every pull request.
+
+## How it works here
+
+`ci.yml` ends in a single job called **`gate`**. It waits on every other job in that file and passes only when each one either succeeded or was legitimately skipped. So one required check, `gate`, covers all fifteen jobs in `ci.yml`.
+
+That trick only reaches so far. A job can only wait on jobs in **its own workflow file**, so the five workflows below cannot be folded into `gate`. Each has to be named in branch protection separately, or it blocks nothing.
+
+`server/src/ci-aggregate-covers-jobs.test.ts` fails if a new workflow starts running on pull requests without being accounted for, and if a job in `ci.yml` is not watched by `gate`.
+
+## The list to require
+
+Set these as required status checks on the default branch:
+
+| check | what it is | what merges without it |
+| --- | --- | --- |
+| `gate` | every job in `ci.yml`: build, tests, e2e, desktop, install, Rust, Windows, macOS, bench | a red build of any kind |
+| `package-quality` | the published packages: exports and types correctness, and the browser SDK's size budget | a package that installs but cannot be imported, or a silently growing SDK |
+| `break-gates` | onboarding | a broken first-run experience |
+| `codeql` | security scan | a flagged vulnerability |
+| `dco` | contributions are signed off | an unsigned contribution |
+
+`labeler` is deliberately absent. It adds labels to a pull request; there is no result to block on.
+
+## Adding a workflow
+
+Two choices, and picking one is required rather than optional:
+
+1. **Put its jobs in `ci.yml`.** `gate` then covers them and there is nothing to configure. Prefer this.
+2. **Keep it separate.** Reasonable when it needs different permissions or a different trigger. Then add it to `PR_JOBS_OUTSIDE_THE_AGGREGATE` in the test above, and add it to the table here and to branch protection. All three, or it runs on every pull request and decides nothing.

package/docs/skill-file.mdx

@@ -5,7 +5,7 @@ description: One URL you paste into any coding agent to teach it Reticle. How it
 icon: graduation-cap
 ---
 
-Paste `https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md` into any coding agent and say "read this and set up Reticle". The document tells the agent to run `npx @reticlehq/server init --flow "<what>"`, which does the whole install and ends with a verdict, and gives it the rules for verifying afterwards. You often do not need the file at all: that one command configures Claude Code, Cursor and nine other agents directly, and the file mostly exists to tell an agent which journey to prove and how to read what comes back.
+Paste `https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md` into any coding agent and say "read this and set up Reticle". The document tells the agent to run `npx @reticlehq/server init`, which wires the project and gets the app connected, then to do the first run with `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`, and gives it the rules for verifying afterwards. You often do not need the file at all: that one command configures Claude Code, Cursor and nine other agents directly, and the file mostly exists to tell an agent which journey to prove and how to read what comes back.
 
 `SKILL.md` is a single document you hand to a coding agent. It teaches the agent to install Reticle, wire it into your app, and then drive a verification loop properly. Without you explaining any of it.
 
@@ -40,7 +40,7 @@ One document, two jobs, no flag for you to remember. The second time you invoke
 | Phase | What the agent does |
 | --- | --- |
 | Save the skill | Store it as `/reticle` so the loop is one word away from then on |
-| Run `init --flow` | Without asking you questions it can answer itself, passing the journey worth proving |
+| Run `init`, then the first run | Without asking you questions it can answer itself, naming the journey worth proving as the `persona` |
 | Manual fallbacks | Only when `init` could not run: an older CLI that stops after writing files, or the same failure twice |
 | Validate | Confirm a session actually connected. Not that a checklist went green |
 | Prove it | Drive one real flow while you watch, so the install ends in evidence |

package/docs/skill-setup.md

@@ -0,0 +1,104 @@
+---
+title: Setting Reticle up
+description: 'What to pass `reticle init`, how to read what it gives back, and what to do when it cannot finish the job. Read this once, when you are setting up. The everyday loop is in SKILL.md.'
+icon: wrench
+---
+
+You only need this page while you are setting Reticle up, which happens once per project. Once an app is connected, the everyday loop lives in `SKILL.md` and you never need to come back here.
+
+**One command. It does all of it, and it ends with a verdict.**
+
+```bash
+RETICLE_INSTALL_SOURCE=skill_file npx @reticlehq/server@latest init
+```
+
+`@latest` is deliberate: `npx` caches, and a stale cached CLI is the most common silent setup failure. Never pin a version here.
+
+That single command detects the framework and package manager, wires the build config, installs the SDK, registers the MCP server, starts the dev server, opens the app, and waits for a session to connect from inside it. It exits non-zero if nothing connected, and prints exactly what is left to do. Then prove a flow. That is the FIRST RUN, and it is a separate call: `reticle_verify { action: "explore", persona: "<who does what>" }`. It drives with a model inside the daemon and records what it drove, so later checks replay it with no model in the loop.
+
+## What YOU decide, and pass in
+
+The command reads the repository. It cannot read the request, and three things live only there. Decide them before you run it; do not walk any of them by hand.
+
+| flag | what only you know |
+| --- | --- |
+| `persona: "<what>"` | Not an `init` flag. It belongs to the FIRST RUN, `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`. Which journey proves the thing the user asked for: code can list the buttons; it cannot know checkout matters and the theme toggle does not. Naming it took one real app from a ten-minute timeout to 138 seconds, because the turns go into FINDING a flow. |
+| `--env KEY=VALUE` | what the app needs to reach a usable state: the key from `.env.example`, the mock backend in the README, the variable that skips an auth wall. Repeatable. Without it a real app sits on a login screen and there is no flow to drive at all. |
+| `--app <dir>` | which app in a monorepo. It can list the ones that are servable; only the request says which one is being worked on. |
+
+**Ask the user nothing.** Not the framework, package manager, port, editor or MCP client: every one is answerable from the repo you are sitting in. Read `.env.example`, the README and `package.json`, decide, and say what you decided in one line.
+
+**Never ask about the port.** There are two, and conflating them is a top setup failure. The dev-server port (3000, 5173) belongs to the project's own dev script. The bridge port (**4400**) is the daemon-to-SDK channel and defaults correctly.
+
+## Then read what it gives you back
+
+`⚠` lines and a non-zero exit are a to-do list, not a failed install. The command names the cause and prints the REMAINING steps from wherever it stopped, and it will not tell you to redo a phase that already worked. Do those, and re-run; re-running is safe.
+
+**It is not finished until a verdict exists.** Writing files is not an install, and neither is a connected session. If it exits non-zero, the app is wired and something is still outstanding; say so plainly rather than reporting success.
+
+**If the user gave you a license key**, see [License key](#license-key) below.
+
+---
+
+## If that command could not run it
+
+**Do not choose this path.** It is not the thorough version of the one above; it is what you fall back to when the command physically could not do the work, and taking it by preference is how an install costs 176 turns instead of one. That is a measured figure, not a way of speaking.
+
+Use it only when ONE of these is true, and you can say which:
+
+- `init` exited without ever printing `starting:` or `▸ WATCH`, which means the CLI on this machine predates the runtime phases and stopped after writing files.
+- `init` printed a to-do list, you did those things, re-ran it, and it stopped in the same place twice.
+- There is no Node 18 or newer on this machine, so nothing can run.
+
+Anything else is not a reason: not a `⚠` in the report, not a step you would rather do yourself, not a feeling that you should check its work. Re-run the command. It is idempotent, it reports what is already wired, and it names what is still outstanding.
+
+When one of those three IS true, the whole manual procedure is one page:
+
+```bash
+curl https://docs.reticle.sh/install-manual.md      # register the MCP, wire the SDK, prove it
+curl https://docs.reticle.sh/troubleshooting.md     # nothing connected, click did nothing, verdict unknown
+```
+
+**Vite + React**, **Next.js**, **Remix** and **Astro** are the frameworks with an app and a CI gate behind them, so their wiring is proven rather than assumed. **TanStack Start** is detected and given a client-only recipe, but nothing in CI proves it. The SDK is framework-agnostic and usually connects elsewhere, but say that honestly rather than reporting a proven install.
+
+Do not reconstruct it from memory. Three things decide whether it works, and all three get skipped:
+
+1. **The SDK must load in a RUNNING page.** Not wired in a config file: loaded, in a page a browser has open. This is the step the funnel dies on.
+2. **A session must appear** on that app's own url. `reticle_session { action: "list" }` returning an empty list has four causes with four different fixes, and its `next_action` names which one this is.
+3. **A verdict must exist.** `reticle_act_and_wait` or `reticle_assert`, and nothing else. A drive that ends without one has no result however many tools it used.
+
+## The dev server, whoever starts it
+
+**A dev server already running when `init` ran does not have Reticle in its bundle.** It read `vite.config.ts` / `next.config.js` at boot; `init` edited that file afterwards. The process keeps serving the old bundle, the page loads without the SDK, no session appears, and every symptom points at the wiring you just correctly did. This is a 100% failure, not an intermittent one, and it is the single largest cause of an install that gets to step 4 and finds an empty list.
+
+So, in this order:
+
+1. **A dev server was already running?** Restart it, then hard-reload the tab. "Something is listening" does not mean the right bundle is served.
+2. **Nothing was running?** Start it in the BACKGROUND and say so in one line. `reticle_session { action: "list" }` gives you this project's own dev command in `next_action`; use that, never compose one. Started after `init`, it needs no restart. **`reticle init` may start it for you, and stops it again if setup fails**: a command somebody ran is attributable and stoppable where a daemon is not.
+
+Stopping here to ask is how a setup turn ends with nothing verified.
+
+The daemon deliberately will not do this for you. A build process started by a long-lived background daemon is invisible to the person whose machine it runs on and orphans when the daemon exits; a dev server YOU start is in the transcript, attributable, and stoppable.
+
+Four guards, none optional:
+
+1. **Never run two at once.** One dev server on the app's port. Restarting a stale one means stopping it first, not starting a second alongside it.
+2. **Never guess the command.** It comes from `package.json` scripts. No recognisable dev script means say so and stop, not invent one.
+3. **Never kill anything you did not start**, and never a daemon or a port holder. The one exception is the restart above, and say in one line that you did it.
+4. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer. You have no business editing a permissions file yourself. `init` writes one rule, for the `reticle` server alone, and prints that it did.
+
+---
+
+## License key
+
+Enterprise features are unlocked by a signed key, verified locally with Ed25519 and **no network call**. If the user hands you one, during setup or at any later point:
+
+```bash
+npx @reticlehq/server@latest init --license <key>
+```
+
+That writes `RETICLE_LICENSE_KEY` to the project's `.env` and adds `.env` to `.gitignore` if nothing there covers it. Do not do those two by hand: a key committed to git is a leaked credential, and it stays leaked after the file is removed. Confirm with `npx @reticlehq/server license`, which prints `active`, `eval`, `missing` or `expired`.
+
+Never echo the key back in your reply, and never put it in a commit, a code comment, or a feedback report. The rest: `curl https://docs.reticle.sh/enterprise.md`.
+
+---

package/docs/state-files.md

@@ -0,0 +1,46 @@
+---
+title: Reading a file Reticle wrote earlier
+description: What to do when a file on disk was written by a different version, and why repairing it is sometimes the wrong answer.
+---
+
+Reticle keeps a few files: what it has learned about your project, which runs happened, where your projects live, the flows you saved. Every one of them carries a version number.
+
+Sooner or later a version of Reticle opens a file written by a different one. This is the rule for what happens next, and it was written after two places got it wrong in ways nobody would have noticed.
+
+## The rule
+
+**Damage is repaired. A file from another version is left alone.**
+
+| what was found | what to do | why |
+| --- | --- | --- |
+| the file is missing | create it | nothing to lose |
+| it is not valid JSON | replace it | nothing in it can be read, by us or by anybody else |
+| it is valid, and from a version we do not know | **stop, and say so** | it is intact, and the version that wrote it can still read it |
+
+The middle and bottom rows look the same from inside the code: both are "the file did not parse". That is exactly why this goes wrong. They need opposite handling.
+
+## Why the difference matters
+
+Imagine a file that got cut in half by a machine losing power mid-write. One person, one file. There is nothing in it to save, and refusing to work would strand them for no gain. Repair it.
+
+Now imagine a new version of Reticle that changed the format. Every one of those files, on every machine, becomes unreadable at the same moment, and **every one of them is perfectly intact.** Repair them and you have overwritten real history that the version which wrote it could still have read.
+
+The second case looks like the first, happens to everybody at once, and destroys something. That is why "just start fresh, it is only a cache" is a decision to make carefully rather than a default.
+
+## Where this bit us
+
+Two places, both found while preparing v3.
+
+**Recording a run.** Reading a damaged `project.json` fell back to an empty one and wrote it back, so a version change would have silently deleted your run history on the first run after upgrading. Nothing failed, so nobody would have looked.
+
+**Registering a project.** Reticle keeps one file in your home directory listing every project it knows about. Adding a project meant reading that file, adding a line, and writing it back. A file it could not read became a file with one project in it, and every other project you had set up was gone. This happened during `reticle init`, which is what you run right after upgrading.
+
+## If you are adding a file
+
+Three things.
+
+Give it a version number, and add it to `server/src/on-disk-versions.test.ts`. That test fails when any version changes, so the change cannot happen without somebody deciding what becomes of the files already out there.
+
+Tell the two failure cases apart when you read it. `ProjectReadError` shows the shape: `MALFORMED` for damage, `WRONG_VERSION` for a file from elsewhere. One message for both sends somebody hunting a typo in a healthy file.
+
+And prefer adding a field to changing one. A reader that ignores fields it does not recognise, and a writer that preserves them, will survive most version changes without anything special. `.reticle.json` does this: fields nobody recognises are copied through untouched.

package/docs/state-management.mdx

@@ -190,7 +190,7 @@ You can also assert on it directly, which is stronger than reading it afterwards
 That catches a UI-versus-store desync, a deploy that only looks shipped, deterministically and with no model involved.
 
 <CardGroup cols={2}>
-  <Card title="reticle_state" icon="database" href="/tools-state">
+  <Card title="reticle_state" icon="database" href="/tools/state">
     Arguments, depth control, and reading a component's hook state.
   </Card>
   <Card title="Instrument your app" icon="wrench" href="/instrumentation">

package/docs/system-map.md

@@ -8,7 +8,7 @@ A tool call crosses five processes and four hops: coding agent → `reticle mcp`
 
 > How a tool call gets from a coding agent to your app and back, what each hop can do wrong, and which of those failures are **silent**. Written for anyone touching the transport, the daemon, the bridge, or a gate, and for contributors trying to work out where their change lives.
 >
-> Companion pages: [`harness-rules.md`](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md) (what a gate must do about all this) and [`telemetry-contract.md`](./telemetry-contract.md) (the rules for anything that emits).
+> Companion pages: [`harness-rules.md`](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md) (what a gate must do about all this) and [`telemetry-contract.md`](https://github.com/reticlehq/reticle/blob/main/docs/telemetry-contract.md) (the rules for anything that emits).
 
 ## 1. Topology: 5 processes, 4 hops
 
@@ -56,11 +56,13 @@ Three different counts, all measured, and the difference between them matters:
 
 | Count | What it is |
 | --- | --- |
-| **68** | name constants in `ReticleTool` |
-| **48** | tools advertised under `RETICLE_ADVERTISE_ALL_TOOLS=1`, i.e. what `tool-surface-sweep-test` drives (51 calls) |
-| **19** | advertised by default; the rest are reached through `reticle_run` |
+| **76** | name constants in `ReticleTool` |
+| **30** | tools advertised under `RETICLE_ADVERTISE_ALL_TOOLS=1`, i.e. what `tool-surface-sweep-test` drives |
+| **10** | advertised by default; the rest are reached through `reticle_run { tool, args }` |
 
-68 → 48 is **family folding**: `reticle_baseline`, `reticle_session`, `reticle_record`, `reticle_flow` and `reticle_lease` each absorb their members behind an `action` parameter. So "every tool is callable" is asserted over 48 surfaces, not 68 behaviours; a family member reachable only through an `action` value the sweep never passes is not covered by it. Worth closing when the per-tool budget lands (see [`gate-plan.md`](./gate-plan.md), Phase 4).
+The middle number is **family folding**: `reticle_baseline`, `reticle_session`, `reticle_record`, `reticle_flow` and `reticle_lease` each absorb their members behind an `action` parameter. So "every tool is callable" is asserted over the advertised surfaces, not over every named behaviour; a family member reachable only through an `action` value the sweep never passes is not covered by it. Worth closing when the per-tool budget lands (see [`gate-plan.md`](https://github.com/reticlehq/reticle/blob/main/docs/gate-plan.md), Phase 4).
+
+These three were each wrong by the time somebody checked: the table read 68 / 48 / 19 against a measured 76 / 30 / 10, and the middle one had a derived token cost hanging off it. `surface-sizes.test.ts` is the authority and fails when a surface changes size, so prefer reading it to trusting this row.
 
 | Token | Produced by | Consumed by | Invalidated by |
 | --- | --- | --- | --- |
@@ -156,7 +158,7 @@ Still fragile:
 | install | pristine-surface wiring | nothing | the whole class |
 | client | per-agent MCP compatibility | nothing | the whole class |
 
-Nine of eleven layers have a gate. The two that do not are exactly the two that need a second repo and a human. The plan for both is in [`gate-plan.md`](./gate-plan.md).
+Nine of eleven layers have a gate. The two that do not are exactly the two that need a second repo and a human. The plan for both is in [`gate-plan.md`](https://github.com/reticlehq/reticle/blob/main/docs/gate-plan.md).
 
 ## 6. Traces already encode the invariants
 

package/docs/telemetry.md

@@ -37,6 +37,7 @@ Eighteen kinds of events, each a single small JSON object. This is the whole lis
 | `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**, because a reconnect loop can fire many times in a row and an event each would bill for the pathology instead of measuring it |
+| `onboarding_step` | One step of getting set up begins, finishes, fails, is skipped, or is walked away from | Which phase (`install`, `onboard`, `first_run`), which step, what became of it, how long it took, and the framework. The step name comes from a closed list we define -- it can only ever be one of the names in `core/src/onboarding.ts`, so nothing you typed or any path on your disk can arrive in it. `unattended` says whether anybody was asked anything |
 | `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 |
@@ -45,7 +46,7 @@ Eighteen kinds of events, each a single small JSON object. This is the whole lis
 
 **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`](https://github.com/reticlehq/reticle/blob/main/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`](https://github.com/reticlehq/reticle/blob/main/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`).
 
@@ -57,7 +58,7 @@ It also carries a snapshot of the **machine's** state (our own process's memory,
 
 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.
+When the clause is `unclean_capture`, one further name says which of our losses caused it: `buffer_loss` (our server's event buffer), `transport_gap` (our browser-side queue), `journal_loss` (our on-disk event ledger reached its size cap), `blind_spot` (a boundary in the page, such as a cross-origin frame), or `other`. All five 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
 
@@ -127,7 +128,7 @@ Reticle verifies apps for AI agents, and for a long time it had no way to hear w
 
 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`](https://github.com/reticlehq/reticle/blob/main/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`](https://github.com/reticlehq/reticle/blob/main/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.
 

package/docs/testing.md

@@ -1,10 +1,19 @@
 ---
-title: Specs for CI
-description: 'Turn an interactive drive into a repeatable suite with @reticlehq/test: declarative specs bound to signals, never DOM structure.'
+title: Write verification in code
+description: 'Write your own checks with @reticlehq/test, a plain library you call from your own script. No agent required, no test framework required. Also how you run Reticle checks in CI.'
 icon: vial
 ---
 
-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.
+You do not need an agent to use Reticle. `@reticlehq/test` is an ordinary library: you write a script, it drives your running app, and it tells you whether what you expected actually happened.
+
+That makes this page two things at once, and both are the same code:
+
+- **You decide what "verified" means for your app**, in a file you own, in code you can read and keep in version control.
+- **Those same checks run in CI**, so the thing you wrote by hand is the thing that guards the branch.
+
+You will need `@reticlehq/test` installed, and your app already running. Write checks with `reticleTest(name, async (t) => …)`, open a headless session with `bootSession({ driveUrl, headless: true })`, and run them with `runSpecs`. Exit non-zero when `summary.failed` is not `0`.
+
+Checks 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.