@promptbook/cli 0.112.0-35 → 0.112.0-38

package/umd/index.umd.js

@@ -60,7 +60,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-35';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-38';
     /**
      * 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 +1664,142 @@
     // 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 = ['low', 'medium', 'high', 'xhigh'];
+    /**
+     * 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_CONFIGURATION_BY_LEVEL = {
+        low: createRefactorCandidateLevelConfiguration({
+            maxLineCount: 2800,
+            maxEntityCountPerFile: 28,
+            maxFunctionCountPerFile: 18,
+            maxFunctionComplexity: 20,
+        }),
+        medium: createRefactorCandidateLevelConfiguration({
+            maxLineCount: 2000,
+            maxEntityCountPerFile: 20,
+            maxFunctionCountPerFile: 14,
+            maxFunctionComplexity: 16,
+        }),
+        high: createRefactorCandidateLevelConfiguration({
+            maxLineCount: 1500,
+            maxEntityCountPerFile: 16,
+            maxFunctionCountPerFile: 10,
+            maxFunctionComplexity: 12,
+        }),
+        xhigh: createRefactorCandidateLevelConfiguration({
+            maxLineCount: 1000,
+            maxEntityCountPerFile: 12,
+            maxFunctionCountPerFile: 8,
+            maxFunctionComplexity: 8,
+        }),
+    };
+    /**
+     * Resolves the thresholds for a selected refactor-candidate scanning level.
+     */
+    function getRefactorCandidateLevelConfiguration(level = DEFAULT_REFACTOR_CANDIDATE_LEVEL) {
+        return REFACTOR_CANDIDATE_LEVEL_CONFIGURATION_BY_LEVEL[level];
+    }
+    /**
+     * 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
      *
@@ -1676,17 +1812,23 @@
         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)
+            Levels:
+            - low: Conservative scan for only the most obvious refactor targets
+            - medium: Default scan using the current standard thresholds
+            - high: Stricter scan that finds more crowded or complex files
+            - xhigh: Most aggressive scan for denser and more complex candidates
 
             Generates refactor prompts with guidance for identified candidates.
         `));
-        command.action(handleActionErrors(async () => {
+        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);
@@ -1700,6 +1842,236 @@
     // Note: [🟡] Code for CLI command [find-refactor-candidates](src/cli/cli-commands/coder/find-refactor-candidates.ts) should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
+    /**
+     * This error indicates that promptbook not found in the collection
+     *
+     * @public exported from `@promptbook/core`
+     */
+    class NotFoundError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = 'NotFoundError';
+            Object.setPrototypeOf(this, NotFoundError.prototype);
+        }
+    }
+
+    /**
+     * Relative path to the root prompts directory used by Promptbook coder utilities.
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    const PROMPTS_DIRECTORY_PATH = 'prompts';
+    /**
+     * Relative path to the archive directory used by `coder verify`.
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    const PROMPTS_DONE_DIRECTORY_PATH = path.join(PROMPTS_DIRECTORY_PATH, 'done');
+    /**
+     * Relative path to the project-owned boilerplate templates directory.
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    const PROMPTS_TEMPLATES_DIRECTORY_PATH = path.join(PROMPTS_DIRECTORY_PATH, 'templates');
+    /**
+     * 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 = [
+        {
+            id: 'common',
+            relativeFilePath: path.join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'common.md'),
+            slugPrefix: null,
+            content: buildCoderPromptTemplateContent([
+                '-   @@@',
+                "-   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',
+            relativeFilePath: path.join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'agents-server.md'),
+            slugPrefix: 'agents-server',
+            content: buildCoderPromptTemplateContent([
+                '-   @@@',
+                "-   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.
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    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.
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    function getDefaultCoderPromptTemplateDefinition(template) {
+        const definition = getDefaultCoderPromptTemplateDefinitionOrUndefined(template);
+        if (!definition) {
+            throw new NotFoundError(`Built-in coder prompt template \`${template}\` was not found.`);
+        }
+        return definition;
+    }
+    /**
+     * Ensures the default project-owned coder template files exist without overwriting user customizations.
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    async function ensureDefaultCoderPromptTemplateFiles(projectPath) {
+        const ensuredTemplateFiles = [];
+        for (const definition of DEFAULT_CODER_PROJECT_PROMPT_TEMPLATE_DEFINITIONS) {
+            const absoluteTemplatePath = path.join(projectPath, definition.relativeFilePath);
+            if (await isExistingFile$1(absoluteTemplatePath)) {
+                ensuredTemplateFiles.push({
+                    id: definition.id,
+                    relativeFilePath: definition.relativeFilePath,
+                    status: 'unchanged',
+                });
+                continue;
+            }
+            await promises.writeFile(absoluteTemplatePath, `${definition.content}\n`, 'utf-8');
+            ensuredTemplateFiles.push({
+                id: definition.id,
+                relativeFilePath: definition.relativeFilePath,
+                status: 'created',
+            });
+        }
+        return ensuredTemplateFiles;
+    }
+    /**
+     * Resolves the template requested by `coder generate-boilerplates`.
+     *
+     * Supports three modes:
+     * - omitted option => built-in `common`
+     * - built-in alias => one of the shared default templates
+     * - relative path => markdown template file resolved from the project root
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    async function resolveCoderPromptTemplate({ projectPath, templateOption, }) {
+        const normalizedTemplateOption = normalizeCoderPromptTemplateOption(templateOption);
+        if (!normalizedTemplateOption) {
+            return createResolvedBuiltInCoderPromptTemplate('common');
+        }
+        const builtInTemplateDefinition = getDefaultCoderPromptTemplateDefinitionOrUndefined(normalizedTemplateOption);
+        if (builtInTemplateDefinition) {
+            return createResolvedBuiltInCoderPromptTemplate(builtInTemplateDefinition.id);
+        }
+        const absoluteTemplatePath = path.join(projectPath, normalizedTemplateOption);
+        try {
+            const content = (await promises.readFile(absoluteTemplatePath, 'utf-8')).trim();
+            return {
+                identifier: normalizedTemplateOption,
+                relativeFilePath: normalizedTemplateOption,
+                content,
+                slugPrefix: deriveCoderPromptSlugPrefix(normalizedTemplateOption),
+            };
+        }
+        catch (error) {
+            if (isNodeJsErrorWithCode(error, 'ENOENT')) {
+                throw new NotFoundError(_spaceTrim.spaceTrim(`
+                    Prompt boilerplate template was not found at \`${normalizedTemplateOption}\`.
+
+                    -   The \`--template\` option resolves paths relative to the current project root: \`${projectPath}\`
+                    -   Run \`ptbk coder init\` to create the default project templates in \`${PROMPTS_TEMPLATES_DIRECTORY_PATH}\`
+                    -   Or omit \`--template\` / use the built-in aliases \`common\` or \`agents-server\`
+                `));
+            }
+            throw error;
+        }
+    }
+    /**
+     * Normalizes one raw `--template` option to either a trimmed string or `undefined`.
+     */
+    function normalizeCoderPromptTemplateOption(templateOption) {
+        const normalizedTemplateOption = templateOption === null || templateOption === void 0 ? void 0 : templateOption.trim();
+        if (!normalizedTemplateOption) {
+            return undefined;
+        }
+        return normalizedTemplateOption;
+    }
+    /**
+     * Resolves one built-in template definition without throwing.
+     */
+    function getDefaultCoderPromptTemplateDefinitionOrUndefined(template) {
+        return DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS.find((definition) => definition.id === template);
+    }
+    /**
+     * Builds stable markdown content for one coder prompt template without indentation drift.
+     */
+    function buildCoderPromptTemplateContent(lines) {
+        return lines.join('\n');
+    }
+    /**
+     * Creates a fully resolved template payload from one built-in definition.
+     */
+    function createResolvedBuiltInCoderPromptTemplate(template) {
+        const definition = getDefaultCoderPromptTemplateDefinition(template);
+        return {
+            identifier: definition.id,
+            relativeFilePath: definition.relativeFilePath,
+            content: definition.content,
+            slugPrefix: definition.slugPrefix,
+        };
+    }
+    /**
+     * Derives the filename slug prefix from a project-relative template path.
+     */
+    function deriveCoderPromptSlugPrefix(relativeTemplatePath) {
+        const templateBasename = path.basename(relativeTemplatePath)
+            .replace(/\.[^.]+$/u, '')
+            .replace(/\.template$/u, '');
+        if (templateBasename === 'common') {
+            return null;
+        }
+        return templateBasename;
+    }
+    /**
+     * Checks whether the provided error object exposes a specific Node.js `code`.
+     */
+    function isNodeJsErrorWithCode(error, code) {
+        return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+    }
+    /**
+     * 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 boilerplate templates [boilerplateTemplates](src/cli/cli-commands/coder/boilerplateTemplates.ts) should never be published outside of `@promptbook/cli`
+    // Note: [💞] Ignore a discrepancy between file name and exported helper names
+
     /**
      * Initializes `coder generate-boilerplates` command for Promptbook CLI utilities
      *
@@ -1713,12 +2085,21 @@
             Generate prompt boilerplate files with unique emoji tags
         `));
         command.option('--count <count>', `Number of prompt boilerplate files to generate`, '5');
-        command.option('--template <template>', `Prompt template to use: common | agents-server`, 'common');
+        command.option('--template <template>', _spaceTrim.spaceTrim(`
+            Prompt template to use.
+
+            Accepts either a built-in alias (${getDefaultCoderPromptTemplateDefinitions()
+        .map(({ id }) => id)
+        .join(', ')}) or a markdown file path relative to the current project root.
+        `));
         command.action(handleActionErrors(async (cliOptions) => {
             const { count: countOption, template: templateOption } = cliOptions;
             const filesCount = parseFilesCount(countOption);
-            const template = parsePromptTemplate(templateOption);
-            await generatePromptBoilerplate({ filesCount, template });
+            await generatePromptBoilerplate({
+                projectPath: process.cwd(),
+                filesCount,
+                templateOption,
+            });
             return process.exit(0);
         }));
     }
@@ -1727,14 +2108,15 @@
      *
      * @private internal function of `generatePromptBoilerplate` command
      */
