@promptbook/types 0.112.0-73 → 0.112.0-79

package/README.md

@@ -701,28 +701,28 @@ npx ts-node ./src/cli/test/ptbk.ts coder verify
 
 #### Using `ptbk coder` in an external project
 
-If you want to use the workflow in another repository, install the package and invoke the `ptbk` binary. After local installation, `npx ptbk ...` is the most portable form; plain `ptbk ...` also works when your environment exposes the local binary on `PATH`.
+If you want to use the workflow in another repository, install the package and invoke the `ptbk` binary directly.
 
 ```bash
 npm install ptbk
 
 ptbk coder init
 
-npx ptbk coder generate-boilerplates
+ptbk coder generate-boilerplates
 
-npx ptbk coder generate-boilerplates --template prompts/templates/common.md
+ptbk coder generate-boilerplates --template prompts/templates/common.md
 
-npx ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --test npm run test
+ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --test npm run test
 
-npx ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --auto-push
+ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --auto-push
 
-npx ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --test npm run test --ignore-git-changes --no-wait
+ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --test npm run test --ignore-git-changes --no-wait
 
-npx ptbk coder find-refactor-candidates
+ptbk coder find-refactor-candidates
 
-npx ptbk coder find-refactor-candidates --level xhigh
+ptbk coder find-refactor-candidates --level xhigh
 
-npx ptbk coder verify
+ptbk coder verify
 ```
 
 `ptbk coder init` also bootstraps a starter `AGENTS.md`, adds `package.json` scripts for the four main coder commands, adds the shared `/.promptbook` temp ignore to `.gitignore`, and configures `.vscode/settings.json` so pasted images from `prompts/*.md` land in `prompts/screenshots/`.

package/esm/src/avatars/types/AvatarVisualDefinition.d.ts

@@ -7,7 +7,7 @@ import type { AvatarDefinition } from './AvatarDefinition';
  *
  * @private shared contract for the avatar rendering system
  */
-export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'octopus3d' | 'ascii-octopus' | 'minecraft' | 'minecraft2' | 'fractal' | 'orb';
+export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'octopus3d' | 'octopus3d2' | 'ascii-octopus' | 'minecraft' | 'minecraft2' | 'fractal' | 'orb';
 /**
  * Derived color palette used by avatar visuals.
  *

package/esm/src/avatars/visuals/octopus3d2AvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * Octopus 3D 2 avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const octopus3d2AvatarVisual: AvatarVisualDefinition;

package/esm/src/avatars/visuals/octopus3dAvatarVisualShared.d.ts

@@ -0,0 +1,37 @@
+import type { AvatarPalette } from '../types/AvatarVisualDefinition';
+import { type Point3D, type ProjectedPoint } from './avatar3dProjectionShared';
+/**
+ * Eye-style knobs shared by the proper-3D octopus visuals.
+ *
+ * @private helper of the 3D octopus avatar visuals
+ */
+export type OctopusProjectedEyeStyle = {
+    readonly irisScale: number;
+    readonly pupilWidthScale: number;
+    readonly pupilHeightScale: number;
+    readonly upperLidArchRatio: number;
+    readonly upperLidInsetRatio: number;
+    readonly lowerLidOpacity: number;
+};
+/**
+ * Draws one projected eye on a rotated octopus surface.
+ *
+ * @private helper of the 3D octopus avatar visuals
+ */
+export declare function drawProjectedOrganicEye(context: CanvasRenderingContext2D, localCenter: Point3D, radiusX: number, radiusY: number, center: Point3D, rotationX: number, rotationY: number, sceneCenterX: number, sceneCenterY: number, size: number, palette: AvatarPalette, timeMs: number, phase: number, interaction: {
+    readonly gazeX: number;
+    readonly gazeY: number;
+    readonly intensity: number;
+}, eyeStyle: OctopusProjectedEyeStyle): void;
+/**
+ * Draws a subtle projected mouth arc across the front of a rotated octopus surface.
+ *
+ * @private helper of the 3D octopus avatar visuals
+ */
+export declare function drawProjectedOrganicMouth(context: CanvasRenderingContext2D, localPoints: readonly [Point3D, Point3D, Point3D], center: Point3D, rotationX: number, rotationY: number, sceneCenterX: number, sceneCenterY: number, palette: AvatarPalette, size: number): void;
+/**
+ * Draws one filled projected quad.
+ *
+ * @private helper of the 3D octopus avatar visuals
+ */
+export declare function drawProjectedQuad(context: CanvasRenderingContext2D, corners: readonly [ProjectedPoint, ProjectedPoint, ProjectedPoint, ProjectedPoint], fillStyle: string): void;

