@promptbook/components 0.114.0-5 → 0.114.0-50

package/esm/src/book-components/Chat/utils/timeoutToolCallPresentation.d.ts

@@ -1,4 +1,22 @@
 import type { TODO_any } from '../../../utils/organization/TODO_any';
+/**
+ * Tool name of one scheduled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const SET_TIMEOUT_TOOL_CALL_NAME = "set_timeout";
+/**
+ * Tool name of one re-planned wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const UPDATE_TIMEOUT_TOOL_CALL_NAME = "update_timeout";
+/**
+ * Tool name of one cancelled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const CANCEL_TIMEOUT_TOOL_CALL_NAME = "cancel_timeout";
 /**
  * Action performed by timeout tools.
  *
@@ -140,4 +158,16 @@ export declare function buildTimeoutToolPrimarySentence(presentation: TimeoutToo
  * @private internal utility of `<Chat/>`
  */
 export declare function buildTimeoutToolScheduleSentence(presentation: TimeoutToolCallPresentation, translations?: TimeoutToolCallTranslations): string | null;
+/**
+ * Converts timeout duration into natural language sentence fragments.
+ *
+ * Shared by every timeout surface: the chat chips, the goal-chat planned messages of the Agents
+ * Server, and the planned-message prompt section of the agent-folder runner.
+ *
+ * @param milliseconds - Duration or repeat interval in milliseconds.
+ * @returns Label such as `5 minutes` or `1 hour 30 minutes`.
+ *
+ * @private internal utility of `<Chat/>` and the Agents Server planned messages
+ */
+export declare function formatTimeoutDurationHuman(milliseconds: number): string;
 export {};

package/esm/src/cli/$initializePromptbookCliProgram.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from 'commander';
+/**
+ * Registers the CLI commands on a fresh Commander program without parsing arguments or running an action.
+ * Tests can configure output and exit handling before registration, so subcommands inherit those settings.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $initializePromptbookCliProgram(program: Command): void;

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

@@ -0,0 +1,10 @@
+import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
+import type { NormalizedQuestionsCliOptions } from '../common/questionsCliOptions';
+/**
+ * Offers to add missing project-local ignore rules for the selected coding harness.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it may ask the user and update `.gitignore`.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function $ensureCoderHarnessGitignoreRules(projectPath: string, harnessName: PromptRunnerHarnessName | undefined, questionsOptions: NormalizedQuestionsCliOptions): Promise<void>;

package/esm/src/cli/cli-commands/coder/$ensureCoderHarnessGitignoreRules.test.d.ts

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

package/esm/src/cli/cli-commands/coder/GitChangesMode.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Supported values of the `--git-changes` option, which decides what happens with a dirty working tree.
+ *
+ * - `fail` — refuse to start while the working tree has uncommitted changes
+ * - `ignore` — start anyway and leave the uncommitted changes where they are
+ * - `continue` — resume the single prompt which was left in the middle of its implementation
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare const GIT_CHANGES_MODE_VALUES: readonly ["fail", "ignore", "continue"];
+/**
+ * Behavior requested for a working tree which has uncommitted changes.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export type GitChangesMode = (typeof GIT_CHANGES_MODE_VALUES)[number];
+/**
+ * Mode applied when `--git-changes` is not used at all.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare const DEFAULT_GIT_CHANGES_MODE: GitChangesMode;
+/**
+ * Checks whether a value is a supported `--git-changes` mode.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare function isGitChangesMode(value: string): value is GitChangesMode;

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

@@ -1,5 +1,6 @@
 import type { Command as Program } from 'commander';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { type ResolvedCoderPromptTemplate } from './boilerplateTemplates';
 /**
  * Initializes `coder add` command for Promptbook CLI utilities
  *
@@ -28,9 +29,29 @@ export type AddCoderPromptResult = {
  *
  * @private internal utility of `coder add` command
  */
