@reticlehq/server 3.4.0 → 3.6.0

package/docs/getting-started.md

@@ -4,7 +4,7 @@ description: 'Zero to your agent verifying your real app, step by step, with wor
 icon: rocket
 ---
 
-**To get started with Reticle: run the installer, open your coding agent, then run `npx @reticlehq/server init` in your project root.** Getting started is three stages. **Installation** is one command in a terminal, `curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh` (or `irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex` on Windows): it puts the CLI on the machine and registers the MCP server with every agent it can reach, so the tools are there the next time you open your agent. **Onboarding** is `init`: it wires your project, starts your dev server, opens the app and waits for it to connect. **The first run** is what proves anything: `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`, or from a terminal `npx @reticlehq/server verify <url> --explore --persona "<the journey worth proving>"`. A connected app is not a verified one. Reticle is a verification layer that embeds a dev-only SDK in your running web app so an AI coding agent can prove a change works instead of guessing. It needs Node 20 or newer, an app you run locally, and an agent that speaks MCP.
+**To get started: run the installer, then `reticle init` in your app directory before opening your coding agent.** The installer puts the CLI on the machine and registers its MCP tools with supported agents. `init` wires your app and checks that a browser session connected; without it the agent has the tools and nothing to point them at. For a cloud dashboard, use `reticle connect --project "My App"`, which does the same and also links a cloud project and syncs history. The first run is what proves anything: ask your agent to verify one journey in your app, or use `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`. A connected app is not a verified one. You need Node 20.11 or newer, an app you run locally, and an agent that speaks MCP.
 
 > **Looking for the fast path?** [Quickstart](/quickstart) gets you to a real verdict in five minutes, and every response on it was captured live. [Agentic install](/install-agentic) and [Manual install](/install-manual) cover setup in detail, per agent and per framework.
 >
@@ -58,7 +58,9 @@ Everything is **dev-only** and **localhost-only**. It's tree-shaken out of produ
 
 ---
 
-## Fastest path: `reticle init`
+## Wire your app: on the first run, or `reticle init`
+
+Installing Reticle changes nothing in your project. The first time your agent uses Reticle in a project that has never connected (its first `reticle_session { action: "list" }`), Reticle runs `init` there itself and returns the files it changed under `wired`, so you can skip straight to asking your agent to verify a flow. Run `init` yourself to wire a project ahead of time, to preview the changes, or when the agent's MCP server was started outside the project (the call then answers `run_init` with this same command).
 
 From your project root:
 
@@ -94,6 +96,16 @@ If you ran `--files-only` with a dev server already running, restart it, then sk
 
 ---
 
+## Add a cloud dashboard: `reticle connect`
+
+Optional. Instead of, or after, `init`, run this in your app directory:
+
+```bash
+npx @reticlehq/server connect --project "My App"
+```
+
+Approve the short browser code if Reticle asks you to sign in. The command then links this folder and sends any history already on the machine. Open or restart your coding agent and ask it to verify one real journey. For a new project, the dashboard has no result until that first run is recorded.
+
 ## Step 1: Connect your coding agent (MCP), once
 
 You don't start the server manually; your agent starts it via MCP. Register Reticle **once, at the user (global) scope** so every project picks it up. There's nothing to add per project.

package/docs/human-control.md

@@ -25,10 +25,9 @@ MCP is **pull-based**: the agent only receives data when it calls a tool. Reticl
 The floating panel (bottom-center, `present: true`) gives you:
 
 - **Pause / Resume**: one toggle. Paused turns the panel + page border **amber** with a `PAUSED` badge.
-- **Message box + send.** Type a correction ("check the error state first"), hit Send (or Enter). Your message shows as a `🧑 you:` bubble in the transcript **and** is delivered to the agent.
 - **End** ends the session: panel turns **emerald**, shows `Session ended · <summary>`, then fades away.
 - **Minimise (▾)** collapses the panel to a bar that streams only the live line; click the bar to restore.
-- **Flag a bug**, the button in the corner. Toggle it on, click the element that looks wrong, type what's wrong (⌘/Ctrl+Enter to send, Esc to back out). Reticle pins a numbered marker, logs your flag in the panel, and hands the agent a structured mark.
+- **Flag a bug**, the button in the corner. Toggle it on, click the element that looks wrong, type what's wrong (⌘/Ctrl+Enter to send, Esc to back out). Reticle pins a numbered marker, logs your flag in the panel, and hands the agent a structured mark. Notes are kept in `.reticle/notes.json` (pending and resolved), so a reload or a daemon restart does not lose them, and a linked project syncs them to the dashboard.
 
 ## Flag a bug: annotate the mistake where you see it
 

package/docs/index.mdx

@@ -28,7 +28,7 @@ irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1
 
 </CodeGroup>
 
