@promptbook/cli 0.114.0-32 → 0.114.0-34

package/esm/src/cli/cli-commands/common/disk-space/FreeDiskSpaceStatus.d.ts

@@ -0,0 +1,33 @@
+/**
+ * How much free disk space is left, measured against the `ptbk coder` free disk space limits.
+ *
+ * - `sufficient` - there is enough free disk space to start a run and to keep it running
+ * - `low` - there is not enough free disk space to start a new run
+ * - `critical` - there is not enough free disk space to keep a started run going
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type FreeDiskSpaceLevel = 'sufficient' | 'low' | 'critical';
+/**
+ * One measurement of the free disk space on the filesystem which hosts the inspected path.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type FreeDiskSpaceStatus = {
+    /**
+     * Path whose filesystem was measured.
+     */
+    readonly inspectedPath: string;
+    /**
+     * Bytes which are still available to the current user on that filesystem.
+     */
+    readonly availableBytes: number;
+    /**
+     * Total size of that filesystem in bytes.
+     */
+    readonly totalBytes: number;
+    /**
+     * Severity of the measured free disk space.
+     */
+    readonly level: FreeDiskSpaceLevel;
+};

package/esm/src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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`
+ */
+export declare function formatFreeDiskSpaceBytes(bytes: number): string;

package/esm/src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/common/disk-space/formatLowFreeDiskSpaceWarning.d.ts

@@ -0,0 +1,10 @@
+import type { FreeDiskSpaceStatus } from './FreeDiskSpaceStatus';
+/**
+ * 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`
+ */
+export declare function formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus: FreeDiskSpaceStatus): string;

package/esm/src/cli/cli-commands/common/disk-space/freeDiskSpaceConstants.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Free disk space below which `ptbk coder` refuses to start a new run.
+ *
+ * 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`
+ */
+export declare const LOW_FREE_DISK_SPACE_BYTES: number;
+/**
+ * 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`
+ */
+export declare const CRITICALLY_LOW_FREE_DISK_SPACE_BYTES: number;
+/**
+ * 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`
+ */
+export declare const FREE_DISK_SPACE_RECHECK_INTERVAL_MS: number;

package/esm/src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.d.ts

@@ -0,0 +1,7 @@
+import type { FreeDiskSpaceLevel } from './FreeDiskSpaceStatus';
+/**
+ * Classifies one measured amount of free disk space against the `ptbk coder` free disk space limits.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function resolveFreeDiskSpaceLevel(availableBytes: number): FreeDiskSpaceLevel;

package/esm/src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.d.ts

@@ -1,3 +1,4 @@
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 /**
  * Reports one detected harness installation status and offers to install or update the harness.
@@ -6,4 +7,4 @@ import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $applyHarnessInstallationStatus(status: HarnessInstallationStatus): Promise<void>;
+export declare function $applyHarnessInstallationStatus(status: HarnessInstallationStatus, questionsOptions: NormalizedQuestionsCliOptions): Promise<void>;

package/esm/src/cli/cli-commands/common/harness/$ensureHarnessInstallations.d.ts

@@ -1,6 +1,7 @@
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 /**
- * 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,
@@ -10,4 +11,4 @@ import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $ensureHarnessInstallations(harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>, isHarnessUpdateCheckEnabled?: boolean): Promise<void>;
+export declare function $ensureHarnessInstallations(harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>, questionsOptions: NormalizedQuestionsCliOptions): Promise<void>;

package/esm/src/cli/cli-commands/common/harness/HarnessDefinition.d.ts

@@ -19,6 +19,28 @@ export type HarnessStandaloneInstallation = {
      */
     readonly updateCommand: string;
 };
+/**
+ * Description of how the user signs in to one CLI coding harness again.
+ *
+ * Every harness refuses to work once its login is missing or its session has expired, and each of them is
+ * signed in differently - some have a dedicated login command, others sign in from their own interactive UI.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessAuthenticationMethod = {
+    /**
+     * Command which starts the sign-in flow of the harness.
+     */
+    readonly command: string;
+    /**
+     * Step which finishes the sign-in inside the started command.
+     *
+     * Harnesses which sign in from their own interactive user interface leave the user in that interface, so
+     * naming just the command would not be enough to get them signed in. Harnesses with a dedicated login
+     * command leave this undefined.
+     */
+    readonly interactiveStep?: string;
+};
 /**
  * Static description of one supported CLI coding harness.
  *
@@ -49,6 +71,10 @@ export type HarnessDefinition = {
      * Project-local files or directories which this harness can create and which should not be committed.
      */
     readonly projectGitignoreRules: ReadonlyArray<string>;
