@reticlehq/server 3.9.0 → 3.10.0

package/docs/predicates.mdx

@@ -316,7 +316,7 @@ This is the predicate that catches a UI-versus-store desync. A deploy that only
 { "kind": "animation", "name": "dialog-in", "completed": true }
 ```
 
-`target` narrows it to one element. `completed: false` matches an animation that is still running.
+`target` narrows it to one element by Reticle ref (`e12`) or CSS selector. `completed: false` matches an animation that is still running.
 
 ### settled
 

package/docs/quickstart.mdx

@@ -1,11 +1,11 @@
 ---
 title: 'Quickstart: proof in five minutes'
 sidebarTitle: Quickstart
-description: Install Reticle, connect your coding agent, and get a real verdict with evidence in about five minutes.
+description: Check your app with one command, connect your coding agent, and get a real verdict with evidence in about five minutes.
 icon: rocket
 ---
 
-**Run the installer once per machine, then `reticle init` once per project. The dashboard (`reticle connect`) is optional.** Skip `init` and your agent can still check the app with the zero-install lease, and it asks you before it wires the app. Reticle embeds a dev-only SDK in your running app and proves a browser session connected. No account needed for steps 1 and 2.
+**Start with one command in your app's folder: `npx @reticlehq/server`.** It checks the running app with nothing installed and prints a verdict. Then `npx @reticlehq/server init`, once per project, connects your coding agent. The dashboard (`reticle connect`) is optional. No account is needed for steps 1 and 2.
 
 By the end of this page your agent will click a button in your app and prove what happened: the request that fired, the state that changed, and the file to open if it didn't.
 
@@ -18,52 +18,47 @@ By the end of this page your agent will click a button in your app and prove wha
 
 - Node 20.11 or newer
 - A web app you can run locally, and its dev server
-- A coding agent that speaks MCP (Claude Code, Cursor, Codex, OpenCode, Windsurf, VS Code)
+- For step 2, a coding agent that speaks MCP (Claude Code, Cursor, Codex, OpenCode, Windsurf, VS Code)
 
-## Step 1. Install it on this machine
+## Step 1. Check your app, with nothing installed
 
-In a terminal, before you open your coding agent:
+In your app's folder:
 
-<CodeGroup>
-
-```bash macOS / Linux
-curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh
+```bash
+cd path/to/your-app
+npx @reticlehq/server
 ```
 
-```powershell Windows
-irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex
-```
+It finds your app's dev server. If the app does not run, it starts the dev script, and it stops that server at the end. It opens the app in a Reticle browser and installs nothing in your app. It checks that the page loads, that there is no console error and no failed request, and that each same-origin link opens (8 at most). On a small app with two links, it printed:
 
-</CodeGroup>
-
-This puts `reticle` on your PATH and registers the MCP server with every coding agent it can reach: Claude Code, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Copilot CLI, OpenCode, Antigravity, Warp, Kiro, Amazon Q, Cline, Roo Code, Amp, Continue and Factory Droid. Nothing is asked. It does not wire your app, and says so: that is step 2. Want a verdict first? Signed in, `reticle try <url>` drives a URL once in a window you watch.
+```text
+Starting your dev server: npm run dev
+Reticle is checking http://localhost:58440/. It installs nothing in your app.
+  ✓ The page loads.
+  ✓ No console error.
+  ✓ No failed request.
+  ✓ 2 of 2 link(s) opened with no fault.
+```
 
-Codex CLI keeps a TOML config. With the `codex` command installed, the installer registers Reticle through `codex mcp add`. Without it, the installer prints the lines to paste and the file to paste them into. 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.
+Then the verdict line, `verified: yes` with the URL it checked, and the next step, `npx @reticlehq/server init`. A fault gives `verified: no`, and one `✗` line for each fault, for example `✗ Failed request on /broken: GET http://localhost:58473/api/missing: HTTP 404`. The command exits 0 only on `yes`. When the app sends the page to a sign-in page, Reticle verifies up to there and says so.
 
 <Note>
-  **Run this before opening your agent, and there is nothing to restart.** A coding agent reads its
-  MCP server list once at startup. Install while it is closed and the tools are simply there when
-  you open it. If it was already open, quit and reopen it once.
+  **Not in the app's folder?** It checks the one dev server that runs on this computer. When several
+  run, it names them and does not choose. In a folder that `init` already wired, the same command
+  starts the Reticle server (`reticle serve`) instead.
 </Note>
 
-Prefer not to pipe a script into a shell? The same result by hand:
+## Step 2. Connect your coding agent
 
-```bash
-npm install -g @reticlehq/server
-npx @reticlehq/server setup mcp
-```
-
-## Step 2. Wire this project
-
-In your project directory, before opening your coding agent:
+In the same folder, before you open your coding agent, run the command that step 1 printed:
 
 ```bash
 RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server init
 ```
 
-This installs the dev-only SDK, wires your build config, starts the dev server, and checks that a browser session connected. Nothing from your project leaves your machine. If your dev server was already running, restart it once and hard-reload the tab: it read your build config before `init` edited it. Open your coding agent once this command finishes; if it was already open during installation, restart it to load the new tools. The `RETICLE_INSTALL_SOURCE` prefix is optional and only tells us which page you installed from. It is idempotent: run it twice and the second run reports what was already done rather than doing it again.
+This installs the dev-only SDK, wires your build config, and registers Reticle with every coding agent it finds on this machine. Then it starts the dev server and checks that a browser session connected. Nothing from your project leaves your machine. If your dev server was already running, restart it once and hard-reload the tab: it read your build config before `init` edited it. Open your coding agent once this command finishes. If it was open while `init` ran, restart it once: a coding agent reads its MCP server list only when it starts. The `RETICLE_INSTALL_SOURCE` prefix is optional and only tells us which page you installed from. It is idempotent: run it twice and the second run reports what was already done rather than doing it again.
 
