@reticlehq/server 3.8.2 → 3.10.0

package/docs/capabilities.mdx

@@ -105,6 +105,62 @@ The reliable pattern is:
 3. Advance by the required interval.
 4. Assert the consequence.
 
+### Deterministic lease: the same pixels on every run
+
+A canvas game or an animation draws something different on each run, because time and randomness differ. Acquire a lease with `deterministic` to make two runs the same:
+
+```json
+{ "tool": "reticle_lease", "args": { "action": "acquire", "url": "http://localhost:5173", "deterministic": { "seed": 7, "platform": "Linux x86_64" } } }
+{ "tool": "reticle_clock", "args": { "stepFrames": 30 } }
+```
+
+```json
+{ "frozen": true, "frame": 30, "nowMs": 500 }
+```
+
+Before any page script runs, the lease installs these in the tab:
+
+- `Math.random`, `crypto.getRandomValues` and `crypto.randomUUID` take values from a generator with the given `seed` (default 1).
+- `Date`, `performance.now`, `setTimeout`, `setInterval` and `requestAnimationFrame` use a virtual clock. It starts at 2026-01-01T00:00:00Z and moves only on `stepFrames`.
+- `devicePixelRatio` is 1. `platform` sets `navigator.platform`, the platform in `navigator.userAgent` and `navigator.userAgentData.platform`.
+
+Each step frame is 16.67 ms. In each frame, the due timers run in time order, then each `requestAnimationFrame` callback runs once. Then capture or read the page.
+
+<Warning>
+  Time stands still on this tab until you step it. A wait for a timer or an animation does not end
+  on its own. These still run on real time: CSS animations and transitions, workers, WebAssembly
+  threads, media playback and network responses. Mock the network with `reticle_network_mock` if the
+  page draws what it fetches. GPU drawing can differ between machines; compare runs on the same
+  machine.
+</Warning>
+### JS coverage of a leased tab: which code ran
+
+The JS engine counts each block of code that runs. On a leased tab, Reticle reads those counts from outside the app, with no change to it:
+
+```json
+{ "tool": "reticle_lease", "args": { "action": "acquire", "url": "http://localhost:5173", "jsCoverage": true } }
+{ "tool": "reticle_lease", "args": { "action": "coverage", "mode": "take", "urlContains": "/src/" } }
+```
+
+```json
+{
+  "running": true,
+  "scriptCount": 1,
+  "rangeCount": 3,
+  "scripts": [
+    {
+      "url": "http://localhost:5173/src/app.js",
+      "ranges": [
+        { "startOffset": 0, "endOffset": 412, "count": 1 },
+        { "startOffset": 120, "endOffset": 188, "count": 0 }
+      ]
+    }
+  ]
+}
+```
+
+A take returns what ran since the previous take. A range with `count: 0` is code that did not run. `jsCoverage: true` on acquire starts coverage before the page's first script, so the code that runs while the page loads is counted. `{ "mode": "start" }` starts it later, and misses that code. A take stops at `maxRanges` (default 20000) and names what it dropped in `truncated`; `filteredOut` counts the scripts that `urlContains` left out. Chromium only.
+
 ### Crawl: click everything, report anomalies
 
 ```json
@@ -147,7 +203,9 @@ Controls Reticle judges destructive are blocked unless you pass `confirmDangerou
 
 `{ "action": "crawl", "exhaustive": true }` goes past one page. It walks every state reachable from where you start, reaching each one by replaying the path that found it from a fresh load, so it never depends on "back" working. It fills text fields before it tries a form's buttons (from `RETICLE_SECRET_<FIELD>` when set, so it gets past a login, and only on the origin the crawl started on), and treats controls that differ only by a number, like table rows, as one. A control with the same name on a different screen is tried again there. Every write it finds is then driven again with the request failing. A write counts as **branched** only when the request was actually sent and broken. With the write failing, the app must not end up where it goes when the write succeeds; if it does, you get `failure-unhandled`. That part needs a browser Reticle drives (`reticle drive`).
 
-The run folds into the app-wide coverage ledger, which `reticle_verify { action: "coverage", app: true }` also reports. It has six levels, each with what is missing: routes **reached**, controls **touched**, controls **proved** (an `act_and_wait` came back `yes`), journeys **completed**, writes **branched** (failure path driven), and app functions **executed** (V8 coverage, driven browser only, collected from the first coverage request or exhaustive crawl onward, so an ordinary drive pays nothing for it). `frontier` is the number of states found and not yet explored. Zero means every state the explorer could tell apart was explored, not that every reachable state was: a state is its route plus the names of its controls, so two screens that differ only in field values, in how many of a control they show, or in what the same controls do count as one, and the second is never visited. `reticle gate` blocks when a level falls below the best it has reached, and when a changed file never ran. A changed file whose coverage was taken before the edit is reported as `coverageStale` instead, because its counts describe the old code. When a drop was intended, `reticle gate --accept-coverage` records today's levels as the new best.
+The run folds into the app-wide coverage ledger, which `reticle_verify { action: "coverage", app: true }` also reports. It has six levels, each with what is missing: routes **reached**, controls **touched**, controls **proved** (an `act_and_wait` came back `yes`), journeys **completed**, writes **branched** (failure path driven), and app functions **executed** (JS coverage, driven browser only, collected from the first coverage request or exhaustive crawl onward, so an ordinary drive pays nothing for it). `frontier` is the number of states found and not yet explored. Zero means every state the explorer could tell apart was explored, not that every reachable state was: a state is its route plus the names of its controls, so two screens that differ only in field values, in how many of a control they show, or in what the same controls do count as one, and the second is never visited. `reticle gate` blocks when a level falls below the best it has reached, and when a changed file never ran. A changed file whose coverage was taken before the edit is reported as `coverageStale` instead, because its counts describe the old code. When a drop was intended, `reticle gate --accept-coverage` records today's levels as the new best.
+
+The same report has a `holes` block. It names what was never reached, by kind: `routes`, `controls`, `edges` (controls whose edge-case inputs and interactions were never driven), `writes` (failure path never driven), `functions` and `components`. A kind that nothing could measure has `measured: false` and a `note` that tells you why. A list past its cap has `overflow`, the count of the items it does not name. The `findings` block lists the behaviour faults in the ledger: `undo-not-restored`, `repeat-changed-state`, `lost-after-reload`, `shown-differs-from-sent`, `intermittent-result` and `failure-unhandled`. Each finding has the steps that show it, and the `file:line` of the element when the app gives source attribution.
 
 <Warning>
   Exhaustive really does click everything, repeatedly, and submits forms. `maxSteps` bounds it,