+    /**
+     * How the user signs in to this harness again after its login is missing or has expired.
+     */
+    readonly authenticationMethod: HarnessAuthenticationMethod;
     /**
      * How a standalone installation of this harness is recognized and updated.
      *

package/esm/src/cli/cli-commands/common/npm/$askForNpmPackageInstallationApproval.d.ts

@@ -1,9 +1,11 @@
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 /**
  * Asks the user in the terminal whether an npm package should be installed or updated now.
  *
  * 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`
  */
-export declare function $askForNpmPackageInstallationApproval(question: string): Promise<boolean>;
+export declare function $askForNpmPackageInstallationApproval(question: string, questionsOptions: NormalizedQuestionsCliOptions): Promise<boolean>;

package/esm/src/cli/cli-commands/common/promptPriorityCliOptions.d.ts

@@ -0,0 +1,7 @@
+import type { Command as Program } from 'commander';
+/**
+ * Registers the shared prompt-priority filter options on a queue-based `ptbk coder` command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addPromptPriorityOptions(command: Program): void;

package/esm/src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.d.ts

@@ -1,3 +1,4 @@
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 /**
  * Checks local and global Promptbook CLI installations before an interactive coder run and offers to update them.
  *
@@ -11,4 +12,4 @@
  * @returns `true` when at least one installation was updated and the current coder run should stop
  * @private internal utility of `promptbookCli`
  */
-export declare function $ensurePromptbookCliInstallations(): Promise<boolean>;
+export declare function $ensurePromptbookCliInstallations(questionsOptions: NormalizedQuestionsCliOptions): Promise<boolean>;

package/esm/src/cli/cli-commands/common/questionsCliOptions.d.ts

@@ -0,0 +1,45 @@
+import type { Command as Program } from 'commander';
+/**
+ * Commander option bag for opting out of every interactive question.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type QuestionsCliOptions = {
+    readonly questions: boolean;
+};
+/**
+ * Normalized interactive-questions option shared by every `ptbk coder` command which can ask something.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NormalizedQuestionsCliOptions = {
+    readonly isAskingQuestionsEnabled: boolean;
+};
+/**
+ * Description block shared by the `ptbk coder` commands which can ask interactive questions.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const QUESTIONS_DESCRIPTION: string;
+/**
+ * Registers the shared `--no-questions` option on a `ptbk coder` command which can ask interactive questions.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addQuestionsOption(command: Program): void;
+/**
+ * Converts the Commander questions flag into the normalized interactive-questions option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function normalizeQuestionsCliOptions(cliOptions: QuestionsCliOptions): NormalizedQuestionsCliOptions;
+/**
+ * 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`
+ */
+export declare function assertUserConfirmationIsAllowed(options: {
+    readonly isAskingQuestionsEnabled: boolean;
+    readonly isWaitingForUser: boolean;
+}): void;

package/esm/src/cli/cli-commands/common/questionsCliOptions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/common/$deprecateCliCommand.d.ts

@@ -3,6 +3,9 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
 /**
  * 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
  */
 export declare function $deprecateCliCommand(command: Command, deprecationMessage: string): $side_effect;

package/esm/src/cli/common/$hideCliCommandFromHelp.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * 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
+ */
+export declare function $hideCliCommandFromHelp(command: Command): $side_effect;

package/esm/src/cli/common/$hideCliCommandFromHelp.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/common/$requireCliSubcommand.d.ts