-That registers the MCP server with every coding agent it can reach, so the `reticle_*` tools are there the next time you open one. Then, in your project, `npx @reticlehq/server init` wires the app. The [quickstart](/quickstart) walks both.
+That registers the MCP server with every coding agent it can reach, so the `reticle_*` tools are there the next time you open one. Then ask your agent to verify something in your app: its first Reticle call wires the app and lists the files it changed (`npx @reticlehq/server init` does the same by hand). The [quickstart](/quickstart) walks both.
 
 ### Or hand the whole thing to your agent
 
@@ -54,8 +54,9 @@ That one command wires the project, starts the dev server, opens the app and
 waits for it to connect. Do not walk it by hand: read what it prints, do anything
 it says is outstanding, and re-run it, which is safe. It exits non-zero until the
 app connects, and that connection, not a config file, is what "installed" means.
-Then prove a flow, which is a separate call:
-reticle_verify { action: "explore", persona: "<who does what>" }. Only if it could not run at all, follow
+Then prove a flow, which is a separate call: drive the journey with
+reticle_act_and_wait and an `until` on its last step (or, with a linked project,
+reticle_verify { action: "explore", persona: "<who does what>" }). Only if it could not run at all, follow
 https://docs.reticle.sh/install-manual.md.
 
 Afterwards, use it whenever you change any user-facing behaviour.

package/docs/install-agentic.mdx

@@ -248,7 +248,7 @@ Three of these are answers only the caller has. `init` reads your repository; it
 | `--env KEY=VALUE` | What the app needs to reach a usable state: the key from `.env.example`, the mock backend, the variable that skips an auth wall. Repeatable, and a value may contain spaces and equals signs. Without it a real app sits on a login screen and there is no flow to drive. |
 | `--app <dir>` | Monorepos. `init` can find the apps that are servable; only your request says which one you are working in. |
 | `--license <key>` | Writes `RETICLE_LICENSE_KEY` to `.env` and keeps `.env` out of git. Do not do those two by hand. |
-| `--json` | One object on stdout: what was wired, what connected, the verdict, and an `agentTodo` array. For agents. |
+| `--json` | One result object on stdout; progress and package-manager output go to stderr. Default init reports runtime setup and connection. `--files-only` and `--dry-run` report the wiring result. Init does not drive a flow or produce a verification verdict. |
 | `--files-only` | Write the files, register the MCP server with every agent on the machine, pre-approve Reticle's tools, and stop: no dev server, no drive. What `init` did before it learned to boot the app, and the upgrade path for a machine that installed Reticle on an earlier version. |
 | `--no-open` | Do not open a browser: CI, a container, an SSH session, or a tab you already have. |
 | `--dry-run` | See the plan before anything is written. |

package/docs/install-manual.mdx

@@ -7,7 +7,7 @@ icon: screwdriver-wrench
 
 **Installing Reticle by hand is two independent halves: register the MCP server so your agent gets the `reticle_*` tools, then add the SDK to your app so there is something for those tools to talk to.** You need both, in that order.
 
-Do only the first half and the tools appear but every call reports no session. Do only the second and your app connects to a daemon nobody is asking questions.
+Do only the first half and the tools appear but every call reports no session. Do only the second and your app connects to a daemon nobody is asking questions. Stop after the first half and your agent's first Reticle call wires the app itself when you ask it to verify something, and offers to otherwise.
 
 <Warning>
   **You probably do not need this page.** Two commands do all of it:
@@ -175,7 +175,7 @@ Screenshots and headless mode need the Rust crate, which is versioned independen
 
 ```toml
 [dependencies]
-reticle-tauri = "3.4"
+reticle-tauri = "3.6"
 ```
 
 ```rust

package/docs/packages/next.mdx

@@ -44,10 +44,13 @@ Returns the config unchanged when `NODE_ENV === 'production'`. Otherwise it merg
 | --- | --- |
 | `webpack` | Pushes an `enforce: 'pre'` rule for `/\.(t\|j)sx$/`, excluding `node_modules`, using this package's loader. Your own `webpack` function still runs afterwards |
 | `turbopack` | On Next 15.3 and above only: rules for `*.tsx` and `*.jsx` pointing at `@reticlehq/next/loader` |
+| `env.NEXT_PUBLIC_RETICLE_URL` | The bridge URL: a valid `RETICLE_PORT` override, otherwise project daemon discovery and `.reticle.json` |
 | `env.NEXT_PUBLIC_RETICLE_TOKEN` | The pairing token, when one exists on disk |
 | `env.NEXT_PUBLIC_RETICLE_ROOT` | `process.cwd()`, so source paths come back repository-relative |
 | `env.NEXT_PUBLIC_RETICLE_SDK_VERSION` | The version of the app's installed `@reticlehq/react` |
 
+Daemon discovery reads `RETICLE_STATE_DIR` (default `~/.reticle`). Pairing tokens use `RETICLE_PAIRING_TOKEN_DIR` independently. The generated `ReticleDev` component reads `NEXT_PUBLIC_RETICLE_URL`; restart the dev server after changing these settings.
+
 `readPairingToken()` is also exported at runtime. It is not declared in `index.d.ts`, so TypeScript will not see it.
 
 ### `./loader`

package/docs/packages/tauri.mdx

@@ -21,10 +21,10 @@ Tauri IPC observation needs nothing on the Rust side. An `invoke('load_todos')`
 
 ```toml
 [dependencies]