package/esm/src/book-components/Chat/save/_common/chatExportRendering.d.ts

@@ -1,4 +1,6 @@
+import type { ChatMessage } from '../../types/ChatMessage';
 import type { ChatParticipant } from '../../types/ChatParticipant';
+import type { ParsedCitation } from '../../utils/parseCitationsFromContent';
 /**
  * Minimal participant visuals needed by chat exports.
  *
@@ -8,6 +10,33 @@ export type ChatExportParticipantVisuals = {
     readonly displayName: string;
     readonly accentColor: string;
 };
+/**
+ * One numbered source collected from rendered chat message citations.
+ *
+ * @private internal utility of chat save format definitions
+ */
+export type ChatExportCitationFootnote = {
+    readonly number: number;
+    readonly citation: ParsedCitation;
+};
+/**
+ * Document-wide citation footnotes collected while rendering chat exports.
+ *
+ * @private internal utility of chat save format definitions
+ */
+export type ChatExportCitationFootnoteRegistry = {
+    readonly footnotes: Array<ChatExportCitationFootnote>;
+    readonly footnoteBySourceKey: Map<string, ChatExportCitationFootnote>;
+};
+/**
+ * Render-ready chat message citation payload using document-wide footnote numbers.
+ *
+ * @private internal utility of chat save format definitions
+ */
+export type ChatExportCitationRenderModel = {
+    readonly content: ChatMessage['content'];
+    readonly footnotes: ReadonlyArray<ChatExportCitationFootnote>;
+};
 /**
  * Formats exported timestamps into a compact human-readable label.
  *
@@ -26,3 +55,21 @@ export declare function buildChatExportParticipantMap(participants: ReadonlyArra
  * @private internal utility of chat save format definitions
  */
 export declare function resolveChatExportParticipantVisuals(participants: ReadonlyMap<string, ChatParticipant>, sender: string): ChatExportParticipantVisuals;
+/**
+ * Creates an empty document-wide citation footnote registry.
+ *
+ * @private internal utility of chat save format definitions
+ */
+export declare function createChatExportCitationFootnoteRegistry(): ChatExportCitationFootnoteRegistry;
+/**
+ * Converts one message to markdown content with document-wide numbered citation references.
+ *
+ * @private internal utility of chat save format definitions
+ */
+export declare function createChatExportCitationRenderModel(citationFootnotes: ChatExportCitationFootnoteRegistry, message: Pick<ChatMessage, 'content' | 'citations'>): ChatExportCitationRenderModel;
+/**
+ * Creates a readable source label for one citation footnote.
+ *
+ * @private internal utility of chat save format definitions
+ */
+export declare function formatChatExportCitationFootnoteLabel(footnote: ChatExportCitationFootnote, href?: string): string;

package/esm/src/book-components/Chat/save/html/htmlSaveFormatDefinition.d.ts

@@ -1,5 +1,17 @@
 import type { ChatMessage } from '../../types/ChatMessage';
 import type { ChatParticipant } from '../../types/ChatParticipant';
