@reticlehq/server 3.6.0 → 3.7.0

package/docs/tools/sessions.mdx

@@ -51,7 +51,7 @@ A backgrounded tab adds a `recommendation` telling you what to do about it, and
     "outages": 3,
     "lastOutage": { "startedMs": 1786818483776, "durationMs": 967 }
   },
-  "recommendation": "tab hidden/throttled and may be un-focusable from here; refocus it, or run `reticle drive <url>` for a guaranteed scriptable context"
+  "recommendation": "tab is not hidden but has not reported health recently ... Timing-sensitive work (animations, debounces, gestures) is what degrades: pass `refuseWhenThrottled: true` to refuse rather than act over events that may not land. Lease a separate context only if a drive here actually fails; ..."
 }
 ```
 
@@ -62,27 +62,27 @@ An empty list is not silent. It comes back with a `why` that separates the two c
 ```json
 {
   "sessions": [],
-  "why": "no browser session connected. Two things to weigh, and neither of them is proof. (1) Nothing is listening on the ports Reticle scans, so the dev server may not be running. That scan is narrow though: a server on any other port is invisible to it, so if the app IS running, ask for its URL rather than assuming it is down, and open it with `reticle open <url>`. (2) There is no `.reticle.json` in the directory this daemon is running in. That is the file `reticle init` writes, so the app may carry no Reticle SDK."
+  "why": "no browser session connected. Two things to weigh, and neither of them is proof. (1) Nothing is listening on the ports Reticle scans, so the dev server may not be running: START IT YOURSELF, in the background, using the command in `next_action`, and tell the human in one line that it is running. (2) There is no `.reticle.json` in the directory this daemon is running in, which is the file `reticle init` writes, so the app may carry no Reticle SDK. Check the app's OWN directory before re-running it. ..."
 }
 ```
 
-That string is trimmed. The full text also lists the exact ports it scanned and warns that in a monorepo the daemon often runs at the root while the app lives in a subdirectory, so you should check the app's own directory before re-running `init`.
+That string is trimmed. The full text also lists the exact ports it scanned, says a server on any other port is invisible to the scan (ask for the app's URL and open it with `reticle open <url>`), and warns that in a monorepo the daemon often runs at the root while the app lives in a subdirectory.
 
 ## The fields that decide whether driving will work
 
 | Field | Why it matters |
 | --- | --- |
-| `throttled` | The browser is deprioritising a background tab. Synthetic timers and pointer gestures may silently no-op |
+| `throttled` | The tab is hidden, or has not reported health recently. A hidden tab clamps timers and animation frames, so an action can land on a page that never advances; a throttled tab that is not hidden is usually just quiet and often still driveable |
 | `hidden` / `focused` | Why it's throttled, and what to do about it |
-| `hasCapabilities` | Whether the app registered testids, signals and stores. `false` means [`reticle_state`](/tools/state) has nothing to read |
+| `hasCapabilities` | Whether the app registered testids, signals and stores. `false` means [`reticle_look { action: "state" }`](/tools/state) has nothing to read |
 | `adapters` | `["react"]` means you get component names and source pointers |
 | `realInputAvailable` | `true` when native CDP input is available, under `reticle drive` |
 | `outages` | How often the connection has dropped. Non-zero is worth investigating |
 
 <Warning>
-  `throttled: true` is the most common cause of "the click did nothing". Focus the tab, or drive a
-  dedicated context. It is not your app being broken. It is the browser saving battery on a tab
-  nobody is looking at.
+  A hidden tab (`hidden: true`, which also sets `throttled`) is the most common cause of "the click
+  did nothing". Focus the tab, or drive a dedicated context. It is not your app being broken. It is
+  the browser saving battery on a tab nobody is looking at.
 </Warning>
 
 ## Confirm after navigating

package/docs/tools/snapshot.mdx

@@ -39,7 +39,7 @@ icon: camera
 
 Ninety-eight bytes to answer "where am I?". Use it after a navigation instead of re-reading the page.
 
-### `interactive`. the default working view
+### `interactive`. the usual working view
 
 ```json
 { "mode": "interactive" }
@@ -61,7 +61,7 @@ Everything you can act on, with a `ref` for each, for 65 tokens. Note the passwo
 
 | Argument | What it does                                                                 |
 | -------- | ---------------------------------------------------------------------------- |