-reticle-tauri = "3.4"
+reticle-tauri = "3.6"
 ```
 
-Its own dependencies are `tauri = "2"` plus the per-platform capture backends: `objc2` and friends on macOS, `webview2-com` and `windows` on Windows, `webkit2gtk` and `cairo-rs` on Linux and the BSDs.
+Its own dependencies are `tauri = "2.12"` (the Windows backend must use the same `webview2-com` and `windows` versions Tauri does, so it follows Tauri's minor version) plus the per-platform capture backends: `objc2` and friends on macOS, `webview2-com` and `windows` on Windows, `webkit2gtk` and `cairo-rs` on Linux and the BSDs.
 
 ## Wiring
 

package/docs/packages/vite-plugin.mdx

@@ -31,6 +31,8 @@ export default defineConfig({
   [`@reticlehq/server`](/packages/server).
 </Warning>
 
+Set `RETICLE_PORT` in the dev server or desktop build environment to use the same custom bridge port as the CLI. A valid value overrides discovery and `.reticle.json`; invalid values are ignored.
+
 ## Why it exists
 
 `apply: 'serve'` means it never reaches a production build. That is the guarantee that lets you leave it in the config permanently: there is no way to ship Reticle to your users by forgetting to remove a line.
@@ -59,18 +61,39 @@ Plus a dynamic import of your dev module if one exists. It looks for `src/reticl
 | `session` | `string` | Omitted, so the SDK generates one |
 | `projectId` | `string` | Derived from the package name plus the root path |
 | `token` | `string` | `readPairingToken()`, from `~/.reticle/pairing-token` |
+| `present` | `boolean` | `true`. Set `false` to hide Reticle's presenter while keeping the agent connection active |
 | `sourceMapping` | `boolean` | `true`. Set `false` to skip the Babel pass |
 | `inject` | `boolean` | `true`. Set `false` to call `connect()` yourself |
 | `desktop` | `boolean` | `false`. When `true` the connect passes `allowInProduction: true`, which an Electron or Tauri renderer needs, and a `vite build` in a non-production mode (`--mode development`) is instrumented too. A production-mode build is stubbed like a web build |
 | `captureNetworkBodies` | `boolean` | `false`. Also enabled by `VITE_RETICLE_CAPTURE_BODIES=1` |
 | `onWarn` | `(message: string) => void` | `console.warn` |
 
+`reticle({ present: false })` still lets the plugin create and configure the connection; it only hides Reticle's visible presenter. `reticle({ inject: false })` disables that generated connection, so your application must call `connect()` itself. In that manual call, pass the pairing token explicitly:
+
+```ts
+reticle.connect({
+  token: __RETICLE_TOKEN__,
+  root: __RETICLE_ROOT__,
+  sdkVersion: __RETICLE_SDK_VERSION__,
+});
+```
+
+Add ambient declarations for these identifiers to `src/vite-env.d.ts` (or another included `.d.ts`) in a TypeScript app:
+
+```ts
+declare const __RETICLE_TOKEN__: string;
+declare const __RETICLE_ROOT__: string;
+declare const __RETICLE_SDK_VERSION__: string;
+```
+
+Vite replaces these `define` identifiers in application source at build time; the declarations let TypeScript typecheck them and do not create runtime globals. The SDK does not discover the pairing token, so pass it explicitly in a hand-written connection:
+
 ## Other exports
 
 | Export | Type | What it is |
 | --- | --- | --- |
 | `RETICLE_VITE_PLUGIN_NAME` | `'reticle'` | The plugin name |
-| `RETICLE_TOKEN_GLOBAL` | `'__RETICLE_TOKEN__'` | The global the token is stamped onto |
+| `RETICLE_TOKEN_GLOBAL` | `'__RETICLE_TOKEN__'` | The Vite `define` identifier replaced with the pairing token |
 | `RETICLE_CONNECT_MODULE` | `'/@reticle-connect'` | The virtual module id |
 | `RENDER_PREHOOK_SOURCE` | `string` | The inline render prehook snippet |
 | `RETICLE_DEV_MODULE_CANDIDATES` | readonly tuple | The four dev-module paths it looks for |

package/docs/packages.mdx

@@ -239,7 +239,7 @@ A lint rule makes the signal layer self-enforcing, which is the only way a conve
 
 ```toml
 [dependencies]
-reticle-tauri = "3.4"
+reticle-tauri = "3.6"
 ```
 
 <Warning>

package/docs/quickstart.mdx

@@ -5,7 +5,7 @@ description: Install Reticle, connect your coding agent, and get a real verdict
 icon: rocket
 ---
 
