@reticlehq/server 3.4.0 → 3.6.0

package/dist/telemetry/hud-metrics.js

@@ -9,12 +9,16 @@ import { HudPanel, HudView } from '@reticlehq/core';
  */
 /** How many steps of the journey one window keeps. A journey longer than this is cut, and says so. */
 export const HUD_JOURNEY_MAX = 60;
+/** Distinct slide ids counted per window; past this a broken notices file is not a dashboard. */
+const MAX_SLIDE_IDS = 20;
+const SLIDE_ID = /^[a-z0-9-]{1,56}$/;
 export class HudMetrics {
     #now;
     #controls = new Map();
     #viewMs = new Map();
     #panelMs = new Map();
     #journey = [];
+    #slides = new Map();
     #cut = false;
     /** Did anything happen this window. A HUD merely sitting open is not worth a flush of its own. */
     #changed = false;
@@ -27,6 +31,8 @@ export class HudMetrics {
         // A control the HUD never rendered is dropped here, the one place HUD use is counted, so free
         // text cannot ride in on the id.
         const control = use.control !== undefined && isHudControl(use.control) ? use.control : undefined;
+        if (use.slide !== undefined)
+            this.#countSlide(use.slide);
         if (control === undefined && use.view === undefined && use.panel === undefined)
             return;
         this.#changed = true;
@@ -47,6 +53,15 @@ export class HudMetrics {
                 this.#step(`panel:${use.panel}`);
         }
     }
+    #countSlide(slide) {
+        // A slide id is Reticle's own (`notice-<id>` for the remote ones): lowercase words and dashes.
+        if (!SLIDE_ID.test(slide))
+            return;
+        if (!this.#slides.has(slide) && this.#slides.size >= MAX_SLIDE_IDS)
+            return;
+        this.#slides.set(slide, (this.#slides.get(slide) ?? 0) + 1);
+        this.#changed = true;
+    }
     get empty() {
         return !this.#changed;
     }
@@ -60,12 +75,14 @@ export class HudMetrics {
             ...(panelMs.size > 0 ? { hudPanelMs: Object.fromEntries(panelMs) } : {}),
             ...(this.#journey.length > 0 ? { hudJourney: [...this.#journey] } : {}),
             ...(this.#cut ? { hudJourneyCut: true } : {}),
+            ...(this.#slides.size > 0 ? { hudSlides: Object.fromEntries(this.#slides) } : {}),
         };
     }
     /** Start the next window. The current view and panel carry over, timed from now. */
     reset() {
         const at = this.#now();
         this.#controls.clear();
+        this.#slides.clear();
         this.#viewMs.clear();
         this.#panelMs.clear();
         this.#journey.length = 0;

package/dist/telemetry/onboarding-firsts.d.ts

@@ -1,9 +1,9 @@
-/** A tool call the daemon just ran. Called from the dispatch chokepoint, which sees every one. */
+/** A successful page read. The dispatcher calls this after excluding refusals and pauses. */
 export declare function noteOnboardingFirst(toolName: string): void;
 /**
  * The first ACTION of this run, and the fact that this install has been driven at all.
  *
- * Called from the dispatch chokepoint's own action branch rather than matched on a tool name here.
+ * Called after the dispatcher observes a dispatched action, rather than on an attempted call.
  * The name test was `toolName === ReticleTool.ACT`, on the worry that `act_and_wait` would report
  * one call as two different firsts — and the worry was backwards: this server's instructions tell
  * every agent to PREFER `act_and_wait`, so the step measured the tool we ask agents not to use and

package/dist/telemetry/onboarding-firsts.js

@@ -15,7 +15,7 @@ import { reportOnboardingStep } from './onboarding-funnel.js';
  * drives in another has still only crossed each of these once.
  */
 const seen = { look: false, act: false, verdict: false, driven: false };
-/** A tool call the daemon just ran. Called from the dispatch chokepoint, which sees every one. */
+/** A successful page read. The dispatcher calls this after excluding refusals and pauses. */
 export function noteOnboardingFirst(toolName) {
     if (!seen.look && LOOK_TOOLS.has(toolName)) {
         seen.look = true;
@@ -29,7 +29,7 @@ export function noteOnboardingFirst(toolName) {
 /**
  * The first ACTION of this run, and the fact that this install has been driven at all.
  *
- * Called from the dispatch chokepoint's own action branch rather than matched on a tool name here.
+ * Called after the dispatcher observes a dispatched action, rather than on an attempted call.
  * The name test was `toolName === ReticleTool.ACT`, on the worry that `act_and_wait` would report
  * one call as two different firsts — and the worry was backwards: this server's instructions tell
  * every agent to PREFER `act_and_wait`, so the step measured the tool we ask agents not to use and

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/actions.mdx

@@ -5,7 +5,7 @@ description: Every action reticle_act and reticle_act_and_wait can perform, with
 icon: hand-pointer
 ---
 
-Every action Reticle can perform takes the same shape: a `ref` from [`reticle_look { action: "page" }`](/tools/snapshot) or [`reticle_look { action: "find" }`](/tools/query), an `action` name, and an optional `args` object. The same seventeen actions are available on [`reticle_act`](/tools/act), which proves nothing, and on [`reticle_act_and_wait`](/tools/act-and-wait), which returns a verdict.
+Every action Reticle can perform takes the same shape: a `ref` from [`reticle_look { action: "page" }`](/tools/snapshot) or [`reticle_look { action: "find" }`](/tools/query), an `action` name, and an optional `args` object. The same actions are available on [`reticle_act`](/tools/act), which proves nothing, and on [`reticle_act_and_wait`](/tools/act-and-wait), which returns a verdict.
 
 ```json
 { "ref": "e104", "action": "fill", "args": { "value": "reticle" } }
@@ -26,7 +26,6 @@ Every action Reticle can perform takes the same shape: a `ref` from [`reticle_lo
 | `scrollIntoView` | none |  |
 | `upload` | `{ content?, name?, type?, path? }` | Sets a file on `<input type="file">`. Inline bytes default to `"reticle test file"` / `"file.txt"` / `"text/plain"`. `path` reads a file from disk, scoped to the project root plus any opt-in directories listed in `.reticle.json` as `"uploadRoots": ["~/Downloads", "/Volumes/fixtures"]`. A refusal names every allowed root. |
 | `drag` | `{ toRef }` | Pointer-based drag (dnd-kit, react-beautiful-dnd) plus HTML5 DnD. `target` is an alias |
-| `webmcp` | `{ tool, params }` | Calls a `navigator.modelContext` tool, if the site exposes one |
 
 ### Arguments that are not actions
 

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/cloud.mdx

@@ -1,16 +1,18 @@
 ---
 title: reticle cloud commands
-description: Sign in, link a repository, and read runs and regressions from Reticle Cloud.
+description: Connect a project in one command, then read runs and regressions from Reticle Cloud.
 icon: cloud
 ---
 
-Ten subcommands bind this repository to Reticle Cloud so runs and flows land on a dashboard. They dispatch before the local parser, so `reticle login` is one tool, not a second binary.
+From your app directory, `reticle connect --project "My App"` wires the app, opens browser sign-in approval if needed, links the named cloud project, and syncs the local history already on this machine. Run the [installer](/quickstart) once on the machine first. The commands below remain available when you need to sign in or link separately.
 
 ```bash
-npx @reticlehq/server <login|logout|whoami|link|project|config|push|runs|regression|share>
+npx @reticlehq/server connect --project "My App"
 ```
 
-These are thin clients over the `/v1` API. The logic is server-side; these verbs surface it.
+Use `--url https://your-cloud-origin` for a self-hosted cloud. `connect` checks a saved sign-in against that exact host before reuse; if it has expired, the browser approval opens again. It mints or reuses a project-scoped key, so there is no key to paste. A newly wired app may have no run to sync yet: ask your agent to verify one flow and the linked daemon will sync the result. Run `reticle whoami` to check the binding and `reticle push` to send anything still pending.
+
+The other cloud commands are thin clients over the `/v1` API. Their logic is server-side.
 
 ## Where credentials live
 

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

@@ -13,13 +13,9 @@ npx @reticlehq/server <command>
 ```
 
 <Warning>
-  **Always invoke it as `npx @reticlehq/server <command>`.** The tables below name the commands as
-  `reticle <command>`, because `reticle` is the bin this package installs and that is what the CLI
-  prints about itself. It is **not** a package on npm: the bare name `reticle` belongs to an
-  unrelated author, so putting `npx` in front of it downloads and runs their code instead of ours.
-  Once
-  `@reticlehq/server` is a dependency of your project, `reticle <command>` works from an npm script
-  or with the bin on your PATH.
+  If you used the installer, run `reticle <command>`: it put that bin on your PATH. Otherwise use
+  `npx @reticlehq/server <command>`. Do not put `npx` before the bare `reticle` bin name: the npm
+  package with that name belongs to an unrelated author.
 </Warning>
 
 <Note>
@@ -30,9 +26,19 @@ npx @reticlehq/server <command>
 
 ## Setup and diagnosis
 
+### `reticle connect`
+
+From an app directory, one command wires an unwired app, proves a browser session, signs in through browser approval if needed, links the chosen cloud project, and syncs existing local history. A saved sign-in is reused only after the intended cloud host accepts it. Run `reticle init` instead for local-only verification.
+
+```bash
+npx @reticlehq/server connect --project "My App"
+```
+
+For a self-hosted cloud, add `--url <cloud origin>`. If the app was already wired, `connect` keeps its local setup and refreshes the cloud link. A fresh app has no run to send until you verify a flow with your agent.
+
 ### `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.4"
+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