@reticlehq/server 3.5.0 → 3.7.0

package/docs/agent-cheatsheet.md

@@ -4,7 +4,7 @@ description: 'One screen to get fluent: the look → act → observe → assert
 icon: bolt
 ---
 
-The loop is **look → act → observe → assert**, and verdicts come from `reticle_act_and_wait`, `reticle_assert`, and `reticle_act { steps }` when a step declares `expect`. Reach for `reticle_act_and_wait({ ref, action, until })` first: it names the expected consequence before the action, which is the difference between a check and a rationalisation. `verified: "unknown"` is not a pass.
+The loop is **look → act → observe → assert**. Verdicts come from `reticle_act_and_wait`, `reticle_assert`, `reticle_act { steps }` when a step declares `expect`, and `reticle_verify` (`change`/`flows`). Everything else moves or reads the app and proves nothing. Only `verified: "yes"` is a pass: `unknown` means Reticle could not tell, and `no-fault` means nothing was declared to prove. Reach for `reticle_act_and_wait({ ref, action, until })` first: it names the expected consequence before the action, which is the difference between a check and a rationalisation.
 
 One screen to get fluent. Reticle is the **proof layer for AI agents**: no screenshots, no vision model, evidence not prose. Everything below returns structured data. Full guide: [usage.md](usage.md).
 
@@ -14,18 +14,18 @@ One screen to get fluent. Reticle is the **proof layer for AI agents**: no scree
 | --- | --- | --- |
 | **look** | `reticle_look { action: "page" }` / `reticle_look { action: "find" }` | See the page (semantic tree) / find one specific element. |
 | **act** | **`reticle_act_and_wait`** / `reticle_act { steps: [...] }` / `reticle_act` | **Act + name the consequence, one hop. Reach for this first.** / batch a whole journey in one hop / move the app and prove nothing. |
-| **observe** | `reticle_observe` / `reticle_assert { action: "wait" }` | Everything the app did after `since` / block until true. |
+| **observe** | `reticle_observe` / `reticle_assert { action: "wait" }` | Everything the app did after `since` / block until true. The wait carries `verified` and is graded the way `reticle_assert` grades it. |
 | **assert** | `reticle_assert` | Evaluate a predicate → `{ pass, evidence, failureReason? }`. The end of every loop. |
 
-> **Verdicts come from `reticle_act_and_wait`, `reticle_assert`, and `reticle_act { steps }` when a step declares `expect`.** Everything else moves or reads the app and proves nothing, so a drive ending without a verdict has no result however many tools it used. `reticle_act` is the tool agents reach for by habit and it catches nothing; `act_and_wait` is where defects actually surface. And `verified: "unknown"` is not a pass: it means Reticle drove the app and could not tell what happened. Report it as unknown.
+> **Verdicts come from `reticle_act_and_wait`, `reticle_assert`, `reticle_act { steps }` when a step declares `expect`, and `reticle_verify` (`change`/`flows`). Everything else moves or reads the app and proves nothing. Only `verified: "yes"` is a pass: `unknown` means Reticle could not tell, and `no-fault` means nothing was declared to prove.** A drive ending without a verdict has no result however many tools it used. `reticle_act` is the tool agents reach for by habit and it catches nothing; `act_and_wait` is where defects actually surface. Report `unknown` as unknown.
 
-`reticle_act` returns a `since` cursor; pass it to `reticle_observe({ since })` to scope the window. Elements are addressed by stable refs (`e7`) from `snapshot`/`query`; they re-resolve across re-renders.
+`reticle_act` returns a `since` cursor; pass it to `reticle_observe({ since })` to scope the window. Elements are addressed by stable refs (`e7`) from `reticle_look { action: "page" }` or `{ action: "find" }`; they re-resolve across re-renders.
 
 **`assert`/`wait_for` are auto-scoped to your last act.** By default they only count events buffered _since_ the most recent act, so a stale signal from a previous step can't fake a pass. Pass an explicit `since` to override. **Clicks run the code, not pixels:** `reticle_act` click fires the full pointer sequence on the element (no coordinate gesture for the HUD to intercept), reports `occluded:true` when something covers the target, and stays synthetic even with CDP configured (use `args:{ native:true }` for a trusted native click).
 
 **Never sleep. Wait deterministically.** Fixed sleeps are the #1 cause of flaky agent tests. Instead:
 
-- `reticle_act_and_wait({ ref, action })` with **no `until`** waits for the page to _settle_ (network + structural DOM idle; ambient count-up/spinner churn is ignored so an animated page still settles) before returning: the one-call replacement for "click then sleep 500ms".
+- `reticle_act_and_wait({ ref, action })` with **no `until`** waits for the page to _settle_ (settle: nothing new happening for a short quiet window, measured as network + structural DOM idle; ambient count-up/spinner churn is ignored so an animated page still settles) before returning: the one-call replacement for "click then sleep 500ms".
 - Need to wait without acting? `reticle_assert({ action: "wait", predicate: { kind: "settled", quietMs } })`.
 - Waiting for a specific outcome? Pass that consequence as the predicate (`{ signal }` / `{ net }`), or `allOf` it with `{ kind: "settled" }` to wait for both the event _and_ the page going quiet.
 
@@ -37,21 +37,19 @@ One screen to get fluent. Reticle is the **proof layer for AI agents**: no scree
 | `{ kind: "element", role: "button", text: "Save" }` | `{ kind: "element", query: { role, text } }` |
 | `{ kind: "route", url: "/checkout" }` | `{ kind: "route", contains: "/checkout" }` |
 
-**New in 2.8.0, and it changes what some existing assertions mean.** An element predicate now CHECKS `value` and `text` instead of quietly folding them into the locator and ignoring them.
+**An element predicate CHECKS `value` and `text`.** They are not folded into the locator and ignored.
 
 ```jsonc
-// Now a real assertion about the field's contents. Before 2.8.0 this passed
-// whatever the input held, because `value` was read as a locator operand and,
-// with no `by`, silently did nothing.
+// A real assertion about the field's contents.
 { "kind": "element", "role": "textbox", "name": "GST amount", "value": "274.58" }
 ```
 
-Two consequences worth knowing before you write your next predicate:
+Two consequences worth knowing:
 
-- **You can now assert what a field contains.** That was not possible before; agents worked around it by reading the value out of band with `reticle_look { action: "find" }` and comparing in prose, which produces no verdict and therefore does not count as verification.
-- **`{ role, text }` now checks the text.** It used to match on role alone, so it matched every button on the page. If an assertion you have used for months starts failing, that is the likely reason, and the failure is the truth arriving late.
+- **You can assert what a field contains.** Do not read the value with `reticle_look { action: "find" }` and compare it in prose: that produces no verdict and does not count as verification.
+- **`{ role, text }` checks the text,** so it does not match every button with that role.
 