@@ -425,6 +483,8 @@ Nine hundred and fifty-three bytes for 445 recorded events. `timeline_omitted` h
 
 Reticle grades the flow as you save it, and tells you when you have just created a test that cannot fail. Take the warning seriously: an assertion-free flow replays green whatever the app does.
 
+When the flow checks something, `assertions.checks` counts each kind of check over every step, sub-step and the success state, for example `{ "element": 1, "route": 1, "text": 3 }`. A presence-only flow names those checks in its warning. The grade says how strong the checks are, not that there are none.
+
 A replay against a drifted app names what moved and where. This is `reticle_verify { action: "flows" }` reporting the same flow after the app changed underneath it:
 
 ```json

package/docs/cli/affected.mdx

@@ -1,15 +1,17 @@
 ---
-title: reticle affected
+title: reticle gate --list
 description: List which saved flows must re-verify for a set of changed files.
 icon: code-branch
 ---
 
-`reticle affected` answers one question: given these changed files, which saved flows cover them? It is the foundation the [gate](/cli/gate) is built on, and it costs your agent nothing per turn because it runs in the environment.
+`reticle gate --list` answers one question: given these changed files, which saved flows cover them? The [gate](/cli/gate) checks the same set. `--list` only names it and checks nothing. It costs your agent nothing per turn because it runs in the environment.
 
 ```bash
-npx @reticlehq/server affected [--since <ref>] [file...]
+npx @reticlehq/server gate --list [--since <ref>] [file...]
 ```
 
+`reticle affected` is the old name. It still works for one release and prints one line naming `gate --list`.
+
 ## Arguments and flags
 
 | Argument | Type | Default | What it does |
@@ -17,7 +19,7 @@ npx @reticlehq/server affected [--since <ref>] [file...]
 | `file...` | strings, positional | none | Explicit changed files |
 | `--since <ref>` | string | `HEAD` when no files are given | Also include files git reports as changed since this ref |
 
-With nothing after it, `reticle affected` compares the working tree with `HEAD`.
+With no files, `reticle gate --list` compares the working tree with `HEAD`.
 
 ## What it prints
 
@@ -43,11 +45,11 @@ The real run named 47 flows in each list. The CLI prints this as a single line o
 
 ## Exit codes
 
-Always `0`. A load error is logged as `reticle_affected_failed`, not thrown. Use [`reticle gate`](/cli/gate) when you want a non-zero exit.
+Always `0`. A load error is logged as `reticle_affected_failed`, not thrown. Use [`reticle gate`](/cli/gate) without `--list` when you want a non-zero exit.
 
 ## Worked example
 
 ```bash
-npx @reticlehq/server affected --since origin/main
-npx @reticlehq/server affected src/components/Login.tsx
+npx @reticlehq/server gate --list --since origin/main
+npx @reticlehq/server gate --list src/components/Login.tsx
 ```

package/docs/cli/cloud.mdx

@@ -42,7 +42,7 @@ npx @reticlehq/server connect [--project <name|id>] [--workspace <name|id>] [--u
 
 Signs in if needed (a browser device flow like `gh auth login`: approve in the browser, the CLI polls until confirmed), then binds this repository to a cloud project and sends local history. It **mints** a project-scoped key, so there is nothing to paste; with `RETICLE_API_KEY` already set, it resolves that key's project instead. `--project` accepts a slug id or a display name, and creates the project when no project has that name. Omitted, the project is named after the `projectId` in `.reticle.json`, else after this folder. `--workspace` picks the workspace to link in when you belong to more than one. `--no-install` is passed to the `init` it runs for an unwired app. Writes `cloud.json` and the key.
 
-`reticle login`, `reticle link` and `reticle project` are the old spellings. They still work for one release and print one line naming `connect`. Sign-in is with Google or GitHub, in the browser. Email sign-in is gone: `reticle login --email` stops and says so. Without a browser (CI, an agent, a server), set `RETICLE_API_KEY` to a key from Settings > API keys.
+`reticle login`, `reticle link` and `reticle project` were removed. Each prints that it was removed, names `connect`, and exits `1`. Sign-in is with Google or GitHub, in the browser. Email sign-in is gone. Without a browser (CI, an agent, a server), set `RETICLE_API_KEY` to a key from Settings > API keys.
 
 ### `reticle logout`
 
@@ -74,7 +74,7 @@ Sends local run artifacts from `.reticle` to the linked project, honoring the sy
 
 Runs go up in batches, so a large backlog is never one oversized request.
 
-`reticle push` is the old name; it still works for one release and prints one line naming `sync`. Add `--watch` to keep syncing: it runs one cycle, waits, and runs the next, until you stop it with `Ctrl+C`. The wait is 60 seconds by default; set `RETICLE_SYNC_INTERVAL_MS` to change it. Add `--move-history` to also send the runs, flows and records made under this folder's previous link, after it was linked to another workspace.
+`reticle push` was removed: use `reticle sync`. Add `--watch` to keep syncing: it runs one cycle, waits, and runs the next, until you stop it with `Ctrl+C`. The wait is 60 seconds by default; set `RETICLE_SYNC_INTERVAL_MS` to change it. Add `--move-history` to also send the runs, flows and records made under this folder's previous link, after it was linked to another workspace.
 
 ```bash
 npx @reticlehq/server sync --watch