+/**
+ * Class name that gives the PDF renderer the same root styles as the standalone HTML document body.
+ *
+ * @private Internal helper shared by HTML and PDF chat exports.
+ */
+export declare const CHAT_HTML_EXPORT_RENDER_ROOT_CLASS_NAME = "chat-html-export-render-root";
+/**
+ * Builds the standalone HTML chat export document shared by HTML downloads and PDF rendering.
+ *
+ * @private Internal helper shared by HTML and PDF chat exports.
+ */
+export declare function buildChatHtml(title: string, messages: ReadonlyArray<ChatMessage>, participants: ReadonlyArray<ChatParticipant>): string;
 /**
  * HTML export plugin
  *

package/esm/src/book-components/Chat/save/index.d.ts

@@ -26,7 +26,7 @@ export declare const CHAT_SAVE_FORMATS: readonly [{
 }, {
     readonly formatName: "md";
     readonly label: "Markdown";
-    readonly getContent: ({ messages, participants }: {
+    readonly getContent: ({ title, messages, participants }: {
         readonly title: string;
         readonly messages: readonly import("../types/ChatMessage").ChatMessage[];
         readonly participants: readonly import("../types/ChatParticipant").ChatParticipant[];
@@ -60,7 +60,7 @@ export declare const CHAT_SAVE_FORMATS: readonly [{
         readonly title: string;
         readonly messages: readonly import("../types/ChatMessage").ChatMessage[];
         readonly participants: readonly import("../types/ChatParticipant").ChatParticipant[];
-    }) => Uint8Array;
+    }) => Promise<Uint8Array>;
     readonly mimeType: "application/pdf";
     readonly fileExtension: "pdf";
 }];

package/esm/src/book-components/Chat/save/markdown/mdSaveFormatDefinition.d.ts

@@ -1,3 +1,5 @@
+import type { ChatMessage } from '../../types/ChatMessage';
+import type { ChatParticipant } from '../../types/ChatParticipant';
 /**
  * Markdown export plugin
  *
@@ -6,10 +8,10 @@
 export declare const mdSaveFormatDefinition: {
     readonly formatName: "md";
     readonly label: "Markdown";
-    readonly getContent: ({ messages, participants }: {
+    readonly getContent: ({ title, messages, participants }: {
         readonly title: string;
-        readonly messages: readonly import("../../types/ChatMessage").ChatMessage[];
-        readonly participants: readonly import("../../types/ChatParticipant").ChatParticipant[];
+        readonly messages: readonly ChatMessage[];
+        readonly participants: readonly ChatParticipant[];
     }) => string;
     readonly mimeType: "text/markdown";
     readonly fileExtension: "md";

package/esm/src/book-components/Chat/save/pdf/buildChatPdf.d.ts

@@ -1,13 +1,13 @@
 import type { ChatMessage } from '../../types/ChatMessage';
 import type { ChatParticipant } from '../../types/ChatParticipant';
 /**
- * Builds a polished PDF representation of the provided chat.
+ * Builds a PDF from the same standalone HTML document used by the HTML chat download.
  *
  * @param title - Title used in the PDF heading and metadata.
  * @param messages - Messages that should be included in the PDF export.
- * @param participants - Optional participant metadata to resolve sender names.
+ * @param participants - Participant metadata used by the HTML chat export.
  * @returns Binary data for the generated PDF file.
  *
  * @private Internal helper used by `pdfSaveFormatDefinition`.
  */
-export declare function buildChatPdf(title: string, messages: ReadonlyArray<ChatMessage>, participants?: ReadonlyArray<ChatParticipant>): Uint8Array;
+export declare function buildChatPdf(title: string, messages: ReadonlyArray<ChatMessage>, participants: ReadonlyArray<ChatParticipant>): Promise<Uint8Array>;

package/esm/src/book-components/Chat/save/pdf/pdfSaveFormatDefinition.d.ts

@@ -10,7 +10,7 @@ export declare const pdfSaveFormatDefinition: {
         readonly title: string;
         readonly messages: readonly import("../../types/ChatMessage").ChatMessage[];
         readonly participants: readonly import("../../types/ChatParticipant").ChatParticipant[];
-    }) => Uint8Array;
+    }) => Promise<Uint8Array>;
     readonly mimeType: "application/pdf";
     readonly fileExtension: "pdf";
 };

package/esm/src/cli/cli-commands/agent/agentProjectPaths.d.ts

@@ -4,6 +4,12 @@
  * @private internal utility of `ptbk agent`
  */
 export declare const AGENT_BOOK_FILE_PATH = "agent.book";
+/**
+ * Relative path to local knowledge files initialized by `ptbk agent init`.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_KNOWLEDGE_DIRECTORY_PATH = "knowledge";
 /**
  * Relative path to the message queue root initialized by `ptbk agent init`.
  *
@@ -23,19 +29,13 @@ export declare const AGENT_QUEUED_MESSAGES_DIRECTORY_PATH: string;
  */
 export declare const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH: string;
 /**
- * Relative path to local knowledge files referenced by the default agent prompt.
- *
- * @private internal utility of `ptbk agent`
- */
-export declare const AGENT_KNOWLEDGE_DIRECTORY_PATH = "knowledge";
-/**
- * Relative path to local agent documentation initialized by `ptbk agent init`.
+ * Relative path to generated local agent documentation initialized by `ptbk agent init`.
  *
  * @private internal utility of `ptbk agent`
  */
 export declare const AGENT_DOCS_DIRECTORY_PATH = "docs";
 /**
- * Relative path to the local Book language manual used by the coding runner prompt.
+ * Relative path to the local Book language manual initialized by `ptbk agent init`.
  *
  * @private internal utility of `ptbk agent`
  */

