@promptbook/cli 0.112.0-36 → 0.112.0-39

package/umd/index.umd.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('commander'), require('spacetrim'), require('fs'), require('path'), require('fs/promises'), require('waitasecond'), require('prompts'), require('dotenv'), require('crypto-js/enc-hex'), require('crypto-js/sha256'), require('socket.io-client'), require('crypto-js'), require('jszip'), require('crypto'), require('@mozilla/readability'), require('jsdom'), require('showdown'), require('glob-promise'), require('moment'), require('express'), require('express-openapi-validator'), require('http'), require('socket.io'), require('swagger-ui-express'), require('react'), require('react-dom/server'), require('@anthropic-ai/sdk'), require('bottleneck'), require('@azure/openai'), require('typescript'), require('readline'), require('child_process'), require('pg'), require('@supabase/supabase-js'), require('path/posix'), require('rxjs'), require('mime-types'), require('papaparse'), require('@openai/agents'), require('openai')) :
-    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'commander', 'spacetrim', 'fs', 'path', 'fs/promises', 'waitasecond', 'prompts', 'dotenv', 'crypto-js/enc-hex', 'crypto-js/sha256', 'socket.io-client', 'crypto-js', 'jszip', 'crypto', '@mozilla/readability', 'jsdom', 'showdown', 'glob-promise', 'moment', 'express', 'express-openapi-validator', 'http', 'socket.io', 'swagger-ui-express', 'react', 'react-dom/server', '@anthropic-ai/sdk', 'bottleneck', '@azure/openai', 'typescript', 'readline', 'child_process', 'pg', '@supabase/supabase-js', 'path/posix', 'rxjs', 'mime-types', 'papaparse', '@openai/agents', 'openai'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-cli"] = {}, global.colors, global.commander, global._spaceTrim, global.fs, global.path, global.promises, global.waitasecond, global.prompts, global.dotenv, global.hexEncoder, global.sha256, global.socket_ioClient, global.cryptoJs, global.JSZip, global.crypto, global.readability, global.jsdom, global.showdown, global.glob, global.moment, global.express, global.OpenApiValidator, global.http, global.socket_io, global.swaggerUi, global.react, global.server, global.Anthropic, global.Bottleneck, global.openai, global.ts, global.readline, global.child_process, global.pg, null, global.posix, global.rxjs, global.mimeTypes, global.papaparse, global.agents, global.OpenAI));
-})(this, (function (exports, colors, commander, _spaceTrim, fs, path, promises, waitasecond, prompts, dotenv, hexEncoder, sha256, socket_ioClient, cryptoJs, JSZip, crypto, readability, jsdom, showdown, glob, moment, express, OpenApiValidator, http, socket_io, swaggerUi, react, server, Anthropic, Bottleneck, openai, ts, readline, child_process, pg, supabaseJs, posix, rxjs, mimeTypes, papaparse, agents, OpenAI) { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('commander'), require('spacetrim'), require('fs'), require('path'), require('fs/promises'), require('waitasecond'), require('prompts'), require('dotenv'), require('crypto-js/enc-hex'), require('crypto-js/sha256'), require('socket.io-client'), require('crypto-js'), require('jszip'), require('crypto'), require('@mozilla/readability'), require('jsdom'), require('showdown'), require('glob-promise'), require('moment'), require('express'), require('express-openapi-validator'), require('http'), require('socket.io'), require('swagger-ui-express'), require('react'), require('react-dom/server'), require('@anthropic-ai/sdk'), require('bottleneck'), require('@azure/openai'), require('typescript'), require('ignore'), require('readline'), require('child_process'), require('pg'), require('@supabase/supabase-js'), require('path/posix'), require('rxjs'), require('mime-types'), require('papaparse'), require('@openai/agents'), require('openai')) :
+    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'commander', 'spacetrim', 'fs', 'path', 'fs/promises', 'waitasecond', 'prompts', 'dotenv', 'crypto-js/enc-hex', 'crypto-js/sha256', 'socket.io-client', 'crypto-js', 'jszip', 'crypto', '@mozilla/readability', 'jsdom', 'showdown', 'glob-promise', 'moment', 'express', 'express-openapi-validator', 'http', 'socket.io', 'swagger-ui-express', 'react', 'react-dom/server', '@anthropic-ai/sdk', 'bottleneck', '@azure/openai', 'typescript', 'ignore', 'readline', 'child_process', 'pg', '@supabase/supabase-js', 'path/posix', 'rxjs', 'mime-types', 'papaparse', '@openai/agents', 'openai'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-cli"] = {}, global.colors, global.commander, global._spaceTrim, global.fs, global.path, global.promises, global.waitasecond, global.prompts, global.dotenv, global.hexEncoder, global.sha256, global.socket_ioClient, global.cryptoJs, global.JSZip, global.crypto, global.readability, global.jsdom, global.showdown, global.glob, global.moment, global.express, global.OpenApiValidator, global.http, global.socket_io, global.swaggerUi, global.react, global.server, global.Anthropic, global.Bottleneck, global.openai, global.ts, global.ignore, global.readline, global.child_process, global.pg, null, global.posix, global.rxjs, global.mimeTypes, global.papaparse, global.agents, global.OpenAI));
+})(this, (function (exports, colors, commander, _spaceTrim, fs, path, promises, waitasecond, prompts, dotenv, hexEncoder, sha256, socket_ioClient, cryptoJs, JSZip, crypto, readability, jsdom, showdown, glob, moment, express, OpenApiValidator, http, socket_io, swaggerUi, react, server, Anthropic, Bottleneck, openai, ts, ignore, readline, child_process, pg, supabaseJs, posix, rxjs, mimeTypes, papaparse, agents, OpenAI) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -43,6 +43,7 @@
     var Anthropic__default = /*#__PURE__*/_interopDefaultLegacy(Anthropic);
     var Bottleneck__default = /*#__PURE__*/_interopDefaultLegacy(Bottleneck);
     var ts__namespace = /*#__PURE__*/_interopNamespace(ts);
+    var ignore__default = /*#__PURE__*/_interopDefaultLegacy(ignore);
     var readline__namespace = /*#__PURE__*/_interopNamespace(readline);
     var OpenAI__default = /*#__PURE__*/_interopDefaultLegacy(OpenAI);
 
@@ -60,7 +61,7 @@
      * @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
@@ -1664,6 +1665,181 @@
     // 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
      *
@@ -1673,20 +1849,23 @@
      */
     function $initializeCoderFindRefactorCandidatesCommand(program) {
         const command = program.command('find-refactor-candidates');
-        command.description(_spaceTrim.spaceTrim(`
-            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 commander.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);
@@ -1732,7 +1911,9 @@
      */
     const PROMPTS_TEMPLATES_DIRECTORY_PATH = 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 = [
         {
@@ -1741,10 +1922,11 @@
             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',
@@ -1752,14 +1934,19 @@
             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.
      *
@@ -1768,6 +1955,14 @@
     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.
      *
@@ -1787,9 +1982,9 @@
      */
     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 = path.join(projectPath, definition.relativeFilePath);
-            if (await isExistingFile$1(absoluteTemplatePath)) {
+            if (await isExistingFile$2(absoluteTemplatePath)) {
                 ensuredTemplateFiles.push({
                     id: definition.id,
                     relativeFilePath: definition.relativeFilePath,
@@ -1903,7 +2098,7 @@
     /**
      * Checks whether a path exists and is a file.
      */
-    async function isExistingFile$1(path) {
+    async function isExistingFile$2(path) {
         try {
             return (await promises.stat(path)).isFile();
         }
@@ -2053,178 +2248,202 @@
     // 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.spaceTrim(`
-    # 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.spaceTrim(`
-            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 promises.stat(path);
+            if (!fileStats.isFile()) {
+                return undefined;
+            }
+        }
+        catch (_a) {
+            return undefined;
+        }
+        return promises.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 = path.join(projectPath, relativeDirectoryPath);
-        const existedBefore = await isExistingDirectory(directoryPath);
-        if (!existedBefore) {
-            await promises.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 = path.join(projectPath, '.env');
-        const envFileExistedBefore = await isExistingFile(envFilePath);
-        const currentEnvContent = envFileExistedBefore ? await promises.readFile(envFilePath, 'utf-8') : '';
-        const existingEnvVariables = parseEnvVariableNames(currentEnvContent);
-        const missingEnvVariables = REQUIRED_CODER_ENV_VARIABLES.filter(({ name }) => !existingEnvVariables.has(name));
+        const envFilePath = path.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 promises.writeFile(envFilePath, '# Environment variables for Promptbook coder\n', 'utf-8');
+            if (!isEnvFileExisting) {
+                await promises.writeFile(envFilePath, EMPTY_CODER_ENV_FILE_CONTENT, 'utf-8');
                 return {
                     envFileStatus: 'created',
                     initializedEnvVariableNames: [],
@@ -2239,12 +2458,54 @@
         const nextEnvContent = appendBlock(currentEnvContent, envBlockToAppend);
         await promises.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.spaceTrim(`
+        # 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.spaceTrim(`
+    # Promptbook Coder
+    /.tmp
+`);
     /**
      * Ensures `.gitignore` contains the standalone Promptbook coder cache entry.
+     *
+     * @private function of `initializeCoderProjectConfiguration`
      */
     async function ensureCoderGitignoreFile(projectPath) {
         const gitignorePath = path.join(projectPath, GITIGNORE_FILE_PATH);
@@ -2257,95 +2518,339 @@
         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 = path.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 = path.join(projectPath, relativeFilePath);
+        if (await isExistingFile$1(absoluteFilePath)) {
+            return 'unchanged';
+        }
+        await promises.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 promises.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 promises.mkdir(path.join(projectPath, ensureParentDirectoryPath), { recursive: true });
+        }
+        const absoluteFilePath = path.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 promises.writeFile(packageJsonPath, serializeJsonObject(nextPackageJson, formatting), 'utf-8');
-        return packageJsonContent === undefined ? 'created' : 'updated';
+        const nextJsonObject = { ...jsonObject };
+        nextJsonObject[fieldPath] = mergedEntries;
+        await promises.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 promises.mkdir(path.join(projectPath, VSCODE_DIRECTORY_PATH), { recursive: true });
-        const vscodeSettingsPath = path.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.spaceTrim(`
+                Cannot parse \`${relativeFilePath}\` as JSON.
+
+                ${typescript.flattenDiagnosticMessageText(parsedFile.error.messageText, '\n')}
+            `));
         }
-        const nextVscodeSettings = { ...vscodeSettings };
-        nextVscodeSettings[MARKDOWN_COPY_FILES_DESTINATION_SETTING_KEY] = nextMarkdownCopyFilesDestinations;
-        await promises.writeFile(vscodeSettingsPath, serializeJsonObject(nextVscodeSettings, formatting), 'utf-8');
-        return vscodeSettingsContent === undefined ? 'created' : 'updated';
+        if (!isPlainObject(parsedFile.config)) {
+            throw new ParseError(_spaceTrim.spaceTrim(`
+                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.spaceTrim(`
+                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.spaceTrim(`
+                    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.spaceTrim(`
-        # 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 = path.join(projectPath, relativeDirectoryPath);
+        const isDirectoryExisting = await isExistingDirectory(directoryPath);
+        if (!isDirectoryExisting) {
+            await promises.mkdir(directoryPath, { recursive: true });
+            return 'created';
+        }
+        return 'unchanged';
+    }
+    /**
+     * Checks whether a path exists and is a directory.
+     */
+    async function isExistingDirectory(path) {
+        try {
+            return (await promises.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__default["default"].green('Promptbook coder configuration initialized.'));
@@ -2355,6 +2860,8 @@
         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);
@@ -2390,126 +2897,48 @@
     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 promises.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.spaceTrim(`
-                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.spaceTrim(`
-                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.spaceTrim(`
-                File \`${relativeFilePath}\` contains invalid \`${fieldPath}\`.
+    function $initializeCoderInitCommand(program) {
+        const command = program.command('init');
+        command.alias('initialize');
+        command.description(_spaceTrim.spaceTrim(`
+            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.spaceTrim(`
-                    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 promises.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 promises.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
@@ -40743,91 +41172,6 @@
         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.
      *
@@ -40845,7 +41189,7 @@
      * @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 promises.readFile(filePath, 'utf-8');
         if (isGeneratedFile(content)) {
@@ -40856,15 +41200,21 @@
         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) {
@@ -40889,9 +41239,9 @@
      *
      * @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.
@@ -40906,14 +41256,17 @@
         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__namespace.createSourceFile(filePath, content, ts__namespace.ScriptTarget.Latest, false, scriptKind);
-        return countEntitiesInSourceFile(sourceFile);
+        const sourceFile = ts__namespace.createSourceFile(filePath, content, ts__namespace.ScriptTarget.Latest, true, scriptKind);
+        return {
+            entityCount: countEntitiesInSourceFile(sourceFile),
+            ...summarizeFunctionsInSourceFile(sourceFile),
+        };
     }
     /**
      * Counts top-level entities in a parsed TypeScript source file.
@@ -40947,6 +41300,169 @@
         }
         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__namespace.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__namespace.isFunctionDeclaration(node) ||
+            ts__namespace.isMethodDeclaration(node) ||
+            ts__namespace.isConstructorDeclaration(node) ||
+            ts__namespace.isGetAccessorDeclaration(node) ||
+            ts__namespace.isSetAccessorDeclaration(node)) {
+            return true;
+        }
+        if (ts__namespace.isArrowFunction(node) || ts__namespace.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__namespace.isVariableDeclaration(parent) || ts__namespace.isPropertyDeclaration(parent) || ts__namespace.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__namespace.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__namespace.isIfStatement(node) ||
+            ts__namespace.isConditionalExpression(node) ||
+            ts__namespace.isCatchClause(node) ||
+            ts__namespace.isForStatement(node) ||
+            ts__namespace.isForInStatement(node) ||
+            ts__namespace.isForOfStatement(node) ||
+            ts__namespace.isWhileStatement(node) ||
+            ts__namespace.isDoStatement(node) ||
+            ts__namespace.isCaseClause(node)) {
+            return true;
+        }
+        if (ts__namespace.isBinaryExpression(node)) {
+            const operatorKind = node.operatorToken.kind;
+            return (operatorKind === ts__namespace.SyntaxKind.AmpersandAmpersandToken ||
+                operatorKind === ts__namespace.SyntaxKind.BarBarToken ||
+                operatorKind === ts__namespace.SyntaxKind.QuestionQuestionToken);
+        }
+        return false;
+    }
+    /**
+     * Resolves a readable display name for a counted function-like declaration.
+     *
+     * @private function of analyzeSourceFileForRefactorCandidate
+     */
+    function getFunctionDisplayName(functionNode) {
+        if (ts__namespace.isConstructorDeclaration(functionNode)) {
+            return 'constructor';
+        }
+        if (ts__namespace.isFunctionDeclaration(functionNode) ||
+            ts__namespace.isMethodDeclaration(functionNode) ||
+            ts__namespace.isGetAccessorDeclaration(functionNode) ||
+            ts__namespace.isSetAccessorDeclaration(functionNode)) {
+            if (!functionNode.name) {
+                return null;
+            }
+            return getPropertyNameText(functionNode.name);
+        }
+        if (ts__namespace.isArrowFunction(functionNode) || ts__namespace.isFunctionExpression(functionNode)) {
+            if (functionNode.name) {
+                return functionNode.name.text;
+            }
+            const parent = functionNode.parent;
+            if (ts__namespace.isVariableDeclaration(parent)) {
+                return getBindingNameText(parent.name);
+            }
+            if (ts__namespace.isPropertyDeclaration(parent) || ts__namespace.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__namespace.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__namespace.isIdentifier(name) || ts__namespace.isPrivateIdentifier(name) || ts__namespace.isStringLiteral(name) || ts__namespace.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.
      *
@@ -40980,13 +41496,15 @@
      *
      * @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,
             });
@@ -41001,7 +41519,7 @@
      *
      * @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}`];
@@ -41014,6 +41532,9 @@
                 absolute: true,
             });
             for (const match of matches) {
+                if (shouldIgnoreAbsolutePath(rootDir, match, isIgnoredRelativePath)) {
+                    continue;
+                }
                 files.add(match);
             }
         }
@@ -41024,7 +41545,7 @@
      *
      * @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__default["default"](pattern, {
@@ -41034,11 +41555,23 @@
                 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(path.relative(rootDir, absolutePath));
+        return isIgnoredRelativePath(relativePath);
+    }
     /**
      * Normalizes an absolute path for consistent comparisons.
      *
@@ -41087,6 +41620,69 @@
     }
     // 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 = path.resolve(startDir);
+        const gitignorePath = await findNearestGitignorePath(absoluteStartDir);
+        if (!gitignorePath) {
+            return {
+                rootDir: absoluteStartDir,
+                isIgnoredRelativePath: () => false,
+            };
+        }
+        const rootDir = path.dirname(gitignorePath);
+        const gitignoreMatcher = ignore__default["default"]().add(await promises.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 = path.resolve(startDir);
+        while (true) {
+            const gitignorePath = path.join(currentDir, GITIGNORE_FILE_NAME);
+            if (await isExistingFile(gitignorePath)) {
+                return gitignorePath;
+            }
+            const parentDir = path.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 promises.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.
      */
@@ -41259,11 +41855,18 @@
         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
      */
@@ -41272,6 +41875,11 @@
         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) {
@@ -41283,6 +41891,19 @@
             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 {
@@ -41290,6 +41911,11 @@
             maxLines,
             entityCount,
             maxEntities,
+            functionCount,
+            maxFunctions,
+            functionComplexity,
+            maxFunctionComplexity,
+            mostComplexFunctionName,
         };
     }
     /**
@@ -41298,14 +41924,23 @@
      * @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;
     }
@@ -41399,13 +42034,20 @@
      *
      * @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__default["default"].cyan('?? Find refactor candidates'));
-        const rootDir = process.cwd();
+        console.info(colors__default["default"].cyan('⚡🏭 Find refactor candidates'));
+        console.info(colors__default["default"].gray(`Using \`${level}\` scan level.`));
+        const { isIgnoredRelativePath, rootDir } = await resolveRefactorCandidateProject(process.cwd());
         const promptsDir = path.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__default["default"].green('No refactor candidates found.'));
             return;