@reticlehq/init 3.7.0 → 3.8.0

package/dist/detect/detect.d.ts

@@ -122,6 +122,13 @@ export interface Detection {
      * require-hook down with it and the dev server never starts.
      */
     typescript: boolean;
+    /**
+     * Whether the project uses Prettier (config file or package.json "prettier" key).
+     * Used by `init` to decide whether to add `.reticle/` to `.prettierignore` (#1560).
+     *
+     * Optional so existing test fixtures keep compiling without naming it; `detect` always sets it.
+     */
+    usesPrettier?: boolean | undefined;
     reactMajor: number | undefined;
     /**
      * `react-scripts`' major, when the project has it. `undefined` on every other stack.
@@ -251,6 +258,8 @@ export declare function parseMajor(range: string | undefined): number | undefine
  */
 export declare function namesAPackageManager(markers: ReadonlySet<string>): boolean;
 export declare function detectPackageManager(lockfiles: ReadonlySet<string>, nodeModulesMarkers: ReadonlySet<string>, pkg?: unknown): PackageManager;
+/** The file that makes a project TypeScript to its tooling, Next and Vite included. */
+export declare const TSCONFIG_FILE = "tsconfig.json";
 export declare function detect(input: DetectInput): Detection;
 interface InstallCommand {
     command: string;

package/dist/detect/detect.js

@@ -2,6 +2,7 @@
  * Pure framework + toolchain detection for `reticle init`. No filesystem access — callers pass in
  * the parsed package.json and the set of config/lock filenames present in the project root.
  */
+import { hasPrettierConfig } from './prettier-config.js';
 export const Framework = {
     NEXT: 'next',
     /**
@@ -353,7 +354,9 @@ function detectUiLibrary(pkg) {
         return UiLibrary.SVELTE;
     return UiLibrary.UNKNOWN;
 }
-const TS_CONFIGS = ['tsconfig.json'];
+/** The file that makes a project TypeScript to its tooling, Next and Vite included. */
+export const TSCONFIG_FILE = 'tsconfig.json';
+const TS_CONFIGS = [TSCONFIG_FILE];
 export function detect(input) {
     const reactMajor = parseMajor(depVersion(input.pkg, 'react'));
     return {
@@ -362,6 +365,7 @@ export function detect(input) {
         uiLibrary: detectUiLibrary(input.pkg),
         typescript: hasAnyConfig(input.configFiles, TS_CONFIGS) ||
             depVersion(input.pkg, 'typescript') !== undefined,
+        usesPrettier: hasPrettierConfig(input.configFiles, input.pkg),
         reactMajor,
         needsSourceMapping: reactMajor !== undefined && reactMajor >= 19,
         customReconciler: CUSTOM_RECONCILER_DEPS.some((name) => depVersion(input.pkg, name) !== undefined),

package/dist/detect/dev-server-ports.d.ts

@@ -15,6 +15,8 @@
  * on the server side changed.
  */
 export declare const DEV_SERVER_PORTS: ReadonlySet<number>;
+/** The framework's default dev-server port, or undefined for one that has none of its own. */
+export declare function frameworkDevPort(framework: string): number | undefined;
 export declare function isLikelyDevServerPort(port: number): boolean;
 /** The warning printed when a project pins the bridge to something that looks like its dev server. */
 export declare function devServerPortWarning(port: number): string;

package/dist/detect/dev-server-ports.js

@@ -1,3 +1,4 @@
+import { Framework } from './detect.js';
 /**
  * Ports that belong to a DEV SERVER, not to Reticle's bridge. Next defaults to 3000, Vite to 5173,
  * Astro to 4321, and so on.
@@ -44,6 +45,25 @@ export const DEV_SERVER_PORTS = new Set([
     6006, // Storybook
     19006, // Expo web
 ]);
+/**
+ * The port each framework's dev server takes when nothing configures another. Every value is in
+ * {@link DEV_SERVER_PORTS} as well. `reticle setup` reads it to know which port a dev script will
+ * take before starting one, so a server already on half of that port is found first (#1377).
+ */
+const FRAMEWORK_DEV_PORTS = {
+    [Framework.VITE]: 5173,
+    [Framework.SVELTEKIT]: 5173,
+    [Framework.REACT_ROUTER]: 5173,
+    [Framework.NEXT]: 3000,
+    [Framework.NUXT]: 3000,
+    [Framework.CRA]: 3000,
+    [Framework.ASTRO]: 4321,
+    [Framework.ANGULAR]: 4200,
+};
+/** The framework's default dev-server port, or undefined for one that has none of its own. */
+export function frameworkDevPort(framework) {
+    return FRAMEWORK_DEV_PORTS[framework];
+}
 export function isLikelyDevServerPort(port) {
     return DEV_SERVER_PORTS.has(port);
 }

package/dist/detect/prettier-config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Detecting whether a project uses Prettier.
+ *
+ * Lives in `detect/` (not `patch/`) because `patch/` already imports from `detect/` —
+ * the reverse import would create a `detect <-> patch` cycle that
+ * `directory-reach.test.ts` forbids. Detection belongs here anyway.
+ */
+interface PackageJsonLike {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    prettier?: unknown;
+}
+/** Filenames that indicate the project uses Prettier. */
+export declare const PRETTIER_CONFIG_FILES: Set<string>;
+/**
+ * True when the project uses Prettier: a Prettier config file exists at the root,
+ * package.json declares a "prettier" key, or prettier is in (dev)dependencies.
+ */
+export declare function hasPrettierConfig(rootFiles: ReadonlySet<string>, pkg: PackageJsonLike): boolean;
+export {};

package/dist/detect/prettier-config.js

@@ -0,0 +1,38 @@
+/**
+ * Detecting whether a project uses Prettier.
+ *
+ * Lives in `detect/` (not `patch/`) because `patch/` already imports from `detect/` —
+ * the reverse import would create a `detect <-> patch` cycle that
+ * `directory-reach.test.ts` forbids. Detection belongs here anyway.
+ */
+/** Filenames that indicate the project uses Prettier. */
+export const PRETTIER_CONFIG_FILES = new Set([
+    '.prettierrc',
+    '.prettierrc.json',
+    '.prettierrc.yml',
+    '.prettierrc.yaml',
+    '.prettierrc.json5',
+    '.prettierrc.js',
+    '.prettierrc.cjs',
+    '.prettierrc.mjs',
+    '.prettierrc.ts',
+    'prettier.config.js',
+    'prettier.config.cjs',
+    'prettier.config.mjs',
+    'prettier.config.ts',
+]);
+/**
+ * True when the project uses Prettier: a Prettier config file exists at the root,
+ * package.json declares a "prettier" key, or prettier is in (dev)dependencies.
+ */
+export function hasPrettierConfig(rootFiles, pkg) {
+    for (const name of rootFiles) {
+        if (PRETTIER_CONFIG_FILES.has(name))
+            return true;
+    }
+    if (pkg.prettier !== undefined)
+        return true;
+    return (pkg.dependencies?.prettier !== undefined ||
+        pkg.devDependencies?.prettier !== undefined ||
+        pkg.peerDependencies?.prettier !== undefined);
+}

package/dist/detect/workspace-redirect.js

@@ -12,6 +12,7 @@ import { join } from 'node:path';
 import { detect, Framework } from './detect.js';
 import { detectNonJsEcosystem, noPackageJsonMessage } from './non-js-project.js';
 import { findAppsBelow, findWorkspaceApps, PACKAGE_JSON, workspacePackageDirs, } from './workspace-apps.js';
+import { devScriptBody } from './dev-script.js';
 import { projectIdOf, RETICLE_CONFIG_FILE } from './existing-config.js';
 import { chooseWorkspaceApp, withoutTrailingSlashes } from './declared/app-choice.js';
 const ROOT_CONFIG_LEAD = `This root's ${RETICLE_CONFIG_FILE} names`;
@@ -39,14 +40,17 @@ function inHome(io) {
     return trim(io.cwd()) === trim(io.homeDir());
 }
 /** Print the candidates as commands to paste, and stop: the choice is the person's. */
-function listApps(io, header, apps) {
-    io.print(header);
+function printAppCommands(io, apps) {
     for (const a of apps) {
         const displayed = displayedWorkspaceAppCommand(a, process.platform);
         if (displayed.label !== undefined)
             io.print(`  ${displayed.label}`);
         io.print(`  ${displayed.command}`);
     }
+}
+function listApps(io, header, apps) {
+    io.print(header);
+    printAppCommands(io, apps);
     return { ok: false, applied: 0, manual: apps.length, listedAppsBelow: true };
 }
 const WORKSPACE_APP_COMMAND = 'reticle init --app';
@@ -126,6 +130,22 @@ export function redirectToWorkspaceApp(options, io, pkg, runInit) {
     const pointed = appNamedByRootConfig(io);
     if (pointed !== undefined)
         return enterApp(options, io, pointed, ROOT_CONFIG_LEAD, runInit);
+    // A plain page with a manifest that has a dev script is the app too: it renders through its own
+    // index.html, and the dev script that serves it lives in its package.json. A manifest that holds
+    // only tooling is not enough: the real app may sit in a nested folder, so discovery still runs.
+    //
+    // Discovery preferred a nested copy - a `backup/` folder holding another app - over the folder the
+    // person is standing in, and `init --dry-run` named the copy as the target. A root pointer stored
+    // by an earlier `--app` run is read first, above. Past that, the nested app is something to LIST,
+    // never to choose; the root is wired by the normal plan after this null.
+    if (io.exists(STATIC_PAGE) && io.exists(PACKAGE_JSON) && devScriptBody(pkg) !== undefined) {
+        const nested = findWorkspaceApps(io);
+        if (0 < nested.length) {
+            io.print(WIRE_ANOTHER);
+            printAppCommands(io, nested);
+        }
+        return null;
+    }
     const apps = findWorkspaceApps(io);
     // An explicitly named app answers the ambiguity. Refusing to guess is right, but "re-run inside the
     // one you want" is not something a script, a CI step, or an agent that cannot change directory can
@@ -159,12 +179,7 @@ export function redirectToWorkspaceApp(options, io, pkg, runInit) {
         const rest = apps.filter((a) => !wired.includes(a));
         if (0 < wired.length && 0 < rest.length)
             io.print(WIRE_ANOTHER);
-        for (const a of 0 === wired.length ? apps : rest) {
-            const displayed = displayedWorkspaceAppCommand(a, process.platform);
-            if (displayed.label !== undefined)
-                io.print(`  ${displayed.label}`);
-            io.print(`  ${displayed.command}`);
-        }
+        printAppCommands(io, 0 === wired.length ? apps : rest);
         return 0 === wired.length
             ? { ok: false, applied: 0, manual: apps.length }
             : { ok: true, applied: 0, manual: 0 };

package/dist/diagnose/closing-hint.d.ts

@@ -16,6 +16,11 @@ import { StepStatus } from '../plan/plan.js';
  * the workspace redirect is kept from asking twice.
  */
 export declare const FEEDBACK_HINT: string;
+/**
+ * The last line of a successful `init`, after the ask: where the user can tell the maintainers what
+ * they build. Only on success: on a failure, the ask above is the thing to do.
+ */
+export declare const COMMUNITY_HINT = "Tell us what you are building: https://discord.gg/BwAbzv9ZRz";
 /**
  * The last two lines a user reads, and the order matters.
  *

package/dist/diagnose/closing-hint.js

@@ -5,6 +5,7 @@
  * and this decides what to say afterwards. The failure modes differ too — a wrong write breaks an
  * install, a wrong sentence loses a user quietly.
  */
+import { FEEDBACK_KIND_CHOICES } from '@reticlehq/core';
 import { StepStatus } from '../plan/plan.js';
 import { wasMcpRegistered } from '../register/mcp-registered.js';
 import { CLI } from '../project/agent-rules.js';
@@ -19,12 +20,15 @@ import { CLI } from '../project/agent-rules.js';
  */
 export const FEEDBACK_HINT = 'Anything wrong, missing, or awkward — in this setup or in Reticle itself? Tell us; it is the ' +
     'one thing that decides what gets fixed:\n' +
-    `  ${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"   (agents)\n` +
+    `  ${CLI} feedback --agent --kind ${FEEDBACK_KIND_CHOICES} "what happened"   (agents)\n` +
     `  ${CLI} feedback "what worked, what didn't"   (humans)`;
+/**
+ * The last line of a successful `init`, after the ask: where the user can tell the maintainers what
+ * they build. Only on success: on a failure, the ask above is the thing to do.
+ */
+export const COMMUNITY_HINT = 'Tell us what you are building: https://discord.gg/BwAbzv9ZRz';
 /** 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 ' +
@@ -33,9 +37,12 @@ const RestartHintCopy = {
         '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; ' +
+    CLOSING_NO_MCP: 'Once it shows a session, drive one flow and report the verdict — that is the install finished.',
+    CLOSING_ALREADY_NO_MANUAL: 'Once it shows a session, drive one flow and report the verdict — 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 ' +
+    CLOSING_ALREADY_WITH_MANUAL: 'Once it shows a session, drive one flow and report the verdict 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.',
 };
@@ -100,13 +107,14 @@ manualClients = []) {
     //
     // 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 = RestartHintCopy.DEMO;
+    // install that ends in nothing. It is said ONCE, last: after the status check and after the client
+    // restart, because that is the order in which a reader can do it.
     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))
-        return `${dev}\n${demo}\n${prove}`;
+    if (!wasMcpRegistered(mcpStatus)) {
+        return `${dev}\n${prove}\n${RestartHintCopy.CLOSING_NO_MCP}`;
+    }
     // ALREADY: the tools are reachable RIGHT NOW, and this is the branch that used to lie.
     //
     // `wasMcpRegistered` is true for both APPLY and ALREADY, which is wrong here: the two cases have
@@ -125,10 +133,9 @@ manualClients = []) {
         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${availability}\n${prove}\n${closing}`;
     }
     return (`${dev}\n` +
-        `${demo}\n` +
         'Then restart your agent so it picks up the new MCP server. On Claude Code and Codex, do NOT ' +
         'ask a human to do it: `npx @reticlehq/server init --relaunch` prints the exact resume command ' +
         'for THIS conversation — run that command and the restart continues the work on the other ' +

package/dist/gather-plan-input.js

@@ -10,20 +10,22 @@ 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_WORKSPACE_FILE, detect, FORGE_RENDERER_CONFIGS, Framework, TSCONFIG_FILE, } 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 { PromptHookAgent, promptHookTargets, } from './register/prompt-hooks.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 { PRETTIERIGNORE_PATH } from './patch/prettier-ignore.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 { nextUsesTypeScript, 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';
@@ -32,6 +34,7 @@ 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';
+import { projectIdOf } from './detect/existing-config.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. */
@@ -39,8 +42,9 @@ 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)
+        if (source !== null) {
             return { path, source };
+        }
     }
     return null;
 }
@@ -82,41 +86,58 @@ const MAX_SCAN_DEPTH = 5;
  * says the answer is not another name in a list. So: walk the app root, bounded by depth and by a
  * file count.
  */
+/** The files that quote `id` as a whole string literal (see `copiedIdSources`). */
+function quoting(files, id) {
+    if (id === undefined) {
+        return [];
+    }
+    return files.filter((f) => ['"', "'", '`'].some((q) => f.source.includes(`${q}${id}${q}`)));
+}
 function readSourceFiles(io) {
     const out = [];
     const read = (path) => {
         const content = io.readFile(path);
-        if (content !== null)
+        if (content !== null) {
             out.push({ path, source: content });
+        }
     };
     for (const name of io.rootFiles()) {
-        if (out.length >= MAX_SCANNED_FILES)
+        if (out.length >= MAX_SCANNED_FILES) {
             return out;
-        if (SOURCE_FILE.test(name))
+        }
+        if (SOURCE_FILE.test(name)) {
             read(name);
+        }
     }
     const walk = (dir, depth) => {
         for (const name of io.listFiles(dir)) {
-            if (out.length >= MAX_SCANNED_FILES)
+            if (out.length >= MAX_SCANNED_FILES) {
                 return;
-            if (SOURCE_FILE.test(name))
+            }
+            if (SOURCE_FILE.test(name)) {
                 read(`${dir}/${name}`);
+            }
         }
-        if (depth >= MAX_SCAN_DEPTH)
+        if (depth >= MAX_SCAN_DEPTH) {
             return;
+        }
         for (const sub of io.listDirs(dir)) {
-            if (out.length >= MAX_SCANNED_FILES)
+            if (out.length >= MAX_SCANNED_FILES) {
                 return;
-            if (sub.startsWith('.') || NOT_SOURCE_DIRS.has(sub))
+            }
+            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)
+        if (out.length >= MAX_SCANNED_FILES) {
             return out;
-        if (dir.startsWith('.') || NOT_SOURCE_DIRS.has(dir))
+        }
+        if (dir.startsWith('.') || NOT_SOURCE_DIRS.has(dir)) {
             continue;
+        }
         walk(dir, 1);
     }
     return out;
@@ -163,16 +184,19 @@ 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))
+    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)
+        if (source !== null) {
             return { path, source };
+        }
     }
     return null;
 }
@@ -277,16 +301,20 @@ export function gatherPlanInput(options, io, pkg) {
     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);
+    // And which LANGUAGE it is written in follows Next's rule, not `detection.typescript`: a
+    // `typescript` devDependency in a jsconfig app is not a TypeScript project to Next (#1527).
+    const devLocation = reticleDevLocation(layoutPath ?? 'app/layout.tsx', nextUsesTypeScript(layoutPath, rootFiles.has(TSCONFIG_FILE)));
     // Read once: both the testid scan and the store scan want the same bounded set of files.
     const sourceFiles = readSourceFiles(io);
+    const copiedId = projectIdOf(io.readFile(RETICLE_CONFIG_FILE));
     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)
+        if (null !== source) {
             cspSources[file] = source;
+        }
     }
     return {
         detection,
@@ -294,6 +322,7 @@ export function gatherPlanInput(options, io, pkg) {
         captureBodies: options.captureBodies,
         hooks: options.hooks,
         cspSources,
+        prettierIgnoreSource: io.readFile(PRETTIERIGNORE_PATH),
         claudeCli,
         mcpExists,
         insideClaudeCode: io.host.insideClaudeCode(),
@@ -333,6 +362,7 @@ export function gatherPlanInput(options, io, pkg) {
             : null,
         // Capabilities: scanned, never asked for. Bounded — a hint for the agent, not a repo index.
         nextLayoutCandidates: nextMount.candidates,
+        nextUnmountedLayouts: nextMount.unmounted,
         testids: scanTestids(sourceFiles.map((f) => f.source)),
         storeHints: storeHints(dependencyNames(pkg), sourceFiles),
         foundStores: scanStores(sourceFiles, dependencyNames(pkg)),
@@ -386,6 +416,7 @@ export function gatherPlanInput(options, io, pkg) {
         // 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),
+        ...(true === options.newId ? { copiedIdSources: quoting(sourceFiles, copiedId) } : {}),
         // 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')),
@@ -396,6 +427,11 @@ export function gatherPlanInput(options, io, pkg) {
         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)),
+        ...promptHookInput(io, options, claudeCli, agentFile),
+        ...(() => {
+            const bin = io.host.hookBin?.();
+            return bin === undefined ? {} : { hookBin: bin };
+        })(),
         ...(agentRoot === undefined
             ? {}
             : {
@@ -409,8 +445,24 @@ export function gatherPlanInput(options, io, pkg) {
             mcp: options.mcp,
             install: options.install,
             projectId,
+            ...(true === options.newId ? { newId: true } : {}),
             // The SDK must match the CLI asking for it — see pinnedPackages.
             sdkVersion: RETICLE_VERSION,
         },
     };
 }
+/**
+ * Which agents get the prompt-capture hook, and what their configs hold now. Rides with the agent
+ * wiring, so `--no-mcp` skips it as it skips the rule files. Claude Code's entry is merged with the
+ * other hooks in `.claude/settings.json`, so it is a flag here and not a target.
+ */
+function promptHookInput(io, options, claudeCli, agentFile) {
+    if (!options.mcp || false === options.promptCapture) {
+        return { claudePromptHook: false, promptHooks: [] };
+    }
+    const targets = promptHookTargets(io, agentFile('.'), io.homeDir(), claudeCli, join);
+    return {
+        claudePromptHook: targets.some((t) => PromptHookAgent.CLAUDE_CODE === t.spec.id),
+        promptHooks: targets.filter((t) => PromptHookAgent.CLAUDE_CODE !== t.spec.id),
+    };
+}

package/dist/host.d.ts

@@ -49,6 +49,12 @@ export interface InitHost {
      * which the scaffolder does not read for itself.
      */
     insideClaudeCode(): boolean;
+    /**
+     * The installed CLI's bin, for hook commands that run it with node and skip npx's start. Under
+     * the home folder it is written `$HOME/...`, so no user name lands in a committed file. Undefined
+     * where a direct command is not wanted (Windows shells), and the hooks use npx alone.
+     */
+    hookBin?(): string | undefined;
 }
 /**
  * A host that does nothing, for callers that drive `init`'s file surface without running an install

package/dist/index.d.ts

@@ -20,12 +20,12 @@ export { runInit, resolveLockfiles, type InitIo, type InitOptions, type InitResu
 export { windowsShellArg } from './register/windows-quote.js';
 export { buildNodeIo, probeCli } from './node-io.js';
 export { terminalWidth, wrapForTerminal } from './diagnose/terminal-wrap.js';
-export { FEEDBACK_HINT } from './diagnose/closing-hint.js';
+export { COMMUNITY_HINT, FEEDBACK_HINT } from './diagnose/closing-hint.js';
 export { type InitHost, SILENT_HOST } from './host.js';
 export { RETICLE_VERSION, RETICLE_NPM_PACKAGE } from './version.js';
 export { InitFailure } from './diagnose/init-failure.js';
 export { NodePlatform } from './detect/platform.js';
-export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning, } from './detect/dev-server-ports.js';
+export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning, frameworkDevPort, } from './detect/dev-server-ports.js';
 export { configWithInstallSource } from './project/install-source-config.js';
 export { projectIdOf, rememberProjectOnDisk, type RegistryIo } from './project/remember-project.js';
 export { detectPackageManager, Framework, installCommandParts, parseMajor, PackageManager, } from './detect/detect.js';
@@ -50,3 +50,9 @@ export { McpClient, ConfigScope, MCP_CLIENTS, ClientMergeStatus, clientSpec, mer
 export { claudeAddCommand, claudeAvailableProbe, claudeHasReticle, codexAddCommand, codexAvailableProbe, } from './register/mcp.js';
 export { codexNamesOurServer } from './register/codex-toml.js';
 export { detectMcpClients, type DetectedClient } from './register/detect-clients.js';
+/**
+ * The prompt-capture hook, for `reticle hook install|uninstall|status` and `reticle doctor`: the
+ * same agent table and the same merge `init` uses, so the two cannot disagree about an agent.
+ */
+export { AGENT_FLAG, MCP_FALLBACK_AGENTS, PROMPT_HOOK_AGENTS, PromptHookAgent, PromptHookStatus, installPromptHook, promptHookCommand, promptHookInstalled, promptHookNpxOnly, promptHookTargets, uninstallPromptHook, type PromptHookSpec, type PromptHookTarget, } from './register/prompt-hooks.js';
+export { PROMPT_CAPTURE_NOTICE } from './plan/stop-hook-step.js';

package/dist/index.js

@@ -20,12 +20,12 @@ export { runInit, resolveLockfiles, } from './run.js';
 export { windowsShellArg } from './register/windows-quote.js';
 export { buildNodeIo, probeCli } from './node-io.js';
 export { terminalWidth, wrapForTerminal } from './diagnose/terminal-wrap.js';
-export { FEEDBACK_HINT } from './diagnose/closing-hint.js';
+export { COMMUNITY_HINT, FEEDBACK_HINT } from './diagnose/closing-hint.js';
 export { SILENT_HOST } from './host.js';
 export { RETICLE_VERSION, RETICLE_NPM_PACKAGE } from './version.js';
 export { InitFailure } from './diagnose/init-failure.js';
 export { NodePlatform } from './detect/platform.js';
-export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning, } from './detect/dev-server-ports.js';
+export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning, frameworkDevPort, } from './detect/dev-server-ports.js';
 export { configWithInstallSource } from './project/install-source-config.js';
 export { projectIdOf, rememberProjectOnDisk } from './project/remember-project.js';
 export { detectPackageManager, Framework, installCommandParts, parseMajor, PackageManager, } from './detect/detect.js';
@@ -57,3 +57,9 @@ claudeAvailableProbe, claudeHasReticle,
 codexAddCommand, codexAvailableProbe, } from './register/mcp.js';
 export { codexNamesOurServer } from './register/codex-toml.js';
 export { detectMcpClients } from './register/detect-clients.js';
+/**
+ * The prompt-capture hook, for `reticle hook install|uninstall|status` and `reticle doctor`: the
+ * same agent table and the same merge `init` uses, so the two cannot disagree about an agent.
+ */
+export { AGENT_FLAG, MCP_FALLBACK_AGENTS, PROMPT_HOOK_AGENTS, PromptHookAgent, PromptHookStatus, installPromptHook, promptHookCommand, promptHookInstalled, promptHookNpxOnly, promptHookTargets, uninstallPromptHook, } from './register/prompt-hooks.js';
+export { PROMPT_CAPTURE_NOTICE } from './plan/stop-hook-step.js';