-Fields that nothing can check are refused rather than ignored: `by` without a `value`, and `label`, `placeholder`, `testid`, `alt` or `component` when a higher-precedence field already selected the element. An element query is a first-match dispatch, not a conjunction.
+Fields that nothing can check are refused rather than ignored: `by` without a `value`, and `label`, `placeholder`, `testid` or `component` when a higher-precedence field already selected the element. `alt` is the one that can still be checked beside another locator: on an image it is compared with the image's `alt` attribute (so `alt: ""` passes on a decorative image but not on one missing its alt), and on anything that is not an image it is refused, with a hint to use `name`. An element query is a first-match dispatch, not a conjunction.
 
 **Combinators take `predicates`, not a bare array.** This is the shape most often got wrong, and it is the one that produces no verdict at all:
 
@@ -113,9 +111,9 @@ A claim is real only when the layers agree. Check more than the UI:
 
 ## Core tool set
 
-The tools you are shown, plus `reticle_run`, which calls any registered tool by name whether or not it is advertised.
+The ten tools you are shown. `reticle_run` is one of them: it calls any registered tool by name, advertised or not.
 
-`reticle_navigate` · `reticle_act` · `reticle_act_and_wait` · `reticle_assert` · `reticle_look` · `reticle_observe` · `reticle_session` · `reticle_verify` · `reticle_tools`
+`reticle_navigate` · `reticle_act` · `reticle_act_and_wait` · `reticle_assert` · `reticle_look` · `reticle_observe` · `reticle_session` · `reticle_verify` · `reticle_tools` · `reticle_run`
 
 Most of what used to be a tool of its own is now an action on one of them:
 
@@ -125,21 +123,21 @@ Call an old name and you are told the new one. `reticle_tools` prints the live s
 
 - `reticle_verify`: **the only core tool that CONCLUDES.** `{ action:"crawl" }` drives every reachable control itself and reports the whole fault set in one call (destructive: it really clicks). `{ action:"flows" }` replays every saved flow with no model in the loop. Reach for it when you think you are done: every other tool here answers "here is more to look at".
 
