@promptbook/cli 0.114.0-5 → 0.114.0-50

package/src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallation.ts

@@ -0,0 +1,76 @@
+import type { NpmPackageInstallationLocation } from '../npm/buildNpmPackageInstallCommand';
+
+/**
+ * Npm packages which directly provide the `ptbk` executable.
+ *
+ * `ptbk` is the preferred package and forwards to `@promptbook/cli`; the latter can also be installed directly.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const PROMPTBOOK_CLI_NPM_PACKAGE_NAMES = ['ptbk', '@promptbook/cli'] as const;
+
+/**
+ * Npm package which directly provides the `ptbk` executable.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliNpmPackageName = (typeof PROMPTBOOK_CLI_NPM_PACKAGE_NAMES)[number];
+
+/**
+ * Place where one Promptbook CLI package is installed.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationLocation = NpmPackageInstallationLocation;
+
+/**
+ * Fields shared by local and global Promptbook CLI installations.
+ *
+ * @private internal utility of `PromptbookCliInstallation`
+ */
+type PromptbookCliInstallationBase = {
+    /**
+     * Npm package that provides the CLI.
+     */
+    readonly npmPackageName: PromptbookCliNpmPackageName;
+
+    /**
+     * Version from the installed package's `package.json`.
+     */
+    readonly installedVersion: string;
+};
+
+/**
+ * One directly declared local Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type LocalPromptbookCliInstallation = PromptbookCliInstallationBase & {
+    /**
+     * Local manifest section containing the package.
+     */
+    readonly installationLocation: Exclude<PromptbookCliInstallationLocation, 'global'>;
+
+    /**
+     * Project directory containing the `package.json` which declares the package.
+     */
+    readonly projectPath: string;
+};
+
+/**
+ * One directly installed global Promptbook CLI package.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type GlobalPromptbookCliInstallation = PromptbookCliInstallationBase & {
+    readonly installationLocation: 'global';
+};
+
+/**
+ * One local or global Promptbook CLI package that can be updated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallation = LocalPromptbookCliInstallation | GlobalPromptbookCliInstallation;
+
+// Note: [🟡] Code for Promptbook CLI installation definitions [PromptbookCliInstallation](src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallation.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallationStatus.ts

@@ -0,0 +1,32 @@
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+
+/**
+ * Result of comparing one installed Promptbook CLI package with the newest published version.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationState = 'up-to-date' | 'outdated' | 'unknown';
+
+/**
+ * Version status of one Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationStatus = {
+    /**
+     * Installed CLI package being checked.
+     */
+    readonly installation: PromptbookCliInstallation;
+
+    /**
+     * Result of comparing the installed version with the newest published version.
+     */
+    readonly installationState: PromptbookCliInstallationState;
+
+    /**
+     * Newest published package version, or `null` when npm could not be reached.
+     */
+    readonly latestVersion: string | null;
+};
+
+// Note: [🟡] Code for Promptbook CLI installation status [PromptbookCliInstallationStatus](src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallationStatus.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/buildPromptbookCliInstallCommand.ts