-Step 1 is once per machine. This step is once per project. **Skipping it is a common reason Reticle "does nothing":** the agent has the tools, but there is no app on the other end for them to see.
+This step is once per project. **Skipping it is a common reason Reticle "does nothing":** the agent has no tools, or no app on the other end for them to see.
 
 <Note>
   **Skipped this step?** Ask your agent to verify something in the app. Its first `reticle_session`
@@ -73,21 +68,6 @@ Step 1 is once per machine. This step is once per project. **Skipping it is a co
   second project while Reticle is already running for another one.
 </Note>
 
-Prefer to install the skill and let the agent run setup itself? On Claude Code the plugin registers the MCP server and the skill in one step:
-
-```text
-/plugin marketplace add reticlehq/reticle
-/plugin install reticle@reticlehq
-```
-
-On Cursor, Codex, Copilot, Gemini and anything else the skills CLI supports:
-
-```bash
-npx skills add reticlehq/reticle --skill reticle
-```
-
-Then type `/reticle` and the agent runs the install from the skill.
-
 Useful flags for the local-only `reticle init` path:
 
 ```
@@ -110,6 +90,44 @@ Start with `reticle init --dry-run` if you want to see the app changes before an
 
 Prefer to wire it yourself? See [Manual install](/install-manual). It is about ten lines, and worth reading once even if you let the agent do it, because it explains what the agent actually changed.
 
+### Other ways to connect your agent
+
+**On Claude Code, the plugin** registers the MCP server and the skill in one step. Type `/reload-plugins` after the install and the tools load in the open session:
+
+```text
+/plugin marketplace add reticlehq/reticle
+/plugin install reticle@reticlehq
+```
+
+**On Cursor, Codex, Copilot, Gemini** and anything else the skills CLI supports, add the skill, then type `/reticle` and the agent runs the setup from the skill:
+
+```bash
+npx skills add reticlehq/reticle --skill reticle
+```
+
+**The installer** puts `reticle` on your PATH once per machine and registers the MCP server with every coding agent it can reach: Claude Code, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Copilot CLI, OpenCode, Antigravity, Warp, Kiro, Amazon Q, Cline, Roo Code, Amp, Continue and Factory Droid. It asks no questions and does not wire your app. Run it before you open your coding agent:
+
+<CodeGroup>
+
+```bash macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh
+```
+
+```powershell Windows
+irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex
+```
+
+</CodeGroup>
+
+Prefer not to pipe a script into a shell? The same result by hand:
+
+```bash
+npm install -g @reticlehq/server
+npx @reticlehq/server setup mcp
+```
+
+Codex CLI keeps a TOML config. With the `codex` command installed, the installer registers Reticle through `codex mcp add`. Without it, the installer prints the lines to paste and the file to paste them into. 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.
+
 ## Step 3. Connect the dashboard (optional)
 
 Skip this if you only want local verdicts. Everything above works without an account.
@@ -272,10 +290,11 @@ That third state is the one that matters. Most tools have two outcomes and quiet
 
 <AccordionGroup>
   <Accordion title="How long does it actually take to install Reticle?">
-    Two commands, and no restart if you run them in order. The installer registers the MCP server
-    with every agent on the machine, so opening your agent afterwards is all that is needed. Then
-    `npx @reticlehq/server init` wires the project, starts your dev server and opens the app for you. The MCP
-    registration is global, so every later project starts with the tools already there.
+    Two commands in your app's folder. `npx @reticlehq/server` gives a first verdict with nothing
+    installed. Then `npx @reticlehq/server init` wires the project, registers Reticle with every
+    coding agent on the machine, starts your dev server and opens the app for you. Run them before
+    you open your agent, and it needs no restart. For most agents the MCP registration is global, so
+    a later project starts with the tools already there.
   </Accordion>
 
 <Accordion title="Do I need to write tests or learn a query syntax?">

package/docs/skill-setup.md

@@ -97,7 +97,7 @@ Enterprise features are unlocked by a signed key, verified locally with Ed25519
 npx @reticlehq/server@latest init --license <key>
 ```
 
-That writes `RETICLE_LICENSE_KEY` to the project's `.env` and adds `.env` to `.gitignore` if nothing there covers it. Do not do those two by hand: a key committed to git is a leaked credential, and it stays leaked after the file is removed. Confirm with `npx @reticlehq/server license`, which prints `active`, `eval`, `missing`, `invalid` or `expired`.
+That writes `RETICLE_LICENSE_KEY` to the project's `.env` and adds `.env` to `.gitignore` if nothing there covers it. Do not do those two by hand: a key committed to git is a leaked credential, and it stays leaked after the file is removed. Confirm with `npx @reticlehq/server status --json`. Its `license.status` is `active`, `eval`, `missing`, `invalid` or `expired`.
 
 Never echo the key back in your reply, and never put it in a commit, a code comment, or a feedback report. The rest: `curl https://docs.reticle.sh/enterprise.md`.
 

package/docs/skill.md