-export declare function addCoderPrompt({ projectPath, description, priority, templateOption, }: {
+export declare function addCoderPrompt({ projectPath, description, priority, templateOption, promptTemplate, }: {
     readonly projectPath: string;
     readonly description: string;
     readonly priority: number;
     readonly templateOption?: string;
+    /** Internal authoring workflows may supply their own bounded instructions instead of the feature template. */
+    readonly promptTemplate?: ResolvedCoderPromptTemplate;
 }): Promise<AddCoderPromptResult>;
+/**
+ * Prepares a numbered, emoji-tagged prompt for preview without writing the prompt file.
+ * The offset reserves consecutive identities when a planning turn proposes several files.
+ *
+ * @private internal utility shared by `coder add` and `coder plan`
+ */
+export declare function prepareCoderPrompt({ projectPath, description, priority, templateOption, numberOffset, reservedEmojiTag, promptTemplate: providedPromptTemplate, }: {
+    readonly projectPath: string;
+    readonly description: string;
+    readonly priority: number;
+    readonly templateOption?: string;
+    readonly numberOffset?: number;
+    readonly reservedEmojiTag?: string;
+    /** Shared repair authoring preserves numbering and tags without appending ordinary implementation instructions. */
+    readonly promptTemplate?: ResolvedCoderPromptTemplate;
+}): Promise<AddCoderPromptResult & {
+    readonly content: string;
+}>;

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

@@ -0,0 +1,27 @@
+import type { Command as Program } from 'commander';
+import { type CoderAgentRole } from './coderAgentRole';
+/**
+ * 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 declare const CODER_AGENT_OPTION_DESCRIPTION = "Book agent providing persona, instructions, identity and task routing; --harness selects the coding tool and --model selects its model";
+/**
+ * Registers the shared `--agent` option for coder commands.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function addCoderAgentOption(command: Program, defaultRole?: CoderAgentRole): void;
+/**
+ * Registers the shared optional persona and context for single-agent execution or authoring.
+ * @private internal CLI registration helper
+ */
+export declare function addCoderExecutionOptions(command: Program): void;

package/esm/src/cli/cli-commands/coder/augmentCoderAgentTeam.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Adds only missing bundled TEAM commitments using canonical local Book identities.
+ * Role instructions come from the bundled Book, not from a harness or a second template here.
+ *
+ * @private internal utility of `coder init`
+ */
+export declare function augmentCoderAgentTeam(projectPath: string, role: 'developer' | 'planner'): Promise<'augmented' | 'unchanged'>;

package/esm/src/cli/cli-commands/coder/boilerplateCount.d.ts

@@ -12,7 +12,7 @@ export type BoilerplateCount = {
      * Number of prompts written into each generated file.
      *
      * Note: More than one prompt per file is an advanced option - each prompt is one separate
-     *       coding task separated by `---` and tagged with its own fresh emoji tag.
+     *       coding task separated by `---`, with all prompts in the file sharing its fresh emoji tag.
      */
     readonly promptsPerFileCount: number;
 };

package/esm/src/cli/cli-commands/coder/boilerplateTemplates.d.ts

@@ -16,6 +16,12 @@ export declare const PROMPTS_DONE_DIRECTORY_PATH: string;
  * @private internal utility of `ptbk coder`
  */
 export declare const PROMPTS_TEMPLATES_DIRECTORY_PATH: string;
+/**
+ * Relative path to the project-agnostic `common` boilerplate template referenced by the default coder scripts.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare const COMMON_PROMPT_TEMPLATE_FILE_PATH: string;
 /**
  * Initialization statuses used when creating or updating coder configuration artifacts.
  *
@@ -55,25 +61,6 @@ export type CoderPromptTemplateDefinition = {
      */
     readonly isDefaultProjectTemplate: boolean;
 };
-/**
- * Result of ensuring one default coder template file exists inside a project.
- *
- * @private internal utility of `ptbk coder`
- */
-export type EnsuredCoderPromptTemplateFile = {
-    /**
-     * Stable built-in identifier of the template.
-     */
-    readonly id: BuiltInCoderPromptTemplate;
-    /**
-     * Project-relative path of the materialized template file.
-     */
-    readonly relativeFilePath: string;
-    /**
-     * Status describing whether the file had to be created.
-     */
-    readonly status: InitializationStatus;
-};
 /**
  * Fully resolved boilerplate template used by `coder generate-boilerplates`.
  *
@@ -116,11 +103,11 @@ export declare function getDefaultCoderProjectPromptTemplateDefinitions(): Reado
  */
 export declare function getDefaultCoderPromptTemplateDefinition(template: BuiltInCoderPromptTemplate): CoderPromptTemplateDefinition;
 /**
- * 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`
  */
-export declare function ensureDefaultCoderPromptTemplateFiles(projectPath: string): Promise<ReadonlyArray<EnsuredCoderPromptTemplateFile>>;
+export declare function ensureDefaultCoderPromptTemplateFile(projectPath: string, definition: CoderPromptTemplateDefinition): Promise<InitializationStatus>;
 /**
  * Resolves the template requested by `coder generate-boilerplates`.
  *

package/esm/src/cli/cli-commands/coder/coderAgentRole.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Project-owned Book defaults for execution roles, independent of harness and model selection.
+ * Commands without an execution role, such as `coder list`, have no default Book filter.
+ *
+ * @private internal constant of `ptbk coder`
+ */
+export declare const CODER_DEFAULT_AGENT_BOOK_PATHS: {
+    readonly developer: "agents/developer.book";
+    readonly planner: "agents/planner.book";
+};
+/**
+ * Execution role whose editable local Book is selected when `--agent` is omitted.
+ *
+ * @private internal type of `ptbk coder`
+ */
+export type CoderAgentRole = keyof typeof CODER_DEFAULT_AGENT_BOOK_PATHS;
+/**
+ * Shared persona for optional single-agent execution and authoring; capabilities belong to the command.
+ * @private internal constant of project CLI commands
+ */
+export declare const DEFAULT_CODER_AGENT_ROLE: CoderAgentRole;

package/esm/src/cli/cli-commands/coder/coderReferencedArtifacts.d.ts

@@ -0,0 +1,34 @@
+import type { InitializationStatus } from './boilerplateTemplates';
+/**
+ * Status of one default Book or artifact referenced by the default coder scripts.
+ *
+ * `not-referenced` means that no newly added script points at the artifact, so `ptbk coder init` left it alone.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type CoderReferencedArtifactStatus = InitializationStatus | 'augmented' | 'unresolved' | 'not-referenced';
+/**
+ * Result of ensuring one default Book or artifact referenced by the default coder scripts.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type EnsuredCoderReferencedArtifact = {
+    /**
+     * Project-relative path of the referenced artifact.
+     */
+    readonly relativeFilePath: string;
+    /**
+     * Status describing whether the artifact was created, augmented, preserved, or could not be resolved.
+     */
+    readonly status: CoderReferencedArtifactStatus;
+    /** Explanation of an unresolved file or TEAM declaration, with the original content preserved. */
+    readonly diagnostic?: string;
+};
+/**
+ * Initializes essential context and artifacts referenced by freshly added scripts. Books are ensured separately.
+ *
+ * AGENTS.md is essential even when every script already exists or uses implicit defaults.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+export declare function ensureCoderReferencedArtifacts(projectPath: string, referencedArtifactPaths: ReadonlySet<string>): Promise<ReadonlyArray<EnsuredCoderReferencedArtifact>>;

package/esm/src/cli/cli-commands/coder/ensureCoderDefaultAgentFiles.d.ts

@@ -0,0 +1,8 @@
+import type { EnsuredCoderReferencedArtifact } from './coderReferencedArtifacts';
+/**
+ * Ensures every default Book independently, then adds missing helper declarations to the two primary roles.
+ * A failure leaves the affected Book intact and does not prevent the remaining files from being initialized.
+ *
+ * @private internal utility of `coder init`
+ */
+export declare function ensureCoderDefaultAgentFiles(projectPath: string): Promise<EnsuredCoderReferencedArtifact[]>;