-    async function generatePromptBoilerplate({ filesCount, template, }) {
+    async function generatePromptBoilerplate({ projectPath, filesCount, templateOption, }) {
         // Note: Import these dynamically to avoid circular dependencies and keep CLI fast
         const { buildPromptFilename, getPromptNumbering } = await Promise.resolve().then(function () { return getPromptNumbering$1; });
         const { formatPromptEmojiTag, getFreshPromptEmojiTags } = await Promise.resolve().then(function () { return promptEmojiTags; });
         console.info(`🚀  Generate prompt boilerplate files`);
-        const promptTemplateContent = loadPromptTemplate(template);
+        fs.mkdirSync(path.join(projectPath, PROMPTS_DIRECTORY_PATH), { recursive: true });
+        const promptTemplate = await resolveCoderPromptTemplate({ projectPath, templateOption });
         const promptNumbering = await getPromptNumbering({
-            promptsDir: path.join(process.cwd(), 'prompts'),
+            promptsDir: path.join(projectPath, PROMPTS_DIRECTORY_PATH),
             step: 10,
             ignoreGlobs: ['**/node_modules/**'],
         });
@@ -1743,7 +2125,7 @@
         console.info(colors__default["default"].blue(`Highest existing number for ${promptNumbering.datePrefix} found: ${highestNumberFormatted}`));
         const { availableCount, selectedEmojis } = await getFreshPromptEmojiTags({
             count: filesCount,
-            rootDir: process.cwd(),
+            rootDir: projectPath,
         });
         console.info(colors__default["default"].green(`Found ${availableCount} available fresh emojis`));
         console.info(colors__default["default"].green(`Selected emojis: ${selectedEmojis.map((emoji) => formatPromptEmojiTag(emoji)).join(' ')}`));
@@ -1755,8 +2137,9 @@
             const number = promptNumbering.startNumber + i * promptNumbering.step;
             const title = titles[i % titles.length];
             const emoji = selectedEmojis[i];
-            const filename = buildPromptFilename(promptNumbering.datePrefix, number, buildPromptSlug$1(template, title));
-            const filepath = path.join('prompts', filename);
+            const filename = buildPromptFilename(promptNumbering.datePrefix, number, buildPromptSlug$1(promptTemplate.slugPrefix, title));
+            const filepath = path.join(PROMPTS_DIRECTORY_PATH, filename);
+            const absoluteFilepath = path.join(projectPath, filepath);
             const emojiTag = formatPromptEmojiTag(emoji);
             const one = _spaceTrim.spaceTrim((block) => `
 
@@ -1764,7 +2147,7 @@
 
                 ${emojiTag} ${title}
 
-                ${block(promptTemplateContent)}
+                ${block(promptTemplate.content)}
             `);
             const content = _spaceTrim.spaceTrim((block) => `
 
@@ -1785,6 +2168,7 @@
             `);
             filesToCreate.push({
                 filepath,
+                absoluteFilepath,
                 filename,
                 content,
                 emoji,
@@ -1794,7 +2178,7 @@
         // Create the files
         console.info(colors__default["default"].yellow(`Creating ${filesToCreate.length} files:`));
         for (const file of filesToCreate) {
-            fs.writeFileSync(file.filepath, file.content, 'utf-8');
+            fs.writeFileSync(file.absoluteFilepath, file.content, 'utf-8');
             console.info(colors__default["default"].green(`✓ Created: ${file.filename} with ${formatPromptEmojiTag(file.emoji)}`));
         }
         console.info(colors__default["default"].bgGreen(` Successfully created ${filesToCreate.length} prompt boilerplate files! `));
@@ -1813,51 +2197,184 @@
         return Math.floor(filesCount);
     }
     /**
-     * Parses and validates the prompt template name.
+     * Builds filename slug from template and placeholder title.
      *
      * @private internal utility of `generatePromptBoilerplate` command
      */
-    function parsePromptTemplate(templateOption) {
-        if (templateOption === 'common' ||
-            templateOption === 'agents-server'
-        // <- TODO: Unhardcode and allow this dynamically by the template files.
-        ) {
-            return templateOption;
+    function buildPromptSlug$1(templateSlugPrefix, title) {
+        if (!templateSlugPrefix) {
+            return title;
         }
-        console.info(colors__default["default"].yellow(`Invalid --template '${templateOption}'. Falling back to default 'common'.`));
-        return 'common';
+        return `${templateSlugPrefix}-${title}`;
     }
+    // Note: [🟡] Code for CLI command [generate-boilerplates](src/cli/cli-commands/coder/generate-boilerplates.ts) should never be published outside of `@promptbook/cli`
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+
     /**
-     * Loads prompt template markdown content from the local templates folder.
+     * Relative path to the shared coder context file initialized in project roots.
      *
-     * @private internal utility of `generatePromptBoilerplate` command
+     * @private internal utility of `ptbk coder`
      */
-    function loadPromptTemplate(template) {
-        const templateFilePath = path.join(__dirname, '../../../../scripts/generate-prompt-boilerplate/templates', `${template}.template.md`);
-        return fs.readFileSync(templateFilePath, 'utf-8').trim();
+    const AGENTS_FILE_PATH = 'AGENTS.md';
+    /**
+     * Stable boilerplate instructions written into newly initialized `AGENTS.md` files.
+     */
+    const DEFAULT_CODER_AGENTS_FILE_LINES = [
+        '<!-- TODO: Write instructions for the Promptbook AI Coder here -->',
+    ];
+    /**
+     * Shared markdown boilerplate written into new `AGENTS.md` files.
+     */
+    const DEFAULT_CODER_AGENTS_FILE_CONTENT = DEFAULT_CODER_AGENTS_FILE_LINES.join('\n');
+    /**
+     * Returns the default coder `AGENTS.md` boilerplate instructions.
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    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
+
     /**
-     * Builds filename slug from template and placeholder title.
+     * Normalizes one project-relative path for human-readable CLI output and markdown.
      *
-     * @private internal utility of `generatePromptBoilerplate` command
+     * @private internal utility of `ptbk coder`
      */
-    function buildPromptSlug$1(template, title) {
-        if (template === 'common') {
-            return title;
+    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`
+
+    /**
+     * Relative path to the Promptbook Coder quick-reference file initialized in project roots.
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    const AGENT_CODING_FILE_PATH = 'AGENT_CODING.md';
+    /**
+     * Returns the default coder `AGENT_CODING.md` quick-reference content.
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    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');
+    }
+    /**
+     * Builds the sentence describing the starter templates created during initialization.
+     */
+    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 `${template}-${title}`;
+        return `The starter project templates created by \`ptbk coder init\` are ${formatInlineCodeList(starterTemplatePaths)}.`;
     }
-    // Note: [🟡] Code for CLI command [generate-boilerplates](src/cli/cli-commands/coder/generate-boilerplates.ts) should never be published outside of `@promptbook/cli`
-    // Note: [💞] Ignore a discrepancy between file name and entity name
+    /**
+     * Builds the markdown table rows describing the initialized npm scripts.
+     */
+    function buildPackageJsonScriptTableLines(packageJsonScripts) {
+        return Object.entries(packageJsonScripts).map(([scriptName, scriptCommand]) => `| \`npm run ${scriptName}\` | ${describeDefaultCoderPackageJsonScript(scriptName, scriptCommand)} |`);
+    }
+    /**
+     * Describes one initialized npm script in human-readable terms.
+     */
+    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}\`.`;
+    }
+    /**
+     * Formats one inline code list for human-readable markdown.
+     */
+    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
 
     /**
-     * Relative path to the root prompts directory used by Promptbook coder utilities.
+     * Appends one text block to existing file content while preserving readable newlines.
+     *
+     * @private function of `initializeCoderProjectConfiguration`
      */
-    const PROMPTS_DIRECTORY_PATH = 'prompts';
+    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`
+
     /**
-     * Relative path to the archive directory used by `coder verify`.
+     * Reads one text file when it exists, otherwise returns `undefined`.
+     *
+     * @private function of `initializeCoderProjectConfiguration`
      */
-    const PROMPTS_DONE_DIRECTORY_PATH = path.join(PROMPTS_DIRECTORY_PATH, 'done');
+    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`
+
+    /**
+     * Relative path to `.env` in the initialized project.
+     */
+    const ENV_FILE_PATH = '.env';
+    /**
+     * Fallback `.env` content used when no required variables need to be appended.
+     */
+    const EMPTY_CODER_ENV_FILE_CONTENT = '# Environment variables for Promptbook coder\n';
     /**
      * Required environment variables for coding-agent git identity.
      */
@@ -1875,6 +2392,476 @@
             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_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 (!isEnvFileExisting) {
+                await promises.writeFile(envFilePath, EMPTY_CODER_ENV_FILE_CONTENT, 'utf-8');
+                return {
+                    envFileStatus: 'created',
+                    initializedEnvVariableNames: [],
+                };
+            }
+            return {
+                envFileStatus: 'unchanged',
+                initializedEnvVariableNames: [],
+            };
+        }
+        const envBlockToAppend = buildMissingEnvVariablesBlock(missingEnvVariables);
+        const nextEnvContent = appendBlock(currentEnvContent, envBlockToAppend);
+        await promises.writeFile(envFilePath, nextEnvContent, 'utf-8');
+        return {
+            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);
+        const currentGitignoreContent = await readTextFileIfExists(gitignorePath);
+        if (currentGitignoreContent !== undefined && hasTmpGitignoreRule(currentGitignoreContent)) {
+            return 'unchanged';
+        }
+        const nextGitignoreContent = appendBlock(currentGitignoreContent || '', CODER_GITIGNORE_BLOCK);
+        await promises.writeFile(gitignorePath, nextGitignoreContent, 'utf-8');
+        return currentGitignoreContent === undefined ? 'created' : 'updated';
+    }
+    /**
+     * Detects whether `.gitignore` already covers the standalone coder temp directory.
+     */
+    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(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(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 nextJsonObject = { ...jsonObject };
+        nextJsonObject[fieldPath] = mergedEntries;
+        await promises.writeFile(absoluteFilePath, serializeJsonObject(nextJsonObject, formatting), 'utf-8');
+        return fileContent === undefined ? 'created' : 'updated';
+    }
+    /**
+     * 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.
+
+                ${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.
+     */
+    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.
+                `));
+            }
+            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);
+    }
+    // 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.'));
+        printInitializationStatusLine('prompts/', summary.promptsDirectoryStatus);
+        printInitializationStatusLine('prompts/done/', summary.promptsDoneDirectoryStatus);
+        printInitializationStatusLine('prompts/templates/', summary.promptsTemplatesDirectoryStatus);
+        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);
+        printInitializationStatusLine('.vscode/settings.json', summary.vscodeSettingsFileStatus);
+        if (summary.initializedEnvVariableNames.length > 0) {
+            printInitializationNote(`Added env variables: ${summary.initializedEnvVariableNames.join(', ')}`, colors__default["default"].cyan);
+        }
+        else {
+            printInitializationNote('Required coder env variables are already present.', colors__default["default"].gray);
+        }
+    }
+    /**
+     * Formats one initialization status into a human-readable label.
+     */
+    function formatInitializationStatus(status) {
+        if (status === 'created') {
+            return 'created';
+        }
+        if (status === 'updated') {
+            return 'updated';
+        }
+        return 'unchanged';
+    }
+    /**
+     * Prints one checked initialization-status line.
+     */
+    function printInitializationStatusLine(relativePath, status) {
+        console.info(colors__default["default"].gray(`✔ ${relativePath}: ${formatInitializationStatus(status)}`));
+    }
+    /**
+     * Prints one checked initialization note.
+     */
+    function printInitializationNote(message, colorize) {
+        console.info(colorize(`✔ ${message}`));
+    }
+    // Note: [🟡] Code for coder init summary printing [printInitializationSummary](src/cli/cli-commands/coder/printInitializationSummary.ts) should never be published outside of `@promptbook/cli`
+
     /**
      * Initializes `coder init` command for Promptbook CLI utilities.
      *
@@ -1888,9 +2875,15 @@
         command.description(_spaceTrim.spaceTrim(`
             Initialize Promptbook coder configuration for current project
 
-            Creates:
+            Creates or updates:
             - prompts/
             - prompts/done/
+            ${listDefaultCoderProjectPromptTemplateDisplayPaths()}
+            - ${AGENTS_FILE_PATH}
+            - ${AGENT_CODING_FILE_PATH}
+            - .gitignore
+            - package.json
+            - .vscode/settings.json
 
             Ensures required coding-agent environment variables in .env:
             - CODING_AGENT_GIT_NAME
@@ -1903,146 +2896,12 @@
         }));
     }
     /**
-     * Creates or updates all coder configuration artifacts required in the current project.
-     */
-    async function initializeCoderProjectConfiguration(projectPath) {
-        const promptsDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DIRECTORY_PATH);
-        const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
-        const { envFileStatus, initializedEnvVariableNames } = await ensureCoderEnvFile(projectPath);
-        return {
-            promptsDirectoryStatus,
-            promptsDoneDirectoryStatus,
-            envFileStatus,
-            initializedEnvVariableNames,
-        };
-    }
-    /**
-     * Ensures a relative directory exists in the project root.
-     */
-    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';
-    }
-    /**
-     * Ensures `.env` exists and contains all required coder environment variables.
+     * Lists the project-owned template file paths created by `ptbk coder init`.
      */