@@ -115,7 +115,7 @@ The triage queue from the dashboard. `--fix <fingerprint>` prints that one issue
 
 What the linked project has learned, scoped to the project this folder is linked to. `--subject <name>` narrows it to one area. If the response cannot be shown to be about this project, it prints nothing on stdout and exits `1`.
 
-`reticle regression`, `reticle share`, `reticle issues` and `reticle memory` are the old spellings. They still work for one release, with the same exit codes, and print one line naming the `runs` form.
+`reticle regression`, `reticle share`, `reticle issues` and `reticle memory` were removed. Each prints the `runs` form to use and exits `1`.
 
 ## When the repo is not attached
 

package/docs/cli/compare.mdx

@@ -0,0 +1,94 @@
+---
+title: reticle compare
+description: Drive two running builds of one app the same way and list each difference in what users see.
+icon: code-compare
+---
+
+`reticle compare` answers one question: does the candidate build show what the reference build shows? Use it to compare main with a pull request preview, or a known-good build with a changed build. The app needs nothing installed: no SDK, no plugin and no `reticle init`. Any URL works.
+
+```bash
+npx @reticlehq/server compare <reference-url> <candidate-url> [--base <url>] [--state <file>] [--json] [--report <file>]
+```
+
+| Argument | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `<reference-url>` | string | required | The build that is correct, for example main |
+| `<candidate-url>` | string | required | The build to check, for example a pull request preview |
+| `--base <url>` | string | unset | The build before the change. Each difference gets a tag, and the command prints a score |
+| `--state <file>` | string | unset | A JSON file that declares how to read the app's stored data. See [State sources](#state-sources) |
+| `--json` | boolean | off | Print one JSON object instead of text |
+| `--report <file>` | string | unset | Also write the result as one HTML page: the verdict, the counts, and each difference with its steps and the lines on each side. Open it in a browser, share it, or keep it as a CI artifact. It needs no network and runs no script |
+
+## What it does
+
+The command has one recipe and no other settings.
+
+1. **Read the values the app checks for.** The command fetches the reference page and its scripts the way a browser does (at most 40 files). It collects each string that a named value is compared with, for example `values.route === "progress"`. A field whose name matches that name also gets those values, so a branch behind a special value is reached.
+2. **Plan on the reference, breadth first.** The plan has the start page and every single action on every control. It clicks each button, tab, checkbox and option. It fills each text field with two values chosen by the shape of the field's value (a time, a date, a number, text), one edge value of that shape (`23:59`, `2024-02-29`, `-1`, or a long text with markup characters), and the values from step 1. It selects each option of each combobox. After each sequence, the plan goes one level deeper into the controls that appeared. On a page with two or more fields, it fills every field with its own value, then presses each button. A click is also followed by a 4 second wait, but only where the reference showed delayed activity: a request still pending, a page that kept changing while it settled, or a change during the wait. The plan holds at most 220 sequences. A control is found by its test id when it has one, else by its role and name, numbered in page order.
+3. **Drive the plan.** Every sequence starts from a fresh load of the URL. The page is read only when it settles: two reads in a row, 400 ms apart, must match (at most 4 reads). A sequence that starts a longer planned sequence is not driven alone; the longer one is read after each step. The reference is driven two times, the candidate one time, and the base one time. Each run is a new browser tab that the daemon leases.
+4. **Compare what a person sees, and what the app did.** Names, text, values, and the checked, selected, disabled, expanded and pressed states, in page order. Then each network call since the sequence's first action (method, path with the query values removed, status, and the start of the request body) and each console error and warning. Case and spacing of page text are folded, and elapsed times under one second are rounded to whole seconds. A line that differs between the two reference runs (a clock, a random id) is noise and is ignored. A step that the candidate cannot do and the reference could is a difference. When a network or console read fails, the reading says `effects failed`, so an empty list always means that nothing happened.
+
+The command presses every button it finds. On a build served from loopback (`localhost`, `127.0.0.1`) or a `*.localhost` name, that includes the controls the act guard holds back, such as "Place order" or "Delete": those builds are disposable copies, and their submits are the actions most worth comparing. On any other host the guard stays on and those controls are not pressed. Point it at builds whose data you can change, not at a production database.
+
+## State sources
+
+A page read sees only the pages that a sequence opens. If the candidate also changes a record that no page in the plan shows (for example, the price of another product), the page reads cannot see it. Declare how to read the app's stored data, and compare reads it too:
+
+```json
+{
+  "sources": [
+    {
+      "kind": "command",
+      "label": "prices",
+      "container": "shop-db",
+      "command": "mysql -N shop -e 'select entity_id, value from product_price'"
+    },
+    {
+      "kind": "http",
+      "label": "orders",
+      "url": "http://localhost:3000/api/orders",
+      "path": "data.items",
+      "ignore": ["updatedAt"]
+    },
+    { "kind": "file", "label": "settings", "path": "./data/settings.json" }
+  ]
+}
+```
+
+| Kind | Fields | What it reads |
+| --- | --- | --- |
+| `command` | `command`, optional `container` | Each output line of a shell command. With `container`, the command runs through `docker exec <container> sh -c` |
+| `http` | `url`, optional `path` | Each record of a JSON endpoint. `path` is a dotted path to the array |
+| `file` | `path`, optional `at`, optional `container` | Each JSON record of a file (`at` is a dotted path to the array), or each line when the file is not JSON. With `container`, the file is read in that container |
+
+Each source has a `label`. `ignore` is optional: for JSON records it holds field names to remove, and for text lines it holds regular expressions to remove (a time, or an id that changes on each run). A text line that a pattern removes all of is removed.
+
+After each sequence, on every build, compare reads each source and adds its rows to that sequence's reading as `state <label> <row>` lines, sorted. JSON records are written with their keys sorted. The same diff and the same noise rule apply: a row that differs between the two reference runs is ignored. Start each row with the record id, so that a changed row names its record. A source keeps at most 1000 rows. When it has more, a `state rows cut: <label>: kept 1000 of <n>, rest <digest>` line says so. The digest covers the cut rows, so a change to a cut row changes this line, but the line does not name the record. If a cut row differs between the two reference runs, the digest is noise and a change to a cut row is not seen. Remove times with `ignore`, or query fewer rows. A read that fails gives a `state read failed: <label>: <reason>` line, never an empty list.
+
+The builds are driven one after the other, and compare does not reset their data. When two builds use one database, the second build starts from the data the first one changed. Give each build its own data, or reset it before each run.
+
+## What it prints
+
+The first line is the verdict: `SAME`, `DIFFERENT` or `INVALID`. Then the counts, the time for each build in seconds, and the first 5 differences. Each difference shows the steps that reproduce it, then `-` for the lines only the reference shows and `+` for the lines only the candidate shows. `--json` gives every difference.
+
+With `--base`, each difference gets a tag:
+
+| Tag             | Meaning                                                                     |
+| --------------- | --------------------------------------------------------------------------- |
+| `regression`    | The base and the reference show the same page, and the candidate changed it |
+| `target-missed` | The reference changed the page, and the candidate still shows the base page |
+| `changed`       | The candidate differs from both                                             |
+
+The score is `targets matched / targets x (1 - kept sequences changed / kept)`. A target is a sequence where the reference changed the base page. A kept sequence is one where it did not.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Same: every compared sequence shows the same page |
+| `1` | Different |
+| `2` | Invalid: the browser session was lost, nothing could be compared, or the daemon or a build could not be reached. Run it again |
+
+The command uses the daemon on `--port` (or `RETICLE_PORT`), and starts one when there is none.
+
+An agent whose Reticle tools are loaded runs the same compare with `reticle_verify { action: "compare", reference, candidate, base? }`. It answers the same JSON as `--json`; see [reticle_verify](/tools/verify).

