@reticlehq/server 2.2.0 → 2.3.0

package/dist/cli-parse.js

@@ -5,10 +5,11 @@
  * imports are unchanged.
  */
 export const CLI_USAGE = `usage:
-  reticle init  [--yes] [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Reticle into the project in this directory)
+  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Reticle into the project in this directory)
   reticle serve [--port N] [--drive <url>] [--headed] [--http] [--http-port N] [--http-token T]
   reticle stop  [--port N] [--quiet]
   reticle status [--port N]
+  reticle doctor [--port N]                            (diagnose setup: Chromium, daemon, port — one command)
   reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)
   reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
   reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
@@ -18,7 +19,20 @@ export const CLI_USAGE = `usage:
   reticle mcp   [--port N] [--drive <url>] [--headed]  (MCP stdio proxy — auto-starts daemon if needed)
   reticle update                                       (install the latest server version and restart)
   reticle rollback                                     (restore the previous server version and restart)
-  reticle license                                      (show enterprise license status: active | eval | missing)`;
+  reticle license                                      (show enterprise license status: active | eval | missing)
+  reticle telemetry [status|enable|disable]            (anonymous usage metrics — status shows what's sent + the policy)
+  reticle feedback [--rating 1-5] [--bug] "message"    (tell us what worked and what didn't — prints exactly what it sends)
+  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]
+                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)
+
+Cloud (link this project to Reticle Cloud — runs/flows recorded on the dashboard):
+  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)
+  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)
+  reticle whoami                                        (who am I signed in as, and is this repo attached?)
+  reticle project <ls|create <name>>                   (list or create cloud projects)
+  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
+  reticle push                                          (send local run artifacts to the dashboard)
+  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)`;
 const INIT_COMMAND = 'init';
 const SERVE_COMMAND = 'serve';
 const STOP_COMMAND = 'stop';
@@ -27,6 +41,7 @@ const OPEN_COMMAND = 'open';
 const DRIVE_COMMAND = 'drive';
 const VERIFY_COMMAND = 'verify';
 const AFFECTED_COMMAND = 'affected';
+const HUNT_COMMAND = 'hunt';
 const CAPSULES_COMMAND = 'capsules';
 const GATE_COMMAND = 'gate';
 const WATCH_COMMAND = 'watch';
@@ -35,7 +50,75 @@ const ROLLBACK_COMMAND = 'rollback';
 const MCP_COMMAND = 'mcp';
 const LICENSE_COMMAND = 'license';
 const VERSION_COMMAND = 'version';
