@promptbook/cli 0.114.0-32 → 0.114.0-34

package/esm/index.es.js

@@ -1,7 +1,7 @@
 import colors from 'colors';
 import commander, { Option } from 'commander';
 import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
-import { writeFile, stat, mkdir, readFile, readdir, rm, cp, lstat, symlink, rename, unlink, appendFile, realpath, copyFile, access, constants, watch, rmdir } from 'fs/promises';
+import { writeFile, stat, readdir, mkdir, readFile, rm, cp, lstat, symlink, rename, unlink, appendFile, realpath, copyFile, statfs, access, constants, watch, rmdir } from 'fs/promises';
 import { join, delimiter, relative, basename, resolve, dirname, isAbsolute, extname } from 'path';
 import { createHash, randomBytes } from 'crypto';
 import { spawn, spawnSync, execFile } from 'child_process';
@@ -48,7 +48,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-32';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-34';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1708,6 +1708,35 @@ function $initializeAboutCommand(program) {
 // TODO: [🗽] Unite branding and make single place for it
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Message printed when one CLI command which only groups subcommands is run without picking any of them.
+ *
+ * @private internal constant of `$requireCliSubcommand`
+ */
+const MISSING_CLI_SUBCOMMAND_MESSAGE = 'Please specify a subcommand.';
+/**
+ * Makes one CLI command which only groups subcommands ask for a subcommand instead of doing anything on its own.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers an action in the CLI
+ *
+ * @private utility of CLI
+ */
+function $requireCliSubcommand(command) {
+    command.action(() => $reportMissingCliSubcommand(command));
+}
+/**
+ * Asks for a subcommand of one CLI command, prints its help and exits the process.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it writes to the console and exits the process
+ *
+ * @private utility of CLI
+ */
+function $reportMissingCliSubcommand(command) {
+    console.info(colors.yellow(MISSING_CLI_SUBCOMMAND_MESSAGE));
+    console.info('');
+    return command.help();
+}
+
 // Note: [💞] Ignore a discrepancy between file name and entity name
 /**
  * All CLI harness names supported by `CliAgent` and `ptbk agent exec`.
@@ -1812,20 +1841,20 @@ const PROMPT_RUNNER_HARNESS_NAMES = CLI_AGENT_HARNESS_NAMES;
  */
 const PROMPT_RUNNER_DESCRIPTION = spaceTrim$1(`
     Runners:
-    - openai-codex: OpenAI Codex integration (requires --model)
+    - openai-codex: OpenAI Codex integration (requires --model when executing)
     - github-copilot: GitHub Copilot CLI integration
     - cline: Cline CLI integration
     - claude-code: Claude Code integration
     - opencode: Opencode integration
-    - gemini: Google Gemini CLI integration (requires --model)
-    - qwen-code: Qwen Code CLI integration (requires --model)
+    - gemini: Google Gemini CLI integration (requires --model when executing)
+    - qwen-code: Qwen Code CLI integration (requires --model when executing)
 `);
 /**
  * Commander description for the `--harness` option.
  *
  * @private internal utility of `promptbookCli`
  */
-const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION = `Select runner: ${PROMPT_RUNNER_HARNESS_NAMES.join(', ')} (required for non-dry-run)`;
+const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION = `Select runner: ${PROMPT_RUNNER_HARNESS_NAMES.join(', ')} (required when executing prompts)`;
 /**
  * Runner harness names listed as alternatives of the `--harness` option in error messages.
  *
@@ -1838,7 +1867,7 @@ const PROMPT_RUNNER_HARNESS_OPTION_HINT = `--harness <${PROMPT_RUNNER_HARNESS_NA
  * @private internal utility of `promptbookCli`
  */
 const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION = spaceTrim$1(`
-    Model to use (required for openai-codex, gemini and qwen-code)
+    Model to use or filter by (required when executing with openai-codex, gemini and qwen-code)
 
     OpenAI examples: gpt-5.2-codex, default
     Gemini examples: gemini-3-flash-preview, default
@@ -2103,11 +2132,7 @@ function $initializeAgentCommand(program) {
         `));
     $initializeAgentChatCommand(agentCommand);
     $initializeAgentExecCommand(agentCommand);
-    agentCommand.action(() => {
-        console.info(colors.yellow('Please specify a subcommand.'));
-        console.info('');
-        agentCommand.help();
-    });
+    $requireCliSubcommand(agentCommand);
 }
 // Note: [🟡] Code for CLI command [agent](src/cli/cli-commands/agent.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
@@ -2265,6 +2290,23 @@ async function ensureDirectory(projectPath, relativeDirectoryPath) {
     }
     return 'unchanged';
 }
+/**
+ * Checks whether a project-relative directory is missing or contains no entries.
+ *
+ * @private internal utility of `coder init` command
+ */
+async function isDirectoryEmpty(projectPath, relativeDirectoryPath) {
+    const directoryPath = join(projectPath, relativeDirectoryPath);
+    try {
+        return (await readdir(directoryPath)).length === 0;
+    }
+    catch (error) {
+        if (isNodeJsErrorWithCode$1(error, 'ENOENT')) {
+            return true;
+        }
+        throw error;
+    }
+}
 /**
  * Checks whether a path exists and is a directory.
  */
@@ -2276,6 +2318,12 @@ async function isExistingDirectory$2(path) {
         return false;
     }
 }