package/esm/src/cli/cli-commands/agent/initializeAgentRunnerCommand.d.ts

@@ -11,7 +11,7 @@ type InitializeAgentRunnerCommandOptions = {
     readonly aliases?: ReadonlyArray<string>;
     readonly summary: string;
     readonly featureLines: ReadonlyArray<string>;
-    readonly isExitingOnSuccess?: boolean;
+    readonly executionMode: 'once' | 'watch';
     readonly configureCommand?: (command: Program) => void;
     readonly loadExecutor: () => Promise<(runOptions: ReturnType<typeof createAgentRunOptionsFromCliOptions>) => Promise<unknown>>;
 };

package/esm/src/cli/cli-commands/agents-server/buildAgentsServer.d.ts

@@ -0,0 +1,56 @@
+/// <reference types="node" />
+/**
+ * Inputs controlling one cached Agents Server production build.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+type EnsureAgentsServerBuildOptions = {
+    readonly appPath?: string;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly isBuildForced?: boolean;
+    readonly onBuildEvent?: (event: string) => void;
+    readonly onBuildOutput?: (chunk: string) => void;
+};
+/**
+ * Paths needed after the Agents Server production build is ready.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+export type AgentsServerBuildArtifacts = {
+    readonly appPath: string;
+    readonly nextCliPath: string;
+};
+/**
+ * Input paths required to validate or update the cached Agents Server build.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+type AgentsServerBuildCacheOptions = {
+    readonly appPath: string;
+    readonly environment?: NodeJS.ProcessEnv;
+};
+/**
+ * Ensures that the local Agents Server production build exists and matches its source fingerprint.
+ *
+ * @private internal utility of `ptbk agents-server`
+ */
+export declare function ensureAgentsServerBuild(options?: EnsureAgentsServerBuildOptions): Promise<AgentsServerBuildArtifacts>;
+/**
+ * Returns true when the production build marker and source fingerprint still match.
+ *
+ * @private internal utility of `ptbk agents-server`
+ */
+export declare function isAgentsServerBuildCacheCurrent(options: AgentsServerBuildCacheOptions): Promise<boolean>;
+/**
+ * Persists the source fingerprint for the just-created production build.
+ *
+ * @private internal utility of `ptbk agents-server`
+ */
+export declare function writeAgentsServerBuildCache(options: AgentsServerBuildCacheOptions): Promise<void>;
+/**
+ * Finds the Agents Server app in a source checkout or generated CLI package.
+ *
+ * @private internal utility of `ptbk agents-server`
+ */
+export declare function resolveAgentsServerAppPath(): Promise<string>;
+export {};

package/esm/src/cli/cli-commands/agents-server/buildAgentsServer.test.d.ts

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

package/esm/src/cli/cli-commands/agents-server/ensureAgentsServerEnvFile.d.ts

@@ -0,0 +1,7 @@
+import { type EnsureProjectEnvFileResult } from '../common/projectInitialization';
+/**
+ * Ensures `.env` contains all required Agents Server configuration entries.
+ *
+ * @private internal utility of `ptbk agents-server init`
+ */
+export declare function ensureAgentsServerEnvFile(projectPath: string): Promise<EnsureProjectEnvFileResult>;

package/esm/src/cli/cli-commands/agents-server/ensureAgentsServerGitignoreFile.d.ts

@@ -0,0 +1,7 @@
+import { type ProjectInitializationStatus } from '../common/projectInitialization';
+/**
+ * Ensures `.gitignore` excludes local Agents Server runtime artifacts.
+ *
+ * @private internal utility of `ptbk agents-server init`
+ */
+export declare function ensureAgentsServerGitignoreFile(projectPath: string): Promise<ProjectInitializationStatus>;

package/esm/src/cli/cli-commands/agents-server/init.d.ts