+const TELEMETRY_COMMAND = 'telemetry';
+const FEEDBACK_COMMAND = 'feedback';
+const IDENTIFY_COMMAND = 'identify';
+export const COMPANY_FLAG = '--company';
+export const EMAIL_FLAG = '--email';
+export const CONTEXT_FLAG = '--context';
+export const FORGET_FLAG = '--forget';
+/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
+export const RATING_FLAG = '--rating';
+export const BUG_FLAG = '--bug';
+/** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
+export const TelemetryAction = {
+    STATUS: 'status',
+    ENABLE: 'enable',
+    DISABLE: 'disable',
+};
 export const DAEMON_INNER_COMMAND = '_daemon';
+/**
+ * Every subcommand a person can type, as one closed vocabulary. Telemetry reports which one ran, and
+ * this is what keeps that property low-cardinality and non-identifying: an argument we do not
+ * recognize reports as `unknown` rather than being echoed, so a typo — which may be a path, a URL, or
+ * a flow name — can never reach the wire just because someone misspelled `status`.
+ *
+ * Lives here rather than in the telemetry module because this is where the command names are already
+ * defined; a second list somewhere else would drift the first time a command is added.
+ */
+export const UNKNOWN_COMMAND = 'unknown';
+const KNOWN_COMMANDS = new Set([
+    INIT_COMMAND,
+    SERVE_COMMAND,
+    STOP_COMMAND,
+    STATUS_COMMAND,
+    OPEN_COMMAND,
+    DRIVE_COMMAND,
+    VERIFY_COMMAND,
+    AFFECTED_COMMAND,
+    HUNT_COMMAND,
+    CAPSULES_COMMAND,
+    GATE_COMMAND,
+    WATCH_COMMAND,
+    UPDATE_COMMAND,
+    ROLLBACK_COMMAND,
+    MCP_COMMAND,
+    LICENSE_COMMAND,
+    VERSION_COMMAND,
+    TELEMETRY_COMMAND,
+    FEEDBACK_COMMAND,
+    IDENTIFY_COMMAND,
+    DAEMON_INNER_COMMAND,
+    // Cloud subcommands dispatch before the local parser but are still commands a human ran.
+    'login',
+    'logout',
+    'whoami',
+    'link',
+    'project',
+    'config',
+    'push',
+    'runs',
+    'regression',
+    'share',
+    'doctor',
+    'help',
+]);
+/** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
+export function knownCommand(arg) {
+    if (arg === undefined || arg === '')
+        return 'help';
+    return KNOWN_COMMANDS.has(arg) ? arg : UNKNOWN_COMMAND;
+}
 export const HEADED_FLAG = '--headed';
 export const PORT_FLAG = '--port';
 export const DRIVE_FLAG = '--drive';
@@ -261,6 +344,10 @@ export function parseCliArgs(argv, defaultPort) {
     // troubleshooting docs lean on to confirm which npx-resolved build is actually executing.
     if (cmd === VERSION_COMMAND || cmd === '--version' || cmd === '-v')
         return { kind: 'version' };
+    // `help` (and the conventional -h/--help) print usage to stdout and exit 0 — the universal first move
+    // for a new user, which otherwise fell through to a JSON error with exit 1.
+    if (cmd === 'help' || cmd === '--help' || cmd === '-h')
+        return { kind: 'help' };
     switch (cmd) {
         case INIT_COMMAND: {
             const r = parseInitFlags(rest);
@@ -291,8 +378,57 @@ export function parseCliArgs(argv, defaultPort) {
             const port = parsePortFlag(rest, defaultPort);
             return { kind: 'status', port };
         }
+        case 'doctor': {
+            const port = parsePortFlag(rest, defaultPort);
+            return { kind: 'doctor', port };
+        }
         case LICENSE_COMMAND:
             return { kind: 'license' };
+        case TELEMETRY_COMMAND: {
+            const action = rest[0] ?? TelemetryAction.STATUS;
+            if (action !== TelemetryAction.STATUS &&
+                action !== TelemetryAction.ENABLE &&
+                action !== TelemetryAction.DISABLE) {
+                return { kind: 'error', message: `unknown telemetry action: ${action}` };
+            }
+            return { kind: 'telemetry', action };
+        }
+        case IDENTIFY_COMMAND: {
+            const flag = (name) => {
+                const at = rest.indexOf(name);
+                return at === -1 ? undefined : rest[at + 1];
+            };
+            const context = flag(CONTEXT_FLAG);
+            const company = flag(COMPANY_FLAG);
+            const email = flag(EMAIL_FLAG);
+            return {
+                kind: 'identify',
+                ...(context !== undefined ? { context } : {}),
+                ...(company !== undefined ? { company } : {}),
+                ...(email !== undefined ? { email } : {}),
+                forget: rest.includes(FORGET_FLAG),
+            };
+        }
+        case FEEDBACK_COMMAND: {
+            const ratingAt = rest.indexOf(RATING_FLAG);
+            const rating = ratingAt === -1 ? undefined : Number(rest[ratingAt + 1]);
+            if (rating !== undefined && (!Number.isInteger(rating) || rating < 1 || rating > 5)) {
+                return { kind: 'error', message: `${RATING_FLAG} takes a whole number from 1 to 5` };
+            }
+            // Everything that is not a flag or the rating's value is the message. Quoting is the user's
+            // job for shell reasons, but joining the remainder means an unquoted sentence still works.
+            const consumed = new Set(ratingAt === -1 ? [] : [ratingAt, ratingAt + 1]);
+            const text = rest
+                .filter((arg, i) => !consumed.has(i) && !arg.startsWith('--'))
+                .join(' ')
+                .trim();
+            return {
+                kind: 'feedback',
+                text,
+                ...(rating !== undefined ? { rating } : {}),
+                bug: rest.includes(BUG_FLAG),
+            };
+        }
         case OPEN_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
             // The first non-flag arg is the url (optional — omitting reuses a connected tab).
@@ -333,6 +469,12 @@ export function parseCliArgs(argv, defaultPort) {
         }
         case CAPSULES_COMMAND:
             return { kind: 'capsules' };
+        case HUNT_COMMAND: {
+            const dir = rest.find((a) => !a.startsWith('-'));
+            return dir === undefined
+                ? { kind: 'error', message: 'usage: reticle hunt <dir-of-crawl-reports>' }
+                : { kind: 'hunt', dir };
+        }
         case AFFECTED_COMMAND: {
             const t = parseTargetArgs(rest);
             if (t.files.length === 0 && t.since === undefined) {
@@ -368,11 +510,13 @@ export function parseCliArgs(argv, defaultPort) {
                 kind: 'mcp',
                 port: r.port,
                 headless: r.headless,
+                http: r.http,
                 ...(r.driveUrl !== undefined ? { driveUrl: r.driveUrl } : {}),
+                ...(r.httpPort !== undefined ? { httpPort: r.httpPort } : {}),
+                ...(r.httpToken !== undefined ? { httpToken: r.httpToken } : {}),
             };
         }
         default:
             return { kind: 'error', message: CLI_USAGE };
     }
 }
-//# sourceMappingURL=cli-parse.js.map

package/dist/cli-port.d.ts

@@ -29,4 +29,3 @@ export declare function readJournalEnabled(cwd: string, env: string | undefined)
  * Pass `portFlag` when the user explicitly supplied --port; pass `undefined` to fall through.
  */
 export declare function resolvePort(portFlag: number | undefined, envPort: number | undefined, projectPort: number | undefined, defaultPort: number): number;
