@reticlehq/server 3.7.0 → 3.8.1

package/docs/tools/network.mdx

@@ -16,10 +16,10 @@ icon: satellite-dish
 ## Example
 
 ```json
-{ "limit": 3 }
+{ "limit": 3, "bodies": true }
 ```
 
-Real response, with the second call's `headers` block trimmed off:
+Real response with `bodies: true`, with the second call's `headers` block trimmed off:
 
 ```json
 {
@@ -76,15 +76,17 @@ Most tools would return an empty array and let you draw the wrong conclusion. Th
 
 ## Filters
 
-| Argument          | What it does                                                           |
-| ----------------- | ---------------------------------------------------------------------- |
-| `urlContains`     | Substring the URL must contain                                         |
-| `method`          | `GET` · `POST` · `PUT` · `DELETE` · `PATCH`                            |
-| `status`          | Exact status code, e.g. `500`                                          |
-| `ok`              | `false` keeps only failures. The fastest way to "did anything break?"  |
-| `limit`           | Most recent N. Older matches are dropped and counted                   |
-| `actionId`        | Only requests attributed to one action: "what did that click request?" |
-| `since` / `until` | Cursors from a prior act, to scope to a window between two actions     |
+| Argument | What it does |
+| --- | --- |
+| `urlContains` | Substring the URL must contain |
+| `method` | `GET` · `POST` · `PUT` · `DELETE` · `PATCH` |
+| `status` | Exact status code, e.g. `500` |
+| `ok` | `false` keeps only failures. The fastest way to "did anything break?" |
+| `limit` | Most recent N. Older matches are dropped and counted |
+| `actionId` | Only requests attributed to one action: "what did that click request?" |
+| `since` / `until` | Cursors from a prior act, to scope to a window between two actions |
+| `bodies` | Omitted: keep a body only where it can decide a verdict (failures, unscored calls, calls your filter named), and report the rest in `bodiesWithheld`. `true`: every captured body. `false`: no bodies |
+| `assets` | `true` lists the dev server's own successful asset requests. Omitted: they are folded into `assetsFolded` |
 
 ## Catching a double submit
 

package/docs/tools/overview.mdx

@@ -9,7 +9,7 @@ Your agent is shown **ten** tools by default: `reticle_navigate`, `reticle_look`
 
 Most of the rest were not removed. They were **merged**. `reticle_snapshot` is `reticle_look { action: "page" }`; `reticle_console` is `reticle_observe { action: "console" }`. One tool, one action argument, same work. Calling a retired name returns the call that replaced it, and `reticle_tools` prints the whole mapping.
 
-That is not a limitation, it's the design. MCP re-sends every advertised tool definition to the model on **every single turn**, so the tool list is not a menu you pay for once. It's rent.
+That is not a limitation. It is the design. MCP re-sends every advertised tool definition to the model on **every single turn**, so the tool list is not a menu you pay for once. It's rent.
 
 A wider surface costs tokens on every message. Less obviously, it makes the model wander: give it fifty ways to look at a page and it will try several before doing anything useful.
 
@@ -82,7 +82,7 @@ Those repeats were not retries. The calls succeeded and got repeated, because th
 
 `reticle_run` takes a tool name and its arguments. `reticle_tools` lists what's available and returns the full argument grammar for any of them, so your agent can discover a tool mid-task without you having pre-loaded its schema.
 
-Notable residents of the cold tail: flow recording and replay, visual diffing and screenshots, network mocking, viewport pinning, coverage, autonomous crawling, and the human-in-the-loop session controls.
+Notable residents of the cold tail: flow recording and replay, visual diffing and screenshots, network mocking, viewport pinning, the clock, storage, and the App Graph map (`reticle_map`).
 
 ## Read responses carry their cost
 
@@ -156,7 +156,7 @@ These pages are named for the unmerged tools. Each one gives the default spellin
 | [`reticle_assert`](/tools/assert) | Did the named consequence hold? **Produces a verdict** |
 | [`reticle_tools`](/tools/tools-and-run) | What else is available, and what are its arguments? |
 | [`reticle_run`](/tools/tools-and-run) | Invoke any other registered tool by name |
-| [`reticle_session`](/tools/session-and-feedback) | Hand control back to the human |
+| [`reticle_session`](/tools/session-and-feedback) | List connected tabs (the default), hand control back with `yield`, tune the HUD, read the account |
 | [`reticle_session { action: "feedback" }`](/tools/session-and-feedback) | Tell the maintainers Reticle got something wrong (`reticle_feedback` is its unmerged name, not advertised by default) |
 
 <Card title="The complete reference" icon="book" href="/usage">

package/docs/tools/query.mdx

@@ -11,7 +11,7 @@ icon: magnifying-glass
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
 </Warning>
 
-`reticle_look { action: "find" }` answers "where is the thing I mean?" without dumping the whole page into your context window. It queries the way a testing library does. By role, label, text, testid. So your agent binds to meaning rather than to DOM structure that a refactor will move.
+`reticle_look { action: "find" }` answers "where is the thing I mean?" without dumping the whole page into your context window. It queries the way a testing library does: by role, label, text or testid. Your agent then binds to meaning, not to DOM structure that a refactor will move.
 
 ## Example
 
@@ -48,7 +48,7 @@ Real response from a running app, with four of the six elements trimmed out for
 }
 ```
 