-    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));
-        if (missingEnvVariables.length === 0) {
-            if (!envFileExistedBefore) {
-                await promises.writeFile(envFilePath, '# Environment variables for Promptbook coder\n', 'utf-8');
-                return {
-                    envFileStatus: 'created',
-                    initializedEnvVariableNames: [],
-                };
-            }
-            return {
-                envFileStatus: 'unchanged',
-                initializedEnvVariableNames: [],
-            };
-        }
-        const envBlockToAppend = buildMissingEnvVariablesBlock(missingEnvVariables);
-        const nextEnvContent = appendBlock(currentEnvContent, envBlockToAppend);
-        await promises.writeFile(envFilePath, nextEnvContent, 'utf-8');
-        return {
-            envFileStatus: envFileExistedBefore ? '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')}
-    `);
-    }
-    /**
-     * Appends one text block to existing file content while preserving readable newlines.
-     */
-    function appendBlock(currentContent, blockToAppend) {
-        if (currentContent.trim() === '') {
-            return `${blockToAppend}\n`;
-        }
-        const normalizedCurrentContent = currentContent.endsWith('\n') ? currentContent : `${currentContent}\n`;
-        return `${normalizedCurrentContent}\n${blockToAppend}\n`;
-    }
-    /**
-     * Prints a readable summary of what was initialized for the user.
-     */
-    function printInitializationSummary(summary) {
-        console.info(colors__default["default"].green('Promptbook coder configuration initialized.'));
-        console.info(colors__default["default"].gray(`- prompts/: ${formatInitializationStatus(summary.promptsDirectoryStatus)}`));
-        console.info(colors__default["default"].gray(`- prompts/done/: ${formatInitializationStatus(summary.promptsDoneDirectoryStatus)}`));
-        console.info(colors__default["default"].gray(`- .env: ${formatInitializationStatus(summary.envFileStatus)}`));
-        if (summary.initializedEnvVariableNames.length > 0) {
-            console.info(colors__default["default"].cyan(`- Added env variables: ${summary.initializedEnvVariableNames.join(', ')}`));
-        }
-        else {
-            console.info(colors__default["default"].gray('- Required coder env variables are already present.'));
-        }
-    }
-    /**
-     * Formats one initialization status into a human-readable label.
-     */
-    function formatInitializationStatus(status) {
-        if (status === 'created') {
-            return 'created';
-        }
-        if (status === 'updated') {
-            return 'updated';
-        }
-        return 'unchanged';
-    }
-    /**
-     * Checks whether a path exists and is a file.
-     */
-    async function isExistingFile(path) {
-        try {
-            return (await promises.stat(path)).isFile();
-        }
-        catch (_a) {
-            return false;
-        }
-    }
-    /**
-     * Checks whether a path exists and is a directory.
-     */
-    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
@@ -4046,33 +4905,6 @@
         }
     }
 
-    /**
-     * This error indicates that promptbook not found in the collection
-     *
-     * @public exported from `@promptbook/core`
-     */
-    class NotFoundError extends Error {
-        constructor(message) {
-            super(message);
-            this.name = 'NotFoundError';
-            Object.setPrototypeOf(this, NotFoundError.prototype);
-        }
-    }
-
-    /**
-     * 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`
-
     /**
      * Generates random token
      *
@@ -40303,91 +41135,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.
      *
@@ -40405,7 +41152,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)) {
@@ -40416,15 +41163,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) {
@@ -40449,9 +41202,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.
@@ -40466,14 +41219,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.
@@ -40507,6 +41263,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.
      *
@@ -40540,13 +41459,15 @@
      *
      * @private function of findRefactorCandidates
      */