+/**
+ * Checks whether a caught value is a Node.js error with the given error code.
+ */
+function isNodeJsErrorWithCode$1(error, code) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+}
 // Note: [🟡] Code for coder init directory creation [ensureDirectory](src/cli/cli-commands/coder/ensureDirectory.ts) should never be published outside of `@promptbook/cli`
 
 /**
@@ -2563,11 +2611,7 @@ function $initializeAgentFolderCommand(program) {
     $initializeAgentTickCommand(agentFolderCommand);
     $initializeAgentRunCommand(agentFolderCommand);
     $initializeAgentRunMultipleCommand(agentFolderCommand);
-    agentFolderCommand.action(() => {
-        console.info(colors.yellow('Please specify a subcommand.'));
-        console.info('');
-        agentFolderCommand.help();
-    });
+    $requireCliSubcommand(agentFolderCommand);
 }
 // Note: [🟡] Code for CLI command [agent-folder](src/cli/cli-commands/agent-folder.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
@@ -21418,10 +21462,30 @@ function normalizeRelativePath$3(relativePath) {
     return relativePath.replace(/\\/gu, '/');
 }
 
+/**
+ * AuthenticationError is thrown from login function which is dependency of remote server
+ *
+ * @public exported from `@promptbook/core`
+ */
+class AuthenticationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthenticationError';
+        Object.setPrototypeOf(this, AuthenticationError.prototype);
+    }
+}
+
 /**
  * Formats one unknown error-like value into readable text for logs and feedback.
+ *
+ * An `AuthenticationError` is reported without its stack, because its message is written for the user - it
+ * says which harness has to be signed in again and how - and the frames of a failure nobody can debug would
+ * only push those instructions out of sight.
  */
 function formatUnknownErrorDetails(error) {
+    if (error instanceof AuthenticationError) {
+        return error.message;
+    }
     if (error instanceof Error) {
         return error.stack || error.message;
     }
@@ -24138,6 +24202,7 @@ const HARNESS_DEFINITIONS = {
         commandName: 'codex',
         npmPackageName: '@openai/codex',
         projectGitignoreRules: ['.codex'],
+        authenticationMethod: { command: 'codex login' },
         // Note: The official standalone installer keeps its package in `~/.codex` and links it onto the `PATH`
         standaloneInstallation: {
             directoryNames: ['.codex'],
@@ -24150,6 +24215,7 @@ const HARNESS_DEFINITIONS = {
         commandName: 'copilot',
         npmPackageName: '@github/copilot',
         projectGitignoreRules: ['.github/copilot/settings.local.json'],
+        authenticationMethod: { command: 'copilot', interactiveStep: 'running the `/login` command inside it' },
         // Note: The GitHub Copilot CLI downloads its native binary in a postinstall script
         npmInstallEnvironment: { npm_config_ignore_scripts: 'false' },
     },
@@ -24159,6 +24225,7 @@ const HARNESS_DEFINITIONS = {
         commandName: 'cline',
         npmPackageName: 'cline',
         projectGitignoreRules: ['.cline'],
+        authenticationMethod: { command: 'cline', interactiveStep: 'signing in to the provider inside it' },
     },
     'claude-code': {
         harnessName: 'claude-code',
@@ -24166,6 +24233,7 @@ const HARNESS_DEFINITIONS = {
         commandName: 'claude',
         npmPackageName: '@anthropic-ai/claude-code',
         projectGitignoreRules: ['.claude'],
+        authenticationMethod: { command: 'claude', interactiveStep: 'running the `/login` command inside it' },
     },
     opencode: {
         harnessName: 'opencode',
@@ -24173,6 +24241,7 @@ const HARNESS_DEFINITIONS = {
         commandName: 'opencode',
         npmPackageName: 'opencode-ai',
         projectGitignoreRules: ['.opencode'],
+        authenticationMethod: { command: 'opencode auth login' },
     },
     gemini: {
         harnessName: 'gemini',
@@ -24180,6 +24249,7 @@ const HARNESS_DEFINITIONS = {
         commandName: 'gemini',
         npmPackageName: '@google/gemini-cli',
         projectGitignoreRules: ['.gemini'],
+        authenticationMethod: { command: 'gemini', interactiveStep: 'running the `/auth` command inside it' },
     },
     'qwen-code': {
         harnessName: 'qwen-code',
@@ -24187,6 +24257,7 @@ const HARNESS_DEFINITIONS = {
         commandName: 'qwen',
         npmPackageName: '@qwen-code/qwen-code',
         projectGitignoreRules: ['.qwen'],
+        authenticationMethod: { command: 'qwen', interactiveStep: 'running the `/auth` command inside it' },
     },
 };
 /**
@@ -26220,6 +26291,183 @@ function formatClaudeCodeSessionIdForDisplay(sessionId) {
     return `${sessionId.slice(0, 8)}...`;
 }
 
+/**
+ * Formats one unknown error-like value into its readable message without the stack trace.
+ *
+ * Use this instead of `formatUnknownErrorDetails` whenever the text is shown to the user, for example
+ * inside a branded error, where the stack of the wrapped error would only bury the actual cause.
+ */
+function formatUnknownErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    const serializedError = JSON.stringify(error, null, 2);
+    return serializedError !== null && serializedError !== void 0 ? serializedError : String(error);
+}
+
+/**
+ * Builds the branded error which tells the user that the selected harness has to be signed in again.
+ */
+function buildHarnessAuthenticationError(options) {
+    const { harnessName, reason } = options;
+    const { label, authenticationMethod } = getHarnessDefinition(harnessName);
+    return new AuthenticationError(spaceTrim((block) => `
+                The **${label}** harness is not authenticated, so the prompt was not run.
+
+                ${label} reported:
+                > ${reason}
+
+                ${block(buildSignInInstruction(authenticationMethod))}
+
+                Once you are signed in, start the very same \`ptbk coder\` command again.
+            `));
+}
+/**
+ * Builds the sentence which tells the user how to sign in to one harness again.
+ */
+function buildSignInInstruction(authenticationMethod) {
+    const { command, interactiveStep } = authenticationMethod;
+    if (interactiveStep === undefined) {
+        return `Sign in again by running \`${command}\`.`;
+    }
+    return `Sign in again by running \`${command}\` and then ${interactiveStep}.`;
+}
+
+/**
+ * Maximum length of the harness reason quoted back to the user.
+ */
+const MAXIMUM_AUTHENTICATION_FAILURE_REASON_LENGTH = 300;
+/**
+ * Keys of machine-readable harness output whose string value carries the human-readable failure reason.
+ *
+ * Harnesses which stream JSON events - like Claude Code with its `stream-json` output - report the reason only
+ * inside such a value, surrounded by hundreds of characters of session metadata which must never be shown to
+ * the user. The keys are ordered from the most to the least conclusive one.
+ */
+const HARNESS_FAILURE_MESSAGE_KEYS = ['result', 'error_message', 'message', 'text'];
+/**
+ * Patterns which extract one JSON string value reported under a harness failure message key.
+ */
+const HARNESS_FAILURE_MESSAGE_PATTERNS = HARNESS_FAILURE_MESSAGE_KEYS.map((messageKey) => new RegExp(`"${messageKey}"\\s*:\\s*("(?:[^"\\\\]|\\\\.)*")`, 'g'));
+/**
+ * Signatures which mean that the harness refused to work because it is not logged in.
+ *
+ * They are deliberately narrow phrases instead of single words like `login`, because the output of a harness
+ * routinely mentions its own `/login` command among the commands it offers, and such a mention must never be
+ * read as a failed login.
+ */
+const AUTHENTICATION_FAILURE_PATTERNS = [
+    /\bauthentication[ _-]?failed\b/i,
+    /\bfailed to authenticate\b/i,
+    /\bnot authenticated\b/i,
+    /\bnot logged[ -]?in\b/i,
+    /\bnot signed[ -]?in\b/i,
+    /\bno authentication information found\b/i,
+    /\bauthentication (?:is )?required\b/i,
+    /\blogin (?:is )?required\b/i,
+    /\bplease (?:log|sign) in\b/i,
+    /\bunauthorized\b/i,
+    /\b(?:oauth|session|token|credentials?|login)\b[^.]{0,60}?\bexpired\b/i,
+    /\bexpired\b[^.]{0,60}?\b(?:oauth|session|token|credentials?|login)\b/i,
+    /\binvalid api[ _-]?key\b/i,
+    /\bmissing api[ _-]?key\b/i,
+    /\binvalid credentials?\b/i,
+];
+/**
+ * Reads the reason why a harness refused to work because it is not logged in, from its raw CLI output.
+ *
+ * Messages the harness reports in machine-readable output are preferred over its raw output lines, so the
+ * reason is the sentence the harness wrote for a human and not the JSON event which transported it.
+ *
+ * @returns One short single-line reason, or `undefined` when the failure was not caused by authentication.
+ */
+function extractHarnessAuthenticationFailureReason(harnessOutput) {
+    const reportedMessages = [...extractHarnessReportedMessages(harnessOutput), ...harnessOutput.split(/\r?\n/)];
+    for (const reportedMessage of reportedMessages) {
+        const reason = reportedMessage.replace(/\s+/g, ' ').trim();
+        if (isAuthenticationFailureReason(reason)) {
+            return limitAuthenticationFailureReason(reason);
+        }
+    }
+    return undefined;
+}
+/**
+ * Lists the human-readable messages a harness reported in its machine-readable output.
+ */
+function extractHarnessReportedMessages(harnessOutput) {
+    const reportedMessages = [];
+    for (const messagePattern of HARNESS_FAILURE_MESSAGE_PATTERNS) {
+        for (const match of harnessOutput.matchAll(messagePattern)) {
+            const reportedMessage = parseSerializedJsonString(match[1]);
+            if (reportedMessage !== undefined) {
+                reportedMessages.push(reportedMessage);
+            }
+        }
+    }
+    return reportedMessages;
+}
+/**
+ * Reads one JSON string literal back into plain text, tolerating output which only looks like JSON.
+ */
+function parseSerializedJsonString(serializedString) {
+    if (serializedString === undefined) {
+        return undefined;
+    }
+    try {
+        const parsedString = JSON.parse(serializedString);
+        return typeof parsedString === 'string' ? parsedString : undefined;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+/**
+ * Returns true when one message of the harness says that it is not logged in.
+ */
+function isAuthenticationFailureReason(reportedMessage) {
+    return AUTHENTICATION_FAILURE_PATTERNS.some((pattern) => pattern.test(reportedMessage));
+}
+/**
+ * Shortens a very long reason, so the guidance which follows it stays visible in the terminal.
+ */
+function limitAuthenticationFailureReason(reason) {
+    if (reason.length <= MAXIMUM_AUTHENTICATION_FAILURE_REASON_LENGTH) {
+        return reason;
+    }
+    return `${reason.slice(0, MAXIMUM_AUTHENTICATION_FAILURE_REASON_LENGTH)}...`;
+}
+
+/**
+ * Wraps one prompt runner so a failure caused by a missing or expired harness login is reported as a branded
+ * `AuthenticationError` which tells the user how to sign in again.
+ *
+ * Each harness reports its own failures differently, but all of them report them by failing `runPrompt` with
+ * the raw CLI output as the message. Translating the failure here therefore keeps exactly one place which has
+ * to recognize an unauthenticated harness, for every harness and for every command which runs prompts.
+ */
+function createAuthenticationAwarePromptRunner(runner, harnessName) {
+    var _a;
+    return {
+        name: runner.name,
+        runPrompt: async (options) => {
+            try {
+                return await runner.runPrompt(options);
+            }
+            catch (error) {
+                const reason = extractHarnessAuthenticationFailureReason(formatUnknownErrorMessage(error));
+                if (reason === undefined) {
+                    throw error;
+                }
+                throw buildHarnessAuthenticationError({ harnessName, reason });
+            }
+        },
+        getSubscriptionUsage: (_a = runner.getSubscriptionUsage) === null || _a === void 0 ? void 0 : _a.bind(runner),
+    };
+}
+
 /**
  * Creates a temporary script file, runs it, and cleans it up unless preservation is requested or the run fails.
  */
@@ -27959,6 +28207,18 @@ function resolvePromptRunner(options) {
     if (!agentName) {
         throw new Error('Missing --harness in non-dry run mode');
     }
+    const resolution = resolveHarnessPromptRunner(agentName, options);
+    return {
+        ...resolution,
+        // Note: Every harness is wrapped here, so a harness which is not logged in is reported the same clear
+        //       way no matter which harness it is and which command has resolved the runner
+        runner: createAuthenticationAwarePromptRunner(resolution.runner, agentName),
+    };
+}
+/**
+ * Creates the runner of one selected harness together with its status-line metadata.
+ */
+function resolveHarnessPromptRunner(agentName, options) {
     if (agentName === 'openai-codex') {
         return createOpenAiCodexRunnerResolution(options);
     }
@@ -28426,11 +28686,19 @@ const MIN_FRAME_WIDTH = 56;
  * Maximum width used for the rich coder-run frame.
  */
 const MAX_FRAME_WIDTH = 96;
+/**
+ * Number of terminal columns deliberately left unused by the rich coder-run frame.
+ *
+ * A row which fills the final physical terminal column can auto-wrap. The incremental terminal
+ * updater moves by logical rows, so an auto-wrapped row would put its cursor out of sync with the
+ * frame and let a later animated avatar redraw overwrite dashboard content.
+ */
+const TERMINAL_AUTO_WRAP_RESERVED_COLUMNS = 1;
 /**
  * Builds the complete boxed terminal frame for the rich `ptbk coder run` UI.
  */
 function buildCoderRunUiFrame(options) {
-    const totalWidth = Math.max(MIN_FRAME_WIDTH, Math.min(options.terminalWidth, MAX_FRAME_WIDTH));
+    const totalWidth = resolveCoderRunUiFrameWidth(options.terminalWidth);
     const isPromptActive = options.phase === 'running' || options.phase === 'verifying' || options.phase === 'loading';
     const promptStatusPrefix = isPromptActive ? `${colors.yellow(`${options.spinner} `)}` : '';
     const pausePresentation = buildPausePresentation(options.phase, options.pauseState, options.pauseTargetLabel, options.statusMessage);
@@ -28467,6 +28735,16 @@ function buildCoderRunUiFrame(options) {
     frame.push(...renderBox('Controls', controlsBoxLines, totalWidth, colors.white.bold));
     return frame;
 }
+/**
+ * Resolves the safe width of the rich terminal frame from the available physical terminal columns.
+ *
+ * The reserved trailing column keeps every boxed row from auto-wrapping, which makes the frame's
+ * logical row count match its physical terminal row count during animated incremental redraws.
+ */
+function resolveCoderRunUiFrameWidth(terminalWidth) {
+    const availableFrameWidth = terminalWidth - TERMINAL_AUTO_WRAP_RESERVED_COLUMNS;
+    return Math.max(MIN_FRAME_WIDTH, Math.min(availableFrameWidth, MAX_FRAME_WIDTH));
+}
 /**
  * Builds the header visual above the dashboard boxes.
  *
@@ -29943,16 +30221,14 @@ const SPINNER_FRAMES = [
  */
 const DEFAULT_TERMINAL_WIDTH = 80;
 /**
- * Maximum terminal width supported by the boxed runner UI.
- */
-const MAX_TERMINAL_WIDTH = 96;
-/**
- * Returns the usable terminal width, capped at 96.
+ * Returns the number of columns reported by the current terminal.
+ *
+ * The frame builder owns clamping and reserves its trailing auto-wrap safety column.
  *
  * @private internal utility of coder run UI
  */
-function getTerminalWidth() {
-    return Math.min(process.stdout.columns || DEFAULT_TERMINAL_WIDTH, MAX_TERMINAL_WIDTH);
+function getTerminalColumnCount() {
+    return process.stdout.columns || DEFAULT_TERMINAL_WIDTH;
 }
 /**
  * Boots the ANSI terminal UI for `ptbk coder run`.
@@ -30059,7 +30335,7 @@ function renderCoderRunUi(startTime, options = {}) {
      */
     function buildFrameLines() {
         return buildFrameLinesFromState({
-            terminalWidth: getTerminalWidth(),
+            terminalWidth: getTerminalColumnCount(),
             animationFrame: spinnerFrame,
             animationTimeMs: Date.now() - animationStartTimeMs,
             spinner: SPINNER_FRAMES[spinnerFrame],
@@ -33790,19 +34066,6 @@ class CsvFormatError extends AbstractFormatError {
     }
 }
 
-/**
- * AuthenticationError is thrown from login function which is dependency of remote server
- *
- * @public exported from `@promptbook/core`
- */
-class AuthenticationError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'AuthenticationError';
-        Object.setPrototypeOf(this, AuthenticationError.prototype);
-    }
-}
-
 /**
  * This error indicates that the pipeline collection cannot be properly loaded
  *
@@ -42031,11 +42294,7 @@ function $initializeAgentsServerCommand(program) {
     $initializeAgentsServerDevCommand(agentsServerCommand);
     $initializeAgentsServerInitCommand(agentsServerCommand);
     $initializeAgentsServerStartCommand(agentsServerCommand);
-    agentsServerCommand.action(() => {
-        console.info(colors.yellow('Please specify a subcommand.'));
-        console.info('');
-        agentsServerCommand.help();
-    });
+    $requireCliSubcommand(agentsServerCommand);
 }
 // Note: [🟡] Code for CLI command [agents-server](src/cli/cli-commands/agents-server.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
@@ -42125,24 +42384,82 @@ function normalizeCoderGitSyncCliOptions(cliOptions) {
 // Note: [🟡] Code for CLI git synchronization options [coderGitSyncCliOptions](src/cli/cli-commands/common/coderGitSyncCliOptions.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and exported helper names
 
+/**
+ * Description block shared by the `ptbk coder` commands which can ask interactive questions.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+const QUESTIONS_DESCRIPTION = spaceTrim$1(`
+    Interactive questions:
+    - Steps which need an answer to continue are asked in the terminal
+    - --no-questions never asks: an optional step is skipped with a note how to do it manually, a required one fails right away
+`);
+/**
+ * Registers the shared `--no-questions` option on a `ptbk coder` command which can ask interactive questions.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function addQuestionsOption(command) {
+    command.option('--no-questions', 'Never ask an interactive question and skip every optional step which needs an answer to continue');
+}
+/**
+ * Converts the Commander questions flag into the normalized interactive-questions option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function normalizeQuestionsCliOptions(cliOptions) {
+    return {
+        isAskingQuestionsEnabled: cliOptions.questions,
+    };
+}
+/**
+ * Asserts that a command which waits for a user confirmation before each prompt is allowed to ask for it.
+ *
+ * @throws {NotAllowed} when `--no-auto` is combined with `--no-questions`
+ * @private internal utility of `promptbookCli`
+ */
+function assertUserConfirmationIsAllowed(options) {
+    const { isAskingQuestionsEnabled, isWaitingForUser } = options;
+    if (!isWaitingForUser || isAskingQuestionsEnabled) {
+        return;
+    }
+    throw new NotAllowed(spaceTrim$1(`
+            Flag \`--no-auto\` can not be used together with \`--no-questions\`.
+
+            **There is nobody who could confirm each prompt when no question may be asked.**
+
+            Actionable hints:
+            - Keep \`--no-auto\` for a supervised run, for example \`ptbk coder run --harness claude-code --no-auto\`.
+            - Keep \`--no-questions\` for an unattended run, for example \`ptbk coder run --harness claude-code --no-questions\`.
+        `));
+}
+// Note: [🟡] Code for CLI interactive questions options [questionsCliOptions](src/cli/cli-commands/common/questionsCliOptions.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.
  *
  * @private internal utility of `ptbk coder`
  */
-const PROMPTS_DIRECTORY_PATH = 'prompts';
+const PROMPTS_DIRECTORY_PATH$1 = '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');
+const PROMPTS_DONE_DIRECTORY_PATH = join(PROMPTS_DIRECTORY_PATH$1, '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');
+const PROMPTS_TEMPLATES_DIRECTORY_PATH = join(PROMPTS_DIRECTORY_PATH$1, 'templates');
+/**
+ * Relative path to the project-agnostic `common` boilerplate template referenced by the default coder scripts.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+const COMMON_PROMPT_TEMPLATE_FILE_PATH = join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'common.md');
 /**
  * Built-in boilerplate templates available to `coder generate-boilerplates`.
  *
@@ -42151,7 +42468,7 @@ const PROMPTS_TEMPLATES_DIRECTORY_PATH = join(PROMPTS_DIRECTORY_PATH, 'templates
 const DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS = [
     {
         id: 'common',
-        relativeFilePath: join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'common.md'),
+        relativeFilePath: COMMON_PROMPT_TEMPLATE_FILE_PATH,
         slugPrefix: null,
         content: spaceTrim$1(`
             -   @@@
@@ -42197,30 +42514,17 @@ function getDefaultCoderPromptTemplateDefinition(template) {
     return definition;
 }
 /**
- * Ensures the default project-owned coder template files exist without overwriting user customizations.
+ * Ensures one project-owned coder template file exists 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$3(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',
-        });
+async function ensureDefaultCoderPromptTemplateFile(projectPath, definition) {
+    const absoluteTemplatePath = join(projectPath, definition.relativeFilePath);
+    if (await isExistingFile$3(absoluteTemplatePath)) {
+        return 'unchanged';
     }
-    return ensuredTemplateFiles;
+    await writeFile(absoluteTemplatePath, `${definition.content}\n`, 'utf-8');
+    return 'created';
 }
 /**
  * Resolves the template requested by `coder generate-boilerplates`.
@@ -42376,6 +42680,8 @@ function $initializeCoderAddCommand(program) {
                 - \`ptbk coder add\`
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
+
+                ${block(QUESTIONS_DESCRIPTION)}
             `));
     command.argument('[description]', 'Plain-language description of the feature or task to implement');
     command.option('--priority <priority>', 'Priority of the new prompt — higher priorities run first (rendered as trailing `!` markers)', parsePriorityOption, 0);
@@ -42387,11 +42693,13 @@ function $initializeCoderAddCommand(program) {
         .join(', ')}) or a markdown file path relative to the current project root.
         `));
     addCoderGitSyncOptions(command);
+    addQuestionsOption(command);
     command.action(handleActionErrors(async (descriptionArgument, cliOptions) => {
         const { priority, template: templateOption } = cliOptions;
         const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
+        const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
         const projectPath = process.cwd();
-        const description = await resolveCoderPromptDescription(descriptionArgument);
+        const description = await resolveCoderPromptDescription(descriptionArgument, questionsOptions);
         // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
         const { $commitCoderChanges, $startCoderGitSync } = await Promise.resolve().then(function () { return coderGitSync; });
         const commitScope = await $startCoderGitSync({ gitSync, projectPath });
@@ -42426,7 +42734,7 @@ async function addCoderPrompt({ projectPath, description, priority, templateOpti
     // Note: Import these dynamically to avoid circular dependencies and keep the CLI fast
     const { buildPromptFilename, getPromptNumbering } = await Promise.resolve().then(function () { return getPromptNumbering$1; });
     const { formatPromptEmojiTag, getFreshPromptEmojiTags } = await Promise.resolve().then(function () { return promptEmojiTags; });
-    const promptsDirectory = join(projectPath, PROMPTS_DIRECTORY_PATH);
+    const promptsDirectory = join(projectPath, PROMPTS_DIRECTORY_PATH$1);
     mkdirSync(promptsDirectory, { recursive: true });
     const promptTemplate = await resolveCoderPromptTemplate({ projectPath, templateOption });
     const promptNumbering = await getPromptNumbering({
@@ -42450,7 +42758,7 @@ async function addCoderPrompt({ projectPath, description, priority, templateOpti
     });
     const slug = buildAddPromptSlug(promptTemplate.slugPrefix, title);
     const filename = buildPromptFilename(promptNumbering.datePrefix, promptNumbering.startNumber, slug);
-    const filePath = join(PROMPTS_DIRECTORY_PATH, filename);
+    const filePath = join(PROMPTS_DIRECTORY_PATH$1, filename);
     const absoluteFilePath = join(projectPath, filePath);
     writeFileSync(absoluteFilePath, `${section}\n`, 'utf-8');
     console.info(colors.green(`✓ Added prompt ${emojiTag} in ${filePath}`));
@@ -42461,7 +42769,7 @@ async function addCoderPrompt({ projectPath, description, priority, templateOpti
  *
  * @private internal utility of `coder add` command
  */
-async function resolveCoderPromptDescription(descriptionArgument) {
+async function resolveCoderPromptDescription(descriptionArgument, { isAskingQuestionsEnabled }) {
     if (descriptionArgument !== undefined && descriptionArgument.trim() !== '') {
         return descriptionArgument.trim();
     }
@@ -42479,6 +42787,14 @@ async function resolveCoderPromptDescription(descriptionArgument) {
         }
         return standardInputDescription;
     }
+    if (!isAskingQuestionsEnabled) {
+        throw new ParseError(spaceTrim$1(`
+                Cannot add a prompt without a description.
+
+                The description can not be typed interactively because \`--no-questions\` is used — provide it as an argument or pipe it through stdin instead:
+                - \`ptbk coder add --no-questions "some new feature"\`
+            `));
+    }
     const { default: prompts } = await loadPromptsModule();
     const response = await prompts({
         type: 'text',
@@ -43042,10 +43358,10 @@ async function generatePromptBoilerplate({ projectPath, boilerplateCount, templa
     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`);
-    mkdirSync(join(projectPath, PROMPTS_DIRECTORY_PATH), { recursive: true });
+    mkdirSync(join(projectPath, PROMPTS_DIRECTORY_PATH$1), { recursive: true });
     const promptTemplate = await resolveCoderPromptTemplate({ projectPath, templateOption });
     const promptNumbering = await getPromptNumbering({
-        promptsDir: join(projectPath, PROMPTS_DIRECTORY_PATH),
+        promptsDir: join(projectPath, PROMPTS_DIRECTORY_PATH$1),
         step: 10,
         ignoreGlobs: ['**/node_modules/**'],
     });
@@ -43069,7 +43385,7 @@ async function generatePromptBoilerplate({ projectPath, boilerplateCount, templa
         const title = titles[i % titles.length];
         const emojiTag = formatPromptEmojiTag(selectedEmojis[i]);
         const filename = buildPromptFilename(promptNumbering.datePrefix, number, buildPromptSlug$1(promptTemplate.slugPrefix, title));
-        const filepath = join(PROMPTS_DIRECTORY_PATH, filename);
+        const filepath = join(PROMPTS_DIRECTORY_PATH$1, filename);
         const absoluteFilepath = join(projectPath, filepath);
         const content = buildBoilerplatePromptFileContent({
             emojiTag,
@@ -43129,10 +43445,15 @@ function buildPromptSlug$1(templateSlugPrefix, title) {
  *
  * Note: `$` is used to indicate that this function is not a pure function - it reads the answer from stdin.
  *
- * @returns `true` when the user confirms, `false` when the user declines or the terminal is not interactive.
+ * @returns `true` when the user confirms, `false` when the user declines, the terminal is not interactive
+ *          or the questions are disabled by `--no-questions`.
  * @private internal utility of `promptbookCli`
  */
-async function $askForConfirmation(question) {
+async function $askForConfirmation(question, { isAskingQuestionsEnabled }) {
+    if (!isAskingQuestionsEnabled) {
+        // Note: `--no-questions` forbids asking, so the optional change is declined without blocking the run.
+        return false;
+    }
     if (!process.stdin.isTTY) {
         // Note: In non-interactive environments like CI there is nobody who could confirm the change.
         return false;
@@ -43155,11 +43476,12 @@ async function $askForConfirmation(question) {
  *
  * Note: `$` is used to indicate that this function is not a pure function - it reads the answer from stdin
  *
- * @returns `true` when the user confirms, `false` when the user declines or the terminal is not interactive
+ * @returns `true` when the user confirms, `false` when the user declines, the terminal is not interactive
+ *          or the questions are disabled by `--no-questions`
  * @private internal utility of `promptbookCli`
  */
-async function $askForNpmPackageInstallationApproval(question) {
-    return $askForConfirmation(question);
+async function $askForNpmPackageInstallationApproval(question, questionsOptions) {
+    return $askForConfirmation(question, questionsOptions);
 }
 // Note: [🟡] Code for CLI npm package installation approval [$askForNpmPackageInstallationApproval](src/cli/cli-commands/common/npm/$askForNpmPackageInstallationApproval.ts) should never be published outside of `@promptbook/cli`
 
@@ -43349,7 +43671,7 @@ function resolveHarnessUpdatePlan(definition, installationMethod) {
  *
  * @private internal utility of `promptbookCli`
  */
-async function $applyHarnessInstallationStatus(status) {
+async function $applyHarnessInstallationStatus(status, questionsOptions) {
     const { definition, installationState, installedVersion } = status;
     if (installationState === 'up-to-date') {
         console.info(colors.gray(`✔ ${definition.label} ${installedVersion} is up to date.`));
@@ -43365,17 +43687,17 @@ async function $applyHarnessInstallationStatus(status) {
     }
     console.warn(colors.yellow(formatHarnessInstallationWarning(status)));
     if (installationState === 'not-installed') {
-        await $applyMissingHarnessInstallation(definition);
+        await $applyMissingHarnessInstallation(definition, questionsOptions);
         return;
     }
-    await $applyOutdatedHarnessInstallation(status);
+    await $applyOutdatedHarnessInstallation(status, questionsOptions);
 }
 /**
  * Offers to install a missing harness globally through npm.
  */
-async function $applyMissingHarnessInstallation(definition) {
+async function $applyMissingHarnessInstallation(definition, questionsOptions) {
     const installCommand = buildHarnessInstallCommand(definition);
-    const isInstallationApproved = await $askForNpmPackageInstallationApproval(`Install ${definition.label} globally now?`);
+    const isInstallationApproved = await $askForNpmPackageInstallationApproval(`Install ${definition.label} globally now?`, questionsOptions);
     if (!isInstallationApproved) {
         console.info(colors.gray(`Skipped, run \`${installCommand}\` to do it manually.`));
         return;
@@ -43390,14 +43712,14 @@ async function $applyMissingHarnessInstallation(definition) {
 /**
  * Offers to update an outdated harness exactly where it is installed.
  */
-async function $applyOutdatedHarnessInstallation(status) {
+async function $applyOutdatedHarnessInstallation(status, questionsOptions) {
     const { definition, latestVersion, installationOrigin } = status;
     const updatePlan = resolveHarnessUpdatePlan(definition, installationOrigin.installationMethod);
     if (updatePlan.command === null || !updatePlan.isRunnableByPromptbook) {
         console.info(colors.gray(formatHarnessManualUpdateInstruction(status, updatePlan)));
         return;
     }
-    const isUpdateApproved = await $askForNpmPackageInstallationApproval(`Update ${definition.label} to ${latestVersion} with \`${updatePlan.command}\` now?`);
+    const isUpdateApproved = await $askForNpmPackageInstallationApproval(`Update ${definition.label} to ${latestVersion} with \`${updatePlan.command}\` now?`, questionsOptions);
     if (!isUpdateApproved) {
         console.info(colors.gray(`Skipped, run \`${updatePlan.command}\` to do it manually.`));
         return;
@@ -43833,7 +44155,7 @@ function resolveHarnessInstallationState(installedVersion, latestVersion, isHarn
 // Note: [🟡] Code for CLI harness installation check [$checkHarnessInstallation](src/cli/cli-commands/common/harness/$checkHarnessInstallation.ts) should never be published outside of `@promptbook/cli`
 
 /**
- * Checks that every given CLI coding harness is installed globally and, when enabled, up to date.
+ * Checks that every given CLI coding harness is installed globally and, when the questions are enabled, up to date.
  * Offers to install missing harnesses and update outdated ones.
  *
  * Harness names which are `undefined`, for example when no `--harness` is selected in a dry run,
@@ -43843,15 +44165,18 @@ function resolveHarnessInstallationState(installedVersion, latestVersion, isHarn
  *
  * @private internal utility of `promptbookCli`
  */
-async function $ensureHarnessInstallations(harnessNames, isHarnessUpdateCheckEnabled = true) {
+async function $ensureHarnessInstallations(harnessNames, questionsOptions) {
     const definitions = resolveCheckedHarnessDefinitions(harnessNames);
     if (definitions.length === 0) {
         return;
     }
+    // Note: An outdated harness can be updated only after the user confirms it, so `--no-questions`
+    //       skips the slower npm registry lookup entirely and only reports what is installed.
+    const isHarnessUpdateCheckEnabled = questionsOptions.isAskingQuestionsEnabled;
     // Note: Detection of all harnesses runs in parallel, the questions have to be asked one by one
     const statuses = await Promise.all(definitions.map((definition) => $checkHarnessInstallation(definition, isHarnessUpdateCheckEnabled)));
     for (const status of statuses) {
-        await $applyHarnessInstallationStatus(status);
+        await $applyHarnessInstallationStatus(status, questionsOptions);
     }
 }
 /**
@@ -43863,48 +44188,6 @@ function resolveCheckedHarnessDefinitions(harnessNames) {
 }
 // Note: [🟡] Code for CLI harness installation orchestration [$ensureHarnessInstallations](src/cli/cli-commands/common/harness/$ensureHarnessInstallations.ts) should never be published outside of `@promptbook/cli`
 
-/**
- * Registers the shared `--no-harness-update` option on a `ptbk coder` command that uses a coding harness.
- *
- * @private internal utility of `promptbookCli`
- */
-function addHarnessUpdateOption(command) {
-    command.option('--no-harness-update', 'Skip checking whether the installed coding harnesses are up to date');
-}
-/**
- * Converts the Commander harness-update flag into the normalized harness-check option.
- *
- * @private internal utility of `promptbookCli`
- */
-function normalizeHarnessUpdateCliOptions(cliOptions) {
-    return {
-        isHarnessUpdateCheckEnabled: cliOptions.harnessUpdate,
-    };
-}
-// Note: [🟡] Code for CLI harness update options [harnessUpdateCliOptions](src/cli/cli-commands/common/harnessUpdateCliOptions.ts) should never be published outside of `@promptbook/cli`
-// Note: [💞] Ignore a discrepancy between file name and exported helper names
-
-/**
- * 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() {
-    return spaceTrim$1(`
-        # ✨ Promptbook Coder agent coding
-
-        This project is using [Promptbook Coder](https://coder.ptbk.io) or run \`ptbk coder\`!
-    `);
-}
-// 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 shared coder context file initialized in project roots.
  *
@@ -44006,6 +44289,51 @@ function formatDisplayPath(relativePath) {
 }
 // Note: [🟡] Code for coder path formatting [formatDisplayPath](src/cli/cli-commands/coder/formatDisplayPath.ts) should never be published outside of `@promptbook/cli`
 
+/**
+ * Creates the artifact definition of one project-owned coder prompt template.
+ */
+function createCoderPromptTemplateArtifactDefinition(definition) {
+    return {
+        relativeFilePath: definition.relativeFilePath,
+        ensureArtifactFile: (projectPath) => ensureDefaultCoderPromptTemplateFile(projectPath, definition),
+    };
+}
+/**
+ * Every artifact which the default coder scripts can reference.
+ */
+const CODER_REFERENCED_ARTIFACT_DEFINITIONS = [
+    {
+        relativeFilePath: CODER_DEVELOPER_AGENT_FILE_PATH,
+        ensureArtifactFile: ensureCoderDeveloperAgentFile,
+    },
+    {
+        relativeFilePath: AGENTS_FILE_PATH,
+        ensureArtifactFile: (projectPath) => ensureCoderMarkdownFile(projectPath, AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent()),
+    },
+    ...getDefaultCoderProjectPromptTemplateDefinitions().map(createCoderPromptTemplateArtifactDefinition),
+];
+/**
+ * Creates only those referenced artifacts which the freshly added coder scripts point at.
+ *
+ * An artifact of a script which the project already defines is intentionally **not** created - the project-owned
+ * script is kept as is, so it does not reference the default artifact in the first place.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+async function ensureCoderReferencedArtifacts(projectPath, referencedArtifactPaths) {
+    const ensuredArtifacts = [];
+    for (const { relativeFilePath, ensureArtifactFile } of CODER_REFERENCED_ARTIFACT_DEFINITIONS) {
+        if (!referencedArtifactPaths.has(relativeFilePath)) {
+            ensuredArtifacts.push({ relativeFilePath, status: 'not-referenced' });
+            continue;
+        }
+        ensuredArtifacts.push({ relativeFilePath, status: await ensureArtifactFile(projectPath) });
+    }
+    return ensuredArtifacts;
+}
+// Note: [🟡] Code for coder init referenced artifacts [coderReferencedArtifacts](src/cli/cli-commands/coder/coderReferencedArtifacts.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names
+
 /**
  * Fallback `.env` content used when no required variables need to be appended.
  */
@@ -44100,26 +44428,79 @@ async function ensureCoderGitignoreRules(projectPath, rules) {
 }
 // Note: [🟡] Code for coder init gitignore bootstrapping [ensureCoderGitignoreFile](src/cli/cli-commands/coder/ensureCoderGitignoreFile.ts) should never be published outside of `@promptbook/cli`
 
+/**
+ * Name of the npm script which `ptbk coder run` uses to verify the project.
+ */
+const CODER_TEST_SCRIPT_NAME = 'test-for-ptbk-coder';
 /**
  * Default npm scripts initialized by `ptbk coder init`.
+ *
+ * Note: Using NPX because `ptbk` can be installed globally or locally, and NPX will resolve it correctly in either case.
  */
-const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
-    // Note: Using NPX because `ptbk` can be installed globally or locally, and NPX will resolve it correctly in either case.
-    'coder:generate-boilerplates': `npx ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ./prompts/templates/common.md`,
-    'coder:add': 'npx ptbk coder add --template ./prompts/templates/common.md',
-    'coder:run': 'npx ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max --agent agents/developer.book --context AGENTS.md --test-before yes-and-fix',
-    // 'coder:find-refactor-candidates': 'npx ptbk coder find-refactor-candidates',
-    'coder:verify': 'npx ptbk coder verify',
-};
+const DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS = [
+    {
+        scriptName: 'coder:generate-boilerplates',
+        scriptCommand: `npx ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ${formatCoderScriptFilePath(COMMON_PROMPT_TEMPLATE_FILE_PATH)}`,
+        referencedArtifactPaths: [COMMON_PROMPT_TEMPLATE_FILE_PATH],
+    },
+    {
+        scriptName: 'coder:add',
+        scriptCommand: `npx ptbk coder add --template ${formatCoderScriptFilePath(COMMON_PROMPT_TEMPLATE_FILE_PATH)}`,
+        referencedArtifactPaths: [COMMON_PROMPT_TEMPLATE_FILE_PATH],
+    },
+    {
+        scriptName: 'coder:run',
+        scriptCommand: [
+            'npx ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max',
+            `--agent ${formatDisplayPath(CODER_DEVELOPER_AGENT_FILE_PATH)}`,
+            `--context ${formatDisplayPath(AGENTS_FILE_PATH)}`,
+            `--test "npm run ${CODER_TEST_SCRIPT_NAME}" --test-before yes-and-fix`,
+        ].join(' '),
+        referencedArtifactPaths: [CODER_DEVELOPER_AGENT_FILE_PATH, AGENTS_FILE_PATH],
+    },
+    // { scriptName: 'coder:find-refactor-candidates', scriptCommand: 'npx ptbk coder find-refactor-candidates', referencedArtifactPaths: [] },
+    {
+        scriptName: 'coder:verify',
+        scriptCommand: 'npx ptbk coder verify',
+        referencedArtifactPaths: [],
+    },
+    {
+        // Note: The verification command of `coder:run` is a project-owned script, so every project can decide
+        //       what "verified" means without touching the `coder:run` script itself
+        scriptName: CODER_TEST_SCRIPT_NAME,
+        scriptCommand: 'npm test',
+        referencedArtifactPaths: [],
+    },
+];
 /**
  * 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;
+    return Object.fromEntries(DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS.map(({ scriptName, scriptCommand }) => [
+        scriptName,
+        scriptCommand,
+    ]));
+}
+/**
+ * Collects the project-relative artifact paths referenced by the given default coder scripts.
+ *
+ * @private internal utility of `coder init` command
+ */
+function resolveCoderPackageJsonScriptReferencedArtifactPaths(scriptNames) {
+    return new Set(DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS.filter(({ scriptName }) => scriptNames.includes(scriptName))
+        .map(({ referencedArtifactPaths }) => referencedArtifactPaths)
+        .flat());
+}
+/**
+ * Formats one project-relative path as an explicitly project-rooted path usable inside a shell command.
+ */
+function formatCoderScriptFilePath(relativeFilePath) {
+    return `./${formatDisplayPath(relativeFilePath)}`;
 }
 // Note: [🟡] Code for coder init package scripts [getDefaultCoderPackageJsonScripts](src/cli/cli-commands/coder/getDefaultCoderPackageJsonScripts.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names
 
 /**
  * Loads the TypeScript runtime used for parsing JSONC-style project files.
@@ -44152,6 +44533,9 @@ const DEFAULT_JSON_FILE_NEWLINE = '\n';
 /**
  * Ensures one JSON object field contains the provided string-record entries.
  *
+ * Entries which the project already defines are **never** overridden - only missing keys are added,
+ * so hand-tuned scripts and settings survive every repeated `ptbk coder init`.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
 async function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, }) {
@@ -44163,21 +44547,24 @@ async function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldP
     const formatting = detectJsonFileFormatting(fileContent);
     const jsonObject = fileContent === undefined ? {} : await parseJsonObjectFile(relativeFilePath, fileContent);
     const existingEntries = getStringRecordOrDefault(jsonObject[fieldPath], relativeFilePath, fieldPath);
-    let hasChanges = fileContent === undefined;
+    const addedEntryKeys = [];
     const mergedEntries = { ...existingEntries };
     for (const [entryKey, entryValue] of Object.entries(nextEntries)) {
-        if (mergedEntries[entryKey] !== entryValue) {
-            mergedEntries[entryKey] = entryValue;
-            hasChanges = true;
+        if (Object.prototype.hasOwnProperty.call(mergedEntries, entryKey)) {
+            // Note: The project already defines this entry, keep its own value untouched
+            continue;
         }
+        mergedEntries[entryKey] = entryValue;
+        addedEntryKeys.push(entryKey);
     }
+    const hasChanges = fileContent === undefined || addedEntryKeys.length > 0;
     if (!hasChanges) {
-        return 'unchanged';
+        return { status: 'unchanged', addedEntryKeys };
     }
     const nextJsonObject = { ...jsonObject };
     nextJsonObject[fieldPath] = mergedEntries;
     await writeFile(absoluteFilePath, serializeJsonObject(nextJsonObject, formatting), 'utf-8');
-    return fileContent === undefined ? 'created' : 'updated';
+    return { status: fileContent === undefined ? 'created' : 'updated', addedEntryKeys };
 }
 /**
  * Parses one JSON object file while accepting VS Code style comments and trailing commas.
@@ -44266,6 +44653,8 @@ const PACKAGE_JSON_FILE_PATH = 'package.json';
 /**
  * Ensures `package.json` contains the standalone Promptbook coder helper scripts.
  *
+ * Scripts which the project already defines are kept as they are, only missing ones are added.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
 async function ensureCoderPackageJsonFile(projectPath) {
@@ -44319,17 +44708,20 @@ const VSCODE_DIRECTORY_PATH = '.vscode';
 /**
  * Ensures VS Code routes pasted prompt images into `prompts/screenshots`.
  *
+ * Settings which the project already defines are kept as they are, only missing ones are added.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
 async function ensureCoderVscodeSettingsFile(projectPath) {
     const [fieldPath, nextEntries] = resolveDefaultCoderVscodeSettingsEntry();
-    return mergeStringRecordJsonFile({
+    const { status } = await mergeStringRecordJsonFile({
         projectPath,
         relativeFilePath: VSCODE_SETTINGS_FILE_PATH,
         fieldPath,
         nextEntries,
         ensureParentDirectoryPath: VSCODE_DIRECTORY_PATH,
     });
+    return status;
 }
 /**
  * Resolves the default string-record entry that `coder init` merges into VS Code settings.
@@ -44346,34 +44738,32 @@ function resolveDefaultCoderVscodeSettingsEntry() {
 /**
  * Creates or updates all coder configuration artifacts required in the current project.
  *
+ * Nothing the project already owns is ever overwritten - existing scripts, settings and files are kept as they are,
+ * and the artifacts they would reference are created only together with the scripts which actually reference them.
+ *
  * @private internal utility of `coder init` command
  */
 async function initializeCoderProjectConfiguration(projectPath) {
-    const promptsDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DIRECTORY_PATH);
+    const promptsDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DIRECTORY_PATH$1);
     const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
     const promptsTemplatesDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH);
-    const promptTemplateFileStatuses = await ensureDefaultCoderPromptTemplateFiles(projectPath);
     const agentsDirectoryStatus = await ensureDirectory(projectPath, CODER_AGENTS_DIRECTORY_PATH);
-    const developerAgentFileStatus = await ensureCoderDeveloperAgentFile(projectPath);
-    const agentsFileStatus = await ensureCoderMarkdownFile(projectPath, AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent());
-    const agentCodingFileStatus = await ensureCoderMarkdownFile(projectPath, AGENT_CODING_FILE_PATH, getDefaultCoderAgentCodingFileContent());
     const { envFileStatus, initializedEnvVariableNames } = await ensureCoderEnvFile(projectPath);
     const gitignoreFileStatus = await ensureCoderGitignoreFile(projectPath);
-    const packageJsonFileStatus = await ensureCoderPackageJsonFile(projectPath);
+    const { status: packageJsonFileStatus, addedEntryKeys: addedPackageJsonScriptNames } = await ensureCoderPackageJsonFile(projectPath);
     const vscodeSettingsFileStatus = await ensureCoderVscodeSettingsFile(projectPath);
+    const referencedArtifactStatuses = await ensureCoderReferencedArtifacts(projectPath, resolveCoderPackageJsonScriptReferencedArtifactPaths(addedPackageJsonScriptNames));
     return {
         promptsDirectoryStatus,
         promptsDoneDirectoryStatus,
         promptsTemplatesDirectoryStatus,
-        promptTemplateFileStatuses,
         agentsDirectoryStatus,
-        developerAgentFileStatus,
-        agentsFileStatus,
-        agentCodingFileStatus,
         envFileStatus,
         gitignoreFileStatus,
         packageJsonFileStatus,
         vscodeSettingsFileStatus,
+        addedPackageJsonScriptNames,
+        referencedArtifactStatuses,
         initializedEnvVariableNames,
     };
 }
@@ -44389,17 +44779,20 @@ function printInitializationSummary(summary) {
     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/', summary.agentsDirectoryStatus);
-    printInitializationStatusLine(CODER_DEVELOPER_AGENT_FILE_PATH, summary.developerAgentFileStatus);
-    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);
+    for (const referencedArtifactStatus of summary.referencedArtifactStatuses) {
+        printInitializationStatusLine(formatDisplayPath(referencedArtifactStatus.relativeFilePath), referencedArtifactStatus.status);
+    }
+    if (summary.addedPackageJsonScriptNames.length > 0) {
+        printInitializationNote(`Added npm scripts: ${summary.addedPackageJsonScriptNames.join(', ')}`, colors.cyan);
+    }
+    else {
+        printInitializationNote('All Promptbook coder npm scripts are already present.', colors.gray);
+    }
     if (summary.initializedEnvVariableNames.length > 0) {
         printInitializationNote(`Added env variables: ${summary.initializedEnvVariableNames.join(', ')}`, colors.cyan);
     }
@@ -44417,6 +44810,9 @@ function formatInitializationStatus(status) {
     if (status === 'updated') {
         return 'updated';
     }
+    if (status === 'not-referenced') {
+        return 'not referenced by the added scripts, kept as is';
+    }
     return 'unchanged';
 }
 /**
@@ -44459,39 +44855,48 @@ function $initializeCoderInitCommand(program) {
                 ${block(listDefaultCoderProjectPromptTemplateDisplayPaths())}
                 - ${CODER_DEVELOPER_AGENT_FILE_PATH}
                 - ${AGENTS_FILE_PATH}
-                - ${AGENT_CODING_FILE_PATH}
                 - .gitignore with local artifacts from every supported harness
                 - package.json
                 - .vscode/settings.json
 
+                Never overwrites what the project already owns:
+                - Existing package.json scripts and .vscode/settings.json settings are kept, only missing ones are added
+                - Files referenced by a script, like the agent and context of coder:run, are created only together
+                  with the script which references them
+
                 Ensures required coding-agent environment variables in .env:
                 - CODING_AGENT_GIT_NAME
                 - CODING_AGENT_GIT_EMAIL
                 - CODING_AGENT_GIT_SIGNING_KEY
 
-                Checks that the coding harnesses are installed and up to date unless \`--no-harness-update\` is used:
+                Checks that the coding harnesses are installed and up to date unless \`--no-questions\` is used:
                 ${block(listCheckedHarnessLabels())}
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
+
+                ${block(QUESTIONS_DESCRIPTION)}
             `));
     addCoderGitSyncOptions(command);
-    addHarnessUpdateOption(command);
+    addQuestionsOption(command);
     command.action(handleActionErrors(async (cliOptions) => {
         const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
-        const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
+        const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
         const projectPath = process.cwd();
         // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
         const { $commitCoderChanges, $startCoderGitSync } = await Promise.resolve().then(function () { return coderGitSync; });
         const commitScope = await $startCoderGitSync({ gitSync, projectPath });
+        const isPromptsDirectoryEmpty = await isDirectoryEmpty(projectPath, PROMPTS_DIRECTORY_PATH$1);
         const summary = await initializeCoderProjectConfiguration(projectPath);
         printInitializationSummary(summary);
-        await generatePromptBoilerplate({ projectPath, boilerplateCount: DEFAULT_BOILERPLATE_COUNT });
+        if (isPromptsDirectoryEmpty) {
+            await generatePromptBoilerplate({ projectPath, boilerplateCount: DEFAULT_BOILERPLATE_COUNT });
+        }
         await $commitCoderChanges({
             gitSync,
             commitScope,
             commitMessage: 'Initialize Promptbook Coder',
         });
-        await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, isHarnessUpdateCheckEnabled);
+        await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, questionsOptions);
     }));
 }
 /**
@@ -44511,6 +44916,112 @@ function listDefaultCoderProjectPromptTemplateDisplayPaths() {
 // 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
 
+/**
+ * Creates a Commander argument parser that accepts only non-negative integers.
+ *
+ * The returned parser is meant to be passed as the coercion callback of `command.option(...)`.
+ * It throws a branded `NotAllowed` error with a clear message referencing the given option name
+ * when the provided value is not a non-negative integer.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function createNonNegativeIntegerOptionParser(optionName) {
+    return (value) => {
+        const parsedValue = Number(value);
+        if (!Number.isInteger(parsedValue) || parsedValue < 0) {
+            throw new NotAllowed(spaceTrim$1(`
+                    Invalid value for \`${optionName}\`: \`${value}\`.
+
+                    Use a non-negative integer.
+                `));
+        }
+        return parsedValue;
+    };
+}
+// Note: [🟡] Code for CLI option parser [createNonNegativeIntegerOptionParser](src/cli/cli-commands/common/createNonNegativeIntegerOptionParser.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Registers the shared prompt-priority filter options on a queue-based `ptbk coder` command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function addPromptPriorityOptions(command) {
+    command.option('--priority <minimum-priority>', 'Alias for --min-priority; filter prompts by minimum priority level', createNonNegativeIntegerOptionParser('--priority'));
+    command.option('--min-priority <minimum-priority>', 'Filter prompts by minimum priority level', createNonNegativeIntegerOptionParser('--min-priority'));
+    command.option('--max-priority <maximum-priority>', 'Filter prompts by maximum priority level', createNonNegativeIntegerOptionParser('--max-priority'));
+}
+// Note: [🟡] Code for CLI prompt priority options [promptPriorityCliOptions](src/cli/cli-commands/common/promptPriorityCliOptions.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names
+
+/**
+ * Description shared by coder commands which accept an agent Book.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+const CODER_AGENT_OPTION_DESCRIPTION = 'Path to a .book file used to personalize coding prompts and select agent-specific tasks';
+/**
+ * Registers the shared `--agent` option for coder commands.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+function addCoderAgentOption(command) {
+    command.option('--agent <agent-book-path>', CODER_AGENT_OPTION_DESCRIPTION);
+}
+// Note: [🟡] Code for CLI coder agent options should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names
+
+/**
+ * Initializes `coder list` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+function $initializeCoderListCommand(program) {
+    const command = program.command('list');
+    command.description(spaceTrim$1(`
+            List ready coding prompts by priority without executing them
+
+            ${PROMPT_RUNNER_DESCRIPTION}
+
+            Features:
+            - Lists only ready, fully authored prompts
+            - Groups prompts from highest to lowest priority
+            - Optional --harness, --model and --agent filters show only prompts compatible with that selection
+            - Does not start a coding harness or modify prompt files
+        `));
+    addPromptRunnerSelectionOptions(command);
+    addCoderAgentOption(command);
+    addPromptPriorityOptions(command);
+    command.action(handleActionErrors(async (cliOptions) => {
+        const { agent, priority, minPriority: minimumPriority, maxPriority: maximumPriority, } = cliOptions;
+        const runnerOptions = normalizePromptRunnerSelectionCliOptions(cliOptions, { isAgentRequired: false });
+        const resolvedCoderAgentBook = agent === undefined
+            ? undefined
+            : await (await Promise.resolve().then(function () { return resolveCoderAgent$1; }))
+                .resolveCoderAgentBook(agent, process.cwd());
+        const promptRunnerIdentity = runnerOptions.agentName === undefined &&
+            runnerOptions.model === undefined &&
+            resolvedCoderAgentBook === undefined
+            ? undefined
+            : {
+                harnessName: runnerOptions.agentName,
+                modelName: runnerOptions.model,
+                agentReferences: resolvedCoderAgentBook === null || resolvedCoderAgentBook === void 0 ? void 0 : resolvedCoderAgentBook.agentReferences,
+            };
+        // Note: Import dynamically to avoid loading prompt parsing dependencies until this command is used.
+        const { listCoderPrompts } = await Promise.resolve().then(function () { return listCoderPrompts$1; });
+        await listCoderPrompts({
+            priority,
+            minimumPriority,
+            maximumPriority,
+            promptRunnerIdentity,
+        });
+    }));
+}
+// Note: [🟡] Code for CLI command [list](src/cli/cli-commands/coder/list.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
 /**
  * Default wait duration applied before retrying a prompt round after an error (10 minutes).
  *
@@ -44564,7 +45075,7 @@ function parseOptionalPeriodDuration(optionName, value) {
  *
  * @private internal utility of `ptbk coder`
  */
-async function $ensureCoderHarnessGitignoreRules(projectPath, harnessName) {
+async function $ensureCoderHarnessGitignoreRules(projectPath, harnessName, questionsOptions) {
     if (harnessName === undefined) {
         return;
     }
@@ -44575,7 +45086,7 @@ async function $ensureCoderHarnessGitignoreRules(projectPath, harnessName) {
     const { label } = getHarnessDefinition(harnessName);
     const formattedRules = formatGitignoreRules(missingRules);
     const entryLabel = missingRules.length === 1 ? 'entry' : 'entries';
-    const isAdditionApproved = await $askForConfirmation(`Add the missing ${label} ignore ${entryLabel} ${formattedRules} to \`.gitignore\` now?`);
+    const isAdditionApproved = await $askForConfirmation(`Add the missing ${label} ignore ${entryLabel} ${formattedRules} to \`.gitignore\` now?`, questionsOptions);
     if (!isAdditionApproved) {
         console.info(colors.gray(`Skipped, add ${formattedRules} to \`.gitignore\` manually.`));
         return;
@@ -44600,22 +45111,24 @@ function formatGitignoreRules(rules) {
  */
 function $initializeCoderPingCommand(program) {
     const command = program.command('ping');
-    command.description(spaceTrim$1(`
-            Send one tiny dummy prompt to a harness and model to measure and warm them up
+    command.description(spaceTrim$1((block) => `
+                Send one tiny dummy prompt to a harness and model to measure and warm them up
 
-            ${PROMPT_RUNNER_DESCRIPTION}
+                ${block(PROMPT_RUNNER_DESCRIPTION)}
 
-            Features:
-            - Verifies that the selected harness, model, thinking level and authentication really work
-            - Reports the answer of the harness, the response time and the reported usage
-            - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
-            - Optional --period keeps the quota window refreshing by pinging once per period until stopped
-            - Makes no coding changes or commits; if the selected harness has missing local ignore rules, offers to add them to .gitignore
-            - Checks that the selected harness is installed and up to date unless --no-harness-update is used
-            - Use --no-ui to stream the raw harness output instead of only the compact result
-        `));
+                ${block(QUESTIONS_DESCRIPTION)}
+
+                Features:
+                - Verifies that the selected harness, model, thinking level and authentication really work
+                - Reports the answer of the harness, the response time and the reported usage
+                - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
+                - Optional --period keeps the quota window refreshing by pinging once per period until stopped
+                - Makes no coding changes or commits; if the selected harness has missing local ignore rules, offers to add them to .gitignore
+                - Checks that the selected harness is installed and up to date unless --no-questions is used
+                - Use --no-ui to stream the raw harness output instead of only the compact result
+            `));
     addPromptRunnerSelectionOptions(command);
-    addHarnessUpdateOption(command);
+    addQuestionsOption(command);
     addPromptRunnerRuntimeOptions(command);
     command.option('--period <duration>', spaceTrim$1(`
             Keep pinging once per period instead of pinging only once.
@@ -44624,11 +45137,11 @@ function $initializeCoderPingCommand(program) {
     command.action(handleActionErrors(async (cliOptions) => {
         const { period: periodValue } = cliOptions;
         const runnerOptions = normalizePromptRunnerSelectionCliOptions(cliOptions, { isAgentRequired: true });
-        const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
+        const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
         // Note: The period is validated before the harness installation check, so a mistyped duration fails fast
         const periodMs = parseOptionalPeriodDuration('--period', periodValue);
-        await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
-        await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
+        await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
+        await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName, questionsOptions);
         const pingOptions = {
             agentName: runnerOptions.agentName,
             model: runnerOptions.model,
@@ -44652,28 +45165,157 @@ function $initializeCoderPingCommand(program) {
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
- * Creates a Commander argument parser that accepts only non-negative integers.
+ * Free disk space below which `ptbk coder` refuses to start a new run.
  *
- * The returned parser is meant to be passed as the coercion callback of `command.option(...)`.
- * It throws a branded `NotAllowed` error with a clear message referencing the given option name
- * when the provided value is not a non-negative integer.
+ * A coding round writes prompt and log artifacts, lets the harness rewrite the project, may install npm packages,
+ * may create a git worktree for `--isolate` and usually runs a build, so a run started with less than this
+ * would very likely die somewhere in the middle with a filesystem error.
  *
  * @private internal utility of `promptbookCli`
  */
-function createNonNegativeIntegerOptionParser(optionName) {
-    return (value) => {
-        const parsedValue = Number(value);
-        if (!Number.isInteger(parsedValue) || parsedValue < 0) {
-            throw new NotAllowed(spaceTrim$1(`
-                    Invalid value for \`${optionName}\`: \`${value}\`.
+const LOW_FREE_DISK_SPACE_BYTES = 2 * 1024 * 1024 * 1024;
+/**
+ * Free disk space below which a started `ptbk coder` run stops at its next checkpoint and waits until space is freed.
+ *
+ * This limit is lower than `LOW_FREE_DISK_SPACE_BYTES`, because interrupting a run which is already in progress
+ * is more expensive than not starting one at all.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+const CRITICALLY_LOW_FREE_DISK_SPACE_BYTES = 1 * 1024 * 1024 * 1024;
+/**
+ * How long one free disk space measurement is reused before the filesystem is measured again during a run.
+ *
+ * Pause checkpoints are passed very often - for example on every tick of a timed wait - so without this
+ * interval the filesystem would be measured many times per second.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+const FREE_DISK_SPACE_RECHECK_INTERVAL_MS = 60 * 1000;
+// Note: [🟡] Code for CLI free disk space handling [freeDiskSpaceConstants](src/cli/cli-commands/common/disk-space/freeDiskSpaceConstants.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
-                    Use a non-negative integer.
-                `));
+/**
+ * Classifies one measured amount of free disk space against the `ptbk coder` free disk space limits.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function resolveFreeDiskSpaceLevel(availableBytes) {
+    if (availableBytes < CRITICALLY_LOW_FREE_DISK_SPACE_BYTES) {
+        return 'critical';
+    }
+    if (availableBytes < LOW_FREE_DISK_SPACE_BYTES) {
+        return 'low';
+    }
+    return 'sufficient';
+}
+// Note: [🟡] Code for CLI free disk space handling [resolveFreeDiskSpaceLevel](src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Measures the free disk space on the filesystem which hosts the given path.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the state of the filesystem
+ *
+ * @returns the measurement, or `null` when the filesystem can not be measured, for example on a platform which
+ *          does not report filesystem statistics - a run is never stopped by a measurement which could not be taken
+ * @private internal utility of `promptbookCli`
+ */
+async function $readFreeDiskSpaceStatus(inspectedPath) {
+    try {
+        const fileSystemStats = await statfs(inspectedPath);
+        const blockSizeBytes = fileSystemStats.bsize;
+        const availableBytes = fileSystemStats.bavail * blockSizeBytes;
+        const totalBytes = fileSystemStats.blocks * blockSizeBytes;
+        if (!Number.isFinite(availableBytes) || availableBytes < 0) {
+            return null;
         }
-        return parsedValue;
-    };
+        return {
+            inspectedPath,
+            availableBytes,
+            totalBytes,
+            level: resolveFreeDiskSpaceLevel(availableBytes),
+        };
+    }
+    catch (_a) {
+        // Note: A path or a platform which can not report its free disk space must not stop `ptbk coder` from running
+        return null;
+    }
 }
-// Note: [🟡] Code for CLI option parser [createNonNegativeIntegerOptionParser](src/cli/cli-commands/common/createNonNegativeIntegerOptionParser.ts) should never be published outside of `@promptbook/cli`
+// Note: [🟡] Code for CLI free disk space handling [$readFreeDiskSpaceStatus](src/cli/cli-commands/common/disk-space/$readFreeDiskSpaceStatus.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Byte units used when one amount of disk space is written for a human.
+ */
+const FREE_DISK_SPACE_BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'];
+/**
+ * Writes one byte count as a compact human-readable amount of disk space, for example `812 MB` or `1.5 GB`.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function formatFreeDiskSpaceBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0) {
+        return '0 B';
+    }
+    const unitIndex = Math.min(FREE_DISK_SPACE_BYTE_UNITS.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+    const value = bytes / Math.pow(1024, unitIndex);
+    // Note: One decimal place only matters for small values, `476 GB` is more readable than `476.3 GB`
+    const decimalPlaceCount = value >= 10 || unitIndex === 0 ? 0 : 1;
+    // Note: An empty decimal place only adds noise, `2 GB` is more readable than `2.0 GB`
+    const displayedValue = value.toFixed(decimalPlaceCount).replace(/\.0$/, '');
+    return `${displayedValue} ${FREE_DISK_SPACE_BYTE_UNITS[unitIndex]}`;
+}
+// Note: [🟡] Code for CLI free disk space handling [formatFreeDiskSpaceBytes](src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Writes the shared warning which explains one low free disk space measurement and how to get out of it.
+ *
+ * The very same wording is used by the check which refuses to start a run and by the check which pauses
+ * a run that ran out of disk space while it was working.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus) {
+    const { inspectedPath } = freeDiskSpaceStatus;
+    const availableSpace = formatFreeDiskSpaceBytes(freeDiskSpaceStatus.availableBytes);
+    const totalSpace = formatFreeDiskSpaceBytes(freeDiskSpaceStatus.totalBytes);
+    const requiredSpaceToStart = formatFreeDiskSpaceBytes(LOW_FREE_DISK_SPACE_BYTES);
+    const requiredSpaceToContinue = formatFreeDiskSpaceBytes(CRITICALLY_LOW_FREE_DISK_SPACE_BYTES);
+    return spaceTrim$1(`
+        Only **${availableSpace}** of ${totalSpace} is left on the disk which hosts \`${inspectedPath}\`.
+
+        **\`ptbk coder\` needs at least ${requiredSpaceToStart} of free disk space to start a run and at least ${requiredSpaceToContinue} to keep one running.**
+
+        Actionable hints:
+        - Free up disk space on the drive which hosts \`${inspectedPath}\`.
+        - Remove build artifacts, package caches and \`node_modules\` folders of projects you are not working on.
+        - Remove the temporary worktrees which earlier \`--isolate\` runs left behind.
+    `);
+}
+// Note: [🟡] Code for CLI free disk space handling [formatLowFreeDiskSpaceWarning](src/cli/cli-commands/common/disk-space/formatLowFreeDiskSpaceWarning.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Refuses to start one `ptbk coder` command when the disk which hosts the project is nearly full.
+ *
+ * A run which starts without enough free disk space fails somewhere in the middle, after the coding agent has
+ * already rewritten a part of the project, so it is stopped before it writes anything at all.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the state of the filesystem
+ *
+ * @throws {LimitReachedError} when there is not enough free disk space left to start
+ * @private internal utility of `promptbookCli`
+ */
+async function $assertSufficientFreeDiskSpace(inspectedPath) {
+    const freeDiskSpaceStatus = await $readFreeDiskSpaceStatus(inspectedPath);
+    if (freeDiskSpaceStatus === null || freeDiskSpaceStatus.level === 'sufficient') {
+        return;
+    }
+    throw new LimitReachedError(spaceTrim$1((block) => `
+                There is not enough free disk space to run \`ptbk coder\`.
+
+                ${block(formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus))}
+            `));
+}
+// Note: [🟡] Code for CLI free disk space handling [$assertSufficientFreeDiskSpace](src/cli/cli-commands/common/disk-space/$assertSufficientFreeDiskSpace.ts) should never be published outside of `@promptbook/cli`
 
 /**
  * Npm packages which directly provide the `ptbk` executable.
@@ -45003,7 +45645,11 @@ function formatPromptbookCliInstallationLocation(installationLocation) {
  * @returns `true` when at least one installation was updated and the current coder run should stop
  * @private internal utility of `promptbookCli`
  */
-async function $ensurePromptbookCliInstallations() {
+async function $ensurePromptbookCliInstallations(questionsOptions) {
+    if (!questionsOptions.isAskingQuestionsEnabled) {
+        // Note: `--no-questions` forbids asking for the approval, so the registry checks would be useless
+        return false;
+    }
     if (!process.stdin.isTTY) {
         // Note: Non-interactive runs cannot approve an update and should not wait for registry checks
         return false;
@@ -45015,7 +45661,7 @@ async function $ensurePromptbookCliInstallations() {
         return false;
     }
     console.warn(colors.yellow(formatPromptbookCliInstallationWarning(outdatedStatuses)));
-    const isUpdateApproved = await $askForNpmPackageInstallationApproval('Update Promptbook CLI now?');
+    const isUpdateApproved = await $askForNpmPackageInstallationApproval('Update Promptbook CLI now?', questionsOptions);
     if (!isUpdateApproved) {
         reportManualPromptbookCliUpdateCommands(outdatedStatuses);
         return false;
@@ -45082,6 +45728,17 @@ function isTestBeforeMode(value) {
     return TEST_BEFORE_MODE_VALUES.includes(value);
 }
 
+/**
+ * Prints why a coder run has ended to the terminal.
+ *
+ * @private internal utility of `coder run` and `coder server` commands
+ */
+function printCoderRunFailure(error) {
+    console.error(colors.bgRed(`${error.name}`));
+    console.error(colors.red(formatUnknownErrorDetails(error)));
+}
+// Note: [🟡] Code for coder failure reporting [printCoderRunFailure](src/cli/cli-commands/coder/printCoderRunFailure.ts) should never be published outside of `@promptbook/cli`
+
 /**
  * Initializes `coder run` command for Promptbook CLI utilities
  *
@@ -45091,10 +45748,12 @@ function isTestBeforeMode(value) {
  */
 function $initializeCoderRunCommand(program) {
     const command = program.command('run');
-    command.description(spaceTrim$1(`
+    command.description(spaceTrim$1((block) => `
             Execute coding prompts through selected AI agent
 
-            ${PROMPT_RUNNER_DESCRIPTION}
+            ${block(PROMPT_RUNNER_DESCRIPTION)}
+
+            ${block(QUESTIONS_DESCRIPTION)}
 
             Features:
             - Automatically stages and commits changes with agent identity unless --no-commit is used
@@ -45104,9 +45763,11 @@ function $initializeCoderRunCommand(program) {
             - Optional post-commit git push with explicit --auto-push opt-in
             - Optional pre-prompt git pull with explicit --auto-pull opt-in
             - Optional --isolate runs every prompt in its own temporary git worktree and merges it back when verified
+            - Saves the run trace of every round into prompts/traces/, named after its prompt file
             - Optional --preserve-logs keeps temp prompt/log artifacts after successful rounds
             - Optional --no-ui keeps plain streaming console output for logging and debugging
-            - Checks that the selected harness is installed and up to date before the first prompt unless --no-harness-update is used
+            - Refuses to start on a nearly full disk and pauses the run when the free disk space becomes critical, unless --no-questions is used
+            - Checks that the selected harness is installed and up to date before the first prompt unless --no-questions is used
             - Offers to add missing project-local ignore rules for the selected harness
             - In interactive mode, checks local and global Promptbook CLI installations and offers to update them
             - Supports GPG signing of commits
@@ -45117,8 +45778,8 @@ function $initializeCoderRunCommand(program) {
         `));
     command.option('--dry-run', 'Print unwritten prompts without executing', false);
     addPromptRunnerSelectionOptions(command);
-    addHarnessUpdateOption(command);
-    command.option('--agent <agent-book-path>', 'Path to a .book file whose compiled system message is prepended to each coding prompt');
+    addQuestionsOption(command);
+    addCoderAgentOption(command);
     command.option('--context <context-or-file>', 'Append extra instructions either inline or from a file path relative to the current project');
     command.option('--test <test-command...>', 'Run a verification command after each prompt; quote it when the command itself contains top-level flags');
     command.addOption(new Option('--test-before <mode>', `Run tests before coding: ${TEST_BEFORE_MODE_VALUES.join(', ')} (defaults to no; uses npm test when --test is omitted)`)
@@ -45131,9 +45792,7 @@ function $initializeCoderRunCommand(program) {
             A verified task is merged back into the branch the coder runs on and the worktree is deleted.
             A task that cannot be merged is marked as failed and its worktree is kept for a manual merge.
         `), false);
-    command.option('--priority <minimum-priority>', 'Alias for --min-priority; filter prompts by minimum priority level', createNonNegativeIntegerOptionParser('--priority'));
-    command.option('--min-priority <minimum-priority>', 'Filter prompts by minimum priority level', createNonNegativeIntegerOptionParser('--min-priority'));
-    command.option('--max-priority <maximum-priority>', 'Filter prompts by maximum priority level', createNonNegativeIntegerOptionParser('--max-priority'));
+    addPromptPriorityOptions(command);
     command.option('--limit <run-count>', 'Stop after processing this many prompt runs', createPositiveIntegerOptionParser('--limit'));
     command.option('--wait-after-prompt <duration>', spaceTrim$1(`
             Wait this long after each prompt has been implemented, verified and committed before starting the next prompt.
@@ -45159,7 +45818,7 @@ function $initializeCoderRunCommand(program) {
         const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
             isAgentRequired: !dryRun,
         });
-        const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
+        const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
         // [1] Parse the wait options and --no-auto:
         //   default: run automatically through the queue (no waiting between prompts)
         //   --no-auto: wait for user confirmation before each prompt (interactive mode)
@@ -45167,11 +45826,15 @@ function $initializeCoderRunCommand(program) {
         //   --wait-between-prompts: pace from start of one prompt to start of next
         //   --wait-after-error: wait before retrying after an error (default 10m)
         const waitForUser = !auto;
-        if (await $ensurePromptbookCliInstallations()) {
+        assertUserConfirmationIsAllowed({ ...questionsOptions, isWaitingForUser: waitForUser });
+        // Note: Checked before anything is installed or written, because installing a harness, updating the
+        //       Promptbook CLI and coding itself all need the disk space which is missing
+        await $assertSufficientFreeDiskSpace(process.cwd());
+        if (await $ensurePromptbookCliInstallations(questionsOptions)) {
             return process.exit(0);
         }
-        await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
-        await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
+        await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
+        await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName, questionsOptions);
         const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
         const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
         const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS$1);
@@ -45204,6 +45867,7 @@ function $initializeCoderRunCommand(program) {
             allowDestructiveAutoMigrate,
             autoPush: runnerOptions.autoPush,
             autoPull: runnerOptions.autoPull,
+            isAskingQuestionsEnabled: questionsOptions.isAskingQuestionsEnabled,
         };
         // Note: Import the function dynamically to avoid loading heavy dependencies until needed
         const { runCodexPrompts } = await Promise.resolve().then(function () { return runCodexPrompts$1; });
@@ -45213,8 +45877,7 @@ function $initializeCoderRunCommand(program) {
         }
         catch (error) {
             assertsError(error);
-            console.error(colors.bgRed(`${error.name}`));
-            console.error(colors.red(error.stack || error.message));
+            printCoderRunFailure(error);
             return process.exit(1);
         }
         return process.exit(0);
@@ -45258,35 +45921,36 @@ const DEFAULT_CODER_SERVER_PORT = '4441';
  */
 function $initializeCoderServerCommand(program) {
     const command = program.command('server');
-    command.description(spaceTrim$1(`
-            Start a coder server that watches for prompts and serves a kanban web UI
+    command.description(spaceTrim$1((block) => `
+                Start a coder server that watches for prompts and serves a kanban web UI
 
-            ${PROMPT_RUNNER_DESCRIPTION}
+                ${block(PROMPT_RUNNER_DESCRIPTION)}
 
-            Features:
-            - Runs the same prompt processing as \`ptbk coder run\`
-            - Checks that the selected harness is installed and up to date on startup unless --no-harness-update is used
-            - Offers to add missing project-local ignore rules for the selected harness
-            - Does not exit when all prompts are done; polls for new prompt files instead
-            - Serves a kanban board at http://localhost:<port> for visual progress tracking
-            - Allows editing prompt files directly from the browser (Trello-style)
-            - Play / pause button in the browser stays in sync with the CLI pause state
-            - Terminal controls match \`ptbk coder run\`: P pause/resume, S skip waiting, X end after current prompt
-        `));
+                ${block(QUESTIONS_DESCRIPTION)}
+
+                Features:
+                - Runs the same prompt processing as \`ptbk coder run\`
+                - Refuses to start on a nearly full disk and pauses the run when the free disk space becomes critical, unless --no-questions is used
+                - Checks that the selected harness is installed and up to date on startup unless --no-questions is used
+                - Offers to add missing project-local ignore rules for the selected harness
+                - Does not exit when all prompts are done; polls for new prompt files instead
+                - Serves a kanban board at http://localhost:<port> for visual progress tracking
+                - Allows editing prompt files directly from the browser (Trello-style)
+                - Play / pause button in the browser stays in sync with the CLI pause state
+                - Terminal controls match \`ptbk coder run\`: P pause/resume, S skip waiting, X end after current prompt
+            `));
     command.addOption(new Option('--port <port>', 'Port to start the coder server on')
         .env('PTBK_CODER_SERVER_PORT')
         .default(DEFAULT_CODER_SERVER_PORT));
     command.option('--dry-run', 'Print unwritten prompts without executing', false);
     addPromptRunnerSelectionOptions(command);
-    addHarnessUpdateOption(command);
-    command.option('--agent <agent-book-path>', 'Path to a .book file whose compiled system message is prepended to each coding prompt');
+    addQuestionsOption(command);
+    addCoderAgentOption(command);
     command.option('--context <context-or-file>', 'Append extra instructions either inline or from a file path relative to the current project');
     command.option('--test <test-command...>', 'Run a verification command after each prompt; quote it when the command itself contains top-level flags');
     command.option('--preserve-logs', 'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics', false);
     addPromptRunnerExecutionOptions(command);
-    command.option('--priority <minimum-priority>', 'Alias for --min-priority; filter prompts by minimum priority level', createNonNegativeIntegerOptionParser('--priority'));
-    command.option('--min-priority <minimum-priority>', 'Filter prompts by minimum priority level', createNonNegativeIntegerOptionParser('--min-priority'));
-    command.option('--max-priority <maximum-priority>', 'Filter prompts by maximum priority level', createNonNegativeIntegerOptionParser('--max-priority'));
+    addPromptPriorityOptions(command);
     command.option('--wait-after-prompt <duration>', spaceTrim$1(`
             Wait this long after each prompt has been implemented, verified and committed before starting the next prompt.
             Accepts durations like 1h, 30m, 5s. Defaults to 0 (no wait).
@@ -45310,11 +45974,15 @@ function $initializeCoderServerCommand(program) {
         const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
             isAgentRequired: !dryRun,
         });
-        const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
-        await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
-        await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
+        const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
         // [1] Parse the wait options and --no-auto (same logic as `coder run`)
         const waitForUser = !auto;
+        assertUserConfirmationIsAllowed({ ...questionsOptions, isWaitingForUser: waitForUser });
+        // Note: Checked before anything is installed or written, because installing a harness and coding
+        //       itself both need the disk space which is missing
+        await $assertSufficientFreeDiskSpace(process.cwd());
+        await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
+        await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName, questionsOptions);
         const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
         const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
         const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS$1);
@@ -45344,6 +46012,7 @@ function $initializeCoderServerCommand(program) {
             allowDestructiveAutoMigrate,
             autoPush: runnerOptions.autoPush,
             autoPull: runnerOptions.autoPull,
+            isAskingQuestionsEnabled: questionsOptions.isAskingQuestionsEnabled,
         };
         // Note: Import dynamically to avoid loading heavy dependencies until needed
         const { runCodexPromptsServer } = await Promise.resolve().then(function () { return runCodexPromptsServer$1; });
@@ -45352,8 +46021,7 @@ function $initializeCoderServerCommand(program) {
         }
         catch (error) {
             assertsError(error);
-            console.error(colors.bgRed(`${error.name}`));
-            console.error(colors.red(error.stack || error.message));
+            printCoderRunFailure(error);
             return process.exit(1);
         }
         return process.exit(0);
@@ -45501,6 +46169,7 @@ function collectStringOption(value, previousValues) {
  * - add: Add one ready-to-run prompt file to the queue
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
+ * - list: List ready prompts in priority order without running them
  * - run: Run coding prompts with AI agents
  * - ping: Test one harness and model with a tiny dummy prompt
  * - verify: Verify completed prompts
@@ -45521,6 +46190,7 @@ function $initializeCoderCommand(program) {
             - generate-boilerplates: Generate prompt boilerplate files
             - find-refactor-candidates: Find files that need refactoring
             - find-unwritten: List prompt sections that still need to be authored
+            - list: List ready prompts in priority order without running them
             - run: Run coding prompts with AI agents
             - ping: Test the connection, response time and quota of one harness and model
             - server: Start a long-running coder server with a kanban web UI
@@ -45533,17 +46203,14 @@ function $initializeCoderCommand(program) {
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
     $initializeCoderFindUnwrittenCommand(coderCommand);
+    $initializeCoderListCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
     $initializeCoderPingCommand(coderCommand);
     $initializeCoderServerCommand(coderCommand);
     $initializeCoderVerifyCommand(coderCommand);
     $initializeCoderFindFreshEmojiTagCommand(coderCommand);
     // If no subcommand is provided, show help
-    coderCommand.action(() => {
-        console.info(colors.yellow('Please specify a subcommand.'));
-        console.info('');
-        coderCommand.help();
-    });
+    $requireCliSubcommand(coderCommand);
 }
 // Note: [🟡] Code for CLI command [coder](src/cli/cli-commands/coder.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
@@ -56133,7 +56800,9 @@ function shouldRunInteractiveChatbot(options) {
  * @private internal function of `promptbookCli`
  */
 function $initializeRunCommand(program) {
-    const runCommand = program.command('run', { isDefault: true });
+    // Note: `run` is deprecated, so it is intentionally NOT the default command of `ptbk`
+    //       and it must be asked for explicitly
+    const runCommand = program.command('run');
     configureRunCommand(runCommand);
     runCommand.action(handleActionErrors((pipelineSource, cliOptions) => runCommandAction(pipelineSource, cliOptions)));
 }
@@ -57972,9 +58641,24 @@ function $addGlobalOptionsToCommand(command) {
     command.option('--remote-server-url <url>', `URL of remote server to use when `, DEFAULT_REMOTE_SERVER_URL);
 }
 
+/**
+ * Keeps one already registered CLI command out of the help of its parent command while the command itself stays
+ * fully usable - it can still be run, it still has its own help and it is still reachable through `ptbk help <command>`.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it changes how the CLI renders its help
+ *
+ * @private utility of CLI
+ */
+function $hideCliCommandFromHelp(command) {
+    command._hidden = true;
+}
+
 /**
  * Marks one CLI command as deprecated while keeping it available for existing callers.
  *
+ * Deprecated commands are not advertised anymore - they are hidden from the list of commands in the help of their
+ * parent command, they warn when they are used and they explain the deprecation in their own help.
+ *
  * @private utility of CLI
  */
 function $deprecateCliCommand(command, deprecationMessage) {
@@ -57986,6 +58670,7 @@ function $deprecateCliCommand(command, deprecationMessage) {
     command.hook('preAction', () => {
         console.warn(colors.yellow(createDeprecatedCliCommandWarning(command, deprecationMessage)));
     });
+    $hideCliCommandFromHelp(command);
 }
 /**
  * Creates the runtime warning printed before a deprecated CLI command action starts.
@@ -58053,10 +58738,17 @@ async function promptbookCli() {
     program.version(PROMPTBOOK_ENGINE_VERSION);
     program.description(CLAIM);
     // Note: These options are valid for all commands
+    // Note: Commands are listed in the help in the order they are registered,
+    //       `coder` is the most used one so it goes first and the deprecated ones,
+    //       which `$deprecateTopLevelCommands` hides from the help entirely, go last
+    $initializeCoderCommand(program);
+    $initializeAgentCommand(program);
+    $initializeAgentFolderCommand(program);
+    $initializeAgentsServerCommand(program);
     $initializeAboutCommand(program);
+    $initializeHelloCommand(program);
     $initializeRunCommand(program);
     $initializeLoginCommand(program);
-    $initializeHelloCommand(program);
     $initializeMakeCommand(program);
     $initializePrettifyCommand(program);
     $initializeTestCommand(program);
@@ -58064,16 +58756,13 @@ async function promptbookCli() {
     $initializeListScrapersCommand(program);
     $initializeStartAgentsServerCommand(program);
     $initializeStartPipelinesServerCommand(program);
-    $initializeAgentCommand(program);
-    $initializeAgentFolderCommand(program);
-    $initializeAgentsServerCommand(program);
-    $initializeCoderCommand(program);
     $deprecateTopLevelCommands(program);
     // TODO: [🧠] Should it be here or not> $addGlobalOptionsToCommand(program);
     program.commands.forEach($addGlobalOptionsToCommand);
+    // Note: There is no default command, so `ptbk` without a subcommand asks for one
+    //       instead of running the deprecated `ptbk run`
     if (commandLineArguments.length === 0) {
-        program.outputHelp();
-        return process.exit(0);
+        return $reportMissingCliSubcommand(program);
     }
     program.parse(process.argv);
 }
@@ -58087,7 +58776,7 @@ function isTopLevelVersionRequested(commandLineArguments) {
     return firstCommandLineArgument !== undefined && VERSION_OPTION_ARGUMENTS.has(firstCommandLineArgument);
 }
 /**
- * Adds one deprecation notice to each configured top-level legacy command.
+ * Marks each configured top-level legacy command as deprecated, which keeps it usable but takes it out of the help.
  */
 function $deprecateTopLevelCommands(program) {
     for (const command of program.commands) {
@@ -58098,7 +58787,6 @@ function $deprecateTopLevelCommands(program) {
     }
 }
 // Note: [🟡] Code for CLI program [promptbookCli](src/cli/promptbookCli.ts) should never be published outside of `@promptbook/cli`
-// TODO: [🧠] Maybe `run` command the default, instead of `ptbk run ./foo.book` -> `ptbk ./foo.book`
 // TODO: [🥠] Do not export, its just for CLI script
 // TODO: [🕌] When more functionalities, rename
 // Note: 11:11
@@ -59210,7 +59898,9 @@ const VERCEL_PROVIDER_PROFILE = {
  */
 function createExecutionToolsFromVercelProvider(options) {
     let { title, description } = options;
-    const { vercelProvider, availableModels, userId, additionalChatSettings = {} } = options;
+    const { vercelProvider, availableModels, additionalChatSettings = {} } = options;
+    // <- Note: `userId` is not forwarded, because Vercel AI SDK moved provider-specific settings like `user` from
+    //          `vercelProvider.chat(modelName, settings)` into `providerOptions` which are keyed by the provider
     if (!/Vercel/i.test(title)) {
         title = `${title} (through Vercel)`;
         // <- TODO: [🧈] Maybe standartize the suffix
@@ -59251,10 +59941,7 @@ function createExecutionToolsFromVercelProvider(options) {
 
                     `));
             }
-            const model = await vercelProvider.chat(modelName, {
-                user: (userId === null || userId === void 0 ? void 0 : userId.toString()) || undefined,
-                ...additionalChatSettings,
-            });
+            const model = await vercelProvider.chat(modelName);
             const rawPromptContent = templateParameters(content, { ...parameters, modelName });
             // Support for passing a chat thread (multi-message conversation)
             let promptMessages;
@@ -59292,14 +59979,9 @@ function createExecutionToolsFromVercelProvider(options) {
             }
             const rawRequest = {
                 // <- TODO: [☂]
-                inputFormat: 'messages',
-                mode: {
-                    type: 'regular',
-                    tools: [
-                    /* <- TODO: Pass the tools */
-                    ],
-                },
                 prompt: promptMessages,
+                // <- TODO: Pass the tools via `tools`
+                ...additionalChatSettings,
             };
             const start = $getCurrentDate();
             if (options.isVerbose) {
@@ -59316,28 +59998,31 @@ function createExecutionToolsFromVercelProvider(options) {
             if (options.isVerbose) {
                 console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
             }
-            if (rawResponse.text === undefined) {
+            // Note: Vercel AI SDK returns ordered content parts, the chat message is made only of the text parts
+            const responseTextParts = rawResponse.content.flatMap((contentPart) => contentPart.type === 'text' ? [contentPart.text] : []);
+            if (responseTextParts.length === 0) {
                 throw new PipelineExecutionError('No response message');
             }
+            const responseText = responseTextParts.join('');
             const complete = $getCurrentDate();
             const duration = uncertainNumber((new Date(complete).getTime() - new Date(start).getTime()) / 1000);
             const usage = {
                 price: UNCERTAIN_ZERO_VALUE,
                 duration,
                 input: {
-                    tokensCount: uncertainNumber(rawResponse.usage.promptTokens),
+                    tokensCount: uncertainNumber(rawResponse.usage.inputTokens),
                     ...computeUsageCounts(rawPromptContent),
                 },
                 output: {
-                    tokensCount: uncertainNumber(rawResponse.usage.completionTokens),
-                    ...computeUsageCounts(rawResponse.text),
+                    tokensCount: uncertainNumber(rawResponse.usage.outputTokens),
+                    ...computeUsageCounts(responseText),
                 },
             };
             return exportJson({
                 name: 'promptResult',
                 message: `Result of \`createExecutionToolsFromVercelProvider.callChatModel\``,
                 value: {
-                    content: rawResponse.text,
+                    content: responseText,
                     modelName,
                     timing: {
                         start,
@@ -74642,13 +75327,15 @@ function findFirstNonEmptyLineIndex(lines, startLine, endLine) {
 }
 
 /**
- * Checks whether a prompt is unrestricted or matches the selected harness/model.
+ * Checks whether a prompt is unrestricted or matches the selected harness, model or Book agent.
  *
- * A prompt status line can contain one or more backtick-delimited model or harness
- * names. Matching is intentionally based on normalized substrings so a token such as
- * `gpt` selects any `gpt-*` model and `opus` selects a `claude-opus-*` model.
+ * A prompt status line can contain one or more backtick-delimited model, harness or agent
+ * references. Matching is intentionally based on normalized substrings so a token such as
+ * `gpt` selects any `gpt-*` model, `developer` selects an agent Book named `developer.book`,
+ * and `opus` selects a `claude-opus-*` model.
  */
 function isPromptCompatibleWithRunner(file, section, promptRunnerIdentity) {
+    var _a;
     if (promptRunnerIdentity === undefined) {
         return true;
     }
@@ -74657,7 +75344,11 @@ function isPromptCompatibleWithRunner(file, section, promptRunnerIdentity) {
     if (requiredRunnerTokens.length === 0) {
         return true;
     }
-    const normalizedRunnerNames = [promptRunnerIdentity.harnessName, promptRunnerIdentity.modelName]
+    const normalizedRunnerNames = [
+        promptRunnerIdentity.harnessName,
+        promptRunnerIdentity.modelName,
+        ...((_a = promptRunnerIdentity.agentReferences) !== null && _a !== void 0 ? _a : []),
+    ]
         .filter((name) => name !== undefined && name.trim() !== '')
         .map((name) => normalizeToKebabCase(name))
         .filter((name) => name !== '');
@@ -74668,7 +75359,7 @@ function isPromptCompatibleWithRunner(file, section, promptRunnerIdentity) {
     });
 }
 /**
- * Extracts model and harness tokens from a prompt status line.
+ * Extracts model, harness and Book-agent tokens from a prompt status line.
  */
 function extractPromptRunnerTokens(statusLine) {
     return Array.from(statusLine.matchAll(/`([^`]+)`/gu))
@@ -74683,7 +75374,7 @@ function extractPromptRunnerTokens(statusLine) {
  *
  * @private internal constant of `parsePromptFile`
  */
-const PROMPT_STATUS_MARKER_PATTERN = /^\[(?: |-|[xX]|\^|!)\]/u;
+const PROMPT_STATUS_LINE_PATTERN = /^\[(?<marker> |-|\.|[xX]|\^|!)\](?<details>.*)$/u;
 /**
  * Parses a prompt markdown file into sections and metadata.
  */
@@ -74707,7 +75398,7 @@ function parsePromptFile(filePath, content) {
         if (firstNonEmptyLine !== undefined) {
             const statusLine = (lines[firstNonEmptyLine] || '').trim();
             const parsedStatus = parseStatusLine(statusLine);
-            const status = (_a = parsedStatus === null || parsedStatus === void 0 ? void 0 : parsedStatus.status) !== null && _a !== void 0 ? _a : (hasPromptStatusMarker(statusLine) ? 'not-ready' : 'todo');
+            const status = (_a = parsedStatus === null || parsedStatus === void 0 ? void 0 : parsedStatus.status) !== null && _a !== void 0 ? _a : (PROMPT_STATUS_LINE_PATTERN.test(statusLine) ? 'not-ready' : 'todo');
             const priority = (_b = parsedStatus === null || parsedStatus === void 0 ? void 0 : parsedStatus.priority) !== null && _b !== void 0 ? _b : 0;
             sections.push({
                 index,
@@ -74735,51 +75426,47 @@ function parsePromptFile(filePath, content) {
  * For [x] done, [!] failed and [^] in-progress prompts, allow metadata after the status marker.
  */
 function parseStatusLine(line) {
-    var _a, _b, _c, _d;
-    // For done prompts [x], allow any content after (for cost/time metadata)
-    const doneMatch = line.match(/^\[(?<status>[xX])\]/);
-    if (doneMatch) {
+    var _a, _b, _c, _d, _e;
+    const statusLineMatch = line.match(PROMPT_STATUS_LINE_PATTERN);
+    const marker = (_a = statusLineMatch === null || statusLineMatch === void 0 ? void 0 : statusLineMatch.groups) === null || _a === void 0 ? void 0 : _a.marker;
+    const details = (_c = (_b = statusLineMatch === null || statusLineMatch === void 0 ? void 0 : statusLineMatch.groups) === null || _b === void 0 ? void 0 : _b.details) !== null && _c !== void 0 ? _c : '';
+    if (marker === 'x' || marker === 'X') {
+        // For done prompts [x], allow any content after (for cost/time metadata).
         return { status: 'done', priority: 0 };
     }
-    // For failed prompts [!], allow any content after (for failure metadata)
-    const failedMatch = line.match(/^\[(?<status>!)\]/);
-    if (failedMatch) {
+    if (marker === '!') {
+        // For failed prompts [!], allow any content after (for failure metadata).
         return { status: 'failed', priority: 0 };
     }
-    // For in-progress prompts [^], allow any content after (for the steps recorded so far)
-    const inProgressMatch = line.match(/^\[(?<status>\^)\]/);
-    if (inProgressMatch) {
+    if (marker === '^') {
+        // For in-progress prompts [^], allow any content after (for the steps recorded so far).
         return { status: 'in-progress', priority: 0 };
     }
-    // For not-ready [-], keep the historical clean-line syntax.
-    if (/^\[-\]\s*!*\s*$/u.test(line)) {
+    // Treat [.] as the alternative spelling of not-ready [-], preserving the historical clean-line syntax.
+    if ((marker === '-' || marker === '.') && /^[!\s]*$/u.test(details)) {
         return { status: 'not-ready', priority: 0 };
     }
-    // Todo [ ] may contain backtick-delimited model/harness tokens and priority markers
-    // before or after those tokens. Other trailing text remains an invalid status line.
-    const todoMatch = line.match(/^\[ \](?<details>.*)$/u);
-    if (!todoMatch) {
+    if (marker !== ' ') {
         return undefined;
     }
-    const details = (_b = (_a = todoMatch.groups) === null || _a === void 0 ? void 0 : _a.details) !== null && _b !== void 0 ? _b : '';
+    // Todo [ ] may contain backtick-delimited model/harness tokens and priority markers
+    // before or after those tokens. Other trailing text remains an invalid status line.
     const isPriorityOnly = /^[!\s]*$/u.test(details);
     const hasPromptRunnerTokens = extractPromptRunnerTokens(line).length > 0;
     if (details.trim() !== '' && !isPriorityOnly && !hasPromptRunnerTokens) {
         return undefined;
     }
-    return { status: 'todo', priority: (_d = (_c = details.match(/!/gu)) === null || _c === void 0 ? void 0 : _c.length) !== null && _d !== void 0 ? _d : 0 };
+    return { status: 'todo', priority: (_e = (_d = details.match(/!/gu)) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0 };
 }
+
 /**
- * Checks whether a line starts with one of the supported prompt status markers.
+ * HTML comment which excludes a Markdown file from all `ptbk coder` queues.
  *
- * @private internal utility of `parsePromptFile`
+ * @private internal constant of `loadPromptFiles`
  */
-function hasPromptStatusMarker(line) {
-    return PROMPT_STATUS_MARKER_PATTERN.test(line);
-}
-
+const PTBK_CODER_IGNORE_MARKER = '<!--ptbk-coder-ignore-->';
 /**
- * Loads and parses prompt files from the prompts directory.
+ * Loads and parses prompt files from the prompts directory, excluding files marked for `ptbk coder` to ignore.
  */
 async function loadPromptFiles(promptsDir) {
     const entries = await readdir(promptsDir, { withFileTypes: true });
@@ -74790,6 +75477,9 @@ async function loadPromptFiles(promptsDir) {
     const promptFiles = [];
     for (const filePath of files) {
         const content = await readFile(filePath, 'utf-8');
+        if (content.includes(PTBK_CODER_IGNORE_MARKER)) {
+            continue;
+        }
         promptFiles.push(parsePromptFile(filePath, content));
     }
     return promptFiles;
@@ -74900,22 +75590,158 @@ var findUnwrittenPrompts$1 = /*#__PURE__*/Object.freeze({
 });
 
 /**
- * Formats one unknown error-like value into its readable message without the stack trace.
+ * Reads an optional agent `.book` file and prepares the references that route prompts to it.
  *
- * Use this instead of `formatUnknownErrorDetails` whenever the text is shown to the user, for example
- * inside a branded error, where the stack of the wrapped error would only bury the actual cause.
+ * Returns `undefined` when no agent path is provided.
  */
-function formatUnknownErrorMessage(error) {
-    if (error instanceof Error) {
-        return error.message;
+async function resolveCoderAgentBook(agentBookReference, currentWorkingDirectory) {
+    const normalizedAgentBookReference = agentBookReference === null || agentBookReference === void 0 ? void 0 : agentBookReference.trim();
+    if (!normalizedAgentBookReference) {
+        return undefined;
     }
-    if (typeof error === 'string') {
-        return error;
+    const resolvedAgentBookPath = resolve(currentWorkingDirectory, normalizedAgentBookReference);
+    const agentSource = (await readFile(resolvedAgentBookPath, 'utf-8').catch((error) => {
+        if (error.code === 'ENOENT' || error.code === 'EISDIR') {
+            throw new NotFoundError(spaceTrim(`
+                    Agent book \`${normalizedAgentBookReference}\` was not found or is not a file.
+
+                    Pass a path to a \`.book\` file in \`--agent\`.
+                `));
+        }
+        throw error;
+    }));
+    return {
+        agentSource,
+        agentReferences: createCoderAgentReferences({
+            agentBookReference: normalizedAgentBookReference,
+            resolvedAgentBookPath,
+            currentWorkingDirectory,
+            agentSource,
+        }),
+    };
+}
+/**
+ * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
+ *
+ * Returns `undefined` when no agent path is provided.
+ */
+async function resolveCoderAgent(agentBookReference, currentWorkingDirectory) {
+    const resolvedAgentBook = await resolveCoderAgentBook(agentBookReference, currentWorkingDirectory);
+    if (resolvedAgentBook === undefined) {
+        return undefined;
     }
-    const serializedError = JSON.stringify(error, null, 2);
-    return serializedError !== null && serializedError !== void 0 ? serializedError : String(error);
+    return {
+        ...resolvedAgentBook,
+        systemMessage: await createAgentRunnerSystemMessage(resolvedAgentBook.agentSource),
+    };
+}
+/**
+ * Creates the path and Book-title aliases which a prompt can use to target one selected agent.
+ *
+ * @private internal utility of `resolveCoderAgentBook`
+ */
+function createCoderAgentReferences(options) {
+    const relativeAgentBookPath = relative(options.currentWorkingDirectory, options.resolvedAgentBookPath).replaceAll('\\', '/');
+    const agentBookFileName = basename(options.resolvedAgentBookPath);
+    const agentBookName = basename(options.resolvedAgentBookPath, extname(options.resolvedAgentBookPath));
+    const agentNameFromBook = parseAgentSource(options.agentSource).agentName;
+    return Array.from(new Set([
+        options.agentBookReference,
+        relativeAgentBookPath,
+        agentBookFileName,
+        agentBookName,
+        agentNameFromBook,
+    ].filter((agentReference) => agentReference.trim() !== '')));
+}
+
+var resolveCoderAgent$1 = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    resolveCoderAgentBook: resolveCoderAgentBook,
+    resolveCoderAgent: resolveCoderAgent
+});
+
+/**
+ * Lists todo prompts that are ready to run (no authoring placeholders).
+ */
+function listRunnablePrompts(files, priorityFilter = {}, promptRunnerIdentity) {
+    return listTodoPrompts(files).filter((prompt) => !isPromptToBeWritten(prompt.file, prompt.section) &&
+        isPromptInPriorityFilter(prompt.section, priorityFilter) &&
+        isPromptCompatibleWithRunner(prompt.file, prompt.section, promptRunnerIdentity));
+}
+
+/**
+ * Lists upcoming tasks that are ready to run (no authoring placeholders).
+ */
+function listUpcomingTasks(files, priorityFilter = {}, promptRunnerIdentity) {
+    return listRunnablePrompts(files, priorityFilter, promptRunnerIdentity).map(({ file, section }) => ({
+        label: buildPromptLabelForDisplay(file, section),
+        summary: buildPromptSummary(file, section),
+        priority: section.priority,
+    }));
+}
+
+/**
+ * Groups upcoming tasks by priority, high to low.
+ */
+function groupUpcomingTasksByPriority(tasks) {
+    const grouped = new Map();
+    for (const task of tasks) {
+        const group = grouped.get(task.priority);
+        if (group) {
+            group.push(task);
+        }
+        else {
+            grouped.set(task.priority, [task]);
+        }
+    }
+    return Array.from(grouped.entries())
+        .sort((a, b) => b[0] - a[0])
+        .map(([priority, groupedTasks]) => ({ priority, tasks: groupedTasks }));
+}
+
+/**
+ * Prints upcoming tasks grouped by priority.
+ */
+function printUpcomingTasks(tasks) {
+    if (tasks.length === 0) {
+        console.info(colors.green('No upcoming tasks.'));
+        return;
+    }
+    console.info(colors.cyan('Upcoming tasks (grouped by priority):'));
+    for (const group of groupUpcomingTasksByPriority(tasks)) {
+        console.info(colors.cyan(`Priority ${group.priority}:`));
+        for (const [index, task] of group.tasks.entries()) {
+            const summary = task.summary ? ` - ${task.summary}` : '';
+            console.info(` ${index + 1}. ${task.label}${summary}`);
+        }
+    }
+}
+
+/**
+ * Directory containing the prompt queue of the current project.
+ *
+ * @private internal constant of `listCoderPrompts`
+ */
+const PROMPTS_DIRECTORY_PATH = join(process.cwd(), 'prompts');
+/**
+ * Lists ready, fully authored coding prompts in descending priority groups without starting a coding harness.
+ *
+ * @returns The number of prompts printed.
+ * @public exported from `@promptbook/cli`
+ */
+async function listCoderPrompts(options = {}) {
+    const priorityFilter = normalizePriorityFilter(options);
+    const promptFiles = await loadPromptFiles(PROMPTS_DIRECTORY_PATH);
+    const upcomingTasks = listUpcomingTasks(promptFiles, priorityFilter, options.promptRunnerIdentity);
+    printUpcomingTasks(upcomingTasks);
+    return upcomingTasks.length;
 }
 
+var listCoderPrompts$1 = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    listCoderPrompts: listCoderPrompts
+});
+
 /**
  * Builds a normalized temporary shell script path for prompt runners.
  */
@@ -75214,7 +76040,7 @@ const DEFAULT_WAIT_AFTER_ERROR_MS = 10 * 60 * 1000;
 /**
  * CLI usage text for this script.
  */
-const USAGE = 'Usage: run-codex-prompts [--dry-run] [--harness <harness-name>] [--model <model>] [--context <context-or-file>] [--test <test-command...>] [--test-before <no|yes-and-fail|yes-and-fix>] [--preserve-logs] [--isolate] [--no-ui] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--min-priority <minimum-priority>] [--max-priority <maximum-priority>] [--limit <run-count>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--wait-after-prompt <duration>] [--wait-between-prompts <duration>] [--wait-after-error <duration>] [--no-auto] [--no-commit] [--git-changes <fail|ignore|continue>] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
+const USAGE = 'Usage: run-codex-prompts [--dry-run] [--harness <harness-name>] [--model <model>] [--agent <agent-book-path>] [--context <context-or-file>] [--test <test-command...>] [--test-before <no|yes-and-fail|yes-and-fix>] [--preserve-logs] [--isolate] [--no-ui] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--min-priority <minimum-priority>] [--max-priority <maximum-priority>] [--limit <run-count>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--wait-after-prompt <duration>] [--wait-between-prompts <duration>] [--wait-after-error <duration>] [--no-auto] [--no-commit] [--git-changes <fail|ignore|continue>] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
 /**
  * Top-level flags supported by this command.
  */
@@ -75222,6 +76048,7 @@ const KNOWN_OPTION_FLAGS = new Set([
     '--dry-run',
     '--harness',
     '--model',
+    '--agent',
     '--context',
     '--test',
     '--test-before',
@@ -75260,6 +76087,7 @@ function parseRunOptions(args) {
         }
     }
     const model = readOptionValue(args, '--model');
+    const agent = readOptionValue(args, '--agent');
     const context = readOptionValue(args, '--context');
     const hasTestCommandFlag = args.includes('--test');
     const testCommand = readVariadicOptionValue(args, '--test');
@@ -75336,6 +76164,7 @@ function parseRunOptions(args) {
         noUi,
         agentName,
         model,
+        agent,
         context,
         testCommand,
         testBefore,
@@ -75770,30 +76599,43 @@ async function recordPromptDurationSample(key, promptDurationMs) {
 // Note: [🟡] Code in this file is only used from `@promptbook/cli` orchestration scripts and is not shipped to other consumers.
 
 /**
- * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
+ * Creates the guard which watches the free disk space while one `ptbk coder` run is in progress.
  *
- * Returns `undefined` when no agent path is provided.
+ * The guard runs at every pause checkpoint of the run. When the disk became critically full it reports the
+ * warning and requests a pause, so the run stops at that checkpoint instead of failing in the middle of a
+ * coding round, and continues once the user has freed some space and pressed `P`.
+ *
+ * @private internal utility of `ptbk coder` free disk space handling
  */
-async function resolveCoderAgent(agentPath, currentWorkingDirectory) {
-    if (!agentPath) {
-        return undefined;
-    }
-    const resolvedAgentPath = resolve(currentWorkingDirectory, agentPath);
-    const agentSource = await readFile(resolvedAgentPath, 'utf-8').catch((error) => {
-        if (error.code === 'ENOENT' || error.code === 'EISDIR') {
-            throw new NotFoundError(spaceTrim(`
-                    Agent book \`${agentPath}\` was not found or is not a file.
+function createFreeDiskSpaceGuard(options) {
+    const { inspectedPath, isAskingQuestionsEnabled } = options;
+    let lastMeasurementTimeMs;
+    return async () => {
+        if (lastMeasurementTimeMs !== undefined &&
+            Date.now() - lastMeasurementTimeMs < FREE_DISK_SPACE_RECHECK_INTERVAL_MS) {
+            return;
+        }
+        lastMeasurementTimeMs = Date.now();
+        const freeDiskSpaceStatus = await $readFreeDiskSpaceStatus(inspectedPath);
+        if (freeDiskSpaceStatus === null || freeDiskSpaceStatus.level !== 'critical') {
+            return;
+        }
+        console.warn(colors.yellow(spaceTrim$1((block) => `
+                        The disk is running out of space while \`ptbk coder\` is working.
 
-                    Pass a path to a \`.book\` file in \`--agent\`.
-                `));
+                        ${block(formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus))}
+                        - Press \`P\` to continue once the disk space is freed, or start the run with \`--no-questions\` to never pause on a full disk.
+                    `)));
+        if (!isAskingQuestionsEnabled) {
+            // Note: `--no-questions` forbids stopping and waiting for somebody who would free the disk space,
+            //       so the run keeps going and the warning above is the only thing which is reported
+            return;
         }
-        throw error;
-    });
-    return {
-        agentSource: agentSource,
-        systemMessage: await createAgentRunnerSystemMessage(agentSource),
+        announcePauseTargetLabel(`continuing with only ${formatFreeDiskSpaceBytes(freeDiskSpaceStatus.availableBytes)} of free disk space left`);
+        requestPause();
     };
 }
+// Note: [🟡] Code for `ptbk coder` free disk space handling [createFreeDiskSpaceGuard](scripts/run-codex-prompts/common/createFreeDiskSpaceGuard.ts) should never be published outside of `@promptbook/cli`
 
 /**
  * Refresh interval used by the countdown display while waiting.
@@ -77764,6 +78606,169 @@ async function writePromptFile(file) {
     await writeFile(file.path, content, 'utf-8');
 }
 
+/**
+ * Creates a safe markdown fenced code block even when content contains backticks.
+ *
+ * @param content - Raw code content.
+ * @param language - Optional info-string language label.
+ * @returns Fenced code block.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown` and of the `ptbk coder` run traces
+ */
+function getSafeCodeBlock(content, language = 'markdown') {
+    const maxBacktickCount = Math.max(0, ...(content.match(/`+/g) || []).map((match) => match.length));
+    const fence = '`'.repeat(Math.max(3, maxBacktickCount + 1));
+    return `${fence}${language}\n${content}\n${fence}`;
+}
+
+/**
+ * Renders the markdown run trace of one finished or failed prompt round.
+ *
+ * The trace pairs the metadata of the round - which harness, model and thinking level ran it, how long each of
+ * its steps took and what it cost - with the untouched runtime log, so a finished round can still be analyzed
+ * after its temporary artifacts are cleaned up.
+ */
+function buildPromptRunTraceContent(options) {
+    const sections = [
+        buildPromptRunTraceSummarySection(options),
+        buildPromptRunTraceFailureSection(options.outcome),
+        buildPromptRunTraceRuntimeLogSection(options.runtimeLog),
+    ].filter((section) => section !== undefined);
+    return `${sections.join('\n\n')}\n`;
+}
+/**
+ * Renders the heading and the metadata bullet list of one run trace.
+ */
+function buildPromptRunTraceSummarySection(options) {
+    const { file, section, outcome } = options;
+    const runnerSignature = formatRunnerSignature(options.runnerName, options.modelName, options.thinkingLevel);
+    const loginMethodLabel = outcome.kind === 'succeeded' ? formatCodexLoginMethod(outcome.loginMethod) : undefined;
+    const loginMethodSuffix = loginMethodLabel ? ` (${loginMethodLabel})` : '';
+    const detailLines = [
+        `-   **Prompt:** ${buildPromptSummary(file, section)}`,
+        ...buildPromptRunTraceSectionLines(file, section),
+        `-   **Outcome:** ${formatPromptRunTraceOutcomeLabel(outcome)}`,
+        `-   **Runner:** ${runnerSignature}${loginMethodSuffix}`,
+        `-   **Attempts:** ${options.attemptCount}`,
+        ...buildPromptRunTraceStepsLines(outcome),
+        ...buildPromptRunTraceTestCommandLines(options.testCommand),
+        `-   **Started:** ${options.startedDate.toISOString()}`,
+        `-   **Finished:** ${options.finishedDate.toISOString()}`,
+        `-   **Duration:** ${moment.duration(options.finishedDate.diff(options.startedDate)).humanize()}`,
+    ];
+    return spaceTrim$1((block) => `
+            # Run trace of \`${buildPromptLabelForDisplay(file, section)}\`
+
+            ${block(detailLines.join('\n'))}
+        `);
+}
+/**
+ * Renders which section of its prompt file the round implemented.
+ *
+ * A prompt file holding exactly one section says nothing by naming it, exactly like the section suffix of its
+ * generated artifact names, so only a file with more than one section reports the section it traced.
+ */
+function buildPromptRunTraceSectionLines(file, section) {
+    if (file.sections.length <= 1) {
+        return [];
+    }
+    return [`-   **Prompt section:** ${section.index + 1} of ${file.sections.length}`];
+}
+/**
+ * Renders the per-step usage breakdown of a successful round, omitted for a round which never finished one.
+ */
+function buildPromptRunTraceStepsLines(outcome) {
+    if (outcome.kind !== 'succeeded') {
+        return [];
+    }
+    const stepsSummary = formatCoderRunSteps(outcome.steps);
+    if (stepsSummary === '') {
+        return [];
+    }
+    return [`-   **Steps:** ${stepsSummary}`];
+}
+/**
+ * Renders the verification command of the round, omitted when the round ran without one.
+ */
+function buildPromptRunTraceTestCommandLines(testCommand) {
+    if (!testCommand) {
+        return [];
+    }
+    return [`-   **Verification command:** \`${testCommand}\``];
+}
+/**
+ * Renders the failure details of a failed round, omitted for a successful one.
+ */
+function buildPromptRunTraceFailureSection(outcome) {
+    if (outcome.kind !== 'failed') {
+        return undefined;
+    }
+    return `## Failure\n\n${getSafeCodeBlock(formatUnknownErrorDetails(outcome.error), 'text')}`;
+}
+/**
+ * Renders the untouched runtime log of the round, or says that the round produced none.
+ */
+function buildPromptRunTraceRuntimeLogSection(runtimeLog) {
+    if (runtimeLog.trim() === '') {
+        return '## Runtime log\n\n_This round has produced no readable runtime log._';
+    }
+    return `## Runtime log\n\n${getSafeCodeBlock(runtimeLog.replace(/\r\n/gu, '\n').trimEnd(), 'text')}`;
+}
+/**
+ * Formats the outcome of the round as the human-readable label of its trace.
+ */
+function formatPromptRunTraceOutcomeLabel(outcome) {
+    return outcome.kind === 'succeeded' ? 'Succeeded' : 'Failed';
+}
+
+/**
+ * Name of the directory which keeps the run traces inside the prompts directory.
+ */
+const PROMPT_RUN_TRACES_DIRECTORY_NAME = 'traces';
+/**
+ * Builds the path of the run trace which belongs to one prompt section.
+ *
+ * The trace is stored in the `traces` directory of the very same prompts directory the prompt itself lives in,
+ * and it carries the name of its prompt file. A prompt file holding more than one section appends the section
+ * suffix, exactly like the temporary scripts and the isolation worktrees of the same section do.
+ */
+function buildPromptRunTracePath(file, section) {
+    const promptFileBaseName = file.name.replace(/\.[^.]+$/u, '');
+    const traceFileName = `${promptFileBaseName}${buildPromptSectionSuffix(file, section)}.md`;
+    return join(dirname(file.path), PROMPT_RUN_TRACES_DIRECTORY_NAME, traceFileName);
+}
+
+/**
+ * Writes the run trace of one prompt round into the `traces` directory of the prompts directory.
+ *
+ * Returns the path of the written trace so callers can include it in a commit.
+ */
+async function writePromptRunTrace(options) {
+    const { logPath, ...contentOptions } = options;
+    const tracePath = buildPromptRunTracePath(options.file, options.section);
+    const runtimeLog = await readPromptRuntimeLog(logPath);
+    await mkdir(dirname(tracePath), { recursive: true });
+    await writeFile(tracePath, buildPromptRunTraceContent({ ...contentOptions, runtimeLog }), 'utf-8');
+    return tracePath;
+}
+/**
+ * Reads the live runtime log of one round.
+ *
+ * A round which never produced a readable log still gets its trace, because the metadata of the round is worth
+ * keeping on its own - so a missing log is reported as empty instead of failing the round which has just passed.
+ */
+async function readPromptRuntimeLog(logPath) {
+    if (!logPath) {
+        return '';
+    }
+    try {
+        return await readFile(logPath, 'utf-8');
+    }
+    catch (_a) {
+        return '';
+    }
+}
+
 /**
  * Refreshes optional harness subscription usage in the shared coder-run UI state.
  *
@@ -77886,7 +78891,9 @@ async function runPromptRound({ options, runner, runnerMetadata, nextPrompt, pro
             catch (error) {
                 uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
                 lastError = error;
-                if (errorRetryAttempt >= MAX_RETRY_ATTEMPTS_AFTER_ERROR) {
+                // Note: A harness which is not logged in answers every retry the same way, so the user gets
+                //       the sign-in instructions right away instead of after every retry has waited its delay
+                if (error instanceof AuthenticationError || errorRetryAttempt >= MAX_RETRY_ATTEMPTS_AFTER_ERROR) {
                     break;
                 }
                 await waitAfterErrorBeforeRetry({
@@ -77908,6 +78915,7 @@ async function runPromptRound({ options, runner, runnerMetadata, nextPrompt, pro
             attemptCount,
             error: lastError,
             options,
+            logPath,
             roundCommitScope,
             uiHandle,
             waitForRequestedPause,
@@ -78024,6 +79032,17 @@ async function finalizeSuccessfulPromptRound(options) {
     // Note: The prompt status is always written into the original project, an isolated round transports
     //       its own changes back through the merge instead
     await writePromptFile(nextPrompt.file);
+    // Note: Written before the round is committed, so the trace of the round lands in the very same commit
+    //       as the prompt it describes, and before the live runtime log it is built from is deleted
+    await recordPromptRoundTrace({
+        options: runOptions,
+        nextPrompt,
+        runnerMetadata,
+        promptExecutionStartedDate,
+        attemptCount: result.attemptCount,
+        logPath,
+        outcome: { kind: 'succeeded', steps: result.steps, loginMethod: result.loginMethod },
+    });
     await normalizeLineEndingsForCurrentRound(runOptions, roundProjectPath, roundCommitScope);
     await recordPromptDurationInEstimateCache({
         options: runOptions,
@@ -78071,7 +79090,7 @@ async function finalizeSuccessfulPromptRound(options) {
  * Finalizes a failed prompt round, persisting prompt failure metadata before rethrowing.
  */
 async function finalizeFailedPromptRound(options) {
-    const { nextPrompt, runnerMetadata, previousRunnerSignatures, promptExecutionStartedDate, attemptCount, error, options: runOptions, roundCommitScope, uiHandle, waitForRequestedPause, roundProjectPath, } = options;
+    const { nextPrompt, runnerMetadata, previousRunnerSignatures, promptExecutionStartedDate, attemptCount, error, options: runOptions, logPath, roundCommitScope, uiHandle, waitForRequestedPause, roundProjectPath, } = options;
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('error');
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.addError(error instanceof Error ? error.message : String(error));
@@ -78097,8 +79116,42 @@ async function finalizeFailedPromptRound(options) {
         modelName: runnerMetadata.modelName,
         error,
     });
+    // Note: A failed round is exactly the round whose trace is worth reading, so it is written before the live
+    //       runtime log it is built from is deleted
+    await recordPromptRoundTrace({
+        options: runOptions,
+        nextPrompt,
+        runnerMetadata,
+        promptExecutionStartedDate,
+        attemptCount,
+        logPath,
+        outcome: { kind: 'failed', error },
+    });
     await normalizeLineEndingsForCurrentRound(runOptions, roundProjectPath, roundCommitScope);
 }
+/**
+ * Persists the run trace of one prompt round, so the round can still be analyzed after its temporary
+ * artifacts are gone.
+ *
+ * This is the single place where both the successful and the failed round record what they did, which harness,
+ * model and thinking level did it and everything that harness has written while doing it.
+ */
+async function recordPromptRoundTrace(options) {
+    const { options: runOptions, nextPrompt, runnerMetadata, promptExecutionStartedDate, attemptCount, logPath, outcome, } = options;
+    await writePromptRunTrace({
+        file: nextPrompt.file,
+        section: nextPrompt.section,
+        runnerName: runnerMetadata.runnerName,
+        modelName: runnerMetadata.modelName,
+        thinkingLevel: runOptions.thinkingLevel,
+        testCommand: runOptions.testCommand,
+        attemptCount,
+        startedDate: promptExecutionStartedDate,
+        finishedDate: moment(),
+        outcome,
+        logPath,
+    });
+}
 /**
  * Waits for the optional user confirmation immediately before creating the commit.
  */
@@ -78747,7 +79800,13 @@ async function recordIsolationMergeFailure(options, worktree, failureDetails) {
     await commitChanges(buildCoderIsolationMergeFailureCommitMessage(worktree), {
         autoPush: options.options.autoPush,
         projectPath: worktree.projectPath,
-        relevantPaths: [nextPrompt.file.path, errorLogPath].map((path) => toProjectRelativeGitPath(worktree.projectPath, path)),
+        // Note: The round itself has already succeeded, so it has left its run trace in the original project.
+        //       It belongs to this commit, which is the only one this task still gets.
+        relevantPaths: [
+            nextPrompt.file.path,
+            errorLogPath,
+            buildPromptRunTracePath(nextPrompt.file, nextPrompt.section),
+        ].map((path) => toProjectRelativeGitPath(worktree.projectPath, path)),
     });
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.addError(mergeFailureError.message);
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(`Merging \`${worktree.taskName}\` failed, worktree kept for a manual merge`);
@@ -78771,15 +79830,6 @@ function toProjectRelativeGitPath(projectPath, path) {
     return relative(projectPath, path).replace(/\\/gu, '/');
 }
 
-/**
- * Lists todo prompts that are ready to run (no authoring placeholders).
- */
-function listRunnablePrompts(files, priorityFilter = {}, promptRunnerIdentity) {
-    return listTodoPrompts(files).filter((prompt) => !isPromptToBeWritten(prompt.file, prompt.section) &&
-        isPromptInPriorityFilter(prompt.section, priorityFilter) &&
-        isPromptCompatibleWithRunner(prompt.file, prompt.section, promptRunnerIdentity));
-}
-
 /**
  * Selects the next runnable prompt based on priority.
  */
@@ -78793,54 +79843,6 @@ function findNextTodoPrompt(files, priorityFilter = {}, promptRunnerIdentity) {
     return nextPrompt;
 }
 
-/**
- * Lists upcoming tasks that are ready to run (no authoring placeholders).
- */
-function listUpcomingTasks(files, priorityFilter = {}, promptRunnerIdentity) {
-    return listRunnablePrompts(files, priorityFilter, promptRunnerIdentity).map(({ file, section }) => ({
-        label: buildPromptLabelForDisplay(file, section),
-        summary: buildPromptSummary(file, section),
-        priority: section.priority,
-    }));
-}
-
-/**
- * Groups upcoming tasks by priority, high to low.
- */
-function groupUpcomingTasksByPriority(tasks) {
-    const grouped = new Map();
-    for (const task of tasks) {
-        const group = grouped.get(task.priority);
-        if (group) {
-            group.push(task);
-        }
-        else {
-            grouped.set(task.priority, [task]);
-        }
-    }
-    return Array.from(grouped.entries())
-        .sort((a, b) => b[0] - a[0])
-        .map(([priority, groupedTasks]) => ({ priority, tasks: groupedTasks }));
-}
-
-/**
- * Prints upcoming tasks grouped by priority.
- */
-function printUpcomingTasks(tasks) {
-    if (tasks.length === 0) {
-        console.info(colors.green('No upcoming tasks.'));
-        return;
-    }
-    console.info(colors.cyan('Upcoming tasks (grouped by priority):'));
-    for (const group of groupUpcomingTasksByPriority(tasks)) {
-        console.info(colors.cyan(`Priority ${group.priority}:`));
-        for (const [index, task] of group.tasks.entries()) {
-            const summary = task.summary ? ` - ${task.summary}` : '';
-            console.info(` ${index + 1}. ${task.label}${summary}`);
-        }
-    }
-}
-
 /**
  * Builds a label that identifies the prompt section by index.
  */
@@ -79079,12 +80081,23 @@ const PRE_CODING_TEST_CHANGES_COMMIT_MESSAGE = 'test: Apply changes made by pre-
  * @public exported from `@promptbook/cli`
  */
 async function runCodexPrompts(providedOptions) {
+    var _a;
     const options = normalizeRunOptions(providedOptions !== null && providedOptions !== void 0 ? providedOptions : parseRunOptions(process.argv.slice(2)));
     validateRunCodexPromptOptions(options);
     resetCoderRunControls();
     const runStartDate = moment();
     const { isRichUiEnabled, progressDisplay, uiHandle } = createRunDisplays(options, runStartDate);
-    const waitForRequestedPause = createPauseWaiter({ isRichUiEnabled, progressDisplay, uiHandle });
+    const waitForRequestedPause = createPauseWaiter({
+        isRichUiEnabled,
+        progressDisplay,
+        uiHandle,
+        // Note: Every pause checkpoint of the whole run goes through this one waiter, so watching the free disk
+        //       space here covers each round, each verification and each runner without repeating the check
+        guardFreeDiskSpace: createFreeDiskSpaceGuard({
+            inspectedPath: process.cwd(),
+            isAskingQuestionsEnabled: (_a = options.isAskingQuestionsEnabled) !== null && _a !== void 0 ? _a : true,
+        }),
+    });
     startPauseListenerIfNeeded(isRichUiEnabled);
     try {
         const resolvedCoderContext = await resolveCoderContext(options.context, process.cwd());
@@ -79097,6 +80110,7 @@ async function runCodexPrompts(providedOptions) {
         const promptRunnerIdentity = {
             harnessName: options.agentName,
             modelName: actualRunnerModel,
+            agentReferences: resolvedCoderAgent === null || resolvedCoderAgent === void 0 ? void 0 : resolvedCoderAgent.agentReferences,
         };
         console.info(colors.green(`Running prompts with ${runner.name}`));
         initializeRunUi(uiHandle, runner.name, actualRunnerModel, options);
@@ -79533,11 +80547,14 @@ async function commitTestBeforeChangesIfNeeded(options) {
  * Creates a pause waiter that keeps the progress display and rich UI in sync.
  */
 function createPauseWaiter(options) {
-    const { isRichUiEnabled, progressDisplay, uiHandle } = options;
+    const { isRichUiEnabled, progressDisplay, uiHandle, guardFreeDiskSpace } = options;
     return async (checkpoint) => {
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase(checkpoint.phase);
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(checkpoint.statusMessage);
         announcePauseTargetLabel(checkpoint.checkpointLabel);
+        // Note: Runs after the checkpoint label is announced, so a pause requested because of a full disk
+        //       replaces that label and says why the run is standing still
+        await guardFreeDiskSpace();
         await checkPause({
             silent: isRichUiEnabled,
             onPaused: () => {
@@ -79656,7 +80673,7 @@ function finishWhenNoPromptIsAvailable(promptQueueSnapshot, isRichUiEnabled, uiH
         return false;
     }
     if (promptQueueSnapshot.stats.forAgent > 0) {
-        announceRunCompletion('No prompts match the selected harness or model.', colors.yellow, isRichUiEnabled, uiHandle);
+        announceRunCompletion('No prompts match the selected harness, model or agent.', colors.yellow, isRichUiEnabled, uiHandle);
     }
     else if (promptQueueSnapshot.stats.toBeWritten > 0) {
         announceRunCompletion('No prompts ready for agent.', colors.yellow, isRichUiEnabled, uiHandle);
@@ -79701,7 +80718,7 @@ function finishWhenEndAfterCurrentPromptIsRequested(options) {
 function announceKeepAliveStatus(promptQueueSnapshot, isRichUiEnabled, uiHandle) {
     let message;
     if (promptQueueSnapshot.stats.forAgent > 0) {
-        message = 'No prompts match the selected harness or model. Watching for changes...';
+        message = 'No prompts match the selected harness, model or agent. Watching for changes...';
     }
     else if (promptQueueSnapshot.stats.toBeWritten > 0) {
         message = 'No prompts ready for agent. Watching for changes...';