-**Run the installer in a terminal, open your coding agent, then run `init` in your project.** Reticle is a verification layer for AI coding agents: it embeds a dev-only SDK in your running web app so an agent can prove a change works instead of guessing.
+**Run the installer once, then ask your agent to verify something in your app; its first Reticle call wires the app (the same thing `reticle init` does, which you can also run yourself).** Reticle embeds a dev-only SDK in your running app and proves a browser session connected. No account needed. Add `reticle connect` later if you want a cloud dashboard.
 
 By the end of this page your agent will click a button in your app and prove what happened: the request that fired, the state that changed, and the file to open if it didn't.
 
@@ -53,17 +53,26 @@ npm install -g @reticlehq/server
 npx @reticlehq/server setup mcp
 ```
 
-## Step 2. Open your coding agent, and wire the project
+## Step 2. Wire this project
 
-The `reticle_*` tools are already there. In your project directory:
+In your project directory, before opening your coding agent:
 
 ```bash
-npx @reticlehq/server init
+RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server init
 ```
 
-Like `npm init` or `git init`, this is the per-project step: it installs the SDK, wires it into your app's entry point, starts your dev server and then opens your app to prove a session connected. It is idempotent. Run it twice and the second run reports what was already done rather than doing it again.
+This installs the dev-only SDK, wires your build config, starts the dev server, and checks that a browser session connected. Nothing from your project leaves your machine. Open your coding agent once this command finishes; if it was already open during installation, restart it to load the new tools. The `RETICLE_INSTALL_SOURCE` prefix is optional and only tells us which page you installed from. It is idempotent: run it twice and the second run reports what was already done rather than doing it again.
 
-Step 1 is once per machine. This step is once per project.
+Step 1 is once per machine. This step is once per project. **Skipping it is the most common reason Reticle "does nothing":** the agent has the tools, but there is no app on the other end for them to see.
+
+Want a cloud dashboard too? Run `npx @reticlehq/server connect --project "My App"` instead of, or after, `init`. It does everything `init` does, then opens browser sign-in approval, links this folder to the named cloud project, and sends existing local history. Approve the short code shown in the browser and terminal; the command resumes by itself.
+
+<Note>
+  **Skipped this step?** Ask your agent to verify something in the app. Its first `reticle_session`
+  call finds a project that has never connected, runs `init` there itself, and lists every file it
+  changed under `wired`. Asked about something unrelated, it offers to wire the app instead of doing
+  it. This works in Claude Code, Codex, Cursor and other MCP agents.
+</Note>
 
 Prefer to install the skill and let the agent run setup itself? On Claude Code the plugin registers the MCP server and the skill in one step:
 
@@ -80,7 +89,7 @@ npx skills add reticlehq/reticle
 
 Then type `/reticle` and the agent runs the install from the skill.
 
-Useful flags, from `reticle init` itself:
+Useful flags for the local-only `reticle init` path:
 
 ```
 reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
@@ -90,7 +99,7 @@ reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
               only make sense once the tools are reachable.
 ```
 
-Start with `--dry-run` if you want to see the plan before anything is written.
+Start with `reticle init --dry-run` if you want to see the app changes before anything is written.
 
 <Tip>
   In a monorepo, `init` will find several apps and ask which one you mean. `--app packages/web`
@@ -107,9 +116,9 @@ npx @reticlehq/server doctor
 
 `doctor` diagnoses the whole setup in one command: Chromium, the daemon, the port. If something is wrong this is the page you want before you start debugging your app instead.
 
-## Step 4. Start your app and open it
+## Step 4. Open your app again when you need it
 
-Start your dev server as usual, then:
+`connect` already started the dev server and opened the app. On a later day, start your dev server as usual, then:
 
 ```bash
 npx @reticlehq/server open
@@ -216,7 +225,7 @@ Read what that actually proves:
 
 ## What "verified" can say
 
-<CardGroup cols={3}>
+<CardGroup cols={2}>
   <Card title="yes" icon="circle-check">
     The consequence you named actually happened, and the evidence is attached.
   </Card>
@@ -226,6 +235,9 @@ Read what that actually proves:
   <Card title="unknown" icon="circle-question">
     Reticle drove the app and could not tell. **This is not a pass.** Report it as unknown.
   </Card>
+  <Card title="no-fault" icon="circle-minus">
+    Nothing was declared to prove, so nothing was checked. **Not a pass either:** add an `until`.
+  </Card>
 </CardGroup>
 
 That third state is the one that matters. Most tools have two outcomes and quietly file "I couldn't tell" under "fine". A verification layer that cannot admit uncertainty is just a very confident random number generator.

package/docs/telemetry.md