@@ -3,7 +3,7 @@ name: reticle-docs
 description: Install, instrument and verify this running web app from the inside (DOM, network, routing, console and framework state) instead of screenshots or guessing. Drives one real flow end to end and returns a verdict with the file:line to fix. Use when the user asks to set up or install Reticle, when a user-facing change needs proving before you call it done, when a test passes but the UI is broken, or when the user types /reticle.
 license: Apache-2.0
 metadata:
-  version: 3.9.0
+  version: 3.10.0
   homepage: https://docs.reticle.sh
   repository: https://github.com/reticlehq/reticle
   internal: true
@@ -13,30 +13,31 @@ metadata:
 
 Reticle is the proof layer for AI coding agents. A dev-only SDK inside the user's running app gives you `reticle_*` MCP tools that read the DOM, network, routing, console and framework state. You act on the real app and get a verdict: `yes`, `no`, or `unknown` (could not tell), with evidence and the `file:line` to open. No screenshots: it drives the tab the user already has open.
 
-**Your first goal: one real verdict in the user's app.** Do the three steps in order. Do not stop to explain Reticle first.
+**Your first goal: one real verdict in the user's app.** Do the steps in order. Do not stop to explain Reticle first.
 
-## 1. Install (once per machine)
+## 1. Check the app, with nothing installed
 
-**`reticle_*` tools visible?** Go to step 2.
+**`reticle_*` tools visible?** Call `reticle_session { action: "list" }`. It changes no file. On a wired project, go to step 3. On a project that is not wired, its `next_step` names the zero-install lease and asks the consent question for `init`.
 
-**Not visible?** Hand the user one line for a terminal, outside this client, and stop:
+**No tools, or an app with no `.reticle.json`?** Run this in the app's folder. It changes no file:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh
-irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex   # Windows
+npx @reticlehq/server@latest
 ```
 
-It registers Reticle with every coding agent it finds and prints the next steps: restart the agent (a client loads MCP servers only at start, so a prompt cannot replace this command), then paste the prompt it printed. Do not register the server yourself and work around your client not having reloaded. If your client did register mid-session, `npx @reticlehq/server init --relaunch` prints the command that resumes this conversation with the tools.
+It starts the dev server if the app does not run, opens the app in a Reticle browser and checks it: the page loads, no console error, no failed request, and each same-origin link opens. It prints `verified: yes` or `verified: no` with each fault. Show the user that verdict, then offer `init`.
 
 ## 2. Wire this app (once per project)
 
-In the project, call `reticle_session { action: "list" }`. It changes no file. On a project that is not wired, its `next_step` asks the consent question for `init`. When an app is running, it also names the zero-install lease, which checks that app now with nothing installed. `init` changes files, so run it only when the user agrees. A request to set up Reticle is that agreement. Run it in the app's folder:
+`init` changes files, so run it only when the user agrees. A request to set up Reticle is that agreement. Run it in the app's folder:
 
 ```bash
 RETICLE_INSTALL_SOURCE=skill_file npx @reticlehq/server@latest init
 ```
 
-A dev server that was running when `init` ran must be restarted once. If `init` cannot finish alone, read SETUP below.
+It registers Reticle with every coding agent it finds. A dev server that was running when `init` ran must be restarted once. If `init` cannot finish alone, read SETUP below.
+
+**Still no `reticle_*` tools?** A client loads MCP servers only at start, so a prompt cannot add them. `npx @reticlehq/server init --relaunch` prints the command that resumes this conversation with the tools. Else ask the user to restart the agent. Do not register the server yourself and work around your client not having reloaded.
 
 ## 3. Prove one flow
 
@@ -87,7 +88,7 @@ The advertised surface is deliberately small (`default` 10, `all` 30). `RETICLE_
 | `reticle_verify` | replay, coverage, Harness | `action`: `change` `flows` `affected` `coverage` `crawl` `explore` `mutate` `heal` |
 | `reticle_tools` / `reticle_run` | everything else (below) | `names`; `tool`, `args` |
 
-Actions: `click` `dblclick` `hover` `focus` `blur` `fill` `type` `clear` `select` `check` `uncheck` `submit` `press` `upload` `scrollIntoView` `scroll` `drag` `tap` `zoom`. `args`: `{ value }` for fill/select, `{ text: "Enter" }` for press, `{ toRef }` for drag, `{ path }` for upload, `{ native: true }` for a trusted click. A control whose label reads as destructive is refused until you pass `args.confirmDangerous: true`, and only do that when the user asked for it.
+Actions: `click` `dblclick` `hover` `focus` `blur` `fill` `type` `clear` `select` `check` `uncheck` `submit` `press` `upload` `scrollIntoView` `scroll` `drag` `tap` `zoom` `insertText`. `args`: `{ value }` for fill/select, `{ text: "Enter" }` for press, `{ toRef }` for drag, `{ path }` for upload, `{ native: true }` for a trusted click. `insertText` takes `{ text }` and types into a contenteditable/Tiptap/ProseMirror editor, where `fill` and `type` are refused. A control whose label reads as destructive is refused until you pass `args.confirmDangerous: true`, and only do that when the user asked for it.
 
 Beyond the advertised set, one hop each:
 
@@ -105,7 +106,7 @@ Every `until`, `predicate` and `expect` is `{ kind, ...fields }`; unknown fields
 
 | kind | fields |
 | --- | --- |