-Not on this surface at all, but one hop away: `reticle_run { tool, args }` calls any registered tool by name, advertised or not, and `reticle_tools { names: [...] }` loads its arguments. That reaches `reticle_capabilities` (the app's whole testable surface in one call), `reticle_domain` (learn the app + gaps), `reticle_baseline {action:"diff"}`, `reticle_project` (run history), `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock` and `reticle_clock`. A daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises them directly instead.
+Not on this surface at all, but one hop away: `reticle_run { tool, args }` calls any registered tool by name, advertised or not, and `reticle_tools { names: [...] }` loads its arguments. That reaches `reticle_capabilities` (the app's whole testable surface in one call), `reticle_domain` (learn the app + gaps), `reticle_run { tool: "reticle_baseline", args: { action: "diff" } }`, `reticle_project` (run history), `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock` and `reticle_clock`. A daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises some of these directly (`reticle_capabilities`, `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock`, `reticle_clock`, plus `reticle_record`, `reticle_flow_save`, `reticle_flow_replay`, `reticle_intent` and `reticle_context`); the rest stay behind `reticle_run`. It also switches to the unmerged spelling: `reticle_snapshot`/`reticle_query`/`reticle_inspect`/`reticle_state` replace `reticle_look`, `reticle_network`/`reticle_console` replace `reticle_observe { action }`, `reticle_wait_for` replaces `reticle_assert { action: "wait" }`, `reticle_sessions`/`reticle_feedback` replace `reticle_session` list/feedback, and `reticle_act_sequence` replaces `reticle_act { steps }`. Examples on this page use the default spelling.
 
-**What the wider surface adds, through `reticle_run` or advertised directly with `RETICLE_ADVERTISE_ALL_TOOLS=1`:** record/replay a journey (`reticle_record {action:"start"}/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_verify { action: "heal" }`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_verify {action:"crawl"}` is now advertised directly, clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_look { action: "find" }` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven or leased), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session {action:"end"}` / `reticle_session {action:"resume"}` / `reticle_session {action:"messages"}`, and **`reticle_session {action:"review"}`** to drain + fix the bugs the human flagged from the panel).
+**What the wider surface adds, through `reticle_run` (a few are also advertised directly with `RETICLE_ADVERTISE_ALL_TOOLS=1`):** record/replay a journey (`reticle_run { tool: "reticle_record", args: { action: "start" } }/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_verify { action: "heal" }`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_verify { action: "crawl" }` is now advertised directly, clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_look { action: "find" }` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven or leased), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session { action: "end" }` / `reticle_session { action: "resume" }` / `reticle_session { action: "messages" }`, and **`reticle_session { action: "review" }`** to drain + fix the bugs the human flagged from the panel).
 
 ## flows vs baselines vs project.json (the persistence layers)
 
 | Artifact | Tool(s) | What it is |
 | --- | --- | --- |
 | **flows** | `reticle_flow_save*` / `reticle_flow_replay` / `reticle_verify { action: "heal" }` | Replayable **golden journeys**, anchored to testids/signals; drift is legible and self-heals. |
-| **baselines** | `reticle_baseline {action:"save"}` / `reticle_baseline {action:"diff"}` | Structural **"before" snapshots**; `reticle_baseline {action:"diff"}` flags regressions against them. |
-| **project.json** | `reticle_project` | Cross-run **run-history**: "did it behave like last run?" read via `reticle_project`. |
+| **baselines** | `reticle_run { tool: "reticle_baseline", args: { action: "save" } }` / `reticle_run { tool: "reticle_baseline", args: { action: "diff" } }` | Structural **"before" snapshots**; `reticle_run { tool: "reticle_baseline", args: { action: "diff" } }` flags regressions against them. |
+| **project.json** | `reticle_project` | Cross-run **run-history**: "did it behave like last run?" read via `reticle_project`. Its `cloud.sync` says where this project's runs stand with the platform (on it, waiting, refused, last push); `push: true` syncs before answering. |
 
 > `reticle_project` / `project.json` are the **run-history layer**. flows answer "does the journey still work?"; baselines answer "did the structure change?"; project.json answers "is this run consistent with prior runs?".
 
-**Visual layer (opt-in).** `reticle_screenshot` saves a PNG baseline to `.reticle/visual/<name>.png`; `reticle_visual_diff` perceptually compares the live page to it (`{ masks }` to ignore volatile regions, `{ maxRatio }` tolerance) → `{ matched, changedPixels, ratio, region, diffPath }`. It answers "does it **look** right", complementary to the behavioral layers, never a replacement. Both need a **driven browser** (`reticle drive <url>` / `RETICLE_CDP_URL`); without one they return `{ ok:false, reason:"no-visual-provider" }` (the always-on SDK ships no screenshotter).
+**Visual layer (opt-in).** `reticle_screenshot` saves a PNG baseline to `.reticle/visual/<name>.png`; `reticle_visual_diff` perceptually compares the live page to it (`{ masks }` to ignore volatile regions, `{ maxRatio }` tolerance) → `{ matched, changedPixels, ratio, region, diffPath }`. It answers "does it **look** right", complementary to the behavioral layers, never a replacement. Both need a **driven browser** (`reticle drive <url>` / `RETICLE_CDP_URL`) or a leased tab (`reticle_lease`); without one they return `{ ok:false, reason:"no-visual-provider" }` (the always-on SDK ships no screenshotter).
 
 ## Fields worth reading that you may not know are there
 
@@ -147,22 +145,21 @@ Recent additions, each of which answers a question agents were previously asking
 
 | Field | On | What it tells you |
 | --- | --- | --- |
-| `expiresInMs` | `reticle_lease { action: "acquire" }` | How long the lease lives if untouched, reset by every call that targets it. Plan a pass to finish inside it, or re-acquire deliberately, rather than losing a measurement to a silent expiry. |
+| `expiresInMs` | `reticle_run { tool: "reticle_lease", args: { action: "acquire" } }` | How long the lease lives if untouched, reset by every call that targets it. Plan a pass to finish inside it, or re-acquire deliberately, rather than losing a measurement to a silent expiry. |
 | `scroll` | `reticle_look { action: "element" }` | `scrollTop`, `scrollHeight`, `clientHeight`, `overflowY`. Whether the element scrolls, which you cannot infer from geometry alone. |
-| `timeline_omitted` | `reticle_record { action: "stop" }` | The raw event timeline is not in the response. It says how many events there were and names the call that returns them, with the cursor filled in. |
+| `timeline_omitted` | `reticle_run { tool: "reticle_record", args: { action: "stop" } }` | The raw event timeline is not in the response. It says how many events there were and names the call that returns them, with the cursor filled in. |
 | `elided` | `reticle_act_and_wait` | Some diff arrays were capped. The count is real even when the list is trimmed, so a small array does not mean a quiet app. |
 | `colorTokens`, `themeScope` | `reticle_look { action: "element" }` | Every design token matching a colour, not one arbitrary winner, and which theme the reading was taken under. The singular `colorToken` is `null` when several tokens share a colour, because naming one of them was the defect. |
 | `why` | `reticle_session { action: "list" }`, when the list is empty | Why nothing is connected, and the next action. An empty list is never the end of the road. |
 
 **When a verdict comes back `unsettled`,** it now names what it was waiting for and what the window actually held. Read those before retrying: an `unknown` that explains itself is a retry with a better `until`, and one that does not is a dead end.
 
-**If the port is taken,** `reticle kill` frees it and leaves your own MCP proxy alone. Do not reach for `lsof -i :4400` and kill what it lists; that matches every process on the port, including the proxy you are talking through.
+**If the port is taken,** `reticle stop --force` frees it and leaves your own MCP proxy alone. Do not reach for `lsof -i :4400` and kill what it lists; that matches every process on the port, including the proxy you are talking through.
 
 ## Start here
 
-0. Just ran `reticle init` / started the dev server? Poll `reticle_session({ action: "list" })` until your tab appears. Readiness is server-internal now, so the first live call already blocks until the SDK connects.
-1. `reticle_session { action: "list" }` finds the connected tab (omit `sessionId` if there's only one). **An empty list is not a dead end: read the `why` field.** It names which case this is (no app running, an app running that has never dialled this daemon, a project that never went through `init`, or a tab that closed) and the fix for each. Do not fall back to static reasoning until you have read it.
-2. `reticle_domain` learns the app BEFORE testing: the saved flows, what each asserts, and the **gaps** (declared signals/testids that no flow verifies, i.e. untested intent). Tells you what to test and where the real risk is without crawling the whole app. Falls back to `reticle_capabilities` for the raw testable surface (`testids`, `signals`, `stores`, `flows`).
+1. **First move, always:** `reticle_session { action: "list" }` finds the connected tab. Just ran `reticle init` or restarted the dev server? You do not need to poll: live tools wait briefly for a tab that is about to connect. Omit `sessionId` if there's only one tab. **An empty list is not a dead end: read the `why` field.** It names which case this is (no app running, an app running that has never dialled this daemon, a project that never went through `init`, or a tab that closed) and the fix for each. Do not fall back to static reasoning until you have read it.
+2. `reticle_run({ tool: "reticle_domain", args: {} })` learns the app BEFORE testing: the saved flows, what each asserts, and the **gaps** (declared signals/testids that no flow verifies, i.e. untested intent). Tells you what to test and where the real risk is without crawling the whole app. Falls back to `reticle_run({ tool: "reticle_capabilities", args: {} })` for the raw testable surface (`testids`, `signals`, `stores`, `flows`).
 3. Run the loop: **look → act → observe → assert**, cross-checking the 4 layers on anything that matters.
 
 ## Token note
@@ -171,5 +168,5 @@ Recent additions, each of which answers a question agents were previously asking
 - **Re-look with `reticle_look({ action: "page", diff:true })`** after an action; it returns only what changed (`mode:delta`/`unchanged`), ~99% fewer tokens than a full re-snapshot and no stale tree to mis-read. Every snapshot/query result carries `cost:{ bytes, tokens }`, so re-scope before reading if it's large.
 - **Cap broad reads.** `reticle_look { action: "find" }` takes `limit` (caps descriptors; reports `total`/`truncated`) and `count_only` (just the match count). `reticle_observe { action: "network" }` / `reticle_observe { action: "console" }` take `limit` (most-recent-N, reports `droppedOldest`) and carry the same `cost` hint, so a busy page or wide window never floods your context unnoticed.
 - **A saved flow tells you if it's a real test.** `reticle_flow_save` returns `assertions.grade` (`asserted` / `presence-only` / `assertion-free`); if it's not `asserted`, add a consequence (`reticle_annotate` assert-signal/assert-net or a success-state) so it can't pass while broken. On replay, an ambiguous heal (two testids tie) is surfaced, never auto-applied. And an `apply` heal re-replays the rebound flow and **refuses to write** if the success consequence no longer fires (`status:consequence_broken`): it heals the locator, never the intent.
-- **Predicate schema is not bloated.** The recursive predicate DSL used by `reticle_assert` / `reticle_assert { action: "wait" }` / `reticle_act_and_wait` is **factored, not inlined**: when converted to the JSON Schema MCP sends, the predicate body is emitted **once** (~2.7k chars ≈ **~685 tokens** per tool) and recursion is handled by self-`$ref` (`#/properties/predicate`), with no per-recursion duplication. No action needed.
-- **One tool surface, and a hatch behind it.** Reticle advertises navigate/act/act_and_wait/assert/look/observe/session/verify, plus `reticle_tools` and `reticle_run`. That is the whole detect loop, the file-pointer, the feedback channel, the handback, and the one tool that CONCLUDES, reached by an `action` argument rather than by a name each. `reticle_tools` discovers: no args lists every registered tool name and summary, `names:[…]` loads full params on demand. `reticle_run { tool, args }` then calls any of them, advertised or not, which is what keeps recording a flow, screenshots, visual diff, storage, network mocking and the clock reachable without spending a slot on each. A daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read at startup, so restart it) advertises the full table outright, with output schemas. `reticle_verify` is advertised: `{ action:"flows" }` replays every saved flow with no model in the loop, and `{ action:"crawl" }` drives every reachable control itself and reports the whole fault set in one call. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.
+- **Predicate schema is not bloated.** The recursive predicate DSL used by `reticle_assert` / `reticle_assert { action: "wait" }` / `reticle_act_and_wait` is defined once (`PredicateSchema` in `@reticlehq/core`) and shared by all three tools. No action needed.
+- **One tool surface, and a hatch behind it.** Reticle advertises navigate/act/act_and_wait/assert/look/observe/session/verify, plus `reticle_tools` and `reticle_run`. That is the whole detect loop, the file-pointer, the feedback channel, the handback, and the one tool that CONCLUDES, reached by an `action` argument rather than by a name each. `reticle_tools` discovers: no args lists every registered tool name and summary, `names:[…]` loads full params on demand. `reticle_run { tool, args }` then calls any of them, advertised or not, which is what keeps recording a flow, screenshots, visual diff, storage, network mocking and the clock reachable without spending a slot on each. A daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read at startup, so restart it) advertises a wider set outright (the default tools plus the extra ones listed above), with output schemas, under the unmerged names listed above. It is not the whole registry: the count is capped because editors budget tools across every connected MCP server. `reticle_verify` is advertised: `{ action:"flows" }` replays every saved flow with no model in the loop, and `{ action:"crawl" }` drives every reachable control itself and reports the whole fault set in one call. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.

