@reticlehq/server 2.2.1 → 2.3.0

package/dist/hunt/hunt-report.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Aggregate many crawl runs into the one number the core claim needs.
+ *
+ * Detection already exists: `reticle_crawl` drives every reachable control and reports contradictions
+ * — two channels disagreeing about the same click. It found `swallowed-500-login` and, separately,
+ * `ui-advanced-request-failed` on a control whose assertion was green, neither of them planted.
+ *
+ * What was missing is the arithmetic that turns those into evidence. The claim worth making is not
+ * "Reticle can find bugs"; it is:
+ *
+ *   "Run over N already-merged, already-green changes, it found X real bugs their own tests
+ *    certified as passing."
+ *
+ * That needs no control arm, which is why it is the cheapest credible proof available: the
+ * counterfactual is already established, because those changes SHIPPED. An A/B is the second study,
+ * and this tells you where to point it.
+ *
+ * Pure functions over already-collected reports — the driving is `reticle_crawl`'s job, and running
+ * it across a commit range is a shell loop. This is only the part that must not be done by eye.
+ */
+/** The contradiction kinds — cross-channel disagreement, as opposed to a single-channel fault. */
+export declare const CONTRADICTION_KINDS: readonly string[];
+export interface HuntAnomaly {
+    kind: string;
+    ref?: string;
+    desc?: string;
+    detail?: string;
+}
+/** One crawl over one checkout. `label` is whatever identifies it — a commit sha, a PR number. */
+export interface HuntRun {
+    label: string;
+    anomalies: readonly HuntAnomaly[];
+    /** Controls actually driven. A run that drove nothing proves nothing and is reported separately. */
+    stepsRun?: number;
+}
+export interface HuntSummary {
+    runs: number;
+    /** Runs that actually drove at least one control. The denominator that can honestly be quoted. */
+    runsWithCoverage: number;
+    /** Runs where at least one CONTRADICTION was found — the headline numerator. */
+    runsWithContradictions: number;
+    contradictions: number;
+    /** Single-channel faults (console errors, failed requests, dead controls). Context, not the claim. */
+    singleChannelFaults: number;
+    byKind: Record<string, number>;
+    /** Labels with contradictions, so each one can be confirmed by hand before it is counted. */
+    flagged: string[];
+    headline: string;
+}
+export declare function summarizeHunt(runs: readonly HuntRun[]): HuntSummary;

package/dist/hunt/hunt-report.js