package/esm/src/cli/cli-commands/coder/ensureCoderDefaultAgentFiles.test.d.ts

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

package/esm/src/cli/cli-commands/coder/ensureCoderGitattributesFile.d.ts

@@ -0,0 +1,13 @@
+import type { InitializationStatus } from './boilerplateTemplates';
+/**
+ * Project-relative path to the Git attributes initialized by Promptbook Coder.
+ *
+ * @private internal constant of `coder init`
+ */
+export declare const CODER_GITATTRIBUTES_FILE_PATH = ".gitattributes";
+/**
+ * Creates default Git attributes when missing, preserving project-owned attributes.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+export declare function ensureCoderGitattributesFile(projectPath: string): Promise<InitializationStatus>;

package/esm/src/cli/cli-commands/coder/ensureCoderGitignoreFile.d.ts

@@ -1,7 +1,20 @@
+import { type PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
 import type { InitializationStatus } from './boilerplateTemplates';
 /**
- * Ensures `.gitignore` contains the standalone Promptbook temp entry.
+ * Ensures `.gitignore` covers local dependencies, coder artifacts and every supported harness's local artifacts.
  *
  * @private function of `initializeCoderProjectConfiguration`
  */
 export declare function ensureCoderGitignoreFile(projectPath: string): Promise<InitializationStatus>;