@@ -0,0 +1,13 @@
+import { buildNpmPackageInstallCommand } from '../npm/buildNpmPackageInstallCommand';
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+
+/**
+ * Builds the npm command that updates one existing Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function buildPromptbookCliInstallCommand(installation: PromptbookCliInstallation): string {
+    return buildNpmPackageInstallCommand(installation.npmPackageName, installation.installationLocation);
+}
+
+// Note: [🟡] Code for Promptbook CLI installation command [buildPromptbookCliInstallCommand](src/cli/cli-commands/common/promptbook-cli/buildPromptbookCliInstallCommand.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/formatPromptbookCliInstallationWarning.ts

@@ -0,0 +1,45 @@
+import { spaceTrim } from 'spacetrim';
+import type { PromptbookCliInstallationLocation } from './PromptbookCliInstallation';
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+
+/**
+ * Formats the warning shown when one or more Promptbook CLI installations are outdated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function formatPromptbookCliInstallationWarning(
+    statuses: ReadonlyArray<PromptbookCliInstallationStatus>,
+): string {
+    const statusLines = statuses.map((status) => {
+        const { npmPackageName, installedVersion, installationLocation } = status.installation;
+
+        return `- ${formatPromptbookCliInstallationLocation(
+            installationLocation,
+        )} \`${npmPackageName}\`: installed \`${installedVersion}\`, newest \`${status.latestVersion}\``;
+    });
+
+    return spaceTrim(
+        (block) => `
+            **Promptbook CLI** is outdated.
+
+            ${block(statusLines.join('\n'))}
+        `,
+    );
+}
+
+/**
+ * Describes an installation location in text suitable for an update warning.
+ */
+function formatPromptbookCliInstallationLocation(installationLocation: PromptbookCliInstallationLocation): string {
+    if (installationLocation === 'global') {
+        return 'Globally installed';
+    }
+
+    if (installationLocation === 'local-development-dependency') {
+        return 'Locally in `devDependencies`';
+    }
+
+    return 'Locally in `dependencies`';
+}
+
+// Note: [🟡] Code for Promptbook CLI installation warning [formatPromptbookCliInstallationWarning](src/cli/cli-commands/common/promptbook-cli/formatPromptbookCliInstallationWarning.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,89 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../errors/NotAllowed';
+
+/**
+ * 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 const QUESTIONS_DESCRIPTION = spaceTrim(`
+    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`
+ */
+export function addQuestionsOption(command: Program): void {
+    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`
+ */
+export function normalizeQuestionsCliOptions(cliOptions: QuestionsCliOptions): NormalizedQuestionsCliOptions {
+    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`
+ */
+export function assertUserConfirmationIsAllowed(options: {
+    readonly isAskingQuestionsEnabled: boolean;
+    readonly isWaitingForUser: boolean;
+}): void {
+    const { isAskingQuestionsEnabled, isWaitingForUser } = options;
+
+    if (!isWaitingForUser || isAskingQuestionsEnabled) {
+        return;
+    }
+
+    throw new NotAllowed(
+        spaceTrim(`
+            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

package/src/cli/cli-commands/common/resolveBundledAgentBookPath.ts

@@ -0,0 +1,38 @@
+import { stat } from 'fs/promises';
+import { join } from 'path';
+import { spaceTrim } from 'spacetrim';
+import { NotFoundError } from '../../../errors/NotFoundError';
+
+/**
+ * Locates a bundled agent in either the source checkout or the generated CLI package.
+ *
+ * @private internal utility of CLI agent initialization
+ */
+export async function resolveBundledAgentBookPath(relativeFilePath: string): Promise<string> {
+    const candidates = [
+        join(__dirname, '..', relativeFilePath),
+        join(__dirname, '..', '..', '..', '..', relativeFilePath),
+    ];
+
+    for (const candidate of candidates) {
+        if (
+            await stat(candidate).then(
+                (entry) => entry.isFile(),
+                () => false,
+            )
+        ) {
+            return candidate;
+        }
+    }
+
+    throw new NotFoundError(
+        spaceTrim(
+            (block) => `
+            Cannot find the bundled agent book \`${relativeFilePath}\`.
+
+            Checked:
+            ${block(candidates.map((candidate) => `- \`${candidate}\``).join('\n'))}
+        `,
+        ),
+    );
+}

package/src/cli/cli-commands/common/resolveLocalAgentSource.ts

@@ -0,0 +1,147 @@
+import { dirname } from 'path';
+import { spaceTrim } from 'spacetrim';
+import type { AgentReferenceResolver } from '../../../book-2.0/agent-source/AgentReferenceResolver';
+import { getEffectiveExplicitFromCommitment } from '../../../book-2.0/agent-source/explicitFromCommitment';
+import { parseAgentSourceWithCommitments } from '../../../book-2.0/agent-source/parseAgentSourceWithCommitments';
+import { parseAgentSource } from '../../../book-2.0/agent-source/parseAgentSource';
+import { isPseudoAgentUrl } from '../../../book-2.0/agent-source/pseudoAgentReferences';
+import { resolveInheritedAgentSource } from '../../../book-2.0/agent-source/resolveInheritedAgentSource';
+import type { string_book } from '../../../book-2.0/agent-source/string_book';
+import { DEFAULT_MAX_RECURSION } from '../../../config';
+import { ParseError } from '../../../errors/ParseError';
+import { createLocalAgentReferenceResolver } from './createLocalAgentReferenceResolver';
+import { LocalAgentBookCollection, type LocalAgentBook } from './LocalAgentBookCollection';
+
+/**
+ * Resolved source together with the profile resolver used when compiling TEAM commitments.
+ *
+ * @private internal type of CLI agent resolution
+ */
+export type ResolvedLocalAgentSource = {
+    /** Canonical identity used to bound recursive TEAM consultations. */
+    readonly agentUrl: string;
+    readonly agentSource: string_book;
+    readonly agentReferenceResolver: AgentReferenceResolver;
+    /** Resolves another Book in this collection, retaining its own inheritance and reference locations. */
+    readonly resolveAgentSource: (url: string, signal?: AbortSignal) => Promise<ResolvedLocalAgentSource>;
+    /** Newly created books which the coder may include in its initialization commit. */
+    readonly createdAgentBookPaths: ReadonlyArray<string>;
+};
+
+/**
+ * Applies the shared Agent Server inheritance rules to a repository's local and remote books.
+ *
+ * @private internal utility of CLI agent resolution
+ */
+export async function resolveLocalAgentSource(
+    agentBookPath: string,
+    currentWorkingDirectory: string,
+    options: { readonly isInitializationAllowed?: boolean; readonly signal?: AbortSignal } = {},
+): Promise<ResolvedLocalAgentSource> {
+    const collection = new LocalAgentBookCollection(
+        dirname(agentBookPath),
+        currentWorkingDirectory,
+        options.isInitializationAllowed,
+        options.signal,
+    );
+    await collection.initialize();
+    const primaryBook = await collection.readBook(agentBookPath);
+    const adamAgentUrl = collection.getAdamAgentUrl();
+
+    /** Resolves each dependency with its own location and the current inheritance stack. */
+    async function resolveBook(
+        book: LocalAgentBook,
+        inheritancePath: ReadonlyArray<string> = [],
+        signal = options.signal,
+    ): Promise<string_book> {
+        signal?.throwIfAborted();
+        if (inheritancePath.length > DEFAULT_MAX_RECURSION) {
+            throw new ParseError(
+                spaceTrim(
+                    `Agent inheritance exceeds **${DEFAULT_MAX_RECURSION}** levels at \`${
+                        book.filePath || book.url
+                    }\`.`,
+                ),
+            );
+        }
+        const agentReferenceResolver = createLocalAgentReferenceResolver(collection, book);
+        const source = await resolveBookCommitmentReferences(book.source, agentReferenceResolver);
+        return resolveInheritedAgentSource(source, {
+            adamAgentUrl,
+            currentAgentUrl: book.url,
+            inheritancePath,
+            agentSourceImporter: async (url, context) =>
+                resolveBook(await collection.getBook(url, signal), context.importAgentOptions.inheritancePath, signal),
+        });
+    }
+
+    /** Keeps the source loader and profiles scoped to this resolution, never to a global TEAM registry. */
+    async function resolveAgent(book: LocalAgentBook, signal = options.signal): Promise<ResolvedLocalAgentSource> {
+        return {
+            agentUrl: book.url,
+            agentSource: await resolveBook(book, [], signal),
+            agentReferenceResolver: {
+                ...createLocalAgentReferenceResolver(collection, book),
+                resolveTeammateProfile: async (url) => {
+                    if (isPseudoAgentUrl(url)) {
+                        return null;
+                    }
+                    const book = await collection.getBook(url, signal);
+                    const parsedSource = parseAgentSource(await resolveBook(book, [], signal));
+                    return {
+                        agentName: book.profile.agentName,
+                        personaDescription: parsedSource.personaDescription,
+                    };
+                },
+            },
+            resolveAgentSource: async (url, consultationSignal) =>
+                resolveAgent(await collection.getBook(url, consultationSignal || signal), consultationSignal || signal),
+            createdAgentBookPaths: collection.createdAgentBookPaths,
+        };
+    }
+
+    return resolveAgent(primaryBook);
+}
+
+/**
+ * Resolves reference blocks before embedding dependencies so inherited TEAM paths keep their original directory.
+ * Parser-provided locations keep examples, unknown commitments and ordinary prose untouched.
+ */
+async function resolveBookCommitmentReferences(
+    source: string_book,
+    resolver: AgentReferenceResolver,
+): Promise<string_book> {
+    const parsedSource = parseAgentSourceWithCommitments(source);
+    const lines = source.split(/\r?\n/);
+    const commitmentStartLines = [...parsedSource.commitments, ...(parsedSource.unknownCommitments || [])]
+        .map((commitment) => commitment.lineNumber - 1)
+        .sort((left, right) => left - right);
+    const effectiveFrom = getEffectiveExplicitFromCommitment(source);
+
+    for (const commitment of [...parsedSource.commitments].reverse()) {
+        if (!['FROM', 'IMPORT', 'IMPORTS', 'TEAM'].includes(commitment.type)) {
+            continue;
+        }
+        const startLine = commitment.lineNumber - 1;
+        if (commitment.type === 'FROM' && effectiveFrom?.lineIndex !== startLine) {
+            continue;
+        }
+        let endLine = commitmentStartLines.find((lineNumber) => lineNumber > startLine) ?? lines.length;
+        // A horizontal rule also terminates a commitment before the next registered keyword.
+        for (let lineIndex = startLine + 1; lineIndex < endLine; lineIndex++) {
+            if (/^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/.test(lines[lineIndex] || '')) {
+                endLine = lineIndex;
+                break;
+            }
+        }
+        const content = await resolver.resolveCommitmentContent(commitment.type, commitment.content);
+        const commitmentType = commitment.type === 'IMPORTS' ? 'IMPORT' : commitment.type;
+        const replacement = content.trim()
+            ? `${commitmentType} ${content}\n`
+            : commitmentType === 'FROM'
+            ? 'FROM @Null\n'
+            : '';
+        lines.splice(startLine, endLine - startLine, ...replacement.split('\n'));
+    }
+    return lines.join('\n') as string_book;
+}