package/docs/architecture.md

@@ -44,14 +44,14 @@ Reticle is a pnpm + Turborepo monorepo. The split is not cosmetic: each boundary
 | `@reticlehq/babel-plugin`, `@reticlehq/next`, `@reticlehq/vite-plugin` | build time | Stamp `data-reticle-source` for source mapping (and, for Vite, inject `connect()`) | Plain tooling |
 | `@reticlehq/electron` | Electron main process | Adapter for the desktop runtime: IPC observer, main-process capture | Desktop-only, outside the web gates |
 | `adapters/realm/tauri` (`reticle-tauri`) | Tauri (Rust) | Capture backend for the Tauri desktop runtime | Rust, outside every JS gate; compiled by CI's `rust`/`rust-macos` jobs |
-| `@reticlehq/test` | Node (dev dependency) | Spec runner + matchers used by CI's own test suites | Peer dependency on `vitest` |
-| `@reticlehq/eslint-plugin` | dev tooling | Repo-internal lint rule: a state change must fire a signal | Dev-only, never shipped in a user's bundle |
+| `@reticlehq/test` | Node (dev dependency) | Spec runner + matchers for running Reticle checks in your CI | Peer dependency on `vitest` |
+| `@reticlehq/eslint-plugin` | dev tooling | Lint rule for your app: a state change must fire a signal | Dev-only, never shipped in a user's bundle |
 
 > Note: pre-2.0, `@reticlehq/core` was a single umbrella package that re-exported all of the above under subpaths. In 2.0 the umbrella was retired and `@reticlehq/core` became the bottom-of-graph wire contract.
 
 **Why core-as-contract matters:** because the browser and the server are two different runtimes (a DOM and a Node process) that must agree exactly on every message, the temptation is to inline a string like `"net.request"` in both. That's how drift and silent breakage start. Instead, every such string and shape lives once in `@reticlehq/core` as a named constant + a zod schema.
 
-The browser and server both import it; neither can invent a message the other doesn't understand. The server zod-parses **every** inbound WebSocket message; malformed input closes the socket rather than flowing into logic.
+The browser and server both import it; neither can invent a message the other doesn't understand. The server zod-parses **every** inbound WebSocket message; malformed input never flows into logic. A malformed `HELLO` is refused, and a malformed frame on a live session is dropped and recorded as a gap in that window.
 
 ---
 
@@ -87,7 +87,7 @@ The same verification runs over and over, every commit, every CI run. Reticle re
 
 ### 4. Dev-only, localhost-only, your app data stays local
 