+/**
+ * Lists missing project-local ignore rules for the selected harnesses.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function getMissingCoderHarnessGitignoreRules(projectPath: string, harnessNames: ReadonlyArray<PromptRunnerHarnessName>): Promise<ReadonlyArray<string>>;
+/**
+ * Adds the given Promptbook Coder rules to a project's `.gitignore` file.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function ensureCoderGitignoreRules(projectPath: string, rules: ReadonlyArray<string>): Promise<InitializationStatus>;

package/esm/src/cli/cli-commands/coder/ensureCoderPackageJsonFile.d.ts

@@ -1,7 +1,10 @@
-import type { InitializationStatus } from './boilerplateTemplates';
+import type { MergedStringRecordJsonFile } from './mergeStringRecordJsonFile';
+import { type PreparedCoderPackageJsonScripts } from './prepareCoderPackageJsonScripts';
 /**
  * Ensures `package.json` contains the standalone Promptbook coder helper scripts.
  *
+ * Project definitions are preserved; missing scripts and narrowly recognized generated migrations are applied.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
-export declare function ensureCoderPackageJsonFile(projectPath: string): Promise<InitializationStatus>;
+export declare function ensureCoderPackageJsonFile(projectPath: string): Promise<MergedStringRecordJsonFile & Omit<PreparedCoderPackageJsonScripts, 'scripts'>>;

package/esm/src/cli/cli-commands/coder/ensureCoderPackageJsonFile.test.d.ts

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

package/esm/src/cli/cli-commands/coder/ensureCoderRoleAgentFile.d.ts

@@ -0,0 +1,12 @@
+import type { InitializationStatus } from './boilerplateTemplates';
+/**
+ * Project-owned planning role selected when `coder plan` has no explicit Book override.
+ * @private internal constant of Coder role resolution
+ */
+export declare const CODER_PLANNER_AGENT_FILE_PATH = "agents/planner.book";
+/**
+ * Copies a bundled role without overwriting an existing project-owned Book, including on repeated init.
+ *
+ * @private internal utility of `coder init`
+ */
+export declare function ensureCoderRoleAgentFile(projectPath: string, role: 'developer' | 'planner' | 'lawyer' | 'copywriter'): Promise<InitializationStatus>;

package/esm/src/cli/cli-commands/coder/ensureCoderVscodeSettingsFile.d.ts

@@ -2,6 +2,8 @@ import type { InitializationStatus } from './boilerplateTemplates';
 /**
  * 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`
  */
 export declare function ensureCoderVscodeSettingsFile(projectPath: string): Promise<InitializationStatus>;

package/esm/src/cli/cli-commands/coder/ensureDirectory.d.ts