@@ -0,0 +1,9 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+export { initializeAgentsServerProjectConfiguration } from './initializeAgentsServerProjectConfiguration';
+/**
+ * Initializes `agents-server init` command for Promptbook CLI utilities.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentsServerInitCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/agents-server/init.test.d.ts

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

package/esm/src/cli/cli-commands/agents-server/initializeAgentsServerProjectConfiguration.d.ts

@@ -0,0 +1,17 @@
+import type { ProjectInitializationStatus } from '../common/projectInitialization';
+/**
+ * Result summary returned after Agents Server configuration initialization.
+ *
+ * @private internal utility of `ptbk agents-server init`
+ */
+export type AgentsServerInitializationSummary = {
+    readonly envFileStatus: ProjectInitializationStatus;
+    readonly gitignoreFileStatus: ProjectInitializationStatus;
+    readonly initializedEnvVariableNames: ReadonlyArray<string>;
+};
+/**
+ * Creates or updates local Agents Server configuration files in the current project.
+ *
+ * @private internal utility of `ptbk agents-server init`
+ */
+export declare function initializeAgentsServerProjectConfiguration(projectPath: string): Promise<AgentsServerInitializationSummary>;

package/esm/src/cli/cli-commands/agents-server/printAgentsServerInitializationSummary.d.ts

@@ -0,0 +1,7 @@
+import type { AgentsServerInitializationSummary } from './initializeAgentsServerProjectConfiguration';
+/**
+ * Prints a readable summary of local Agents Server configuration initialization.
+ *
+ * @private internal utility of `ptbk agents-server init`
+ */
+export declare function printAgentsServerInitializationSummary(summary: AgentsServerInitializationSummary): void;

package/esm/src/cli/cli-commands/agents-server/run.d.ts

@@ -0,0 +1,14 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `agents-server start` command for Promptbook CLI utilities.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentsServerStartCommand(program: Program): $side_effect;
+/**
+ * Initializes `agents-server build` command for Promptbook CLI utilities.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentsServerBuildCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/agents-server/run.test.d.ts

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

package/esm/src/cli/cli-commands/agents-server/startAgentsServer.d.ts

@@ -0,0 +1,23 @@
+import type { ThinkingLevel } from '../coder/ThinkingLevel';
+import type { PromptRunnerAgentName } from '../common/promptRunnerCliOptions';
+import type { number_port } from '../../../types/number_positive';
+/**
+ * Options required to start the foreground Agents Server service group.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+export type StartAgentsServerOptions = {
+    readonly port: number_port;
+    readonly agentName: PromptRunnerAgentName;
+    readonly model?: string;
+    readonly noUi: boolean;
+    readonly thinkingLevel?: ThinkingLevel;
+    readonly allowCredits: boolean;
+    readonly isBuildForced: boolean;
+};
+/**
+ * Starts the Agents Server web app and local coding-agent queue workers in the foreground.
+ *
+ * @private internal utility of `ptbk agents-server`
+ */
+export declare function startAgentsServer(options: StartAgentsServerOptions): Promise<void>;

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

@@ -0,0 +1,8 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * Initializes `agents-server` command with subcommands for Promptbook CLI utilities.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentsServerCommand(program: Program): $side_effect;

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

