@reticlehq/server 2.12.0 → 2.13.1

package/dist/version/version-nudge.d.ts

@@ -23,6 +23,20 @@ interface VersionSkewNudge {
 export declare function noteVersionSkew(pair: SkewPair, action: string): void;
 /** The next undelivered skew, once. */
 export declare function takeVersionSkew(): VersionSkewNudge | undefined;
+/**
+ * Splice pending skew onto a tool-error payload.
+ *
+ * Successful calls already carry `version_skew` via `runTool`. Thrown errors never reached that
+ * splice — they became a Playwright string plus `FEEDBACK_ASK`, so a caller debugs a CDP timeout
+ * instead of the mismatched pair that caused it (#618). When the error was unrecognized, the
+ * feedback ask is replaced: the skew IS the next move, and inviting a bug report about it is
+ * backwards. A recognized recovery is kept; the envelope still rides along.
+ */
+export declare function takeVersionSkewOnto(payload: {
+    error: string;
+    recovery?: string;
+    feedback?: string;
+}): Record<string, unknown>;
 /** Tests only — drop the module state so each case starts clean. */
 export declare function resetVersionSkew(): void;
 export {};

package/dist/version/version-nudge.js

@@ -11,6 +11,7 @@
  * result, then goes quiet until the skew CHANGES. Told, not nagged: a banner on every call is one an
  * agent learns to skip, and it would cost those tokens on every call for the rest of the session.
  */
+import { EnvelopeKey } from '../tools/tool-kit.js';
 /** Pending per pair — the SDK and the daemon are different upgrades and each is worth saying once. */
 const pending = new Map();
 /** The last message delivered for each pair, so the same skew is never repeated. */
@@ -33,6 +34,26 @@ export function takeVersionSkew() {
     }
     return undefined;
 }