@@ -0,0 +1,84 @@
+/**
+ * Aggregate many crawl runs into the one number the core claim needs.
+ *
+ * Detection already exists: `reticle_crawl` drives every reachable control and reports contradictions
+ * — two channels disagreeing about the same click. It found `swallowed-500-login` and, separately,
+ * `ui-advanced-request-failed` on a control whose assertion was green, neither of them planted.
+ *
+ * What was missing is the arithmetic that turns those into evidence. The claim worth making is not
+ * "Reticle can find bugs"; it is:
+ *
+ *   "Run over N already-merged, already-green changes, it found X real bugs their own tests
+ *    certified as passing."
+ *
+ * That needs no control arm, which is why it is the cheapest credible proof available: the
+ * counterfactual is already established, because those changes SHIPPED. An A/B is the second study,
+ * and this tells you where to point it.
+ *
+ * Pure functions over already-collected reports — the driving is `reticle_crawl`'s job, and running
+ * it across a commit range is a shell loop. This is only the part that must not be done by eye.
+ */
+/** The contradiction kinds — cross-channel disagreement, as opposed to a single-channel fault. */
+export const CONTRADICTION_KINDS = [
+    'ui-advanced-request-failed',
+    'signal-contradicted',
+    'response-ignored',
+    'duplicate-request',
+    'request-never-settled',
+    'failure-misattributed',
+];
+const isContradiction = (kind) => CONTRADICTION_KINDS.includes(kind);
+export function summarizeHunt(runs) {
+    const byKind = {};
+    const flagged = [];
+    let contradictions = 0;
+    let singleChannelFaults = 0;
+    let runsWithCoverage = 0;
+    for (const run of runs) {
+        // A run that drove nothing is not evidence of cleanliness. Counting it in the denominator would
+        // dilute the rate with checkouts where the app never even came up — the arithmetic equivalent of
+        // reporting a green because no test ran.
+        if ((run.stepsRun ?? 0) > 0)
+            runsWithCoverage += 1;
+        let flaggedThisRun = false;
+        for (const anomaly of run.anomalies) {
+            byKind[anomaly.kind] = (byKind[anomaly.kind] ?? 0) + 1;
+            if (isContradiction(anomaly.kind)) {
+                contradictions += 1;
+                flaggedThisRun = true;
+            }
+            else {
+                singleChannelFaults += 1;
+            }
+        }
+        if (flaggedThisRun)
+            flagged.push(run.label);
+    }
+    return {
+        runs: runs.length,
+        runsWithCoverage,
+        runsWithContradictions: flagged.length,
+        contradictions,
+        singleChannelFaults,
+        byKind,
+        flagged,
+        headline: buildHeadline(runsWithCoverage, flagged.length, contradictions),
+    };
+}
+/**
+ * The sentence that goes in front of someone, phrased so it cannot overstate itself.
+ *
+ * It counts CHECKOUTS with a finding rather than raw findings, because one broken control clicked
+ * five times is one bug and five anomalies. It also says "candidate": every flag still has to be
+ * confirmed by hand before it is a bug, and a number that skips that step is the kind of evidence
+ * this project exists to distrust.
+ */
+function buildHeadline(withCoverage, flaggedRuns, contradictions) {
+    if (withCoverage === 0) {
+        return 'no run drove a single control — nothing was measured, which is not the same as nothing being wrong';
+    }
+    if (flaggedRuns === 0) {
+        return `${String(withCoverage)} merged changes crawled, no cross-channel contradictions found — confirm coverage was real before reading this as clean`;
+    }
+    return `${String(flaggedRuns)} of ${String(withCoverage)} merged, already-green changes carried a candidate false green (${String(contradictions)} contradictions) — each needs manual confirmation before it is counted`;
+}

package/dist/idle-shutdown.d.ts

@@ -31,4 +31,3 @@ export declare class IdleShutdown {
  * `0` to disable. Anything missing/invalid falls back to the default. Pure.
  */
 export declare function resolveIdleShutdownMs(raw: string | undefined): number;
-//# sourceMappingURL=idle-shutdown.d.ts.map

package/dist/idle-shutdown.js

@@ -65,4 +65,3 @@ export function resolveIdleShutdownMs(raw) {
         return SESSION_LIFECYCLE.DAEMON_IDLE_SHUTDOWN_MS;
     return Math.floor(n);
 }
-//# sourceMappingURL=idle-shutdown.js.map

package/dist/index.d.ts

@@ -132,4 +132,3 @@ export declare function start(options?: StartOptions): Promise<RunningServer>;
  * browser sessions persist in the daemon.
  */
 export declare function startDaemon(options?: StartOptions): Promise<RunningServer>;
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -426,4 +426,3 @@ export async function startDaemon(options = {}) {
         },
     };
 }
-//# sourceMappingURL=index.js.map

package/dist/init/agent-rules.d.ts

@@ -35,4 +35,3 @@ export declare function markedBlock(): string;
 export declare function mergeMarkedInstruction(existing: string | null | undefined): AgentRuleResult;
 /** The Cursor rule file (.mdc): `alwaysApply` keeps the rule in every turn's context. */
 export declare function cursorRuleFile(): string;
-//# sourceMappingURL=agent-rules.d.ts.map

package/dist/init/agent-rules.js