@@ -5,3 +5,9 @@ import type { InitializationStatus } from './boilerplateTemplates';
  * @private function of `initializeCoderProjectConfiguration`
  */
 export declare function ensureDirectory(projectPath: string, relativeDirectoryPath: string): Promise<InitializationStatus>;
+/**
+ * Checks whether a project-relative directory is missing or contains no entries.
+ *
+ * @private internal utility of `coder init` command
+ */
+export declare function isDirectoryEmpty(projectPath: string, relativeDirectoryPath: string): Promise<boolean>;

package/esm/src/cli/cli-commands/coder/findLegacyCoderCheckCallers.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Finds external project callers conservatively; it never rewrites their shell expressions.
+ * @private migration safety check for the Coder initializer
+ */
+export declare function findLegacyCoderCheckCallers(projectPath: string, legacyNames: ReadonlyArray<string>): Promise<Readonly<Record<string, ReadonlyArray<string>>>>;

package/esm/src/cli/cli-commands/coder/fix.d.ts

@@ -0,0 +1,7 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Registers a finite check-repair command with the shared parser, defaults and execution policy.
+ * @private internal CLI command registration
+ */
+export declare function $initializeCoderFixCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/coder/fix.test.d.ts

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

package/esm/src/cli/cli-commands/coder/fixWorkflow.test.d.ts

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

package/esm/src/cli/cli-commands/coder/generate-boilerplates.d.ts

@@ -10,7 +10,7 @@ import type { BoilerplateCount } from './boilerplateCount';
  */
 export declare function $initializeCoderGenerateBoilerplatesCommand(program: Program): $side_effect;
 /**
- * Generates boilerplate prompt files with unique emoji tags.
+ * Generates boilerplate prompt files with one unique emoji tag per file.
  *
  * @private internal function of `generatePromptBoilerplate` command
  */
@@ -18,4 +18,4 @@ export declare function generatePromptBoilerplate({ projectPath, boilerplateCoun
     readonly projectPath: string;
     readonly boilerplateCount: BoilerplateCount;
     readonly templateOption?: string;
-}): Promise<void>;
+}): Promise<ReadonlyArray<string>>;

package/esm/src/cli/cli-commands/coder/getCoderInitializationCommitPaths.d.ts

@@ -0,0 +1,9 @@
+import type { WorkspaceRepositoryContext } from '../common/workspaceRepository';
+import type { CoderInitializationSummary } from './initializeCoderProjectConfiguration';
+/**
+ * Restricts an explicit initialization commit to the initializer's write set, in repository-relative paths.
+ * The shared snapshot still excludes pre-existing files that initialization did not actually change.
+ *
+ * @private internal utility of the shared project initializer
+ */
+export declare function getCoderInitializationCommitPaths(workspace: WorkspaceRepositoryContext, summary: CoderInitializationSummary, boilerplatePaths: ReadonlyArray<string>): ReadonlyArray<string>;

package/esm/src/cli/cli-commands/coder/getDefaultCoderPackageJsonScripts.d.ts

@@ -4,3 +4,9 @@
  * @private internal utility of `coder init` command
  */
 export declare function getDefaultCoderPackageJsonScripts(): Readonly<Record<string, string>>;
+/**
+ * Collects the project-relative artifact paths referenced by the given default coder scripts.
+ *
+ * @private internal utility of `coder init` command
+ */
+export declare function resolveCoderPackageJsonScriptReferencedArtifactPaths(scriptNames: ReadonlyArray<string>): ReadonlySet<string>;

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

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

package/esm/src/cli/cli-commands/coder/initializeCoderProjectConfiguration.d.ts

