@reticlehq/server 3.5.0 → 3.6.0

package/dist/telemetry/telemetry.d.ts

@@ -10,6 +10,18 @@ import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Id
  * analytics side learns a customer list only when we deliberately upload one.
  */
 export declare const POSTHOG_GROUP_ORGANIZATION = "organization";
+/**
+ * Read (or mint-and-persist) the anonymous machine id. `firstRun` is true the run that created it.
+ *
+ * Read first and create exclusively (`wx`), rather than asking `existsSync` and then writing: two
+ * processes starting together used to both see no file, both mint, and the second write replaced
+ * the first id, so one machine reported as two first runs. The loser of the exclusive create now
+ * reads the winner's id instead.
+ */
+export declare const resolveIdentity: (file?: string) => {
+    anonymousId: string;
+    firstRun: boolean;
+};
 /**
  * One-way project fingerprint: distinct-count of this = "projects Reticle is used in", reveals nothing.
  *

package/dist/telemetry/telemetry.js

@@ -19,6 +19,7 @@ import { appendFileSync, readFileSync, writeFileSync, mkdirSync, existsSync, rmS
 import { homedir, platform } from 'node:os';
 import { dirname, join } from 'node:path';
 import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, isSessionScoped, } from '@reticlehq/core/telemetry';
+import { ReticleEnv } from '@reticlehq/core';
 import { SERVER_VERSION } from '../command/version/identity/server-version.js';
 const RETICLE_DIR = join(homedir(), '.reticle');
 const ID_FILE = join(RETICLE_DIR, 'telemetry-id');
@@ -100,8 +101,8 @@ import { licenseFacts } from './license-activation.js';
 import { gitFacts } from './git-facts.js';
 import { currentAutomationHint } from './automation-hint.js';
 const Env = {
-    DISABLE: 'RETICLE_TELEMETRY', // "0" / "false" / "off" → disabled
-    DO_NOT_TRACK: 'DO_NOT_TRACK', // the cross-tool opt-out convention (any truthy value)
+    DISABLE: ReticleEnv.TELEMETRY, // "0" / "false" / "off" → disabled
+    DO_NOT_TRACK: ReticleEnv.DO_NOT_TRACK, // the cross-tool opt-out convention (any truthy value)
     URL: 'RETICLE_TELEMETRY_URL', // override the PostHog host (EU cloud / self-hosted)
     FILE: 'RETICLE_TELEMETRY_FILE', // record to a local JSONL file and send NOTHING — see the sink note
     KEY: 'RETICLE_TELEMETRY_KEY', // override the PostHog project key
@@ -140,17 +141,45 @@ const isDisabled = (env, cwd = process.cwd()) => {
  * file, and a test run. This lifts one implicit guard for one user-initiated event kind.
  */
 const onlyBlockedBySourceCheckout = (env, cwd) => isDisabled(env, cwd) && !isDisabled(env, '/');