@@ -0,0 +1,65 @@
+/**
+ * File status returned by project configuration bootstrapping helpers.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export type ProjectInitializationStatus = 'created' | 'updated' | 'unchanged';
+/**
+ * Minimal environment variable descriptor used for additive `.env` initialization.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export type ProjectEnvVariableDefinition = {
+    readonly name: string;
+};
+/**
+ * Result of one additive `.env` initialization attempt.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export type EnsureProjectEnvFileResult = {
+    readonly envFileStatus: ProjectInitializationStatus;
+    readonly initializedEnvVariableNames: ReadonlyArray<string>;
+};
+/**
+ * Options required to append missing variables into a project `.env`.
+ */
+type EnsureProjectEnvFileOptions<TEnvVariable extends ProjectEnvVariableDefinition> = {
+    readonly projectPath: string;
+    readonly emptyFileContent: string;
+    readonly envVariables: ReadonlyArray<TEnvVariable>;
+    readonly buildMissingEnvVariablesBlock: (envVariables: ReadonlyArray<TEnvVariable>) => string;
+};
+/**
+ * Options required to append missing rules into a project `.gitignore`.
+ */
+type EnsureProjectGitignoreFileOptions = {
+    readonly projectPath: string;
+    readonly blockHeader: string;
+    readonly rules: ReadonlyArray<string>;
+};
+/**
+ * Ensures `.env` exists and appends only still-missing variable definitions.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export declare function ensureProjectEnvFile<TEnvVariable extends ProjectEnvVariableDefinition>({ projectPath, emptyFileContent, envVariables, buildMissingEnvVariablesBlock, }: EnsureProjectEnvFileOptions<TEnvVariable>): Promise<EnsureProjectEnvFileResult>;
+/**
+ * Ensures `.gitignore` contains all required project initialization rules.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export declare function ensureProjectGitignoreFile({ projectPath, blockHeader, rules, }: EnsureProjectGitignoreFileOptions): Promise<ProjectInitializationStatus>;
+/**
+ * Reads one text file when it exists, otherwise returns `undefined`.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export declare function readTextFileIfExists(path: string): Promise<string | undefined>;
+/**
+ * Appends one text block to existing file content while preserving readable newlines.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export declare function appendBlock(currentContent: string, blockToAppend: string): string;
+export {};

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

@@ -6,6 +6,24 @@ import type { ThinkingLevel } from '../coder/ThinkingLevel';
  * @private internal utility of `promptbookCli`
  */
 export declare const PROMPT_RUNNER_AGENT_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
+/**
+ * Environment variable used as the default runner identifier when `--agent` is omitted.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PTBK_AGENT_ENV = "PTBK_AGENT";
+/**
+ * Environment variable used as the default runner model when `--model` is omitted.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PTBK_MODEL_ENV = "PTBK_MODEL";
+/**
+ * Environment variable used as the default runner thinking level when `--thinking-level` is omitted.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PTBK_THINKING_LEVEL_ENV = "PTBK_THINKING_LEVEL";
 /**
  * Runner identifier supported by Promptbook CLI agent orchestration commands.
  *
@@ -29,6 +47,12 @@ export type PromptRunnerCliOptions = {
     readonly autoPush: boolean;
     readonly autoPull: boolean;
 };
+/**
+ * Commander option bag for runner selection plus terminal/runtime switches shared with server orchestration.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptRunnerSelectionCliOptions = Pick<PromptRunnerCliOptions, 'agent' | 'model' | 'ui' | 'thinkingLevel' | 'allowCredits'>;
 /**
  * Normalized runner options used by runner-backed CLI commands.
  *
@@ -46,6 +70,12 @@ export type NormalizedPromptRunnerCliOptions = {
     readonly autoPush: boolean;
     readonly autoPull: boolean;
 };
+/**
+ * Normalized runner selection plus terminal/runtime switches shared with server orchestration.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NormalizedPromptRunnerSelectionCliOptions = Pick<NormalizedPromptRunnerCliOptions, 'agentName' | 'model' | 'noUi' | 'thinkingLevel' | 'allowCredits'>;
 /**
  * Description block shared by runner-backed CLI commands.
  *
@@ -70,6 +100,12 @@ export declare const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION: string;
  * @private internal utility of `promptbookCli`
  */
 export declare function addPromptRunnerSelectionOptions(command: Program): void;
+/**
+ * Registers shared runner terminal/runtime flags on a command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addPromptRunnerRuntimeOptions(command: Program): void;
 /**
  * Registers shared runner execution flags on a command.
  *
@@ -84,3 +120,11 @@ export declare function addPromptRunnerExecutionOptions(command: Program): void;
 export declare function normalizePromptRunnerCliOptions(cliOptions: PromptRunnerCliOptions, options: {
     readonly isAgentRequired: boolean;
 }): NormalizedPromptRunnerCliOptions;
+/**
+ * Converts Commander runner selection/runtime flags into the normalized runner shape.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function normalizePromptRunnerSelectionCliOptions(cliOptions: PromptRunnerSelectionCliOptions, options: {
+    readonly isAgentRequired: boolean;
+}): NormalizedPromptRunnerSelectionCliOptions;

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

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * Marks one CLI command as deprecated while keeping it available for existing callers.
+ *
+ * @private utility of CLI
+ */
+export declare function $deprecateCliCommand(command: Command, deprecationMessage: string): $side_effect;

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

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