-| `element` | `query: { testid \| role+name \| text \| label \| placeholder \| alt \| component, scope? }`, `state?`: `visible` `hidden` `enabled` `disabled` `checked` `expanded` `pressed` `focused` `present` `inViewport`, `absent?` |
+| `element` | `query: { testid \| role+name \| text \| label \| placeholder \| alt \| component, scope? }`, `state?`: `visible` `hidden` `enabled` `disabled` `checked` `expanded` `pressed` `focused` `present` `inViewport` `receivesPointer`, `absent?` |
 | `text` | `contains`, `scope?`, `visible?`, `absent?`, `ignoreCase?`, `satisfies?` |
 | `net` | `method`, `urlContains`, `status`, `ok`, `count` (exact; omit = ≥1; 0 = never), `bodyContains`, `bodyMatches`, `requestBodyMatches`, `repeatable` |
 | `route` | `pathname` or `contains` |
@@ -115,7 +116,7 @@ Every `until`, `predicate` and `expect` is `{ kind, ...fields }`; unknown fields
 | `settled` / `animation` / `compare` | `quietMs`, `channel?` / `name`, `completed` / `left`, `right`, `as` |
 | `allOf` / `anyOf` / `not` | `predicates: [...]` / `predicates: [...]` / `predicate` |
 
-`satisfies` asserts a property when the exact value varies: `nonEmpty`, `oneOf`, `withinTolerance`, `matchesPattern`, `type`, `changed`, `unchanged`, `increased`, `decreased`. Composites hold only predicates: `absent` belongs inside a child, and an `element` takes a `query`, never a `ref`. A bare `route` or `state` is already true before the action and proves nothing; pair it with what the action causes.
+`satisfies` asserts a property when the exact value varies: `nonEmpty`, `oneOf`, `withinTolerance`, `matchesPattern`, `type`, `changed`, `unchanged`, `increased`, `decreased`. Composites hold only predicates: `absent` belongs inside a child, and an `element` takes a `query`, never a `ref`. A bare `route` or `state` is already true before the action and proves nothing; pair it with what the action causes. `absent` means not in the DOM; to say a thing is not shown, add `visible: true`. Assert what the requirement names, not a label you saw: another correct build can name it differently.
 
 ## Feedback is first-class
 

package/docs/telemetry.md

@@ -43,7 +43,7 @@ Twenty-five kinds of events, each a single small JSON object. This is the whole
 | `onboarding_step` | One step of getting set up begins, finishes, fails, is skipped, or is walked away from | Which phase (`install`, `onboard`, `first_run`), which step, what became of it, how long it took, and the framework. The step name comes from a closed list we define -- it can only ever be one of the names in `core/src/onboarding.ts`, so nothing you typed or any path on your disk can arrive in it. `unattended` says whether anybody was asked anything. A step that failed can carry why setup stopped, also from a closed list (`no_node`, `node_too_old`, `no_web_app`, `dev_server_failed`, `chromium_unavailable`, and so on) |
 | `init_completed` | `reticle init` finishes | Whether it worked, a classified reason when it did not, and which published install route you came through, DECLARED by that route via `RETICLE_INSTALL_SOURCE` and never inferred, and `unknown` when nothing declared one |
 | `bug_found` | Reticle finds a defect in the app under test | The **kind** of defect (`signal-contradicted`, `console-error`, …) and how it was found, never what it was found in |