-The SDK is tree-shaken out of production builds and connects only to a local bridge. The bridge binds to loopback by default; exposing it beyond localhost _requires_ a pairing token (the server refuses to bind a non-loopback host without one). Every environment variable that gates a security control is a single named constant, so a typo can't silently disable auth. Nothing from the app under test ever leaves your machine: no DOM, network, console, state, or source. The CLI reports anonymous, opt-out usage metrics only (a random id + event names like `invoke`/`session_start`; no code, no PII; see [telemetry](telemetry.md)); opt out with `reticle telemetry disable`, `RETICLE_TELEMETRY=0`, or `DO_NOT_TRACK=1`. The one thing that carries free text is feedback you or your agent deliberately send (`reticle feedback` / `reticle_session { action: "feedback" }`). It is never collected passively, it is redacted before sending, and it is disabled separately with `RETICLE_FEEDBACK=0`.
+The SDK is tree-shaken out of production builds and connects only to a local bridge. The bridge binds to loopback by default; exposing it beyond localhost _requires_ a pairing token (and the server refuses to start on a non-loopback host unless `RETICLE_ALLOWED_ORIGINS` names the app's origins). Every environment variable that gates a security control is a single named constant, so a typo can't silently disable auth. Nothing from the app under test leaves your machine unless you link a project: no DOM, network, console, state, or source. What a linked project syncs is set by `reticle config`; see [what is recorded](what-is-recorded.md). The CLI reports anonymous, opt-out usage metrics only (a random id + event names like `cli_command_run`/`daemon_started`; no code, no PII; see [telemetry](telemetry.md)); opt out with `reticle telemetry disable`, `RETICLE_TELEMETRY=0`, or `DO_NOT_TRACK=1`. The one thing that carries free text is feedback you or your agent deliberately send (`reticle feedback` / `reticle_session { action: "feedback" }`). It is never collected passively, it is redacted before sending, and it is disabled separately with `RETICLE_FEEDBACK=0`.
 
 ---
 
@@ -119,7 +119,7 @@ This is plain, reviewable, version-controllable data, not a black box.
 - The **server / CLI** is under the **Functional Source License (FSL-1.1, Apache-2.0 future)**: source-available, converts to Apache-2.0 over time.
 - Enterprise-only features live behind a license gate and are clearly separated.
 
-See [LICENSE](../LICENSE) and each package's own `LICENSE` file. The licensing _mechanism_ is open and inspectable; activation is offline (no phone-home).
+See [LICENSE](https://github.com/reticlehq/reticle/blob/main/LICENSE) and each package's own `LICENSE` file. The licensing _mechanism_ is open and inspectable; activation is offline (no phone-home).
 
 ---
 

package/docs/autodrive.md

@@ -1,19 +1,20 @@
 ---
 title: Let Reticle drive
-description: Hand the whole drive to a model inside the daemon, and get the flows it recorded back, so every run after the first one replays with no model in the loop.
+description: Hand the whole drive to the Reticle Harness on the platform, and get back the flows it recorded, so every run after the first one replays with no model in the loop.
 icon: steering-wheel
 ---
 
 Driving an app is the expensive part of verifying one. Every snapshot, every act result and every observation lands in your agent's context and is re-read on every turn after, and none of it is kept: the next run starts from nothing and pays again.
 
-`reticle_verify { action: "explore" }` moves the driving into the daemon. A model there drives your app through the same tool surface your agent uses, records what it drove as saved flows, and hands back a few lines.
+`reticle_verify { action: "explore" }` hands the driving to the Reticle Harness. It decides on the Reticle platform, and the daemon on your machine executes each step through the same tool surface your agent uses, records what it drove as saved flows, and hands back a few lines. It needs a linked project (`reticle connect`).
 
 ```jsonc
 reticle_verify {
   action: "explore",
   persona: "a returning customer checking out with a saved card"
 }
-// → { stopReason, steps, savedFlows: ["checkout"], summary, usage }
+// → within `wait` seconds (default 50): { status, runId, stopReason, steps, savedFlows: ["checkout"], summary, usage, ... }
+//   still driving: { status: "running", runId }, poll again with that runId
 ```
 
 From the command line, on a project with nothing recorded yet:
@@ -32,57 +33,61 @@ So the drive is a one-off: pay for it once, and the journeys it recorded become
 
 A drive reads `.reticle` first: every saved flow with the consequence that must still hold, and every signal and testid your app declares that no flow has ever asserted. It builds a plan from that before it opens its eyes on a page.
 
-Anything already recorded is **replayed**, deterministically, with no model call at all. Only the gaps are driven. So a second run over the same app is mostly free, and the model budget is spent on the part nobody has proved yet rather than on rediscovering what is already on disk. A replay that goes red is reported as a regression; one that DRIFTS is reported separately, because the app moved under the recording and that needs re-anchoring rather than a code change.
+With no persona, anything already recorded is **replayed**, deterministically, with no model call at all, and only the gaps are driven (see the plan below). With a persona, it drives that journey and replays nothing else: the saved flows have nothing to do with the journey you named. So a second run over the same app is mostly free, and the model budget is spent on the part nobody has proved yet rather than on rediscovering what is already on disk. A replay that goes red is reported as a regression; one that DRIFTS is reported separately, because the app moved under the recording and that needs re-anchoring rather than a code change.
 
 Every journey a drive walks is saved, whatever happens to the drive, including one that broke, ran out of budget, or whose model simply stopped asking for tools.
 
-## What it needs
+## The platform plans the drive
 
-**A model in the daemon's environment.** Any one of three, and the choice is reported back so a comparison can never mislabel its own arms:
+The platform plans every drive (link the project once with `reticle connect`, or set `RETICLE_API_KEY` in CI). With a persona or without one, it proposes the people worth being, orders the saved flows, finds where they branch, and writes into each journey the product rules that apply to it, read from your project's own intents. The rules tell the Harness what the journey is for and where it ends (a journey that names Settings is not finished before Settings). They are not checked as assertions: a rule like "the row shows refunded" is guidance, and the checks are the consequences each step declares. Your machine sends what the project knows, with each saved step as a short hash and never the values it typed. It runs the plan it gets back and reports what happened. The plan is checked before it runs, and a plan that fails the checks is dropped. Every decision while it drives is the platform's too: your machine executes each step it is handed and reports what happened.
 
-| Variable | Driver |
-| --- | --- |
-| `RETICLE_API_KEY` | `jev`, against the platform's own proxy, using the key `reticle link` already wrote. No model API key of your own, and the cheap path: it answers typed questions about the page rather than generating tool calls as text. |
-| `ANTHROPIC_API_KEY` | `anthropic`, which generates its calls as text. |
-| `OPENAI_API_KEY` | `openai`, the same, on OpenAI. |
-| `JEV_API_KEY` | `jev`, against TypeSafe directly, for anyone who holds their own key. |
+## With no persona, it writes a plan first
 
-With several configured, `anthropic` is the default and `RETICLE_HARNESS_DRIVER` moves off it; with only a platform key, `jev` is not the cheaper option, it is the only one. Naming a driver that is not configured is an error, never a silent substitution.
+Called with no `persona`, explore writes the whole drive down before it starts, as a drive plan:
 
-A driver can also be chosen per call, as `reticle_verify { action: "explore", driver: "jev" }`. The question people actually have is comparative, and answering it with an environment variable means restarting the daemon between arms.
+- **Journeys.** Each saved flow worth replaying, plus one open journey for each persona the platform proposes, for the request the user declared (`reticle_run { tool: "reticle_intent", args: { action: "declare" } }`), and for each intent nobody has proved. Replays need no model; only open journeys reach one.
+- **Order.** A flow that `needs` another runs after it. An open journey runs after the flow everything else needs, usually sign-in.
+- **Lanes.** Each journey nothing else needs gets a lane holding what it needs, in order. Lanes run side by side, each in its own leased browser context, up to four at a time (fewer when the browser pool has less room). A journey that needs one from another lane waits for it, and is blocked if that journey failed. A prerequisite that commits something (a payment, an email) runs in one lane only, and the others wait on it rather than commit it twice.
+- **Branches.** Flows that start with the same steps become one journey. The shared steps are driven once and marked as a checkpoint, then each flow continues from that point. Every flow after the first replays back to the checkpoint first, so none of them starts from the page the previous one left.
 
-Three other dials, all optional:
+The plan appears at the top of the HUD's Agent Log: one row per lane, a card per journey, the running journey opened to its steps, and each card marked as it passes, fails or is blocked. The tool's answer carries one line per journey.
+
+Two arguments of the flow replay make the branches possible, and you can use them directly through `reticle_run { tool: "reticle_flow_replay", args: { flowName, to | at } }`. `to` stops before a step. `at` continues at a step on the page as it is, without driving the steps before it. A part-way replay checks the steps it drove and records nothing about the flow as a whole.
+
+## What it needs
+
+**A project on the Reticle platform.** Every plan includes the Harness. A new account gets 10 free credits (about two full drives of a small app), a card starts a 14-day trial with 500, and the paid plan includes 1,000 credits per seat each month. Run `reticle connect` once in your app's folder. The Harness runs on the platform: planning, personas, and every choice of what to press next. A model key of your own does not drive it, and a machine with no platform link gets the refusal and the way to fix it.
 
 | Variable | What it does |
 | --- | --- |
-| `RETICLE_HARNESS_MODEL` | The Anthropic model that drives. Defaults to a mid-tier one on purpose, for the reason below. |
-| `RETICLE_HARNESS_MAX_STEPS` | Ceiling on model turns in one drive. Bounds cost, not value. |
-| `RETICLE_HARNESS_BASE_URL` | A proxy or gateway instead of the default API host. |
-
-## Two models, and what each one is for
+| `RETICLE_API_KEY` | For CI, where nobody ran `reticle connect`. Locally the daemon uses the key `connect` stored in `~/.reticle/credentials.json`; either way it is what asks the platform to drive. |
+| `RETICLE_HARNESS_MAX_STEPS` | Ceiling on steps in one drive. Bounds cost, not value. |
+| `RETICLE_SECRET_<FIELD>` | The value for a secret field, such as `RETICLE_SECRET_AUTH_PASSWORD` for a field named `auth-password`. Only the field's NAME goes to the platform. The value is typed in on your machine and never sent. |
 
-The `jev` driver decides; it cannot write. Every choice a drive makes is a selection from candidates Reticle enumerated off the page: which element, which tool, what consequence to claim. That is why it costs a fraction of a generating model and answers in a few hundred milliseconds.
+**What you see.** The HUD's Agent Log marks the moment the Harness takes over ("Reticle Harness is driving") and gives its steps their own colour, so you can tell its work from your agent's. Each Harness drive is recorded as its own run, named for its journey and credited to the Harness, beside your agent's run. Any "double-quoted text" in a persona must be on the page when the journey ends, and is checked.
 
-One thing in a drive is not a selection. A text field is a composition: "a business name", "a statement descriptor", "a search term that returns results" cannot be enumerated from the page. Where the field's label is enough to guess, a small table answers it. Where it is not, and a generating model is configured, that model writes the value, and nothing else.
+## How it decides
 
-Typing is a small minority of what a drive does: clicks and navigations are the overwhelming majority. So this is escalation rather than a second model in the loop, and a drive with no text fields never calls it at all.
+The platform drives with Jev, a System One model that answers typed questions and cannot write. Every choice is a selection from candidates read off the page: which element, which tool, what consequence to claim. Three rules sit around those choices, because each one was a drive that stopped short or claimed nothing:
 
-What it writes is a FIXTURE, not an opinion. Generated values are saved to `.reticle/fill-values.json` and reused forever: the second drive pays nothing, a replay sends exactly what the recording sent, and a value you dislike is a line in a git-checked file you can edit rather than an argument with a model.
+- A journey that names a page it has not reached ("then turn on automatic refunds in Settings") is not finished. The Harness goes there instead of stopping.
+- A dialog whose destructive action already ran is closed rather than treated as the end of the journey.
+- A control the destructive-action gate refused is a write, so the Harness always claims a request or a signal for it. A save the server rejects then fails visibly instead of passing as nothing to prove.
 
 ## Turning it off, and who pays for it
 
 A project linked to a Reticle workspace reads two things from it before a drive starts, and honours both:
 
-- **The switch.** Autonomous driving can be turned off per project in the dashboard, under Settings → Verification model. A drive then refuses and says where to turn it back on. Everything else is unaffected, including the tools your own agent drives with.
-- **Who is paying.** Driving through the platform spends Reticle's model budget, which is free for three months once claimed and included on a paid plan. Outside both, a drive is refused with the claim link rather than run on somebody else's money.
+- **The switch.** Autonomous driving can be turned off per project, from the HUD's Reticle Harness switch or the dashboard (Settings → Projects → Reticle Harness on <project>). A drive then refuses and says where to turn it back on. Switched off while a platform drive is running, the drive stops at its next turn with `stopReason: "stopped"`, keeps what it drove, and says so in the Agent Log. Everything else is unaffected, including the tools your own agent drives with.
+- **Credits.** Harness drives and dashboard chat checks spend Harness credits. The platform sets the amount for your plan (see above). The HUD shows how many are left; once they are spent a drive is refused with that number and the way to get more.
 
-Neither applies to a drive on a model key of your own: that costs us nothing, so it is not ours to gate. A daemon that cannot reach the platform at all drives normally: an unreachable settings endpoint is not a reason to lose a feature you were never told to stop using.
+If only the settings endpoint is unreachable, the on/off switch and the credit check do not block a drive: an unreachable settings endpoint is not a reason to lose a feature you were never told to stop using. The drive itself still needs the platform, so with no connection at all it is refused with the reason.
 
 ## What it will not do
 
 **It does not decide whether your app is correct.** The model chooses what to _try_; the engine decides what _happened_, from what it recorded. A model that graded its own driving would be scoring its own homework, and its verdict would be unfalsifiable. So the summary it writes is an account of what it drove, and nothing downstream grades from it.
 
-That split is also why the default model is not the largest one available. The harness is exploring an interface and stating expectations, not reasoning about your business logic. If finding defects needed a frontier model _there_, the engine would not be doing its job.
+That split is also why the platform's model is not the largest one available. The harness is exploring an interface and stating expectations, not reasoning about your business logic. If finding defects needed a frontier model _there_, the engine would not be doing its job.
 
 **It really clicks.** A drive navigates, submits forms and mutates state, exactly like the crawl does. Point it at a preview or a dev environment, not production.
 

package/docs/benchmarks.md

@@ -8,7 +8,7 @@ Two different measurements, because there are two different questions.
 
 Against a **Playwright script** over an 88-bug registry, each tool running its own native check deterministically with no model in the loop, Reticle caught **85 of 88** and Playwright **59 of 88**, both with zero false alarms on the clean build. The gap is not spread evenly: it is 26 bugs Playwright **structurally cannot** see, and on everything observable from outside the app the two tie exactly. See Part 5a.
 
-Against **Playwright MCP and Chrome DevTools MCP**, the agent-driven tools where cost per look matters, Reticle caught 10 of 10 injected regressions to Playwright MCP's 9 and DevTools' 8, averaging 815 tokens per look against 1,292 and 758. See Part 5b.
+Against **Playwright MCP and Chrome DevTools MCP**, the agent-driven tools where cost per look matters, Reticle caught 10 of 10 injected regressions to Playwright MCP's 9 and DevTools' 8, averaging 815 tokens per look against 1,292 and 758. That pass last ran on 2026-06-22, against versions of both tools that have since moved on. See Part 5b.
 
 Where Reticle loses is stated plainly in Part 5, and it loses in more places than these two tables show.
 
@@ -28,7 +28,7 @@ There are roughly three ways teams do this:
 
 1. **Manual testing.** A human clicks through the app. Accurate, but slow and easy to skip.
 2. **Automated tests**: code that clicks through the app for you. Fast to re-run, but expensive to write and notoriously **flaky** (they break for reasons unrelated to real bugs).
-3. **Nothing.** Ship and hope. More common than anyone admits: surveys put ~44% of teams with no automated testing at all.
+3. **Nothing.** Ship and hope. More common than anyone admits.
 
 A **regression** is the specific bug this page cares about: something that _used to work_ and quietly _stopped working_ after a change. Regressions are insidious because the feature looked done, right up until a later edit broke it and nobody noticed.
 
@@ -151,7 +151,7 @@ Bug registry: `bench/pw-vs-reticle/bugs.mjs`. Runner: `bench/pw-vs-reticle/run.m
 
 ### 5b. The controlled toy app (the demo)
 
-Measured on the observation-cost pass (numbers regenerate from `bench/raw/`):
+Measured on the observation-cost pass (numbers regenerate from `bench/raw/`). The cross-tool passes last ran on 2026-06-22, against `@playwright/mcp@0.0.76` and `chrome-devtools-mcp@1.3.0`; re-run `pnpm bench:full` before quoting a competitive delta:
 
 | Tool | Bugs caught (of 10) | Detection accuracy | Avg tokens per look | Verification Efficiency |
 | --- | --- | --- | --- | --- |
@@ -201,7 +201,7 @@ Honesty is the point of this page, so here are the places Reticle does **not** w
 
 The numbers above are for **one** verification. But a test suite's real job is the **same** check, over and over, every commit, every CI run. Here the picture changes shape:
 
-- Reticle records a flow once, then **replays it with no AI model at all** (re-resolving each element and re-asserting the outcome) for **~239 tokens per run** (re-measured 2026-08-11; it was ~175 before each flow started carrying a success oracle).
+- Reticle records a flow once, then **replays it with no AI model at all** (re-resolving each element and re-asserting the outcome) for **~239 tokens per flow, per run** (re-measured 2026-08-11). Verifying a whole four-flow suite in one call reads **~480 tokens** for the suite (re-measured 2026-10-06; see `bench/SCORECARD.md`), about 60 tokens per added flow.
 - Playwright MCP and DevTools MCP have no replay: re-checking means an agent **re-drives the whole flow with the model every time**, costing tens of thousands of tokens per run.
 
 That's a **~127× cost difference per re-run**, and it grows with how often you run. This is where the "much cheaper than screenshots" claim becomes dramatic rather than incremental.
@@ -227,7 +227,7 @@ A fleet of agents (or a parallel suite) verifying the same app doesn't need a br
 
 - **Every number comes from a committed harness**, not a slide. Re-run it: `pnpm bench`.
 - **A no-bug control** runs in every pass, so a tool can't look good by flagging everything.
-- **Tool versions are pinned**; the raw payloads are saved to `bench/raw/` so anyone can audit them.
+- **Tool versions are recorded by hand in `bench/README.md`; re-derive before quoting.** The raw payloads are saved to `bench/raw/` so anyone can audit them.
 - **The token counter is a tokenizer**, not a guess. Where we use a proxy tokenizer instead of a specific model's, we say so and lean on _relative_ differences, which are robust to the choice.
 - **We publish where we lose** (above). A benchmark that only flatters its author isn't a benchmark.
 

package/docs/best-practices.mdx

@@ -5,7 +5,7 @@ description: The habits that make a verdict worth trusting, and the specific mis
 icon: star
 ---
 
-A green is worth trusting when you named the consequence **before** you acted, ended the run on `reticle_act_and_wait` or `reticle_assert` (nothing else produces a verdict), scoped the assertion with `since`, and read `verified` rather than `pass`. Everything below is one of those habits, or the specific mistake that breaks it.
+A green is worth trusting when you named the consequence **before** you acted, ended the run on a call that produces a verdict (`reticle_act_and_wait`, `reticle_assert`, a `reticle_act { steps }` whose last step declares `expect`, or `reticle_verify`), scoped the assertion with `since`, and read `verified` rather than `pass`. Everything below is one of those habits, or the specific mistake that breaks it.
 
 Everything here comes from driving Reticle against real apps and getting it wrong first. None of it is theoretical, and several entries exist because they bit us while writing these docs.
 
@@ -27,7 +27,7 @@ An agent that acts first and then decides what counts as success will always fin
 
 ## A drive that ends on `reticle_act` proved nothing
 
-Only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Everything else moves or reads the app.
+Verdicts come from `reticle_act_and_wait`, `reticle_assert`, `reticle_act { steps }` when a step declares `expect`, and `reticle_verify` (`change`/`flows`). Everything else moves or reads the app and proves nothing. Only `verified: "yes"` is a pass: `unknown` means Reticle could not tell, and `no-fault` means nothing was declared to prove.
 
 This is not pedantry. Here is a real `act_sequence` response:
 
@@ -37,7 +37,7 @@ This is not pedantry. Here is a real `act_sequence` response:
 
 `ok: true`, and the login **failed**. `ok` means the actions were dispatched, which they were. If your run ends there, you have a green tick attached to a broken flow.
 
-**Batch the setup, prove the outcome.** Use `act_sequence` for the fills, then `act_and_wait` on the final click.
+**Batch the setup, prove the outcome.** Use `reticle_act { steps }` for the fills, then `act_and_wait` on the final click.
 
 ## Treat `unknown` as unknown
 
@@ -172,10 +172,10 @@ If you relax a predicate, you should be able to say why the _original_ expectati
 
 | Instead of | Use | Why |
 | --- | --- | --- |
-| `snapshot` on every turn | `snapshot { mode: "status" }` | 25 tokens to answer "where am I?" |
-| `snapshot` then reading it | `query { by: "testid" }` | Retrieval, not orientation |
-| `query` to count rows | `query { count_only: true }` | Around 30x smaller |
-| `observe` for one question | `network` or `console` | The summary block is usually enough |
+| `look { action: "page" }` on every turn | `look { action: "page", mode: "status" }` | 25 tokens to answer "where am I?" |
+| `look { action: "page" }` then reading it | `look { action: "find", by: "testid" }` | Retrieval, not orientation |
+| `look { action: "find" }` to count rows | `look { action: "find", count_only: true }` | Around 30x smaller |
+| `observe` for one question | `observe { action: "network" }` or `{ action: "console" }` | The summary block is usually enough |
 | Re-snapshotting after each act | Reuse the `ref` | Refs stay valid until the element leaves the DOM |
 
 Every response carries `cost: { bytes, tokens }`. If a loop is expensive, that field tells you which call to fix.
@@ -192,11 +192,29 @@ Sessions accumulate. Four stale ones pointing at dev servers you restarted an ho
 { "action": "yield", "mode": "waiting" }
 ```
 
-`yield` when you are pausing, `end` when you are done. Both revive on your next action, so neither is destructive. The difference is what the human watching the panel is told. The panel reads "live" until you say otherwise.
+`yield` when you are pausing, `end` when you are done. A yielded session revives on your next action; `end` is terminal, so use it only when the whole task is complete. The difference is also what the human watching the panel is told. The panel reads "live" until you say otherwise.
+
+## End with the Reticle result
+
+`reticle_verify` (`flows` and `change`) and `reticle_session { action: "end" }` return `reticleResult`: a short markdown block the server builds from the verdicts it holds. Paste it to the user verbatim as the last thing you say. It reads the same wherever it came from:
+
+```md
+**Reticle result: proved** · 3 of 3 checks held
+
+- Checks: 3 yes · 0 no · 0 undecided
+- Covered: checkout-pay, login
+- Metrics: 3 checks · 2 flows replayed · 4.2s
+- Evidence: .reticle/visual/runs/r1/0001-act.jpg, .reticle/visual/runs/r1/0002-act.jpg
+- Run on the dashboard: https://app.reticle.sh/runs/r1
+```
+
+- The verdict line has three words only: **proved**, **not proved**, **failed**. One undecided check makes the whole result not proved. Do not reword it into a pass.
+- A metric Reticle did not measure is left out, never printed as zero. Model tokens saved by replay are not measured per run, so the block never claims them.
+- The last line is about the platform, once per result. Linked, it links the run. Not linked, it says what the platform adds (run history, your team, Reticle Harness), the trial, and `npx @reticlehq/server connect`. Keep it; do not repeat it elsewhere.
 
 ## Confirm a navigation landed
 
-`reticle_navigate` returns `confirmed: false` by design. A navigation destroys the document the SDK lives in, so it can only report dispatch. Check [`reticle_session { action: "list" }`](/tools/sessions) for a session at the new URL before acting, and re-snapshot: refs do not survive a new document.
+`reticle_navigate`'s `ok` only means the navigation was dispatched: it destroys the document the SDK lives in. It then waits up to `timeout_ms` (default 5000) for the SDK to reconnect. `confirmed: true` with a `sessionId` means the page arrived; `confirmed: false` with `landedOn` means a redirect took it elsewhere; `confirmed: false` alone means it was not seen in time. Re-snapshot either way: refs do not survive a new document.
 
 ## Start with what the app says about itself
 

package/docs/capabilities.mdx

@@ -4,7 +4,7 @@ description: Coverage, storage, fake clocks, autonomous crawling, visual diffing
 icon: sparkles
 ---
 
-These are the Reticle tools that do something other than look, act, observe and assert: control coverage, client storage, a fake clock, autonomous crawling, semantic and visual baselines, network mocking, flow recording and replay, and the CI artifact. Reach for them when the verify loop is not the shape of the question. They are **not advertised on the default tool surface, but they are reachable from it**: `reticle_run({ tool, args })` dispatches to any registered tool by name, advertised or not, which is the spelling used on this page. To have them advertised outright instead, with their output schemas, start the daemon with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read once at startup, so restart it) and call them by name.
+These are the Reticle tools that do something other than look, act, observe and assert: control coverage, client storage, a fake clock, autonomous crawling, semantic and visual baselines, network mocking, flow recording and replay, and the CI artifact. Reach for them when the verify loop is not the shape of the question. They are **not advertised on the default tool surface, but they are reachable from it**: `reticle_run({ tool, args })` dispatches to any registered tool by name, advertised or not, which is the spelling used on this page. Starting the daemon with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read once at startup, so restart it) advertises some of them outright, with their output schemas: storage, clock, screenshot, visual diff, network mocking, recording, flow save and replay. The rest stay behind `reticle_run` on every surface.
 
 Most of the time you want the verify loop. Look, act, observe, assert. These are the tools for the times you want something else, and they are the ones people are most surprised exist.
 