-//# sourceMappingURL=cli-port.d.ts.map

package/dist/cli-port.js

@@ -80,4 +80,3 @@ export function readJournalEnabled(cwd, env) {
 export function resolvePort(portFlag, envPort, projectPort, defaultPort) {
     return portFlag ?? envPort ?? projectPort ?? defaultPort;
 }
-//# sourceMappingURL=cli-port.js.map

package/dist/cli-verify.d.ts

@@ -41,6 +41,7 @@ export declare function handleVerify(parsed: {
     headless: boolean;
     timeoutMs?: number;
     storageState?: string;
+    /** Bridge port — parseCliArgs already resolves --port / RETICLE_PORT / .reticle.json into this. */
+    port?: number;
 }): void;
 export {};
-//# sourceMappingURL=cli-verify.d.ts.map

package/dist/cli-verify.js

@@ -13,6 +13,7 @@ import { join, basename } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { RETICLE_DEFAULT_PORT, ReticleEnv, bridgeWsUrl, isLoopbackHostname, ReticleDir, RunAgentKind, RunFramework, RunProfile, RunTrigger, VerdictStatus, } from '@reticlehq/core';
 import { start } from './index.js';
+import { resolveCloudConfig, syncRunToCloud, SyncOutcome } from './cloud/cloud-sync.js';
 import { ReticleRunner } from './runs/reticle-runner.js';
 import { createRunnerPort } from './runs/runner-port.js';
 import { RunStore } from './runs/run-store.js';
@@ -33,7 +34,8 @@ const MSG_NO_SESSION = 'No app connected — Reticle drove the URL but no @retic
     '  Make sure the SDK is in the build and reticle.connect() runs on the preview page' +
     ' (for a non-localhost preview: allowNonLocalhost + a pairing token).';
 const MSG_NO_FLOWS = 'No saved flows to verify (.reticle/flows is empty) — refusing to report a pass for verifying nothing.\n' +
-    '  Record a flow first (reticle_record_start → act → reticle_flow_save), then re-run verify.';
+    '  Flows are recorded interactively by an agent (reticle_record{action:"start"} → act → reticle_flow_save via the\n' +
+    '  MCP tools), then committed to .reticle/flows/. In CI, check those files in and re-run `reticle verify`.';
 const MSG_VERIFY_PREFIX = 'verify failed: ';
 function errMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -67,6 +69,7 @@ export async function runVerify(args, ports) {
             return;
         }
         const run = await conn.verify();
+        await pushRunToCloud(run, ports); // best-effort; opt-in; never changes the verdict or exit code
         ports.out(renderRunReport(run));
         ports.exit(run.verdict.status === VerdictStatus.PASS ? EXIT_PASS : EXIT_FAIL);
     }
