@promptbook/cli 0.112.0-35 → 0.112.0-38

package/esm/index.es.js

@@ -2,10 +2,10 @@ import colors from 'colors';
 import commander, { Option } from 'commander';
 import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import * as fs from 'fs';
-import { writeFileSync, readFileSync, existsSync } from 'fs';
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'fs';
 import * as path from 'path';
 import { join, basename, dirname, isAbsolute, relative, extname, resolve } from 'path';
-import { mkdir, readFile, writeFile, stat, access, constants, readdir, watch, unlink, rm, rename, rmdir } from 'fs/promises';
+import { readFile, writeFile, stat, mkdir, access, constants, readdir, watch, unlink, rm, rename, rmdir } from 'fs/promises';
 import { forTime, forEver } from 'waitasecond';
 import prompts from 'prompts';
 import * as dotenv from 'dotenv';
@@ -57,7 +57,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @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
@@ -1661,6 +1661,142 @@ function $initializeCoderFindFreshEmojiTagCommand(program) {
 // Note: [🟡] Code for CLI command [find-fresh-emoji-tags](src/cli/cli-commands/coder/find-fresh-emoji-tags.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Root folders that contain source-like files for scanning.
+ */
+const SOURCE_ROOTS = ['src', 'apps', 'scripts', 'examples', 'agents', 'other'];
+/**
+ * File extensions treated as source code.
+ */
+const SOURCE_FILE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+/**
+ * Glob patterns that should be ignored when scanning for source files.
+ */
+const SOURCE_FILE_IGNORE_GLOBS = [
+    '**/node_modules/**',
+    '**/packages/**',
+    '**/.*/**',
+    '**/.git/**',
+    '**/.idea/**',
+    '**/.vscode/**',
+    '**/.promptbook/**',
+    '**/.next/**',
+    '**/.tmp/**',
+    '**/tmp/**',
+    '**/coverage/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/out/**',
+    '**/prompts/**',
+    '**/changelog/**',
+];
+/**
+ * Glob patterns that are exempt from line-count checks.
+ */
+const LINE_COUNT_EXEMPT_GLOBS = ['other/cspell-dictionaries/**/*.txt'];
+/**
+ * File extensions eligible for structural AST analysis.
+ */
+const STRUCTURAL_ANALYSIS_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+/**
+ * Markers that identify generated files which should be skipped.
+ */
+const GENERATED_CODE_MARKERS = [
+    'WARNING: This code has been generated',
+    'This code has been generated so that any manual changes will be overwritten',
+];
+/**
+ * Name of the prompts directory.
+ */
+const PROMPTS_DIR_NAME = 'prompts';
+/**
+ * Step size used for prompt numbering.
+ */
+const PROMPT_NUMBER_STEP = 10;
+/**
+ * Prefix used for generated prompt slugs.
+ */
+const PROMPT_SLUG_PREFIX = 'refactor';
+/**
+ * Label used to mark the target file in generated prompts.
+ */
+const PROMPT_TARGET_LABEL = 'Target file';
+/**
+ * Maximum length for generated prompt slugs.
+ */
+const PROMPT_SLUG_MAX_LENGTH = 80;
+/**
+ * Note: [?] Code in this file should never be published in any package
+ */
+
+/**
+ * Supported aggressiveness levels for refactor-candidate scanning.
+ */
+const REFACTOR_CANDIDATE_LEVEL_VALUES = ['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
  *
@@ -1673,17 +1809,23 @@ function $initializeCoderFindRefactorCandidatesCommand(program) {
     command.description(spaceTrim$1(`
             Scan source files to identify refactoring candidates
 
-            Flags files that exceed:
-            - Line count limits (500 lines per file by extension)
-            - Entity count limits (max 4 entities per file)
+            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 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);
@@ -1697,6 +1839,236 @@ function $initializeCoderFindRefactorCandidatesCommand(program) {
 // 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 = 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 = 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: 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: 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 = join(projectPath, definition.relativeFilePath);
+        if (await isExistingFile$1(absoluteTemplatePath)) {
+            ensuredTemplateFiles.push({
+                id: definition.id,
+                relativeFilePath: definition.relativeFilePath,
+                status: 'unchanged',
+            });
+            continue;
+        }
+        await 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 = join(projectPath, normalizedTemplateOption);
+    try {
+        const content = (await readFile(absoluteTemplatePath, 'utf-8')).trim();
+        return {
+            identifier: normalizedTemplateOption,
+            relativeFilePath: normalizedTemplateOption,
+            content,
+            slugPrefix: deriveCoderPromptSlugPrefix(normalizedTemplateOption),
+        };
+    }
+    catch (error) {
+        if (isNodeJsErrorWithCode(error, 'ENOENT')) {
+            throw new NotFoundError(spaceTrim$1(`
+                    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 = 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 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
  *
@@ -1710,12 +2082,21 @@ function $initializeCoderGenerateBoilerplatesCommand(program) {
             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$1(`
+            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);
     }));
 }
@@ -1724,14 +2105,15 @@ function $initializeCoderGenerateBoilerplatesCommand(program) {
  *
  * @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);
+    mkdirSync(join(projectPath, PROMPTS_DIRECTORY_PATH), { recursive: true });
+    const promptTemplate = await resolveCoderPromptTemplate({ projectPath, templateOption });
     const promptNumbering = await getPromptNumbering({
-        promptsDir: join(process.cwd(), 'prompts'),
+        promptsDir: join(projectPath, PROMPTS_DIRECTORY_PATH),
         step: 10,
         ignoreGlobs: ['**/node_modules/**'],
     });
@@ -1740,7 +2122,7 @@ async function generatePromptBoilerplate({ filesCount, template, }) {
     console.info(colors.blue(`Highest existing number for ${promptNumbering.datePrefix} found: ${highestNumberFormatted}`));
     const { availableCount, selectedEmojis } = await getFreshPromptEmojiTags({
         count: filesCount,
-        rootDir: process.cwd(),
+        rootDir: projectPath,
     });
     console.info(colors.green(`Found ${availableCount} available fresh emojis`));
     console.info(colors.green(`Selected emojis: ${selectedEmojis.map((emoji) => formatPromptEmojiTag(emoji)).join(' ')}`));
@@ -1752,8 +2134,9 @@ async function generatePromptBoilerplate({ filesCount, template, }) {
         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 = join('prompts', filename);
+        const filename = buildPromptFilename(promptNumbering.datePrefix, number, buildPromptSlug$1(promptTemplate.slugPrefix, title));
+        const filepath = join(PROMPTS_DIRECTORY_PATH, filename);
+        const absoluteFilepath = join(projectPath, filepath);
         const emojiTag = formatPromptEmojiTag(emoji);
         const one = spaceTrim$1((block) => `
 
@@ -1761,7 +2144,7 @@ async function generatePromptBoilerplate({ filesCount, template, }) {
 
                 ${emojiTag} ${title}
 
-                ${block(promptTemplateContent)}
+                ${block(promptTemplate.content)}
             `);
         const content = spaceTrim$1((block) => `
 
@@ -1782,6 +2165,7 @@ async function generatePromptBoilerplate({ filesCount, template, }) {
             `);
         filesToCreate.push({
             filepath,
+            absoluteFilepath,
             filename,
             content,
             emoji,
@@ -1791,7 +2175,7 @@ async function generatePromptBoilerplate({ filesCount, template, }) {
     // Create the files
     console.info(colors.yellow(`Creating ${filesToCreate.length} files:`));
     for (const file of filesToCreate) {
-        writeFileSync(file.filepath, file.content, 'utf-8');
+        writeFileSync(file.absoluteFilepath, file.content, 'utf-8');
         console.info(colors.green(`✓ Created: ${file.filename} with ${formatPromptEmojiTag(file.emoji)}`));
     }
     console.info(colors.bgGreen(` Successfully created ${filesToCreate.length} prompt boilerplate files! `));
@@ -1810,51 +2194,184 @@ function parseFilesCount(countOption) {
     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.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 = join(__dirname, '../../../../scripts/generate-prompt-boilerplate/templates', `${template}.template.md`);
-    return 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 = join(PROMPTS_DIRECTORY_PATH, 'done');
+async function readTextFileIfExists(path) {
+    try {
+        const fileStats = await stat(path);
+        if (!fileStats.isFile()) {
+            return undefined;
+        }
+    }
+    catch (_a) {
+        return undefined;
+    }
+    return readFile(path, 'utf-8');
+}
+// Note: [🟡] Code for coder init text-file reading [readTextFileIfExists](src/cli/cli-commands/coder/readTextFileIfExists.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * 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.
  */
@@ -1872,6 +2389,476 @@ const REQUIRED_CODER_ENV_VARIABLES = [
         value: '13406525ED912F938FEA85AB4046C687298B2382',
     },
 ];
+/**
+ * Ensures `.env` exists and contains all required coder environment variables.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+async function ensureCoderEnvFile(projectPath) {
+    const envFilePath = join(projectPath, ENV_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 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 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$1(`
+        # Promptbook coder identity (initialized by \`ptbk coder init\`)
+        ${variables.map(({ name, value }) => `${name}=${JSON.stringify(value)}`).join('\n')}
+    `);
+}
+// Note: [🟡] Code for coder init environment bootstrapping [ensureCoderEnvFile](src/cli/cli-commands/coder/ensureCoderEnvFile.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Relative path to `.gitignore` in the initialized project.
+ */
+const GITIGNORE_FILE_PATH = '.gitignore';
+/**
+ * `.gitignore` block required by standalone Promptbook coder projects.
+ */
+const CODER_GITIGNORE_BLOCK = spaceTrim$1(`
+    # Promptbook Coder
+    /.tmp
+`);
+/**
+ * Ensures `.gitignore` contains the standalone Promptbook coder cache entry.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+async function ensureCoderGitignoreFile(projectPath) {
+    const gitignorePath = join(projectPath, GITIGNORE_FILE_PATH);
+    const currentGitignoreContent = await readTextFileIfExists(gitignorePath);
+    if (currentGitignoreContent !== undefined && hasTmpGitignoreRule(currentGitignoreContent)) {
+        return 'unchanged';
+    }
+    const nextGitignoreContent = appendBlock(currentGitignoreContent || '', CODER_GITIGNORE_BLOCK);
+    await 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 = join(projectPath, relativeFilePath);
+    if (await isExistingFile(absoluteFilePath)) {
+        return 'unchanged';
+    }
+    await writeFile(absoluteFilePath, `${fileContent}\n`, 'utf-8');
+    return 'created';
+}
+/**
+ * Checks whether a path exists and is a file.
+ */
+async function isExistingFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch (_a) {
+        return false;
+    }
+}
+// Note: [🟡] Code for coder init markdown bootstrapping [ensureCoderMarkdownFile](src/cli/cli-commands/coder/ensureCoderMarkdownFile.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Default npm scripts initialized by `ptbk coder init`.
+ */
+const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
+    'coder:generate-boilerplates': 'npx ptbk coder generate-boilerplates',
+    'coder:run': 'npx ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --no-wait',
+    'coder:find-refactor-candidates': 'npx ptbk coder find-refactor-candidates',
+    'coder:verify': 'npx ptbk coder verify',
+};
+/**
+ * Lists the default npm scripts initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+function getDefaultCoderPackageJsonScripts() {
+    return DEFAULT_CODER_PACKAGE_JSON_SCRIPTS;
+}
+// Note: [🟡] Code for coder init package scripts [getDefaultCoderPackageJsonScripts](src/cli/cli-commands/coder/getDefaultCoderPackageJsonScripts.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
+ *
+ * @public exported from `@promptbook/core`
+ */
+class ParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ParseError';
+        Object.setPrototypeOf(this, ParseError.prototype);
+    }
+}
+// TODO: Maybe split `ParseError` and `ApplyError`
+
+/**
+ * Default indentation used when creating new JSON configuration files.
+ */
+const DEFAULT_JSON_FILE_INDENTATION = '    ';
+/**
+ * Default newline used when creating new JSON configuration files.
+ */
+const DEFAULT_JSON_FILE_NEWLINE = '\n';
+/**
+ * Ensures one JSON object field contains the provided string-record entries.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+async function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, }) {
+    if (ensureParentDirectoryPath) {
+        await mkdir(join(projectPath, ensureParentDirectoryPath), { recursive: true });
+    }
+    const absoluteFilePath = join(projectPath, relativeFilePath);
+    const fileContent = await readTextFileIfExists(absoluteFilePath);
+    const formatting = detectJsonFileFormatting(fileContent);
+    const jsonObject = fileContent === undefined ? {} : await parseJsonObjectFile(relativeFilePath, fileContent);
+    const existingEntries = getStringRecordOrDefault(jsonObject[fieldPath], relativeFilePath, fieldPath);
+    let hasChanges = fileContent === undefined;
+    const mergedEntries = { ...existingEntries };
+    for (const [entryKey, entryValue] of Object.entries(nextEntries)) {
+        if (mergedEntries[entryKey] !== entryValue) {
+            mergedEntries[entryKey] = entryValue;
+            hasChanges = true;
+        }
+    }
+    if (!hasChanges) {
+        return 'unchanged';
+    }
+    const nextJsonObject = { ...jsonObject };
+    nextJsonObject[fieldPath] = mergedEntries;
+    await 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$1(`
+                Cannot parse \`${relativeFilePath}\` as JSON.
+
+                ${typescript.flattenDiagnosticMessageText(parsedFile.error.messageText, '\n')}
+            `));
+    }
+    if (!isPlainObject(parsedFile.config)) {
+        throw new ParseError(spaceTrim$1(`
+                File \`${relativeFilePath}\` must contain one top-level JSON object.
+            `));
+    }
+    return parsedFile.config;
+}
+/**
+ * Reads one JSON object field as a string-to-string record.
+ */
+function getStringRecordOrDefault(value, relativeFilePath, fieldPath) {
+    if (value === undefined) {
+        return {};
+    }
+    if (!isPlainObject(value)) {
+        throw new ParseError(spaceTrim$1(`
+                File \`${relativeFilePath}\` contains invalid \`${fieldPath}\`.
+
+                Expected \`${fieldPath}\` to be an object with string values.
+            `));
+    }
+    const stringRecord = {};
+    for (const [key, itemValue] of Object.entries(value)) {
+        if (typeof itemValue !== 'string') {
+            throw new ParseError(spaceTrim$1(`
+                    File \`${relativeFilePath}\` contains invalid \`${fieldPath}.${key}\`.
+
+                    Expected \`${fieldPath}\` to be an object with string values.
+                `));
+        }
+        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 = join(projectPath, relativeDirectoryPath);
+    const isDirectoryExisting = await isExistingDirectory(directoryPath);
+    if (!isDirectoryExisting) {
+        await mkdir(directoryPath, { recursive: true });
+        return 'created';
+    }
+    return 'unchanged';
+}
+/**
+ * Checks whether a path exists and is a directory.
+ */
+async function isExistingDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch (_a) {
+        return false;
+    }
+}
+// Note: [🟡] Code for coder init directory creation [ensureDirectory](src/cli/cli-commands/coder/ensureDirectory.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Creates or updates all coder configuration artifacts required in the current project.
+ *
+ * @private internal utility of `coder init` command
+ */
+async function initializeCoderProjectConfiguration(projectPath) {
+    const promptsDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DIRECTORY_PATH);
+    const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
+    const promptsTemplatesDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH);
+    const promptTemplateFileStatuses = await ensureDefaultCoderPromptTemplateFiles(projectPath);
+    const agentsFileStatus = await ensureCoderMarkdownFile(projectPath, AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent());
+    const agentCodingFileStatus = await ensureCoderMarkdownFile(projectPath, AGENT_CODING_FILE_PATH, getDefaultCoderAgentCodingFileContent({
+        packageJsonScripts: getDefaultCoderPackageJsonScripts(),
+    }));
+    const { envFileStatus, initializedEnvVariableNames } = await ensureCoderEnvFile(projectPath);
+    const gitignoreFileStatus = await ensureCoderGitignoreFile(projectPath);
+    const packageJsonFileStatus = await ensureCoderPackageJsonFile(projectPath);
+    const vscodeSettingsFileStatus = await ensureCoderVscodeSettingsFile(projectPath);
+    return {
+        promptsDirectoryStatus,
+        promptsDoneDirectoryStatus,
+        promptsTemplatesDirectoryStatus,
+        promptTemplateFileStatuses,
+        agentsFileStatus,
+        agentCodingFileStatus,
+        envFileStatus,
+        gitignoreFileStatus,
+        packageJsonFileStatus,
+        vscodeSettingsFileStatus,
+        initializedEnvVariableNames,
+    };
+}
+// Note: [🟡] Code for coder init project bootstrapping [initializeCoderProjectConfiguration](src/cli/cli-commands/coder/initializeCoderProjectConfiguration.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Prints a readable summary of what was initialized for the user.
+ *
+ * @private function of `coder init` command
+ */
+function printInitializationSummary(summary) {
+    console.info(colors.green('Promptbook coder configuration initialized.'));
+    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.cyan);
+    }
+    else {
+        printInitializationNote('Required coder env variables are already present.', colors.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.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.
  *
@@ -1885,9 +2872,15 @@ function $initializeCoderInitCommand(program) {
     command.description(spaceTrim$1(`
             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
@@ -1900,146 +2893,12 @@ function $initializeCoderInitCommand(program) {
     }));
 }
 /**
- * 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 = join(projectPath, relativeDirectoryPath);
-    const existedBefore = await isExistingDirectory(directoryPath);
-    if (!existedBefore) {
-        await 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 = join(projectPath, '.env');
-    const envFileExistedBefore = await isExistingFile(envFilePath);
-    const currentEnvContent = envFileExistedBefore ? await readFile(envFilePath, 'utf-8') : '';
-    const existingEnvVariables = parseEnvVariableNames(currentEnvContent);
-    const missingEnvVariables = REQUIRED_CODER_ENV_VARIABLES.filter(({ name }) => !existingEnvVariables.has(name));
-    if (missingEnvVariables.length === 0) {
-        if (!envFileExistedBefore) {
-            await 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 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$1(`
-        # 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.green('Promptbook coder configuration initialized.'));
-    console.info(colors.gray(`- prompts/: ${formatInitializationStatus(summary.promptsDirectoryStatus)}`));
-    console.info(colors.gray(`- prompts/done/: ${formatInitializationStatus(summary.promptsDoneDirectoryStatus)}`));
-    console.info(colors.gray(`- .env: ${formatInitializationStatus(summary.envFileStatus)}`));
-    if (summary.initializedEnvVariableNames.length > 0) {
-        console.info(colors.cyan(`- Added env variables: ${summary.initializedEnvVariableNames.join(', ')}`));
-    }
-    else {
-        console.info(colors.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 stat(path)).isFile();
-    }
-    catch (_a) {
-        return false;
-    }
-}
-/**
- * Checks whether a path exists and is a directory.
- */
-async function isExistingDirectory(path) {
-    try {
-        return (await stat(path)).isDirectory();
-    }
-    catch (_a) {
-        return false;
-    }
+function listDefaultCoderProjectPromptTemplateDisplayPaths() {
+    return getDefaultCoderProjectPromptTemplateDefinitions()
+        .map(({ relativeFilePath }) => `- ${formatDisplayPath(relativeFilePath)}`)
+        .join('\n');
 }
 // Note: [🟡] Code for CLI command [init](src/cli/cli-commands/coder/init.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
@@ -4043,33 +4902,6 @@ class NotAllowed extends Error {
     }
 }
 
-/**
- * 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
  *
@@ -40300,91 +41132,6 @@ var findFreshEmojiTags = /*#__PURE__*/Object.freeze({
     findFreshEmojiTag: findFreshEmojiTag
 });
 
-/**
- * Root folders that contain source-like files for scanning.
- */
-const SOURCE_ROOTS = ['src', 'apps', 'scripts', 'examples', 'agents', 'other'];
-/**
- * File extensions treated as source code.
- */
-const SOURCE_FILE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
-/**
- * Glob patterns that should be ignored when scanning for source files.
- */
-const SOURCE_FILE_IGNORE_GLOBS = [
-    '**/node_modules/**',
-    '**/packages/**',
-    '**/.*/**',
-    '**/.git/**',
-    '**/.idea/**',
-    '**/.vscode/**',
-    '**/.promptbook/**',
-    '**/.next/**',
-    '**/.tmp/**',
-    '**/tmp/**',
-    '**/coverage/**',
-    '**/dist/**',
-    '**/build/**',
-    '**/out/**',
-    '**/prompts/**',
-    '**/changelog/**',
-];
-/**
- * Default maximum line count for source files.
- */
-const DEFAULT_MAX_LINE_COUNT = 2000;
-/**
- * Per-extension line count limits.
- */
-const LINE_COUNT_LIMITS_BY_EXTENSION = {
-    '.ts': 2000,
-    '.tsx': 2000,
-    '.js': 2000,
-    '.jsx': 2000,
-};
-/**
- * Glob patterns that are exempt from line-count checks.
- */
-const LINE_COUNT_EXEMPT_GLOBS = ['other/cspell-dictionaries/**/*.txt'];
-/**
- * Maximum number of entities before a file is flagged.
- */
-const MAX_ENTITIES_PER_FILE = 20;
-/**
- * File extensions eligible for entity counting.
- */
-const ENTITY_COUNT_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
-/**
- * Markers that identify generated files which should be skipped.
- */
-const GENERATED_CODE_MARKERS = [
-    'WARNING: This code has been generated',
-    'This code has been generated so that any manual changes will be overwritten',
-];
-/**
- * Name of the prompts directory.
- */
-const PROMPTS_DIR_NAME = 'prompts';
-/**
- * Step size used for prompt numbering.
- */
-const PROMPT_NUMBER_STEP = 10;
-/**
- * Prefix used for generated prompt slugs.
- */
-const PROMPT_SLUG_PREFIX = 'refactor';
-/**
- * Label used to mark the target file in generated prompts.
- */
-const PROMPT_TARGET_LABEL = 'Target file';
-/**
- * Maximum length for generated prompt slugs.
- */
-const PROMPT_SLUG_MAX_LENGTH = 80;
-/**
- * Note: [?] Code in this file should never be published in any package
- */
-
 /**
  * Normalizes a repo-relative path to use forward slashes.
  *
@@ -40402,7 +41149,7 @@ function normalizeRefactorCandidatePath(pathValue) {
  * @private function of findRefactorCandidates
  */
 async function analyzeSourceFileForRefactorCandidate(options) {
-    const { filePath, lineCountExemptPaths, rootDir } = options;
+    const { filePath, heuristics, lineCountExemptPaths, rootDir } = options;
     const normalizedAbsolutePath = normalizeAbsolutePath$1(filePath);
     const content = await readFile(filePath, 'utf-8');
     if (isGeneratedFile(content)) {
@@ -40413,15 +41160,21 @@ async function analyzeSourceFileForRefactorCandidate(options) {
     const reasons = [];
     if (!lineCountExemptPaths.has(normalizedAbsolutePath)) {
         const lineCount = countLines(content);
-        const maxLines = getMaxLinesForExtension(extension);
+        const maxLines = getMaxLinesForExtension(extension, heuristics);
         if (lineCount > maxLines) {
             reasons.push(`lines ${lineCount}/${maxLines}`);
         }
     }
-    if (ENTITY_COUNT_EXTENSIONS.includes(extension)) {
-        const entityCount = countEntities(content, extension, filePath);
-        if (entityCount > MAX_ENTITIES_PER_FILE) {
-            reasons.push(`entities ${entityCount}/${MAX_ENTITIES_PER_FILE}`);
+    if (STRUCTURAL_ANALYSIS_EXTENSIONS.includes(extension)) {
+        const structureSummary = summarizeSourceFileStructure(content, extension, filePath);
+        if (structureSummary.entityCount > heuristics.maxEntityCountPerFile) {
+            reasons.push(`entities ${structureSummary.entityCount}/${heuristics.maxEntityCountPerFile}`);
+        }
+        if (structureSummary.functionCount > heuristics.maxFunctionCountPerFile) {
+            reasons.push(`functions ${structureSummary.functionCount}/${heuristics.maxFunctionCountPerFile}`);
+        }
+        if (structureSummary.maxFunctionComplexity > heuristics.maxFunctionComplexity) {
+            reasons.push(buildComplexityReason(structureSummary, heuristics.maxFunctionComplexity));
         }
     }
     if (reasons.length === 0) {
@@ -40446,9 +41199,9 @@ function isGeneratedFile(content) {
  *
  * @private function of analyzeSourceFileForRefactorCandidate
  */
-function getMaxLinesForExtension(extension) {
+function getMaxLinesForExtension(extension, heuristics) {
     var _a;
-    return (_a = LINE_COUNT_LIMITS_BY_EXTENSION[extension]) !== null && _a !== void 0 ? _a : DEFAULT_MAX_LINE_COUNT;
+    return (_a = heuristics.maxLineCountByExtension[extension]) !== null && _a !== void 0 ? _a : heuristics.maxDefaultLineCount;
 }
 /**
  * Counts lines while ignoring a trailing newline.
@@ -40463,14 +41216,17 @@ function countLines(content) {
     return lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
 }
 /**
- * Counts top-level entities in a source file.
+ * Summarizes the structural metrics used to score one source file.
  *
  * @private function of analyzeSourceFileForRefactorCandidate
  */
-function countEntities(content, extension, filePath) {
+function summarizeSourceFileStructure(content, extension, filePath) {
     const scriptKind = getScriptKindForExtension(extension);
-    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, false, scriptKind);
-    return countEntitiesInSourceFile(sourceFile);
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, scriptKind);
+    return {
+        entityCount: countEntitiesInSourceFile(sourceFile),
+        ...summarizeFunctionsInSourceFile(sourceFile),
+    };
 }
 /**
  * Counts top-level entities in a parsed TypeScript source file.
@@ -40504,6 +41260,169 @@ function countEntitiesInSourceFile(sourceFile) {
     }
     return count;
 }
+/**
+ * Summarizes named functions and methods in a parsed source file.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function summarizeFunctionsInSourceFile(sourceFile) {
+    let functionCount = 0;
+    let maxFunctionComplexity = 0;
+    let mostComplexFunctionName = null;
+    const visitNode = (node) => {
+        if (isCountedFunctionLikeDeclaration(node)) {
+            functionCount += 1;
+            const functionComplexity = calculateFunctionComplexity(node);
+            if (functionComplexity > maxFunctionComplexity) {
+                maxFunctionComplexity = functionComplexity;
+                mostComplexFunctionName = getFunctionDisplayName(node);
+            }
+        }
+        ts.forEachChild(node, visitNode);
+    };
+    visitNode(sourceFile);
+    return {
+        functionCount,
+        maxFunctionComplexity,
+        mostComplexFunctionName,
+    };
+}
+/**
+ * Determines whether a node counts as a named function or method for density checks.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function isCountedFunctionLikeDeclaration(node) {
+    if (ts.isFunctionDeclaration(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isConstructorDeclaration(node) ||
+        ts.isGetAccessorDeclaration(node) ||
+        ts.isSetAccessorDeclaration(node)) {
+        return true;
+    }
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+        return isNamedFunctionExpression(node);
+    }
+    return false;
+}
+/**
+ * Determines whether a function expression is attached to a named variable or property.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function isNamedFunctionExpression(node) {
+    const parent = node.parent;
+    return (ts.isVariableDeclaration(parent) || ts.isPropertyDeclaration(parent) || ts.isPropertyAssignment(parent));
+}
+/**
+ * Calculates a lightweight cyclomatic-complexity score for one function.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function calculateFunctionComplexity(functionNode) {
+    if (!functionNode.body) {
+        return 1;
+    }
+    let complexity = 1;
+    const visitNode = (node) => {
+        if (node !== functionNode.body && isCountedFunctionLikeDeclaration(node)) {
+            return;
+        }
+        if (isComplexityDecisionNode(node)) {
+            complexity += 1;
+        }
+        ts.forEachChild(node, visitNode);
+    };
+    visitNode(functionNode.body);
+    return complexity;
+}
+/**
+ * Determines whether a node should increase the complexity score.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function isComplexityDecisionNode(node) {
+    if (ts.isIfStatement(node) ||
+        ts.isConditionalExpression(node) ||
+        ts.isCatchClause(node) ||
+        ts.isForStatement(node) ||
+        ts.isForInStatement(node) ||
+        ts.isForOfStatement(node) ||
+        ts.isWhileStatement(node) ||
+        ts.isDoStatement(node) ||
+        ts.isCaseClause(node)) {
+        return true;
+    }
+    if (ts.isBinaryExpression(node)) {
+        const operatorKind = node.operatorToken.kind;
+        return (operatorKind === ts.SyntaxKind.AmpersandAmpersandToken ||
+            operatorKind === ts.SyntaxKind.BarBarToken ||
+            operatorKind === ts.SyntaxKind.QuestionQuestionToken);
+    }
+    return false;
+}
+/**
+ * Resolves a readable display name for a counted function-like declaration.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function getFunctionDisplayName(functionNode) {
+    if (ts.isConstructorDeclaration(functionNode)) {
+        return 'constructor';
+    }
+    if (ts.isFunctionDeclaration(functionNode) ||
+        ts.isMethodDeclaration(functionNode) ||
+        ts.isGetAccessorDeclaration(functionNode) ||
+        ts.isSetAccessorDeclaration(functionNode)) {
+        if (!functionNode.name) {
+            return null;
+        }
+        return getPropertyNameText(functionNode.name);
+    }
+    if (ts.isArrowFunction(functionNode) || ts.isFunctionExpression(functionNode)) {
+        if (functionNode.name) {
+            return functionNode.name.text;
+        }
+        const parent = functionNode.parent;
+        if (ts.isVariableDeclaration(parent)) {
+            return getBindingNameText(parent.name);
+        }
+        if (ts.isPropertyDeclaration(parent) || ts.isPropertyAssignment(parent)) {
+            return getPropertyNameText(parent.name);
+        }
+    }
+    return null;
+}
+/**
+ * Resolves text for a binding name when it is a simple identifier.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function getBindingNameText(name) {
+    return ts.isIdentifier(name) ? name.text : null;
+}
+/**
+ * Resolves text for a property name while preserving computed names when necessary.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function getPropertyNameText(name) {
+    if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+        return name.text;
+    }
+    return name.getText();
+}
+/**
+ * Formats the reason emitted when a function in the file exceeds the complexity threshold.
+ *
+ * @private function of analyzeSourceFileForRefactorCandidate
+ */
+function buildComplexityReason(structureSummary, maxAllowedFunctionComplexity) {
+    const functionSuffix = structureSummary.mostComplexFunctionName
+        ? ` in \`${structureSummary.mostComplexFunctionName}\``
+        : '';
+    return `complexity ${structureSummary.maxFunctionComplexity}/${maxAllowedFunctionComplexity}${functionSuffix}`;
+}
 /**
  * Resolves the script kind for a source file extension.
  *
@@ -40537,13 +41456,15 @@ function normalizeAbsolutePath$1(pathValue) {
  *
  * @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,
         });
@@ -40816,11 +41737,18 @@ function buildPromptGuidance(candidate) {
     if (counts.entityCount !== null && counts.maxEntities !== null) {
         guidance.push(`- The file defines too many responsibilities (${counts.entityCount} in single file)`, `    - Keep in mind the Single Responsibility Principle (SRP)`, `    - Consider breaking it down into smaller, focused modules or components.`);
     }
+    if (counts.functionCount !== null && counts.maxFunctions !== null) {
+        guidance.push(`- The file contains too many functions (${counts.functionCount}/${counts.maxFunctions})`, `    - Keep related responsibilities grouped behind small facades or focused modules.`, `    - Consider extracting private helpers or splitting independent concerns into dedicated files.`);
+    }
+    if (counts.functionComplexity !== null && counts.maxFunctionComplexity !== null) {
+        const functionSuffix = counts.mostComplexFunctionName ? ` in \`${counts.mostComplexFunctionName}\`` : '';
+        guidance.push(`- The file contains overly complex logic${functionSuffix} (${counts.functionComplexity}/${counts.maxFunctionComplexity})`, `    - Break branching logic into smaller, focused helper functions.`, `    - Keep each function responsible for one clear step or decision.`);
+    }
     guidance.push('- Purpose of this refactoring is to improve code maintainability and readability.', '- Look at the internal structure, the usage and also surrounding code to understand how to best refactor this file.', '- Consider breaking down large functions into smaller, more manageable ones, removing any redundant code, and ensuring that the file adheres to the project coding standards.', '- After the refactoring, ensure that (1) `npm run test-name-discrepancies` and (2) `npm run test-package-generation` are passing successfully.', '    1. All the things you have moved to new files should correspond the thing in the file with the file name, for example `MyComponent.tsx` should export `MyComponent`.', '    2. All the things you have moved to new files but are private things to the outside world should have `@private function of TheMainThing` JSDoc comment.', '- Keep in mind DRY *(Do not repeat yourself)* and SOLID principles while refactoring.', '- **Do not change the external behavior** of the code. Focus solely on improving the internal structure and organization of the code.', '- Before you start refactoring, make sure to read the code carefully and understand its current structure and functionality. Do a analysis of the current functionality before you start.');
     return guidance;
 }
 /**
- * Extracts line and entity counts from refactor reasons.
+ * Extracts structural counts from refactor reasons.
  *
  * @private function of buildPromptContent
  */
@@ -40829,6 +41757,11 @@ function extractReasonCounts(reasons) {
     let maxLines = null;
     let entityCount = null;
     let maxEntities = null;
+    let functionCount = null;
+    let maxFunctions = null;
+    let functionComplexity = null;
+    let maxFunctionComplexity = null;
+    let mostComplexFunctionName = null;
     for (const reason of reasons) {
         const lineMatch = reason.match(/lines\s+(?<count>\d+)\/(?<max>\d+)/i);
         if (lineMatch === null || lineMatch === void 0 ? void 0 : lineMatch.groups) {
@@ -40840,6 +41773,19 @@ function extractReasonCounts(reasons) {
         if (entityMatch === null || entityMatch === void 0 ? void 0 : entityMatch.groups) {
             entityCount = Number(entityMatch.groups.count);
             maxEntities = Number(entityMatch.groups.max);
+            continue;
+        }
+        const functionMatch = reason.match(/functions\s+(?<count>\d+)\/(?<max>\d+)/i);
+        if (functionMatch === null || functionMatch === void 0 ? void 0 : functionMatch.groups) {
+            functionCount = Number(functionMatch.groups.count);
+            maxFunctions = Number(functionMatch.groups.max);
+            continue;
+        }
+        const complexityMatch = reason.match(/complexity\s+(?<count>\d+)\/(?<max>\d+)(?:\s+in\s+`(?<functionName>[^`]+)`)?/i);
+        if (complexityMatch === null || complexityMatch === void 0 ? void 0 : complexityMatch.groups) {
+            functionComplexity = Number(complexityMatch.groups.count);
+            maxFunctionComplexity = Number(complexityMatch.groups.max);
+            mostComplexFunctionName = complexityMatch.groups.functionName || null;
         }
     }
     return {
@@ -40847,6 +41793,11 @@ function extractReasonCounts(reasons) {
         maxLines,
         entityCount,
         maxEntities,
+        functionCount,
+        maxFunctions,
+        functionComplexity,
+        maxFunctionComplexity,
+        mostComplexFunctionName,
     };
 }
 /**
@@ -40855,14 +41806,23 @@ function extractReasonCounts(reasons) {
  * @private function of buildPromptContent
  */
 function buildDensityNote(counts) {
-    if (counts.lineCount !== null && counts.entityCount !== null) {
-        return 'The file mixes multiple concerns, making it harder to follow.';
+    const activeSignalsCount = [
+        counts.lineCount !== null,
+        counts.entityCount !== null,
+        counts.functionCount !== null,
+        counts.functionComplexity !== null,
+    ].filter(Boolean).length;
+    if (activeSignalsCount > 1) {
+        return 'The file mixes multiple concerns and dense logic, making it harder to follow.';
     }
     if (counts.lineCount !== null) {
         return 'The file is large enough that it is hard to follow.';
     }
-    if (counts.entityCount !== null) {
-        return 'The file is dense enough that it is hard to follow.';
+    if (counts.entityCount !== null || counts.functionCount !== null) {
+        return 'The file packs too many responsibilities into one place.';
+    }
+    if (counts.functionComplexity !== null) {
+        return 'The file contains logic that is too complex to follow comfortably.';
     }
     return null;
 }
@@ -40956,13 +41916,19 @@ function initializeFindRefactorCandidatesRun() {
  *
  * @public exported from `@promptbook/cli`
  */
-async function findRefactorCandidates() {
+async function findRefactorCandidates(options = {}) {
+    const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL } = options;
+    const heuristics = getRefactorCandidateLevelConfiguration(level);
     initializeFindRefactorCandidatesRun();
-    console.info(colors.cyan('?? Find refactor candidates'));
+    console.info(colors.cyan('⚡🏭 Find refactor candidates'));
+    console.info(colors.gray(`Using \`${level}\` scan level.`));
     const rootDir = process.cwd();
     const promptsDir = 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.green('No refactor candidates found.'));
         return;
@@ -44048,11 +45014,11 @@ function buildGitHubCopilotScript(options) {
             ${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}
         `);
 }