@@ -255,11 +255,10 @@ Records the meaningful state of a page and compares later. Structure and content
 
 ## Needs a driven browser
 
-Four tools apply their effects through the Chrome DevTools Protocol. The always-on SDK cannot do that, so they need a browser Reticle is driving.
+Four tools apply their effects through the Chrome DevTools Protocol or a browser page Reticle owns. The always-on SDK cannot do that, so they need a browser Reticle is driving (`reticle drive <url>`, or `RETICLE_CDP_URL` pointed at a Chrome started with `--remote-debugging-port`) or a leased tab (`reticle_lease { action: "acquire" }`).
 
 <Warning>
-**A pooled lease is not enough.** Re-verified on 2026-08-16: acquire one with `reticle_lease` and
-`reticle_screenshot` answers
+On a tab the SDK alone is connected to, `reticle_screenshot` answers
 
 ```json
 {
@@ -269,9 +268,7 @@ Four tools apply their effects through the Chrome DevTools Protocol. The always-
 }
 ```
 
-while `reticle_network_mock` answers `{ "applied": false, "count": 0, "ok": false, "reason": "no-cdp-provider" }`. Under a driven browser, all four work: the captures below were taken that way.
-
-Run `reticle drive <url>`, or point `RETICLE_CDP_URL` at a Chrome started with `--remote-debugging-port`.
+and `reticle_network_mock` answers `{ "applied": false, "count": 0, "ok": false, "reason": "no-cdp-provider" }`. The captures below were taken under a driven browser.
 
 </Warning>
 