-Seven buttons, each with a `ref` to act on and a source file to open, for 236 tokens.
+Seven buttons matched and six came back, because `limit` is 6. Each one has a `ref` to act on and a source file to open, for 236 tokens.
 
 ## Arguments
 
@@ -121,7 +121,7 @@ The testid existed, on another route. `hint.route` says where you actually are,
 
 `ref` is the handle for every other call: `reticle_act`, `reticle_look { action: "element" }`, `reticle_look { action: "state" }`. It stays valid until the element leaves the DOM, so you do not need to re-snapshot between actions on the same element.
 
-`source` appears when the app is built in dev with the Reticle build plugin; production builds omit it. Note that both sidebar buttons above report `Sidebar.tsx:41`, and so do the three trimmed out of the example. That is the line where the component renders all five in a loop, which is exactly the line you want to edit.
+`source` appears when the app is built in development with the Reticle build plugin. Production builds omit it. Both sidebar buttons above report `Sidebar.tsx:41`. That is the line where the component renders its nav buttons in a loop, which is the line you want to edit.
 
 `truncated: true` with `total: 7` means `limit` cut the list, not that Reticle ran out of room. Neither field is emitted when nothing was cut, so their absence is itself the signal that you are looking at every match.
 

package/docs/tools/session-and-feedback.mdx

@@ -13,9 +13,9 @@ The presenter panel in your app shows a live transcript of what the agent is doi
 | Action | What it does |
 | --- | --- |
 | `list` | Which tabs are connected, and whether they can be driven. Your first call. An empty list carries a `why` naming the cause |