@@ -27,7 +27,10 @@ This app is instrumented by **Reticle** — an in-app verification layer exposed
 - **How:** drive the actual flow (\`reticle_act\` / \`reticle_act_and_wait\`), then read the observable effect (\`reticle_assert\`, \`reticle_snapshot\`, \`reticle_state\`, \`reticle_network\`). Confirm the change produced the effect it was meant to, with no new console errors or failed requests.
 - **Covered flows:** run \`reticle gate\` — it reports which recorded flows the changed files affect and whether they still pass.
 - **Never weaken a check to make it green.** Downgrading, skipping, or deleting an assertion is a finding, not a fix.
-- **If Reticle can't run** (no daemon, or this is not a running web app), say so — do not skip verification silently.`;
+- **If Reticle can't run** (no daemon, or this is not a running web app), say so — do not skip verification silently.
+- **If a tool result carries \`update_available\`, say so.** Reticle checked npm and a newer version exists. Tell the human the version numbers and offer to run \`reticle update\` — between tasks, never mid-verification, because it restarts the daemon and drops the session. Finish what you are doing first.
+- **Wish Reticle could do something? Ask for it with \`reticle_feedback\`.** Reticle is built for agents, so what you find awkward or missing is what decides the roadmap — and you are the only one who can report it, because that thought disappears when your context does. File \`feature_request\` for something that does not exist, \`improvement\` for something that works but costs too many calls. Say what you are actually trying to achieve (\`need\`) and how you work around it today (\`currentApproach\`), and set \`model\` to the model you are running. File it the moment you notice, then carry on — nothing is too minor.
+- **If Reticle itself fails you, tell its maintainers with \`reticle_feedback\`.** A tool that returned something wrong, a thing Reticle could not observe at all, or a verdict you could not act on — file it with a root-cause analysis and the call trace, then carry on with the task. Working around a broken tool in silence is how the same defect survives. This is about defects in *Reticle*; a bug you find in *this app* is Reticle working, and belongs in your report to the user instead.`;
 export const AgentRuleStatus = {
     APPLY: 'apply',
     ALREADY: 'already',
@@ -62,4 +65,3 @@ alwaysApply: true
 ${RULE_BODY}
 `;
 }
-//# sourceMappingURL=agent-rules.js.map

package/dist/init/cursor.d.ts

@@ -22,4 +22,3 @@ interface CursorMergeResult {
 export declare function cursorServerEntry(): Record<string, unknown>;
 export declare function mergeCursorConfig(existing: string | null): CursorMergeResult;
 export {};
-//# sourceMappingURL=cursor.d.ts.map

package/dist/init/cursor.js

@@ -46,4 +46,3 @@ export function mergeCursorConfig(existing) {
     };
     return { status: CursorMergeStatus.APPLY, content: `${JSON.stringify(merged, null, 2)}\n` };
 }
-//# sourceMappingURL=cursor.js.map

package/dist/init/desktop-doctor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Setup RCA for desktop apps.
+ *
+ * Every failure this catches is SILENT. A Tauri app with the default CSP runs perfectly and simply
+ * never appears in `reticle status` — the WebSocket is blocked before it opens, and nothing in the
+ * app's own console says so. An Electron app missing the preload line works fine and reports zero
+ * network activity forever, which reads as "the app makes no backend calls" rather than "you are
+ * blind to all of them".
+ *
+ * Silent misconfiguration is the same disease as a false green: the tool answers confidently and the
+ * answer is wrong. So the diagnosis names the file, the reason, and the exact line to add.
+ *
+ * Pure: a `read` function in, findings out. No fs, no cwd, no process.
+ */
+export declare const DesktopFinding: {
+    /** Tauri's CSP will block the bridge WebSocket — the app will never connect, with no error. */
+    readonly TAURI_CSP_BLOCKS_BRIDGE: "tauri-csp-blocks-bridge";
+    /** A custom CSP dropped the `ipc:` source Tauri needs for `invoke` itself. */
+    readonly TAURI_CSP_BLOCKS_IPC: "tauri-csp-blocks-ipc";
+    /** The preload never requires the shim, so every IPC call is invisible. */
+    readonly ELECTRON_PRELOAD_MISSING: "electron-preload-missing";
+    /** The main process never installs the capture helper, so screenshots are unavailable. */
+    readonly ELECTRON_CAPTURE_MISSING: "electron-capture-missing";
+};
+export type DesktopFinding = (typeof DesktopFinding)[keyof typeof DesktopFinding];
+export interface DesktopDiagnosis {
+    code: DesktopFinding;
+    /** Which file to look at. */
+    file: string;
+    /** What is wrong, in one line. */
+    problem: string;
+    /** Exactly what to add — copy-pasteable, with the port actually in use. */
+    fix: string;
+}
+/** Reads a project-relative path. Undefined means the file does not exist. */
+export type ReadFile = (path: string) => string | undefined;
+/** Is this project a desktop shell at all? Used to print a positive result instead of silence. */
+export declare function isDesktopProject(read: ReadFile): boolean;
+/** Which desktop shell (if any) this project is, and what is missing from its Reticle wiring. */
+export declare function diagnoseDesktop(read: ReadFile, port: number): DesktopDiagnosis[];

package/dist/init/desktop-doctor.js

@@ -0,0 +1,198 @@
+import { RETICLE_IPC_GLOBAL } from '@reticlehq/core';
+/**
+ * Setup RCA for desktop apps.
+ *
+ * Every failure this catches is SILENT. A Tauri app with the default CSP runs perfectly and simply
+ * never appears in `reticle status` — the WebSocket is blocked before it opens, and nothing in the
+ * app's own console says so. An Electron app missing the preload line works fine and reports zero
+ * network activity forever, which reads as "the app makes no backend calls" rather than "you are
+ * blind to all of them".
+ *
+ * Silent misconfiguration is the same disease as a false green: the tool answers confidently and the
+ * answer is wrong. So the diagnosis names the file, the reason, and the exact line to add.
+ *
+ * Pure: a `read` function in, findings out. No fs, no cwd, no process.
+ */
+export const DesktopFinding = {
+    /** Tauri's CSP will block the bridge WebSocket — the app will never connect, with no error. */
+    TAURI_CSP_BLOCKS_BRIDGE: 'tauri-csp-blocks-bridge',
+    /** A custom CSP dropped the `ipc:` source Tauri needs for `invoke` itself. */
+    TAURI_CSP_BLOCKS_IPC: 'tauri-csp-blocks-ipc',
+    /** The preload never requires the shim, so every IPC call is invisible. */
+    ELECTRON_PRELOAD_MISSING: 'electron-preload-missing',
+    /** The main process never installs the capture helper, so screenshots are unavailable. */
+    ELECTRON_CAPTURE_MISSING: 'electron-capture-missing',
+};
+const TAURI_CONF = 'src-tauri/tauri.conf.json';
+const PRELOAD_REQUIRE = '@reticlehq/electron/preload';
+const CAPTURE_REQUIRE = '@reticlehq/electron/main';
+function parseJson(text) {
+    if (text === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined; // a malformed config is the app's problem, not something to crash the doctor on
+    }
+}
+function record(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+/**
+ * Does this CSP permit the bridge WebSocket on `port`?
+ *
+ * A MISSING csp key is treated as blocking, not permissive: Tauri applies a restrictive default, so
+ * reporting "no CSP, therefore fine" would be precisely the false green this tool exists to prevent.
+ */
+function cspAllowsBridge(csp, port) {
+    if (csp === undefined)
+        return false;
+    const exact = `ws://localhost:${String(port)}`;
+    const loopback = `ws://127.0.0.1:${String(port)}`;
+    // A BARE `ws:` scheme source allows any ws origin. It must be matched as a whole source, not as a
+    // substring: `includes('ws:')` also matches `ws://localhost:4400`, which would make every port
+    // look allowed and silently defeat the port check this function exists to perform.
+    const bareScheme = /(^|[\s;])ws:(?!\/\/)/.test(csp);
+    return (csp.includes(exact) ||
+        csp.includes(loopback) ||
+        csp.includes('ws://localhost:*') ||
+        csp.includes('ws://127.0.0.1:*') ||
+        bareScheme);
+}
+/** Tauri v2 needs `ipc:`/`http://ipc.localhost` in connect-src for `invoke` to work at all. */
+function cspAllowsIpc(csp) {
+    return csp.includes('ipc:') || csp.includes('ipc.localhost');
+}
+function diagnoseTauri(read, port) {
+    const conf = parseJson(read(TAURI_CONF));
+    if (conf === undefined)
+        return [];
+    const security = record(record(conf['app'])['security']);
+    const csp = typeof security['csp'] === 'string' ? security['csp'] : undefined;
+    const findings = [];
+    if (!cspAllowsBridge(csp, port)) {
+        findings.push({
+            code: DesktopFinding.TAURI_CSP_BLOCKS_BRIDGE,
+            file: TAURI_CONF,
+            problem: csp === undefined
+                ? "no `app.security.csp` set, so Tauri's restrictive default applies and blocks the Reticle bridge — the app will run normally and never connect"
+                : 'the CSP `connect-src` does not allow the Reticle bridge WebSocket — the app will run normally and never connect',
+            fix: `add to app.security.csp connect-src:  ws://localhost:${String(port)}`,
+        });
+    }
+    if (csp !== undefined && !cspAllowsIpc(csp)) {
+        findings.push({
+            code: DesktopFinding.TAURI_CSP_BLOCKS_IPC,
+            file: TAURI_CONF,
+            problem: 'the CSP dropped the `ipc:` source Tauri needs — `invoke` itself will fail',
+            fix: 'add to app.security.csp connect-src:  ipc: http://ipc.localhost',
+        });
+    }
+    return findings;
+}
+/** The directory portion of a path, without pulling in node:path (this module stays pure). */
+function dirOf(path) {
+    const cut = path.lastIndexOf('/');
+    return cut < 0 ? '' : path.slice(0, cut + 1);
+}
+/**
+ * Where a preload SOURCE might live, in the order worth trying.
+ *
+ * Beside `main` first (the unbundled layout), then the usual source directories — a bundled setup
+ * points `main` at `out/` or `dist/` while the real preload stays in `src/` or `electron/`.
+ */
+function preloadCandidates(mainDir) {
+    const names = ['preload.cjs', 'preload.js', 'preload.mjs', 'preload.ts', 'preload.mts'];
+    const dirs = [mainDir, 'electron/', 'src/', 'src/preload/', 'src/main/', ''];
+    return dirs.flatMap((dir) => names.map((name) => `${dir}${name}`));
+}
+/**
+ * Where a BUNDLED preload's output lands. electron-vite's default layout mirrors `out/main` with
+ * `out/preload`; Forge and hand-rolled setups favour `dist`/`build`.
+ */
+function bundledPreloadCandidates(mainDir) {
+    const roots = [mainDir.replace(/main\/?$/, ''), 'out/', 'dist/', 'build/', '.vite/build/'];
+    const names = [
+        'preload/index.js',
+        'preload/index.mjs',
+        'preload/index.cjs',
+        'preload.js',
+        'preload.mjs',
+        'preload.cjs',
+    ];
+    return roots.flatMap((root) => names.map((name) => `${root}${name}`));
+}
+/**
+ * Is the preload wired, judged from whatever evidence exists?
+ *
+ * Source first (the require is right there). Failing that, the BUILD OUTPUT: bundling inlines the
+ * shim, and the shim carries the contract's own window global — finding that string in the artifact
+ * proves the preload is wired even though the require has been compiled away. Undefined means no
+ * evidence either way, and an unknown must never be reported as a fault.
+ */
+function preloadWired(read, mainDir) {
+    for (const candidate of preloadCandidates(mainDir)) {
+        const source = read(candidate);
+        if (source !== undefined)
+            return { wired: source.includes(PRELOAD_REQUIRE), file: candidate };
+    }
+    for (const candidate of bundledPreloadCandidates(mainDir)) {
+        const built = read(candidate);
+        if (built !== undefined) {
+            return { wired: built.includes(RETICLE_IPC_GLOBAL), file: candidate };
+        }
+    }
+    return undefined;
+}
+function diagnoseElectron(read, main) {
+    const findings = [];
+    const dir = dirOf(main);
+    // Undefined = no source AND no build output to judge from. An unknown is not a fault.
+    const preload = preloadWired(read, dir);
+    if (preload !== undefined && !preload.wired) {
+        findings.push({
+            code: DesktopFinding.ELECTRON_PRELOAD_MISSING,
+            file: preload.file,
+            problem: 'the preload never installs the Reticle IPC shim, so every ipcRenderer.invoke is invisible — reticle_network will report nothing and read as "this app makes no backend calls"',
+            fix: `add as the FIRST line:  require('${PRELOAD_REQUIRE}')`,
+        });
+    }
+    const mainSource = read(main);
+    if (mainSource !== undefined && !mainSource.includes(CAPTURE_REQUIRE)) {
+        findings.push({
+            code: DesktopFinding.ELECTRON_CAPTURE_MISSING,
+            file: main,
+            problem: 'the main process never installs the capture helper, so screenshots are unavailable',
+            fix: `add:  const { installReticleCapture } = require('${CAPTURE_REQUIRE}')  then installReticleCapture(win)`,
+        });
+    }
+    return findings;
+}
+/** Is this project a desktop shell at all? Used to print a positive result instead of silence. */
+export function isDesktopProject(read) {
+    if (read(TAURI_CONF) !== undefined)
+        return true;
+    const pkg = parseJson(read('package.json'));
+    if (pkg === undefined)
+        return false;
+    const deps = { ...record(pkg['dependencies']), ...record(pkg['devDependencies']) };
+    return deps['electron'] !== undefined;
+}
+/** Which desktop shell (if any) this project is, and what is missing from its Reticle wiring. */
+export function diagnoseDesktop(read, port) {
+    const tauri = diagnoseTauri(read, port);
+    if (tauri.length > 0 || read(TAURI_CONF) !== undefined)
+        return tauri;
+    const pkg = parseJson(read('package.json'));
+    if (pkg === undefined)
+        return [];
+    const deps = { ...record(pkg['dependencies']), ...record(pkg['devDependencies']) };
+    if (deps['electron'] === undefined)
+        return [];
+    const main = typeof pkg['main'] === 'string' ? pkg['main'] : undefined;
+    return main === undefined ? [] : diagnoseElectron(read, main);
+}

package/dist/init/detect.d.ts

@@ -46,4 +46,3 @@ interface InstallCommand {
 export declare function installCommandParts(pm: PackageManager, pkgs: string | readonly string[]): InstallCommand;
 export declare function installCommand(pm: PackageManager, pkgs: string | readonly string[]): string;
 export {};
-//# sourceMappingURL=detect.d.ts.map

package/dist/init/detect.js

@@ -81,4 +81,3 @@ export function installCommand(pm, pkgs) {
     const { command, args } = installCommandParts(pm, pkgs);
     return `${command} ${args.join(' ')}`;
 }
-//# sourceMappingURL=detect.js.map

package/dist/init/mcp.d.ts

@@ -37,4 +37,3 @@ export declare function claudeAvailableProbe(): {
 /** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
 export declare function mcpManual(): string;
 export {};
-//# sourceMappingURL=mcp.d.ts.map

package/dist/init/mcp.js

@@ -53,4 +53,3 @@ Or, for another agent, add this to its global MCP config (e.g. Cursor's ~/.curso
 
   "${MCP_SERVER_NAME}": { "command": "${NPX}", "args": ${JSON.stringify(serverInvocation().slice(1))} }`;
 }
-//# sourceMappingURL=mcp.js.map

package/dist/init/node-io.d.ts

@@ -5,4 +5,3 @@
  */
 import type { InitIo } from './run.js';
 export declare function buildNodeIo(cwd: string): InitIo;
-//# sourceMappingURL=node-io.d.ts.map

package/dist/init/node-io.js

@@ -54,4 +54,3 @@ export function buildNodeIo(cwd) {
         },
     };
 }
-//# sourceMappingURL=node-io.js.map

package/dist/init/plan.d.ts

@@ -6,6 +6,10 @@
 import { Framework, type Detection } from './detect.js';
 /** The dev-dependencies `reticle init` installs for a given framework — kit first, build plugin next. */
 export declare function frameworkPackages(framework: Framework): readonly string[];
+/** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
+export declare const MCP_TARGET = "global (claude user scope)";
+/** The step that runs the package manager — the other thing that commonly fails on a user's machine. */
+export declare const DEPS_TARGET = "package.json";
 export declare const StepStatus: {
     readonly APPLY: "apply";
     readonly MANUAL: "manual";
@@ -75,4 +79,3 @@ export interface PlanInput {
 }
 export declare function buildPlan(input: PlanInput): Plan;
 export {};
-//# sourceMappingURL=plan.d.ts.map

package/dist/init/plan.js

@@ -8,7 +8,7 @@ import { claudeAddCommand, mcpManual } from './mcp.js';
 import { mergeCursorConfig, CursorMergeStatus, cursorServerEntry } from './cursor.js';
 import { mergeMarkedInstruction, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, AGENTS_MD_PATH, CURSOR_RULE_PATH, } from './agent-rules.js';
 import { patchViteConfig, VitePatchKind } from './vite-config.js';
-import { viteManual, htmlManual, NEXT_LAYOUT_MANUAL, nextReticleDevFile, NEXT_RETICLE_DEV_PATH, nextConfigManual, reticleConfigContent, svelteKitHooksFile, SVELTEKIT_HOOKS_PATH, } from './snippets.js';
+import { viteManual, htmlManual, NEXT_LAYOUT_MANUAL, nextReticleDevFile, NEXT_RETICLE_DEV_PATH, nextConfigManual, reticleConfigContent, svelteKitHooksFile, SVELTEKIT_HOOKS_PATH, UNVERIFIED_FRAMEWORK_NOTE, } from './snippets.js';
 // An app dev installs exactly the audience-scoped browser-side dependencies — never the retired
 // `@reticlehq/core` umbrella (which dragged the Node MCP server + ws into every app). The kit is the
 // framework adapter (it re-exports the browser sensor), paired with that framework's dev-only build
@@ -30,7 +30,10 @@ export function frameworkPackages(framework) {
             return [RETICLE_REACT_KIT];
     }
 }
-const MCP_TARGET = 'global (claude user scope)';
+/** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
+export const MCP_TARGET = 'global (claude user scope)';
+/** The step that runs the package manager — the other thing that commonly fails on a user's machine. */
+export const DEPS_TARGET = 'package.json';
 const RETICLE_CONFIG_FILE = '.reticle.json';
 export const StepStatus = {
     APPLY: 'apply',
@@ -283,11 +286,26 @@ function nextSteps(input) {
         },
     ];
 }
