@reticlehq/init 3.5.0 → 3.7.0

package/dist/diagnose/closing-hint.js

@@ -21,6 +21,24 @@ export const FEEDBACK_HINT = 'Anything wrong, missing, or awkward — in this se
     'one thing that decides what gets fixed:\n' +
     `  ${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"   (agents)\n` +
     `  ${CLI} feedback "what worked, what didn't"   (humans)`;
+/** User-facing closing copy for `restartHint` — one named home per sentence block. */
+const RestartHintCopy = {
+    DEMO: 'Then drive one real flow of your app end to end and report the verdict — that is the install ' +
+        "proving itself, and it is the agent's job, not a separate command.",
+    PROVE: 'Then run `npx @reticlehq/server status` — it confirms the app connected, or says exactly why ' +
+        'it has not.',
+    ALREADY_REGISTERED_ALL: 'The Reticle MCP server was already registered on this machine, so there is no restart to do ' +
+        'and the tools are available now.',
+    ALREADY_REGISTERED_CLAUDE_HEAD: 'The Reticle MCP server was already registered with Claude Code, so there is no restart to ' +
+        'do and the tools are available there now. They are NOT available in the clients whose ' +
+        'step above still needs a hand edit (',
+    ALREADY_REGISTERED_CLAUDE_TAIL: ') until that is done.',
+    CLOSING_ALREADY_NO_MANUAL: 'Once it shows a session, drive a flow — that is the install finished. Carry straight on; ' +
+        'nothing here is waiting on a human.',
+    CLOSING_ALREADY_WITH_MANUAL: 'Once it shows a session, drive a flow where the tools are already available — that is the ' +
+        'install finished on that client. The hand-edit step above still needs a human for the other ' +
+        'clients named there.',
+};
 /**
  * What to say about the dev server.
  *
@@ -53,7 +71,13 @@ function devServerRestart(devCommand) {
  */
 export function restartHint(mcpStatus, 
 /** The project's own dev command, when package.json named one. */
-devCommand) {
+devCommand, 
+/**
+ * Titles of other clients' registration steps this run left for the reader (the `⚠` rows). The
+ * Claude Code row says nothing about them, so without these the closing line contradicts the
+ * report above it.
+ */
+manualClients = []) {
     const dev = `${devServerRestart(devCommand)}.`;
     // NAME THE COMMAND THAT PROVES IT, not one that merely asks.
     //
@@ -77,10 +101,8 @@ devCommand) {
     // So the close hands the agent the sequence instead. It is deliberately one drive of one real
     // flow ending in a verdict, because an install that ends in "the tools are available" is an
     // install that ends in nothing.
-    const demo = 'Then drive one real flow of your app end to end and report the verdict — that is the install ' +
-        "proving itself, and it is the agent's job, not a separate command.";
-    const prove = 'Then run `npx @reticlehq/server status` — it confirms the app connected, or says exactly why ' +
-        'it has not.';
+    const demo = RestartHintCopy.DEMO;
+    const prove = RestartHintCopy.PROVE;
     // Nothing registered this run (`--no-mcp`, or a client that needs a manual edit): a restart picks
     // up nothing, so advice about one would be advice about something we did not do.
     if (!wasMcpRegistered(mcpStatus))
@@ -92,13 +114,18 @@ devCommand) {
     // agent, the tools only appear after that" — and an agent believes the output in front of it over
     // whatever its skill file said, so it stops with the project wired and nothing driven.
     if (mcpStatus === StepStatus.ALREADY) {
-        return (`${dev}\n` +
-            `${demo}\n` +
-            'The Reticle MCP server was already registered on this machine, so there is no restart to do ' +
-            'and the tools are available now.\n' +
-            `${prove}\n` +
-            'Once it shows a session, drive a flow — that is the install finished. Carry straight on; ' +
-            'nothing here is waiting on a human.');
+        // Only Claude Code's row was read, so "available now" is true for Claude Code and nothing else.
+        // Name the registrations still left, or a Codex user reads two contradicting lines and believes
+        // the last one.
+        const availability = 0 === manualClients.length
+            ? RestartHintCopy.ALREADY_REGISTERED_ALL
+            : RestartHintCopy.ALREADY_REGISTERED_CLAUDE_HEAD +
+                manualClients.join(', ') +
+                RestartHintCopy.ALREADY_REGISTERED_CLAUDE_TAIL;
+        const closing = 0 === manualClients.length
+            ? RestartHintCopy.CLOSING_ALREADY_NO_MANUAL
+            : RestartHintCopy.CLOSING_ALREADY_WITH_MANUAL;
+        return `${dev}\n${demo}\n${availability}\n${prove}\n${closing}`;
     }
     return (`${dev}\n` +
         `${demo}\n` +

package/dist/diagnose/csp-check.js

@@ -24,23 +24,26 @@ const WILDCARDS = ['*', 'ws:', 'wss:', 'ws://*', 'https:'];
 function bridgeOrigins(port) {
     return [`ws://localhost:${String(port)}`, `ws://127.0.0.1:${String(port)}`];
 }
-/**
- * The `connect-src` directive's source list, or undefined when the text declares none.
- *
- * Matches to the end of the directive (`;`) or the end of the enclosing quoted string, which is how
- * these are written in both a Next `headers()` value and a `<meta content="...">`.
- */
+const TERNARY_GAP = /^"\s*:\s*"$/;
+const EXPRESSION_EDGE = /^["'`})\]]+|["'`})\]]+$/g;
 function directiveSources(text, directive) {
     // Stops at the directive separator or the closing double quote of the enclosing string. Single
     // quotes are NOT terminators: `'self'` is a source, not the end of the list.
-    const match = new RegExp(`${directive}([^;"]*)`, 'i').exec(text);
-    const list = match?.[1];
-    if (list === undefined)
+    const matches = [...text.matchAll(new RegExp(`${directive}([^;"]*)`, 'gi'))];
+    if (0 === matches.length)
         return undefined;
-    return list
-        .split(/\s+/)
-        .map((source) => source.trim())
-        .filter((source) => source.length > 0);
+    return matches.map((match, index) => {
+        const previous = matches[index - 1];
+        const previousEnd = previous === undefined ? undefined : (previous.index ?? 0) + previous[0].length;
+        return {
+            sources: (match[1] ?? '')
+                .split(/\s+/)
+                .map((source) => source.trim())
+                .filter((source) => source.length > 0),
+            alternativeWithPrevious: previousEnd !== undefined &&
+                TERNARY_GAP.test(text.slice(previousEnd, match.index ?? previousEnd)),
+        };
+    });
 }
 /**
  * What this policy allows a WebSocket to reach — `connect-src`, or `default-src` when it is absent.
@@ -55,7 +58,11 @@ function directiveSources(text, directive) {
  * Still undefined when NEITHER is present — a policy that constrains neither is not blocking us.
  */
 function connectSrcSources(text) {
-    return directiveSources(text, 'connect-src') ?? directiveSources(text, 'default-src');
+    const sources = directiveSources(text, 'connect-src') ?? directiveSources(text, 'default-src');
+    return sources?.map(({ sources: sourceList, alternativeWithPrevious }) => ({
+        sources: sourceList.map((source) => source.replace(EXPRESSION_EDGE, '')),
+        alternativeWithPrevious,
+    }));
 }
 /**
  * The problem with this app's `connect-src`, or undefined if there is not one.
@@ -67,15 +74,41 @@ export function cspConnectSrcProblem(text, port) {
     const sources = connectSrcSources(text);
     if (sources === undefined || 0 === sources.length)
         return undefined;
-    if (sources.some((source) => WILDCARDS.includes(source)))
-        return undefined;
     const wanted = bridgeOrigins(port);
+    // Separate CSP policies are all enforced, so every group must admit the bridge. Two occurrences
+    // that are alternate branches of one source-level ternary are not enforced together: either
+    // branch admitting the bridge is enough for that group.
+    const missingByPolicyGroup = [];
+    for (const { sources: sourceList, alternativeWithPrevious } of sources) {
+        const missingFromSourceList = sourceList.some((source) => WILDCARDS.includes(source))
+            ? []
+            : wanted.filter((origin) => !sourceList.includes(origin));
+        if (alternativeWithPrevious) {
+            const previousIndex = missingByPolicyGroup.length - 1;
+            const previousMissing = missingByPolicyGroup[previousIndex];
+            if (previousMissing === undefined) {
+                missingByPolicyGroup.push(missingFromSourceList);
+            }
+            else {
+                // Either complete branch makes this conditional group safe. If both branches block, retain
+                // every origin needed to make either possible policy admit the bridge.
+                missingByPolicyGroup[previousIndex] =
+                    0 === previousMissing.length || 0 === missingFromSourceList.length
+                        ? []
+                        : wanted.filter((origin) => previousMissing.includes(origin) || missingFromSourceList.includes(origin));
+            }
+        }
+        else {
+            missingByPolicyGroup.push(missingFromSourceList);
+        }
+    }
     // BOTH, not either: the SDK picks its host from how the page was served, and a policy that admits
     // one is a coin flip. A coin flip that fails is indistinguishable from every other silent
     // non-connect, which is the whole cost being avoided here.
-    if (wanted.every((origin) => sources.includes(origin)))
+    const blockingGroups = missingByPolicyGroup.filter((missing) => 0 < missing.length);
+    if (0 === blockingGroups.length)
         return undefined;
-    const missing = wanted.filter((origin) => !sources.includes(origin));
+    const missing = wanted.filter((origin) => blockingGroups.some((group) => group.includes(origin)));
     return (`this app declares a Content-Security-Policy whose \`connect-src\` does not admit the Reticle ` +
         `bridge: ${missing.join(' and ')} ${1 === missing.length ? 'is' : 'are'} missing. The browser ` +
         `will block the WebSocket and report it in ITS console only — every check on the Reticle side ` +
@@ -125,7 +158,19 @@ export function cspInlineScriptProblem(text, port) {
     const sources = scriptSrcSources(text);
     if (sources === undefined || 0 === sources.length)
         return undefined;
-    if (!blocksInlineScript(sources))
+    // The same CSP composition rule applies here: any independent blocking policy wins, while a
+    // source-level conditional is safe when either of its mutually exclusive branches permits inline.
+    const policiesThatBlockInlineScript = [];
+    for (const { sources: sourceList, alternativeWithPrevious } of sources) {
+        const blocksInline = blocksInlineScript(sourceList);
+        if (alternativeWithPrevious) {
+            policiesThatBlockInlineScript[policiesThatBlockInlineScript.length - 1] &&= blocksInline;
+        }
+        else {
+            policiesThatBlockInlineScript.push(blocksInline);
+        }
+    }
+    if (!policiesThatBlockInlineScript.some(Boolean))
         return undefined;
     return (`this app declares a Content-Security-Policy whose \`script-src\` does not admit an inline ` +
         `script, so the connect snippet never executes. Nothing on the Reticle side can see this: with ` +
@@ -182,7 +227,7 @@ function withBridgeOrigins(policy, port) {
     }
     // No connect-src: the socket falls back to default-src, so the new directive starts from what
     // default-src already allowed — adding it bare would take 'self' away from every fetch the app does.
-    const fallback = directiveSources(policy, 'default-src') ?? [];
+    const fallback = directiveSources(policy, 'default-src')?.[0]?.sources ?? [];
     const added = ` connect-src ${[...fallback, ...origins].join(' ')}`;
     const trimmed = policy.trimEnd();
     return trimmed.endsWith(';') ? `${trimmed}${added};` : `${trimmed};${added}`;

package/dist/diagnose/init-failure.d.ts

@@ -20,6 +20,8 @@ export declare const InitFailure: {
     readonly APP_CONNECTION: "app_connection";
     readonly BRIDGE_OCCUPIED: "bridge_occupied";
     readonly RUNTIME_ERROR: "runtime_error";
+    /** Ctrl-C (or a SIGTERM) during the runtime phase, before it could say how setup went. */
+    readonly INTERRUPTED: "interrupted";
     readonly OTHER: "other";
 };
 export type InitFailure = (typeof InitFailure)[keyof typeof InitFailure];

package/dist/diagnose/init-failure.js

@@ -20,5 +20,7 @@ export const InitFailure = {
     APP_CONNECTION: 'app_connection',
     BRIDGE_OCCUPIED: 'bridge_occupied',
     RUNTIME_ERROR: 'runtime_error',
+    /** Ctrl-C (or a SIGTERM) during the runtime phase, before it could say how setup went. */
+    INTERRUPTED: 'interrupted',
     OTHER: 'other',
 };

package/dist/gather-plan-input.d.ts

@@ -0,0 +1,11 @@
+import type { InitOptions, InitIo } from './run-types.js';
+import { type PlanInput } from './plan/plan.js';
+/**
+ * The directory the human's agent runs in, when it is not the app's directory.
+ *
+ * `undefined` for a single-package repo, which keeps every agent-file path project-relative exactly
+ * as it was — the two roots are the same there, which is why writing them beside the app went
+ * unnoticed until a repo with its app at `src/admin` reported it.
+ */
+export declare function agentRootOf(options: InitOptions): string | undefined;
+export declare function gatherPlanInput(options: InitOptions, io: InitIo, pkg: unknown): PlanInput;

package/dist/gather-plan-input.js

@@ -0,0 +1,416 @@
+/**
+ * What `reticle init` reads before it plans: every project file, probe and host answer the pure
+ * planner takes, gathered through the injected `InitIo`.
+ *
+ * Split from `run.ts`, which orchestrates the run (plan, apply, report). This is only the read side,
+ * and it writes nothing.
+ */
+import { detectMcpClients } from './register/detect-clients.js';
+import { dirname, join } from 'node:path';
+import { CONTAINER_MARKERS, runsDevServer } from './diagnose/containerised-dev-server.js';
+import { CSP_FILES } from './diagnose/csp-doctor.js';
+import { devScriptBody, discoverPlainViteConfig } from './detect/dev-script.js';
+import { ANGULAR_WORKSPACE_FILE, detect, FORGE_RENDERER_CONFIGS, Framework, } from './detect/detect.js';
+import { ANGULAR_PROXY_PATH, angularEntry } from './patch/angular.js';
+import { HTML_INDEX_PATH, STATIC_GITIGNORE_PATH, STATIC_TOKEN_MODULE, } from './patch/static-page.js';
+import { pickAstroHost } from './patch/astro-host.js';
+import { ELECTRON_VITE_CONFIG_CANDIDATES, NEXT_CONFIG_CANDIDATES, VITE_CONFIG_CANDIDATES, } from './detect/workspace-apps.js';
+import { CURSOR_RULE_PATH, RETICLE_MD_PATH } from './project/agent-rules.js';
+import { CLAUDE_SETTINGS_PATH } from './plan/stop-hook-step.js';
+import { CRA_ENV_PATH } from './patch/cra.js';
+import { findNextMountFile } from './patch/next-patch.js';
+import { tanstackStartConnectPath } from './patch/tanstack-start.js';
+import { installedViteMajor } from './patch/vite-owning-config.js';
+import { RETICLE_CONFIG_FILE } from './plan/plan.js';
+import { claudeAvailableProbe, claudeHasReticle, codexAvailableProbe } from './register/mcp.js';
+import { reticleDevLocation } from './patch/next-patch.js';
+import { scanTestids, storeHints, scanStores } from './detect/capabilities.js';
+import { CLAUDE_PROJECT_CONFIG, CURSOR_PROJECT_MARKER, McpClient } from './register/mcp-clients.js';
+import { deriveProjectId, packageName } from './project/project-id.js';
+import { VITE_DEV_MODULE_PATH, ELECTRON_VITE_DEV_MODULE_PATH, nuxtPluginPath, } from './patch/snippets.js';
+import { NUXT_CONFIG_CANDIDATES } from './patch/nuxt-patch.js';
+import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH } from './register/slash-command.js';
+import { RETICLE_VERSION } from './version.js';
+import { resolveLockfiles } from './detect/lockfiles.js';
+/** CRA's bundled entry, in the order create-react-app itself generates them. */
+const CRA_ENTRY_CANDIDATES = ['src/index.tsx', 'src/index.jsx', 'src/index.ts', 'src/index.js'];
+/** Preview snippets must not mint a real machine credential or imply this token is usable. */
+const DRY_RUN_PAIRING_TOKEN = 'DRY_RUN_TOKEN_NOT_FOR_USE';
+function craEntryOf(io) {
+    for (const path of CRA_ENTRY_CANDIDATES) {
+        const source = io.readFile(path);
+        if (source !== null)
+            return { path, source };
+    }
+    return null;
+}
+const SVELTEKIT_HOOKS = 'src/hooks.client.ts';
+const REACT_ROUTER_ENTRY = 'app/entry.client.tsx';
+const TANSTACK_START_ROOT_CANDIDATES = [
+    'src/routes/__root.tsx',
+    'src/routes/__root.jsx',
+    'app/routes/__root.tsx',
+    'app/routes/__root.jsx',
+];
+const SOURCE_FILE = /\.(tsx|jsx|ts|js|svelte|vue|astro)$/;
+/** Files read for the testid scan. A capabilities block is a hint; reading a whole repo for it is not. */
+const MAX_SCANNED_FILES = 200;
+/** Directories that never hold the app's own source, and are expensive or misleading to read. */
+const NOT_SOURCE_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    'target',
+    'public',
+    'static',
+    '.next',
+    '.svelte-kit',
+    '.nuxt',
+]);
+/** How far below the app root to look. Deep enough for `modules/users/UserList.tsx`, not a repo crawl. */
+const MAX_SCAN_DEPTH = 5;
+/**
+ * Read a bounded set of the app's source files, for the `data-testid` scan.
+ *
+ * This used to walk the fixed list `src, src/components, src/pages, app, components`. Reported from
+ * the field (#318) by a repo whose app is at `src/admin`: the scan read directories that were not
+ * the app's and correctly reported finding nothing in them, so `init` said "no data-testid values
+ * yet" about an app with several — which makes an agent go and write the ones already there. That
+ * list had already grown once for a `frontend/` app, and a third report of the same shape is what
+ * says the answer is not another name in a list. So: walk the app root, bounded by depth and by a
+ * file count.
+ */
+function readSourceFiles(io) {
+    const out = [];
+    const read = (path) => {
+        const content = io.readFile(path);
+        if (content !== null)
+            out.push({ path, source: content });
+    };
+    for (const name of io.rootFiles()) {
+        if (out.length >= MAX_SCANNED_FILES)
+            return out;
+        if (SOURCE_FILE.test(name))
+            read(name);
+    }
+    const walk = (dir, depth) => {
+        for (const name of io.listFiles(dir)) {
+            if (out.length >= MAX_SCANNED_FILES)
+                return;
+            if (SOURCE_FILE.test(name))
+                read(`${dir}/${name}`);
+        }
+        if (depth >= MAX_SCAN_DEPTH)
+            return;
+        for (const sub of io.listDirs(dir)) {
+            if (out.length >= MAX_SCANNED_FILES)
+                return;
+            if (sub.startsWith('.') || NOT_SOURCE_DIRS.has(sub))
+                continue;
+            walk(`${dir}/${sub}`, depth + 1);
+        }
+    };
+    for (const dir of io.listDirs('.')) {
+        if (out.length >= MAX_SCANNED_FILES)
+            return out;
+        if (dir.startsWith('.') || NOT_SOURCE_DIRS.has(dir))
+            continue;
+        walk(dir, 1);
+    }
+    return out;
+}
+/** Direct dependency names, for naming the state libraries an app actually has. */
+function dependencyNames(pkg) {
+    const p = (pkg ?? {});
+    return new Set([
+        ...Object.keys(p['dependencies'] ?? {}),
+        ...Object.keys(p['devDependencies'] ?? {}),
+    ]);
+}
+/** electron-vite and the unbundled Electron layouts this repo already ships. */
+const ELECTRON_MAIN_SOURCES = [
+    'src/main/index.ts',
+    'src/main/index.js',
+    'src/main/index.mts',
+    'src/main/index.mjs',
+    'electron/main.cjs',
+    'electron/main.js',
+    'electron/main.ts',
+    'src/main.ts',
+    'src/main.js',
+];
+const ELECTRON_PRELOAD_SOURCES = [
+    'src/preload/index.ts',
+    'src/preload/index.js',
+    'src/preload/index.mts',
+    'src/preload/index.mjs',
+    'electron/preload.cjs',
+    'electron/preload.js',
+    'electron/preload.ts',
+    'src/preload.ts',
+    'src/preload.js',
+];
+const ASTRO_CONFIG_CANDIDATES = [
+    'astro.config.mjs',
+    'astro.config.js',
+    'astro.config.ts',
+    'astro.config.cjs',
+];
+/** Where a conventional Astro app keeps the layout every page wraps itself in. */
+const ASTRO_LAYOUTS_DIR = 'src/layouts';
+/** Also searched: an app with no layouts directory renders the document straight from a page. */
+const ASTRO_PAGES_DIR = 'src/pages';
+function firstPresent(files, candidates) {
+    for (const c of candidates)
+        if (files.has(c))
+            return c;
+    return null;
+}
+function firstReadable(io, candidates) {
+    for (const path of candidates) {
+        const source = io.readFile(path);
+        if (source !== null)
+            return { path, source };
+    }
+    return null;
+}
+/**
+ * The directory the human's agent runs in, when it is not the app's directory.
+ *
+ * `undefined` for a single-package repo, which keeps every agent-file path project-relative exactly
+ * as it was — the two roots are the same there, which is why writing them beside the app went
+ * unnoticed until a repo with its app at `src/admin` reported it.
+ */
+export function agentRootOf(options) {
+    const root = options.agentRoot;
+    return root === undefined || root === options.cwd ? undefined : root;
+}
+/** What the Angular steps read: the workspace file, the entry it names, and our proxy module. */
+function angularInputs(io) {
+    const workspace = io.readFile(ANGULAR_WORKSPACE_FILE);
+    const entryPath = angularEntry(workspace);
+    const entry = io.readFile(entryPath);
+    return {
+        angularWorkspace: null === workspace ? null : { path: ANGULAR_WORKSPACE_FILE, source: workspace },
+        angularEntry: null === entry ? null : { path: entryPath, source: entry },
+        angularProxySource: io.readFile(ANGULAR_PROXY_PATH),
+    };
+}
+export function gatherPlanInput(options, io, pkg) {
+    // Stable identity derived from the app's package.json name + root, so it survives port changes.
+    const projectId = deriveProjectId(packageName(pkg), options.cwd);
+    const rootFiles = new Set(io.rootFiles());
+    const nodeModulesMarkers = new Set(io.listFiles('node_modules'));
+    const detectInput = {
+        pkg: 'object' === typeof pkg && pkg !== null ? pkg : {},
+        configFiles: rootFiles,
+        // Walk up for the lockfile so a monorepo sub-package picks the workspace's package manager —
+        // unless this package's own installed tree already answers it, which outranks an inherited one.
+        lockfiles: resolveLockfiles(rootFiles, options.cwd, io, nodeModulesMarkers),
+        // An already-installed tree names its own manager, which matters when no lockfile is committed.
+        nodeModulesMarkers,
+    };
+    const detection = detect(detectInput);
+    const nodeModulesLinked = true === io.isSymlink?.('node_modules');
+    // Forge has no `vite.config.*`; its renderer config IS the Vite config the plugin belongs in, and
+    // handing it over under that name is what lets the ordinary Vite patcher do the work.
+    const plainViteConfig = Framework.VITE === detection.framework
+        ? discoverPlainViteConfig(io, pkg, rootFiles, VITE_CONFIG_CANDIDATES)
+        : undefined;
+    const vitePath = firstPresent(rootFiles, Framework.ELECTRON_FORGE === detection.framework
+        ? FORGE_RENDERER_CONFIGS
+        : VITE_CONFIG_CANDIDATES);
+    const viteSource = null === vitePath ? null : io.readFile(vitePath);
+    const viteConfig = plainViteConfig === undefined
+        ? vitePath !== null && viteSource !== null
+            ? { path: vitePath, source: viteSource }
+            : null
+        : plainViteConfig.config;
+    const electronVitePath = firstPresent(rootFiles, ELECTRON_VITE_CONFIG_CANDIDATES);
+    const electronViteSource = null === electronVitePath ? null : io.readFile(electronVitePath);
+    const electronViteConfig = electronVitePath !== null && electronViteSource !== null
+        ? { path: electronVitePath, source: electronViteSource }
+        : null;
+    const electronMain = firstReadable(io, ELECTRON_MAIN_SOURCES);
+    const electronPreload = firstReadable(io, ELECTRON_PRELOAD_SOURCES);
+    // Global MCP registration targets each agent that's present: Claude via its CLI, Cursor via its
+    // global config file. Only probe when the MCP step is in play.
+    const availableProbe = claudeAvailableProbe();
+    const claudeCli = options.mcp ? io.probe(availableProbe.command, availableProbe.args) : false;
+    // Read from Claude's config, never `claude mcp get`: that launches the server — see claudeHasReticle.
+    const mcpExists = claudeCli ? claudeHasReticle(io, io.cwd()) : false;
+    // Every MCP client this machine shows evidence of. Conservative and one-directional: we write
+    // into a config a client ALREADY has, and never create ~/.gemini or ~/.codeium for somebody who
+    // does not use them.
+    const detectedClients = options.mcp ? detectMcpClients(io) : [];
+    // Codex registers through its own CLI when there is one. Asked only after Codex was FOUND: the
+    // probe runs a binary, and a machine with no Codex has no business running one.
+    const codexProbe = codexAvailableProbe();
+    const codexCli = detectedClients.some((client) => McpClient.CODEX === client.id)
+        ? io.probe(codexProbe.command, codexProbe.args)
+        : false;
+    const astroPath = firstPresent(rootFiles, ASTRO_CONFIG_CANDIDATES);
+    const astroSource = null === astroPath ? null : io.readFile(astroPath);
+    // Which file owns the DOCUMENT, not how many files sit in a directory. The old rule ("exactly one
+    // .astro in src/layouts") fired on neither real Astro app: one has no layouts directory and
+    // renders from src/pages/index.astro, the other has three files there of which two are partials.
+    // `</body>` is the discriminator — see astro-host.
+    const astroCandidates = [ASTRO_LAYOUTS_DIR, ASTRO_PAGES_DIR].flatMap((dir) => io
+        .listFiles(dir)
+        .filter((f) => f.endsWith('.astro'))
+        .map((f) => ({ path: `${dir}/${f}`, source: io.readFile(`${dir}/${f}`) }))
+        .filter((c) => c.source !== null));
+    const astroHost = pickAstroHost(astroCandidates);
+    const layoutRelPath = astroHost?.path ?? null;
+    const astroLayoutSource = astroHost?.source ?? null;
+    const nuxtConfigPath = firstPresent(rootFiles, NUXT_CONFIG_CANDIDATES);
+    const nuxtConfigSource = null === nuxtConfigPath ? null : io.readFile(nuxtConfigPath);
+    // Nuxt 4's default srcDir is `app/`, Nuxt 3's is the root — and a plugin written into the
+    // directory Nuxt does not scan is never registered, silently.
+    const nuxtHasAppDir = io.listDirs('.').includes('app');
+    const nextConfigFile = firstPresent(rootFiles, NEXT_CONFIG_CANDIDATES);
+    // App Router first, route groups included (#1538); a Pages Router app mounts in pages/_app.
+    const nextMount = findNextMountFile(io);
+    const layoutPath = nextMount.path;
+    const layoutSource = null === layoutPath ? null : io.readFile(layoutPath);
+    // Where the component goes depends on WHICH router mounts it: `pages/` routes on presence, so a
+    // component there becomes a broken route; `app/` routes on filename, so a sibling is inert.
+    const devLocation = reticleDevLocation(layoutPath ?? 'app/layout.tsx', detection.typescript);
+    // Read once: both the testid scan and the store scan want the same bounded set of files.
+    const sourceFiles = readSourceFiles(io);
+    const agentRoot = agentRootOf(options);
+    const agentFile = (relPath) => agentRoot === undefined ? relPath : join(agentRoot, relPath);
+    const cspSources = {};
+    for (const file of CSP_FILES) {
+        const source = io.readFile(file);
+        if (null !== source)
+            cspSources[file] = source;
+    }
+    return {
+        detection,
+        ...(nodeModulesLinked ? { nodeModulesLinked } : {}),
+        captureBodies: options.captureBodies,
+        hooks: options.hooks,
+        cspSources,
+        claudeCli,
+        mcpExists,
+        insideClaudeCode: io.host.insideClaudeCode(),
+        claudeProjectConfig: options.mcp ? io.readFile(agentFile(CLAUDE_PROJECT_CONFIG)) : undefined,
+        platform: process.platform,
+        detectedClients,
+        codexCli,
+        cursorProjectPresent: io.exists(CURSOR_PROJECT_MARKER),
+        // Looked for beside the app AND one level up, because the app is routinely a subdirectory of the
+        // repo that containerises it — `frontend/` under a root `docker-compose.yml` is the shape this
+        // came from. Only the first match is reported; the note is the same whichever file found it.
+        ...(() => {
+            // Only a file that RUNS the dev server: a production-only image is the common case, and
+            // React Router's template ships one. See runsDevServer.
+            const devScript = devScriptBody(pkg);
+            const marker = CONTAINER_MARKERS.find((name) => [name, join('..', name)].some((path) => {
+                const content = io.readFile(path);
+                return null !== content && runsDevServer(name, content, devScript);
+            }));
+            return marker === undefined ? {} : { containerMarker: marker };
+        })(),
+        viteConfig,
+        viteConfigCandidates: plainViteConfig?.candidates,
+        electronViteConfig,
+        electronPreload,
+        electronMain,
+        astroConfig: astroPath !== null && astroSource !== null ? { path: astroPath, source: astroSource } : null,
+        astroLayout: layoutRelPath !== null && astroLayoutSource !== null
+            ? { path: layoutRelPath, source: astroLayoutSource }
+            : null,
+        astroEnvDts: io.readFile('src/env.d.ts'),
+        astroReticleDev: io.readFile('src/components/ReticleDev.ts'),
+        nextConfigFile,
+        nextConfigSource: null === nextConfigFile ? null : io.readFile(nextConfigFile),
+        nextLayout: layoutPath !== null && layoutSource !== null
+            ? { path: layoutPath, source: layoutSource }
+            : null,
+        // Capabilities: scanned, never asked for. Bounded — a hint for the agent, not a repo index.
+        nextLayoutCandidates: nextMount.candidates,
+        testids: scanTestids(sourceFiles.map((f) => f.source)),
+        storeHints: storeHints(dependencyNames(pkg), sourceFiles),
+        foundStores: scanStores(sourceFiles, dependencyNames(pkg)),
+        nextFoundStores: scanStores(sourceFiles, dependencyNames(pkg), dirname(devLocation.path)),
+        viteDevModuleExists: io.exists(detection.framework === Framework.ELECTRON_VITE
+            ? ELECTRON_VITE_DEV_MODULE_PATH
+            : VITE_DEV_MODULE_PATH),
+        nextReticleDevPath: devLocation.path,
+        nextReticleDevImport: devLocation.importSpecifier,
+        nextReticleDevExists: io.exists(devLocation.path),
+        nextReticleDevSource: io.readFile(devLocation.path),
+        svelteKitHooksExists: io.exists(SVELTEKIT_HOOKS),
+        svelteKitHooksSource: io.readFile(SVELTEKIT_HOOKS),
+        reactRouterEntryExists: io.exists(REACT_ROUTER_ENTRY),
+        // The SOURCE, so an entry the app already owns is ADDED TO rather than replaced — it is an
+        // override of React Router's default, and everything in it is load-bearing.
+        reactRouterEntrySource: io.readFile(REACT_ROUTER_ENTRY),
+        nuxtConfig: nuxtConfigPath !== null && nuxtConfigSource !== null
+            ? { path: nuxtConfigPath, source: nuxtConfigSource }
+            : null,
+        nuxtHasAppDir,
+        viteMajor: installedViteMajor(io, detectInput.pkg),
+        nuxtPluginExists: io.exists(nuxtPluginPath(nuxtHasAppDir)),
+        nuxtPluginSource: io.readFile(nuxtPluginPath(nuxtHasAppDir)),
+        ...(() => {
+            const root = TANSTACK_START_ROOT_CANDIDATES.find((file) => io.exists(file));
+            return root === undefined
+                ? {}
+                : {
+                    tanstackStartRoot: root,
+                    tanstackStartRootSource: io.readFile(root),
+                    tanstackStartConnectExists: io.exists(tanstackStartConnectPath(root)),
+                    tanstackStartConnectSource: io.readFile(tanstackStartConnectPath(root)),
+                };
+        })(),
+        ...(Framework.ANGULAR === detection.framework ? angularInputs(io) : {}),
+        ...(Framework.HTML === detection.framework
+            ? {
+                htmlIndexSource: io.readFile(HTML_INDEX_PATH),
+                htmlLocalSources: {
+                    [STATIC_TOKEN_MODULE]: io.readFile(STATIC_TOKEN_MODULE),
+                    [STATIC_GITIGNORE_PATH]: io.readFile(STATIC_GITIGNORE_PATH),
+                },
+            }
+            : {}),
+        craEntry: craEntryOf(io),
+        craEnv: io.readFile(CRA_ENV_PATH),
+        pairingToken: options.dryRun ? DRY_RUN_PAIRING_TOKEN : io.host.pairingToken(),
+        installSource: io.host.installSource(),
+        reticleConfigExists: io.exists(RETICLE_CONFIG_FILE),
+        // The CONTENT, so a config that exists can be checked rather than trusted — a `"port"` set to
+        // the app's own dev-server port used to survive every re-run of `init`.
+        reticleConfigSource: io.readFile(RETICLE_CONFIG_FILE),
+        // Read the agent instruction files so the rule merge stays idempotent across re-runs — from the
+        // agent's own root, or the merge would idempotently check a file it is not going to write.
+        claudeMdContent: io.readFile(agentFile('CLAUDE.md')),
+        agentsMdContent: io.readFile(agentFile('AGENTS.md')),
+        reticleMdContent: io.readFile(agentFile(RETICLE_MD_PATH)),
+        cursorRuleContent: io.readFile(agentFile(CURSOR_RULE_PATH)),
+        claudeCommandContent: io.readFile(agentFile(CLAUDE_COMMAND_PATH)),
+        cursorCommandContent: io.readFile(agentFile(CURSOR_COMMAND_PATH)),
+        // Read only to MERGE into: the settings file is the user's, and other tools write in it too.
+        claudeSettingsContent: io.readFile(agentFile(CLAUDE_SETTINGS_PATH)),
+        ...(agentRoot === undefined
+            ? {}
+            : {
+                agentFileRoot: agentRoot,
+                // The config the AGENT's cwd already has, if any — see agentRootConfigStep.
+                agentRootConfigSource: io.readFile(agentFile(RETICLE_CONFIG_FILE)),
+                agentRootSeveralApps: true === options.severalApps,
+            }),
+        options: {
+            port: options.port,
+            mcp: options.mcp,
+            install: options.install,
+            projectId,
+            // The SDK must match the CLI asking for it — see pinnedPackages.
+            sdkVersion: RETICLE_VERSION,
+        },
+    };
+}