-| `mode`   | `full` · `interactive` · `status`                                            |
+| `mode`   | `full` (the default) · `interactive` · `status`                              |
 | `scope`  | CSS selector or ref, to snapshot one subtree                                 |
 | `diff`   | Return only what changed since your last snapshot of the same scope and mode |
 
@@ -112,8 +112,8 @@ When something did move, you get only what changed. This is the same call after
 A route change resets it: the next call after one returns a full snapshot rather than a delta against a page that no longer exists.
 
 <Tip>
-  Reach for [`reticle_query`](/tools/query) instead when you already know what you're looking for.
-  Snapshot is for orientation; query is for retrieval, and it's almost always cheaper.
+  Reach for [`reticle_look { action: "find" }`](/tools/query) instead when you already know what
+  you're looking for. `page` is for orientation; `find` is for retrieval, and it's almost always cheaper.
 </Tip>
 
 ## Refs change across documents
@@ -132,5 +132,6 @@ Reticle refuses a stale ref rather than clicking whatever now occupies that slot
 <Note>
   That `recovery` string is trimmed. The full text also recommends
   [`reticle_act_and_wait`](/tools/act-and-wait) with `until`, so the next ref is taken after the
-  page settles.
+  page settles, and, on a page that keeps re-rendering, passing `target: { role, name }` instead of
+  a ref.
 </Note>

package/docs/tools/state.mdx

@@ -11,9 +11,9 @@ icon: database
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
 </Warning>
 
-`reticle_state` reads live framework state straight out of the running app, without the app broadcasting anything. Reach for it when the DOM looks right and you want to know whether the application actually accepted the change, which is where false greens live.
+`reticle_look { action: "state" }` reads live framework state straight out of the running app, without the app broadcasting anything. Reach for it when the DOM looks right and you want to know whether the application actually accepted the change, which is where false greens live.
 
-The DOM tells you what the app _drew_. `reticle_state` tells you what it _believes_. The gap between those two is where false greens live: a row appears in the table, the store never changed, and a reload makes the row vanish.
+The DOM tells you what the app _drew_. `reticle_look { action: "state" }` tells you what it _believes_. The gap between those two is where false greens live: a row appears in the table, the store never changed, and a reload makes the row vanish.
 
 ## Example
 
@@ -68,24 +68,24 @@ Drill in once you know what you want:
 A wrong `path` comes back `{ "found": false, "availableKeys": [...] }` rather than an empty value, so a typo is diagnosable instead of looking like an empty store.
 
 <Warning>
-  `reticle_state` asks the page and waits. On a backgrounded tab the page may never answer, and you
+  `reticle_look { action: "state" }` asks the page and waits. On a backgrounded tab the page may never answer, and you
   get `"command 'state_read' timed out after 8000ms"` with a recovery note pointing at
-  [`reticle_sessions`](/tools/sessions). That is a fact about the tab, not a Reticle failure. Bring
+  [`reticle_session { action: "list" }`](/tools/sessions). That is a fact about the tab, not a Reticle failure. Bring
   it to the front, or drive your own browser.
 </Warning>
 
 ## You have to register stores first
 
-`reticle_state` reads what your app registered in `src/reticle-dev.ts`. With nothing registered, `storeNames` comes back empty and this tool has nothing to say.
+`reticle_look { action: "state" }` reads the stores your app registered, usually in `src/reticle-dev.ts`. With nothing registered, `storeNames` comes back empty and this tool has nothing to say.
 
 ```ts
-registerCapabilities({
-  stores: [{ name: 'app', store: appStore }],
-});
+import { registerStore } from '@reticlehq/browser';
+
+registerStore('app', appStore);
 ```
 
 <Warning>
-Pass the **store**, not `() => store.getState()`. The store form wires `subscribe` too, so every
+Pass the **store**, not `() => appStore.getState()`. The store form wires `subscribe` too, so every
 mutation emits a state diff. The getter form is read-only and silently produces empty diffs, which
 looks like "nothing changed" and is really "I was never watching".
 </Warning>

package/docs/tools/tools-and-run.mdx

