@open-agent-toolkit/cli 0.0.10

package/dist/commands/docs/analyze.d.ts

@@ -0,0 +1,8 @@
+import { type CommandContext, type GlobalOptions } from '../../app/command-context.js';
+import { Command } from 'commander';
+interface DocsAnalyzeDependencies {
+    buildCommandContext: (options: GlobalOptions) => CommandContext;
+}
+export declare function createDocsAnalyzeCommand(overrides?: Partial<DocsAnalyzeDependencies>): Command;
+export {};
+//# sourceMappingURL=analyze.d.ts.map

package/dist/commands/docs/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,UAAU,uBAAuB;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;CACjE;AAoCD,wBAAgB,wBAAwB,CACtC,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CAcT"}

package/dist/commands/docs/analyze.js

@@ -0,0 +1,45 @@
+import { buildCommandContext, } from '../../app/command-context.js';
+import { readGlobalOptions } from '../shared/shared.utils.js';
+import { Command } from 'commander';
+const DEFAULT_DEPENDENCIES = {
+    buildCommandContext,
+};
+function buildAnalyzeGuidance() {
+    return {
+        status: 'ok',
+        command: 'oat docs analyze',
+        skill: 'oat-docs-analyze',
+        artifactDirectory: '.oat/repo/analysis',
+        message: 'Docs analysis currently runs through the oat-docs-analyze skill.',
+        nextSteps: [
+            'Run oat-docs-analyze to generate a docs analysis artifact.',
+            'Review the generated artifact in .oat/repo/analysis/.',
+            'Use oat docs apply after analysis is available.',
+        ],
+    };
+}
+async function runDocsAnalyzeCommand(context) {
+    const guidance = buildAnalyzeGuidance();
+    if (context.json) {
+        context.logger.json(guidance);
+    }
+    else {
+        context.logger.info(guidance.message);
+        context.logger.info('  Skill: oat-docs-analyze');
+        context.logger.info('  Artifact dir: .oat/repo/analysis');
+        context.logger.info('  Next: run oat docs apply after reviewing findings.');
+    }
+    process.exitCode = 0;
+}
+export function createDocsAnalyzeCommand(overrides = {}) {
+    const dependencies = {
+        ...DEFAULT_DEPENDENCIES,
+        ...overrides,
+    };
+    return new Command('analyze')
+        .description('Run the docs analysis workflow')
+        .action(async (_options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        await runDocsAnalyzeCommand(context);
+    });
+}

package/dist/commands/docs/apply.d.ts

@@ -0,0 +1,8 @@
+import { type CommandContext, type GlobalOptions } from '../../app/command-context.js';
+import { Command } from 'commander';
+interface DocsApplyDependencies {
+    buildCommandContext: (options: GlobalOptions) => CommandContext;
+}
+export declare function createDocsApplyCommand(overrides?: Partial<DocsApplyDependencies>): Command;
+export {};
+//# sourceMappingURL=apply.d.ts.map

package/dist/commands/docs/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/apply.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,UAAU,qBAAqB;IAC7B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;CACjE;AAoCD,wBAAgB,sBAAsB,CACpC,SAAS,GAAE,OAAO,CAAC,qBAAqB,CAAM,GAC7C,OAAO,CAcT"}

package/dist/commands/docs/apply.js