-| `tool_refused` | A tool cannot do what an agent asked | Which tool, why (one of six buckets: no session, no match, unsupported, bad arguments, not ready, other), and whether the same call was retried. **Never the message**, because a refusal interpolates whatever you asked for, so only the tool name and the bucket are sent. Capped at 50 per daemon run |
+| `tool_refused` | A tool cannot do what an agent asked | Which tool, why (one of six buckets: no session, no match, unsupported, bad arguments, not ready, other), the cause inside the bucket as a name from a closed list (such as `chromium_missing` or `throttled`), and whether the same call was retried. **Never the message**, because a refusal interpolates whatever you asked for, so only the tool name and the bucket are sent. Capped at 50 per daemon run |
 | `feedback_submitted` | **Only** when you or your agent explicitly send feedback | The report; see [Feedback](#feedback). The AGENT's call does not wait for the network: the receipt says `accepted` (validated, redacted, queued), never `sent`, and a delivery that then fails is reported back on the agent's next tool result. `reticle feedback` typed by a human still waits, because a person at a terminal is owed the real answer |
 | `hud_viewed` | You open a page of the in-page HUD (Agent Log, Flows, Notes, Harness, Impact, Settings) or its account menu | Which page, from a closed list, and how many tabs had a HUD (a bucket: `1`, `2-3`, and so on). The same page opened again within 30 seconds counts once for the whole daemon run, also after a reload. The Agent Log that the HUD opens by itself when a page loads is not a view |
 | `hud_signin_prompted` | The HUD shows you a sign-in or "link this project" prompt | Which prompt (`rail`, `harness` or `header`), once per prompt for each daemon run |
@@ -62,7 +62,7 @@ It also carries a snapshot of the **machine's** state (our own process's memory,
 
 ### Why a verdict came out that way
 
-`verification_completed` carries the **clause** that decided the verdict, from a fixed list we define: `proved`, `contradicted`, `assertion_failed`, `already_true`, `hidden_match`, `unclean_capture`, `vacuous_grade`, `nothing_declared`, `outcome_pending`, `outcome_unread`, `unsettled`, `evidence_incomplete`, `absence_blind_spot`, `observation_lost`, `window_closed_early`, `inconclusive`, `version_skew`, `capability-absent`.
+`verification_completed` carries the **clause** that decided the verdict, from a fixed list we define: `proved`, `contradicted`, `assertion_failed`, `already_true`, `hidden_match`, `unclean_capture`, `vacuous_grade`, `nothing_declared`, `outcome_pending`, `outcome_unread`, `unsettled`, `evidence_incomplete`, `absence_blind_spot`, `observation_lost`, `window_closed_early`, `dialog_declined`, `inconclusive`, `version_skew`, `capability-absent`.
 
 It exists because `verified: "unknown"` covered seven different situations belonging to three different owners (your app, your agent, and Reticle's own blind spots), and they arrived as one value. It is a **name from our own vocabulary**, never a description of your app: `contradicted` says two channels disagreed, not which ones, about what, or on which page.
 

package/docs/tools/navigate.mdx

@@ -77,7 +77,7 @@ with [`reticle_session`](/tools/sessions), and only then look at the page. If no
 | --- | --- |
 | `url` | Where to go. Relative paths work |
 | `reload` | Reload in place instead of navigating |
-| `hard` | With `reload`, bypass the cache |
+| `hard` | With `reload`, bypass the cache. On a leased tab the browser reloads with its cache ignored (`hardReload: "cache_ignored"`). On a tab Reticle does not drive, only the document is fetched again, and scripts and modules can come from the cache (`hardReload: "document_only"`) |
 | `timeout_ms` | How long to wait for the page to come back before `confirmed: false`. Default 5000; 0 looks once |
 
 ## Client-side routing is different

package/docs/tools/verify.mdx

@@ -1,6 +1,6 @@
 ---
 title: reticle_verify
-description: Prove what is and is not working, by action. Replay saved flows for a change or for the whole suite, list coverage, crawl, explore, mutate or heal.
+description: Prove what is and is not working, by action. Replay saved flows for a change or for the whole suite, list coverage, crawl, explore, mutate, heal, or compare two builds.
 icon: shield-check
 ---
 
@@ -20,9 +20,12 @@ icon: shield-check
 | `explore` | The Harness, Reticle's model-driven explorer, drives the journey you name in `persona` and saves what it drove as flows. Runs on the Reticle platform: run `reticle connect` first. A new account gets free credits to try it. **Destructive** | no |
 | `mutate` | Grades a saved flow: breaks the endpoint it depends on and replays it. A flow that stays green is a click sequence, not a test | no |
 | `heal` | Rebinds a flow whose locator was renamed. Re-asserts the saved consequence first and refuses if it stops firing. `apply: true` writes the fix | no |
+| `compare` | Drives two running builds (`reference`, `candidate`, optional `base`) the same way and lists each difference in what users see and in the requests and console errors the app made. Nothing is installed in the app. Answers the JSON of [`reticle compare --json`](/cli/compare), with `verified` `yes` (same), `no` (different) or `unknown` (the run proves nothing). Within `wait` seconds it gives the result, or `{ status: "running", runId }` to poll with `runId`. **Destructive:** it presses every button it finds | yes |
 
 Only `verified: "yes"` is a pass. `unknown` means Reticle could not tell, and `no-fault` means nothing was declared to prove.
 
+For `action: "flows"` and `action: "change"`, `parallel` opens one isolated lease per replayed flow. These leases inherit the source lease's certificate setting. Set `ignoreHTTPSErrors: true` to accept a self-signed or local-CA certificate when the source is not a lease. An explicit `false` keeps certificate checks on.
+
 Replay before you drive: a covered journey re-verifies for a few hundred tokens, where driving it again costs tens of thousands.
 
 From a terminal, `reticle verify <url>` replays the saved flows and exits `0` on pass. See [`reticle verify`](/cli/verify).

package/docs/troubleshooting.mdx

@@ -263,7 +263,7 @@ Some clients read their MCP tool list once, at startup, and never again. Cursor
 ## Restarting things
 
 ```bash
-npx @reticlehq/server restart  # clean stop, then start and wait until it listens
+npx @reticlehq/server serve --restart  # clean stop, then start and wait until it listens
 npx @reticlehq/server status   # confirm it is back
 ```
 

package/docs/usage.md

@@ -129,7 +129,7 @@ Deep detail on one element, including the signals a snapshot/a11y tree omits, so
 Perform one action / several in order.
 
 - **`reticle_act` args:** `ref`, `action`, `args?`, `refuseWhenThrottled?`, `sessionId?`. → `{ since, dispatched, settled, settleReason, result, session, warning? }` where `result = { ok, ref, action, dispatched, settled, settleReason, effect }`. The `session` block `{ lastSeenMs, throttled, focused }` reports tab health on every act; when `throttled` is true a `warning` string is also attached. Pass `refuseWhenThrottled: true` to hard-fail instead of warning (opt-in; default is warn-only so background testing never breaks).
-- **`reticle_act { steps: [...] }` args:** `steps: [{ ref | target, action, args?, expect? }]`. `expect` takes the same predicate as `reticle_act_and_wait` `until`. A step with `expect` proves its consequence. The call stops at the first `expect` that fails and returns `verified` and `because`. Each step takes `ref` (from a snapshot/query) or `target` (`{ testid }` / `{ label }` / `{ role, name }` / `{ text }`). That is the same locator `reticle_act` accepts. → `{ since, dispatched, result }` where `result = { ok, count, effects: [...], steps: [...] }` (one `effect` per step; each step carries its own `dispatched`/`settled`/`settleReason`).
+- **`reticle_act { steps: [...] }` args:** `steps: [{ ref | target, action, args?, expect? }]`. `expect` takes the same predicate as `reticle_act_and_wait` `until`. A step with `expect` proves its consequence. The call stops at the first `expect` that fails and returns `verified` and `because`. When a step could not be judged, the plan is `verified: "unknown"` (`verifiedReason: "inconclusive"`), and `because` names that step and what was missing: `step 2 (click) could not be judged: the assertion could not be evaluated: …`. `stopped_at` is the index of the same step, counted from 0. Each step takes `ref` (from a snapshot/query) or `target` (`{ testid }` / `{ label }` / `{ role, name }` / `{ text }`). That is the same locator `reticle_act` accepts. → `{ since, dispatched, result }` where `result = { ok, count, effects: [...], steps: [...] }` (one `effect` per step; each step carries its own `dispatched`/`settled`/`settleReason`).
 - See [§5](#5-actions-full-list) for the action list.
 
 **Dispatch vs settle.** (Settle means the page has stopped changing for now.) The action is two phases: the **dispatch** (the synchronous click/fill, which is what can fail) and the **settle** (waiting one animation frame so React's commit lands before we return). The settle is **bounded** (~200ms): in a throttled/background tab `requestAnimationFrame` never fires, so Reticle falls back to a timer and resolves anyway. A settle timeout is therefore **never an error**: `reticle_act` resolves with `settled:false, settleReason:"timeout"` and the dispatch (the click) has still landed. Only a real dispatch failure (stale ref, wrong element type) throws.
@@ -148,9 +148,9 @@ Perform one action / several in order.
 | `targetMatched` | the ref still resolved to a connected element |
 | `visible` | element was visible at the start of the action |
 | `enabled` | element was not disabled / aria-disabled at the start |
-| `defaultPrevented` | a handler called `preventDefault()` on the primary cancelable event. Only meaningful for `click`/`dblclick`/`hover`/`fill`/`type`/`clear`/`press`/`upload`/`drag`; always `false` for non-cancelable events (`focus`/`blur`/`select`/`check`/`uncheck`/`submit`/`scrollIntoView`) |
+| `defaultPrevented` | a handler called `preventDefault()` on the primary cancelable event. Only meaningful for `click`/`dblclick`/`hover`/`fill`/`type`/`insertText`/`clear`/`press`/`upload`/`drag`; always `false` for non-cancelable events (`focus`/`blur`/`select`/`check`/`uncheck`/`submit`/`scrollIntoView`). For `insertText`, `true` with `valueChanged: true` means an editor that owns its input took the text: that is success, not a refusal |
 | `focusMoved` | `"<prevRef>-><newRef>"` if `document.activeElement` changed, else `null` (body counts as `null`) |
-| `valueChanged` | `fill`/`type`/`clear` only: input value before !== after; otherwise `false` |
+| `valueChanged` | `fill`/`type`/`clear`, and `insertText`: the field value (or the editor's text) before !== after; otherwise `false` |
 | `domMutatedWithin` | count of MutationObserver records seen in the window |
 | `occluded` | `click`/`dblclick` only: the click point hit-tested to a _foreign_ element (an overlay is on top). Synthetic dispatch still delivered the event, but **a real user could not click it**, so treat the target as visually blocked. `false` when not click-like or not hit-testable |
 | `occludedBy` | the ref of the element actually on top at the click point when `occluded`, else `null` |
@@ -283,13 +283,13 @@ Show the agent's intent on the page, and control time (toasts/debounces/auto-dis
 
 Regression detection. See [§8](#8-regression-baselines--diff).
 
-### `reticle_run { tool: "reticle_record", args: { action: "start" } }` / `reticle_run { tool: "reticle_record", args: { action: "stop" } }` / `reticle_replay`
+### `reticle_run { tool: "reticle_record", args: { action: "start" | "stop" | "replay" } }`
 
 Capture a flow's reaction report and compile it into a replayable program. See [§9](#9-recording-a-flow). `reticle_run { tool: "reticle_record", args: { action: "stop" } }` also returns a `cost:{ events, bytes }` hint alongside the reaction report so you can gauge the recording's size.
 
-### `reticle_explore`
+### Autonomous exploration
 
-List interactive elements + console-error count for autonomous exploration. See [§10](#10-autonomous-exploration).
+List the interactive elements with `reticle_snapshot { mode: "interactive" }` and read console errors with `reticle_console`. See [§10](#10-autonomous-exploration).
 
 ### Flows, recorder & self-healing (`.reticle/`)
 
@@ -356,7 +356,9 @@ A **predicate** declares what should be true. `reticle_assert` / `reticle_assert
 // An element exists / is in a state
 { "kind": "element", "query": { "role": "dialog", "name": "Confirm" }, "state": "visible" }
 // query supports: role, name, text, label, placeholder, testid, alt, scope
-// state: visible | hidden | enabled | disabled | checked | expanded | pressed | focused | present | inViewport
+// state: visible | hidden | enabled | disabled | checked | expanded | pressed | focused | present | inViewport | receivesPointer
+// receivesPointer asserts that a tap at the element's centre reaches it: visible, in the viewport, and no app element on top
+// (a fixed header over a close button leaves it `visible` and untappable). Reticle's own UI never counts as a cover.
 // inViewport asserts the element is in the viewport NOW (not just in the DOM), so a scrollIntoView is gradeable
 // add "absent": true to assert it is NOT there (regression / removal)
 
@@ -419,11 +421,12 @@ A `state` assertion is graded as a **consequence** (a wrong element or stale ren
 | `focus` / `blur` | n/a |  |
 | `fill` | `{ value }` | sets value via React-safe native setter + `input`/`change` |
 | `type` | `{ text }` | appends to current value |
+| `insertText` | `{ text }` | inserts plain text into a contenteditable/Tiptap/ProseMirror editor through the browser editing pipeline: it announces `beforeinput` first, then lets the browser insert, so the editor's own model updates. `fill` and `type` refuse these surfaces. It refuses an EditContext editor (Monaco, CodeMirror 6), where a scripted update fires no `textupdate` for the model, and it refuses when the native command exists and fails, rather than writing the DOM while the editor's model stays stale |
 | `clear` | n/a | empties an input |
 | `select` | `{ value }` | `<select>` option |
 | `check` / `uncheck` | n/a | checkbox/radio |
 | `submit` | n/a | submits the element's `<form>` |
-| `press` | `{ text, modifiers?, holdMs?, keys?, code? }` | keydown/up (default `Enter`). `text` is the key name (`Escape`, `Tab`); `key` is an accepted alias; `modifiers`: an array of `Meta` / `Control` / `Shift` / `Alt` for Cmd+K-style shortcuts. With a `ref` the key is dispatched AT that element; with NO ref it is a document key (Escape, Tab, a shortcut) and goes through the real keyboard, so it can actually move focus. `holdMs` keeps the key DOWN for that long (hold-to-confirm, hold-to-reveal). `keys` holds several keys together, pressed in order and released in reverse, and `code` names the physical key: both stay on the in-page dispatcher, which is the only path that can express them |
+| `press` | `{ text, modifiers?, holdMs?, keys?, code?, document? }` | keydown/up (default `Enter`). `document: true` makes any key a document key, so it needs no `ref`. `text` is the key name (`Escape`, `Tab`); `key` is an accepted alias; `modifiers`: an array of `Meta` / `Control` / `Shift` / `Alt` for Cmd+K-style shortcuts. With a `ref` the key is dispatched AT that element; with NO ref it is a document key (Escape, Tab, an arrow key, a shortcut) and goes through the real keyboard, so it can actually move focus. `holdMs` keeps the key DOWN for that long (hold-to-confirm, hold-to-reveal). `keys` holds several keys together, pressed in order and released in reverse, and `code` names the physical key: both stay on the in-page dispatcher, which is the only path that can express them |
 | `scrollIntoView` | n/a |  |
 | `scroll` | `{ dy?, dx?, fraction? }` | Scrolls the nearest scrollable container (or the page, with no `ref`) by `dy`/`dx` pixels, either direction. `fraction` (0 to 1) jumps to that point of the height. No args steps down most of a screen |
 | `tap` | `{ holdMs? }` | A touch tap: pointer and touch events, then `click`. `holdMs` makes it a long press |
@@ -441,7 +444,7 @@ A `state` assertion is graded as a **consequence** (a wrong element or stale ren
 - **`interactive`** (~100 tokens): only actionable elements (buttons, inputs, tabs…). "What can I click?" Non-interactive content (e.g. 1,000 list rows) is skipped.
 - **`full`**: the whole semantic tree. Use only when you truly need everything.
 
-**`scope`** narrows any snapshot or query to a subtree, either a CSS selector (`scope: "[data-testid=item-list]"`) or a ref. This is the main lever for keeping payloads small and queries unambiguous on big pages.
+**`scope`** narrows any snapshot or query to a subtree, either a CSS selector (`scope: "[data-testid=item-list]"`) or a ref. This is the main lever for keeping payloads small and queries unambiguous on big pages. In a query or a check, a CSS selector that matches several elements searches all of them, and the result reports how many it matched in `scopeMatches`. A ref names one element.
 
 ---
 
@@ -666,7 +669,7 @@ reticle_run({ tool: "reticle_record", args: { action: "stop", recordingName: "ch
 `reticle_run { tool: "reticle_record", args: { action: "stop" } }` returns a compiled, replayable `program`: the agent's `reticle_act` / `reticle_act { steps: [...] }` invocations captured during the span, with each ref normalized to its element's `data-testid` where resolvable. Re-run it later:
 
 ```jsonc
-reticle_run({ tool: "reticle_replay", args: { recordingName: "checkout" } })
+reticle_run({ tool: "reticle_record", args: { action: "replay", recordingName: "checkout" } })
 // re-resolves each step by testid and re-runs the actions in order
 // → { recordingName, ok, steps: [{ tool, ok, error?, note? }] }   // stops at the first failure
 ```
@@ -680,8 +683,8 @@ reticle_run({ tool: "reticle_replay", args: { recordingName: "checkout" } })
 Have the agent crawl and stress a screen without a script:
 
 ```jsonc
-reticle_run({ tool: "reticle_explore", args: { scope: "main" } })
-// → { interactive: [ { ref, desc }, … ], consoleErrors, hint }
+reticle_snapshot({ mode: "interactive", scope: "main" })   // the controls, with refs
+reticle_console({})                                        // the console errors so far
 ```
 
 The agent then acts on each ref, observes the reaction, and reports anomalies (failed requests, console errors, dead controls). Good for "click everything on this page and tell me what breaks."
@@ -1043,9 +1046,9 @@ registerCapabilities({ testids: [...], signals: [...], stores: [...], flows: [..
 reticle_run({ tool: "reticle_capabilities", args: {} })   // → { testids, signals, stores, flows }
 ```
 
-### `reticle_replay`: recordings become re-runnable programs
+### `reticle_record { action: "replay" }`: recordings become re-runnable programs
 
-`reticle_run { tool: "reticle_record", args: { action: "start" } }` → drive the flow → `reticle_run { tool: "reticle_record", args: { action: "stop" } }` returns a **compiled program** (steps bound to testids/signals, not volatile refs). `reticle_run({ tool: "reticle_replay", args: { recordingName } })` re-executes it, so your flow becomes a deterministic regression run, not a checklist.
+`reticle_run { tool: "reticle_record", args: { action: "start" } }` → drive the flow → `reticle_run { tool: "reticle_record", args: { action: "stop" } }` returns a **compiled program** (steps bound to testids/signals, not volatile refs). `reticle_run({ tool: "reticle_record", args: { action: "replay", recordingName } })` re-executes it, so your flow becomes a deterministic regression run, not a checklist.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "mcpName": "io.github.reticlehq/reticle",
   "description": "Reticle CLI, bridge and MCP server: a coding agent drives your running web app from the inside and gets a verdict with evidence, for change verification, access control, accessibility, performance and SEO checks.",
   "type": "module",
@@ -20,23 +20,23 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.31.0",
-    "ws": "^8.21.3",
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "ws": "^8.22.1",
     "zod": "^4.6.6",
-    "@reticlehq/browser": "3.9.0",
-    "@reticlehq/core": "3.9.0",
-    "@reticlehq/init": "3.9.0",
-    "open-verification": "1.1.0",
-    "@reticlehq/engine": "3.9.0"
+    "@reticlehq/browser": "3.10.0",
+    "@reticlehq/init": "3.10.0",
+    "@reticlehq/core": "3.10.0",
+    "@reticlehq/engine": "3.10.0",
+    "open-verification": "1.1.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
-    "@types/ws": "^8.5.13",
+    "@types/ws": "^8.18.2",
     "yaml": "^2.9.1"
   },
   "optionalDependencies": {
     "pixelmatch": "^8.0.0",
-    "playwright": "^1.63.0",
+    "playwright": "^1.64.1",
     "pngjs": "^7.0.0"
   },
   "license": "Apache-2.0",
@@ -65,10 +65,10 @@
     "cli"
   ],
   "reticle": {
-    "changelog": "3.9.0 gets more installs to a first verdict. The one-line installer and reticle init now check your app and wait for your agent to connect. A lease reads a deployed preview with no SDK installed. Several false verdicts are fixed: a click that hit Reticle's own panel, a recorded flow that lost its assertion, and an iframe that took over a page's session. Every package is now Apache-2.0. Update the CLI and the SDK in your app.",
+    "changelog": "3.10.0 checks every change against what worked before. reticle compare and verify --against list what users would see change between two builds, and reticle grade grades a finished run from the app's stored data. Several false verdicts are fixed, most of them text checks that answered no for text that was on the page. An agent in a Claude Code worktree now reaches its own tab. Update the CLI and the SDK in your app.",
     "breakingChanges": [
-      "A headless page now opens at 1440x900, not 1280x720. Record your headless screenshot baselines again, or they report dimension-mismatch.",
-      "The JSON line of `reticle license` no longer has the `gated` and `coversNothingHere` fields."
+      "The commands kill, login, link, project, whoami, push, regression, share, issues and memory are removed. Each prints the command that replaces it and exits 1. See MIGRATION.md.",
+      "The MCP tools reticle_explore and reticle_replay left the tool surface. Use reticle_look { action: \"page\", mode: \"interactive\" } and reticle_record { action: \"replay\" }."
     ]
   },
   "publishConfig": {

package/dist/features/exhaust/exhaust-run.d.ts

@@ -1,33 +0,0 @@
-/**
- * `reticle_crawl { exhaustive: true }` — explore every reachable state, drive every write's failure
- * path, take the code coverage, fold all of it into the ledger, and say what is left.
- *
- * It answers in crawl's own shape, so every caller that reads a crawl keeps working, and adds one
- * `exhaustive` block with what only this mode knows.
- */
-import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
-import { type RawScriptCoverage } from './code-coverage.js';
-import { type PortSession } from './session-port.js';
-/** Default action budget: generous, because every edge replays its path from a fresh load. */
-export declare const EXHAUST_DEFAULT_ACTIONS = 400;
-export declare function runExhaustive(input: {
-    sessions: {
-        get(id: string): PortSession | undefined;
-    };
-    session: PortSession;
-    startUrl: string;
-    maxActions: number;
-    settleMs: number;
-    /** What to type into a field, given the page it is on — a secret is only for its own origin. */
-    fillValue: (label: string, pageUrl: string) => string;
-    now: () => number;
-    sleep: (ms: number) => Promise<void>;
-    setMocks?: (sessionUrl: string, rules: {
-        urlContains: string;
-        method?: string;
-        abort?: boolean;
-    }[]) => Promise<boolean>;
-    takeCode?: (sessionUrl: string) => Promise<readonly RawScriptCoverage[] | undefined>;
-    fs: FileSystemPort;
-    reticleRoot: string;
-}): Promise<Record<string, unknown>>;