@@ -14,23 +14,19 @@ icon: boxes-stacked
 {}
 ```
 
-Returns every tool with a one-line summary. A sample of what lives in the cold tail:
+Returns every tool with a one-line summary. A sample of what lives in the cold tail. (`reticle_verify` is advertised, so its `flows`, `change`, `crawl` and `coverage` actions need no hop.)
 
-| Tool | What it does |
-| --- | --- |
+| Tool                   | What it does                                                           |
+| ---------------------- | ---------------------------------------------------------------------- |
 | `reticle_capabilities` | The app's advertised testable surface, testids, signals, stores, flows |
-| `reticle_verify` (`flows`) | Replay every saved flow, return one consolidated suite verdict |
-| `reticle_screenshot` | Pixel screenshot of the driven page, saved as a visual baseline |
-| `reticle_visual_diff` | Perceptually diff the live page against that baseline |
-| `reticle_network_mock` | Force a 500, go offline, or delay a response |
-| `reticle_viewport` | Pin the viewport so screenshots are reproducible across machines |
-| `reticle_verify` (`crawl`) | Click every reachable control and report anomalies, with no script |
-| `reticle_clock` | Freeze time or fast-forward timers, toasts, debounces, auto-dismiss |
-| `reticle_storage` | localStorage, sessionStorage and readable cookies |
-| `reticle_verify` (`coverage`) | Which controls you have driven this session, and which you have not |
-| `reticle_verify` (`change`) | Give it the files you edited; it replays the flows that cover them |
-| `reticle_reconcile` | Compare what the API returned against what the page actually renders |
-| `reticle_scroll_to` | Find a row in a virtualised list that has not rendered yet |
+| `reticle_screenshot`   | Pixel screenshot of the driven page, saved as a visual baseline        |
+| `reticle_visual_diff`  | Perceptually diff the live page against that baseline                  |
+| `reticle_network_mock` | Force a 500, go offline, or delay a response                           |
+| `reticle_viewport`     | Pin the viewport so screenshots are reproducible across machines       |
+| `reticle_clock`        | Freeze time or fast-forward timers, toasts, debounces, auto-dismiss    |
+| `reticle_storage`      | localStorage, sessionStorage and readable cookies                      |
+| `reticle_reconcile`    | Compare what the API returned against what the page actually renders   |
+| `reticle_scroll_to`    | Find a row in a virtualised list that has not rendered yet             |
 
 The response also tells you which surface is active:
 
@@ -41,11 +37,11 @@ The response also tells you which surface is active:
     "source": "RETICLE_ADVERTISE_ALL_TOOLS set in the DAEMON's environment at startup",
     "note": "The surface is read once at daemon startup: set RETICLE_ADVERTISE_ALL_TOOLS=1 and restart the daemon, or it has no effect. No surface advertises every tool: the advertised count is capped because editors budget tools across all connected MCP servers. Every tool listed here is callable through reticle_run { tool, args } whether or not it is advertised."
   },
-  "next": "Load params with reticle_tools { names:[…] }, then call reticle_run { tool, args }."
+  "next": "All <N> tools above are callable, advertised or not. Load full params with reticle_tools { names:[…] }, then call reticle_run { tool, args }. `retired` maps names that are no longer tools to the call that replaced each."
 }
 ```
 
-That capture is from a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1`. On a default daemon, `active` reads `default` and names the environment variable as unset.
+That capture is from a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1`. On a default daemon, `active` reads `merged`, the ten-tool default surface.
 
 <Warning>
   "Read once at daemon startup" is doing real work in that sentence. Setting the environment
@@ -69,17 +65,23 @@ Each named tool comes back with its full description and a `params` array of `{
 
 ```json
 {
-  "error": "unknown parameter for reticle_flow_save: name",
+  "error": "unknown parameter for reticle_flow_save: title",
   "tool": "reticle_flow_save",
   "params": [
-    { "name": "flow", "required": false, "description": "Alias for `flowName`." },
-    { "name": "flowName", "required": true, "description": "Name for the flow file." }
+    {
+      "name": "flow",
+      "required": false,
+      "description": "Alias for `flowName` (the name reticle_annotate uses)."
+    },
+    { "name": "name", "required": false, "description": "Alias for `flowName`." },
+    { "name": "flowName", "required": false, "description": "Which RECORDING to save …" },
+    { "name": "saveAs", "required": false, "description": "…" }
   ],
   "hint": "fix the arguments and call reticle_run again"
 }
 ```
 
-The full `error` string continues: _"NOT applied, so any result would be an answer to a different question."_
+The full `error` string continues: _"NOT applied, so any result would be an answer to a different question."_ The params list is trimmed here. When the tool has an example call, the refusal carries it as `example` too.
 
 </Warning>
 
@@ -127,11 +129,11 @@ Real response from an instrumented app, trimmed:
 }
 ```
 