-| `feedback` | Tell the maintainers Reticle got something wrong. Takes the fields described under [reticle_feedback](#reticle-feedback) below |
+| `feedback` | Tell the maintainers Reticle got something wrong. Takes the fields described under [Feedback](#feedback) below |
 | `yield` | Hand control back between turns. `mode: "waiting"` or `"ask"`. Revivable |
-| `end` | The task is done. Frees the session; revives on the next action |
+| `end` | The whole task is done. Ends the session for good, and it does not revive. Ending a leased tab also releases the lease |
 | `tune` | Adjust session behaviour: `idleEndMs`, the idle-end window, or `hud`: `hidden`, `shown`, `removed` (until reload), or a corner (`top-left`, `top-right`, `bottom-left`, `bottom-right`) when the HUD covers a control you must test |
 | `resume` | Clear a pause the human applied |
 | `messages` | Drain the human-to-agent inbox |
@@ -48,12 +48,11 @@ And each lease carries the rule in the payload itself:
 ```
 
 <Tip>
-  `yield` when you are pausing and might come back. `end` when you are finished. Both revive on your
-  next action, so neither is destructive. The difference is what the human watching the panel is
-  told.
+  Use `yield` when you pause and might come back: your next action revives the session. Use `end`
+  only when the whole task is done: it is final, and the panel shows the session as ended.
 </Tip>
 
-## reticle_feedback
+## Feedback
 
 <Note>
   `reticle_feedback` is not advertised by default. Call `reticle_session { action: "feedback", kind, text }`: the same fields, routed on `action`. The old name answers with the new call.
@@ -83,6 +82,8 @@ Reticle is built for agents, which creates an unusual problem: the primary user'
 
 The `rating` is secondary to that text on purpose. A score produced because something asked for one is indistinguishable from a score that was earned, and once both sit in the same column neither means anything. The text is the part that can be acted on or quoted.
 
+`contact` is an email address for a reply from the maintainers. Send only an address that the user typed for this purpose. Never guess one or reuse one from somewhere else. It must be one plain address of at most 254 characters. Anything else is refused with a reason, and nothing is filed. Without `contact`, no address is sent.
+
 ### It will tell you when it cannot send
 
 Feedback sends in the background so you are not kept waiting, but it does not pretend to succeed: `sent` stays `false` until delivery is confirmed, `accepted` says the report was validated and queued, and a send that later fails is reported on a later tool result. A report that is not accepted says why:
@@ -119,6 +120,8 @@ The setup that failed to finish is exactly the setup that most needs reporting,
 npx @reticlehq/server feedback --agent --kind gap "reticle init finished but no session ever connected"
 ```
 
+To get a reply, add `--contact you@example.com`. Use only an address that the user typed for this purpose. Without the flag, no address is sent.
+
 <Note>
   Report defects in **Reticle**. A bug you find in the app under test is Reticle working correctly,
   and belongs in your answer to the user. Not in a bug report to us. We get a surprising number of

package/docs/tools/sessions.mdx

@@ -27,6 +27,7 @@ Real response from a healthy session:
       "url": "http://localhost:4310/",
       "title": "Reticle · Mission Control",
       "adapters": ["react"],
+      "sdkVersion": "3.8.0",
       "hasCapabilities": true,
       "hidden": false,
       "lastSeenMs": 155,
@@ -68,6 +69,8 @@ An empty list is not silent. It comes back with a `why` that separates the two c
 
 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 empty list also carries `next_action`, the same answer as a command to run. In a project that was never wired, it carries `next_step` too. Nothing was installed and no file changed. `lease` is the call that checks the running app now with nothing installed: do it first. `consent` is the question to ask before `reticle init` wires the app. Run `init` only when the user agrees.
+
 ## The fields that decide whether driving will work
 
 | Field | Why it matters |
@@ -78,6 +81,10 @@ That string is trimmed. The full text also lists the exact ports it scanned, say
 | `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 |
+| `sdkVersion` | The page's SDK version |
+| `sdkBehind` | Present when the page SDK is a minor release or more behind the daemon. Newer commands and fixes are missing. It says how to update |
+| `versionSkew` | Present when the page SDK and the daemon differ. Fix it before you trust a verdict |
+| `instrumentation` | `injected` when a hosted verifier put the SDK into the page from outside. Absent means the app installed it |
 
 <Warning>
   A hidden tab (`hidden: true`, which also sets `throttled`) is the most common cause of "the click

package/docs/tools/snapshot.mdx

@@ -21,7 +21,7 @@ icon: camera
 | `interactive` | Only clickable and focusable elements | **65 tokens**         |
 | `full`        | Every element                         | Depends on the page   |
 
-### `status`. the cheapest possible check
+### `status`: the cheapest check
 
 ```json
 { "mode": "status" }
@@ -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 usual working view
+### `interactive`: the usual working view
 
 ```json
 { "mode": "interactive" }
@@ -59,11 +59,13 @@ Everything you can act on, with a `ref` for each, for 65 tokens. Note the passwo
 
 ## Arguments
 
-| Argument | What it does                                                                 |
-| -------- | ---------------------------------------------------------------------------- |
-| `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 |
+| Argument | What it does |
+| --- | --- |
+| `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 |
+| `ids` | Add `[testid=…]` to each control that has one. Off by default, because it costs tokens |
+| `audit` | Also measure what a person would see as broken: text cut off with no ellipsis, controls drawn over each other, text below WCAG contrast. Returns `audit: [{ kind, ref, what, detail }]`. Off by default, because it forces layout |
 
 ## `diff` is how you keep a long session cheap
 

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

@@ -16,17 +16,18 @@ icon: boxes-stacked
 
 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_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             |
+| `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 |
+| `reticle_map` | The app as Reticle has seen it: screens, how much of each is proved, where to test next, and, with `to`, the controls to press to reach a route |
 
 The response also tells you which surface is active:
 

package/docs/tools/verify.mdx

@@ -17,7 +17,7 @@ icon: shield-check
 | `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 |
+| `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 |
 

package/docs/troubleshooting.mdx

@@ -20,10 +20,12 @@ npx @reticlehq/server doctor
 ```
 reticle doctor
   node         v22.14.0
-  chromium     ✓ installed
+  chromium     ✓ installed (chromium-1234)
   daemon       ✓ running on :4400 (pid 24735, v<the version you have>)
   sessions     ✓ 1 page connected
   bridge port  4400  (your app must dial THIS port, not your dev-server port)
+  agent link   ✓ an MCP client attached here and called tools before (a record, not a live check)
+  project      ✓ wired here (my-app)
   daemon log   /Users/you/.reticle/daemon-4400.log
   tracing      RETICLE_TRACE=1 on the daemon for per-stage timings in that log
 ```
@@ -57,7 +59,7 @@ If nothing ever connected:
 
 The daemon still does not do it, on purpose. A build process started by a long-lived background daemon is invisible to whoever's machine it is running on, was never consented to, cannot easily be stopped, and orphans when the daemon exits. It would also mean a piece of standing infrastructure runs arbitrary `package.json` scripts. An agent already has shell access in your repo, already runs install and build commands, and runs inside a host that asks you before it does. A dev server the agent starts is in the transcript, attributable to a step you approved, and stoppable.
 
-The agent does not have to work out the command. When `reticle_session { action: "list" }` comes back with nothing connected, it carries a `next_action` naming which of four cases this is and, where one applies, the literal command and port: start the dev server, run `reticle init`, open the app, or reopen a tab that went away. The command is read from this project's own scripts, so a project with no recognisable dev script gets no command rather than a guess.
+The agent does not have to work out the command. When `reticle_session { action: "list" }` comes back with nothing connected, it carries a `next_action`. Its `action` names the case: `daemon_split` (the app is on a different daemon; start nothing), `start_dev_server`, `run_init`, `open_app` or `reopen_app`. Where one applies, it also gives the literal command and the port. In a project that was never wired, it also carries `next_step`. Its `lease` checks the running app now with nothing installed. Its `consent` is the question to ask before `reticle init` changes files. Run `init` only when the user agrees. The command is read from this project's own scripts, so a project with no recognisable dev script gets no command rather than a guess.
 
 The guards, which apply wherever this instruction appears:
 
@@ -107,8 +109,8 @@ failed. That is everything the page can see: from inside the browser it cannot t
 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 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…
+the page at it: RETICLE_PORT or reticle({ port }) with the Vite plugin, reticle.connect({ url })
+by hand. An https page cannot open a ws:// socket. 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:
@@ -210,7 +212,7 @@ Before concluding "no request fired", read the buffer note:
 ## Assertions are flaky on async UIs
 
 - Use `timeout_ms` on `assert` and `wait_for`.
-- Pass the `since` cursor from `reticle_act` so only post-action events count. Without it, an assertion can pass on an event from two clicks ago.
+- By default an assertion counts only the events after your last act. Pass a `since` cursor from `reticle_act` or `reticle_observe` to set that window yourself.
 
 ## `reticle_look { action: "state" }` returns nothing
 
@@ -238,9 +240,19 @@ A dev server on `https://` with a self-signed or mkcert certificate makes `retic
 
 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.
 
+## The page never connects under a strict CSP
+
+A build that sends a strict Content-Security-Policy blocks the bridge socket. A production build that you run locally (`next start`, `vite preview`) often sends one. The app runs, and the SDK never connects, with no error in the app. Add the bridge to `connect-src`, with your bridge port if it is not `4400`:
+
+```text
+connect-src 'self' ws://localhost:4400 ws://127.0.0.1:4400
+```
+
+Add it only in the builds that Reticle drives, never in the policy that you deploy. If the policy also blocks inline scripts, `script-src` stops a pasted connect snippet before it runs: serve that snippet as an external module. `reticle doctor` reads the policy that the page serves and names the line to add, and a lease result says the same. For [production mode](/production-mode), add the `wss://` bridge from the ticket instead. Desktop apps have their own note in [Desktop](/desktop).
+
 ## `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).
+`@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-next-js-or-react-prerelease).
 
 ## The tool list is empty
 
@@ -251,8 +263,8 @@ Some clients read their MCP tool list once, at startup, and never again. Cursor
 ## Restarting things
 
 ```bash
-npx @reticlehq/server stop     # clean daemon shutdown, no pkill needed
-npx @reticlehq/server status   # confirm it came back
+npx @reticlehq/server restart  # clean stop, then start and wait until it listens
+npx @reticlehq/server status   # confirm it is back
 ```
 
 <Warning>
@@ -274,7 +286,7 @@ Stale sessions pointing at dev servers you restarted an hour ago look completely
 ## Frequently asked questions
 
 <AccordionGroup>
-  <Accordion title="Why does reticle_session { action: "list" } return nothing when my app is clearly running?">
+  <Accordion title='Why does reticle_session { action: "list" } return nothing when my app is clearly running?'>
     Your app running is not the same as your app being connected. The SDK has to dial the daemon's
     bridge port over a WebSocket. If `npx @reticlehq/server doctor` shows the daemon up and
     `sessions` at zero, either `reticle.connect()` never executed (check the dev guard is actually