@@ -0,0 +1,18 @@
+import type { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * 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
+ */
+export declare function $requireCliSubcommand(command: Command): $side_effect;
+/**
+ * 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
+ */
+export declare function $reportMissingCliSubcommand(command: Command): never;

package/esm/src/cli/common/$requireCliSubcommand.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/llm-providers/vercel/VercelExecutionToolsOptions.d.ts

@@ -17,7 +17,10 @@ export type VercelExecutionToolsOptions = CommonToolsOptions & Pick<LlmExecution
      */
     readonly availableModels: ReadonlyArray<AvailableModel>;
     /**
-     * Additional settings for chat models when calling `vercelProvider.chat('model-name', settings)`
+     * Additional settings for chat models, for example `temperature` or `providerOptions`
+     *
+     * Note: Since Vercel AI SDK v5 these settings belong to the model call, not to
+     *       `vercelProvider.chat('model-name')` which takes just the model name
      */
-    readonly additionalChatSettings?: Partial<Parameters<VercelProvider['chat']>[1]>;
+    readonly additionalChatSettings?: Partial<Omit<Parameters<ReturnType<VercelProvider['chat']>['doGenerate']>[0], 'prompt'>>;
 };

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-31`).
+ * It follows semantic versioning (e.g., `0.114.0-33`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.114.0-32",
+    "version": "0.114.0-34",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,
@@ -92,12 +92,9 @@
         "node": ">=18.18.0",
         "npm": ">=8.0.0"
     },
-    "overrides": {
-        "zod": "$zod"
-    },
     "dependencies": {
-        "@ai-sdk/deepseek": "0.1.17",
-        "@ai-sdk/google": "1.0.17",
+        "@ai-sdk/deepseek": "1.0.56",
+        "@ai-sdk/google": "2.0.97",
         "@anthropic-ai/sdk": "0.68.0",
         "@azure/openai": "1.0.0-beta.13",
         "@mozilla/readability": "0.6.0",
@@ -129,10 +126,8 @@
         "socket.io-client": "4.7.5",
         "spacetrim": "0.11.60",
         "swagger-ui-express": "5.0.1",
-        "type-fest": "4.5.0",
         "userhome": "1.0.1",
         "waitasecond": "1.11.164",
-        "zod": "4.3.6",
         "typescript": "5.2.2",
         "ts-node": "10.9.2",
         "next": "15.4.11",
@@ -142,7 +137,7 @@
         "@tailwindcss/typography": "0.5.19",
         "postcss": "8.5.12",
         "autoprefixer": "10.4.27",
-        "@ai-sdk/openai": "1.0.20",
+        "@ai-sdk/openai": "2.0.127",
         "@aws-sdk/client-s3": "3.936.0",
         "@dnd-kit/core": "6.3.1",
         "@dnd-kit/sortable": "10.0.0",
@@ -180,15 +175,17 @@
         "node-gzip": "1.1.2",
         "nodemailer": "^7.0.13",
         "qrcode": "1.5.4",
-        "swagger-ui-react": "5.31.2",
+        "swagger-ui-react": "5.32.15",
         "turndown": "7.2.4",
+        "type-fest": "4.5.0",
         "web-push": "^3.6.7",
         "y-monaco": "0.1.6",
         "y-protocols": "1.0.7",
         "y-websocket": "3.0.0",
         "y-websocket-server": "1.0.2",
         "yjs": "13.6.30",
-        "zeptomail": "7.0.2"
+        "zeptomail": "7.0.2",
+        "zod": "4.3.6"
     },
     "bin": {
         "promptbook": "bin/promptbook-cli.js",

package/src/book-2.0/book-language-documentation/getSafeCodeBlock.ts

@@ -5,7 +5,7 @@
  * @param language - Optional info-string language label.
  * @returns Fenced code block.
  *
- * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ * @private internal utility of `createStandaloneBookLanguageMarkdown` and of the `ptbk coder` run traces
  */
 export function getSafeCodeBlock(content: string, language = 'markdown'): string {
     const maxBacktickCount = Math.max(0, ...(content.match(/`+/g) || []).map((match) => match.length));

package/src/book-components/Chat/MockedChat/MockedChat.tsx

@@ -155,6 +155,28 @@ type SimulateMockedChatPlaybackProps = {
     readonly isCancelledRef: () => boolean;
 };
 