-The full response on this fixture carries 49 testids and 16 signals. `source: "live"` means it was read from the running app; pass `{ "fromDisk": true }` to read the git-checked `.reticle/contract.json` instead, which works with no browser attached at all.
+`source: "live"` means it was read from the running app; pass `{ "fromDisk": true }` to read the git-checked `.reticle/contract.json` instead, which works with no browser attached at all.
 
-## Start here, not with a snapshot
+## Then this, not a snapshot
 
-That `reticle_capabilities` output is the single best first call on an unfamiliar app. It is the app telling you what it considers testable: the elements worth driving, the signals that mean success, and the flows somebody already thought were important.
+Your first move is always `reticle_session { action: "list" }`, to find the connected tab. After that, the `reticle_capabilities` output is the best next call on an unfamiliar app. It is the app telling you what it considers testable: the elements worth driving, the signals that mean success, and the flows somebody already thought were important.
 
 Compared with snapshotting the page and guessing from element names, it is both cheaper and more truthful. `auth:granted` is what the app means by "logged in", and no amount of looking at the DOM will tell you that.
 

package/docs/tools/verify.mdx

@@ -0,0 +1,28 @@
+---
+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.
+icon: shield-check
+---
+
+`reticle_verify` answers "is this proved?" in one call. It has no default `action`: every call names one, because some actions really click.
+
+```json
+{ "action": "change", "files": ["src/App.tsx"] }
+```
+
+| `action` | What it does | Verdict? |
+| --- | --- | --- |
+| `change` | Replays the saved flows that cover the `files` you edited (or the files changed `since` a git ref). One `verified` plus `because`. `unknown` when no saved flow covers the change: nothing ran, so nothing was proved | yes |
+| `flows` | Replays every saved flow, with no model in the loop, for one suite verdict. `names` or `labels` narrow it | yes |
+| `affected` | Names the saved flows that must re-verify for `files` or `since`, without running them | no |
+| `coverage` | Lists the controls you have and have not driven this session | no |
+| `crawl` | Drives every reachable control itself and reports faults and contradictions. **Destructive:** it really clicks | no |
+| `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 10 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 |
+
+Only `verified: "yes"` is a pass. `unknown` means Reticle could not tell, and `no-fault` means nothing was declared to prove.
+
+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/tools/wait-for.mdx

@@ -11,7 +11,7 @@ icon: hourglass
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
 </Warning>
 
-`reticle_wait_for` blocks until a predicate holds, or returns straight away if it is already satisfied in the recent event buffer. Reach for it when you are waiting on something you did not cause. It reads and waits; it does not produce a verdict, so finish with [`reticle_assert`](/tools/assert).
+`reticle_wait_for` blocks until a predicate holds, or returns straight away if it is already satisfied in the recent event buffer. Reach for it when you are waiting on something you did not cause. It returns `verified` and `because`, graded the way [`reticle_assert`](/tools/assert) grades them, but the wait is not journaled: it settles the page, and the proof you keep is the assert.
 
 It takes the same predicate grammar as [`reticle_act_and_wait`](/tools/act-and-wait), without the action. Use it when the thing you are waiting for was triggered by something other than your own click. A timer, a websocket push, a background refresh.
 
@@ -24,10 +24,11 @@ It takes the same predicate grammar as [`reticle_act_and_wait`](/tools/act-and-w
 }
 ```
 