package/src/cli/cli-commands/common/validateCoderRunOptions.ts

@@ -0,0 +1,113 @@
+import { spaceTrim } from 'spacetrim';
+import type { RunOptions } from '../../../../scripts/run-codex-prompts/cli/RunOptions';
+import { isCheckBeforeMode } from '../../../../scripts/run-codex-prompts/checks/CheckBeforeMode';
+import { DatabaseError } from '../../../errors/DatabaseError';
+import { NotAllowed } from '../../../errors/NotAllowed';
+
+/**
+ * Validates cross-flag constraints before workspace setup or the run starts.
+ * @private shared validation for Coder execution commands
+ */
+export function validateCoderRunOptions(
+    options: Pick<
+        RunOptions,
+        | 'checkCommand'
+        | 'checkBefore'
+        | 'allowDestructiveAutoMigrate'
+        | 'autoMigrate'
+        | 'noCommit'
+        | 'waitForUser'
+        | 'gitChanges'
+        | 'autoPull'
+        | 'dryRun'
+        | 'isIsolated'
+        | 'limit'
+    >,
+): void {
+    if (options.checkCommand !== undefined && !options.checkCommand.trim()) {
+        throw new NotAllowed(
+            spaceTrim(`
+            Option \`--check\` requires a non-empty shell command, for example \`npm run check\`.
+        `),
+        );
+    }
+    if (!isCheckBeforeMode(options.checkBefore ?? 'no')) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid ${'`--check-before`'} mode: \`${String(options.checkBefore)}\`.
+
+                Use one of: \`no\`, \`yes-and-fail\`, \`yes-and-fix\`.
+            `),
+        );
+    }
+
+    if (options.allowDestructiveAutoMigrate && !options.autoMigrate) {
+        throw new DatabaseError(
+            spaceTrim(`
+                Flag \`--allow-destructive-auto-migrate\` requires \`--auto-migrate\`.
+            `),
+        );
+    }
+
+    if (options.noCommit && !options.waitForUser && options.gitChanges !== 'ignore') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--no-commit\` requires \`--git-changes ignore\` when running in auto mode (the default; pass \`--no-auto\` for interactive confirmation).
+
+                Without commits, the next prompt round would fail the clean working tree check.
+            `),
+        );
+    }
+
+    if (options.autoPull && options.noCommit && !options.dryRun) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--auto-pull\` requires commits, so it cannot be combined with \`--no-commit\`.
+
+                Auto-pull keeps the repository up to date between prompt rounds, which requires each successful round to end with a clean committed working tree.
+            `),
+        );
+    }
+
+    if (options.isIsolated && options.noCommit) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--isolate\` cannot be combined with \`--no-commit\`.
+
+                An isolated task is implemented in a temporary worktree and reaches the original branch only through a merge, which requires the round to end with a commit.
+            `),
+        );
+    }
+
+    if (options.isIsolated && options.gitChanges === 'continue') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--isolate\` cannot be combined with \`--git-changes continue\`.
+
+                An isolated task is implemented in a fresh temporary worktree checked out from the last commit, so the uncommitted changes of the interrupted prompt would be left behind instead of being continued.
+            `),
+        );
+    }
+
+    if (options.gitChanges === 'continue' && options.checkBefore === 'yes-and-fix') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--git-changes continue\` cannot be combined with \`--check-before yes-and-fix\`.
+
+                An interrupted prompt already has changes in progress, so there is no unmodified project state for pre-coding verification to repair.
+            `),
+        );
+    }
+
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit <= 0)) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--limit\` expects a positive integer.
+
+                Received: \`${options.limit}\`
+            `),
+        );
+    }
+}
+
+// Note: [🟡] Code for Coder run validation [validateCoderRunOptions](src/cli/cli-commands/common/validateCoderRunOptions.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/workspaceRepository.md

