@reticlehq/server 3.9.0 → 3.10.1

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/init.mdx

@@ -122,8 +122,8 @@ In the two captures above, the punctuation that separates the two halves of the
 
 | Code | Meaning |
 | --- | --- |
-| `0` | The app connected. Steps marked `⚠` still need a hand, and do not change the code |
-| `1` | No session connected, init failed, an unknown flag was passed, or several apps were found and none was chosen |
+| `0` | The app connected. Or the files are written and the machine kept the dev server from starting (its port was taken, or it answered on one loopback address only): init prints the steps to confirm the connection (`--json` answers `"confirmed": false`). Steps marked `⚠` still need a hand, and do not change the code |
+| `1` | The dev server exited, hung or does not exist, a running app did not connect, init failed, an unknown flag was passed, or several apps were found and none was chosen |
 
 An unknown flag is rejected by name: `reticle init --bogus` prints `unknown argument '--bogus'`, then the short usage (`reticle --help`), and exits `1`.
 

package/docs/cli/license.mdx

@@ -1,20 +1,22 @@
 ---
-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
 {
@@ -43,7 +45,7 @@ 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="Enterprise" icon="building" href="/enterprise">

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/stop.mdx

@@ -10,7 +10,7 @@ icon: circle-stop
 npx @reticlehq/server stop [--port N] [--quiet] [--force]
 ```
 
-`reticle kill` is the old name for `stop --force`. It still works for one release and prints one line naming the new spelling.
+`reticle kill` was removed. It prints that `stop --force` replaces it and exits `1`.
 
 ## Flags
 
@@ -94,7 +94,7 @@ Killed:
 Refused, because the listener is not ours. This one was captured with `python3 -m http.server 4498` holding the port:
 
 ```
-{"t":"2026-08-15T18:43:57.128Z","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.128Z","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"}
 ```
 
 Nothing to free:
@@ -118,6 +118,6 @@ With `--force`, exit `0` means the port is free and `1` means it is still held:
 
 ```bash
 npx @reticlehq/server stop --port 4400 --quiet && npx @reticlehq/server serve --port 4400
-npx @reticlehq/server restart --port 4400   # the same thing, honest about each half
+npx @reticlehq/server serve --restart --port 4400   # the same thing, honest about each half
 npx @reticlehq/server stop --force          # the port is held and the pid file says nothing
 ```

package/docs/cli/update.mdx

@@ -61,6 +61,6 @@ npx @reticlehq/server update
 <Warning>
   A daemon that is already running keeps its own version. When no tab and no other agent is attached
   to it, your agent's new MCP server stops it and starts the new version. When a tab or another
-  agent is attached, the old daemon keeps running. Run [`reticle restart`](/cli/restart) to start
-  the new version now.
+  agent is attached, the old daemon keeps running. Run [`reticle serve --restart`](/cli/restart) to
+  start the new version now.
 </Warning>

package/docs/cli/verify.mdx

@@ -20,12 +20,13 @@ It uses the same runner and the same verdict as the MCP and HTTP paths, so a pla
 | `--headed` | boolean | `false` (headless) | Show the browser |
 | `--timeout N` | number, ms | `15000` | How long to wait for a browser session to dial back. With `--expect`, how long the predicate may take to come true instead, default `4000` |
 | `--storage-state <file>` | string | unset | A Playwright storage state file. This is how you verify flows behind a login without scripting the login every time |
-| `--results-json <file>` | string | unset | Also write one verdict per journey to this file: `{ verdict, results: [{ journey, verdict, reason?, runId? }] }`, each verdict `yes`, `no` or `unknown`. A skipped journey is `unknown`, and the run is `yes` only when every journey is. `runId` names the run the journey came from, and is set only when that run reached the platform. Written when verify boots its own browser and a run finishes; a refusal before that writes nothing. The [GitHub Action](https://github.com/reticlehq/reticle/tree/main/action) posts this file |
+| `--results-json <file>` | string | unset | Also write one verdict per journey to this file: `{ schemaVersion, verdict, results: [{ journey, verdict, reason?, runId?, steps }], score }`, each verdict `yes`, `no` or `unknown`. `schemaVersion` is 2 (a file without it has only `verdict` and `results`). `steps` is `{ passed, failed, unknown }` for the journey, and `score` is the total with `value` = passed / total. A step counts only when every earlier step of its journey passed; a step never reached is `unknown` and stays in the total. With `--sweep`, verdicts after a failed step are reported apart as `steps.swept` and never raise the score. A skipped journey is `unknown`, and the run is `yes` only when every journey is. `runId` names the run the journey came from, and is set only when that run reached the platform. Written when verify boots its own browser and a run finishes; a refusal before that writes nothing. The [GitHub Action](https://github.com/reticlehq/reticle/tree/main/action) posts this file |
 | `--port N` | number | `RETICLE_PORT`, else the project's port, else `4400` | The bridge port the app dials |
 | `--session-id <id>` | string | unset | Use a tab that is already connected |
 | `--select <label>` | string, repeatable | unset | Verify only flows carrying this label |
 | `--expect '<json predicate>'` / `--expect-file <path>` | string | unset | One verdict on one predicate, no saved flows needed. Asks the daemon that owns the port and never starts one; with no daemon it refuses. Waits up to `--timeout` for the predicate, the way `reticle_assert { action: "wait" }` does, so a request still in flight after the page loads is waited for. Exits `0` only on `verified: "yes"`. Cannot be combined with `--storage-state` |
 | `--explore` / `--persona "<who does what>"` | boolean / string | off | No saved flows yet? The Harness drives the app and records them. `--persona` implies `--explore`. Needs a linked project (`reticle connect`, or `RETICLE_API_KEY` in CI). It runs at any instrumentation score |
+| `--against <reference-url>` | string | unset | Compare the URL with a reference build, for example a pull request preview with production. See [Compare two builds](#compare-two-builds). Cannot be combined with `--expect`, `--expect-file`, `--explore` or `--persona` |
 | `--confirm-dangerous` | boolean | off | Let this run press the controls the replay guard holds as destructive, such as a "Place order" or "Delete" button in a saved flow. Without it such a step is refused, so a checkout flow cannot pass. It covers this run only and is never saved into a flow. |
 
 On Windows PowerShell, write the predicate to a file and pass `--expect-file` so the JSON never goes through shell quoting:
@@ -35,6 +36,27 @@ On Windows PowerShell, write the predicate to a file and pass `--expect-file` so
 npx @reticlehq/server verify http://localhost:3000 --expect-file expect.json
 ```
 
+## Compare two builds
+
+```bash
+npx @reticlehq/server verify https://pr-42.preview.example.com --against https://example.com
+```
+
+`--against` answers one question: did the change alter what users see? It drives both running builds with the same actions and reports each difference in what a person can read and use.
+
+- **The actions.** Each saved flow in `.reticle/flows/` (with `--select`, only the flows with those labels) is replayed one step at a time, and the page is read after every step. Then the explorer of `reticle_verify { action: "crawl", exhaustive: true }` walks the reference breadth first. It fills each empty text field with its own value (`text 1`, `text 2`), clicks each control, and waits a short time after each action. Both builds then get the same list of actions.
+- **What is compared.** The accessibility tree, reduced to what a person sees: names, text, values, and the checked, selected, disabled, expanded and pressed states, in page order. Case and spacing are folded. Refs, focus, layout, test ids, source locations and component names are removed.
+- **Noise.** The reference is driven two times, each time in a new browser. A line that differs between those two runs (a clock, a random id) is ignored. A step that the reference did on only one of its runs is not compared.
+- **A step the candidate cannot do.** When the reference did a step and the candidate could not (the control is gone, or a flow anchor does not resolve), that is a difference.
+
+The command uses the daemon on `--port`, and starts one when there is none. Each run is a leased browser tab, so the apps do not need `reticle init`. Each replayed flow step is written as a run, the same as any replay.
+
+The explorer clicks every control it finds. The action guard refuses a control it holds as destructive, and `--confirm-dangerous` removes that guard. Point `--against` at a build whose data you can change, not at a production database.
+
+Each difference prints the actions that first reached it, then `-` for the lines only the reference shows and `+` for the lines only the candidate shows. Differences with the same lines are printed one time, with the number of steps they were seen at. Exit `0` only when steps were compared and nothing differs. A run that compared no step exits `1`, because it proved nothing.
+
+`--results-json <file>` writes `{ schemaVersion: 1, reference, candidate, identical, differences: [{ id, kind, actions, removed, added, seen }], journeys, compared, unstable, ignored, explored }`. `kind` is `changed` or `unreached`. `id` is a hash of the difference's lines, so the same difference has the same id on every run. `ignored` counts the lines skipped as noise, and `unstable` counts the steps not compared.
+
 ## What it prints
 
 The rendered run report on stdout. On failure it names the cause on stderr instead, and there are two refusals worth knowing:

package/docs/cli.mdx

@@ -41,18 +41,20 @@ npx @reticlehq/server <command>
 | Command | What it does | Page |
 | --- | --- | --- |
 | `reticle verify <url>` | One-shot: drive the URL, verify saved flows or one predicate, exit 0 on pass | [verify](/cli/verify) |
+| `reticle compare <reference-url> <candidate-url> [--base <url>] [--state <file>] [--json] [--report <file>]` | Drive two running builds the same way and list each difference in what users see; exit 0 same, 1 different, 2 invalid | [compare](/cli/compare) |
+| `reticle grade <snapshot\|judge\|tables\|suggest> [flags]` | Grade a finished run of an app from snapshots of its stored data, and check its final answer; exit 0 pass, 1 fail, 2 unverified | [grade](/cli/grade) |
 | `reticle gate [--since <ref>] [--accept-coverage] [--hook]` | Exit non-zero unless passing artifacts cover the affected flows | [gate](/cli/gate) |
+| `reticle gate --list [--since <ref>]` | Which saved flows must re-verify for the changed files | [affected](/cli/affected) |
 
 ### Reticle on this machine
 
 | Command | What it does | Page |
 | --- | --- | --- |
-| `reticle status [--json]` | Is the daemon up, which pages connected, who is signed in, is this repo linked | [status](/cli/status) |
+| `reticle status [--json]` | Is the daemon up, which pages connected, who is signed in, is this repo linked, which license is active | [status](/cli/status) |
 | `reticle doctor` | Find what is wrong with the setup (Chromium, daemon, port, agent link), and what is missing from coverage | [doctor](/cli/doctor) |
 | `reticle open [url]` | Show the app: reuse the connected tab, else open one | [open](/cli/open) |
 | `reticle stop [--force]` | Stop the daemon we started; `--force` frees the port by its listener, never the agent's MCP proxy | [stop](/cli/stop) |
-| `reticle restart` | Free the port, then start a daemon and wait for a real bind | [restart](/cli/restart) |
-| `reticle update` | Install the latest server version and restart | [update](/cli/update) |
+| `reticle update [--rollback]` | Install the latest server version and restart; `--rollback` restores the previous one | [update](/cli/update) |
 
 ### Account
 
@@ -75,14 +77,11 @@ npx @reticlehq/server <command>
 | `reticle config` | Choose what syncs: runs, memory, flows; where verification runs | [cloud](/cli/cloud#reticle-config) |
 | `reticle hook [status\|install\|uninstall]` | The prompt hook: is each prompt captured here, add it, or remove exactly what was added | [prompt capture](/prompt-capture#reticle-hook) |
 | `reticle setup mcp` | Register the MCP server with your coding agents (the installer's registration half) | [setup](/cli/setup) |
-| `reticle serve` | Start the daemon and wait for it to bind | [serve](/cli/serve) |
+| `reticle serve [--restart]` | Start the daemon and wait for it to bind; `--restart` frees the port first | [serve](/cli/serve) |
 | `reticle mcp` | The MCP stdio proxy your agent runs; starts the daemon if needed | [mcp](/cli/mcp) |
 | `reticle drive <url>` | Foreground mode, for debugging | [drive](/cli/drive) |
-| `reticle affected [--since <ref>]` | Which saved flows must re-verify for the changed files | [affected](/cli/affected) |
 | `reticle context --compact [--session <id>]` | Resume after a compaction: what was proved, failed and is still owed | none |
 | `reticle report [--session <id>] [--hook]` | What the latest session claimed, and what held | [report](/cli/report) |
-| `reticle rollback` | Restore the previous server version and restart | [rollback](/cli/rollback) |
-| `reticle license` | Enterprise license status: active, eval or missing | [license](/cli/license) |
 | `reticle version` | Print the version | [version](/cli/version) |
 | `reticle help [all\|<command>]` | Usage: the short list, every command, or one command | [help](/cli/help) |
 
@@ -90,16 +89,27 @@ npx @reticlehq/server <command>
 
 The old names below still work for one release and print one line naming the new one.
 
-| Old | Now |
+| Old                | Now                         |
+| ------------------ | --------------------------- |
+| `reticle affected` | `reticle gate --list`       |
+| `reticle license`  | `reticle status`            |
+| `reticle rollback` | `reticle update --rollback` |
+| `reticle restart`  | `reticle serve --restart`   |
+
+These names were removed. Each prints what to use instead and exits `1`.
+
+| Removed | Use |
 | --- | --- |
 | `reticle kill` | `reticle stop --force` |
-| `reticle login`, `reticle link` | `reticle connect`. `reticle login --email` is gone: sign-in is only in the browser, with Google or GitHub. Without a browser, set `RETICLE_API_KEY` |
+| `reticle login`, `reticle link` | `reticle connect`. Sign-in is only in the browser, with Google or GitHub. Without a browser, set `RETICLE_API_KEY` |
 | `reticle project` | `reticle connect --project <name\|id>` |
 | `reticle whoami` | `reticle status` |
 | `reticle push` | `reticle sync` |
 | `reticle regression`, `share`, `issues`, `memory` | `reticle runs regression`, `runs share`, `runs issues`, `runs memory` |
-
-`hunt`, `watch`, `capsules`, `tutorial` and `identify` were removed. Each prints what to use instead and exits `1`: `reticle affected` or `reticle gate` for `watch`, `reticle init` or `reticle try <url>` for `tutorial`, `reticle feedback` for `identify`. Saved capsules stay in `.reticle/capsules`.
+| `reticle watch` | `reticle gate --list` or `reticle gate` |
+| `reticle tutorial` | `reticle init` or `reticle try <url>` |
+| `reticle identify` | `reticle feedback` |
+| `reticle hunt`, `reticle capsules` | nothing. Saved capsules stay in `.reticle/capsules` |
 
 ## Setup and diagnosis
 
@@ -192,7 +202,7 @@ policy       https://github.com/reticlehq/reticle/blob/main/docs/telemetry.md
 | `reticle serve` | Start the daemon and wait for it to bind. `--drive <url>`, `--headless`, `--headed`, `--http`, `--http-port N`, `--http-token T` |
 | `reticle stop` | Stop the daemon we started, by its recorded pid. `--quiet` |
 | `reticle stop --force` | Free the port by asking who is **listening** on it |
-| `reticle restart` | Free the port, then start a daemon and wait for a real bind. `--force` |
+| `reticle serve --restart` | Free the port, then start a daemon and wait for a real bind. `--force` |
 | `reticle open [url]` | Show the app. Reuse the connected tab, or open one |
 | `reticle drive <url>` | Foreground mode, for debugging |
 | `reticle mcp` | The MCP stdio proxy. Auto-starts the daemon if needed. This is what your agent runs |
@@ -203,7 +213,7 @@ A bare `reticle` with no arguments is not help. In a project that `init` wired,
   When the Reticle SDK installed in the project is a different **major** version from the CLI you ran,
   the CLI hands the same command to `npx @reticlehq/server@<that version>`, so an unpinned
   `npx @reticlehq/server` never pairs a daemon with an SDK it cannot talk to. `init`, `update`,
-  `rollback`, `setup install`, `version` and `help` always run as typed, and so does a command whose
+  `update --rollback`, `setup install`, `version` and `help` always run as typed, and so does a command whose
   version you pinned yourself (`npx @reticlehq/server@<version> …`). Set `RETICLE_NO_VERSION_MATCH=1` to
   turn it off. Because `--help` runs as typed too, it describes the CLI you ran. When the command it
   describes would run at the project's version instead, the help opens with a line naming that version.
@@ -238,12 +248,12 @@ Options:
 - `--results-json <file>`: also write one verdict per journey as JSON, for CI.
 - `--confirm-dangerous`: let this run press what the replay guard holds as destructive.
 
-### `reticle affected`
+### `reticle gate --list`
 
-Which saved flows must re-verify for a set of changed files.
+Which saved flows must re-verify for a set of changed files. It checks nothing.
 
 ```bash
-npx @reticlehq/server affected --since HEAD~1
+npx @reticlehq/server gate --list --since HEAD~1
 ```
 
 ```json
@@ -290,13 +300,13 @@ Measured exit code: **`1`**, with the flow lists trimmed above. That run genuine
 
 ## Maintenance
 
-| Command            | What it does                                        |
-| ------------------ | --------------------------------------------------- |
-| `reticle update`   | Install the latest server version and restart       |
-| `reticle rollback` | Restore the previous version and restart            |
-| `reticle license`  | Enterprise license status: active, eval, or missing |
-| `reticle version`  | Print the version                                   |
-| `reticle help`     | The short list; `help all` for every command        |
+| Command                     | What it does                                                 |
+| --------------------------- | ------------------------------------------------------------ |
+| `reticle update`            | Install the latest server version and restart                |
+| `reticle update --rollback` | Restore the previous version and restart                     |
+| `reticle status --json`     | Carries `license`: active, eval, missing, expired or invalid |
+| `reticle version`           | Print the version                                            |
+| `reticle help`              | The short list; `help all` for every command                 |
 
 <Tip>
   `rollback` exists because an auto-updating dev tool that cannot go back is a dev tool that can

package/docs/deploy-checks.md

@@ -70,7 +70,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: reticlehq/reticle/action@v3.9.0
+      - uses: reticlehq/reticle/action@v3.10.1
         with:
           api-key: ${{ secrets.RETICLE_API_KEY }}
           # Only for a Vercel preview behind Deployment Protection.

package/docs/desktop.mdx

@@ -224,7 +224,7 @@ Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-por
 
 ```toml
 [dependencies]
-reticle-tauri = "3.9"
+reticle-tauri = "3.10"
 ```
 
 ```rust

package/docs/enterprise.md

@@ -22,7 +22,7 @@ No feature in the open packages needs a key. A key identifies your organisation
    export RETICLE_LICENSE_KEY="<your key>"
    # the release already bakes the issuer public key (RETICLE_LICENSE_PUBLIC_KEY)
    ```
-3. **Verify.** `reticle license` prints one JSON line whose `status` and `detail` say where you stand:
+3. **Verify.** `reticle status --json` carries a `license` object whose `status` and `detail` say where you stand:
 
    ```
    active    licensed to Acme Corp (enterprise), expires 2027-06-20T00:00:00.000Z
@@ -36,7 +36,7 @@ No feature in the open packages needs a key. A key identifies your organisation
 
 4. **Renew.** Keys carry an expiry, shown as `expiresAt`; once it passes, the status is `expired`.
 
-> Procuring a license: contact **[hey@reticle.sh](mailto:hey@reticle.sh)**. Keys are issued offline and signed with Ed25519; the activation you run (`reticle license`) verifies them locally with no network call.
+> Procuring a license: contact **[hey@reticle.sh](mailto:hey@reticle.sh)**. Keys are issued offline and signed with Ed25519; the activation check (`reticle status`) verifies them locally with no network call.
 
 ## Roadmap
 

package/docs/environment.mdx

@@ -53,7 +53,7 @@ Reticle works with none of these set. Each one changes a single behaviour, and m
 | Variable | Read by | What it does |
 | --- | --- | --- |
 | `RETICLE_SKIP_GATE` | `reticle gate --hook` | Lets an agent's stop hook proceed past a failing gate. The skip is printed and recorded, never silent. It does not affect `reticle gate` without `--hook`, which is what CI runs. |
-| `RETICLE_NO_CI_HINT` | `reticle gate`, `reticle verify`, `reticle affected` | `1` stops the one line these commands write to stderr at the end of a run in a CI runner or a container. The line names the pull request check and `https://reticle.sh/ci`. It never prints in an interactive terminal or for `gate --hook`, and it makes no network call. |
+| `RETICLE_NO_CI_HINT` | `reticle gate`, `reticle verify` | `1` stops the one line these commands write to stderr at the end of a run in a CI runner or a container. The line names the pull request check and `https://reticle.sh/ci`. It never prints in an interactive terminal or for `gate --hook`, and it makes no network call. |
 | `RETICLE_VERIFY_TOKEN` | `reticle serve --http` | The bearer token the optional HTTP verify endpoint requires. |
 | `RETICLE_SECRET_<FIELD>` | replay, verify, crawl | The value typed into a password or secret field at replay. A recorded flow never stores it. See [what is recorded](/what-is-recorded). |
 

package/docs/flows.md

@@ -80,7 +80,7 @@ reticle_run({ tool: "reticle_flow_save", args: { flowName: "create-task" } })
 }
 ```
 
-Each step binds to a **semantic anchor**, never a `eXX` ref: a `testid`/`signal` when available, else an auto-derived `component` anchor (component name + source `file:line`) for an element with no testid, so the flow stays stable with zero hand-added testids. A press of a document key (Escape, Tab, a shortcut) with no target is aimed at no element, so it is saved with a `{ "kind": "role", "role": "document" }` anchor and replayed at the document, as it ran. Only when none of those resolve is a step kept `degraded: true` (a last-resort "add a testid here" marker) rather than silently dropped.
+Each step binds to a **semantic anchor**, never a `eXX` ref: a `testid`/`signal` when available, else an auto-derived `component` anchor (component name + source `file:line`) for an element with no testid, so the flow stays stable with zero hand-added testids. A press of a document key (Escape, Tab, an arrow key, a shortcut) with no target is aimed at no element, so it is saved with a `{ "kind": "role", "role": "document" }` anchor and replayed at the document, as it ran. Only when none of those resolve is a step kept `degraded: true` (a last-resort "add a testid here" marker) rather than silently dropped.
 
 ## Run a flow
 
@@ -110,6 +110,16 @@ Every session's driving is saved as a flow at teardown when it declared a conseq
 - declare `requires` (the start page) and `ensures` (the end page) as route claims, so `canFollow` can tell which flows chain. Replay treats a required start page as met by navigating there;
 - carry `author: { agent, person }`: the MCP client that drove it and the email of whoever signed in with `reticle connect` on that machine. Either is left out when it is not known.
 
+### A route in `requires`
+
+A route claim in `requires` says which page the flow needs. Replay puts the tab there before step 1, so a suite does not run the flow on the page that the previous flow left open. It goes to `startPath` when that is on the route, else to the route itself.
+
+A route can name an entity id with a `:name` segment, for example `{ "kind": "route", "pathname": "/cases/:id/notes" }`. When the tab is already on a page that matches, replay keeps that page and its id. When the tab is on another page of the same record (`/cases/c-42/files`), replay opens the route with that id (`/cases/c-42/notes`). It opens the recorded address only when the tab has no id to give. The recorded id can be a record that was deleted since.
+
+Replay checks every route claim in `requires`, its `contains` too, on the page it arrives at. When the tab is already on the route, replay reloads it, the same reset a `startPath` gets. State that the previous flow left in memory is lost. A flow that needs that state declares it with a claim that is not a route.
+
+When replay cannot put the tab on the route (the page refuses, the app redirects to another page, or a pattern has no recorded address to open), the flow is `unverifiable` with a reason that names the route. No step runs.
+
 ## Delete a flow
 
 ```jsonc

package/docs/frameworks.mdx

@@ -5,7 +5,7 @@ description: Which frameworks Reticle supports, which are wired but unverified,
 icon: layer-group
 ---
 
-**React + Vite, Next.js, Remix and Astro are fully supported, each with an example app in CI: React + Vite and Next.js are driven to a verdict by the e2e battery, and the Remix and Astro examples are booted and must register a session. SvelteKit, Nuxt, React Router framework mode, Create React App, Vue and Angular have their INSTALL gated: the install gate scaffolds each from scratch whenever the install path changes and requires a real session, but no gate drives them to a verdict. TanStack Start, Preact and plain HTML are wired by `init` and documented but not gated at all, so treat them as plausible rather than proven.** The exact wiring for each is below.
+**Reticle works on React, Next.js, Remix, Astro, Vue, SvelteKit and Angular. React + Vite, Next.js, Remix and Astro each have an example app in CI: React + Vite and Next.js are driven to a verdict by the e2e battery, and the Remix and Astro examples are booted and must register a session. Vue, SvelteKit and Angular are supported with the framework-neutral sensor; their install is gated (scaffolded from scratch whenever the install path changes, and a real session is required), and no CI gate drives them to a verdict yet. The `file:line` source pointer works on React and Svelte, not on Vue or Angular. Nuxt, React Router framework mode and Create React App have their install gated the same way. TanStack Start, Preact and plain HTML are wired by `init` and documented but not gated at all, so treat them as plausible rather than proven.** The exact wiring for each is below.
 
 Reticle is a verification layer that embeds a dev-only SDK in your running web app so an AI coding agent can prove a change works. Its core is framework-neutral: DOM, network, console, routing, animations and source mapping work anywhere JavaScript runs.
 
@@ -15,7 +15,7 @@ What varies is two things: how `connect()` gets into your app, and whether you g
 
 ## Where each framework stands
 
-We separate "we tested this" from "this should work". Four frameworks have an example app and a CI gate. The rest are wired and documented but nothing proves they still work.
+We separate "supported" from "what CI proves". Four frameworks have an example app and a CI gate. Vue, SvelteKit and Angular are supported and install gated. The rest are wired and documented, and nothing in CI proves they still work.
 
 Two columns say different things and it is worth keeping them apart. **CI gate** `yes` means an example app runs in CI: React + Vite and Next.js are driven to a verdict, Remix and Astro are booted and must register a session. **install only** means the install gate scaffolds that stack from scratch, runs `init`, boots it and waits for a session, so the setup is proven and the drive is not. Vue is there because a release once nearly shipped an installer that left a Vue app connecting 0% of the time, and the gate that exists for exactly that had only React scaffolds.
 
@@ -27,14 +27,14 @@ Two columns say different things and it is worth keeping them apart. **CI gate**
 | **Next.js** | yes | yes | yes | yes | Supported |
 | **Remix** | yes | yes | yes | yes | Supported |
 | **Astro** | yes | yes | yes | yes | Supported |
-| **SvelteKit** | yes | no | install only | unproven | Install gated, drive unverified |
+| **SvelteKit** | yes | no | install only | yes | Supported |
 | **TanStack Start** | yes | no | no | unproven | Wired, unverified |
 | **Nuxt** | yes | no | install only | no | Install gated, drive unverified |
 | **React Router (framework mode)** | yes | no | install only | yes | Install gated, drive unverified |
 | **Create React App** | yes | no | install only | unproven | Install gated, drive unverified |
-| **Angular 17+** | yes | no | install only | no | Install gated, drive unverified |
+| **Angular 17+** | yes | no | install only | no | Supported (no `file:line`) |
 | **Plain HTML** | yes | no | no | no | Wired, unverified |
-| **Vue (non-Nuxt)** | as Vite | no | install only | no | Install gated, drive unverified |
+| **Vue (non-Nuxt)** | as Vite | no | install only | no | Supported (no `file:line`) |
 | **Preact** | as Vite | no | no | transform-tested; drive unproven | Sensor, React adapter via `preact/compat` |
 | **Server-rendered (Django, Flask, FastAPI, Streamlit, Rails)** | yes | no | no | no | Wired, unverified |
 
@@ -392,10 +392,10 @@ Solid appears in dependency detection but has no wiring, no adapter and no gate.
   </Accordion>
 
 <Accordion title="Does Reticle work with Vue?">
-  Partly, and the limit is specific. Install `@reticlehq/browser` rather than the React kit, and you
-  get DOM, network, console, routing, actions and Pinia state. What you do not get is a `source`
-  field: source stamping covers JSX and Svelte components, and a Vue single-file component is
-  neither. The install path is covered by a gate; the drive is not.
+  Yes. Install `@reticlehq/browser` rather than the React kit, and you get DOM, network, console,
+  routing, actions, verdicts and Pinia state. The one thing you do not get is a `source` field:
+  source stamping covers JSX and Svelte components, and a Vue single-file component is neither. The
+  install path is gated in CI; no example app is driven to a verdict there yet.
 </Accordion>
 
 <Accordion title="Which framework should I pick if I want the strongest verdicts?">

package/docs/getting-started.md

@@ -287,7 +287,7 @@ if (process.env.NODE_ENV !== 'production') {
 
 Change the `./reticle.local.js` path so that it points to the project root from your entry module. Do not commit `reticle.local.js`: the token is for this machine only. A teammate runs `reticle init` to get their own.
 
-Plain HTML with no build step: run `npx @reticlehq/server init` in the folder that holds `index.html`. It adds a dev-only snippet that connects only on localhost, and puts this machine's pairing token in a gitignored `reticle.local.js` beside the page, so the token never lands in anything you publish. A hand-written script tag without that token is refused by the bridge.
+Plain HTML with no build step: run `npx @reticlehq/server init` in the folder that holds `index.html`. Init does not change `index.html`. It serves the folder with Reticle's static server, which adds a dev-only connect snippet to the page that it serves. With `--url` or `--files-only`, nothing of Reticle's serves the page, so init writes the snippet into `index.html`. That snippet connects only on localhost. Init puts this machine's pairing token in a gitignored `reticle.local.js` beside the page, so the token never lands in anything you publish. A hand-written script tag without that token is refused by the bridge.
 
 > **Want to watch the agent work?** Add `present: true` to `reticle.connect()` for a glowing border, a synthetic cursor that flies to targets, click/hover effects, and a narration HUD. See [usage §16](usage.md#16-presenter-mode-narration-&-fake-clock-watch-+-control).
 

package/docs/install-manual.mdx

@@ -202,7 +202,7 @@ Screenshots and headless mode need the Rust crate, which is versioned independen
 
 ```toml
 [dependencies]
-reticle-tauri = "3.9"
+reticle-tauri = "3.10"
 ```
 
 ```rust

package/docs/license-activation.mdx

@@ -67,10 +67,10 @@ Put the key in the MCP server's own `env` block instead, then restart the editor
 ## Confirm it worked
 
 ```bash
-npx @reticlehq/server license
+npx @reticlehq/server status --json
 ```
 
-You do not need `NODE_ENV` set, a project, a dev server, or a running app. This reads the key and nothing else.
+Read `license.status` in the output. You do not need `NODE_ENV` set, a project, a dev server, or a running app. The license check reads the key and nothing else.
 
 | `status` | What it means | What to do |
 | --- | --- | --- |
@@ -142,4 +142,4 @@ export RETICLE_TELEMETRY=0
 
 [hey@reticle.sh](mailto:hey@reticle.sh) for activation problems, renewals and re-issues.
 
-Include the output of `npx @reticlehq/server license`. It carries your license id and no secrets, and it usually tells us the answer immediately.
+Include the output of `npx @reticlehq/server status --json`. It carries your license id and no secrets, and it usually tells us the answer immediately.