@promptbook/cli 0.112.0-36 → 0.112.0-39

package/esm/index.es.js

@@ -5,7 +5,7 @@ import * as fs from 'fs';
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'fs';
 import * as path from 'path';
 import { join, basename, dirname, isAbsolute, relative, extname, resolve } from 'path';
-import { writeFile, readFile, stat, mkdir, access, constants, readdir, watch, unlink, rm, rename, rmdir } from 'fs/promises';
+import { readFile, writeFile, stat, mkdir, access, constants, readdir, watch, unlink, rm, rename, rmdir } from 'fs/promises';
 import { forTime, forEver } from 'waitasecond';
 import prompts from 'prompts';
 import * as dotenv from 'dotenv';
@@ -31,6 +31,7 @@ import Anthropic from '@anthropic-ai/sdk';
 import Bottleneck from 'bottleneck';
 import { OpenAIClient, AzureKeyCredential } from '@azure/openai';
 import * as ts from 'typescript';
+import ignore from 'ignore';
 import * as readline from 'readline';
 import { cursorTo, clearLine, createInterface } from 'readline';
 import { spawn } from 'child_process';
@@ -57,7 +58,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-36';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-39';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1661,6 +1662,181 @@ function $initializeCoderFindFreshEmojiTagCommand(program) {
 // Note: [🟡] Code for CLI command [find-fresh-emoji-tags](src/cli/cli-commands/coder/find-fresh-emoji-tags.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Root folders that contain source-like files for scanning.
+ */
+const SOURCE_ROOTS = ['src', 'apps', 'scripts', 'examples', 'agents', 'other'];
+/**
+ * File extensions treated as source code.
+ */
+const SOURCE_FILE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+/**
+ * Glob patterns that should be ignored when scanning for source files.
+ */
+const SOURCE_FILE_IGNORE_GLOBS = [
+    '**/node_modules/**',
+    '**/packages/**',
+    '**/.*/**',
+    '**/.git/**',
+    '**/.idea/**',
+    '**/.vscode/**',
+    '**/.promptbook/**',
+    '**/.next/**',
+    '**/.tmp/**',
+    '**/tmp/**',
+    '**/coverage/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/out/**',
+    '**/prompts/**',
+    '**/changelog/**',
+];
+/**
+ * Glob patterns that are exempt from line-count checks.
+ */
+const LINE_COUNT_EXEMPT_GLOBS = ['other/cspell-dictionaries/**/*.txt'];
+/**
+ * File extensions eligible for structural AST analysis.
+ */
+const STRUCTURAL_ANALYSIS_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+/**
+ * Markers that identify generated files which should be skipped.
+ */
+const GENERATED_CODE_MARKERS = [
+    'WARNING: This code has been generated',
+    'This code has been generated so that any manual changes will be overwritten',
+];
+/**
+ * Name of the prompts directory.
+ */
+const PROMPTS_DIR_NAME = 'prompts';
+/**
+ * Step size used for prompt numbering.
+ */
+const PROMPT_NUMBER_STEP = 10;
+/**
+ * Prefix used for generated prompt slugs.
+ */
+const PROMPT_SLUG_PREFIX = 'refactor';
+/**
+ * Label used to mark the target file in generated prompts.
+ */
+const PROMPT_TARGET_LABEL = 'Target file';
+/**
+ * Maximum length for generated prompt slugs.
+ */
+const PROMPT_SLUG_MAX_LENGTH = 80;
+/**
+ * Note: [?] Code in this file should never be published in any package
+ */
+
+/**
+ * Supported aggressiveness levels for refactor-candidate scanning.
+ */
+const REFACTOR_CANDIDATE_LEVEL_VALUES = ['xlow', 'low', 'medium', 'high', 'xhigh', 'extreme'];
+/**
+ * Default aggressiveness level for refactor-candidate scanning.
+ */
+const DEFAULT_REFACTOR_CANDIDATE_LEVEL = 'medium';
+/**
+ * Threshold table for each supported refactor-candidate scanning level.
+ */
+const REFACTOR_CANDIDATE_LEVEL_DETAILS_BY_LEVEL = {
+    xlow: createRefactorCandidateLevelDetails({
+        description: 'Very benevolent scan that only flags the most obvious refactor targets.',
+        maxLineCount: 4200,
+        maxEntityCountPerFile: 36,
+        maxFunctionCountPerFile: 24,
+        maxFunctionComplexity: 24,
+    }),
+    low: createRefactorCandidateLevelDetails({
+        description: 'Conservative scan for only the most obvious refactor targets.',
+        maxLineCount: 2800,
+        maxEntityCountPerFile: 28,
+        maxFunctionCountPerFile: 18,
+        maxFunctionComplexity: 20,
+    }),
+    medium: createRefactorCandidateLevelDetails({
+        description: 'Default scan using the current standard thresholds.',
+        maxLineCount: 2000,
+        maxEntityCountPerFile: 20,
+        maxFunctionCountPerFile: 14,
+        maxFunctionComplexity: 16,
+    }),
+    high: createRefactorCandidateLevelDetails({
+        description: 'Strict scan that finds more crowded or complex files.',
+        maxLineCount: 1400,
+        maxEntityCountPerFile: 15,
+        maxFunctionCountPerFile: 10,
+        maxFunctionComplexity: 12,
+    }),
+    xhigh: createRefactorCandidateLevelDetails({
+        description: 'Very strict scan for denser and more complex candidates.',
+        maxLineCount: 900,
+        maxEntityCountPerFile: 10,
+        maxFunctionCountPerFile: 7,
+        maxFunctionComplexity: 8,
+    }),
+    extreme: createRefactorCandidateLevelDetails({
+        description: 'Most aggressive scan that also surfaces weaker refactor opportunities.',
+        maxLineCount: 600,
+        maxEntityCountPerFile: 6,
+        maxFunctionCountPerFile: 4,
+        maxFunctionComplexity: 6,
+    }),
+};
+/**
+ * Resolves the thresholds for a selected refactor-candidate scanning level.
+ */
+function getRefactorCandidateLevelConfiguration(level = DEFAULT_REFACTOR_CANDIDATE_LEVEL) {
+    return REFACTOR_CANDIDATE_LEVEL_DETAILS_BY_LEVEL[level].configuration;
+}
+/**
+ * Resolves the user-facing description for a selected refactor-candidate scanning level.
+ */
+function getRefactorCandidateLevelDescription(level) {
+    return REFACTOR_CANDIDATE_LEVEL_DETAILS_BY_LEVEL[level].description;
+}
+/**
+ * Builds one normalized refactor-candidate level entry.
+ */
+function createRefactorCandidateLevelDetails(options) {
+    const { description, maxLineCount, maxEntityCountPerFile, maxFunctionCountPerFile, maxFunctionComplexity } = options;
+    return {
+        description,
+        configuration: createRefactorCandidateLevelConfiguration({
+            maxLineCount,
+            maxEntityCountPerFile,
+            maxFunctionCountPerFile,
+            maxFunctionComplexity,
+        }),
+    };
+}
+/**
+ * Builds one normalized refactor-candidate level configuration entry.
+ */
+function createRefactorCandidateLevelConfiguration(options) {
+    const { maxLineCount, maxEntityCountPerFile, maxFunctionCountPerFile, maxFunctionComplexity } = options;
+    return {
+        maxDefaultLineCount: maxLineCount,
+        maxLineCountByExtension: createLineCountLimits(maxLineCount),
+        maxEntityCountPerFile,
+        maxFunctionCountPerFile,
+        maxFunctionComplexity,
+    };
+}
+/**
+ * Creates a per-extension line-count table using one shared threshold.
+ */
+function createLineCountLimits(maxLineCount) {
+    const maxLineCountByExtension = {};
+    for (const extension of SOURCE_FILE_EXTENSIONS) {
+        maxLineCountByExtension[extension] = maxLineCount;
+    }
+    return maxLineCountByExtension;
+}
+// Note: [🟡] Code for repository script [RefactorCandidateLevel](scripts/find-refactor-candidates/RefactorCandidateLevel.ts) should never be published outside of `@promptbook/cli`
+
 /**
  * Initializes `coder find-refactor-candidates` command for Promptbook CLI utilities
  *
@@ -1670,20 +1846,23 @@ function $initializeCoderFindFreshEmojiTagCommand(program) {
  */
 function $initializeCoderFindRefactorCandidatesCommand(program) {
     const command = program.command('find-refactor-candidates');
-    command.description(spaceTrim$1(`
-            Scan source files to identify refactoring candidates
-
-            Flags files that exceed:
-            - Line count limits (500 lines per file by extension)
-            - Entity count limits (max 4 entities per file)
-
-            Generates refactor prompts with guidance for identified candidates.
-        `));
-    command.action(handleActionErrors(async () => {
+    command.description([
+        'Scan source files to identify refactoring candidates',
+        '',
+        'Levels:',
+        ...REFACTOR_CANDIDATE_LEVEL_VALUES.map((level) => `- ${level}: ${getRefactorCandidateLevelDescription(level)}`),
+        '',
+        'Generates refactor prompts with guidance for identified candidates.',
+    ].join('\n'));
+    command.addOption(new Option('--level <level>', `Set scan aggressiveness (${REFACTOR_CANDIDATE_LEVEL_VALUES.join(', ')})`)
+        .choices([...REFACTOR_CANDIDATE_LEVEL_VALUES])
+        .default(DEFAULT_REFACTOR_CANDIDATE_LEVEL));
+    command.action(handleActionErrors(async (cliOptions) => {
+        const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL } = cliOptions;
         // Note: Import the function dynamically to avoid loading heavy dependencies until needed
         const { findRefactorCandidates } = await Promise.resolve().then(function () { return findRefactorCandidates$1; });
         try {
-            await findRefactorCandidates();
+            await findRefactorCandidates({ level });
         }
         catch (error) {
             assertsError(error);
@@ -1729,7 +1908,9 @@ const PROMPTS_DONE_DIRECTORY_PATH = join(PROMPTS_DIRECTORY_PATH, 'done');
  */
 const PROMPTS_TEMPLATES_DIRECTORY_PATH = join(PROMPTS_DIRECTORY_PATH, 'templates');
 /**
- * Built-in boilerplate templates shared by `coder init` and `coder generate-boilerplates`.
+ * Built-in boilerplate templates available to `coder generate-boilerplates`.
+ *
+ * Only the project-agnostic subset is materialized by `coder init`.
  */
 const DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS = [
     {
@@ -1738,10 +1919,11 @@ const DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS = [
         slugPrefix: null,
         content: buildCoderPromptTemplateContent([
             '-   @@@',
-            '-   Keep in mind the DRY _(don\'t repeat yourself)_ principle.',
+            "-   Keep in mind the DRY _(don't repeat yourself)_ principle.",
             '-   Do a proper analysis of the current functionality before you start implementing.',
             '-   Add the changes into the [changelog](./changelog/_current-preversion.md)',
         ]),
+        isDefaultProjectTemplate: true,
     },
     {
         id: 'agents-server',
@@ -1749,14 +1931,19 @@ const DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS = [
         slugPrefix: 'agents-server',
         content: buildCoderPromptTemplateContent([
             '-   @@@',
-            '-   Keep in mind the DRY _(don\'t repeat yourself)_ principle.',
+            "-   Keep in mind the DRY _(don't repeat yourself)_ principle.",
             '-   Do a proper analysis of the current functionality before you start implementing.',
             '-   You are working with the [Agents Server](apps/agents-server)',
             '-   If you need to do the database migration, do it',
             '-   Add the changes into the [changelog](changelog/_current-preversion.md)',
         ]),
+        isDefaultProjectTemplate: false,
     },
 ];
+/**
+ * Project-agnostic coder templates that `ptbk coder init` should materialize in any repository.
+ */
+const DEFAULT_CODER_PROJECT_PROMPT_TEMPLATE_DEFINITIONS = DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS.filter(({ isDefaultProjectTemplate }) => isDefaultProjectTemplate);
 /**
  * Lists the built-in coder boilerplate templates.
  *
@@ -1765,6 +1952,14 @@ const DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS = [
 function getDefaultCoderPromptTemplateDefinitions() {
     return DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS;
 }
+/**
+ * Lists the built-in coder prompt templates that are safe to initialize in any project.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+function getDefaultCoderProjectPromptTemplateDefinitions() {
+    return DEFAULT_CODER_PROJECT_PROMPT_TEMPLATE_DEFINITIONS;
+}
 /**
  * Resolves one built-in coder boilerplate template definition by its stable identifier.
  *
@@ -1784,9 +1979,9 @@ function getDefaultCoderPromptTemplateDefinition(template) {
  */
 async function ensureDefaultCoderPromptTemplateFiles(projectPath) {
     const ensuredTemplateFiles = [];
-    for (const definition of DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS) {
+    for (const definition of DEFAULT_CODER_PROJECT_PROMPT_TEMPLATE_DEFINITIONS) {
         const absoluteTemplatePath = join(projectPath, definition.relativeFilePath);
-        if (await isExistingFile$1(absoluteTemplatePath)) {
+        if (await isExistingFile$2(absoluteTemplatePath)) {
             ensuredTemplateFiles.push({
                 id: definition.id,
                 relativeFilePath: definition.relativeFilePath,
@@ -1900,7 +2095,7 @@ function isNodeJsErrorWithCode(error, code) {
 /**
  * Checks whether a path exists and is a file.
  */
-async function isExistingFile$1(path) {
+async function isExistingFile$2(path) {
     try {
         return (await stat(path)).isFile();
     }
@@ -2050,178 +2245,202 @@ function buildPromptSlug$1(templateSlugPrefix, title) {
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
- * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
+ * Relative path to the shared coder context file initialized in project roots.
  *
- * @public exported from `@promptbook/core`
+ * @private internal utility of `ptbk coder`
  */
-class ParseError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ParseError';
-        Object.setPrototypeOf(this, ParseError.prototype);
-    }
-}
-// TODO: Maybe split `ParseError` and `ApplyError`
-
+const AGENTS_FILE_PATH = 'AGENTS.md';
 /**
- * Required environment variables for coding-agent git identity.
+ * Stable boilerplate instructions written into newly initialized `AGENTS.md` files.
  */
-const REQUIRED_CODER_ENV_VARIABLES = [
-    {
-        name: 'CODING_AGENT_GIT_NAME',
-        value: 'Promptbook Coding Agent',
-    },
-    {
-        name: 'CODING_AGENT_GIT_EMAIL',
-        value: 'coding-agent@promptbook.studio',
-    },
-    {
-        name: 'CODING_AGENT_GIT_SIGNING_KEY',
-        value: '13406525ED912F938FEA85AB4046C687298B2382',
-    },
+const DEFAULT_CODER_AGENTS_FILE_LINES = [
+    '<!-- TODO: Write instructions for the Promptbook AI Coder here -->',
 ];
 /**
- * Default npm scripts initialized by `ptbk coder init`.
+ * Shared markdown boilerplate written into new `AGENTS.md` files.
  */
-const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
-    'coder:generate-boilerplates': 'npx ptbk coder generate-boilerplates',
-    'coder:run': 'npx ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --no-wait',
-    'coder:find-refactor-candidates': 'npx ptbk coder find-refactor-candidates',
-    'coder:verify': 'npx ptbk coder verify',
-};
+const DEFAULT_CODER_AGENTS_FILE_CONTENT = DEFAULT_CODER_AGENTS_FILE_LINES.join('\n');
 /**
- * Relative path to `.gitignore` in the initialized project.
- */
-const GITIGNORE_FILE_PATH = '.gitignore';
-/**
- * Relative path to `package.json` in the initialized project.
- */
-const PACKAGE_JSON_FILE_PATH = 'package.json';
-/**
- * Relative path to the VS Code settings file initialized by `ptbk coder init`.
+ * Returns the default coder `AGENTS.md` boilerplate instructions.
+ *
+ * @private internal utility of `ptbk coder`
  */
-const VSCODE_SETTINGS_FILE_PATH = '.vscode/settings.json';
+function getDefaultCoderAgentsFileContent() {
+    return DEFAULT_CODER_AGENTS_FILE_CONTENT;
+}
+// Note: [🟡] Code for coder AGENTS file boilerplate [agentsFile](src/cli/cli-commands/coder/agentsFile.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names
+
 /**
- * Relative path to the VS Code directory initialized by `ptbk coder init`.
+ * Normalizes one project-relative path for human-readable CLI output and markdown.
+ *
+ * @private internal utility of `ptbk coder`
  */
-const VSCODE_DIRECTORY_PATH = '.vscode';
+function formatDisplayPath(relativePath) {
+    return relativePath.replace(/\\/gu, '/');
+}
+// Note: [🟡] Code for coder path formatting [formatDisplayPath](src/cli/cli-commands/coder/formatDisplayPath.ts) should never be published outside of `@promptbook/cli`
+
 /**
- * VS Code setting key used to route pasted markdown images into prompt-specific screenshots.
+ * Relative path to the Promptbook Coder quick-reference file initialized in project roots.
+ *
+ * @private internal utility of `ptbk coder`
  */
-const MARKDOWN_COPY_FILES_DESTINATION_SETTING_KEY = 'markdown.copyFiles.destination';
+const AGENT_CODING_FILE_PATH = 'AGENT_CODING.md';
 /**
- * Markdown glob used for coder prompt files inside VS Code settings.
+ * Returns the default coder `AGENT_CODING.md` quick-reference content.
+ *
+ * @private internal utility of `ptbk coder`
  */
-const PROMPTS_MARKDOWN_FILE_GLOB = 'prompts/*md';
+function getDefaultCoderAgentCodingFileContent({ packageJsonScripts, }) {
+    return [
+        '# Promptbook Coder quick reference',
+        '',
+        `This project is prepared for the \`ptbk coder\` workflow. Promptbook Coder does not create a new model on its own; it orchestrates coding agents such as GitHub Copilot, OpenAI Codex, Claude Code, Opencode, Cline, and Gemini CLI through prompt files in \`${formatDisplayPath(PROMPTS_DIRECTORY_PATH)}/\`.`,
+        '',
+        '## Workflow',
+        `1. Put repository-wide coding rules into \`${AGENTS_FILE_PATH}\`. The default \`npm run coder:run\` script already passes \`--context ${AGENTS_FILE_PATH}\`.`,
+        `2. Create or customize prompt templates in \`${formatDisplayPath(PROMPTS_TEMPLATES_DIRECTORY_PATH)}/\`. ${buildStarterTemplateSentence()}`,
+        '3. Generate prompt files with `npm run coder:generate-boilerplates` or `npx ptbk coder generate-boilerplates --template <template> --count <count>`.',
+        '4. Replace every `@@@`, keep drafts as `[-]`, and switch prompts to `[ ]` when they are ready to run. Completed prompts are marked `[x]`.',
+        '5. Run `npm run coder:run` to execute the next ready prompt with the configured coding agent.',
+        `6. Use \`npm run coder:verify\` to archive finished prompts into \`${formatDisplayPath(PROMPTS_DONE_DIRECTORY_PATH)}/\` and append repair follow-up prompts when more work is needed.`,
+        '7. Use `npm run coder:find-refactor-candidates` when you want Promptbook to suggest refactor prompts automatically.',
+        '',
+        '## Templates',
+        `-   Project-owned templates created by \`ptbk coder init\`: ${formatInlineCodeList(getDefaultCoderProjectPromptTemplateDefinitions().map(({ relativeFilePath }) => formatDisplayPath(relativeFilePath)))}`,
+        `-   Built-in \`--template\` aliases: ${formatInlineCodeList(getDefaultCoderPromptTemplateDefinitions().map(({ id }) => id))}`,
+        `-   To add a custom template, create a markdown file such as \`${formatDisplayPath(PROMPTS_TEMPLATES_DIRECTORY_PATH)}/backend.md\`.`,
+        `-   To use a project template, run \`npx ptbk coder generate-boilerplates --template ${formatDisplayPath(PROMPTS_TEMPLATES_DIRECTORY_PATH)}/backend.md\`.`,
+        `-   Keep shared repository rules in \`${AGENTS_FILE_PATH}\` and recurring task-family rules in template files so individual prompt files stay focused on the actual task.`,
+        '',
+        '## Created npm scripts',
+        '| Script | Purpose |',
+        '| --- | --- |',
+        ...buildPackageJsonScriptTableLines(packageJsonScripts),
+        '',
+        '## Customizing the workflow',
+        '-   Edit `package.json` if you want `npm run coder:run` to use another coding agent, model, thinking level, context file, or wait mode.',
+        '-   Use direct CLI commands when you need one-off flags such as `--priority`, `--ignore-git-changes`, `--dry-run`, `--allow-credits`, or `--auto-migrate`.',
+        '-   Use `npx ptbk coder --help` and `npx ptbk coder <command> --help` for the full CLI reference.',
+    ].join('\n');
+}
 /**
- * Screenshot destination used for pasted prompt images inside VS Code settings.
+ * Builds the sentence describing the starter templates created during initialization.
  */
-const PROMPTS_SCREENSHOT_DESTINATION = './prompts/screenshots/${documentBaseName}.png';
+function buildStarterTemplateSentence() {
+    const starterTemplatePaths = getDefaultCoderProjectPromptTemplateDefinitions().map(({ relativeFilePath }) => formatDisplayPath(relativeFilePath));
+    if (starterTemplatePaths.length === 1) {
+        return `The starter project template created by \`ptbk coder init\` is \`${starterTemplatePaths[0]}\`.`;
+    }
+    return `The starter project templates created by \`ptbk coder init\` are ${formatInlineCodeList(starterTemplatePaths)}.`;
+}
 /**
- * Default indentation used when creating new JSON configuration files.
+ * Builds the markdown table rows describing the initialized npm scripts.
  */
-const DEFAULT_JSON_FILE_INDENTATION = '    ';
+function buildPackageJsonScriptTableLines(packageJsonScripts) {
+    return Object.entries(packageJsonScripts).map(([scriptName, scriptCommand]) => `| \`npm run ${scriptName}\` | ${describeDefaultCoderPackageJsonScript(scriptName, scriptCommand)} |`);
+}
 /**
- * Default newline used when creating new JSON configuration files.
+ * Describes one initialized npm script in human-readable terms.
  */
-const DEFAULT_JSON_FILE_NEWLINE = '\n';
+function describeDefaultCoderPackageJsonScript(scriptName, scriptCommand) {
+    if (scriptName === 'coder:generate-boilerplates') {
+        return `Runs \`${scriptCommand}\` to create new prompt files in \`${formatDisplayPath(PROMPTS_DIRECTORY_PATH)}/\`.`;
+    }
+    if (scriptName === 'coder:run') {
+        return `Runs \`${scriptCommand}\` to execute the next ready prompt with shared repository context from \`${AGENTS_FILE_PATH}\`.`;
+    }
+    if (scriptName === 'coder:find-refactor-candidates') {
+        return `Runs \`${scriptCommand}\` to generate prompt candidates for large or crowded files.`;
+    }
+    if (scriptName === 'coder:verify') {
+        return `Runs \`${scriptCommand}\` to archive verified prompts into \`${formatDisplayPath(PROMPTS_DONE_DIRECTORY_PATH)}/\` and append repair prompts when needed.`;
+    }
+    return `Runs \`${scriptCommand}\`.`;
+}
 /**
- * `.gitignore` block required by standalone Promptbook coder projects.
+ * Formats one inline code list for human-readable markdown.
  */
-const CODER_GITIGNORE_BLOCK = spaceTrim$1(`
-    # Promptbook Coder
-    /.tmp
-`);
+function formatInlineCodeList(values) {
+    return values.map((value) => `\`${value}\``).join(', ');
+}
+// Note: [🟡] Code for coder AGENT_CODING file boilerplate [agentCodingFile](src/cli/cli-commands/coder/agentCodingFile.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names
+
 /**
- * Initializes `coder init` command for Promptbook CLI utilities.
- *
- * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ * Appends one text block to existing file content while preserving readable newlines.
  *
- * @private internal function of `promptbookCli`
+ * @private function of `initializeCoderProjectConfiguration`
  */
-function $initializeCoderInitCommand(program) {
-    const command = program.command('init');
-    command.alias('initialize');
-    command.description(spaceTrim$1(`
-            Initialize Promptbook coder configuration for current project
-
-            Creates or updates:
-            - prompts/
-            - prompts/done/
-            - prompts/templates/common.md
-            - prompts/templates/agents-server.md
-            - .gitignore
-            - package.json
-            - .vscode/settings.json
-
-            Ensures required coding-agent environment variables in .env:
-            - CODING_AGENT_GIT_NAME
-            - CODING_AGENT_GIT_EMAIL
-            - CODING_AGENT_GIT_SIGNING_KEY
-        `));
-    command.action(handleActionErrors(async () => {
-        const summary = await initializeCoderProjectConfiguration(process.cwd());
-        printInitializationSummary(summary);
-    }));
+function appendBlock(currentContent, blockToAppend) {
+    if (currentContent.trim() === '') {
+        return `${blockToAppend}\n`;
+    }
+    const normalizedCurrentContent = currentContent.endsWith('\n') ? currentContent : `${currentContent}\n`;
+    return `${normalizedCurrentContent}\n${blockToAppend}\n`;
 }
+// Note: [🟡] Code for coder init text appending [appendBlock](src/cli/cli-commands/coder/appendBlock.ts) should never be published outside of `@promptbook/cli`
+
 /**
- * Lists the default npm scripts initialized by `ptbk coder init`.
+ * Reads one text file when it exists, otherwise returns `undefined`.
  *
- * @private internal utility of `coder init` command
+ * @private function of `initializeCoderProjectConfiguration`
  */
-function getDefaultCoderPackageJsonScripts() {
-    return DEFAULT_CODER_PACKAGE_JSON_SCRIPTS;
+async function readTextFileIfExists(path) {
+    try {
+        const fileStats = await stat(path);
+        if (!fileStats.isFile()) {
+            return undefined;
+        }
+    }
+    catch (_a) {
+        return undefined;
+    }
+    return readFile(path, 'utf-8');
 }
+// Note: [🟡] Code for coder init text-file reading [readTextFileIfExists](src/cli/cli-commands/coder/readTextFileIfExists.ts) should never be published outside of `@promptbook/cli`
+
 /**
- * Creates or updates all coder configuration artifacts required in the current project.
- *
- * @private internal utility of `coder init` command
+ * Relative path to `.env` in the initialized project.
  */
-async function initializeCoderProjectConfiguration(projectPath) {
-    const promptsDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DIRECTORY_PATH);
-    const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
-    const promptsTemplatesDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH);
-    const promptTemplateFileStatuses = await ensureDefaultCoderPromptTemplateFiles(projectPath);
-    const { envFileStatus, initializedEnvVariableNames } = await ensureCoderEnvFile(projectPath);
-    const gitignoreFileStatus = await ensureCoderGitignoreFile(projectPath);
-    const packageJsonFileStatus = await ensureCoderPackageJsonFile(projectPath);
-    const vscodeSettingsFileStatus = await ensureCoderVscodeSettingsFile(projectPath);
-    return {
-        promptsDirectoryStatus,
-        promptsDoneDirectoryStatus,
-        promptsTemplatesDirectoryStatus,
-        promptTemplateFileStatuses,
-        envFileStatus,
-        gitignoreFileStatus,
-        packageJsonFileStatus,
-        vscodeSettingsFileStatus,
-        initializedEnvVariableNames,
-    };
-}
+const ENV_FILE_PATH = '.env';
 /**
- * Ensures a relative directory exists in the project root.
+ * Fallback `.env` content used when no required variables need to be appended.
  */
-async function ensureDirectory(projectPath, relativeDirectoryPath) {
-    const directoryPath = join(projectPath, relativeDirectoryPath);
-    const existedBefore = await isExistingDirectory(directoryPath);
-    if (!existedBefore) {
-        await mkdir(directoryPath, { recursive: true });
-        return 'created';
-    }
-    return 'unchanged';
-}
+const EMPTY_CODER_ENV_FILE_CONTENT = '# Environment variables for Promptbook coder\n';
+/**
+ * Required environment variables for coding-agent git identity.
+ */
+const REQUIRED_CODER_ENV_VARIABLES = [
+    {
+        name: 'CODING_AGENT_GIT_NAME',
+        value: 'Promptbook Coding Agent',
+    },
+    {
+        name: 'CODING_AGENT_GIT_EMAIL',
+        value: 'coding-agent@promptbook.studio',
+    },
+    {
+        name: 'CODING_AGENT_GIT_SIGNING_KEY',
+        value: '13406525ED912F938FEA85AB4046C687298B2382',
+    },
+];
 /**
  * Ensures `.env` exists and contains all required coder environment variables.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
  */
 async function ensureCoderEnvFile(projectPath) {
-    const envFilePath = join(projectPath, '.env');
-    const envFileExistedBefore = await isExistingFile(envFilePath);
-    const currentEnvContent = envFileExistedBefore ? await readFile(envFilePath, 'utf-8') : '';
-    const existingEnvVariables = parseEnvVariableNames(currentEnvContent);
-    const missingEnvVariables = REQUIRED_CODER_ENV_VARIABLES.filter(({ name }) => !existingEnvVariables.has(name));
+    const envFilePath = join(projectPath, ENV_FILE_PATH);
+    const existingEnvContent = await readTextFileIfExists(envFilePath);
+    const isEnvFileExisting = existingEnvContent !== undefined;
+    const currentEnvContent = existingEnvContent || '';
+    const existingEnvVariableNames = parseEnvVariableNames(currentEnvContent);
+    const missingEnvVariables = REQUIRED_CODER_ENV_VARIABLES.filter(({ name }) => !existingEnvVariableNames.has(name));
     if (missingEnvVariables.length === 0) {
-        if (!envFileExistedBefore) {
-            await writeFile(envFilePath, '# Environment variables for Promptbook coder\n', 'utf-8');
+        if (!isEnvFileExisting) {
+            await writeFile(envFilePath, EMPTY_CODER_ENV_FILE_CONTENT, 'utf-8');
             return {
                 envFileStatus: 'created',
                 initializedEnvVariableNames: [],
@@ -2236,12 +2455,54 @@ async function ensureCoderEnvFile(projectPath) {
     const nextEnvContent = appendBlock(currentEnvContent, envBlockToAppend);
     await writeFile(envFilePath, nextEnvContent, 'utf-8');
     return {
-        envFileStatus: envFileExistedBefore ? 'updated' : 'created',
+        envFileStatus: isEnvFileExisting ? 'updated' : 'created',
         initializedEnvVariableNames: missingEnvVariables.map(({ name }) => name),
     };
 }
+/**
+ * Parses variable names currently defined in `.env` style content.
+ */
+function parseEnvVariableNames(envContent) {
+    const variableNames = new Set();
+    for (const line of envContent.split(/\r?\n/)) {
+        const trimmedLine = line.trim();
+        if (trimmedLine === '' || trimmedLine.startsWith('#')) {
+            continue;
+        }
+        const match = trimmedLine.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        if (!match || !match[1]) {
+            continue;
+        }
+        variableNames.add(match[1]);
+    }
+    return variableNames;
+}
+/**
+ * Builds a `.env` block containing missing coder environment variables.
+ */
+function buildMissingEnvVariablesBlock(variables) {
+    return spaceTrim$1(`
+        # Promptbook coder identity (initialized by \`ptbk coder init\`)
+        ${variables.map(({ name, value }) => `${name}=${JSON.stringify(value)}`).join('\n')}
+    `);
+}
+// Note: [🟡] Code for coder init environment bootstrapping [ensureCoderEnvFile](src/cli/cli-commands/coder/ensureCoderEnvFile.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Relative path to `.gitignore` in the initialized project.
+ */
+const GITIGNORE_FILE_PATH = '.gitignore';
+/**
+ * `.gitignore` block required by standalone Promptbook coder projects.
+ */
+const CODER_GITIGNORE_BLOCK = spaceTrim$1(`
+    # Promptbook Coder
+    /.tmp
+`);
 /**
  * Ensures `.gitignore` contains the standalone Promptbook coder cache entry.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
  */
 async function ensureCoderGitignoreFile(projectPath) {
     const gitignorePath = join(projectPath, GITIGNORE_FILE_PATH);
@@ -2254,95 +2515,339 @@ async function ensureCoderGitignoreFile(projectPath) {
     return currentGitignoreContent === undefined ? 'created' : 'updated';
 }
 /**
- * Ensures `package.json` contains the standalone Promptbook coder helper scripts.
+ * Detects whether `.gitignore` already covers the standalone coder temp directory.
  */
-async function ensureCoderPackageJsonFile(projectPath) {
-    const packageJsonPath = join(projectPath, PACKAGE_JSON_FILE_PATH);
-    const packageJsonContent = await readTextFileIfExists(packageJsonPath);
-    const formatting = detectJsonFileFormatting(packageJsonContent);
-    const packageJson = packageJsonContent === undefined ? {} : await parseJsonObjectFile(PACKAGE_JSON_FILE_PATH, packageJsonContent);
-    const scripts = getStringRecordOrDefault(packageJson['scripts'], PACKAGE_JSON_FILE_PATH, 'scripts');
-    let hasChanges = packageJsonContent === undefined;
-    const nextScripts = { ...scripts };
-    for (const [scriptName, scriptCommand] of Object.entries(getDefaultCoderPackageJsonScripts())) {
-        if (nextScripts[scriptName] !== scriptCommand) {
-            nextScripts[scriptName] = scriptCommand;
+function hasTmpGitignoreRule(gitignoreContent) {
+    return /(^|[\r\n])\/?\.tmp(?:[\r\n]|$)/u.test(gitignoreContent);
+}
+// Note: [🟡] Code for coder init gitignore bootstrapping [ensureCoderGitignoreFile](src/cli/cli-commands/coder/ensureCoderGitignoreFile.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Ensures one coder markdown file exists with the provided default boilerplate.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+async function ensureCoderMarkdownFile(projectPath, relativeFilePath, fileContent) {
+    const absoluteFilePath = join(projectPath, relativeFilePath);
+    if (await isExistingFile$1(absoluteFilePath)) {
+        return 'unchanged';
+    }
+    await writeFile(absoluteFilePath, `${fileContent}\n`, 'utf-8');
+    return 'created';
+}
+/**
+ * Checks whether a path exists and is a file.
+ */
+async function isExistingFile$1(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch (_a) {
+        return false;
+    }
+}
+// Note: [🟡] Code for coder init markdown bootstrapping [ensureCoderMarkdownFile](src/cli/cli-commands/coder/ensureCoderMarkdownFile.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Default npm scripts initialized by `ptbk coder init`.
+ */
+const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
+    'coder:generate-boilerplates': 'npx ptbk coder generate-boilerplates',
+    'coder:run': 'npx ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --no-wait',
+    'coder:find-refactor-candidates': 'npx ptbk coder find-refactor-candidates',
+    'coder:verify': 'npx ptbk coder verify',
+};
+/**
+ * Lists the default npm scripts initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+function getDefaultCoderPackageJsonScripts() {
+    return DEFAULT_CODER_PACKAGE_JSON_SCRIPTS;
+}
+// Note: [🟡] Code for coder init package scripts [getDefaultCoderPackageJsonScripts](src/cli/cli-commands/coder/getDefaultCoderPackageJsonScripts.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
+ *
+ * @public exported from `@promptbook/core`
+ */
+class ParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ParseError';
+        Object.setPrototypeOf(this, ParseError.prototype);
+    }
+}
+// TODO: Maybe split `ParseError` and `ApplyError`
+
+/**
+ * Default indentation used when creating new JSON configuration files.
+ */
+const DEFAULT_JSON_FILE_INDENTATION = '    ';
+/**
+ * Default newline used when creating new JSON configuration files.
+ */
+const DEFAULT_JSON_FILE_NEWLINE = '\n';
+/**
+ * Ensures one JSON object field contains the provided string-record entries.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+async function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, }) {
+    if (ensureParentDirectoryPath) {
+        await mkdir(join(projectPath, ensureParentDirectoryPath), { recursive: true });
+    }
+    const absoluteFilePath = join(projectPath, relativeFilePath);
+    const fileContent = await readTextFileIfExists(absoluteFilePath);
+    const formatting = detectJsonFileFormatting(fileContent);
+    const jsonObject = fileContent === undefined ? {} : await parseJsonObjectFile(relativeFilePath, fileContent);
+    const existingEntries = getStringRecordOrDefault(jsonObject[fieldPath], relativeFilePath, fieldPath);
+    let hasChanges = fileContent === undefined;
+    const mergedEntries = { ...existingEntries };
+    for (const [entryKey, entryValue] of Object.entries(nextEntries)) {
+        if (mergedEntries[entryKey] !== entryValue) {
+            mergedEntries[entryKey] = entryValue;
             hasChanges = true;
         }
     }
     if (!hasChanges) {
         return 'unchanged';
     }
-    const nextPackageJson = { ...packageJson };
-    nextPackageJson['scripts'] = nextScripts;
-    await writeFile(packageJsonPath, serializeJsonObject(nextPackageJson, formatting), 'utf-8');
-    return packageJsonContent === undefined ? 'created' : 'updated';
+    const nextJsonObject = { ...jsonObject };
+    nextJsonObject[fieldPath] = mergedEntries;
+    await writeFile(absoluteFilePath, serializeJsonObject(nextJsonObject, formatting), 'utf-8');
+    return fileContent === undefined ? 'created' : 'updated';
 }
 /**
- * Ensures VS Code routes pasted prompt images into `prompts/screenshots`.
+ * Parses one JSON object file while accepting VS Code style comments and trailing commas.
  */
-async function ensureCoderVscodeSettingsFile(projectPath) {
-    await mkdir(join(projectPath, VSCODE_DIRECTORY_PATH), { recursive: true });
-    const vscodeSettingsPath = join(projectPath, VSCODE_SETTINGS_FILE_PATH);
-    const vscodeSettingsContent = await readTextFileIfExists(vscodeSettingsPath);
-    const formatting = detectJsonFileFormatting(vscodeSettingsContent);
-    const vscodeSettings = vscodeSettingsContent === undefined
-        ? {}
-        : await parseJsonObjectFile(VSCODE_SETTINGS_FILE_PATH, vscodeSettingsContent);
-    const markdownCopyFilesDestinations = getStringRecordOrDefault(vscodeSettings[MARKDOWN_COPY_FILES_DESTINATION_SETTING_KEY], VSCODE_SETTINGS_FILE_PATH, MARKDOWN_COPY_FILES_DESTINATION_SETTING_KEY);
-    let hasChanges = vscodeSettingsContent === undefined;
-    const nextMarkdownCopyFilesDestinations = { ...markdownCopyFilesDestinations };
-    if (nextMarkdownCopyFilesDestinations[PROMPTS_MARKDOWN_FILE_GLOB] !== PROMPTS_SCREENSHOT_DESTINATION) {
-        nextMarkdownCopyFilesDestinations[PROMPTS_MARKDOWN_FILE_GLOB] = PROMPTS_SCREENSHOT_DESTINATION;
-        hasChanges = true;
+async function parseJsonObjectFile(relativeFilePath, fileContent) {
+    if (fileContent.trim() === '') {
+        return {};
     }
-    if (!hasChanges) {
-        return 'unchanged';
+    const typescript = await import('typescript');
+    const parsedFile = typescript.parseConfigFileTextToJson(relativeFilePath, fileContent);
+    if (parsedFile.error) {
+        throw new ParseError(spaceTrim$1(`
+                Cannot parse \`${relativeFilePath}\` as JSON.
+
+                ${typescript.flattenDiagnosticMessageText(parsedFile.error.messageText, '\n')}
+            `));
     }
-    const nextVscodeSettings = { ...vscodeSettings };
-    nextVscodeSettings[MARKDOWN_COPY_FILES_DESTINATION_SETTING_KEY] = nextMarkdownCopyFilesDestinations;
-    await writeFile(vscodeSettingsPath, serializeJsonObject(nextVscodeSettings, formatting), 'utf-8');
-    return vscodeSettingsContent === undefined ? 'created' : 'updated';
+    if (!isPlainObject(parsedFile.config)) {
+        throw new ParseError(spaceTrim$1(`
+                File \`${relativeFilePath}\` must contain one top-level JSON object.
+            `));
+    }
+    return parsedFile.config;
 }
 /**
- * Parses variable names currently defined in `.env` style content.
+ * Reads one JSON object field as a string-to-string record.
  */
-function parseEnvVariableNames(envContent) {
-    const variableNames = new Set();
-    for (const line of envContent.split(/\r?\n/)) {
-        const trimmedLine = line.trim();
-        if (trimmedLine === '' || trimmedLine.startsWith('#')) {
-            continue;
-        }
-        const match = trimmedLine.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/);
-        if (!match || !match[1]) {
-            continue;
+function getStringRecordOrDefault(value, relativeFilePath, fieldPath) {
+    if (value === undefined) {
+        return {};
+    }
+    if (!isPlainObject(value)) {
+        throw new ParseError(spaceTrim$1(`
+                File \`${relativeFilePath}\` contains invalid \`${fieldPath}\`.
+
+                Expected \`${fieldPath}\` to be an object with string values.
+            `));
+    }
+    const stringRecord = {};
+    for (const [key, itemValue] of Object.entries(value)) {
+        if (typeof itemValue !== 'string') {
+            throw new ParseError(spaceTrim$1(`
+                    File \`${relativeFilePath}\` contains invalid \`${fieldPath}.${key}\`.
+
+                    Expected \`${fieldPath}\` to be an object with string values.
+                `));
         }
-        variableNames.add(match[1]);
+        stringRecord[key] = itemValue;
     }
-    return variableNames;
+    return stringRecord;
 }
 /**
- * Builds a `.env` block containing missing coder environment variables.
+ * Serializes one JSON object using detected or default formatting.
  */
-function buildMissingEnvVariablesBlock(variables) {
-    return spaceTrim$1(`
-        # Promptbook coder identity (initialized by \`ptbk coder init\`)
-        ${variables.map(({ name, value }) => `${name}=${JSON.stringify(value)}`).join('\n')}
-    `);
+function serializeJsonObject(value, formatting) {
+    return `${JSON.stringify(value, null, formatting.indentation)}${formatting.newline}`;
 }
 /**
- * Appends one text block to existing file content while preserving readable newlines.
+ * Detects indentation and newline formatting from an existing JSON file.
  */
-function appendBlock(currentContent, blockToAppend) {
-    if (currentContent.trim() === '') {
-        return `${blockToAppend}\n`;
+function detectJsonFileFormatting(fileContent) {
+    if (!fileContent) {
+        return {
+            indentation: DEFAULT_JSON_FILE_INDENTATION,
+            newline: DEFAULT_JSON_FILE_NEWLINE,
+        };
     }
-    const normalizedCurrentContent = currentContent.endsWith('\n') ? currentContent : `${currentContent}\n`;
-    return `${normalizedCurrentContent}\n${blockToAppend}\n`;
+    const indentationMatch = fileContent.match(/^[ \t]+(?=")/mu);
+    return {
+        indentation: (indentationMatch === null || indentationMatch === void 0 ? void 0 : indentationMatch[0]) || DEFAULT_JSON_FILE_INDENTATION,
+        newline: fileContent.includes('\r\n') ? '\r\n' : '\n',
+    };
+}
+/**
+ * Checks whether one parsed JSON value is a plain object.
+ */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Note: [🟡] Code for coder init JSON merging [mergeStringRecordJsonFile](src/cli/cli-commands/coder/mergeStringRecordJsonFile.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Relative path to `package.json` in the initialized project.
+ */
+const PACKAGE_JSON_FILE_PATH = 'package.json';
+/**
+ * Ensures `package.json` contains the standalone Promptbook coder helper scripts.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+async function ensureCoderPackageJsonFile(projectPath) {
+    return mergeStringRecordJsonFile({
+        projectPath,
+        relativeFilePath: PACKAGE_JSON_FILE_PATH,
+        fieldPath: 'scripts',
+        nextEntries: getDefaultCoderPackageJsonScripts(),
+    });
+}
+// Note: [🟡] Code for coder init package.json bootstrapping [ensureCoderPackageJsonFile](src/cli/cli-commands/coder/ensureCoderPackageJsonFile.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * VS Code setting key used to route pasted markdown images into prompt-specific screenshots.
+ */
+const MARKDOWN_COPY_FILES_DESTINATION_SETTING_KEY = 'markdown.copyFiles.destination';
+/**
+ * Markdown glob used for coder prompt files inside VS Code settings.
+ */
+const PROMPTS_MARKDOWN_FILE_GLOB = 'prompts/*md';
+/**
+ * Screenshot destination used for pasted prompt images inside VS Code settings.
+ */
+const PROMPTS_SCREENSHOT_DESTINATION = './prompts/screenshots/${documentBaseName}.png';
+/**
+ * Default VS Code settings initialized by `ptbk coder init`.
+ */
+const DEFAULT_CODER_VSCODE_SETTINGS = {
+    [MARKDOWN_COPY_FILES_DESTINATION_SETTING_KEY]: {
+        [PROMPTS_MARKDOWN_FILE_GLOB]: PROMPTS_SCREENSHOT_DESTINATION,
+    },
+};
+/**
+ * Lists the default VS Code settings initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+function getDefaultCoderVscodeSettings() {
+    return DEFAULT_CODER_VSCODE_SETTINGS;
+}
+// Note: [🟡] Code for coder init VS Code settings [getDefaultCoderVscodeSettings](src/cli/cli-commands/coder/getDefaultCoderVscodeSettings.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Relative path to the VS Code settings file initialized by `ptbk coder init`.
+ */
+const VSCODE_SETTINGS_FILE_PATH = '.vscode/settings.json';
+/**
+ * Relative path to the VS Code directory initialized by `ptbk coder init`.
+ */
+const VSCODE_DIRECTORY_PATH = '.vscode';
+/**
+ * Ensures VS Code routes pasted prompt images into `prompts/screenshots`.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+async function ensureCoderVscodeSettingsFile(projectPath) {
+    const [fieldPath, nextEntries] = resolveDefaultCoderVscodeSettingsEntry();
+    return mergeStringRecordJsonFile({
+        projectPath,
+        relativeFilePath: VSCODE_SETTINGS_FILE_PATH,
+        fieldPath,
+        nextEntries,
+        ensureParentDirectoryPath: VSCODE_DIRECTORY_PATH,
+    });
+}
+/**
+ * Resolves the default string-record entry that `coder init` merges into VS Code settings.
+ */
+function resolveDefaultCoderVscodeSettingsEntry() {
+    const [defaultVscodeSettingsEntry] = Object.entries(getDefaultCoderVscodeSettings());
+    if (!defaultVscodeSettingsEntry) {
+        throw new Error('Default coder VS Code settings must define at least one string-record entry.');
+    }
+    return defaultVscodeSettingsEntry;
+}
+// Note: [🟡] Code for coder init VS Code bootstrapping [ensureCoderVscodeSettingsFile](src/cli/cli-commands/coder/ensureCoderVscodeSettingsFile.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Ensures a relative directory exists in the project root.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+async function ensureDirectory(projectPath, relativeDirectoryPath) {
+    const directoryPath = join(projectPath, relativeDirectoryPath);
+    const isDirectoryExisting = await isExistingDirectory(directoryPath);
+    if (!isDirectoryExisting) {
+        await mkdir(directoryPath, { recursive: true });
+        return 'created';
+    }
+    return 'unchanged';
+}
+/**
+ * Checks whether a path exists and is a directory.
+ */
+async function isExistingDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch (_a) {
+        return false;
+    }
+}
+// Note: [🟡] Code for coder init directory creation [ensureDirectory](src/cli/cli-commands/coder/ensureDirectory.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Creates or updates all coder configuration artifacts required in the current project.
+ *
+ * @private internal utility of `coder init` command
+ */
+async function initializeCoderProjectConfiguration(projectPath) {
+    const promptsDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DIRECTORY_PATH);
+    const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
+    const promptsTemplatesDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH);
+    const promptTemplateFileStatuses = await ensureDefaultCoderPromptTemplateFiles(projectPath);
+    const agentsFileStatus = await ensureCoderMarkdownFile(projectPath, AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent());
+    const agentCodingFileStatus = await ensureCoderMarkdownFile(projectPath, AGENT_CODING_FILE_PATH, getDefaultCoderAgentCodingFileContent({
+        packageJsonScripts: getDefaultCoderPackageJsonScripts(),
+    }));
+    const { envFileStatus, initializedEnvVariableNames } = await ensureCoderEnvFile(projectPath);
+    const gitignoreFileStatus = await ensureCoderGitignoreFile(projectPath);
+    const packageJsonFileStatus = await ensureCoderPackageJsonFile(projectPath);
+    const vscodeSettingsFileStatus = await ensureCoderVscodeSettingsFile(projectPath);
+    return {
+        promptsDirectoryStatus,
+        promptsDoneDirectoryStatus,
+        promptsTemplatesDirectoryStatus,
+        promptTemplateFileStatuses,
+        agentsFileStatus,
+        agentCodingFileStatus,
+        envFileStatus,
+        gitignoreFileStatus,
+        packageJsonFileStatus,
+        vscodeSettingsFileStatus,
+        initializedEnvVariableNames,
+    };
 }
+// Note: [🟡] Code for coder init project bootstrapping [initializeCoderProjectConfiguration](src/cli/cli-commands/coder/initializeCoderProjectConfiguration.ts) should never be published outside of `@promptbook/cli`
+
 /**
  * Prints a readable summary of what was initialized for the user.
+ *
+ * @private function of `coder init` command
  */
 function printInitializationSummary(summary) {
     console.info(colors.green('Promptbook coder configuration initialized.'));
@@ -2352,6 +2857,8 @@ function printInitializationSummary(summary) {
     for (const templateFileStatus of summary.promptTemplateFileStatuses) {
         printInitializationStatusLine(formatDisplayPath(templateFileStatus.relativeFilePath), templateFileStatus.status);
     }
+    printInitializationStatusLine(AGENTS_FILE_PATH, summary.agentsFileStatus);
+    printInitializationStatusLine(AGENT_CODING_FILE_PATH, summary.agentCodingFileStatus);
     printInitializationStatusLine('.env', summary.envFileStatus);
     printInitializationStatusLine('.gitignore', summary.gitignoreFileStatus);
     printInitializationStatusLine('package.json', summary.packageJsonFileStatus);
@@ -2387,126 +2894,48 @@ function printInitializationStatusLine(relativePath, status) {
 function printInitializationNote(message, colorize) {
     console.info(colorize(`✔ ${message}`));
 }
-/**
- * Normalizes one project-relative path for human-readable CLI output.
- */
-function formatDisplayPath(relativePath) {
-    return relativePath.replace(/\\/gu, '/');
-}
-/**
- * Detects whether `.gitignore` already covers the standalone coder temp directory.
- */
-function hasTmpGitignoreRule(gitignoreContent) {
-    return /(^|[\r\n])\/?\.tmp(?:[\r\n]|$)/u.test(gitignoreContent);
-}
-/**
- * Reads one text file when it exists, otherwise returns `undefined`.
- */
-async function readTextFileIfExists(path) {
-    if (!(await isExistingFile(path))) {
-        return undefined;
-    }
-    return readFile(path, 'utf-8');
-}
-/**
- * Parses one JSON object file while accepting VS Code style comments and trailing commas.
- */
-async function parseJsonObjectFile(relativeFilePath, fileContent) {
-    if (fileContent.trim() === '') {
-        return {};
-    }
-    const typescript = await import('typescript');
-    const parsedFile = typescript.parseConfigFileTextToJson(relativeFilePath, fileContent);
-    if (parsedFile.error) {
-        throw new ParseError(spaceTrim$1(`
-                Cannot parse \`${relativeFilePath}\` as JSON.
+// Note: [🟡] Code for coder init summary printing [printInitializationSummary](src/cli/cli-commands/coder/printInitializationSummary.ts) should never be published outside of `@promptbook/cli`
 
-                ${typescript.flattenDiagnosticMessageText(parsedFile.error.messageText, '\n')}
-            `));
-    }
-    if (!isPlainObject(parsedFile.config)) {
-        throw new ParseError(spaceTrim$1(`
-                File \`${relativeFilePath}\` must contain one top-level JSON object.
-            `));
-    }
-    return parsedFile.config;
-}
 /**
- * Reads one JSON object field as a string-to-string record.
+ * Initializes `coder init` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
  */
-function getStringRecordOrDefault(value, relativeFilePath, fieldPath) {
-    if (value === undefined) {
-        return {};
-    }
-    if (!isPlainObject(value)) {
-        throw new ParseError(spaceTrim$1(`
-                File \`${relativeFilePath}\` contains invalid \`${fieldPath}\`.
+function $initializeCoderInitCommand(program) {
+    const command = program.command('init');
+    command.alias('initialize');
+    command.description(spaceTrim$1(`
+            Initialize Promptbook coder configuration for current project
 
-                Expected \`${fieldPath}\` to be an object with string values.
-            `));
-    }
-    const stringRecord = {};
-    for (const [key, itemValue] of Object.entries(value)) {
-        if (typeof itemValue !== 'string') {
-            throw new ParseError(spaceTrim$1(`
-                    File \`${relativeFilePath}\` contains invalid \`${fieldPath}.${key}\`.
+            Creates or updates:
+            - prompts/
+            - prompts/done/
+            ${listDefaultCoderProjectPromptTemplateDisplayPaths()}
+            - ${AGENTS_FILE_PATH}
+            - ${AGENT_CODING_FILE_PATH}
+            - .gitignore
+            - package.json
+            - .vscode/settings.json
 
-                    Expected \`${fieldPath}\` to be an object with string values.
-                `));
-        }
-        stringRecord[key] = itemValue;
-    }
-    return stringRecord;
-}
-/**
- * Serializes one JSON object using detected or default formatting.
- */
-function serializeJsonObject(value, formatting) {
-    return `${JSON.stringify(value, null, formatting.indentation)}${formatting.newline}`;
-}
-/**
- * Detects indentation and newline formatting from an existing JSON file.
- */
-function detectJsonFileFormatting(fileContent) {
-    if (!fileContent) {
-        return {
-            indentation: DEFAULT_JSON_FILE_INDENTATION,
-            newline: DEFAULT_JSON_FILE_NEWLINE,
-        };
-    }
-    const indentationMatch = fileContent.match(/^[ \t]+(?=")/mu);
-    return {
-        indentation: (indentationMatch === null || indentationMatch === void 0 ? void 0 : indentationMatch[0]) || DEFAULT_JSON_FILE_INDENTATION,
-        newline: fileContent.includes('\r\n') ? '\r\n' : '\n',
-    };
-}
-/**
- * Checks whether one parsed JSON value is a plain object.
- */
-function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-/**
- * Checks whether a path exists and is a file.
- */
-async function isExistingFile(path) {
-    try {
-        return (await stat(path)).isFile();
-    }
-    catch (_a) {
-        return false;
-    }
+            Ensures required coding-agent environment variables in .env:
+            - CODING_AGENT_GIT_NAME
+            - CODING_AGENT_GIT_EMAIL
+            - CODING_AGENT_GIT_SIGNING_KEY
+        `));
+    command.action(handleActionErrors(async () => {
+        const summary = await initializeCoderProjectConfiguration(process.cwd());
+        printInitializationSummary(summary);
+    }));
 }
 /**
- * Checks whether a path exists and is a directory.
+ * Lists the project-owned template file paths created by `ptbk coder init`.
  */
-async function isExistingDirectory(path) {
-    try {
-        return (await stat(path)).isDirectory();
-    }
-    catch (_a) {
-        return false;
-    }
+function listDefaultCoderProjectPromptTemplateDisplayPaths() {
+    return getDefaultCoderProjectPromptTemplateDefinitions()
+        .map(({ relativeFilePath }) => `- ${formatDisplayPath(relativeFilePath)}`)
+        .join('\n');
 }
 // Note: [🟡] Code for CLI command [init](src/cli/cli-commands/coder/init.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
@@ -40740,91 +41169,6 @@ var findFreshEmojiTags = /*#__PURE__*/Object.freeze({
     findFreshEmojiTag: findFreshEmojiTag
 });
 
-/**
- * Root folders that contain source-like files for scanning.
- */
-const SOURCE_ROOTS = ['src', 'apps', 'scripts', 'examples', 'agents', 'other'];
-/**
- * File extensions treated as source code.
- */
-const SOURCE_FILE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
-/**
- * Glob patterns that should be ignored when scanning for source files.
- */
-const SOURCE_FILE_IGNORE_GLOBS = [
-    '**/node_modules/**',
-    '**/packages/**',
-    '**/.*/**',
-    '**/.git/**',
-    '**/.idea/**',
-    '**/.vscode/**',
-    '**/.promptbook/**',
-    '**/.next/**',
-    '**/.tmp/**',
-    '**/tmp/**',
-    '**/coverage/**',
-    '**/dist/**',
-    '**/build/**',
-    '**/out/**',
-    '**/prompts/**',
-    '**/changelog/**',
-];
-/**
- * Default maximum line count for source files.
- */
-const DEFAULT_MAX_LINE_COUNT = 2000;
-/**
- * Per-extension line count limits.
- */
-const LINE_COUNT_LIMITS_BY_EXTENSION = {
-    '.ts': 2000,
-    '.tsx': 2000,
-    '.js': 2000,
-    '.jsx': 2000,
-};
-/**
- * Glob patterns that are exempt from line-count checks.
- */
-const LINE_COUNT_EXEMPT_GLOBS = ['other/cspell-dictionaries/**/*.txt'];
-/**
- * Maximum number of entities before a file is flagged.
- */
-const MAX_ENTITIES_PER_FILE = 20;
-/**
- * File extensions eligible for entity counting.
- */
-const ENTITY_COUNT_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
-/**
- * Markers that identify generated files which should be skipped.
- */
-const GENERATED_CODE_MARKERS = [
-    'WARNING: This code has been generated',
-    'This code has been generated so that any manual changes will be overwritten',
-];
-/**
- * Name of the prompts directory.
- */
-const PROMPTS_DIR_NAME = 'prompts';
-/**
- * Step size used for prompt numbering.
- */
-const PROMPT_NUMBER_STEP = 10;
-/**
- * Prefix used for generated prompt slugs.
- */
-const PROMPT_SLUG_PREFIX = 'refactor';
-/**
- * Label used to mark the target file in generated prompts.
- */
-const PROMPT_TARGET_LABEL = 'Target file';
-/**
- * Maximum length for generated prompt slugs.
- */
-const PROMPT_SLUG_MAX_LENGTH = 80;
-/**
- * Note: [?] Code in this file should never be published in any package
- */
-
 /**
  * Normalizes a repo-relative path to use forward slashes.
  *
@@ -40842,7 +41186,7 @@ function normalizeRefactorCandidatePath(pathValue) {
  * @private function of findRefactorCandidates
  */
 async function analyzeSourceFileForRefactorCandidate(options) {
-    const { filePath, lineCountExemptPaths, rootDir } = options;
+    const { filePath, heuristics, lineCountExemptPaths, rootDir } = options;
     const normalizedAbsolutePath = normalizeAbsolutePath$1(filePath);
     const content = await readFile(filePath, 'utf-8');
     if (isGeneratedFile(content)) {
@@ -40853,15 +41197,21 @@ async function analyzeSourceFileForRefactorCandidate(options) {
     const reasons = [];
     if (!lineCountExemptPaths.has(normalizedAbsolutePath)) {
         const lineCount = countLines(content);
-        const maxLines = getMaxLinesForExtension(extension);
+        const maxLines = getMaxLinesForExtension(extension, heuristics);
         if (lineCount > maxLines) {
             reasons.push(`lines ${lineCount}/${maxLines}`);
         }
     }
-    if (ENTITY_COUNT_EXTENSIONS.includes(extension)) {
-        const entityCount = countEntities(content, extension, filePath);
-        if (entityCount > MAX_ENTITIES_PER_FILE) {
-            reasons.push(`entities ${entityCount}/${MAX_ENTITIES_PER_FILE}`);
+    if (STRUCTURAL_ANALYSIS_EXTENSIONS.includes(extension)) {
+        const structureSummary = summarizeSourceFileStructure(content, extension, filePath);
+        if (structureSummary.entityCount > heuristics.maxEntityCountPerFile) {
+            reasons.push(`entities ${structureSummary.entityCount}/${heuristics.maxEntityCountPerFile}`);
+        }
+        if (structureSummary.functionCount > heuristics.maxFunctionCountPerFile) {
+            reasons.push(`functions ${structureSummary.functionCount}/${heuristics.maxFunctionCountPerFile}`);
+        }
+        if (structureSummary.maxFunctionComplexity > heuristics.maxFunctionComplexity) {
+            reasons.push(buildComplexityReason(structureSummary, heuristics.maxFunctionComplexity));
         }
     }
     if (reasons.length === 0) {
@@ -40886,9 +41236,9 @@ function isGeneratedFile(content) {
  *
  * @private function of analyzeSourceFileForRefactorCandidate
  */
-function getMaxLinesForExtension(extension) {
+function getMaxLinesForExtension(extension, heuristics) {
     var _a;
-    return (_a = LINE_COUNT_LIMITS_BY_EXTENSION[extension]) !== null && _a !== void 0 ? _a : DEFAULT_MAX_LINE_COUNT;
+    return (_a = heuristics.maxLineCountByExtension[extension]) !== null && _a !== void 0 ? _a : heuristics.maxDefaultLineCount;
 }
 /**
  * Counts lines while ignoring a trailing newline.
@@ -40903,14 +41253,17 @@ function countLines(content) {
     return lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
 }
 /**
- * Counts top-level entities in a source file.
+ * Summarizes the structural metrics used to score one source file.
  *
  * @private function of analyzeSourceFileForRefactorCandidate
  */
-function countEntities(content, extension, filePath) {
+function summarizeSourceFileStructure(content, extension, filePath) {
     const scriptKind = getScriptKindForExtension(extension);
-    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, false, scriptKind);
-    return countEntitiesInSourceFile(sourceFile);
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, scriptKind);
+    return {
+        entityCount: countEntitiesInSourceFile(sourceFile),
+        ...summarizeFunctionsInSourceFile(sourceFile),
+    };
 }
 /**
  * Counts top-level entities in a parsed TypeScript source file.
@@ -40944,6 +41297,169 @@ function countEntitiesInSourceFile(sourceFile) {
     }
     return count;
 }
+/**
+ * Summarizes named functions and methods in a parsed source file.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function summarizeFunctionsInSourceFile(sourceFile) {
+    let functionCount = 0;
+    let maxFunctionComplexity = 0;
+    let mostComplexFunctionName = null;
+    const visitNode = (node) => {
+        if (isCountedFunctionLikeDeclaration(node)) {
+            functionCount += 1;
+            const functionComplexity = calculateFunctionComplexity(node);
+            if (functionComplexity > maxFunctionComplexity) {
+                maxFunctionComplexity = functionComplexity;
+                mostComplexFunctionName = getFunctionDisplayName(node);
+            }
+        }
+        ts.forEachChild(node, visitNode);
+    };
+    visitNode(sourceFile);
+    return {
+        functionCount,
+        maxFunctionComplexity,
+        mostComplexFunctionName,
+    };
+}
+/**
+ * Determines whether a node counts as a named function or method for density checks.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function isCountedFunctionLikeDeclaration(node) {
+    if (ts.isFunctionDeclaration(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isConstructorDeclaration(node) ||
+        ts.isGetAccessorDeclaration(node) ||
+        ts.isSetAccessorDeclaration(node)) {
+        return true;
+    }
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+        return isNamedFunctionExpression(node);
+    }
+    return false;
+}
+/**
+ * Determines whether a function expression is attached to a named variable or property.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function isNamedFunctionExpression(node) {
+    const parent = node.parent;
+    return (ts.isVariableDeclaration(parent) || ts.isPropertyDeclaration(parent) || ts.isPropertyAssignment(parent));
+}
+/**
+ * Calculates a lightweight cyclomatic-complexity score for one function.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function calculateFunctionComplexity(functionNode) {
+    if (!functionNode.body) {
+        return 1;
+    }
+    let complexity = 1;
+    const visitNode = (node) => {
+        if (node !== functionNode.body && isCountedFunctionLikeDeclaration(node)) {
+            return;
+        }
+        if (isComplexityDecisionNode(node)) {
+            complexity += 1;
+        }
+        ts.forEachChild(node, visitNode);
+    };
+    visitNode(functionNode.body);
+    return complexity;
+}
+/**
+ * Determines whether a node should increase the complexity score.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function isComplexityDecisionNode(node) {
+    if (ts.isIfStatement(node) ||
+        ts.isConditionalExpression(node) ||
+        ts.isCatchClause(node) ||
+        ts.isForStatement(node) ||
+        ts.isForInStatement(node) ||
+        ts.isForOfStatement(node) ||
+        ts.isWhileStatement(node) ||
+        ts.isDoStatement(node) ||
+        ts.isCaseClause(node)) {
+        return true;
+    }
+    if (ts.isBinaryExpression(node)) {
+        const operatorKind = node.operatorToken.kind;
+        return (operatorKind === ts.SyntaxKind.AmpersandAmpersandToken ||
+            operatorKind === ts.SyntaxKind.BarBarToken ||
+            operatorKind === ts.SyntaxKind.QuestionQuestionToken);
+    }
+    return false;
+}
+/**
+ * Resolves a readable display name for a counted function-like declaration.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function getFunctionDisplayName(functionNode) {
+    if (ts.isConstructorDeclaration(functionNode)) {
+        return 'constructor';
+    }
+    if (ts.isFunctionDeclaration(functionNode) ||
+        ts.isMethodDeclaration(functionNode) ||
+        ts.isGetAccessorDeclaration(functionNode) ||
+        ts.isSetAccessorDeclaration(functionNode)) {
+        if (!functionNode.name) {
+            return null;
+        }
+        return getPropertyNameText(functionNode.name);
+    }
+    if (ts.isArrowFunction(functionNode) || ts.isFunctionExpression(functionNode)) {
+        if (functionNode.name) {
+            return functionNode.name.text;
+        }
+        const parent = functionNode.parent;
+        if (ts.isVariableDeclaration(parent)) {
+            return getBindingNameText(parent.name);
+        }
+        if (ts.isPropertyDeclaration(parent) || ts.isPropertyAssignment(parent)) {
+            return getPropertyNameText(parent.name);
+        }
+    }
+    return null;
+}
+/**
+ * Resolves text for a binding name when it is a simple identifier.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function getBindingNameText(name) {
+    return ts.isIdentifier(name) ? name.text : null;
+}
+/**
+ * Resolves text for a property name while preserving computed names when necessary.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function getPropertyNameText(name) {
+    if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+        return name.text;
+    }
+    return name.getText();
+}
+/**
+ * Formats the reason emitted when a function in the file exceeds the complexity threshold.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function buildComplexityReason(structureSummary, maxAllowedFunctionComplexity) {
+    const functionSuffix = structureSummary.mostComplexFunctionName
+        ? ` in \`${structureSummary.mostComplexFunctionName}\``
+        : '';
+    return `complexity ${structureSummary.maxFunctionComplexity}/${maxAllowedFunctionComplexity}${functionSuffix}`;
+}
 /**
  * Resolves the script kind for a source file extension.
  *
@@ -40977,13 +41493,15 @@ function normalizeAbsolutePath$1(pathValue) {
  *
  * @private function of findRefactorCandidates
  */
-async function findRefactorCandidatesInProject(rootDir) {
-    const lineCountExemptPaths = await buildExemptPathSet(rootDir, LINE_COUNT_EXEMPT_GLOBS);
-    const sourceFiles = await listSourceFiles(rootDir);
+async function findRefactorCandidatesInProject(options) {
+    const { heuristics, isIgnoredRelativePath = () => false, rootDir } = options;
+    const lineCountExemptPaths = await buildExemptPathSet(rootDir, LINE_COUNT_EXEMPT_GLOBS, isIgnoredRelativePath);
+    const sourceFiles = await listSourceFiles(rootDir, isIgnoredRelativePath);
     const candidates = [];
     for (const filePath of sourceFiles) {
         const candidate = await analyzeSourceFileForRefactorCandidate({
             filePath,
+            heuristics,
             lineCountExemptPaths,
             rootDir,
         });
@@ -40998,7 +41516,7 @@ async function findRefactorCandidatesInProject(rootDir) {
  *
  * @private function of findRefactorCandidatesInProject
  */
-async function listSourceFiles(rootDir) {
+async function listSourceFiles(rootDir, isIgnoredRelativePath) {
     const extensions = SOURCE_FILE_EXTENSIONS.map((extension) => extension.replace(/^\./, '')).join(',');
     const extensionGlob = `{${extensions}}`;
     const patterns = [...SOURCE_ROOTS.map((root) => `${root}/**/*.${extensionGlob}`), `*.${extensionGlob}`];
@@ -41011,6 +41529,9 @@ async function listSourceFiles(rootDir) {
             absolute: true,
         });
         for (const match of matches) {
+            if (shouldIgnoreAbsolutePath(rootDir, match, isIgnoredRelativePath)) {
+                continue;
+            }
             files.add(match);
         }
     }
@@ -41021,7 +41542,7 @@ async function listSourceFiles(rootDir) {
  *
  * @private function of findRefactorCandidatesInProject
  */
-async function buildExemptPathSet(rootDir, patterns) {
+async function buildExemptPathSet(rootDir, patterns, isIgnoredRelativePath) {
     const exemptPaths = new Set();
     for (const pattern of patterns) {
         const matches = await glob(pattern, {
@@ -41031,11 +41552,23 @@ async function buildExemptPathSet(rootDir, patterns) {
             absolute: true,
         });
         for (const match of matches) {
+            if (shouldIgnoreAbsolutePath(rootDir, match, isIgnoredRelativePath)) {
+                continue;
+            }
             exemptPaths.add(normalizeAbsolutePath(match));
         }
     }
     return exemptPaths;
 }
+/**
+ * Resolves whether an absolute path falls under the project `.gitignore` rules.
+ *
+ * @private function of findRefactorCandidatesInProject
+ */
+function shouldIgnoreAbsolutePath(rootDir, absolutePath, isIgnoredRelativePath) {
+    const relativePath = normalizeRefactorCandidatePath(relative(rootDir, absolutePath));
+    return isIgnoredRelativePath(relativePath);
+}
 /**
  * Normalizes an absolute path for consistent comparisons.
  *
@@ -41084,6 +41617,69 @@ function escapeRegExp(value) {
 }
 // Note: [🟡] Code for repository script [loadExistingPromptTargets](scripts/find-refactor-candidates/loadExistingPromptTargets.ts) should never be published outside of `@promptbook/cli`
 
+/**
+ * Filename used to discover the project root for refactor-candidate scanning.
+ */
+const GITIGNORE_FILE_NAME = '.gitignore';
+/**
+ * Resolves the project root and `.gitignore` matcher for refactor-candidate scanning.
+ *
+ * @private function of findRefactorCandidates
+ */
+async function resolveRefactorCandidateProject(startDir) {
+    const absoluteStartDir = resolve(startDir);
+    const gitignorePath = await findNearestGitignorePath(absoluteStartDir);
+    if (!gitignorePath) {
+        return {
+            rootDir: absoluteStartDir,
+            isIgnoredRelativePath: () => false,
+        };
+    }
+    const rootDir = dirname(gitignorePath);
+    const gitignoreMatcher = ignore().add(await readFile(gitignorePath, 'utf-8'));
+    return {
+        rootDir,
+        isIgnoredRelativePath(relativePath) {
+            return gitignoreMatcher.ignores(normalizeRefactorCandidatePath(relativePath));
+        },
+    };
+}
+/**
+ * Finds the nearest ancestor `.gitignore` so scans work from any project subdirectory.
+ *
+ * @private function of resolveRefactorCandidateProject
+ */
+async function findNearestGitignorePath(startDir) {
+    let currentDir = resolve(startDir);
+    while (true) {
+        const gitignorePath = join(currentDir, GITIGNORE_FILE_NAME);
+        if (await isExistingFile(gitignorePath)) {
+            return gitignorePath;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
+/**
+ * Detects whether a file exists without swallowing unexpected filesystem failures.
+ *
+ * @private function of resolveRefactorCandidateProject
+ */
+async function isExistingFile(filePath) {
+    var _a;
+    const fileStats = await stat(filePath).catch((error) => {
+        if (error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    });
+    return (_a = fileStats === null || fileStats === void 0 ? void 0 : fileStats.isFile()) !== null && _a !== void 0 ? _a : false;
+}
+// Note: [🟡] Code for repository script [resolveRefactorCandidateProject](scripts/find-refactor-candidates/resolveRefactorCandidateProject.ts) should never be published outside of `@promptbook/cli`
+
 /**
  * Calculates the next available prompt numbering sequence for a month.
  */
@@ -41256,11 +41852,18 @@ function buildPromptGuidance(candidate) {
     if (counts.entityCount !== null && counts.maxEntities !== null) {
         guidance.push(`- The file defines too many responsibilities (${counts.entityCount} in single file)`, `    - Keep in mind the Single Responsibility Principle (SRP)`, `    - Consider breaking it down into smaller, focused modules or components.`);
     }
+    if (counts.functionCount !== null && counts.maxFunctions !== null) {
+        guidance.push(`- The file contains too many functions (${counts.functionCount}/${counts.maxFunctions})`, `    - Keep related responsibilities grouped behind small facades or focused modules.`, `    - Consider extracting private helpers or splitting independent concerns into dedicated files.`);
+    }
+    if (counts.functionComplexity !== null && counts.maxFunctionComplexity !== null) {
+        const functionSuffix = counts.mostComplexFunctionName ? ` in \`${counts.mostComplexFunctionName}\`` : '';
+        guidance.push(`- The file contains overly complex logic${functionSuffix} (${counts.functionComplexity}/${counts.maxFunctionComplexity})`, `    - Break branching logic into smaller, focused helper functions.`, `    - Keep each function responsible for one clear step or decision.`);
+    }
     guidance.push('- Purpose of this refactoring is to improve code maintainability and readability.', '- Look at the internal structure, the usage and also surrounding code to understand how to best refactor this file.', '- Consider breaking down large functions into smaller, more manageable ones, removing any redundant code, and ensuring that the file adheres to the project coding standards.', '- After the refactoring, ensure that (1) `npm run test-name-discrepancies` and (2) `npm run test-package-generation` are passing successfully.', '    1. All the things you have moved to new files should correspond the thing in the file with the file name, for example `MyComponent.tsx` should export `MyComponent`.', '    2. All the things you have moved to new files but are private things to the outside world should have `@private function of TheMainThing` JSDoc comment.', '- Keep in mind DRY *(Do not repeat yourself)* and SOLID principles while refactoring.', '- **Do not change the external behavior** of the code. Focus solely on improving the internal structure and organization of the code.', '- Before you start refactoring, make sure to read the code carefully and understand its current structure and functionality. Do a analysis of the current functionality before you start.');
     return guidance;
 }
 /**
- * Extracts line and entity counts from refactor reasons.
+ * Extracts structural counts from refactor reasons.
  *
  * @private function of buildPromptContent
  */
@@ -41269,6 +41872,11 @@ function extractReasonCounts(reasons) {
     let maxLines = null;
     let entityCount = null;
     let maxEntities = null;
+    let functionCount = null;
+    let maxFunctions = null;
+    let functionComplexity = null;
+    let maxFunctionComplexity = null;
+    let mostComplexFunctionName = null;
     for (const reason of reasons) {
         const lineMatch = reason.match(/lines\s+(?<count>\d+)\/(?<max>\d+)/i);
         if (lineMatch === null || lineMatch === void 0 ? void 0 : lineMatch.groups) {
@@ -41280,6 +41888,19 @@ function extractReasonCounts(reasons) {
         if (entityMatch === null || entityMatch === void 0 ? void 0 : entityMatch.groups) {
             entityCount = Number(entityMatch.groups.count);
             maxEntities = Number(entityMatch.groups.max);
+            continue;
+        }
+        const functionMatch = reason.match(/functions\s+(?<count>\d+)\/(?<max>\d+)/i);
+        if (functionMatch === null || functionMatch === void 0 ? void 0 : functionMatch.groups) {
+            functionCount = Number(functionMatch.groups.count);
+            maxFunctions = Number(functionMatch.groups.max);
+            continue;
+        }
+        const complexityMatch = reason.match(/complexity\s+(?<count>\d+)\/(?<max>\d+)(?:\s+in\s+`(?<functionName>[^`]+)`)?/i);
+        if (complexityMatch === null || complexityMatch === void 0 ? void 0 : complexityMatch.groups) {
+            functionComplexity = Number(complexityMatch.groups.count);
+            maxFunctionComplexity = Number(complexityMatch.groups.max);
+            mostComplexFunctionName = complexityMatch.groups.functionName || null;
         }
     }
     return {
@@ -41287,6 +41908,11 @@ function extractReasonCounts(reasons) {
         maxLines,
         entityCount,
         maxEntities,
+        functionCount,
+        maxFunctions,
+        functionComplexity,
+        maxFunctionComplexity,
+        mostComplexFunctionName,
     };
 }
 /**
@@ -41295,14 +41921,23 @@ function extractReasonCounts(reasons) {
  * @private function of buildPromptContent
  */
 function buildDensityNote(counts) {
-    if (counts.lineCount !== null && counts.entityCount !== null) {
-        return 'The file mixes multiple concerns, making it harder to follow.';
+    const activeSignalsCount = [
+        counts.lineCount !== null,
+        counts.entityCount !== null,
+        counts.functionCount !== null,
+        counts.functionComplexity !== null,
+    ].filter(Boolean).length;
+    if (activeSignalsCount > 1) {
+        return 'The file mixes multiple concerns and dense logic, making it harder to follow.';
     }
     if (counts.lineCount !== null) {
         return 'The file is large enough that it is hard to follow.';
     }
-    if (counts.entityCount !== null) {
-        return 'The file is dense enough that it is hard to follow.';
+    if (counts.entityCount !== null || counts.functionCount !== null) {
+        return 'The file packs too many responsibilities into one place.';
+    }
+    if (counts.functionComplexity !== null) {
+        return 'The file contains logic that is too complex to follow comfortably.';
     }
     return null;
 }
@@ -41396,13 +42031,20 @@ function initializeFindRefactorCandidatesRun() {
  *
  * @public exported from `@promptbook/cli`
  */
-async function findRefactorCandidates() {
+async function findRefactorCandidates(options = {}) {
+    const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL } = options;
+    const heuristics = getRefactorCandidateLevelConfiguration(level);
     initializeFindRefactorCandidatesRun();
-    console.info(colors.cyan('?? Find refactor candidates'));
-    const rootDir = process.cwd();
+    console.info(colors.cyan('⚡🏭 Find refactor candidates'));
+    console.info(colors.gray(`Using \`${level}\` scan level.`));
+    const { isIgnoredRelativePath, rootDir } = await resolveRefactorCandidateProject(process.cwd());
     const promptsDir = join(rootDir, PROMPTS_DIR_NAME);
     const existingTargets = await loadExistingPromptTargets(promptsDir);
-    const candidates = await findRefactorCandidatesInProject(rootDir);
+    const candidates = await findRefactorCandidatesInProject({
+        heuristics,
+        isIgnoredRelativePath,
+        rootDir,
+    });
     if (candidates.length === 0) {
         console.info(colors.green('No refactor candidates found.'));
         return;