@@ -78,6 +81,24 @@ export async function runVerify(args, ports) {
         await conn.close().catch(() => undefined);
     }
 }
+/**
+ * Best-effort push of a finished run to the cloud dashboard. Opt-in: only fires when the user has set
+ * RETICLE_CLOUD_URL + RETICLE_CLOUD_KEY (the "shifted to server" step). Absent → no-op, nothing leaves the
+ * machine (the no-phone-home default). A push failure NEVER changes the verdict or exit code — the run is
+ * already reported locally; the cloud copy is an enhancement.
+ */
+async function pushRunToCloud(run, ports) {
+    const config = resolveCloudConfig(process.env);
+    if (config === null)
+        return;
+    const result = await syncRunToCloud(run, config, (url, init) => fetch(url, init));
+    if (result.outcome === SyncOutcome.SYNCED) {
+        ports.out(`↑ run ${run.runId} recorded on the Reticle Cloud dashboard`);
+    }
+    else {
+        ports.fail(`cloud run sync failed (${result.status ?? result.error ?? 'error'}); run kept locally`);
+    }
+}
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -127,7 +148,7 @@ async function openLiveConnection(opts) {
     // `reticle verify` boots its OWN daemon. Hardcoding the default port meant it crashed with EADDRINUSE
     // on any machine already running a daemon — i.e. every developer machine — so honour RETICLE_PORT.
     const envPort = Number(process.env[ReticleEnv.PORT]);
-    const port = Number.isFinite(envPort) && envPort > 0 ? envPort : RETICLE_DEFAULT_PORT;
+    const port = Number.isFinite(envPort) && envPort > 0 ? envPort : opts.port;
     const { origin, loopback } = urlParts(opts.url);
     const pairing = loopback
         ? {}
@@ -189,6 +210,7 @@ export function handleVerify(parsed) {
             reticleRoot,
             projectName,
             now,
+            port: parsed.port ?? RETICLE_DEFAULT_PORT,
             ...(parsed.storageState !== undefined ? { storageState: parsed.storageState } : {}),
         }),
         out: (line) => process.stdout.write(`${line}\n`),
@@ -197,4 +219,3 @@ export function handleVerify(parsed) {
     };
     void runVerify({ url: parsed.url, timeoutMs: parsed.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS }, ports);
 }
-//# sourceMappingURL=cli-verify.js.map

package/dist/cli.d.ts

@@ -1,6 +1,4 @@
 #!/usr/bin/env node
-import { parseCliArgs } from './cli-parse.js';
-export { parseCliArgs };
-export { CLI_USAGE } from './cli-parse.js';
+import { parseCliArgs, CLI_USAGE } from './cli-parse.js';
+export { parseCliArgs, CLI_USAGE };
 export type { CliResult } from './cli-parse.js';
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -4,11 +4,13 @@ import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv } from '@reticlehq/core';
+import { loadDotEnv } from './telemetry/dev-repo.js';
 import { createNodeFileSystem } from './project/fs-port.js';
 import { affectedSavedFlows } from './flows/flow-sources.js';
 import { checkForUpdate } from './update/update-checker.js';
 import { applyUpdate, rollback } from './update/updater.js';
 import { start, startDaemon } from './index.js';