@@ -1,4 +1,5 @@
-import type { EnsuredCoderPromptTemplateFile, InitializationStatus } from './boilerplateTemplates';
+import type { InitializationStatus } from './boilerplateTemplates';
+import type { CoderReferencedArtifactStatus, EnsuredCoderReferencedArtifact } from './coderReferencedArtifacts';
 /**
  * Result summary returned after coder configuration initialization.
  *
@@ -6,22 +7,33 @@ import type { EnsuredCoderPromptTemplateFile, InitializationStatus } from './boi
  */
 export type CoderInitializationSummary = {
     readonly promptsDirectoryStatus: InitializationStatus;
+    readonly promptsReadmeFileStatus: InitializationStatus;
     readonly promptsDoneDirectoryStatus: InitializationStatus;
     readonly promptsTemplatesDirectoryStatus: InitializationStatus;
-    readonly promptTemplateFileStatuses: ReadonlyArray<EnsuredCoderPromptTemplateFile>;
     readonly agentsDirectoryStatus: InitializationStatus;
-    readonly developerAgentFileStatus: InitializationStatus;
-    readonly agentsFileStatus: InitializationStatus;
-    readonly agentCodingFileStatus: InitializationStatus;
+    readonly adamAgentFileStatus: CoderReferencedArtifactStatus;
+    readonly adamAgentFileDiagnostic?: string;
     readonly envFileStatus: InitializationStatus;
     readonly gitignoreFileStatus: InitializationStatus;
+    readonly gitattributesFileStatus: InitializationStatus;
     readonly packageJsonFileStatus: InitializationStatus;
     readonly vscodeSettingsFileStatus: InitializationStatus;
+    readonly addedPackageJsonScriptNames: ReadonlyArray<string>;
+    readonly referencedArtifactStatuses: ReadonlyArray<EnsuredCoderReferencedArtifact>;
     readonly initializedEnvVariableNames: ReadonlyArray<string>;
+    /** Actual preserved or generated scope of the project check. */
+    readonly checkScriptSummary: string;
+    /** Manual steps needed for custom or conflicting legacy entries. */
+    readonly migrationInstructions: ReadonlyArray<string>;
+    /** Whether validation is configured rather than still requiring setup. */
+    readonly isCheckConfigured: boolean;
 };
 /**
  * Creates or updates all coder configuration artifacts required in the current project.
  *
+ * Existing scripts, settings and Books are preserved. Missing Books and helper TEAM declarations are added
+ * independently of package scripts, with unresolved artifacts reported without replacing project content.
+ *
  * @private internal utility of `coder init` command
  */
-export declare function initializeCoderProjectConfiguration(projectPath: string): Promise<CoderInitializationSummary>;
+export declare function initializeCoderProjectConfiguration(projectPath: string, onStepCompleted?: (step: string) => void): Promise<CoderInitializationSummary>;