@@ -0,0 +1,45 @@
+import { buildCommandContext, } from '../../app/command-context.js';
+import { readGlobalOptions } from '../shared/shared.utils.js';
+import { Command } from 'commander';
+const DEFAULT_DEPENDENCIES = {
+    buildCommandContext,
+};
+function buildApplyGuidance() {
+    return {
+        status: 'ok',
+        command: 'oat docs apply',
+        skill: 'oat-docs-apply',
+        artifactDirectory: '.oat/repo/analysis',
+        message: 'Docs apply currently runs through the oat-docs-apply skill.',
+        nextSteps: [
+            'Confirm a recent docs analysis artifact exists in .oat/repo/analysis/.',
+            'Run oat-docs-apply to review recommendations and approve changes.',
+            'Use the generated branch and PR flow from the apply skill.',
+        ],
+    };
+}
+async function runDocsApplyCommand(context) {
+    const guidance = buildApplyGuidance();
+    if (context.json) {
+        context.logger.json(guidance);
+    }
+    else {
+        context.logger.info(guidance.message);
+        context.logger.info('  Skill: oat-docs-apply');
+        context.logger.info('  Requires: latest docs analysis artifact');
+        context.logger.info('  Artifact dir: .oat/repo/analysis');
+    }
+    process.exitCode = 0;
+}
+export function createDocsApplyCommand(overrides = {}) {
+    const dependencies = {
+        ...DEFAULT_DEPENDENCIES,
+        ...overrides,
+    };
+    return new Command('apply')
+        .description('Run the docs apply workflow')
+        .action(async (_options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        await runDocsApplyCommand(context);
+    });
+}

package/dist/commands/docs/index-generate/generator.d.ts

@@ -0,0 +1,9 @@
+export interface IndexEntry {
+    title: string;
+    description?: string;
+    path: string;
+    children?: IndexEntry[];
+}
+export declare function generateIndex(docsDir: string): Promise<IndexEntry[]>;
+export declare function renderIndex(entries: IndexEntry[]): string;
+//# sourceMappingURL=generator.d.ts.map

package/dist/commands/docs/index-generate/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/generator.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;CACzB;AA4ED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAiC1E;AAmBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAMzD"}

package/dist/commands/docs/index-generate/generator.js