+import { isCloudCommand, runCloudCommand } from './cloud-cli.js';
 import { SERVER_VERSION } from './server-version.js';
 import { log } from './log.js';
 import { readPid, isAlive, isRunning, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon.js';
@@ -17,14 +19,18 @@ import { installDaemonResilience } from './daemon-resilience.js';
 import { IdleShutdown, resolveIdleShutdownMs } from './idle-shutdown.js';
 import { fetchStatus, summarizeStatus, decideOpen, openInBrowser } from './cli-launch.js';
 import { handleVerify } from './cli-verify.js';
+import { summarizeHunt } from './hunt/hunt-report.js';
 import { runInit } from './init/run.js';
+import { handleDoctor } from './cli-doctor.js';
 import { buildNodeIo } from './init/node-io.js';
 import { describeLicense } from './license/license.js';
 import { readProjectPort, readProjectId } from './cli-port.js';
-import { DAEMON_INNER_COMMAND, PORT_FLAG, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, parseCliArgs, } from './cli-parse.js';
+import { DAEMON_INNER_COMMAND, PORT_FLAG, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, parseCliArgs, CLI_USAGE, } from './cli-parse.js';
+import { handleFeedback, handleIdentify, handleTelemetry } from './telemetry/feedback-cli.js';
+import { installDaemonTelemetry } from './telemetry/daemon-telemetry.js';
+import { reportCliRun } from './telemetry/cli-telemetry.js';
 // Re-exported so existing imports (and the CLI tests) keep resolving from './cli.js'.
-export { parseCliArgs };
-export { CLI_USAGE } from './cli-parse.js';
+export { parseCliArgs, CLI_USAGE };
 function handleInit(parsed) {
     const cwd = process.cwd();
     const result = runInit({ cwd, port: parsed.port, mcp: parsed.mcp, dryRun: parsed.dryRun, install: parsed.install }, buildNodeIo(cwd));
@@ -99,11 +105,11 @@ function handleStatus(port) {
         log('reticle_status', { port, running: true, pid, ...summarizeStatus(payload) });
     });
 }
-/** `reticle license` — show enterprise activation resolved from the environment (offline; nothing leaves). */
 /** Print the running package version (resolved once in server-version.ts). */
 function handleVersion() {
     log('reticle_version', { version: SERVER_VERSION });
 }
+/** `reticle license` — show enterprise activation resolved from the environment (offline; nothing leaves). */
 function handleLicense() {
     log('reticle_license', { ...describeLicense(Date.now()) });
 }
@@ -130,6 +136,42 @@ async function handleAffected(files, since) {
         });
     }
 }