package/esm/src/cli/cli-commands/coder/list.d.ts

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * 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`
+ */
+export declare function $initializeCoderListCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/coder/list.test.d.ts

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

package/esm/src/cli/cli-commands/coder/mergeStringRecordJsonFile.d.ts

@@ -8,11 +8,31 @@ type MergeStringRecordJsonFileOptions = {
     readonly fieldPath: string;
     readonly nextEntries: Readonly<Record<string, string>>;
     readonly ensureParentDirectoryPath?: string;
+    /** Optional narrowly scoped migration of existing entries before missing defaults are added. */
+    readonly transformExistingEntries?: (entries: Readonly<Record<string, string>>) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
+};
+/**
+ * Result of one additive string-record merge into a JSON file.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type MergedStringRecordJsonFile = {
+    /**
+     * Status describing whether the JSON file had to be created or updated.
+     */
+    readonly status: InitializationStatus;
+    /**
+     * Keys which were missing in the JSON file and therefore added by the merge.
+     */
+    readonly addedEntryKeys: ReadonlyArray<string>;
 };
 /**
  * Ensures one JSON object field contains the provided string-record entries.
  *
+ * Entries are additive unless a caller explicitly supplies a scoped migration callback.
+ * Hand-tuned scripts and settings survive repeated `ptbk coder init`; migrations recognize generated entries only.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
-export declare function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, }: MergeStringRecordJsonFileOptions): Promise<InitializationStatus>;
+export declare function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, transformExistingEntries, }: MergeStringRecordJsonFileOptions): Promise<MergedStringRecordJsonFile>;
 export {};

package/esm/src/cli/cli-commands/coder/plan.d.ts

@@ -0,0 +1,7 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Registers the repository-aware, planning-only conversation under the existing coder command group.
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $initializeCoderPlanCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/coder/planning/assertPlanningCommitSafe.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Protects the shared authoring Git helper's temporary directory and shell-quoted absolute message path.
+ * PRD paths themselves are checked separately by the write boundary before every save and commit.
+ * @private internal execution boundary of `coder plan`
+ */
+export declare function assertPlanningCommitSafe(projectPath: string): void;

package/esm/src/cli/cli-commands/coder/planning/assertPlanningPrdCommitScope.d.ts

@@ -0,0 +1,7 @@
+import type { PlanningChange } from './preparePlanningChanges';
+/**
+ * Refuses to mix prior or concurrent user edits into a PRD that this session intends to commit.
+ * After the first save, the session's exact saved text is the baseline for subsequent revisions.
+ * @private internal execution boundary of `coder plan`
+ */
+export declare function assertPlanningPrdCommitScope(projectPath: string, changes: ReadonlyArray<PlanningChange>, savedContents: ReadonlyMap<string, string>, preexistingChangedPaths: ReadonlySet<string>): Promise<void>;

package/esm/src/cli/cli-commands/coder/planning/assertPlanningRuntimePath.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Keeps host-owned staging and Git runtime directories inside the ordinary Promptbook temporary tree.
+ * Missing directories are allowed, but no existing ancestor may redirect subsequent writes through a link.
+ * @private internal execution boundary of `coder plan`
+ */
+export declare function assertPlanningRuntimePath(projectPath: string, runtimePath: string): void;

package/esm/src/cli/cli-commands/coder/planning/createPlanningTerminal.d.ts

@@ -0,0 +1,8 @@
+import type { PlanningSessionIo } from './runPlanningSession';
+/**
+ * Builds an EOF-aware terminal. EOF or Ctrl+C also cancels an in-flight harness turn.
+ * @private internal utility of `coder plan`
+ */
+export declare function createPlanningTerminal(): PlanningSessionIo & {
+    readonly close: () => void;
+};

package/esm/src/cli/cli-commands/coder/planning/createPlanningTerminal.test.d.ts

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

package/esm/src/cli/cli-commands/coder/planning/createPlanningWorkspace.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Host-owned structured output contract kept outside the PRD queue.
+ * @private internal constant of `coder plan`
+ */
+export declare const PLANNING_RESPONSE_SCHEMA_FILENAME = "response.schema.json";
+/**
+ * Creates isolated runtime state in the already ignored Promptbook location, outside the PRD queue.
+ * An empty Git root prevents the harness from loading repository-local configuration and hooks.
+ * @private internal utility of `coder plan`
+ */
+export declare function createPlanningWorkspace(projectPath: string): Promise<string>;

package/esm/src/cli/cli-commands/coder/planning/discussPlanningTurn.d.ts

@@ -0,0 +1,15 @@
+import type { CoderTeamScope } from '../../../../../scripts/run-codex-prompts/team/CoderTeamRuntime';
+import { type PlanningMessage, type PlanningReply } from './planningProtocol';
+/**
+ * Runs the same read-only protocol throughout the delegation tree. Only the primary caller can receive proposals.
+ * @private internal utility of `coder plan`
+ */
+export declare function discussPlanningTurn(options: {
+    readonly projectPath: string;
+    readonly history: PlanningMessage[];
+    readonly signal: AbortSignal;
+    readonly infer: () => Promise<string>;
+    readonly team?: CoderTeamScope;
+    readonly isAdviser?: boolean;
+    readonly write?: (message: string) => void;
+}): Promise<PlanningReply>;

package/esm/src/cli/cli-commands/coder/planning/fixtures/snapshotPlanningProject.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Captures project-owned fixture files while excluding the ignored planning runtime and linked test targets.
+ * @private test utility of `coder plan`
+ */
+export declare function snapshotPlanningProject(projectPath: string, directory?: string): Promise<Record<string, string>>;