@@ -0,0 +1,114 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
+const HEADING_RE = /^#\s+(.+)$/m;
+function fileNameToTitle(fileName) {
+    return fileName
+        .replace(/\.md$/, '')
+        .split(/[-_]/g)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
+function parseFrontmatter(content) {
+    const match = FRONTMATTER_RE.exec(content);
+    if (!match) {
+        return {};
+    }
+    const fm = match[1];
+    const titleMatch = /^title:\s*(.+)$/m.exec(fm);
+    const descMatch = /^description:\s*(.+)$/m.exec(fm);
+    return {
+        title: titleMatch?.[1]?.trim().replace(/^["']|["']$/g, '') || undefined,
+        description: descMatch?.[1]?.trim().replace(/^["']|["']$/g, '') || undefined,
+    };
+}
+function resolveTitle(content, fileName) {
+    const fm = parseFrontmatter(content);
+    if (fm.title) {
+        return { title: fm.title, description: fm.description };
+    }
+    const headingMatch = HEADING_RE.exec(content);
+    if (headingMatch) {
+        return { title: headingMatch[1].trim(), description: fm.description };
+    }
+    return { title: fileNameToTitle(fileName), description: fm.description };
+}
+function sortEntries(entries) {
+    return entries.sort((a, b) => {
+        // index.md always first
+        const aIsIndex = a.path.endsWith('index.md');
+        const bIsIndex = b.path.endsWith('index.md');
+        if (aIsIndex && !bIsIndex)
+            return -1;
+        if (!aIsIndex && bIsIndex)
+            return 1;
+        // directories (entries with children) before files
+        const aIsDir = a.children !== undefined;
+        const bIsDir = b.children !== undefined;
+        if (aIsDir && !bIsDir)
+            return -1;
+        if (!aIsDir && bIsDir)
+            return 1;
+        return a.path.localeCompare(b.path);
+    });
+}
+function prefixEntryPath(entry, prefix) {
+    return {
+        ...entry,
+        path: join(prefix, entry.path),
+        children: entry.children?.map((child) => prefixEntryPath(child, prefix)),
+    };
+}
+export async function generateIndex(docsDir) {
+    const entries = [];
+    const subdirs = [];
+    const dirEntries = await readdir(docsDir, { withFileTypes: true });
+    for (const entry of dirEntries) {
+        if (entry.isDirectory()) {
+            subdirs.push(entry.name);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            const filePath = join(docsDir, entry.name);
+            const content = await readFile(filePath, 'utf8');
+            const { title, description } = resolveTitle(content, entry.name);
+            entries.push({
+                title,
+                description: description || undefined,
+                path: entry.name,
+            });
+        }
+    }
+    for (const subdir of subdirs.sort()) {
+        const children = await generateIndex(join(docsDir, subdir));
+        if (children.length > 0) {
+            entries.push({
+                title: fileNameToTitle(subdir),
+                path: subdir,
+                children: children.map((child) => prefixEntryPath(child, subdir)),
+            });
+        }
+    }
+    return sortEntries(entries);
+}
+function renderEntries(entries, indent) {
+    const lines = [];
+    const prefix = '  '.repeat(indent);
+    for (const entry of entries) {
+        if (entry.children) {
+            lines.push(`${prefix}- ${entry.title}`);
+            lines.push(...renderEntries(entry.children, indent + 1));
+        }
+        else {
+            const desc = entry.description ? ` — ${entry.description}` : '';
+            lines.push(`${prefix}- [${entry.title}](${entry.path})${desc}`);
+        }
+    }
+    return lines;
+}
+export function renderIndex(entries) {
+    if (entries.length === 0) {
+        return '';
+    }
+    return `${renderEntries(entries, 0).join('\n')}\n`;
+}

package/dist/commands/docs/index-generate/index.d.ts

@@ -0,0 +1,16 @@
+import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
+import { Command } from 'commander';
+interface IndexGenerateFileDependencies {
+    generateIndex: (docsDir: string) => Promise<import('./generator.js').IndexEntry[]>;
+    renderIndex: (entries: import('./generator.js').IndexEntry[]) => string;
+    writeFile: (path: string, content: string, encoding: BufferEncoding) => Promise<void>;
+    readOatConfig: (repoRoot: string) => Promise<import('../../../config/oat-config.js').OatConfig>;
+    writeOatConfig: (repoRoot: string, config: import('../../../config/oat-config.js').OatConfig) => Promise<void>;
+}
+interface IndexGenerateDependencies {
+    buildCommandContext: (options: GlobalOptions) => CommandContext;
+    fileDeps: IndexGenerateFileDependencies;
+}
+export declare function createDocsGenerateIndexCommand(overrides?: Partial<IndexGenerateDependencies>): Command;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/docs/index-generate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAS5C,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CACb,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,OAAO,oBAAoB,EAAE,SAAS,CAAC,CAAC;IACrD,cAAc,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,oBAAoB,EAAE,SAAS,KAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAsED,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsBT"}

package/dist/commands/docs/index-generate/index.js

@@ -0,0 +1,72 @@
+import { writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { buildCommandContext, } from '../../../app/command-context.js';
+import { readGlobalOptions } from '../../shared/shared.utils.js';
+import { readOatConfig, writeOatConfig } from '../../../config/oat-config.js';
+import { Command, Option } from 'commander';
+import { generateIndex, renderIndex } from './generator.js';
+const DEFAULT_FILE_DEPS = {
+    generateIndex,
+    renderIndex,
+    writeFile,
+    readOatConfig,
+    writeOatConfig,
+};
+const DEFAULT_DEPENDENCIES = {
+    buildCommandContext,
+    fileDeps: DEFAULT_FILE_DEPS,
+};
+async function runIndexGenerate(context, options, deps) {
+    const docsDir = join(context.cwd, options.docsDir);
+    const outputPath = options.output
+        ? join(context.cwd, options.output)
+        : join(context.cwd, 'index.md');
+    const entries = await deps.generateIndex(docsDir);
+    const content = deps.renderIndex(entries);
+    await deps.writeFile(outputPath, content, 'utf8');
+    const config = await deps.readOatConfig(context.cwd);
+    config.documentation = {
+        ...config.documentation,
+        index: relative(context.cwd, outputPath) || 'index.md',
+    };
+    await deps.writeOatConfig(context.cwd, config);
+    if (context.json) {
+        context.logger.json({
+            status: 'ok',
+            entriesGenerated: entries.length,
+            outputPath,
+        });
+        return;
+    }
+    context.logger.info(`Generated index with ${entries.length} entries → ${outputPath}`);
+}
+async function runIndexGenerateCommand(context, options, dependencies) {
+    try {
+        await runIndexGenerate(context, options, dependencies.fileDeps);
+        process.exitCode = 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (context.json) {
+            context.logger.json({ status: 'error', message });
+        }
+        else {
+            context.logger.error(message);
+        }
+        process.exitCode = 1;
+    }
+}
+export function createDocsGenerateIndexCommand(overrides = {}) {
+    const dependencies = {
+        ...DEFAULT_DEPENDENCIES,
+        ...overrides,
+    };
+    return new Command('generate-index')
+        .description('Generate a docs index from markdown files')
+        .addOption(new Option('--docs-dir <path>', 'Documentation source directory').default('docs'))
+        .addOption(new Option('--output <path>', 'Output file path (default: index.md)'))
+        .action(async (options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        await runIndexGenerateCommand(context, options, dependencies);
+    });
+}

package/dist/commands/docs/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createDocsCommand(): Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/docs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,wBAAgB,iBAAiB,IAAI,OAAO,CAS3C"}

package/dist/commands/docs/index.js

@@ -0,0 +1,17 @@
+import { Command } from 'commander';
+import { createDocsAnalyzeCommand } from './analyze.js';
+import { createDocsApplyCommand } from './apply.js';
+import { createDocsGenerateIndexCommand } from './index-generate/index.js';
+import { createDocsInitCommand } from './init/index.js';
+import { createDocsMigrateCommand } from './migrate/index.js';
+import { createDocsNavCommand } from './nav/index.js';
+export function createDocsCommand() {
+    return new Command('docs')
+        .description('OAT documentation bootstrap and maintenance commands')
+        .addCommand(createDocsAnalyzeCommand())
+        .addCommand(createDocsApplyCommand())
+        .addCommand(createDocsGenerateIndexCommand())
+        .addCommand(createDocsInitCommand())
+        .addCommand(createDocsMigrateCommand())
+        .addCommand(createDocsNavCommand());
+}

package/dist/commands/docs/init/index.d.ts

@@ -0,0 +1,18 @@
+import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
+import { type UpsertSectionResult } from '../../shared/agents-md.js';
+import { type PromptContext, type SelectChoice } from '../../shared/shared.prompts.js';
+import { Command } from 'commander';
+import { type DocsInitResolvedOptions } from './resolve-options.js';
+interface DocsInitDependencies {
+    buildCommandContext: (options: GlobalOptions) => CommandContext;
+    resolveAssetsRoot: () => Promise<string>;
+    detectRepoShape: (repoRoot: string) => Promise<'monorepo' | 'single-package'>;
+    inputWithDefault: (message: string, defaultValue: string, ctx: PromptContext) => Promise<string | null>;
+    selectWithAbort: <T extends string>(message: string, choices: SelectChoice<T>[], ctx: PromptContext) => Promise<T | null>;
+    runDocsInit: (context: CommandContext, options: DocsInitResolvedOptions, assetsRoot: string) => Promise<void>;
+    upsertAgentsMdSection: (repoRoot: string, key: string, body: string) => Promise<UpsertSectionResult>;
+}
+export declare function buildDocsSectionBody(options: DocsInitResolvedOptions): string;
+export declare function createDocsInitCommand(overrides?: Partial<DocsInitDependencies>): Command;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/docs/init/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAIzC,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAE5C,OAAO,EAIL,KAAK,uBAAuB,EAI7B,MAAM,mBAAmB,CAAC;AAa3B,UAAU,oBAAoB;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,gBAAgB,CAAC,CAAC;IAC9E,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,WAAW,EAAE,CACX,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACnC;AA+CD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAc7E;AAyDD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CAgCT"}

package/dist/commands/docs/init/index.js

@@ -0,0 +1,129 @@
+import { buildCommandContext, } from '../../../app/command-context.js';
+import { upsertAgentsMdSection, } from '../../shared/agents-md.js';
+import { inputWithDefault, selectWithAbort, } from '../../shared/shared.prompts.js';
+import { readGlobalOptions } from '../../shared/shared.utils.js';
+import { readOatConfig, writeOatConfig } from '../../../config/oat-config.js';
+import { resolveAssetsRoot } from '../../../fs/assets.js';
+import { Command, Option } from 'commander';
+import { DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES, detectDocsRepoShape, resolveDocsInitOptions, } from './resolve-options.js';
+import { scaffoldDocsApp } from './scaffold.js';
+const DEFAULT_DEPENDENCIES = {
+    buildCommandContext,
+    resolveAssetsRoot,
+    detectRepoShape: (repoRoot) => detectDocsRepoShape(repoRoot, DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES),
+    inputWithDefault,
+    selectWithAbort,
+    runDocsInit: async (context, options, assetsRoot) => {
+        const result = await scaffoldDocsApp({
+            assetsRoot,
+            ...options,
+        });
+        const config = await readOatConfig(context.cwd);
+        config.documentation = {
+            ...config.documentation,
+            ...result.documentationConfig,
+        };
+        await writeOatConfig(context.cwd, config);
+        if (context.json) {
+            context.logger.json({
+                status: 'ok',
+                ...options,
+                createdFiles: result.createdFiles,
+                appRoot: result.appRoot,
+            });
+            return;
+        }
+        context.logger.info(`Scaffolded docs app at ${options.targetDir}`);
+        context.logger.info(`  Framework: ${options.framework}`);
+        context.logger.info(`  Repo shape: ${options.repoShape}`);
+        context.logger.info(`  App name: ${options.appName}`);
+        context.logger.info(`  Lint: ${options.lint}`);
+        context.logger.info(`  Format: ${options.format}`);
+    },
+    upsertAgentsMdSection,
+};
+const FRAMEWORK_LABELS = {
+    fumadocs: 'Fumadocs (Next.js + MDX)',
+    mkdocs: 'MkDocs (Python)',
+};
+export function buildDocsSectionBody(options) {
+    const lines = [
+        '## Documentation',
+        '',
+        `- **Docs root:** \`${options.targetDir}\``,
+        `- **Framework:** ${FRAMEWORK_LABELS[options.framework]}`,
+        `- **Index file:** \`${options.targetDir}/docs/index.md\``,
+    ];
+    if (options.framework === 'mkdocs') {
+        lines.push(`- **Config:** \`${options.targetDir}/mkdocs.yml\``);
+    }
+    return lines.join('\n');
+}
+async function runDocsInitCommand(context, options, dependencies) {
+    try {
+        const repoShape = await dependencies.detectRepoShape(context.cwd);
+        const resolved = await resolveDocsInitOptions({
+            repoRoot: context.cwd,
+            repoShape,
+            interactive: context.interactive,
+            acceptDefaults: options.yes ?? false,
+            providedFramework: options.framework,
+            providedAppName: options.appName,
+            providedTargetDir: options.targetDir,
+            providedSiteDescription: options.description,
+            providedLint: options.lint,
+            providedFormat: options.format,
+            inputWithDefault: dependencies.inputWithDefault,
+            selectWithAbort: dependencies.selectWithAbort,
+        });
+        if (!resolved) {
+            if (!context.json) {
+                context.logger.info('Docs init cancelled.');
+            }
+            process.exitCode = 0;
+            return;
+        }
+        const assetsRoot = await dependencies.resolveAssetsRoot();
+        await dependencies.runDocsInit(context, resolved, assetsRoot);
+        const sectionBody = buildDocsSectionBody(resolved);
+        const sectionResult = await dependencies.upsertAgentsMdSection(context.cwd, 'docs', sectionBody);
+        if (!context.json && sectionResult.action !== 'no-change') {
+            context.logger.info(`AGENTS.md docs section ${sectionResult.action}.`);
+        }
+        process.exitCode = 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (context.json) {
+            context.logger.json({ status: 'error', message });
+        }
+        else {
+            context.logger.error(message);
+        }
+        process.exitCode = 1;
+    }
+}
+export function createDocsInitCommand(overrides = {}) {
+    const dependencies = {
+        ...DEFAULT_DEPENDENCIES,
+        ...overrides,
+    };
+    return new Command('init')
+        .description('Scaffold an OAT docs app')
+        .addOption(new Option('--framework <framework>', 'Documentation framework').choices([
+        'fumadocs',
+        'mkdocs',
+    ]))
+        .addOption(new Option('--app-name <name>', 'Docs app name'))
+        .addOption(new Option('--target-dir <path>', 'Target directory for the docs app'))
+        .addOption(new Option('--description <text>', 'Site description'))
+        .addOption(new Option('--format <mode>', 'Markdown format mode').choices([
+        'oxfmt',
+        'none',
+    ]))
+        .option('--yes', 'Accept defaults without prompting')
+        .action(async (options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        await runDocsInitCommand(context, options, dependencies);
+    });
+}

package/dist/commands/docs/init/resolve-options.d.ts

@@ -0,0 +1,41 @@
+import type { PromptContext, SelectChoice } from '../../shared/shared.prompts.js';
+export type DocsRepoShape = 'monorepo' | 'single-package';
+export type DocsFramework = 'fumadocs' | 'mkdocs';
+export type DocsLintMode = 'none';
+export type DocsFormatMode = 'oxfmt' | 'none';
+export interface DocsInitResolvedOptions {
+    repoRoot: string;
+    repoShape: DocsRepoShape;
+    framework: DocsFramework;
+    appName: string;
+    targetDir: string;
+    siteDescription: string;
+    lint: DocsLintMode;
+    format: DocsFormatMode;
+}
+export interface ResolveDocsInitOptionsInput {
+    repoRoot: string;
+    repoShape: DocsRepoShape;
+    interactive: boolean;
+    acceptDefaults: boolean;
+    providedFramework?: DocsFramework;
+    providedAppName?: string;
+    providedTargetDir?: string;
+    providedSiteDescription?: string;
+    providedLint?: DocsLintMode;
+    providedFormat?: DocsFormatMode;
+    inputWithDefault: (message: string, defaultValue: string, ctx: PromptContext) => Promise<string | null>;
+    selectWithAbort: <T extends string>(message: string, choices: SelectChoice<T>[], ctx: PromptContext) => Promise<T | null>;
+}
+export interface DocsRepoShapeDependencies {
+    fileExists: (path: string) => Promise<boolean>;
+    dirExists: (path: string) => Promise<boolean>;
+    readFile: (path: string, encoding: BufferEncoding) => Promise<string>;
+}
+export declare function getDefaultDocsAppName(repoRoot: string, repoShape: DocsRepoShape): string;
+export declare function getDefaultDocsTargetDir(repoShape: DocsRepoShape, appName: string): string;
+export declare function detectDocsRepoShape(repoRoot: string, dependencies: DocsRepoShapeDependencies): Promise<DocsRepoShape>;
+export declare function getTemplateDir(framework: DocsFramework): string;
+export declare function resolveDocsInitOptions(input: ResolveDocsInitOptionsInput): Promise<DocsInitResolvedOptions | null>;
+export declare const DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES: DocsRepoShapeDependencies;
+//# sourceMappingURL=resolve-options.d.ts.map

package/dist/commands/docs/init/resolve-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-options.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/resolve-options.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACb,MAAM,iCAAiC,CAAC;AAGzC,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,QAAQ,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,aAAa,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE;AAgBD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,aAAa,GACvB,MAAM,CAMR;AAED,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,MAAM,GACd,MAAM,CAMR;AAoBD,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,yBAAyB,GACtC,OAAO,CAAC,aAAa,CAAC,CAqBxB;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,aAAa,GAAG,MAAM,CAE/D;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CA+EzC;AAED,eAAO,MAAM,oCAAoC,EAAE,yBAOlD,CAAC"}