@@ -317,7 +314,7 @@ Run `reticle drive <url>`, or point `RETICLE_CDP_URL` at a Chrome started with `
   mistake to make twice.
 </Warning>
 
-`fullPage` captures the whole scroll height. `ref` or `clip` scopes to one element or region. `threshold` sets the pixel-difference tolerance, defaulting to `0.01`, `maxRatio` caps the acceptable changed fraction, and `masks` excludes regions that are expected to change.
+`fullPage` captures the whole scroll height. `ref` or `clip` scopes to one element or region. `threshold` sets the pixel-difference tolerance, defaulting to `0.1`, `maxRatio` caps the acceptable changed fraction, and `masks` excludes regions that are expected to change.
 
 Reticle reads program truth, not pixels, so this is the deliberate exception: a font that failed to load or a compositing glitch is only visible in the actual frame.
 
@@ -361,11 +358,11 @@ The loop closer, and the reason Reticle is not only an interactive tool.
 { "tool": "reticle_verify", "args": { "action": "flows" } }
 ```
 
-<Warning>
-  The argument names are not interchangeable. `reticle_record` takes **`recordingName`**,
-  `reticle_flow_save` takes **`flowName`**, and neither accepts `name`. Reticle rejects the call
-  rather than guessing, which is the right call and still costs you a turn.
-</Warning>
+<Note>
+  `reticle_record` takes **`recordingName`** and `reticle_flow_save` takes **`flowName`**. Both also
+  accept `name` as an alias. `flowName` on `reticle_flow_save` is the recording to save; pass
+  `saveAs` to choose the flow's file name.
+</Note>
 
 Stopping a recording used to return a very large payload, almost all of it the raw `events` array. It no longer does. The timeline is omitted and replaced with a pointer, so a stop is under a kilobyte. This is a real capture of a one-click recording, complete rather than trimmed:
 