+/**
+ * SvelteKit is WIRED but not SUPPORTED, and the plan says so out loud.
+ *
+ * There is no SvelteKit app in `apps/` and no CI gate for one, so nothing proves this hook still
+ * registers a session — every other framework init offers (React, Next, Remix, Astro) has both. The
+ * wiring is real and may well work; what is missing is anything that would tell us when it stops.
+ * Silently emitting it reads as a support claim, which is the thing this project exists to not do.
+ */
 function svelteKitSteps(input) {
-    // SvelteKit can't use the Vite-plugin injection (renders via app.html) — wire a client hook that
-    // SvelteKit runs on startup. This is verified to register a session where the plugin does not.
+    const unverified = {
+        title: 'SvelteKit is UNVERIFIED',
+        target: SVELTEKIT_HOOKS_PATH,
+        status: StepStatus.MANUAL,
+        detail: UNVERIFIED_FRAMEWORK_NOTE,
+    };
+    // SvelteKit can't use the Vite-plugin injection (it renders via app.html) — wire a client hook
+    // that SvelteKit runs on startup, which is the path that can register a session at all.
     if (input.svelteKitHooksExists === true) {
         return [
+            unverified,
             {
                 title: 'Reticle client hook',
                 target: SVELTEKIT_HOOKS_PATH,
@@ -297,6 +315,7 @@ function svelteKitSteps(input) {
         ];
     }
     return [
+        unverified,
         {
             title: 'Reticle client hook',
             target: SVELTEKIT_HOOKS_PATH,
@@ -353,4 +372,3 @@ export function buildPlan(input) {
     }
     return { framework: input.detection.framework, steps };
 }
-//# sourceMappingURL=plan.js.map

package/dist/init/project-id.d.ts

@@ -14,4 +14,3 @@ export declare function shortHash(input: string): string;
 export declare function deriveProjectId(pkgName: string | undefined, rootPath: string): string;
 /** Pull a string `name` out of an already-parsed package.json object, or undefined. */
 export declare function packageName(pkg: unknown): string | undefined;
-//# sourceMappingURL=project-id.d.ts.map

package/dist/init/project-id.js

@@ -35,4 +35,3 @@ export function packageName(pkg) {
     }
     return undefined;
 }
-//# sourceMappingURL=project-id.js.map

package/dist/init/run.d.ts

@@ -39,4 +39,3 @@ interface InitResult {
 }
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;
 export {};
-//# sourceMappingURL=run.d.ts.map

package/dist/init/run.js

@@ -5,10 +5,11 @@
  */
 import { dirname, join } from 'node:path';
 import { detect, Framework } from './detect.js';
-import { buildPlan, StepStatus } from './plan.js';
+import { DEPS_TARGET, MCP_TARGET, buildPlan, StepStatus, } from './plan.js';
 import { claudeAvailableProbe, claudeExistsProbe } from './mcp.js';
 import { CURSOR_DIR_RELPATH, CURSOR_MCP_RELPATH } from './cursor.js';
 import { deriveProjectId, packageName } from './project-id.js';
+import { InitFailure, reportInitOutcome } from '../telemetry/init-telemetry.js';
 /** Lockfile basenames, in package-manager preference order (mirrors detect.ts). */
 const LOCKFILE_NAMES = [
     'pnpm-lock.yaml',
@@ -162,14 +163,41 @@ function applyEffects(plan, io) {
     }
     return failed;
 }
+/**
+ * Which STEP failed, from the step targets — not from an error string, which would carry paths.
+ *
+ * The distinction that matters: a dependency install failing is a machine/network problem (offline,
+ * a locked registry, a broken package manager), while MCP registration failing means the `claude` CLI
+ * is missing or refused. Two completely different fixes, and until now both were simply "init didn't
+ * work" with nothing to tell them apart.
+ */
+function classifyInitFailure(failed) {
+    if (failed.has(DEPS_TARGET))
+        return InitFailure.DEPENDENCY_INSTALL;
+    if (failed.has(MCP_TARGET))
+        return InitFailure.MCP_REGISTRATION;
+    return InitFailure.OTHER;
+}
 export function runInit(options, io) {
     const pkgRaw = io.readFile(PACKAGE_JSON);
     if (pkgRaw === null) {
         io.print('No package.json found. Run `reticle init` from your project root.');
+        // The onboarding funnel had NO instrumentation, so a setup that died here was indistinguishable
+        // from someone who never ran the command — the two failure modes with the most different fixes.
+        reportInitOutcome({ ok: false, reason: InitFailure.NO_PACKAGE_JSON });
         return { ok: false, applied: 0, manual: 0 };
     }
     const plan = buildPlan(gatherPlanInput(options, io, pkgRaw));
     const failed = options.dryRun ? new Set() : applyEffects(plan, io);
-    return report(plan, options.dryRun, failed, io);
+    const result = report(plan, options.dryRun, failed, io);
+    // A dry run is a preview, not an outcome — reporting it would inflate both success and failure.
+    if (!options.dryRun) {
+        reportInitOutcome({
+            ok: result.ok,
+            ...(result.ok ? {} : { reason: classifyInitFailure(failed) }),
+            stack: plan.framework,
+            mcpRegistered: !failed.has(MCP_TARGET),
+        });
+    }
+    return result;
 }
-//# sourceMappingURL=run.js.map

package/dist/init/snippets.d.ts

@@ -19,6 +19,11 @@ export declare const NEXT_LAYOUT_MANUAL = "Mount <ReticleDev /> in your root lay
 export declare function htmlManual(port: number | undefined, projectId?: string): string;
 export declare const NEXT_RETICLE_DEV_PATH = "app/reticle-dev.tsx";
 export declare const SVELTEKIT_HOOKS_PATH = "src/hooks.client.ts";
+/**
+ * Said to the user's face rather than discovered later. React, Next, Remix and Astro each have an
+ * app and a CI gate; SvelteKit has neither, so "it generated some wiring" is not evidence it works.
+ */
+export declare const UNVERIFIED_FRAMEWORK_NOTE = "Reticle has no SvelteKit app and no CI gate for one, so this wiring is untested \u2014 it may work, but nothing proves it and nothing will tell us if it breaks. Supported and gated today: Vite + React, Next.js, Remix, Astro, and plain HTML. If the hook does not register a session, please open an issue.";
 /**
  * Dev-only client hook that connects Reticle in a SvelteKit app. SvelteKit renders through app.html and
  * never triggers Vite's index.html injection (verified), so the standard plugin can't auto-connect —
@@ -30,4 +35,3 @@ export declare function svelteKitHooksFile(port: number | undefined, projectId?:
  * and by tooling for the stable projectId (the app's identity across port changes).
  */
 export declare function reticleConfigContent(framework: string, port: number | undefined, projectId?: string): string;
-//# sourceMappingURL=snippets.d.ts.map