@@ -0,0 +1,46 @@
+<!-- cspell:ignore pathspecs noninteractive -->
+
+# Workspace Git prerequisite
+
+Every registered Coder workspace action uses `$preflightWorkspaceRepository` before project writes,
+Git synchronization, harness setup, execution, or server startup. Command argument validation runs first;
+help, version and usage errors do not run preflight. The same helper is available for the subsequent
+workspace `ptbk server` entrypoint and its `ptbk coder server` alias.
+
+| Registered action | Policy | Reason |
+| --- | --- | --- |
+| `ptbk init`, `coder init`, `coder initialize` | Initialization | Explicit authorization to create missing Git metadata, then reuse the existing additive initializer. |
+| `coder add` | Potentially mutating | Authors a prompt in the project queue. |
+| `coder plan` | Potentially mutating | Creates a planning workspace, runs a harness and saves reviewed PRDs. |
+| `coder generate-boilerplates` | Potentially mutating | Generates starter prompt files and scan caches. |
+| `coder find-refactor-candidates` | Potentially mutating | Scans source and generates refactor prompts. |
+| `coder run` | Potentially mutating | Runs tests and a harness, updates task state and may synchronize Git. |
+| `coder ping` | Potentially mutating | May install a harness, augment ignore rules, and create temporary harness artifacts. |
+| `coder server` | Potentially mutating | Starts the server and runner; browser edits also mutate PRDs. |
+| `coder verify` | Potentially mutating | Updates statuses, writes repair prompts and archives completed files. There is no separate archive action. |
+| `coder list` | Read-only | Lists ready prompts and optional runner filters. |
+| `coder find-unwritten` | Read-only | Inspects authoring placeholders. |
+| `coder find-fresh-emoji-tags` | Read-only | Scans existing tags without writing its optional cache. |
+| `coder run --dry-run`, `coder server --dry-run` | Read-only preview | Prints authoring work without installation, writes or server startup. |
+
+Discovery resolves the project directory once and uses Git to find the enclosing working tree, including
+linked worktrees and submodules. The project directory stays separate from the repository root: Books,
+prompts and initialization artifacts stay in the requested project; Git snapshots and pathspecs use the
+repository root. Isolated execution maps that project location into its temporary working tree and copies the
+project environment there. Unborn branches are valid. Discovery never requires a remote or a Git identity.
+
+Only genuinely missing repositories may be initialized. Missing Git, bare repositories, broken metadata,
+permission errors and ownership failures stop with diagnostics; no global `safe.directory` changes are made.
+Damaged inner metadata is rejected even when Git skips it and discovers a valid parent repository.
+Read-only operations warn for absent repositories. Other actions ask once in a terminal and continue after
+successful initialization. Declining or cancelling stops before normal effects. `--no-questions` and
+noninteractive input fail immediately and suggest `ptbk init`, `ptbk coder init`, or `git init`.
+
+Explicit initialization needs no Git confirmation, even with `--no-questions`. Existing Git metadata is reused
+without staging, committing or changing configuration. Optional `--auto-pull` runs after Git validation;
+`--commit` uses the existing scoped change snapshot, including before the first commit. Unrelated staged,
+unstaged and untracked files stay outside initialization commits. Remote synchronization still needs the
+user's configured remote and identity. Partial initialization failures report completed setup steps.
+
+Tests use temporary repositories and mocked prompts or harnesses. The packed CLI fixture exercises the
+top-level initializer and no-repository recovery outside this monorepo without network access.