@@ -394,8 +391,9 @@ Each step's `args` is elided above because a recorded step is an anchor, not a c
 Nine hundred and fifty-three bytes for 445 recorded events. `timeline_omitted` hands you the exact `reticle_observe` call to make if you want them, so nothing is lost, it is only not charged for by default.
 
 <Note>
-  `reticle_record` takes `action`, `recordingName` and `sessionId` and nothing else. `max_events`
-  and `filters` are rejected, which no longer matters now that the timeline is omitted anyway.
+  `reticle_record` takes `action`, `recordingName` (or its alias `name`) and `sessionId`, and
+  nothing else. `max_events` and `filters` are rejected, which no longer matters now that the
+  timeline is omitted anyway.
 </Note>
 
 `proposedConsequences` is the useful part and the reason to record at all. Reticle watched the interaction and worked out what would have proved it, ranked by strength. Tier 0 is the app's own signal. You do not have to invent the assertion; you pick one.
@@ -427,7 +425,7 @@ Nine hundred and fifty-three bytes for 445 recorded events. `timeline_omitted` h
 
 Reticle grades the flow as you save it, and tells you when you have just created a test that cannot fail. Take the warning seriously: an assertion-free flow replays green whatever the app does.
 
-A replay against a drifted app names what moved and where. This is `reticle_verify {action:"flows"}` reporting the same flow after the app changed underneath it:
+A replay against a drifted app names what moved and where. This is `reticle_verify { action: "flows" }` reporting the same flow after the app changed underneath it:
 
 ```json
 {

package/docs/cli/affected.mdx

@@ -4,7 +4,7 @@ description: List which saved flows must re-verify for a set of changed files.
 icon: code-branch
 ---
 
-`reticle affected` answers one question: given these changed files, which saved flows cover them? It is the foundation the [gate](/cli/gate) and [watch](/cli/watch) are built on, and it costs your agent nothing per turn because it runs in the environment.
+`reticle affected` answers one question: given these changed files, which saved flows cover them? It is the foundation the [gate](/cli/gate) is built on, and it costs your agent nothing per turn because it runs in the environment.
 
 ```bash
 npx @reticlehq/server affected [--since <ref>] [file...]