+/**
+ * Splice pending skew onto a tool-error payload.
+ *
+ * Successful calls already carry `version_skew` via `runTool`. Thrown errors never reached that
+ * splice — they became a Playwright string plus `FEEDBACK_ASK`, so a caller debugs a CDP timeout
+ * instead of the mismatched pair that caused it (#618). When the error was unrecognized, the
+ * feedback ask is replaced: the skew IS the next move, and inviting a bug report about it is
+ * backwards. A recognized recovery is kept; the envelope still rides along.
+ */
+export function takeVersionSkewOnto(payload) {
+    const skew = takeVersionSkew();
+    if (skew === undefined)
+        return payload;
+    const { feedback, ...rest } = payload;
+    return {
+        ...rest,
+        ...(feedback !== undefined && rest.recovery === undefined ? { recovery: skew.action } : {}),
+        [EnvelopeKey.VERSION_SKEW]: skew,
+    };
+}
 /** Tests only — drop the module state so each case starts clean. */
 export function resetVersionSkew() {
     pending.clear();

package/dist/version/version-skew.d.ts

@@ -59,8 +59,43 @@ interface SelfIdentity {
  * inventing a warning would be as dishonest as staying silent about a real one.
  */
 export declare function describeSkew(peer: PeerIdentity, self: SelfIdentity): string | undefined;
-/** The fix line for a page whose SDK disagrees with this daemon. */
+/**
+ * The fix line for a page whose SDK disagrees with this daemon, with no project to read.
+ *
+ * Names the framework-neutral sensor and plain npm, because those are the answers that are never
+ * actively wrong. When a project directory IS available, `resolveSdkFix` / `sdkFixForDirectory`
+ * in sdk-fix.ts read the real packages and package manager — this used to hardcode
+ * `@reticlehq/react` and told Vue projects to install a React package (#618).
+ */
 export declare function sdkFix(daemonVersion: string): string;
-/** The fix line for another Reticle process that disagrees with the daemon it attached to. */
-export declare const DAEMON_FIX: string;
+/**
+ * The fix line for another Reticle process that disagrees with the daemon it attached to.
+ *
+ * Branches on DIRECTION, which the old unconditional `reticle stop` did not (#618). Restarting the
+ * daemon converges the pair only when the daemon is the OLDER half. When the daemon is newer — the
+ * common case, because the MCP registration is deliberately unpinned and so resolves fresh while a
+ * long-lived daemon does not — `reticle stop` starts another newer daemon and leaves the same two
+ * contract hashes with the roles unchanged. Nothing the agent can do converges that, so say so and
+ * ask for the one thing that does, exactly as the SDK branch already does when the page is stale.
+ *
+ * Both versions are named by ROLE, not by which side is calling: this is read from both ends — a
+ * CLI judging the daemon it attached to, and the daemon judging an agent that announced itself —
+ * and the advice depends on which piece is behind, not on who noticed.
+ */
+export declare function daemonFix(daemonVersion: string | undefined, agentVersion: string | undefined): string;
+/**
+ * Playwright wording when a CDP call cannot bind to the page.
+ *
+ * Under SDK/daemon version skew this text is a LIE: the page is still connected (DOM tools work),
+ * and the agent spends turns re-acquiring leases and asking a human to sign into a fresh profile
+ * (#688). Matched only so we can replace it with the skew sentence already on the session.
+ */
+export declare const PLAYWRIGHT_CLOSED_ERROR: RegExp;
+/** True when `error` is Playwright's closed-target class — not proof the tab is gone. */
+export declare function isPlaywrightClosedError(error: unknown): boolean;
+/**
+ * Replace a closed-target throw with the session's skew sentence when we already know the pair is
+ * mismatched. Undefined when there is no skew to name, or the throw is something else.
+ */
+export declare function rewriteClosedAsSkew(error: unknown, skew: string | undefined): Error | undefined;
 export {};

package/dist/version/version-skew.js

@@ -23,6 +23,7 @@
  * the wire changes and stays put when internals do. Versions still ride along, because they are what
  * a human acts on.
  */
+import { resolveSdkFix } from './sdk-fix.js';
 /** Which pair disagreed. Named so the nudge can report each independently. */
 export const SkewPair = {
     /** The SDK in the page vs this daemon. */
@@ -60,12 +61,87 @@ export function describeSkew(peer, self) {
         `(${peer.contract} vs ${self.contract}) — so this is a real mismatch, not a harmless patch ` +
         `difference. Tools will behave in ways neither side reports. ${peer.fix}`);
 }
-/** The fix line for a page whose SDK disagrees with this daemon. */
+/**
+ * The fix line for a page whose SDK disagrees with this daemon, with no project to read.
+ *
+ * Names the framework-neutral sensor and plain npm, because those are the answers that are never
+ * actively wrong. When a project directory IS available, `resolveSdkFix` / `sdkFixForDirectory`
+ * in sdk-fix.ts read the real packages and package manager — this used to hardcode
+ * `@reticlehq/react` and told Vue projects to install a React package (#618).
+ */
 export function sdkFix(daemonVersion) {
-    return (`Tell the human to install the matching SDK (\`npm i -D @reticlehq/react@${daemonVersion}\`) ` +
-        'or run `reticle update`, then restart their dev server so the page reloads with it.');
+    return resolveSdkFix(daemonVersion);
+}
+/**
+ * Compare two of our own version strings. Numeric dotted compare, prerelease tags ignored: both
+ * sides are Reticle package versions, so this never sees a range or build metadata. Undefined when
+ * either side does not parse, so the caller can decline to guess a direction.
+ */
+function compareVersions(a, b) {
+    const parts = (v) => {
+        const head = v.split('-')[0];
+        if (head === undefined)
+            return undefined;
+        const nums = head.split('.').map((n) => parseInt(n, 10));
+        return nums.some(isNaN) ? undefined : nums;
+    };
+    if (a === undefined)
+        return undefined;
+    const left = parts(a);
+    const right = parts(b);
+    if (left === undefined || right === undefined)
+        return undefined;
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (0 !== diff)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * The fix line for another Reticle process that disagrees with the daemon it attached to.
+ *
+ * Branches on DIRECTION, which the old unconditional `reticle stop` did not (#618). Restarting the
+ * daemon converges the pair only when the daemon is the OLDER half. When the daemon is newer — the
+ * common case, because the MCP registration is deliberately unpinned and so resolves fresh while a
+ * long-lived daemon does not — `reticle stop` starts another newer daemon and leaves the same two
+ * contract hashes with the roles unchanged. Nothing the agent can do converges that, so say so and
+ * ask for the one thing that does, exactly as the SDK branch already does when the page is stale.
+ *
+ * Both versions are named by ROLE, not by which side is calling: this is read from both ends — a
+ * CLI judging the daemon it attached to, and the daemon judging an agent that announced itself —
+ * and the advice depends on which piece is behind, not on who noticed.
+ */
+export function daemonFix(daemonVersion, agentVersion) {
+    const order = agentVersion === undefined ? undefined : compareVersions(daemonVersion, agentVersion);
+    if (order !== undefined && order > 0) {
+        return ('The daemon is NEWER than this process, so `reticle stop` will not converge them — it would ' +
+            'replace it with another newer daemon and leave the same mismatch. Tell the human to restart ' +
+            'the agent so it spawns a current MCP server (or update the package it spawns), then retry.');
+    }
+    return ('A daemon outlives the agents attached to it, so it keeps serving its OWN code until it restarts ' +
+        '— anything fixed in the newer package is simply absent. Run `reticle stop` and retry to replace ' +
+        'it (other agents on that daemon will need to reconnect).');
+}
+/**
+ * Playwright wording when a CDP call cannot bind to the page.
+ *
+ * Under SDK/daemon version skew this text is a LIE: the page is still connected (DOM tools work),
+ * and the agent spends turns re-acquiring leases and asking a human to sign into a fresh profile
+ * (#688). Matched only so we can replace it with the skew sentence already on the session.
+ */
+export const PLAYWRIGHT_CLOSED_ERROR = /target (?:page|context|browser) has been closed|browser has been closed|browser has disconnected/i;
+/** True when `error` is Playwright's closed-target class — not proof the tab is gone. */
+export function isPlaywrightClosedError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return PLAYWRIGHT_CLOSED_ERROR.test(message);
+}
+/**
+ * Replace a closed-target throw with the session's skew sentence when we already know the pair is
+ * mismatched. Undefined when there is no skew to name, or the throw is something else.
+ */
+export function rewriteClosedAsSkew(error, skew) {
+    if (skew === undefined || !isPlaywrightClosedError(error))
+        return undefined;
+    return new Error(skew);
 }
-/** The fix line for another Reticle process that disagrees with the daemon it attached to. */
-export const DAEMON_FIX = 'A daemon outlives the agents attached to it, so it keeps serving its OWN code until it restarts ' +
-    '— anything fixed in the newer package is simply absent. Run `reticle stop` and retry to replace ' +
-    'it (other agents on that daemon will need to reconnect).';

package/dist/visual/visual-store.d.ts

@@ -8,15 +8,15 @@ export declare class VisualStore {
     constructor(fs: FileSystemPort, root: string);
     /** The absolute baseline path for `name` (for echoing back to the agent). Guards the name so a
      *  crafted value can never echo a path outside .reticle/visual/ to a future caller that does IO. */
-    baselinePath(name: string): string;
+    baselinePath(name: string, runtime?: string): string;
     /** The absolute overlay-diff path for `name`. Same name guard as baselinePath. */
-    diffPath(name: string): string;
+    diffPath(name: string, runtime?: string): string;
     /** True iff a valid name and a baseline PNG exists on disk. */
-    hasBaseline(name: string): Promise<boolean>;
+    hasBaseline(name: string, runtime?: string): Promise<boolean>;
     /** Write a PNG baseline (auto-creating .reticle/visual/). Returns its path; throws on a bad name. */
-    saveBaseline(name: string, png: Uint8Array): Promise<string>;
+    saveBaseline(name: string, png: Uint8Array, runtime?: string): Promise<string>;
     /** Read a PNG baseline, or undefined if absent / invalid name (never throws on missing). */
-    readBaseline(name: string): Promise<Uint8Array | undefined>;
+    readBaseline(name: string, runtime?: string): Promise<Uint8Array | undefined>;
     /** Write the overlay diff PNG for `name` (auto-creating .reticle/visual/). Returns its path. */
-    saveDiff(name: string, png: Uint8Array): Promise<string>;
+    saveDiff(name: string, png: Uint8Array, runtime?: string): Promise<string>;
 }

package/dist/visual/visual-store.js

@@ -1,4 +1,4 @@
-import { reticleDirPaths, isValidFlowName, visualDiffPath, visualPath, } from '../project/reticle-dir.js';
+import { isValidFlowName, visualDiffPath, visualDir, visualPath } from '../project/reticle-dir.js';
 /**
  * On-disk PNG baselines + diffs under .reticle/visual/. Binary sibling of FlowStore — same
  * name guard (rejects path traversal before any join) and injected FileSystemPort, but bytes not text.
@@ -12,39 +12,40 @@ export class VisualStore {
     }
     /** The absolute baseline path for `name` (for echoing back to the agent). Guards the name so a
      *  crafted value can never echo a path outside .reticle/visual/ to a future caller that does IO. */
-    baselinePath(name) {
+    baselinePath(name, runtime) {
         if (!isValidFlowName(name))
             throw new Error(`invalid visual baseline name: ${name}`);
-        return visualPath(this.#root, name);
+        return visualPath(this.#root, name, runtime);
     }
     /** The absolute overlay-diff path for `name`. Same name guard as baselinePath. */
-    diffPath(name) {
+    diffPath(name, runtime) {
         if (!isValidFlowName(name))
             throw new Error(`invalid visual diff name: ${name}`);
-        return visualDiffPath(this.#root, name);
+        return visualDiffPath(this.#root, name, runtime);
     }
     /** True iff a valid name and a baseline PNG exists on disk. */
-    async hasBaseline(name) {
+    async hasBaseline(name, runtime) {
         if (!isValidFlowName(name))
             return false;
-        return this.#fs.exists(visualPath(this.#root, name));
+        return this.#fs.exists(visualPath(this.#root, name, runtime));
     }
     /** Write a PNG baseline (auto-creating .reticle/visual/). Returns its path; throws on a bad name. */
-    async saveBaseline(name, png) {
+    async saveBaseline(name, png, runtime) {
         if (!isValidFlowName(name))
             throw new Error(`invalid visual baseline name: ${name}`);
-        await this.#fs.mkdir(reticleDirPaths(this.#root).visual);
-        const path = visualPath(this.#root, name);
+        // The runtime's own directory, not the shared one — see visualDir.
+        await this.#fs.mkdir(visualDir(this.#root, runtime));
+        const path = visualPath(this.#root, name, runtime);
         await this.#fs.writeFileBytes(path, png);
         return path;
     }
     /** Read a PNG baseline, or undefined if absent / invalid name (never throws on missing). */
-    async readBaseline(name) {
-        if (!isValidFlowName(name) || !(await this.#fs.exists(visualPath(this.#root, name)))) {
+    async readBaseline(name, runtime) {
+        if (!isValidFlowName(name) || !(await this.#fs.exists(visualPath(this.#root, name, runtime)))) {
             return undefined;
         }
         try {
-            return await this.#fs.readFileBytes(visualPath(this.#root, name));
+            return await this.#fs.readFileBytes(visualPath(this.#root, name, runtime));
         }
         catch (error) {
             if (this.#fs.isNotFound(error))
@@ -53,11 +54,12 @@ export class VisualStore {
         }
     }
     /** Write the overlay diff PNG for `name` (auto-creating .reticle/visual/). Returns its path. */
-    async saveDiff(name, png) {
+    async saveDiff(name, png, runtime) {
         if (!isValidFlowName(name))
             throw new Error(`invalid visual baseline name: ${name}`);
-        await this.#fs.mkdir(reticleDirPaths(this.#root).visual);
-        const path = visualDiffPath(this.#root, name);
+        // Beside its baseline, or a diff lands in a directory the baseline is not in.
+        await this.#fs.mkdir(visualDir(this.#root, runtime));
+        const path = visualDiffPath(this.#root, name, runtime);
         await this.#fs.writeFileBytes(path, png);
         return path;
     }

package/dist/visual/visual-tools.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
-import { ReticleCommand, RETICLE_CAPTURE_FILE_PREFIX, VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason, } from '@reticlehq/core';
+import { AppRuntime, ReticleCommand, RETICLE_CAPTURE_FILE_PREFIX, VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
+import { ratioSchema } from '../tools/numeric-bounds.js';
 import { asNumber, asRecord, asString } from '../tools/tools-helpers.js';
 import { diffPng } from './visual-diff.js';
 import { VisualStore } from './visual-store.js';
@@ -148,19 +149,51 @@ function isCompletePng(bytes) {
  * `full-page-unsupported` — a viewport image returned as though it were the whole scroll height is a
  * baseline that says nothing about the content below the fold, and a later diff would call it green.
  */
+/**
+ * Which runtime this session is, for scoping a visual artifact.
+ *
+ * Undefined when the session cannot be resolved or its SDK never reported one — and undefined means
+ * the flat legacy path, so a baseline captured before any of this keeps matching.
+ */
+function runtimeOf(deps, sessionId) {
+    try {
+        return deps.sessions.resolve(sessionId).runtime;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function capture(deps, sessionId, args) {
     const provider = screenshotProvider(deps);
     if (provider !== undefined) {
         const session = deps.sessions.resolve(sessionId);
         const png = await provider.screenshot(session.url, await buildOpts(deps, sessionId, args));
+        // A driven browser renders the session's URL in a BROWSER — so the pixels are web even when the
+        // session named is a desktop window. Scoping those under the desktop runtime would corrupt that
+        // runtime's baseline with a picture of a different renderer.
         if (png !== undefined)
-            return { png };
+            return { png, runtime: AppRuntime.WEB };
     }
+    // The window's own backing store, via the Electron/Tauri adapter — the only route whose pixels
+    // really are the desktop app.
     const desktop = await desktopCapture(deps, sessionId, true === args['fullPage']);
     if (desktop.png !== undefined)
-        return { png: desktop.png };
+        return { png: desktop.png, runtime: runtimeOf(deps, sessionId) };
     if (desktop.reason !== undefined)
         return { reason: desktop.reason };
+    /*
+     * A LEASED page is a real browser page, so the pixels were always there — the visual tools simply
+     * had no route to them. Without this, `reticle_screenshot` answered "no provider" for every context
+     * an agent can actually acquire, which made visual regression impossible on exactly the isolated
+     * contexts the pool exists to hand out. Tried last: a CDP provider, when there is one, is driving
+     * the page the caller means, and a lease is the fallback rather than a competitor.
+     */
+    const leased = sessionId === undefined
+        ? undefined
+        : await deps.pool?.screenshotLease(sessionId, { fullPage: true === args['fullPage'] });
+    // A leased page is a real browser page, whatever the session is.
+    if (leased !== undefined)
+        return { png: leased, runtime: AppRuntime.WEB };
     return {
         reason: provider === undefined ? VisualReason.NO_PROVIDER : VisualReason.CAPTURE_FAILED,
     };
@@ -215,13 +248,16 @@ export const VISUAL_TOOLS = [
         },
         handler: async (deps, args) => {
             const sessionId = asString(args['sessionId']);
-            const { png, reason } = await capture(deps, sessionId, args);
+            const { png, reason, runtime } = await capture(deps, sessionId, args);
             if (png === undefined) {
                 return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
             }
             const name = asString(args['name']) ?? 'default';
             const store = new VisualStore(deps.fs, deps.reticleRoot);
-            const path = await store.saveBaseline(name, png);
+            // Scoped to the runtime that produced it: an Electron window, a Tauri webview and a browser
+            // tab do not render the same url the same way, and one shared baseline makes every
+            // cross-runtime diff wrong. See visualDir.
+            const path = await store.saveBaseline(name, png, runtime);
             return { ok: true, saved: true, name, path, bytes: png.length };
         },
     },
@@ -237,8 +273,10 @@ export const VISUAL_TOOLS = [
             ref: z.string().optional(),
             clip: rectShape.optional(),
             masks: z.array(rectShape).optional(),
-            maxRatio: z.number().optional(),
-            threshold: z.number().optional().describe('Pixel difference threshold (0–1). Default: 0.01.'),
+            maxRatio: ratioSchema.optional(),
+            threshold: ratioSchema
+                .optional()
+                .describe('Pixel difference threshold (0–1). Default: 0.01.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -255,14 +293,21 @@ export const VISUAL_TOOLS = [
         handler: async (deps, args) => {
             const baseline = asString(args['baseline']) ?? '';
             const store = new VisualStore(deps.fs, deps.reticleRoot);
-            const baselineBytes = await store.readBaseline(baseline);
-            if (baselineBytes === undefined)
-                return { ok: false, reason: VisualReason.BASELINE_MISSING };
+            // Capture FIRST, then fetch the baseline for the runtime that produced these pixels. Reading it
+            // by the session's runtime looked equivalent and is not: the route decides the renderer, so a
+            // desktop session captured through a driven browser must be compared against the WEB baseline,
+            // not the desktop one. Comparing across renderers is a confident wrong diff in one direction
+            // and a silently overwritten baseline in the other.
             const sessionId = asString(args['sessionId']);
-            const { png: current, reason } = await capture(deps, sessionId, args);
+            const { png: current, reason, runtime } = await capture(deps, sessionId, args);
             if (current === undefined) {
                 return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
             }
+            // A baseline from another runtime is not missing by accident — it is a different rendering, and
+            // "no baseline for this one" is the honest answer.
+            const baselineBytes = await store.readBaseline(baseline, runtime);
+            if (baselineBytes === undefined)
+                return { ok: false, reason: VisualReason.BASELINE_MISSING };
             const masks = rectsFrom(args['masks']);
             const threshold = asNumber(args['threshold']);
             const maxRatio = asNumber(args['maxRatio']);
@@ -276,7 +321,7 @@ export const VISUAL_TOOLS = [
             if (diffBytes === undefined) {
                 return { ok: false, ...verdict, reason: VisualReason.DIMENSION_MISMATCH };
             }
-            const diffPath = await store.saveDiff(baseline, diffBytes);
+            const diffPath = await store.saveDiff(baseline, diffBytes, runtime);
             return { ok: true, ...verdict, diffPath };
         },
     },

package/docs/cli/doctor.mdx

@@ -51,6 +51,7 @@ When nothing has connected, the `sessions` line fails and the daemon's own diagn
 | `chromium` | Whether the exact Chromium revision the bundled Playwright wants is on disk. The most common silent failure |
 | `daemon` | Whether the port holds a Reticle daemon, a foreign process (named where possible), or nothing. Adds a `version` line when the daemon's version or contract fingerprint disagrees with the CLI's |
 | `sessions` | Whether any page has actually connected. Zero is a FAILING check rather than a neutral note, because it is the state the setup most often stalls in: wired correctly, daemon up, nothing dialled in. When it is zero the daemon's own no-session diagnosis prints below the checklist |
+| `agent link` | Whether an MCP client has listed Reticle's tools on this port **and actually called one**. Every other row here checks a component; this one checks the hop between your agent and the daemon. It is possible for the SDK to be injected, a session to be live, and your client to show every tool enabled, while no request has ever crossed from the agent. That state passes every other check and is the one people lose hours to |
 | `bridge port` | The port your app must dial, spelled out because mixing it up with the dev server port is the most common setup failure |
 | `port check` | Only when your project's configured port disagrees with the one the daemon is on. Prints the mismatch rather than leaving you to spot it across two lines |
 | `sibling` | Only when a well-known Reticle port other than this daemon's has a listener. An observation, not a diagnosis: that listener may or may not be related |

package/docs/cli/serve.mdx

@@ -21,8 +21,10 @@ Most people never type this. Your agent runs [`reticle mcp`](/cli/mcp), which st
 | `--headless` | boolean | `true` for `serve` | Hide the browser |
 | `--headed` | boolean | `false` | Show it. `serve` owns the pooled browser behind leases, which is batch work, so it hides by default |
 | `--http` | boolean | `false` | Also expose the HTTP verify endpoint |
-| `--http-port N` | number | unset | Port for that endpoint |
-| `--http-token T` | string | unset | Bearer token the endpoint requires |
+| `--http-port N` | number | unset (`7331`) | Port for that endpoint. Requires `--http`. |
+| `--http-token T` | string | unset | Bearer token the endpoint requires. Requires `--http`. |
+
+The HTTP flags are honoured or refused, never silently dropped: against an already-running daemon that does not serve the requested verify port, `serve --http` exits 1 and names both ports. A running daemon keeps the flags it was started with, so `reticle stop`, then serve again. A verify port that cannot be bound fails the daemon start with a `reticle_daemon_start_failed` line naming that port.
 
 ## What it prints
 

package/docs/cli.mdx

@@ -4,7 +4,7 @@ description: Every reticle command. What it does, what it prints, and what it ex
 icon: terminal
 ---
 
-The `reticle` CLI wires Reticle into a project (`init`), runs and diagnoses the daemon your app connects to (`serve`, `status`, `doctor`, `kill`, `restart`), and gates a build on verification in CI (`verify`, `affected`, `gate`). This page is the index; each command has its own page with real captured output and measured exit codes.
+The `reticle` CLI installs Reticle into a project and proves the install works (`init`), runs and diagnoses the daemon your app connects to (`serve`, `status`, `doctor`, `kill`, `restart`), and gates a build on verification in CI (`verify`, `affected`, `gate`). This page is the index; each command has its own page with real captured output and measured exit codes.
 
 The CLI is mostly for you, not your agent. Your agent talks MCP; you use these to set things up, work out why nothing connected, and wire verification into CI.
 
@@ -32,12 +32,16 @@ npx @reticlehq/server <command>
 
 ### `reticle init`
 
-Wires Reticle into the project in the current directory.
+Wires Reticle into the project in the current directory, then boots the app, proves a session connected and drives one flow to a verdict. It exits non-zero if no verdict was produced, and prints what is left to do.
 
 ```
-reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
+reticle init  [--flow "<what to drive>"] [--env KEY=VALUE]... [--app <dir>] [--license <key>]
+              [--json] [--files-only] [--no-open] [--no-drive] [--dry-run]
+              [--port N] [--no-mcp] [--no-install] [--timeout S] [--drive-model M]
 ```
 
+`--flow`, `--env` and `--app` are the answers the command cannot work out for itself: which journey proves what you care about, what the app needs to reach a usable state, and which app in a monorepo. `--files-only` is what `init` did before it learned to boot the app: it still registers the MCP server and pre-approves Reticle's tools, so it doubles as the upgrade path for an existing install.
+
 <Card title="Full walkthrough with real output" icon="wand-magic-sparkles" href="/install-agentic">
   What it writes, and how to read its four status marks.
 </Card>

package/docs/desktop.mdx

@@ -214,7 +214,7 @@ Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-por
 
 ```toml
 [dependencies]
-reticle-tauri = "2.12"
+reticle-tauri = "2.13"
 ```
 
 ```rust

package/docs/docs.json

@@ -32,7 +32,7 @@
   "navigation": {
     "versions": [
       {
-        "version": "2.12.0",
+        "version": "2.13.1",
         "default": true,
         "tabs": [
           {

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 `npx @reticlehq/server init` in your project root, restart your dev server, restart your coding agent, then open your app in a browser and ask the agent to drive a flow.** 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 with Reticle: run `npx @reticlehq/server init --flow "<the journey worth proving>"` in your project root.** That one command wires your project, starts your dev server, opens the app, waits for it to connect, and drives that flow to a verdict. You do not restart anything and you do not drive it yourself. 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.
 
 > **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.
 >
@@ -76,7 +76,19 @@ It detects your framework, package manager, and React version, then:
 
 The bridge + MCP server is a single process that serves all your projects, so it's registered at **user scope**, not in a per-project `.mcp.json`. Only the SDK (the `reticle()` plugin / connect call) is added per project.
 
-Re-running is safe (already-registered/already-patched steps are skipped). Preview without writing via `npx @reticlehq/server init --dry-run`. Flags: `--dry-run`, `--port N`, `--no-mcp`, `--no-install`, `--app <dir>`.
+Re-running is safe: already-registered and already-patched steps are skipped, and on a wired project it goes straight to proving the app still works. Preview without writing via `npx @reticlehq/server init --dry-run`.
+
+`init` does not stop at writing files. It starts your dev server (restarting one whose bundle predates the config edit), opens the app, waits for a session to connect from inside it, and drives one flow to a verdict, which it saves so later checks are a single call with no model involved. It exits non-zero if no verdict was produced and prints what is left to do.
+
+Three flags carry what the command cannot work out for itself:
+
+| Flag | What only you know |
+| --- | --- |
+| `--flow "<what>"` | Which journey proves the thing you care about. It can list the buttons on your page; it cannot know that checkout matters and the theme toggle does not. |
+| `--env KEY=VALUE` | What your app needs to reach a usable state: the key from `.env.example`, the mock backend, the variable that skips an auth wall. Repeatable. |
+| `--app <dir>` | Which app in a monorepo. It finds the servable ones; only you know which you are working in. |
+
+The rest are dials: `--license <key>` (writes it to `.env` and keeps `.env` out of git), `--json` (one object for an agent to read), `--files-only` (write, register, pre-approve, and stop, which is what `init` did before it learned to boot the app, and what an existing install re-runs to pick up new wiring), `--no-open`, `--no-drive`, `--dry-run`, `--port N`, `--no-mcp`, `--no-install`.
 
 Then restart your dev server and skip to [Step 4](#step-4-run-it-and-verify-the-connection). The manual steps below explain what `init` sets up, if you prefer to wire it yourself.
 
@@ -310,6 +322,8 @@ export default defineConfig({
 
 ## Step 4: Run it and verify the connection
 
+> `reticle init` does this for you: it starts the dev server, opens the app and waits for the session. Read on only if you are wiring by hand, or if it told you it could not.
+
 1. Start your app's dev server as usual (`npm run dev`).
 2. Open it in the browser (the SDK connects when the page loads).
 3. In your agent, ask it to confirm the connection:
@@ -328,6 +342,8 @@ If the list is empty, see [Troubleshooting](#troubleshooting).
 
 ## Step 5: Your first verification
 
+> `reticle init --flow "<what>"` drives this for you and saves the flow. This section is what it does, for when you want to do it yourself.
+
 Now just talk to your agent in plain language. For example:
 
 > "Add a 'Refresh' button to the header that re-fetches the dashboard data, then use Reticle to verify clicking it fires `GET /api/dashboard` and shows no console errors."
@@ -490,7 +506,7 @@ pnpm add @reticlehq/next
 
 ### What exactly does `reticle init` change in my project?
 
-Four things, and none of them are mysterious: a `.reticle.json` project config, your build config (the `reticle()` Vite plugin, or `withReticle` in `next.config`), a dev-only capabilities file at `src/reticle-dev.ts` (or `app/reticle-dev.tsx` on Next.js), and your agent's rule files. It also registers the MCP server globally, which is a once-per-machine step rather than a per-project one. Run `npx @reticlehq/server init --dry-run` first to see the exact plan before anything is written.
+Four files, and none of them are mysterious: a `.reticle.json` project config, your build config (the `reticle()` Vite plugin, or `withReticle` in `next.config`), a dev-only capabilities file at `src/reticle-dev.ts` (or `app/reticle-dev.tsx` on Next.js), and your agent's rule files. It then starts your dev server, opens the app and drives one flow, none of which changes your source: the dev server is left running for you afterwards, and the only file the drive may edit is the capabilities file, and only when your app registers none. It also registers the MCP server globally, which is a once-per-machine step rather than a per-project one. Run `npx @reticlehq/server init --dry-run` first to see the exact plan before anything is written.
 
 ### Do I have to re-register the MCP server for every project?
 

package/docs/index.mdx

@@ -14,7 +14,7 @@ It answers the only question that matters: did the change actually work? On Reac
 
 ## Install it: paste this into your coding agent
 
-You do not install Reticle by hand. Copy the block below into Claude Code, Cursor, Copilot, Codex, Windsurf, OpenCode, or any MCP agent, and let the agent wire its own workspace. It ends with the only definition of "installed" that counts: one real flow driven, one real verdict returned.
+You do not install Reticle by hand, and neither does your agent: it runs one command that does the whole thing. Copy the block below into Claude Code, Cursor, Copilot, Codex, Windsurf, OpenCode, or any MCP agent, and let it wire its own workspace. It ends with the only definition of "installed" that counts: one real flow driven, one real verdict returned.
 
 ```text
 Reticle is the proof layer for AI coding agents. It runs a dev-only SDK inside my
@@ -30,12 +30,15 @@ silent 500.
 
 Install it now:
 
-  RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server@latest init
+  RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server@latest init \
+    --flow "<pick the journey that matters in my app and name it here>"
 
-Then follow https://docs.reticle.sh/install-agentic.md and, if anything needs a
-manual edit, https://docs.reticle.sh/install-manual.md. Do not stop until you have
-driven one real flow in my app and produced a verdict. That, not a config file, is
-what "installed" means.
+That one command wires the project, starts the dev server, opens the app, waits
+for it to connect and drives that flow to a verdict. 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 a verdict exists, and that, not a config file, is what
+"installed" means. 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.
 ```