-Real response:
+Real response (abridged):
 
 ```json
 {
+  "verified": "yes",
   "pass": true,
   "evidence": [
     {
@@ -61,13 +62,16 @@ The field is `contains`. `value` and `text` are accepted as aliases and rewritte
 | Argument                 | What it does                                                      |
 | ------------------------ | ----------------------------------------------------------------- |
 | `predicate` (or `until`) | `{ kind, ...fields }`, see the [predicate reference](/predicates) |
-| `timeout_ms`             | Maximum wait. Default 4000                                        |
+| `timeout_ms`             | Maximum wait. Default 4000, up to 600000                          |
 | `since`                  | Cursor from a prior act, to widen or narrow the window explicitly |
 
-By default the wait only counts events since your last act, so a signal that fired before the action cannot satisfy it. A miss returns a near-miss diagnosis rather than a bare `false`:
+One call blocks for at most 55 seconds, because an MCP client aborts a longer request. Past that it returns `resume_ms`: call again with `timeout_ms: resume_ms` and the same `since` to keep waiting.
+
+By default the wait only counts events since your last act, so a signal that fired before the action cannot satisfy it. A miss returns a near-miss diagnosis rather than a bare `false` (abridged):
 
 ```json
 {
+  "verified": "no",
   "pass": false,
   "failureReason": "no element matched {\"text\":\"Deployments\"}",
   "observed": "no matching element on the page",

package/docs/troubleshooting.mdx

@@ -106,9 +106,9 @@ Your app dials a port; the daemon listens on one. When they disagree, the app ru
 failed. That is everything the page can see: from inside the browser it cannot tell a daemon that
 is not there from one it is not allowed to reach, so this is not evidence about the daemon. What
 answers it: run `npx @reticlehq/server status` to see whether one is listening and on which port.
-If your app runs in a container, devcontainer or WSL, the daemon is on a different host, so set
-the URL explicitly (Vite: VITE_RETICLE_WS_URL, or reticle.connect({ url })). An https page cannot
-open a ws:// socket at all. Still retrying…
+If your app runs in a container, devcontainer or WSL, the daemon is on a different host, so point
+the page at it explicitly (Vite plugin: RETICLE_PORT or reticle({ port }); by hand:
+reticle.connect({ url })). An https page cannot open a ws:// socket at all. Still retrying…
 ```
 
 **You should not have to read this page to find that out.** If the agent opened the app with `reticle_lease`, which is the path `init` steers it to, the daemon reads that address off the page's own console, compares it with the port it is bound to, and puts the mismatch in the tool result:
@@ -123,9 +123,11 @@ Neither side can work that out alone: the page cannot see the daemon, and the da
 That message names the exact address it tried. Compare its port with `bridge port` from `doctor` and set whichever is wrong:
 
 ```bash
-VITE_RETICLE_WS_URL=ws://localhost:4400/reticle pnpm dev
+RETICLE_PORT=4400 pnpm dev
 ```
 
+That works with the Vite plugin, which reads `RETICLE_PORT` when the dev server starts. You can also set `reticle({ port: 4400 })` in `vite.config`, or pass `reticle.connect({ url: 'ws://localhost:4400/reticle' })` if you wired `connect()` by hand.
+
 <Warning>
   The bridge port is **not** your dev-server port. A dev server on 4312 and a daemon on 4400 is
   normal and correct.
@@ -201,7 +203,7 @@ Before concluding "no request fired", read the buffer note:
 
 ## The agent cannot find an element
 
-- `reticle_look { action: "page" } { mode: "interactive" }` shows everything actionable.
+- `reticle_look { action: "page", mode: "interactive" }` shows everything actionable.
 - Add a `data-testid` for a stable handle.
 - Narrow with `scope`. A CSS selector or a ref.
 
@@ -223,6 +225,19 @@ empty `stateDiffs`. Which reads as "nothing changed" and means "I was never watc
 
 React 19 dropped `_debugSource`. Wire up `@reticlehq/babel-plugin`. Or just use `@reticlehq/vite-plugin` or `@reticlehq/next`, which both include it. Without it you get component identity but no `file:line`.
 
+## A lease on an https dev server with a local certificate
+
+A dev server on `https://` with a self-signed or mkcert certificate makes `reticle_lease { "action": "acquire" }` fail with `net::ERR_CERT_AUTHORITY_INVALID`: the browser does not trust a certificate that no CA vouches for. The result says so and names the fix. If the server is yours, acquire again with `ignoreHTTPSErrors` set:
+
+```json
+{
+  "tool": "reticle_lease",
+  "args": { "action": "acquire", "url": "https://localhost:5173/", "ignoreHTTPSErrors": true }
+}
+```
+
+It is off by default. When it is on, certificate checks are skipped for every site opened in that lease's browser context, including resources loaded from other sites. Other leases keep their checks. A context cannot change the setting once it is made, so acquiring again with the other value replaces the lease instead of reusing it.
+
 ## `ERESOLVE` installing next to a prerelease
 
 `@reticlehq/next` declares `peer next >=13` and `@reticlehq/react` declares `peer react >=18`. On a Next canary or React RC, npm refuses. See [the prerelease notes](/getting-started#installing-alongside-a-nextjs-or-react-prerelease).
@@ -254,7 +269,7 @@ Stale sessions pointing at dev servers you restarted an hour ago look completely
 { "action": "end" }
 ```
 
-`reticle_session { action: "end" }` when you are done, `{ action: "yield" }` when pausing. Both revive on your next action.
+`reticle_session { action: "end" }` when the whole task is done, `{ action: "yield" }` when pausing. A yielded session revives on your next action; an ended one stays ended.
 
 ## Frequently asked questions