+/**
+ * Provides stable identifiers for mocked messages that omit them.
+ *
+ * Incremental typing changes the message content on every word. A stable id
+ * lets the chat renderer preserve the message element instead of treating
+ * every content update as a new message.
+ *
+ * @private function of `MockedChat`
+ */
+function ensureMockedChatMessageIds(messages: ReadonlyArray<ChatMessage>): ReadonlyArray<ChatMessage> {
+    return messages.map((message, messageIndex) => {
+        if (message.id) {
+            return message;
+        }
+
+        return {
+            ...message,
+            id: `mocked-chat-message-${messageIndex}`,
+        };
+    });
+}
+
 /**
  * Resolves one delay value, including random ranges.
  *
@@ -560,7 +582,7 @@ async function simulateMockedChatPlayback(props: SimulateMockedChatPlaybackProps
 export function MockedChat(props: MockedChatProps) {
     const {
         delayConfig,
-        messages: originalMessages,
+        messages: sourceMessages,
         isResettable = true,
         isPausable = true,
         messageOffsetsMs,
@@ -570,6 +592,8 @@ export function MockedChat(props: MockedChatProps) {
         ...chatProps
     } = props;
 
+    const originalMessages = useMemo(() => ensureMockedChatMessageIds(sourceMessages), [sourceMessages]);
+
     const delays = {
         ...MOCKED_CHAT_DELAY_CONFIGS.NORMAL_FLOW,
         ...delayConfig,

package/src/cli/cli-commands/agent-folder.ts

@@ -1,9 +1,9 @@
-import colors from 'colors';
 import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
+import { $requireCliSubcommand } from '../common/$requireCliSubcommand';
 import { $initializeAgentInitCommand } from './agent-folder/init';
 import { $initializeAgentRunMultipleCommand } from './agent-folder/runMultiple';
 import { $initializeAgentRunCommand } from './agent-folder/run';
@@ -41,11 +41,7 @@ export function $initializeAgentFolderCommand(program: Program): $side_effect {
     $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`

package/src/cli/cli-commands/agent.ts

@@ -1,9 +1,9 @@
-import colors from 'colors';
 import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
+import { $requireCliSubcommand } from '../common/$requireCliSubcommand';
 import { $initializeAgentChatCommand } from './agent/chat';
 import { $initializeAgentExecCommand } from './agent/exec';
 
@@ -33,11 +33,7 @@ export function $initializeAgentCommand(program: Program): $side_effect {
     $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`

package/src/cli/cli-commands/agents-server.ts

@@ -1,9 +1,9 @@
-import colors from 'colors';
 import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
+import { $requireCliSubcommand } from '../common/$requireCliSubcommand';
 import { $initializeAgentsServerInitCommand } from './agents-server/init';
 import {
     $initializeAgentsServerBuildCommand,
@@ -35,11 +35,7 @@ export function $initializeAgentsServerCommand(program: Program): $side_effect {
     $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`

package/src/cli/cli-commands/coder/$ensureCoderHarnessGitignoreRules.ts

@@ -1,5 +1,6 @@
 import colors from 'colors';
 import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
+import type { NormalizedQuestionsCliOptions } from '../common/questionsCliOptions';
 import { $askForConfirmation } from '../common/$askForConfirmation';
 import { getHarnessDefinition } from '../common/harness/HarnessDefinition';
 import { ensureCoderGitignoreRules, getMissingCoderHarnessGitignoreRules } from './ensureCoderGitignoreFile';
@@ -14,6 +15,7 @@ import { ensureCoderGitignoreRules, getMissingCoderHarnessGitignoreRules } from
 export async function $ensureCoderHarnessGitignoreRules(
     projectPath: string,
     harnessName: PromptRunnerHarnessName | undefined,
+    questionsOptions: NormalizedQuestionsCliOptions,
 ): Promise<void> {
     if (harnessName === undefined) {
         return;
@@ -30,6 +32,7 @@ export async function $ensureCoderHarnessGitignoreRules(
     const entryLabel = missingRules.length === 1 ? 'entry' : 'entries';
     const isAdditionApproved = await $askForConfirmation(
         `Add the missing ${label} ignore ${entryLabel} ${formattedRules} to \`.gitignore\` now?`,
+        questionsOptions,
     );
 
     if (!isAdditionApproved) {

package/src/cli/cli-commands/coder/add.ts

@@ -17,6 +17,13 @@ import {
     normalizeCoderGitSyncCliOptions,
 } from '../common/coderGitSyncCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
+import {
+    addQuestionsOption,
+    normalizeQuestionsCliOptions,
+    QUESTIONS_DESCRIPTION,
+    type NormalizedQuestionsCliOptions,
+    type QuestionsCliOptions,
+} from '../common/questionsCliOptions';
 import {
     buildCoderPromptSection,
     getDefaultCoderPromptTemplateDefinitions,
@@ -66,6 +73,8 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
                 - \`ptbk coder add\`
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
+
+                ${block(QUESTIONS_DESCRIPTION)}
             `,
         ),
     );
@@ -88,6 +97,7 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
         `),
     );
     addCoderGitSyncOptions(command);
+    addQuestionsOption(command);
 
     command.action(
         handleActionErrors(async (descriptionArgument: string | undefined, cliOptions) => {
@@ -97,9 +107,10 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
             } & CoderGitSyncCliOptions;
 
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
             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 import(
@@ -221,7 +232,10 @@ export async function addCoderPrompt({
  *
  * @private internal utility of `coder add` command
  */
-async function resolveCoderPromptDescription(descriptionArgument: string | undefined): Promise<string> {
+async function resolveCoderPromptDescription(
+    descriptionArgument: string | undefined,
+    { isAskingQuestionsEnabled }: NormalizedQuestionsCliOptions,
+): Promise<string> {
     if (descriptionArgument !== undefined && descriptionArgument.trim() !== '') {
         return descriptionArgument.trim();
     }
@@ -243,6 +257,17 @@ async function resolveCoderPromptDescription(descriptionArgument: string | undef
         return standardInputDescription;
     }
 
+    if (!isAskingQuestionsEnabled) {
+        throw new ParseError(
+            spaceTrim(`
+                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',

package/src/cli/cli-commands/coder/agentCliOptions.ts

@@ -0,0 +1,32 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+
+/**
+ * Commander option bag for an optional Book agent used by coder commands.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export type CoderAgentCliOptions = {
+    readonly agent?: string;
+};
+
+/**
+ * Description shared by coder commands which accept an agent Book.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export 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`
+ */
+export function addCoderAgentOption(command: Program): void {
+    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