@@ -48,7 +48,7 @@ Eighteen kinds of events, each a single small JSON object. This is the whole lis
 
 **Parameter and flag NAMES are collected; their VALUES are not.** We record that `reticle_act` was called with `ref` and `action`, and that you ran `reticle serve --headed --port`. We do not record what you set them to. This distinction is the whole safety property, and it is absolute for CLI flags: `--http-token` holds a secret, `--drive` holds a URL, `--storage-state` holds a file path, so no flag value is ever sent. For tool parameters there is one narrow exception: a short, explicit allowlist of parameters whose values are enums _we_ defined (`action: "click"`), listed in [`argument-shape.ts`](https://github.com/reticlehq/reticle/blob/main/server/src/telemetry/argument-shape.ts). A value outside that allowlist reports as `other`, so a future schema change cannot quietly start forwarding free text. `reticle_act`'s `args` (the text being typed into your app, which on a login form is a password) is **never** in that allowlist.
 
-`daemon_stopped` carries: how long the session ran, how many tool calls and of which tools, how long each tool took (total and worst case), how many failed, how many verifications ran, browser/lease connection attempts with their failure causes, and which MCP clients connected (`claude-code`, `cursor`).
+`daemon_stopped` carries: how long the session ran, how many tool calls and of which tools, how long each tool took (total and worst case), how many failed, how many verifications ran, browser/lease connection attempts with their failure causes, and which MCP clients connected (`claude-code`, `cursor`). It also carries how the in-page HUD was used: presses per control (`hudControls`, by the control's name from a closed list Reticle defines, a toggle as `name:on` / `name:off`), how long the HUD sat as a bubble, collapsed or open and on which page (`hudViewMs`, `hudPanelMs`), which rail slides were shown (`hudSlides`), and the order of those presses and views, cut at 60 (`hudJourney`). Control names, never anything typed or shown on the page.
 
 It also carries a snapshot of the **machine's** state (our own process's memory, free and total system RAM, load average and CPU count), taken at shutdown and again on any crash. This is what separates "your machine ran out of memory" from "Reticle has a bug", which otherwise produce identical-looking failures. No hostname, no username, no paths, no process list.
 

package/docs/tools/act.mdx

@@ -59,7 +59,7 @@ Real response:
 
 ## Actions
 
-`click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `drag` · `webmcp`
+`click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `drag`
 
 | Action           | Arguments                                                       |
 | ---------------- | --------------------------------------------------------------- |

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

@@ -10,15 +10,15 @@ icon: comments
 
 The presenter panel in your app shows a live transcript of what the agent is doing. It reads "live" until the agent says otherwise. So an agent that wanders off without a word leaves a panel claiming work is in progress forever.
 
-| Action     | What it does                                                             |
-| ---------- | ------------------------------------------------------------------------ |
-| `yield`    | Hand control back between turns. `mode: "waiting"` or `"ask"`. Revivable |
-| `end`      | The task is done. Frees the session; revives on the next action          |
-| `tune`     | Adjust session behaviour, such as `idleEndMs`, the idle-end window       |
-| `resume`   | Clear a pause the human applied                                          |
-| `messages` | Drain the human-to-agent inbox                                           |
-| `review`   | List, and with `resolve`, retire the mistakes a human pinned to elements |
-| `narrate`  | State your intent on the presenter panel, with an optional `level`       |
+| Action | What it does |
+| --- | --- |
+| `yield` | Hand control back between turns. `mode: "waiting"` or `"ask"`. Revivable |
+| `end` | The task is done. Frees the session; revives on the next action |
+| `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 |
+| `review` | List, and with `resolve`, retire the mistakes a human pinned to elements |
+| `narrate` | State your intent on the presenter panel, with an optional `level` |
 
 ```json
 { "action": "yield", "mode": "waiting" }

package/docs/usage.md

@@ -415,11 +415,10 @@ A `state` assertion is graded as a **consequence** (a wrong element or stale ren
 | `select` | `{ value }` | `<select>` option |
 | `check` / `uncheck` | n/a | checkbox/radio |
 | `submit` | n/a | submits the element's `<form>` |
-| `press` | `{ key, modifiers? }` | keydown/up (default `Enter`); `modifiers`: an array of `Meta` / `Control` / `Shift` / `Alt` for Cmd+K-style shortcuts |
+| `press` | `{ key, modifiers?, holdMs?, keys?, code? }` | keydown/up (default `Enter`); `modifiers`: an array of `Meta` / `Control` / `Shift` / `Alt` for Cmd+K-style shortcuts. With a `ref` the key is dispatched AT that element; with NO ref it is a document key (Escape, Tab, a shortcut) and goes through the real keyboard, so it can actually move focus. `holdMs` keeps the key DOWN for that long (hold-to-confirm, hold-to-reveal). `keys` holds several keys together, pressed in order and released in reverse, and `code` names the physical key: both stay on the in-page dispatcher, which is the only path that can express them |
 | `scrollIntoView` | n/a |  |
 | `upload` | `{ name, content?, type? }` | sets a file on `<input type=file>` |
 | `drag` | `{ toRef }` | pointer-based drag (dnd-kit / rbd) + HTML5 DnD |
-| `webmcp` | `{ tool, params }` | calls a `navigator.modelContext` tool if the site exposes one |
 
 ---
 
@@ -817,7 +816,7 @@ A session starts on the agent's first activity and must reliably end even when t
 - **Agent kills the Reticle server process** (so no push can arrive) → the SDK self-ends the session after it can't reach the bridge for `BRIDGE_LOST_MS` (~15s), showing "lost connection to Reticle."
 - **Slow-but-alive agent** → if it goes quiet long enough to auto-end and then acts again, the session **revives** automatically (an explicit `reticle_session {action:"end"}` stays terminal).
 
-Tune the idle window with `reticle_session({ action: "tune", idleEndMs })`; it updates both the browser timer and the server reaper. The human keeps the panel (with Copy/Export of the run) after any end.
+Tune the idle window with `reticle_session({ action: "tune", idleEndMs })`; it updates both the browser timer and the server reaper. When the HUD covers a control you have to test, `reticle_session({ action: "tune", hud: "top-left" })` moves it (any corner), and `hud: "hidden"`, `"shown"` or `"removed"` (until the page reloads) take it out of the way; the call fails rather than pretending if the page could not apply it. The human keeps the panel (with Copy/Export of the run) after any end.
 
 ### `reticle_session {action:"narrate"}`: show the agent's intent
 
@@ -1054,6 +1053,9 @@ When `inputMode` is `"synthetic"` and the target has hover/enter handlers, the r
 | `provider-declined` / `provider-error` | the CDP provider declined or threw (the latter also sets `warning`) |
 | `not-a-pointer-action` | `fill`/`type`/etc. are always synthetic by design |
 | `synthetic-click-preferred` | a `click`/`dblclick` ran the occlusion-honest synthetic path by default; pass `args:{ native:true }` to force a trusted native click |
+| `synthetic-element-press-preferred` | the `press` named a `ref`/`target`, so it stayed synthetic on purpose: dispatching AT that element reaches it exactly, while a real keyboard sends the key to whatever holds focus. A `press` with NO ref is a document key (Escape, Tab, a modifier shortcut) and does run through the real keyboard when one is configured |
+| `synthetic-multi-key-press-preferred` | the `press` named `keys`: several keys held down **together**, pressed in order and released in reverse. Only the in-page dispatcher implements that sequence; a real keyboard chord cannot express it |
+| `synthetic-key-code-press-preferred` | the `press` named an explicit `code`, which the real driver cannot send: it presses by KEY name, so `{ text: "z", code: "KeyY" }` would strike a different key than the one asked for |
 
 (No `inputModeReason` is set when real input simply isn't configured; synthetic is the expected default there.)
 

package/docs/what-is-recorded.md

@@ -15,7 +15,7 @@ Everything lands in `.reticle/` in your project, and it is yours. Three kinds of
 | --- | --- | --- |
 | **runs** | a verdict and its evidence | what was claimed, whether it held, the request or state change that decided it, and the `file:line` of the element driven |
 | **flows** | a journey you drove, saved so it can be replayed | the steps, the anchors they resolve by, and the values that were typed |
-| **memory** | what this project has learned across sessions | intents you declared, envelopes of normal behaviour, notes about anchors that drift |
+| **memory** | what this project has learned across sessions | intents you declared, envelopes of normal behaviour, notes about anchors that drift, the coverage ledger (`coverage.json`), the notes people pinned in the HUD (`notes.json`), and the user's latest request as the agent relayed it (`request.json`, local only) |
 
 `.reticle/` splits into a part meant for git and a part meant to stay local. Flows are the part worth committing: a saved flow is a regression test. Evidence is the part that is not.
 
@@ -27,7 +27,7 @@ Everything lands in `.reticle/` in your project, and it is yours. Three kinds of
 
 So: **drive staging.** Not because the risk is large, but because it is real and avoiding it is free.
 
-Network bodies are **not** captured by default. Page content that reaches a verdict is the element text and attributes the assertion needed, not a copy of the DOM.
+Network bodies are **not** captured by default. When you turn body capture on (`captureNetworkBodies: true`, or `VITE_RETICLE_CAPTURE_BODIES=1`), redaction runs **before each body is kept**. Built-in rules mask keys such as `password`, `apiKey` and `authorization`, selected token keys, and high-confidence secret shapes such as JWTs and `sk_live_…` keys. Other credential values can remain under names or in formats those rules do not recognize; add app-specific field names with `redact.keys` and use staging. Page content that reaches a verdict is the element text and attributes the assertion needed, not a copy of the DOM.
 
 ## What leaves, only if you ask
 
@@ -39,6 +39,14 @@ Once linked, you choose what syncs:
 npx @reticlehq/server config --runs on|off --flows on|off --memory on|off
 ```
 
+`--memory` covers the coverage ledger and the HUD notes as well, and the notes are the words people typed. The user's request (`request.json`, the prompt the agent relayed, redacted) goes to the platform with the runs from a linked project, so the dashboard can show what each run was for; `"shareRequests": false` in `.reticle.json` keeps it on the machine. An unlinked project sends it nowhere, and it is kept out of git either way.
+
+The Harness runs on the platform, so the platform sees what it drives: each step's result goes there so it can choose the next one. A secret field is sent by name only; its value is typed in on your machine.
+
+**Your apps, for the platform's chat.** While a project is linked, the daemon tells the platform every ten seconds, with or without an app open, which apps on this machine have Reticle connected, so the chat can list them and you can pick one instead of typing an address. For each app it sends: a key made from a hash of this machine and the project's folder (the folder path itself never leaves), the project's name (its package name, else its folder's name), the address the app is open at with Reticle's own query parameters removed, the page title, what it is built with (`react`, `vite`, `electron`, …), this machine's name, the Reticle version, and what this daemon can do for the platform. The platform keeps the last report for each app until the project is deleted. Its answer can ask this machine to open one of those apps again, or show you a short notice (for example, to update Reticle), which appears in the daemon's log and on the HUD.
+
+**Drives asked for from the platform's chat.** When someone in your workspace asks the chat to drive one of your apps, the daemon drives it here, on your machine: in the tab you have open, or in a browser of its own, headless or in a window, as the chat asked. It only opens addresses on this machine or apps already open here. On a recent platform, the platform decides each step: it sends Reticle tool calls from a fixed list (reading the page, acting on it, asserting, recording and replaying flows), the daemon runs them in that one tab, and sends back what each returned, which includes what the page showed. On an older platform, the daemon drives and sends back each step's result and how the drive ended. Either way the platform keeps the drive as a check you can open in Runs. Unless the request said not to record, the daemon also sends a picture of the tab it is driving, a JPEG about once a second, so the chat can show the drive live and replay it afterwards. Pictures are kept with that check (at most a few minutes' worth per drive) and deleted with the project. A tab the daemon opened, headless or in a window, can be pictured, with Reticle's own panel left out; so can the window `reticle drive` opened, which is pictured as you see it, panel included. A tab in your own browser sends steps only. Unlinking the project stops all of it.
+
 ## Telemetry, which is separate from all of the above
 
 The CLI sends anonymous usage events: event names and a random installation id. No code, no page content, no URLs from your app. It is how we know which parts of the product are reached at all.
@@ -49,7 +57,9 @@ DO_NOT_TRACK=1               # the convention, honoured
 npx @reticlehq/server telemetry disable   # this machine, permanently
 ```
 
-Feedback is the only free text that ever leaves, it is never collected passively, and `RETICLE_FEEDBACK=0` disables it.
+Telemetry carries no free text. Free text leaves in three ways, each one something you chose: a feedback report (never collected passively; `RETICLE_FEEDBACK=0` disables it), HUD notes on a linked project with `--memory on`, and the user's request from a linked project unless `"shareRequests": false`.
+
+The daemon also fetches a small public file, `https://reticle.sh/hud/notices.v1.json`, for the notices in the HUD's rail. The request carries nothing about you or your project. `RETICLE_TELEMETRY=0` or `DO_NOT_TRACK=1` stops it, and `RETICLE_HUD_NOTICES_URL` points it elsewhere.
 
 ## What `init` writes to your project
 

package/docs/what-is-reticle.mdx

@@ -31,7 +31,9 @@ Reticle sits next to several familiar categories, and it works alongside each of
 
 **Monitoring.** Reticle runs against environments you control (a dev server, a staging or preview deployment) and replays saved flows in CI. The SDK refuses to connect in a production build, so it complements an APM or error tracker rather than watching live traffic.
 
-**Your agent.** Reticle has no model of its own for the verify loop. It gives the agent you already use a way to see the running app. Your agent, your model, your keys. (`explore` can drive a journey for you with a model inside the daemon; see [Autodrive](/autodrive).)
+**Not an accessibility auditor.** `reticle_look { action: "page" }` addresses elements by role and name, which is not the same as auditing contrast, focus order, or screen reader behaviour. Use a dedicated accessibility tool for that.
+
+**Your agent.** Reticle has no model of its own for the verify loop. It gives the agent you already use a way to see the running app. Your agent, your model, your keys. (On a linked project, `explore` has the Reticle Harness drive a journey for you on the Reticle platform; see [Autodrive](/autodrive).)
 
 **The verdict.** A verdict of `unknown` means Reticle drove the app and could not tell. It is deliberately not rounded up to a pass.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "Reticle CLI, bridge and MCP server: a coding agent drives your running web app from the inside and gets a verdict with evidence, for change verification, access control, accessibility, performance and SEO checks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,15 +19,15 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "ws": "^8.21.3",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.24.0",
-    "@reticlehq/browser": "3.4.0",
-    "@reticlehq/init": "3.4.0",
-    "@reticlehq/engine": "3.4.0",
+    "@reticlehq/browser": "3.6.0",
+    "@reticlehq/core": "3.6.0",
+    "@reticlehq/engine": "3.6.0",
     "open-verification": "1.0.0",
-    "@reticlehq/core": "3.4.0"
+    "@reticlehq/init": "3.6.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
@@ -64,13 +64,9 @@
     "cli"
   ],
   "reticle": {
-    "changelog": "Reticle writes and tightens your regression flows for you: every drive is recorded automatically and replays with no model in the loop. The agent now sees nine tools instead of seventeen, `init` stops at a connected app and proving a flow is a separate first run, and Windows is supported. Upgrading from 2.x: see MIGRATION.md.",
+    "changelog": "Drive your localhost app from the Reticle platform's chat: the daemon of a linked project drives it on your machine, the chat shows it live and keeps it as a check with a replay. The Harness now runs only on the platform, on every plan, and plans, replays and learns each app. A page on SDK 3.1-3.4 is no longer version-skewed, a pressed key sends its keyCode, and a screenshot never carries another tab's pixels. Upgrading from 3.5: see MIGRATION.md.",
     "breakingChanges": [
-      "The default MCP surface is the merged nine. reticle_snapshot/query/inspect/state -> reticle_look { action }, reticle_network/console -> reticle_observe { action }, reticle_sessions/feedback -> reticle_session { action }, reticle_wait_for -> reticle_assert { action: \"wait\" }, reticle_act_sequence -> reticle_act { steps }. Old names redirect when CALLED, but an allowedTools allowlist or an MCP permission rule naming one refuses first -- update those by hand.",
-      "Twelve tools are unreachable on the default surface and have NO redirect: reticle_capabilities, reticle_clock, reticle_context, reticle_flow_replay, reticle_flow_save, reticle_intent, reticle_network_mock, reticle_record, reticle_run, reticle_screenshot, reticle_storage, reticle_visual_diff. The default surface ships no reticle_run hatch. Start the daemon with RETICLE_ADVERTISE_ALL_TOOLS=1 (read once at startup) and call them by name. Saved flows still replay via reticle_verify { action: \"flows\" }.",
-      "`reticle init` no longer drives: it ends at a connected session. --flow, --no-drive and --drive-model now exit non-zero, each naming its replacement. Prove a flow with reticle_verify { action: \"explore\", persona: \"<who does what>\" }, or npx @reticlehq/server verify <url> --explore --persona \"...\". init's exit code now means \"nothing connected\" rather than \"no verdict\". --files-only is unchanged.",
-      "@reticlehq/server now requires Node >=20.11 (was >=20.0.0).",
-      "@reticlehq/server, @reticlehq/init and @reticlehq/test declare license FSL-1.1-ALv2 instead of \"SEE LICENSE IN LICENSE\". The terms are identical; add the SPDX id to a licence allowlist."
+      "reticle_verify { action: \"explore\" } and reticle verify --explore no longer drive on a model key of your own. The Harness decides on the Reticle platform and needs a linked project (npx @reticlehq/server connect); every plan includes Harness credits. ANTHROPIC_API_KEY, OPENAI_API_KEY and JEV_API_KEY are no longer read for driving, RETICLE_HARNESS_DRIVER and RETICLE_HARNESS_MODEL are ignored, and the explore tool's `driver` argument is removed. A secret field's value comes from RETICLE_SECRET_<FIELD> on your machine."
     ]
   },
   "publishConfig": {

package/dist/features/harness/driver.d.ts

@@ -1,50 +0,0 @@
-/**
- * The model binding: the one file in the harness that knows there is a network.
- *
- * Everything about the loop lives in harness.ts against the `ModelDriver` interface, so this file is
- * a translation layer and nothing else. That split is not tidiness — it is what lets the loop be
- * tested against a scripted model with no API key, on every run of the unit gate.
- *
- * It speaks the Messages API over `fetch` rather than through a vendor SDK. The loop is ours (the
- * harness owns the step budget and has to record every call even when a run is cut short), so an SDK
- * would contribute one HTTP POST and a dependency — and this package's dependency list is short on
- * purpose.
- */
-import type { ModelDriver } from './harness.js';
-/**
- * The default driver model.
- *
- * Deliberately not the largest model available. The harness is not reasoning about business logic; it
- * is exploring an interface and stating consequences, and the verdict is produced by the engine
- * reading what it drove. If finding defects required a frontier model HERE, the engine would not be
- * doing its job — so the model tier is also a standing test of the design.
- */
-export declare const DEFAULT_HARNESS_MODEL = "claude-sonnet-5";
-export declare const DEFAULT_HARNESS_BASE_URL = "https://api.anthropic.com";
-/** The one call this file makes. Injected so a test can drive the translation with no network. */
-export type HarnessFetch = (url: string, init: {
-    method: string;
-    headers: Record<string, string>;
-    body: string;
-}) => Promise<{
-    ok: boolean;
-    status: number;
-    text(): Promise<string>;
-}>;
-export interface HarnessDriverOptions {
-    apiKey: string;
-    model?: string;
-    baseUrl?: string;
-    /** Injected for tests. Defaults to the platform `fetch`. */
-    fetch?: HarnessFetch;
-}
-/**
- * Read the harness's configuration out of the environment.
- *
- * Returns `undefined` when there is no key, which is the ONLY thing that decides whether the harness
- * is available. Stated as a read rather than a throw because "you have not configured this" is a
- * routine answer a caller offers a way out of, not a failure.
- */
-export declare function harnessOptionsFromEnv(env: Record<string, string | undefined>): HarnessDriverOptions | undefined;
-/** Build a driver backed by the Messages API. */
-export declare function harnessDriver(options: HarnessDriverOptions): ModelDriver;