-/** Read (or mint-and-persist) the anonymous machine id. `firstRun` is true the run that created it. */
-const resolveIdentity = () => {
+/** Node's code for "the file is already there" — what an exclusive create answers when it lost. */
+const EEXIST = 'EEXIST';
+const isAlreadyThere = (error) => 'object' === typeof error && null !== error && EEXIST === error.code;
+const readIdFile = (file) => {
     try {
-        if (existsSync(ID_FILE)) {
-            const id = readFileSync(ID_FILE, 'utf8').trim();
-            if (id.length > 0)
-                return { anonymousId: id, firstRun: false };
-        }
+        const id = readFileSync(file, 'utf8').trim();
+        return id.length > 0 ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Read (or mint-and-persist) the anonymous machine id. `firstRun` is true the run that created it.
+ *
+ * Read first and create exclusively (`wx`), rather than asking `existsSync` and then writing: two
+ * processes starting together used to both see no file, both mint, and the second write replaced
+ * the first id, so one machine reported as two first runs. The loser of the exclusive create now
+ * reads the winner's id instead.
+ */
+export const resolveIdentity = (file = ID_FILE) => {
+    try {
+        const existing = readIdFile(file);
+        if (existing !== undefined)
+            return { anonymousId: existing, firstRun: false };
         const id = randomUUID();
-        mkdirSync(RETICLE_DIR, { recursive: true });
-        writeFileSync(ID_FILE, id, 'utf8');
+        mkdirSync(dirname(file), { recursive: true });
+        try {
+            writeFileSync(file, id, { encoding: 'utf8', flag: 'wx' });
+        }
+        catch (error) {
+            if (!isAlreadyThere(error))
+                throw error;
+            const raced = readIdFile(file);
+            if (raced !== undefined)
+                return { anonymousId: raced, firstRun: false };
+            // An empty file left by a crash: replace it, as the old code did.
+            writeFileSync(file, id, 'utf8');
+        }
         return { anonymousId: id, firstRun: true };
     }
     catch {
@@ -209,10 +238,10 @@ const packageRoot = (cwd) => {
 /** Print the opt-out notice exactly once per machine (honest disclosure, the OSS-trust bar). */
 const showNoticeOnce = () => {
     try {
-        if (existsSync(NOTICE_FILE))
-            return;
         mkdirSync(RETICLE_DIR, { recursive: true });
-        writeFileSync(NOTICE_FILE, '1', 'utf8');
+        // Exclusive create IS the "once": it throws when the file is already there, so the check and
+        // the write cannot be split by a second process printing the notice too.
+        writeFileSync(NOTICE_FILE, '1', { encoding: 'utf8', flag: 'wx' });
         process.stderr.write('reticle: anonymous usage telemetry helps improve reticle — no code, no PII, ' +
             `and your app's data never leaves your machine (${POLICY_URL}). ` +
             'Opt out any time: reticle telemetry disable\n');

package/dist/telemetry/verification-of.js

@@ -70,6 +70,7 @@ const REPLAY_VERDICTS = new Map([
     [ReplayStatus.OK, { verified: Verified.YES, passed: true }],
     [ReplayStatus.DRIFT, { verified: Verified.NO, passed: false }],
     [ReplayStatus.ERROR, { verified: Verified.UNKNOWN, passed: false }],
+    [ReplayStatus.UNVERIFIABLE, { verified: Verified.UNKNOWN, passed: false }],
 ]);
 function replayVerdict(toolName, status) {
     if (ReticleTool.FLOW_REPLAY !== toolName || 'string' !== typeof status)

package/dist/wire-journal.js

@@ -8,6 +8,7 @@
  * the 1000-line backstop is what asked for the split.
  */
 import { artifactRootResolver } from './memory/project/artifact-root-resolver.js';
+import { servingDirectoryOf } from './portal/session/serving-directory.js';
 import { originOf } from './portal/session/session-manager.js';
 import { Bridge } from './portal/bridge/bridge.js';
 import { FlowStore } from './language/flows/flows.js';
@@ -35,7 +36,9 @@ export function attachJournal(bridge, deps) {
     const ambientStore = new AmbientStore(deps.fs, deps.reticleRoot);
     // Built once, not per session: the resolver walks config discovery and the user-level registry,
     // and neither changes between two tabs connecting a second apart.
-    const resolveArtifactRoot = artifactRootResolver(deps.reticleRoot);
+    const resolveArtifactRoot = artifactRootResolver(deps.reticleRoot, {
+        servingDirectory: servingDirectoryOf,
+    });
     bridge.attachSessionCreate((session) => {
         // Stamp the project's own `.reticle` before ANY counter fires for this session. Without it every
         // verdict is recorded against wherever the daemon was started, which is how one app's evidence

package/docs/README.md

@@ -76,7 +76,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [vs-screenshots.mdx](vs-screenshots.mdx) | why a better vision model does not fix a non-visual bug |
 | [what-is-recorded.md](what-is-recorded.md) | what Reticle keeps, what is redacted, and what it takes for any of it to leave your machine |
 | [telemetry.md](telemetry.md) | what is collected, and how to turn it off |
-| [local-registry.md](local-registry.md) | installing an unpublished build |
+| [local-registry.md](https://github.com/reticlehq/reticle/blob/main/docs/local-registry.md) | installing an unpublished build |
 | [license-activation.mdx](license-activation.mdx) | you have a key: where to set it, how to confirm it, what to do when it fails |
 | [enterprise.md](enterprise.md) | the licensed surface |
 

package/docs/agent-cheatsheet.md

@@ -135,7 +135,7 @@ Not on this surface at all, but one hop away: `reticle_run { tool, args }` calls
 | --- | --- | --- |
 | **flows** | `reticle_flow_save*` / `reticle_flow_replay` / `reticle_verify { action: "heal" }` | Replayable **golden journeys**, anchored to testids/signals; drift is legible and self-heals. |
 | **baselines** | `reticle_baseline {action:"save"}` / `reticle_baseline {action:"diff"}` | Structural **"before" snapshots**; `reticle_baseline {action:"diff"}` flags regressions against them. |
-| **project.json** | `reticle_project` | Cross-run **run-history**: "did it behave like last run?" read via `reticle_project`. |
+| **project.json** | `reticle_project` | Cross-run **run-history**: "did it behave like last run?" read via `reticle_project`. Its `cloud.sync` says where this project's runs stand with the platform (on it, waiting, refused, last push); `push: true` syncs before answering. |
 
 > `reticle_project` / `project.json` are the **run-history layer**. flows answer "does the journey still work?"; baselines answer "did the structure change?"; project.json answers "is this run consistent with prior runs?".
 

package/docs/autodrive.md

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

package/docs/cli/doctor.mdx

@@ -74,6 +74,12 @@ All three captures below are real, taken by pointing `PLAYWRIGHT_BROWSERS_PATH`
 
 **`✓ using the installed Google Chrome`** (or Microsoft Edge) means the pinned build is absent and Reticle drives the browser you already have instead, through Playwright's channel. Nothing to do: the line also names the command that adds Playwright's own build, if you want it.
 
+**`✓ using <path> (RETICLE_CHROMIUM_PATH)`** means you named the browser with [`RETICLE_CHROMIUM_PATH`](/environment), so the bundled revision is not checked at all. If the path does not exist, is not a file (a directory, say), or is not executable, the line says which instead, and offers no install command, because installing would not fix a wrong path:
+
+```
+  chromium     ✗ RETICLE_CHROMIUM_PATH points at /opt/nope/chrome, which does not exist; fix the path, or unset it to use Playwright's own Chromium
+```
+
 When neither is there, Reticle does not refuse. The first command that needs a browser (a lease, `verify`, a drive) runs the bundled Playwright's own pinned install for you, announced on stderr so `reticle mcp`'s stdout stays clean. The two `✗` lines below are what you see when that has not happened yet, or failed.
 
 **`✗ wrong revision`** means builds are installed and none of them is the wanted one. One pinned download away. The line names the revision Playwright wants, then every revision the root actually holds, then the exact command:

package/docs/cli/drive.mdx

@@ -53,10 +53,16 @@ A daemon on `:4400` is the normal state the moment any agent connects, and `driv
 
 ```bash
 $ npx @reticlehq/server drive http://localhost:5173
-{"event":"reticle_drive_attached","port":4400,"url":"http://localhost:5173","sessionId":"lease-9f2b…","ready":true}
+{"event":"reticle_drive_attached","port":4400,"url":"http://localhost:5173","sessionId":"lease-9f2b…","ready":true,"projectId":"web","title":"Web"}
 ```
 
-A plain-text line follows it naming the same session, how long it survives untouched (any tool call against it resets that), and, if the page never dialled the bridge, why.
+A plain-text line follows it naming the same session, the app it belongs to (the `projectId` and title the page reported), how long it survives untouched (any tool call against it resets that), and, if the page never dialled the bridge, why.
+
+In a monorepo the port you meant for one app can be held by another. When the current directory's `.reticle.json` names a different project from the one the page reported, the line ends with a warning saying so, and the JSON carries both as `projectId` and `expectedProjectId`. Real capture, with app `admin` on the port, `drive` run from app `web`, and the sentence break shown as `...`:
+
+```
+attached to the Reticle daemon on :4497 ... it is driving http://localhost:5177/?__reticle_project=admin (project "admin", "Admin console") as session lease-74bf5522-8eee-4ea2-b66d-4c056c7dad3a, which every Reticle tool can address. It is released after 300s untouched; any tool call against it resets that. Warning: this directory's .reticle.json is project "web", but the page at http://localhost:5177/?__reticle_project=admin is project "admin", so another app is probably serving that port. Check which dev server is on it before trusting anything this session reports.
+```
 
 That session lives in the daemon, so the tools your agent already has open can address it by id. You do **not** need `reticle stop` first, and should not use it: the MCP proxy respawns a daemon as soon as the next tool call arrives, which is a race a manual `stop` loses.
 

package/docs/cli/init.mdx

@@ -74,21 +74,19 @@ With `--no-mcp`, the whole MCP and rules group collapses into one skipped line:
       --no-mcp ... also skips the agent rule files (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command
 ```
 
-Run from a workspace root with several apps, it refuses to guess, names them, and exits `1`:
+Run from a workspace root with several apps, it refuses to guess, prints a command for each one, and exits `1`:
 
 ```
-Several apps found in this workspace. Re-run `reticle init` inside the one you want:
-  adapters/build/next
-  adapters/build/vite
-  apps/atlas
-  apps/bench-app
-  apps/electron-smoke
-  apps/large-dom-bench
-  apps/next-smoke
-  apps/tauri-smoke
-  apps/vibe-builder-demo
-
-Or name one without changing directory:  reticle init --app apps/next-smoke
+Several apps found in this workspace. Re-run `reticle init` for the one you want:
+  reticle init --app adapters/build/next
+  reticle init --app adapters/build/vite
+  reticle init --app apps/atlas
+  reticle init --app apps/bench-app
+  reticle init --app apps/electron-smoke
+  reticle init --app apps/large-dom-bench
+  reticle init --app apps/next-smoke
+  reticle init --app apps/tauri-smoke
+  reticle init --app apps/vibe-builder-demo
 ```
 
 Given `--app`, it says which directory it moved to before printing the plan:

package/docs/cli/status.mdx

@@ -45,7 +45,11 @@ A session's parenthesised notes are the ones that explain an answer you would ot
 
 ### `--json`
 
-The same facts as one event line on stderr, for a caller that parses rather than reads:
+The same facts as one JSON line on stdout, so a caller can pipe it to a parser:
+
+```bash
+npx @reticlehq/server status --json | jq '.running, .sessionCount'
+```
 
 ```json
 {

package/docs/cli/version.mdx

@@ -16,10 +16,10 @@ All three are the same command. No flags.
 
 ## What it prints
 
-One `reticle_version` line. Real capture:
+The version, and nothing else, on stdout, so `V=$(reticle version)` works:
 
-```json
-{ "t": "2026-08-15T18:42:26.275Z", "event": "reticle_version", "version": "2.8.0" }
+```text
+3.6.0
 ```
 
 ## Exit codes

package/docs/cli.mdx

@@ -38,7 +38,7 @@ For a self-hosted cloud, add `--url <cloud origin>`. If the app was already wire
 
 ### `reticle init`
 
-Wires Reticle into the project in the current directory, then boots the app and proves a session connected. It exits non-zero if nothing connected, and prints what is left to do. It does not drive: proving a flow is the FIRST RUN, `reticle verify <url> --explore --persona "<who does what>"`.
+Wires Reticle into the project in the current directory, then boots the app and proves a session connected. It exits non-zero if nothing connected, and prints what is left to do. It does not drive: proving a flow is the FIRST RUN, which your agent drives with `reticle_act_and_wait` and an `until` on its last step, or, with a linked project, `reticle verify <url> --explore --persona "<who does what>"`.
 
 ```
 reticle init  [--env KEY=VALUE]... [--app <dir>] [--license <key>]

package/docs/desktop.mdx

@@ -210,13 +210,15 @@ installReticleCapture(win);
 
 That is all: no CDP flag, no extra packages, and it works on a packaged `file://` renderer. `reticle_screenshot` and `reticle_visual_diff` then work on your app.
 
+In a multi-window app, name each window: `installReticleCapture(win, { label: 'settings' })`. The session list then shows `window: "settings"`. Electron windows have no name of their own, and two of them often share a url.
+
 Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-port=9222` plus `RETICLE_CDP_URL=http://127.0.0.1:9222` also works and additionally enables `fullPage` (the main-process route captures the window as composited, so it cannot scroll-stitch).
 
 **Tauri: one Rust command.** The crate is versioned independently of the npm packages:
 
 ```toml
 [dependencies]
-reticle-tauri = "3.5"
+reticle-tauri = "3.6"
 ```
 
 ```rust
@@ -344,6 +346,8 @@ Playwright MCP is faster. It is also structurally unable to see an IPC failure,
 
 **`reticle open` says there is nothing to open.** That is correct for a desktop app. There is no URL, and there is no `reticle drive` for desktop either. Both launch a browser, which is not what you are testing.
 
+**Several windows, and the wrong one gets driven.** Every window that loads the SDK is its own session, and `reticle_session { action: "list" }` names each (`window: "main"`: Tauri's label, or the `label` you gave `installReticleCapture` on Electron) with whether it is `hidden`. A page served as an error (a dev server's 404 for a static page, say) carries `documentStatus` and is never auto-selected ahead of a working one. To drive a specific window, pass its `sessionId`. To get rid of a stray hidden window for good, call `reticle_session { action: "end", sessionId, disconnect: true }`. It stays detached across its own reloads until the daemon restarts.
+
 **A screenshot came back partly blank.** The window is occluded or minimized, so it is only partially composited. Bring it forward and capture again.
 
 **`{ ok: false, reason: 'full-page-unsupported' }`.** You asked for `fullPage: true` on a platform that cannot render offscreen. Only Tauri on Linux (WebKitGTK) can. Capture the viewport instead, or scroll and capture in sections.

package/docs/environment.mdx

@@ -33,6 +33,7 @@ Reticle works with none of these set. Each one changes a single behaviour, and m
 | Variable | Read by | What it does |
 | --- | --- | --- |
 | `RETICLE_CDP_URL` | daemon | Attach to a browser that is already running, over CDP, instead of launching one. |
+| `RETICLE_CHROMIUM_PATH` | daemon, `drive`, `verify`, `doctor` | The Chromium executable to launch, for a machine where Playwright's own build is missing and cannot be installed and there is no Chrome or Edge in the usual place. When set, nothing else is tried: no Playwright build, no Chrome or Edge, no install. A path that does not exist, is not a file, or is not executable is refused with a message naming it and saying which. `doctor` reports on this path instead of the bundled build. |
 | `RETICLE_MAX_CONTEXTS` | daemon | The most leased headless browser contexts the pool runs at once. |
 | `RETICLE_MAX_MESSAGES_PER_SECOND` | daemon | Events per second a page may send before the bridge starts sampling them. It never disconnects. Raise it for a legitimately busy app, such as a streaming dashboard. |
 
@@ -62,13 +63,8 @@ Reticle works with none of these set. Each one changes a single behaviour, and m
 | `RETICLE_CLOUD_KEY` | CLI, daemon | The key's earlier name. Still honoured. |
 | `RETICLE_CLOUD_URL`, `RETICLE_URL` | CLI, daemon | The platform host. `RETICLE_CLOUD_URL` wins when both are set. |
 | `RETICLE_SYNC_INTERVAL_MS` | `reticle sync --watch` | How often the watching sync runs. Every 60 seconds by default. |
-| `ANTHROPIC_API_KEY` | autonomous drive | The key the drive's model uses when no coding agent is in the loop. Without it, the drive is unavailable and everything else is unaffected. |
-| `RETICLE_HARNESS_MODEL` | autonomous drive | The model the drive uses. A small one by default. |
-| `RETICLE_HARNESS_BASE_URL` | autonomous drive | A proxy or gateway in front of the model API. |
-| `RETICLE_HARNESS_MAX_STEPS` | autonomous drive | A hard ceiling on model turns in one drive. It bounds cost. |
-| `RETICLE_HARNESS_DRIVER` | autonomous drive | Which model drives: `anthropic` (the default) or `jev`. |
-| `JEV_API_KEY`, `RETICLE_HARNESS_JEV_URL` | autonomous drive | A direct key and base URL for the `jev` driver. The usual path is `RETICLE_API_KEY` through the platform. |
-| `OPENAI_API_KEY`, `RETICLE_HARNESS_OPENAI_MODEL` | autonomous drive | A direct key and model for the OpenAI driver. |
+| `RETICLE_HARNESS_MAX_STEPS` | autonomous drive | A hard ceiling on steps in one drive. It bounds cost. The drive itself runs on the platform and needs a linked project; every plan, Free included, has monthly Harness credits. |
+| `RETICLE_SECRET_<FIELD>` | autonomous drive, replay | The value of a secret field, typed in on this machine. Only the field's name goes to the platform. |
 
 ## Licensing
 

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 Cloud: run the installer, then `reticle connect --project "My App"` 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. `connect` wires your app, checks that a browser session connected, opens sign-in approval if needed, links the named cloud project, and syncs existing 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. For local-only verification without an account, use `reticle init` instead. You need Node 20.11 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,17 +58,9 @@ Everything is **dev-only** and **localhost-only**. It's tree-shaken out of produ
 
 ---
 
-## Cloud setup: `reticle connect`
+## Wire your app: on the first run, or `reticle init`
 
-After the one-time [installer](/quickstart), 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.
-
-## Local-only path: `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:
 
@@ -104,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-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.5"
+reticle-tauri = "3.6"
 ```
 
 ```rust

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.5"
+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

@@ -61,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.5"
+reticle-tauri = "3.6"
 ```
 
 <Warning>