package/docs/cli/doctor.mdx

@@ -7,13 +7,14 @@ icon: stethoscope
 `reticle doctor` collapses the setup failure modes into one command. It is the first thing to run when something is wrong.
 
 ```bash
-npx @reticlehq/server doctor [--port N]
+npx @reticlehq/server doctor [--fix] [--port N]
 ```
 
 ## Flags
 
 | Flag | Type | Default | What it does |
 | --- | --- | --- | --- |
+| `--fix` | boolean | off | Repair what Reticle can repair safely, then run the checks again. See [Repair with --fix](#repair-with---fix) |
 | `--port N` | number | `RETICLE_PORT`, else the port in `.reticle.json`, else the daemon already serving this project, else `4400` | Which bridge port to diagnose |
 
 ## What it prints
@@ -50,10 +51,12 @@ When nothing has connected, the `sessions` line fails and the daemon's own diagn
 | Line | What it checks |
 | --- | --- |
 | `node` | The Node version running the CLI |
+| `mcp` | Which coding agents found on this machine have Reticle's MCP server registered. Fails when an agent is found without it, and names the agent and `reticle setup mcp` |
 | `chromium` | Whether the exact Chromium revision the bundled Playwright wants is on disk. The most common silent failure |
 | `daemon` | Whether the port holds a Reticle daemon, a foreign process (named where possible), or nothing. Adds a `version` line when the daemon's version or contract fingerprint disagrees with the CLI's |
 | `sessions` | Whether any page has actually connected. Zero is a FAILING check rather than a neutral note, because it is the state the setup most often stalls in: wired correctly, daemon up, nothing dialled in. When it is zero the daemon's own no-session diagnosis prints below the checklist |
 | `agent link` | Whether an MCP client has listed Reticle's tools on this port **and actually called one**. Every other row here checks a component; this one checks the hop between your agent and the daemon. It is possible for the SDK to be injected, a session to be live, and your client to show every tool enabled, while no request has ever crossed from the agent. That state passes every other check and is the one people lose hours to |
+| `launcher` | Only when an agent config starts Reticle from an installed copy (`node <path> mcp`) and that file does not exist, for example after `npm uninstall -g`. Names the agent, the path, and the command that writes a working entry |
 | `loopback` | Which of `localhost`'s two answers reaches the bridge. Printed **only when they disagree**. The daemon binds `127.0.0.1`, and a best-effort alias forwards `[::1]` to it so the name works everywhere. When that alias cannot open (IPv6 disabled, or something already holding `[::1]` on the port) the daemon serves IPv4 perfectly and a page told to dial `localhost` still cannot reach it, because Windows Chrome tries the IPv6 answer first. Every other row here goes green in that state |
 | `bridge port` | The port your app must dial, spelled out because mixing it up with the dev server port is the most common setup failure |
 | `port check` | Only when your project's configured port disagrees with the one the daemon is on. Prints the mismatch rather than leaving you to spot it across two lines |
@@ -113,9 +116,45 @@ The wanted revision and the root are both read back off the path Playwright itse
   before. That loop is why the line names the version to pin to.
 </Warning>
 
+## Repair with --fix
+
+When a row has a safe repair, a plain `doctor` run ends with one more line:
+
+```
+Run `reticle doctor --fix` to repair 2 of these.
+```
+
+`reticle doctor --fix` prints the checks, applies the safe repairs in a fixed order, runs the checks again, and prints one line for each repair and one for each row that still fails. A repair changes only Reticle's own state:
+
+| Order | Row | Repair | Done only when |
+| --- | --- | --- | --- |
+| 1 | `daemon` | Delete the pid file of a daemon that is not running | The process that the file names does not exist |
+| 2 | `daemon` | Stop a Reticle daemon that holds the port and does not answer, as `reticle serve --restart` does | The holder's command line is a Reticle daemon, and it is still silent after a grace period. A different program and the agent's own `reticle mcp` proxy are never stopped |
+| 3 | `chromium` | Install the pinned Chromium of the bundled Playwright (a download) | No Chrome or Edge can stand in, and `RETICLE_CHROMIUM_PATH` is not set |
+| 4 | `launcher` | Run `reticle setup mcp`, which replaces Reticle's own entry | An agent config starts Reticle from an installed copy that does not exist. `setup mcp` keeps an existing Claude Code entry, so for Claude Code the step stays `claude mcp remove reticle -s user`, then `setup mcp` |
+| 5 | `mcp` | Run `reticle setup mcp` | An agent on this machine does not have Reticle registered |
+
+Each repair checks again before it acts, so a second `--fix` finds nothing to do and changes nothing.
+
+`--fix` never repairs a row that needs a change to your app, a process that Reticle cannot prove is its own daemon, or an action only you can do. For those rows it prints the step that the row names: for example `reticle init` for `project`, starting your agent for a stopped `daemon`, `reticle hook install` for `prompts`, a CSP or desktop change, or a version skew (restart the daemon when no other agent uses it).
+
+```
+reticle doctor --fix
+  daemon       pid file of a stopped daemon: fixed
+  daemon       a Reticle daemon that does not answer: nothing to do
+  chromium     Playwright's own Chromium: nothing to do
+  launcher     a registered launcher that does not exist: nothing to do
+  mcp          agent registrations: fixed
+  still needs: sync         ✗ off: this project is not linked: run `reticle connect`; no push yet
+```
+
+A registration takes effect when the agent reads its config again, so restart your agent after `mcp` is fixed.
+
 ## Exit codes
 
-Always `0`. `doctor` reports; it does not gate.
+A plain `doctor` always exits `0`. It reports; it does not gate.
+
+`doctor --fix` exits `0` only when no row fails after the repairs, and `1` otherwise.
 
 ## Worked example
 

package/docs/cli/grade.mdx

@@ -0,0 +1,97 @@
+---
+title: reticle grade
+description: Grade a finished run of an app from snapshots of its stored data, and check its final answer.
+icon: clipboard-check
+---
+
+`reticle grade` answers one question: did a run leave the app the way the correct steps leave it, and give the correct answer? A run is any sequence of steps on an app you can reset: an agent, a script or a person. The command needs no daemon, no browser and nothing installed in the app. It reads the app's stored data through the [state sources](/cli/compare#state-sources) that `reticle compare --state` uses.
+
+```bash
+npx @reticlehq/server grade snapshot --state <file> --out <file> [--url <url>]
+npx @reticlehq/server grade judge --reference <file> --again <file> --candidate <file> [--expect <file>] [--answer <text>] [--json]
+npx @reticlehq/server grade tables --list <command> --rows <template> [--container <name>] [--skip <prefix,...>] --out <file>
+npx @reticlehq/server grade suggest --state <file> --reference <file> --again <file> --out <file>
+```
+
+## How to grade a run
+
+1. Reset the app. Do the correct steps. Run `grade snapshot --out reference.json`.
+2. Reset the app. Do the correct steps again. Run `grade snapshot --out again.json`.
+3. Reset the app. Do the run to grade. Run `grade snapshot --out candidate.json`.
+4. Run `grade judge --reference reference.json --again again.json --candidate candidate.json`.
+
+Steps 1 and 2 are done one time for each task. Keep the two files, and grade every run of the task against them.
+
+`judge` compares the lines of the three snapshots. A line that differs between the two correct runs (a clock, a random id) is noise and is ignored. Any other line that differs between the reference and the candidate is a difference, and the grade fails. So the grade fails when the run changed the wrong record, changed a record the task did not name, or did not change the record at all. A source that could not be read makes the grade unverified, never a pass.
+
+A row that the two correct runs wrote with different values in some cells (a time of the run, written into `updated_at`) has noise in those cells only. A candidate row that differs from the reference row only in those cells is not a difference. A change to another cell of that row, or to the same cell of another row, is a difference.
+
+Many apps save a record by deleting its child rows and writing them again, with new ids. A run that saves a record two times then has the same data under other ids. `judge` matches these rows: a removed row and an added row of one source are the same record when every cell after the first (the id) is equal, after each id it already matched is replaced by its new id. So a row that links to a written-again row matches too. A match needs an old id that the candidate no longer has, and a new id that the reference did not have, so a changed value in a first column that is not an id is still a difference. `--json` gives the count as `state.renumbered`. This applies to text rows (a `command` source, or a file of plain lines) whose cells are separated by tabs.
+
+| Exit code | Verdict      | Meaning                                                            |
+| --------- | ------------ | ------------------------------------------------------------------ |
+| 0         | `PASS`       | The stored data matches, and the answer is correct                 |
+| 1         | `FAIL`       | A line differs, or the answer is wrong                             |
+| 2         | `UNVERIFIED` | A source or a snapshot could not be read. The grade proves nothing |
+
+`--json` prints one JSON object: `verdict`, `state.removed` and `state.added` (every line that differs), `state.ignored`, `answer` and `unread`. The text output shows the first 10 lines on each side and says how many it left out.
+
+## Snapshot
+
+`grade snapshot --state <file> --out <file>` reads each declared source and writes its rows as `state <label> <row>` lines, sorted. A snapshot keeps every row: unlike `compare`, it has no 1000-row cap, so a changed row always names its record. A read that fails gives a `state read failed: <label>: <reason>` line, and the command exits 2.
+
+`--url <url>` adds the page the run ended on, as a `url` line. Use it for a task whose goal is to open a page. The fragment and a final slash are removed, and the query values are sorted.
+
+## Check the answer
+
+A task that asks a question has a final answer. A fixed answer string goes stale when the data changes. Declare a source whose rows are the correct answer instead, and `judge` reads it when it grades:
+
+```json
+{
+  "answer": {
+    "source": {
+      "kind": "command",
+      "label": "answer",
+      "container": "shop-db",
+      "command": "mysql -N shop -e \"select count(*) from sales_order where customer_email = 'jane@example.com'\""
+    },
+    "match": "number",
+    "none": ["N/A"]
+  }
+}
+```
+
+Give the file with `--expect`, and the run's answer with `--answer`. Text is folded before it is compared: Unicode normal form, lower case, spacing, quotes and a final full stop.
+
+| `match` | The answer passes when |
+| --- | --- |
+| `exact` (default) | It is the one value in the rows. With more than one row, it is checked as `set` |
+| `number` | It is one number and nothing else, equal to the first value within 0.005. `$`, `%` and digit-group commas are removed. `3 orders` and `3 or 4` fail |
+| `set` | It is a list (split on commas, semicolons and new lines, or also on "and") with each value one time and nothing more, in any order |
+| `includes` | It contains each value. An answer that names every choice also passes, so use it only where the run cannot list all choices |
+
+A source with no rows means that the task cannot be done. Then the answer must be one of the `none` words. The default is `N/A`. A row with more than one column is one value, with the columns joined by a space.
+
+## Write the declaration
+
+The declaration must list every table that a run can change, or a change to that table is not seen. Do not write it by hand. Generate it, then remove the tables that change on every run:
+
+```bash
+# 1. One source for each table.
+npx @reticlehq/server grade tables --container shop-db --skip queue_,cron_ --list "mysql -N shop -e 'show tables'" --rows "mysql -N shop -e 'select * from {table}'" --out wide.json
+
+# 2. Two snapshots of the correct steps, from a reset app each time.
+npx @reticlehq/server grade snapshot --state wide.json --out reference.json
+npx @reticlehq/server grade snapshot --state wide.json --out again.json
+
+# 3. Keep the tables that read the same on both runs.
+npx @reticlehq/server grade suggest --state wide.json --reference reference.json --again again.json --out state.json
+```
+
+`tables` takes the first column of each line of the `--list` output as a table name. It skips a name with a character other than A-Z, 0-9, `_` or `$`, and says so. `{table}` in `--rows` is the table name.
+
+`--skip <prefix,...>` leaves out each table whose name starts with one of the prefixes. Separate the prefixes with commas. Use it for tables that hold no task data and that the app changes at its own time: a message queue that a background worker empties, a cron schedule, a session store. Two correct runs do not always show these tables as noise, because the worker can finish before both snapshots and not before a third. For Magento, `--skip queue_,cron_,session`.
+
+Some apps write an empty row that means the same as no row. Magento saves a product form with a `NULL` row for each empty attribute, so a run that saves the form one more time than the reference adds rows with no value. Add an `ignore` pattern that matches all of such a row to the source in `state.json`. A pattern that removes all of a row removes the row. For the Magento attribute tables (`catalog_product_entity_int`, `_decimal`, `_varchar`, `_text`, `_datetime`), use `"ignore": ["^\\d+\\t\\d+\\t\\d+\\t\\d+\\tNULL$"]`.
+
+`suggest` keeps a source that reads the same on both runs, also a source the correct steps did not change: a change to it by a run is a change to a record the task did not name. A source that differs between the two runs only by a date and time is kept, with the time removed. Every other source that differs (a session table, a log) is dropped, because each run adds its own new rows to it, and every run would fail. Each dropped source is printed with the first row that differs. A change to a dropped table is not seen.

package/docs/cli/help.mdx

@@ -33,7 +33,7 @@ Get started
   try         Watch Reticle drive a URL once and say which journeys work
 
 Check your app
-  verify      Check the saved flows against the running app; exit 0 means pass
+  verify      Check saved flows, or one claim with --expect, against the running app; exit 0 = pass
   gate        Fail unless passing checks cover the flows your changes touch
 
 Reticle on this machine
@@ -85,5 +85,7 @@ Two audiences, two channels: the structured line for logs and scripts, the plain
 | `1`  | Help was printed because something else was wrong |
 
 <Note>
-  A bare `reticle` with no arguments is **not** help. It is [`reticle serve`](/cli/serve).
+  A bare `reticle` with no arguments is **not** help. In a wired project it is [`reticle
+  serve`](/cli/serve). In a folder that Reticle has not wired, it gives a first verdict on the app:
+  see [the CLI reference](/cli).
 </Note>

package/docs/cli/license.mdx

@@ -1,36 +1,37 @@
 ---
-title: reticle license
-description: Show the enterprise license status resolved from the environment, offline.
+title: License status
+description: Show the enterprise license status resolved from the environment, offline, with reticle status.
 icon: key
 ---
 
-`reticle license` reports whether an enterprise license is active. It resolves entirely from the environment. Nothing leaves the machine.
+[`reticle status`](/cli/status) reports whether an enterprise license is active. It resolves the license entirely from the environment. Nothing leaves the machine.
 
 ```bash
-npx @reticlehq/server license
+npx @reticlehq/server status --json
 ```
 
-No flags.
+The block that `status` prints has a `license` row only when a key is set. `--json` always carries the `license` object.
+
+`reticle license` is the old name. It still works for one release, prints one line naming `status`, and prints the `reticle_license` line below.
 
 ## What it prints
 
-One `reticle_license` JSON line, on stderr. On a checkout with no issuer key configured:
+The `license` object of `status --json`. `reticle license` printed the same fields as one `reticle_license` JSON line on stderr. On a checkout with no issuer key configured:
 
 ```json
 {
   "t": "2026-08-15T18:42:26.758Z",
   "event": "reticle_license",
-  "gated": ["audit-log"],
   "contact": "hey@reticle.sh",
   "status": "eval",
-  "detail": "evaluation mode: enterprise features run free (no issuer key configured)"
+  "detail": "evaluation mode (no issuer key configured)"
 }
 ```
 
 | `status`  | Meaning                                             |
 | --------- | --------------------------------------------------- |
 | `active`  | A valid license is present                          |
-| `eval`    | Evaluation mode. Enterprise features run free       |
+| `eval`    | Evaluation mode. No issuer key is configured        |
 | `missing` | No license, and the build expects one               |
 | `expired` | The key verified, but its expiry has passed         |
 | `invalid` | The key was rejected, or the build is misconfigured |
@@ -44,9 +45,9 @@ Always `0`.
 ## Worked example
 
 ```bash
-npx @reticlehq/server license 2>&1 | jq -r .status
+npx @reticlehq/server status --json | jq -r .license.status
 ```
 
-<Card title="What enterprise covers" icon="building" href="/enterprise">
-  The licensed surface, and what stays Apache 2.0.
+<Card title="Enterprise" icon="building" href="/enterprise">
+  License keys, the roadmap, and the licensing model.
 </Card>

package/docs/cli/restart.mdx

@@ -1,15 +1,17 @@
 ---
-title: reticle restart
+title: reticle serve --restart
 description: Free the bridge port and put a daemon back on it, reporting each half separately.
 icon: rotate
 ---
 
-`reticle restart` is [`reticle stop --force`](/cli/stop#freeing-the-port-force) followed by a daemon start that waits for a real bind.
+`reticle serve --restart` is [`reticle stop --force`](/cli/stop#freeing-the-port-force) followed by a daemon start that waits for a real bind.
 
 ```bash
-npx @reticlehq/server restart [--port N] [--force]
+npx @reticlehq/server serve --restart [--port N] [--force]
 ```
 
+`reticle restart` is the old name. It still works for one release and prints one line naming `serve --restart`.
+
 ## Flags
 
 | Flag | Type | Default | What it does |
@@ -31,7 +33,7 @@ Real capture, restarting over a running daemon (exit `0`), with the long `note`
 Real capture, when the port is held by something that is not ours (exit `1`). Both `reason` strings are trimmed at the ellipsis:
 
 ```
-{"t":"2026-08-15T18:43:57.317Z","event":"reticle_kill_refused","port":4498,"reason":"pid 78795 (\"Python\") is listening, and it is not a Reticle daemon ... it never answered /status and it is not the pid Reticle recorded. Killing it would be killing someone else's process. If that is what you meant, `reticle restart --force` stops it and starts Reticle there (`stop --force` never does); or start Reticle on another port.","holder":"Python"}
+{"t":"2026-08-15T18:43:57.317Z","event":"reticle_kill_refused","port":4498,"reason":"pid 78795 (\"Python\") is listening, and it is not a Reticle daemon ... it never answered /status and it is not the pid Reticle recorded. Killing it would be killing someone else's process. If that is what you meant, `reticle serve --restart --force` stops it and starts Reticle there (`stop --force` never does); or start Reticle on another port.","holder":"Python"}
 {"t":"2026-08-15T18:43:57.318Z","event":"reticle_restart_aborted","port":4498,"reason":"the port was not freed, so nothing was started ... the old holder is still there"}
 ```
 
@@ -51,7 +53,7 @@ Real capture, when the port is held by something that is not ours (exit `1`). Bo
 ## Worked example
 
 ```bash
-npx @reticlehq/server restart         # after an upgrade, so the new version is the one serving
+npx @reticlehq/server serve --restart   # after an upgrade, so the new version is the one serving
 npx @reticlehq/server status
 ```
 

package/docs/cli/rollback.mdx

@@ -1,16 +1,16 @@
 ---
-title: reticle rollback
+title: reticle update --rollback
 description: Reinstall the previously installed Reticle server version, then exit so your agent restarts it.
 icon: arrow-rotate-left
 ---
 
-`reticle rollback` is the undo for [`reticle update`](/cli/update). It reinstalls the version `update` replaced (recorded in the update manifest), then exits so the next start runs it.
+`reticle update --rollback` is the undo for [`reticle update`](/cli/update). It reinstalls the version `update` replaced (recorded in the update manifest), then exits so the next start runs it.
 
 ```bash
-npx @reticlehq/server rollback
+npx @reticlehq/server update --rollback
 ```
 
-No flags.
+`reticle rollback` is the old name. It still works for one release and prints one line naming `update --rollback`.
 
 ## What it prints
 
@@ -36,6 +36,6 @@ On the global install the installer puts on your PATH (under `npx` there is noth
 ```text
 reticle update
 # the new build misbehaves:
-reticle rollback
+reticle update --rollback
 reticle version
 ```

package/docs/cli/setup.mdx

@@ -14,10 +14,21 @@ No flags, and nothing is asked. It works for your user account, not for one proj
 
 ## What it prints
 
-One line per agent: `✓ <agent>` for a new registration, `✓ <agent> (already set up)` when Reticle was there already, `⚠ <agent>: Reticle registration failed…` when a registration failed (the command then exits `1`), and `⚠ <agent>: add the reticle entry to <path> by hand` for a config it will not rewrite. If it finds no agent, it names every agent it looked for.
+A `Your agents:` block, with one line for each agent and the one next step for that agent:
+
+```text
+Your agents:
+  Claude Code  plugin active: type /reload-plugins if it is open
+  Cursor       added: restart Cursor, then turn Reticle on in Settings › MCP
+  Codex        added: restart Codex, then /mcp shows reticle
+```
+
+`already set up` means that Reticle was there already. `registration failed` gives the command to retry, and the command then exits `1`. `not added: add the reticle entry to <path> by hand` is for a config that it does not rewrite. If it finds no agent, it names every agent it looked for.
+
+In a terminal, and not in CI, it then waits up to 60 seconds for each agent to connect. Then it prints `Connected: <agent> ✓`, or the step that is still missing for that agent. Press Ctrl+C to stop the wait. [`reticle status`](/cli/status) shows the same lines later.
 
 ## How you know it worked
 
-Restart your coding agent. An agent reads its server list only when it starts. After the restart, the `reticle_*` tools are listed.
+Do the next step for your agent. Most agents read their server list only when they start. The Claude Code plugin loads with `/reload-plugins`. Then the `reticle_*` tools are listed, and `reticle status` shows `Connected: <agent> ✓`.
 
 Codex CLI keeps a TOML config. When the `codex` binary is on your PATH, Reticle registers through `codex mcp add`. Otherwise it prints the hand-edit lines above. Reticle then adds one line, `default_tools_approval_mode = "approve"`, under `[mcp_servers.reticle]` in `~/.codex/config.toml`. This line approves Reticle's own tools, so Codex does not ask before each call. Reticle changes no other line, and it keeps a mode that you set. To undo it, change that line to `default_tools_approval_mode = "prompt"`. Reticle does not change a mode that is already there.

package/docs/cli/status.mdx

@@ -35,8 +35,12 @@ reticle status
                http://localhost:5173/  (throttled, hidden)
                http://localhost:7699/  (throttled, hidden)
   agent link   ✓ your agent has read and used Reticle's tools
+  agents       Connected: Claude Code ✓
+               Cursor not connected yet: restart Cursor, then turn Reticle on in Settings › MCP
 ```
 
+The `agents` row has one line for each coding agent on this machine. A line shows `✓` when that agent connected to Reticle at least one time. Otherwise it shows the step that is still missing. `reticle setup mcp` prints the same lines.
+
 And with no daemon on the port:
 
 ```text