+/**
+ * `reticle hunt <dir>` — aggregate crawl reports from many checkouts into one number.
+ *
+ * Detection already exists (`reticle_crawl`). This is the arithmetic that turns a pile of runs into
+ * the claim worth making: over N already-merged, already-green changes, how many carried a candidate
+ * false green? No control arm is needed, because those changes SHIPPED — the counterfactual is
+ * already established, which is what makes this the cheapest credible evidence available.
+ *
+ * Each file in <dir> is one crawl result. Producing them is a shell loop over a commit range:
+ * check out, boot the app, `reticle_crawl`, write the JSON here.
+ */
+async function handleHunt(dir) {
+    try {
+        const fs = createNodeFileSystem();
+        const names = await fs.readdir(dir);
+        const runs = [];
+        for (const name of names.filter((n) => n.endsWith('.json'))) {
+            const raw = await fs.readFile(join(dir, name));
+            if (raw === undefined)
+                continue;
+            const parsed = JSON.parse(raw);
+            const report = parsed;
+            runs.push({
+                label: report.label ?? name.replace(/\.json$/, ''),
+                anomalies: report.anomalies ?? [],
+                ...(report.stepsRun === undefined ? {} : { stepsRun: report.stepsRun }),
+            });
+        }
+        log('reticle_hunt', { ...summarizeHunt(runs) });
+    }
+    catch (error) {
+        log('reticle_hunt_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
 /** `reticle update` — install the latest server version and restart (moved off the MCP surface). */
 async function handleUpdate() {
     try {
@@ -188,7 +230,11 @@ function handleOpen(requestedPort, url) {
         const { sessions } = summarizeStatus(await fetchStatus(port));
         const decision = decideOpen(sessions, url);
         if (decision.action === 'need-url') {
-            log('reticle_open', { port, error: 'no app connected — pass a url: reticle open <url>' });
+            log('reticle_open', {
+                port,
+                error: 'no app connected — pass a url: reticle open <url>. Desktop app (Electron/Tauri)? ' +
+                    'There is no url to open: start it as you normally would and it connects to this bridge itself.',
+            });
             return;
         }
         if (decision.action === 'reuse') {
@@ -220,6 +266,9 @@ function handleDaemonInner(parsed) {
     startDaemon(options)
         .then((server) => {
         log('reticle_daemon_ready', { port: parsed.port, pid: process.pid });
+        // Daemon lifecycle telemetry: started, a one-shot project profile, the periodic counter flush,
+        // and the rich summary on shutdown. All of it lives in one module — see daemon-telemetry.ts.
+        const daemonTelemetry = installDaemonTelemetry(process.cwd());
         // Publish to the discovery registry so a build plugin can find this daemon by projectId — no
         // hand-reconciled port. Written from the child (only it knows its cwd); removePid drops it.
         const registryProjectId = readProjectId(process.cwd());
@@ -236,8 +285,12 @@ function handleDaemonInner(parsed) {
             process.exit(1);
         });
         const shutdown = () => {
-            server
-                .close()
+            // Awaited before the close/exit chain: `process.exit(0)` kills an in-flight POST, and this is
+            // the one event carrying the whole session. A failed send resolves anyway (emit swallows its
+            // own errors), so this can delay the exit by at most the send timeout, never prevent it.
+            void daemonTelemetry
+                .shutdown()
+                .then(() => server.close())
                 .then(() => {
                 removePid(parsed.port);
                 process.exit(0);
@@ -279,7 +332,7 @@ function handleDaemonInner(parsed) {
  * URL. The agent then has full autonomous control without relying on the user's browser.
  */
 function handleMcp(opts) {
-    const { port, driveUrl, headless } = opts;
+    const { port, driveUrl, headless, http, httpPort, httpToken } = opts;
     // Probe the port first — a daemon with a stale PID file is still usable.
     // Only spawn when nothing is actually listening on the port.
     probeDaemon(port)
@@ -297,6 +350,14 @@ function handleMcp(opts) {
                 if (!headless)
                     daemonArgs.push(HEADED_FLAG);
             }
+            // Forward the HTTP-verify flags too (previously silently dropped for `reticle mcp`).
+            if (http) {
+                daemonArgs.push(HTTP_FLAG);
+                if (httpPort !== undefined)
+                    daemonArgs.push(HTTP_PORT_FLAG, String(httpPort));
+                if (httpToken !== undefined)
+                    daemonArgs.push(HTTP_TOKEN_FLAG, httpToken);
+            }
             spawnDaemon(process.execPath, scriptPath, daemonArgs, port);
             log('reticle_mcp_daemon_started', {
                 port,
@@ -328,11 +389,32 @@ function handleLegacyDrive(parsed) {
     });
 }
 function main() {
+    // Before anything reads process.env — notably the telemetry gate and the bridge's security
+    // options — fold in a project-local `.env`. Values already in the environment always win.
+    loadDotEnv(process.cwd());
+    const argv = process.argv.slice(2);
+    // Every invocation passes through here — the single chokepoint for the "how often is it used / how
+    // many distinct machines + projects" metrics. Fire-and-forget: a metric must never delay or fail a run.
+    //
+    // `_daemon` is EXCLUDED, and that exclusion is the whole point of this branch. `reticle mcp` and
+    // `reticle serve` start the daemon by re-running this very binary, so the child re-entered main()
+    // and emitted a second event for what a person experienced as one action. The old `invoke` metric
+    // was therefore inflated ~2x — and inflated worst on the agent-driven sessions that matter most,
+    // while one-shot commands like `version` counted once. That skewed the RATIO between commands, not
+    // just the scale, which is the kind of error you cannot correct for after the fact. The daemon's
+    // own lifecycle is already reported by `daemon_started` / `daemon_stopped`; it is not a CLI run.
+    reportCliRun(argv);
+    // Cloud subcommands (login/link/project/config/push) are a distinct family with their own async client;
+    // handle them before the local typed parser so `reticle login` etc. work as one tool.
+    if (isCloudCommand(argv[0])) {
+        void runCloudCommand(argv).then((code) => process.exit(code));
+        return;
+    }
     const portEnv = process.env[ReticleEnv.PORT];
     const envPort = portEnv !== undefined ? parseInt(portEnv, 10) : undefined;
     const projectPort = readProjectPort(process.cwd());
     const defaultPort = envPort ?? projectPort ?? RETICLE_DEFAULT_PORT;
-    const parsed = parseCliArgs(process.argv.slice(2), defaultPort);
+    const parsed = parseCliArgs(argv, defaultPort);
     switch (parsed.kind) {
         case 'error':
             log('reticle_usage_error', { message: parsed.message });
@@ -353,9 +435,24 @@ function main() {
         case 'license':
             handleLicense();
             break;
+        case 'telemetry':
+            handleTelemetry(parsed.action);
+            break;
+        case 'feedback':
+            void handleFeedback(parsed.text, parsed.rating, parsed.bug);
+            break;
+        case 'identify':
+            void handleIdentify(parsed);
+            break;
         case 'version':
             handleVersion();
             break;
+        case 'help':
+            process.stdout.write(`${CLI_USAGE}\n`);
+            break;
+        case 'doctor':
+            void handleDoctor(parsed.port);
+            break;
         case 'open':
             handleOpen(parsed.port, parsed.url);
             break;
@@ -371,6 +468,9 @@ function main() {
         case 'affected':
             void handleAffected(parsed.files, parsed.since);
             break;
+        case 'hunt':
+            void handleHunt(parsed.dir);
+            break;
         case 'gate':
             void handleGate(parsed.files, parsed.since);
             break;
@@ -413,4 +513,3 @@ function isEntryPoint() {
 if (isEntryPoint()) {
     main();
 }
-//# sourceMappingURL=cli.js.map

package/dist/cloud/cloud-config.d.ts

@@ -0,0 +1,36 @@
+import type { FileSystemPort } from '../project/fs-port.js';
+import { type CloudConfig } from './cloud-sync.js';
+/** `<reticleRoot>/cloud.json` — the project's cloud binding + sync policy (non-secret). */
+export declare const CLOUD_LINK_FILE = "cloud.json";
+/** `~/.reticle/credentials.json` — the user's per-cloud-project API keys (the only secret). */
+export declare const CREDENTIALS_FILE = "credentials.json";
+/** What the daemon mirrors to the cloud for a project. Each surface is independently toggleable. */
+export interface SyncPolicy {
+    /** Push verification-run artifacts to the dashboard Runs tab. */
+    runs: boolean;
+    /** Push per-flow project-memory outcomes (the regression history). */
+    memory: boolean;
+    /** Sync saved flow files (the shared regression suite). */
+    flows: boolean;
+}
+export declare const DEFAULT_SYNC_POLICY: SyncPolicy;
+/** Where a verification actually executes. Reserved for the hosted-runner path; default local. */
+export declare const VerifyMode: {
+    readonly LOCAL: "local";
+    readonly SERVER: "server";
+};
+export type VerifyMode = (typeof VerifyMode)[keyof typeof VerifyMode];
+/** The resolved cloud picture for one project. `config === null` ⇒ cloud NOT attached (stay 100% local). */
+export interface ProjectCloud {
+    config: CloudConfig | null;
+    policy: SyncPolicy;
+    verify: VerifyMode;
+    /** The cloud project id this project is linked to (for display/logging); null when env-fallback. */
+    projectId: string | null;
+}
+/**
+ * Resolve the cloud picture for a project rooted at `reticleRoot`. Reads the project's link file + the
+ * user credential store; if the project isn't linked (no cloud.json), falls back to the global env creds
+ * so the single-project / CI flow is unchanged. `homeDir` is injected (testable; `os.homedir()` at call).
+ */
+export declare function resolveProjectCloud(fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv): Promise<ProjectCloud>;

package/dist/cloud/cloud-config.js

@@ -0,0 +1,86 @@
+/**
+ * Per-project cloud resolution for a SHARED daemon. One reticle MCP/daemon serves many projects; each
+ * project declares its own cloud binding + sync policy in `<root>/.reticle/cloud.json`, and the SECRET
+ * (the API key) lives once per user in `~/.reticle/credentials.json` (keyed by cloud project id) — never
+ * in the repo. The daemon resolves "is cloud attached for THIS project, and what should I push where?"
+ * from those two files, falling back to the global `RETICLE_CLOUD_*` env vars for the single-project /
+ * CI case (backward compatible).
+ *
+ * Vercel-style split: `.reticle/cloud.json` is the safe-to-commit-but-gitignored binding, the key is a
+ * user-level credential. "Cloud attached" = a valid link file AND a key for its project id (or env creds).
+ */
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { resolveCloudConfig } from './cloud-sync.js';
+/** `<reticleRoot>/cloud.json` — the project's cloud binding + sync policy (non-secret). */
+export const CLOUD_LINK_FILE = 'cloud.json';
+/** `~/.reticle/credentials.json` — the user's per-cloud-project API keys (the only secret). */
+export const CREDENTIALS_FILE = 'credentials.json';
+export const DEFAULT_SYNC_POLICY = { runs: true, memory: true, flows: true };
+/** Where a verification actually executes. Reserved for the hosted-runner path; default local. */
+export const VerifyMode = { LOCAL: 'local', SERVER: 'server' };
+const asBool = (v, fallback) => (typeof v === 'boolean' ? v : fallback);
+/** Read + JSON-parse a file, or null on any problem (missing/malformed) — never throws. */
+async function readJson(fs, path) {
+    try {
+        if (!(await fs.exists(path)))
+            return null;
+        return JSON.parse(await fs.readFile(path));
+    }
+    catch {
+        return null;
+    }
+}
+/** Validate the shape of `.reticle/cloud.json`. Requires projectId + url; policy/verify default in. */
+function parseLink(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const o = raw;
+    if (typeof o.projectId !== 'string' || o.projectId.length === 0)
+        return null;
+    if (typeof o.url !== 'string' || o.url.length === 0)
+        return null;
+    const sync = typeof o.sync === 'object' && o.sync !== null ? o.sync : {};
+    return {
+        projectId: o.projectId,
+        url: o.url,
+        sync: {
+            runs: asBool(sync.runs, DEFAULT_SYNC_POLICY.runs),
+            memory: asBool(sync.memory, DEFAULT_SYNC_POLICY.memory),
+            flows: asBool(sync.flows, DEFAULT_SYNC_POLICY.flows),
+        },
+        verify: o.verify === VerifyMode.SERVER ? VerifyMode.SERVER : VerifyMode.LOCAL,
+    };
+}
+/** Look up the API key for a cloud project id in the user credentials map. */
+function credentialFor(raw, projectId) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const key = raw[projectId];
+    return typeof key === 'string' && key.length > 0 ? key : null;
+}
+/**
+ * Resolve the cloud picture for a project rooted at `reticleRoot`. Reads the project's link file + the
+ * user credential store; if the project isn't linked (no cloud.json), falls back to the global env creds
+ * so the single-project / CI flow is unchanged. `homeDir` is injected (testable; `os.homedir()` at call).
+ */
+export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
+    const link = parseLink(await readJson(fs, join(reticleRoot, CLOUD_LINK_FILE)));
+    if (link === null) {
+        // No per-project link → the env vars are the whole story (legacy single-project / CI behaviour).
+        return {
+            config: resolveCloudConfig(env),
+            policy: DEFAULT_SYNC_POLICY,
+            verify: VerifyMode.LOCAL,
+            projectId: null,
+        };
+    }
+    const policy = {
+        runs: link.sync.runs ?? DEFAULT_SYNC_POLICY.runs,
+        memory: link.sync.memory ?? DEFAULT_SYNC_POLICY.memory,
+        flows: link.sync.flows ?? DEFAULT_SYNC_POLICY.flows,
+    };
+    const key = credentialFor(await readJson(fs, join(homeDir, ReticleDir.ROOT, CREDENTIALS_FILE)), link.projectId);
+    const config = key !== null ? { url: link.url.replace(/\/+$/, ''), apiKey: key } : null;
+    return { config, policy, verify: link.verify, projectId: link.projectId };
+}