-    async function findRefactorCandidatesInProject(rootDir) {
+    async function findRefactorCandidatesInProject(options) {
+        const { heuristics, rootDir } = options;
         const lineCountExemptPaths = await buildExemptPathSet(rootDir, LINE_COUNT_EXEMPT_GLOBS);
         const sourceFiles = await listSourceFiles(rootDir);
         const candidates = [];
         for (const filePath of sourceFiles) {
             const candidate = await analyzeSourceFileForRefactorCandidate({
                 filePath,
+                heuristics,
                 lineCountExemptPaths,
                 rootDir,
             });
@@ -40819,11 +41740,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
      */
@@ -40832,6 +41760,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) {
@@ -40843,6 +41776,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 {
@@ -40850,6 +41796,11 @@
             maxLines,
             entityCount,
             maxEntities,
+            functionCount,
+            maxFunctions,
+            functionComplexity,
+            maxFunctionComplexity,
+            mostComplexFunctionName,
         };
     }
     /**
@@ -40858,14 +41809,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;
     }
@@ -40959,13 +41919,19 @@
      *
      * @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'));
+        console.info(colors__default["default"].cyan('⚡🏭 Find refactor candidates'));
+        console.info(colors__default["default"].gray(`Using \`${level}\` scan level.`));
         const rootDir = 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,
+            rootDir,
+        });
         if (candidates.length === 0) {
             console.info(colors__default["default"].green('No refactor candidates found.'));
             return;
@@ -44051,11 +45017,11 @@
             ${block(options.prompt)}
 
             ${delimiter}
-            )" \
-                --yolo \
-                --no-ask-user \
-                --no-color \
-                --output-format json \
+            )" \\
+                --yolo \\
+                --no-ask-user \\
+                --no-color \\
+                --output-format json \\
                 --stream off${modelArgument}${thinkingLevelArgument}
         `);
     }