@open-agent-toolkit/cli 0.3.27 → 0.3.29

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

@@ -9,6 +9,7 @@ import { readOatConfig, writeOatConfig, } from '../../../config/oat-config.js';
 import { resolveAssetsRoot } from '../../../fs/assets.js';
 import { atomicWriteJson, fileExists } from '../../../fs/io.js';
 import { Command, Option } from 'commander';
+import { mergeTemplateExclusion } from './content.js';
 import { buildDocsCommands } from './docs-commands.js';
 import { applyMarkdownDocsPlan, MarkdownDocsWriteError, planMarkdownDocs, validateMarkdownConfig, validateMarkdownTarget, } from './markdown.js';
 import { DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES, detectDocsRepoShape, getDefaultDocsAppName, resolveDocsInitOptions, } from './resolve-options.js';
@@ -107,8 +108,27 @@ const DEFAULT_DEPENDENCIES = {
                         root: plan.targetDir,
                         tooling: 'markdown',
                         index: `${plan.targetDir}/index.md`,
+                        ...(options.iaPreset
+                            ? {
+                                nonReaderPaths: mergeTemplateExclusion(latest.documentation?.nonReaderPaths),
+                            }
+                            : {}),
                     };
-                    await writeOatConfig(context.cwd, latest);
+                    if (options.iaPreset) {
+                        const configPath = join(context.cwd, '.oat/config.json');
+                        const raw = (await fileExists(configPath))
+                            ? JSON.parse(await readFile(configPath, 'utf8'))
+                            : latest;
+                        await atomicWriteJson(configPath, {
+                            ...raw,
+                            documentation: {
+                                ...raw.documentation,
+                                ...latest.documentation,
+                            },
+                        });
+                    }
+                    else
+                        await writeOatConfig(context.cwd, latest);
                     report.configStatus = 'updated';
                 }
                 catch (error) {
@@ -145,6 +165,8 @@ const DEFAULT_DEPENDENCIES = {
             enabled: options.rootPatch,
         });
         const config = await readOatConfig(context.cwd);
+        if (options.iaPreset)
+            result.documentationConfig.nonReaderPaths = mergeTemplateExclusion(config.documentation?.nonReaderPaths);
         config.documentation = {
             ...config.documentation,
             ...result.documentationConfig,
@@ -176,11 +198,16 @@ const DEFAULT_DEPENDENCIES = {
             context.logger.info(`  Format: ${options.format}`);
             if (rootPackagePatch)
                 logRootPackagePatch(context, rootPackagePatch);
+            for (const advice of result.installationAdvice ?? [])
+                context.logger.info(advice);
         }
         return {
             createdFiles: result.createdFiles,
             appRoot: result.appRoot,
             rootPackagePatch,
+            ...(result.installationAdvice
+                ? { installationAdvice: result.installationAdvice }
+                : {}),
         };
     },
     upsertAgentsMdSection,
@@ -245,6 +272,8 @@ async function runDocsInitCommand(context, options, dependencies) {
             interactive: context.interactive,
             acceptDefaults: options.yes ?? false,
             providedFramework: options.framework,
+            providedIaPreset: options.iaPreset,
+            providedPlannedPages: options.plannedPages,
             providedAdopt: options.adopt,
             providedAppName: options.appName,
             providedSiteName: options.siteName,
@@ -271,6 +300,11 @@ async function runDocsInitCommand(context, options, dependencies) {
         }
         const inapplicableOptions = [];
         const existingConfig = await dependencies.readOatConfig(context.cwd);
+        if (resolved.iaPreset &&
+            (existingConfig.documentation?.root ||
+                existingConfig.documentation?.ia ||
+                existingConfig.documentation?.navOwner))
+            throw new Error('Preset init cannot replace an existing docs surface or navigation ownership. Use oat-docs-analyze and individually approved oat-docs-apply.');
         if (resolved.framework === 'markdown') {
             resolved.targetDir = await validateMarkdownTarget(context.cwd, resolved.targetDir);
             validateMarkdownConfig(context.cwd, resolved.targetDir, existingConfig.documentation);
@@ -384,6 +418,9 @@ async function runDocsInitCommand(context, options, dependencies) {
                         framework: resolved.framework,
                     },
                     guidance: sectionResult,
+                    ...(scaffold?.installationAdvice
+                        ? { installationAdvice: scaffold.installationAdvice }
+                        : {}),
                 });
             }
             else {
@@ -456,6 +493,8 @@ export function createDocsInitCommand(overrides = {}) {
         .addOption(new Option('--app-name <name>', 'Docs app name (inapplicable to Markdown)'))
         .addOption(new Option('--site-name <name>', 'Site display title or Markdown documentation title'))
         .addOption(new Option('--target-dir <path>', 'Docs directory (Markdown defaults to docs; requires a dedicated directory)'))
+        .option('--ia-preset <preset>', 'Approved IA preset (requires --planned-pages; fresh empty target only)')
+        .option('--planned-pages <count>', 'Anticipated reader pages: integer >=1; collapse below 15 (requires --ia-preset)')
         .addOption(new Option('--description <text>', 'Documentation description'))
         .addOption(new Option('--lint <mode>', 'Markdown lint mode').choices([
         'none',

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

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/markdown.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAKjE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,mBAAmB,CAAC;AAE3B,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CA0CjB;AAsBD,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,sBAAsB,CAAC;IAC5C,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,QAAQ,CAAC,MAAM,EAAE,kBAAkB;IAFrC,YACE,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,kBAAkB,EACnC,KAAK,EAAE,OAAO,EAGf;CACF;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,sBAAsB,GAChC,IAAI,CAeN;AA6JD,kEAAkE;AAClE,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CA2E3B;AAED,kFAAkF;AAClF,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CA8E7B"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/markdown.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAMjE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,mBAAmB,CAAC;AAE3B,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CA0CjB;AAsBD,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,sBAAsB,CAAC;IAC5C,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,QAAQ,CAAC,MAAM,EAAE,kBAAkB;IAFrC,YACE,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,kBAAkB,EACnC,KAAK,EAAE,OAAO,EAGf;CACF;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,sBAAsB,GAChC,IAAI,CAeN;AA6JD,kEAAkE;AAClE,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CAuG3B;AAED,kFAAkF;AAClF,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CA+E7B"}

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

@@ -4,6 +4,7 @@ import { createExclusionMatcher } from '../../docs/index-generate/generator.js';
 import { dirExists, ensureDir } from '../../../fs/io.js';
 import { normalizeToPosixPath, validatePathWithinScope } from '../../../fs/paths.js';
 import { parse as parseYaml } from 'yaml';
+import { mergeTemplateExclusion, planPresetContent } from './content.js';
 import { humanizeAppName, } from './resolve-options.js';
 /** Validate a dedicated Markdown root, including existing symlink ancestors. */
 export async function validateMarkdownTarget(repoRoot, targetDir) {
@@ -192,15 +193,27 @@ export async function planMarkdownDocs(options) {
         (await readdir(appRoot)).length > 0) {
         throw new Error(`Markdown docs target is not empty: ${targetDir}. Use --adopt to preserve existing docs, then run oat-docs-analyze for content gaps.`);
     }
+    if (options.iaPreset &&
+        (await dirExists(appRoot)) &&
+        (await readdir(appRoot)).length > 0)
+        throw new Error('Preset init requires an empty docs target. Preserve existing docs and use oat-docs-analyze with individually approved oat-docs-apply.');
+    const contentPlan = await planPresetContent({ ...options, markdown: true });
     const documentationConfig = {
         ...options.documentation,
         root: targetDir,
         tooling: 'markdown',
         index: `${targetDir}/index.md`,
+        ...(contentPlan
+            ? {
+                nonReaderPaths: mergeTemplateExclusion(options.documentation?.nonReaderPaths),
+            }
+            : {}),
     };
     const configChanged = options.documentation?.root !== targetDir ||
         options.documentation?.tooling !== 'markdown' ||
-        options.documentation?.index !== `${targetDir}/index.md`;
+        options.documentation?.index !== `${targetDir}/index.md` ||
+        (contentPlan !== null &&
+            !options.documentation?.nonReaderPaths?.includes('contributing/templates/**'));
     const existing = new Map();
     for (const name of ['index.md', 'contributing.md'])
         existing.set(name, await readBaseline(options.repoRoot, join(appRoot, name)));
@@ -223,9 +236,14 @@ export async function planMarkdownDocs(options) {
         const template = await readFile(join(options.assetsRoot, 'templates', 'docs-markdown', name), 'utf8');
         files.push({
             name,
-            content: renderMarkdownTemplate(template, options, contents),
+            content: (contentPlan?.files.find((file) => file.name === name)?.content ??
+                renderMarkdownTemplate(template, options, contents)) +
+                (contentPlan && name === 'contributing.md'
+                    ? `\n${contentPlan.guidance}`
+                    : ''),
         });
     }
+    files.push(...(contentPlan?.files.filter((file) => file.name !== 'index.md') ?? []));
     return {
         repoRoot: options.repoRoot,
         targetDir,
@@ -254,6 +272,7 @@ export async function applyMarkdownDocsPlan(plan) {
         for (const { name, content } of plan.files) {
             await validateMarkdownTarget(plan.repoRoot, plan.targetDir);
             const path = join(plan.appRoot, name);
+            await ensureDir(dirname(path));
             let handle;
             try {
                 handle = await open(path, 'wx');

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

@@ -1,10 +1,11 @@
 import type { PromptContext, SelectChoice } from '../../shared/shared.prompts.js';
+import { type PresetSelection } from './content.js';
 export type DocsRepoShape = 'monorepo' | 'single-package' | 'nested-standalone';
 export type DocsDetectedRepoShape = Exclude<DocsRepoShape, 'nested-standalone'>;
 export type DocsFramework = 'fumadocs' | 'mkdocs' | 'markdown';
 export type DocsLintMode = 'none' | 'markdownlint-cli2';
 export type DocsFormatMode = 'oxfmt' | 'none';
-export interface DocsInitResolvedOptions {
+export interface DocsInitResolvedOptions extends PresetSelection {
     repoRoot: string;
     repoShape: DocsRepoShape;
     framework: DocsFramework;
@@ -23,6 +24,8 @@ export interface ResolveDocsInitOptionsInput {
     interactive: boolean;
     acceptDefaults: boolean;
     providedFramework?: DocsFramework;
+    providedIaPreset?: string;
+    providedPlannedPages?: string;
     providedAdopt?: boolean;
     providedAppName?: string;
     providedSiteName?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"resolve-options.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/resolve-options.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolve-options.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/resolve-options.ts"],"names":[],"mappings":"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"}

package/dist/commands/docs/init/resolve-options.js

@@ -1,5 +1,6 @@
 import { basename, isAbsolute, join, relative, resolve } from 'node:path';
 import { dirExists, fileExists } from '../../../fs/io.js';
+import { resolvePresetSelection } from './content.js';
 const FRAMEWORK_CHOICES = [
     { label: 'Fumadocs (Next.js + MDX, static export)', value: 'fumadocs' },
     { label: 'MkDocs (Python, Material theme)', value: 'mkdocs' },
@@ -83,6 +84,7 @@ export function resolveEffectiveDocsShape(repoShape, framework, repoRoot, target
     return isRepoSubdirectory ? 'nested-standalone' : repoShape;
 }
 export async function resolveDocsInitOptions(input) {
+    const selection = resolvePresetSelection(input.providedIaPreset, input.providedPlannedPages);
     const ctx = { interactive: input.interactive };
     const framework = input.providedFramework ||
         (input.interactive && !input.acceptDefaults
@@ -109,6 +111,7 @@ export async function resolveDocsInitOptions(input) {
         if (!targetDir)
             return null;
         return {
+            ...selection,
             repoRoot: input.repoRoot,
             repoShape: input.repoShape,
             framework,
@@ -168,6 +171,7 @@ export async function resolveDocsInitOptions(input) {
     }
     const repoShape = resolveEffectiveDocsShape(input.repoShape, framework, input.repoRoot, targetDir);
     return {
+        ...selection,
         repoRoot: input.repoRoot,
         repoShape,
         framework,

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

@@ -7,6 +7,7 @@ export interface ScaffoldDocsAppResult {
     appRoot: string;
     createdFiles: string[];
     documentationConfig: OatDocumentationConfig;
+    installationAdvice?: string[];
 }
 export interface OatDepContext {
     isOatRepo: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/scaffold.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAMjE,OAAO,KAAK,EAEV,aAAa,EACb,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AAoG3B,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,MAAM,WAAW,2BAA2B;IAC1C,iBAAiB,EAAE,MAAM,YAAY,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACjE,0BAA0B,EAAE,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACZ,YAAY,CAAC,OAAO,CAAC,CAAC;CAC5B;AAUD,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE;AAgDD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAaxB;AA0ND;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,MAAM,GAChB,sBAAsB,CAwBxB;AA6CD,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAAC,qBAAqB,CAAC,CAyDhC"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/scaffold.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAOjE,OAAO,KAAK,EAEV,aAAa,EACb,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AAqG3B,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,sBAAsB,CAAC;IAC5C,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,MAAM,WAAW,2BAA2B;IAC1C,iBAAiB,EAAE,MAAM,YAAY,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACjE,0BAA0B,EAAE,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACZ,YAAY,CAAC,OAAO,CAAC,CAAC;CAC5B;AAUD,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE;AAgDD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAaxB;AAmOD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,MAAM,GAChB,sBAAsB,CAwBxB;AAyDD,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAAC,qBAAqB,CAAC,CA0GhC"}

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

@@ -1,7 +1,8 @@
-import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { readdir, readFile, realpath, writeFile } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, relative, resolve, } from 'node:path';
 import { dirExists, ensureDir, fileExists } from '../../../fs/io.js';
 import { OAT_VERSION } from '../../../shared/oat-version.js';
+import { planPresetContent } from './content.js';
 import { buildDocsCommands, shellQuote } from './docs-commands.js';
 import { applyMarkdownDocsPlan, planMarkdownDocs } from './markdown.js';
 import { getTemplateDir } from './resolve-options.js';
@@ -11,7 +12,7 @@ const MKDOCS_TEMPLATE_FILES = [
         source: join('docs', 'contributing', name),
         destination: join('docs', 'contributing', name),
     })),
-    { source: '.gitignore', destination: '.gitignore' },
+    { source: 'gitignore.template', destination: '.gitignore' },
     { source: 'mkdocs.yml', destination: 'mkdocs.yml' },
     { source: 'package.json.template', destination: 'package.json' },
     { source: 'requirements.txt', destination: 'requirements.txt' },
@@ -36,7 +37,8 @@ const FUMA_TEMPLATE_FILES = [
         source: join('app', route, 'route.ts'),
         destination: join('app', route, 'route.ts'),
     })),
-    { source: '.gitignore', destination: '.gitignore' },
+    { source: 'gitignore.template', destination: '.gitignore' },
+    { source: 'pnpm-workspace.yaml', destination: 'pnpm-workspace.yaml' },
     { source: 'next.config.js', destination: 'next.config.js' },
     { source: 'postcss.config.mjs', destination: 'postcss.config.mjs' },
     { source: 'source.config.ts', destination: 'source.config.ts' },
@@ -250,6 +252,8 @@ function renderTemplate(template, options, depContext, packageManagerField, node
         '{{PACKAGE_NAME}}': options.appName,
         '{{SITE_NAME}}': options.siteName,
         '{{SITE_DESCRIPTION}}': options.siteDescription,
+        '{{PAGE_DESCRIPTION}}': (options.siteDescription.trim() ||
+            `Reader guides and contributor information for ${options.siteName}.`).replaceAll("'", "''"),
         '{{INSTALL_CMD}}': commands.install,
         '{{DEV_CMD}}': commands.dev,
         '{{BUILD_CMD}}': commands.build,
@@ -273,6 +277,9 @@ function renderTemplate(template, options, depContext, packageManagerField, node
         '{{APP_CWD}}': shellQuote(options.targetDir),
         '{{LINT_STATUS}}': options.lint === 'none' ? 'disabled' : 'enabled (markdownlint-cli2)',
         '{{FORMAT_STATUS}}': options.format === 'none' ? 'disabled' : 'enabled (oxfmt)',
+        '{{DOCS_CHECK_CMD}}': command(depContext.isOatRepo
+            ? `pnpm -w run cli:source -- docs check --target-dir ${shellQuote(options.targetDir)}`
+            : 'oat docs check --target-dir .'),
         '{{NAV_SYNC_CMD}}': command(buildNavSyncCheckCmd(depContext.isOatRepo, options.targetDir).replace(/ --check$/, '')),
         '{{GENERATE_INDEX_CMD}}': command(buildGenerateIndexCmd(depContext.isOatRepo, options.targetDir)),
         '{{NAV_SYNC_CHECK_CMD}}': command(buildNavSyncCheckCmd(depContext.isOatRepo, options.targetDir)),
@@ -341,6 +348,19 @@ async function detectNodeRequirement(repoRoot) {
     }
     return '>=22.17.0';
 }
+// Any enclosing pnpm root makes a local boundary unsafe, even when the
+// requested repo shape was detected from a directory inside that workspace.
+async function hasAncestorPnpmWorkspace(appRoot) {
+    let current = dirname(await realpath(appRoot));
+    while (true) {
+        if (await fileExists(join(current, 'pnpm-workspace.yaml')))
+            return true;
+        const parent = dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
 async function ensureTargetWritable(appRoot) {
     if (!(await dirExists(appRoot))) {
         return;
@@ -368,21 +388,54 @@ export async function scaffoldDocsApp(options, overrides = {}) {
         throw new Error(`Docs app templates not found under ${templateRoot}`);
     }
     await ensureTargetWritable(appRoot);
+    const contentPlan = await planPresetContent({ ...options, markdown: false });
     await ensureDir(appRoot);
     const packageManagerField = await buildPackageManagerField(options, appRoot, dependencies);
     const nodeRequirement = await detectNodeRequirement(options.repoRoot);
+    const independentPnpmRoot = options.repoShape !== 'monorepo' &&
+        !(await hasAncestorPnpmWorkspace(appRoot));
     for (const templateFile of frameworkConfig.templateFiles) {
+        if (templateFile.destination === 'pnpm-workspace.yaml' &&
+            !independentPnpmRoot)
+            continue;
+        if (contentPlan &&
+            [join('docs', 'index.md'), join('docs', 'getting-started.md')].includes(templateFile.destination))
+            continue;
         const source = join(templateRoot, templateFile.source);
         const destination = join(appRoot, templateFile.destination);
         const template = await readFile(source, 'utf8');
-        const rendered = renderTemplate(template, options, depContext, packageManagerField, nodeRequirement, templateFile.destination === 'package.json');
+        let rendered = renderTemplate(template, options, depContext, packageManagerField, nodeRequirement, templateFile.destination === 'package.json');
+        if (contentPlan && templateFile.destination === 'AGENTS.md') {
+            rendered = rendered.replace('This starter separates reader Getting Started from contributor setup.', 'This starter uses the selected reader tracks and entry principles listed below.');
+            rendered += `\n${contentPlan.guidance}`;
+        }
+        if (contentPlan &&
+            templateFile.destination ===
+                join('docs', 'contributing', 'docs-toolchain.md'))
+            rendered = rendered.replaceAll('[Getting Started](../getting-started.md)', '[the documentation home](../index.md)');
         await ensureDir(dirname(destination));
         await writeFile(destination, rendered, 'utf8');
         createdFiles.push(templateFile.destination);
     }
+    for (const file of contentPlan?.files ?? []) {
+        const destination = join(appRoot, 'docs', file.name);
+        await ensureDir(dirname(destination));
+        await writeFile(destination, file.content, 'utf8');
+        createdFiles.push(join('docs', file.name));
+    }
     return {
         appRoot,
         createdFiles,
+        ...(options.framework === 'fumadocs'
+            ? {
+                installationAdvice: [
+                    independentPnpmRoot
+                        ? 'Created app-install-root pnpm-workspace.yaml with mdast-util-to-markdown: 2.1.2 for Fumadocs Markdown compatibility; retain this policy and the generated lockfile.'
+                        : 'Before installing, approve or manually set overrides.mdast-util-to-markdown to "2.1.2" in the effective install-root pnpm-workspace.yaml, preserving existing settings. No local workspace boundary or root dependency-policy edit was made.',
+                    `Read ${join(options.targetDir, 'docs/contributing/docs-toolchain.md')} for exact setup and conflict/skip guidance. --no-root-patch controls root scripts only.`,
+                ],
+            }
+            : {}),
         documentationConfig: buildDocumentationConfig(options.framework, options.targetDir),
     };
 }

package/dist/commands/docs/nav/contents.d.ts

@@ -2,6 +2,9 @@ import { type ExclusionMatcher } from '../../docs/shared/exclusions.js';
 export interface DocsContentsEntry {
     title: string;
     href: string;
+    line?: number;
+    description?: string;
+    separator?: string;
     group?: {
         title: string;
         line: number;
@@ -11,6 +14,7 @@ export interface DocsContentsEntry {
 export declare function hasIndexContents(markdown: string): boolean;
 export declare function parseIndexContents(markdown: string, sourcePath?: string, options?: {
     allowEmpty?: boolean;
+    locations?: boolean;
 }): DocsContentsEntry[];
 export type DocsNavTree = Array<Record<string, DocsNavTree | string> | string>;
 interface BuildDocsNavTreeOptions {

package/dist/commands/docs/nav/contents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contents.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/contents.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kCAAkC,CAAC;AAG1C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AA8BD,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAa,EACvB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GACrC,iBAAiB,EAAE,CAoDrB;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;AAE/E,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAMD,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,KAAK,EAAE,iBAAiB;AACxB;;;GAGG;AACH,cAAc,GAAE,SAAS,MAAM,EAAY,EAC3C,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAuElE;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CA0EtB"}
+{"version":3,"file":"contents.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/contents.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kCAAkC,CAAC;AAG1C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AA8BD,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAa,EACvB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,iBAAiB,EAAE,CA8DrB;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;AAE/E,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAMD,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,KAAK,EAAE,iBAAiB;AACxB;;;GAGG;AACH,cAAc,GAAE,SAAS,MAAM,EAAY,EAC3C,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAuElE;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CA0EtB"}

package/dist/commands/docs/nav/contents.js

@@ -64,6 +64,16 @@ export function parseIndexContents(markdown, sourcePath = 'index.md', options =
                 title: match[1].trim(),
                 href: match[2].trim(),
                 ...(group ? { group } : {}),
+                ...(options.locations
+                    ? {
+                        line: i + 1,
+                        description: line
+                            .slice(match[0].length)
+                            .replace(/^\s*[-–—:]\s*/, '')
+                            .trim(),
+                        separator: /^\s*([-–—:])/.exec(line.slice(match[0].length))?.[1],
+                    }
+                    : {}),
             });
             groupEntries += 1;
         }

package/dist/config/documentation-check.d.ts

@@ -0,0 +1,38 @@
+/** Stable portable documentation rule identifiers. */
+export declare const DOCS_CHECK_RULES: readonly ['directory-index', 'root-width', 'contents-width', 'leaf-size', 'folder-size', 'depth', 'page-length', 'frontmatter', 'description', 'h1', 'links', 'contents-description', 'overview', 'contents-separator', 'navigation', 'commands', 'mermaid', 'diagram-accessibility', 'diagram-pairs', 'diagram-freshness', 'image-alt', 'provenance'];
+export type DocsCheckRule = (typeof DOCS_CHECK_RULES)[number];
+export type DocsCheckSeverity = 'error' | 'warn' | 'off';
+export declare const DOCS_CHECK_THRESHOLDS: {
+    rootWarn: number;
+    rootError: number;
+    contentsWarn: number;
+    contentsError: number;
+    folderWarn: number;
+    folderError: number;
+    depthWarn: number;
+    depthError: number;
+    pageLines: number;
+    referenceLines: number;
+    referenceH3: number;
+    descriptionMin: number;
+    descriptionMax: number;
+    overviewWords: number;
+    altMax: number;
+};
+export interface DocumentationCheckConfig {
+    rules?: Partial<Record<DocsCheckRule, DocsCheckSeverity>>;
+    thresholds?: Partial<typeof DOCS_CHECK_THRESHOLDS>;
+    exceptions?: Array<{
+        path: string;
+        rule: DocsCheckRule;
+        reason: string;
+        severity?: DocsCheckSeverity;
+    }>;
+    provenance?: {
+        ticketPatterns?: string[];
+        milestonePatterns?: string[];
+    };
+    diagramBaseRef?: string;
+}
+export declare function normalizeDocumentationCheck(value: unknown): DocumentationCheckConfig | undefined;
+//# sourceMappingURL=documentation-check.d.ts.map

package/dist/config/documentation-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentation-check.d.ts","sourceRoot":"","sources":["../../src/config/documentation-check.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,YAC3B,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,OAAO,EACP,aAAa,EACb,aAAa,EACb,aAAa,EACb,IAAI,EACJ,OAAO,EACP,sBAAsB,EACtB,UAAU,EACV,oBAAoB,EACpB,YAAY,EACZ,UAAU,EACV,SAAS,EACT,uBAAuB,EACvB,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,YAAY,CACJ,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AACzD,eAAO,MAAM,qBAAqB;IAChC,QAAQ;IACR,SAAS;IACT,YAAY;IACZ,aAAa;IACb,UAAU;IACV,WAAW;IACX,SAAS;IACT,UAAU;IACV,SAAS;IACT,cAAc;IACd,WAAW;IACX,cAAc;IACd,cAAc;IACd,aAAa;IACb,MAAM;CACP,CAAC;AACF,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC1D,UAAU,CAAC,EAAE,OAAO,CAAC,OAAO,qBAAqB,CAAC,CAAC;IACnD,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,aAAa,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,iBAAiB,CAAC;KAC9B,CAAC,CAAC;IACH,UAAU,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,GACb,wBAAwB,GAAG,SAAS,CAgHtC"}

package/dist/config/documentation-check.js

@@ -0,0 +1,132 @@
+/** Stable portable documentation rule identifiers. */
+export const DOCS_CHECK_RULES = [
+    'directory-index',
+    'root-width',
+    'contents-width',
+    'leaf-size',
+    'folder-size',
+    'depth',
+    'page-length',
+    'frontmatter',
+    'description',
+    'h1',
+    'links',
+    'contents-description',
+    'overview',
+    'contents-separator',
+    'navigation',
+    'commands',
+    'mermaid',
+    'diagram-accessibility',
+    'diagram-pairs',
+    'diagram-freshness',
+    'image-alt',
+    'provenance',
+];
+export const DOCS_CHECK_THRESHOLDS = {
+    rootWarn: 10,
+    rootError: 14,
+    contentsWarn: 10,
+    contentsError: 15,
+    folderWarn: 12,
+    folderError: 20,
+    depthWarn: 4,
+    depthError: 5,
+    pageLines: 500,
+    referenceLines: 1000,
+    referenceH3: 40,
+    descriptionMin: 40,
+    descriptionMax: 160,
+    overviewWords: 10,
+    altMax: 155,
+};
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function normalizeDocumentationCheck(value) {
+    if (value === undefined)
+        return undefined;
+    const fail = (detail) => {
+        throw new Error(`Invalid documentation.check: ${detail}. Repair with oat config set documentation.check '<JSON>' or oat config unset documentation.check --shared.`);
+    };
+    const object = (input, keys, label) => {
+        if (!record(input))
+            return fail(`${label} must be an object`);
+        const unknown = Object.keys(input).find((key) => !keys.includes(key));
+        if (unknown)
+            return fail(`unknown ${label} option "${unknown}"`);
+        return input;
+    };
+    const severity = (v) => typeof v === 'string' && ['error', 'warn', 'off'].includes(v);
+    const root = object(value, ['rules', 'thresholds', 'exceptions', 'provenance', 'diagramBaseRef'], 'check');
+    if (root.rules !== undefined) {
+        for (const [key, v] of Object.entries(object(root.rules, DOCS_CHECK_RULES, 'rules'))) {
+            if (!severity(v))
+                fail(`${key} severity must be error, warn or off`);
+        }
+    }
+    if (root.thresholds !== undefined) {
+        const thresholds = object(root.thresholds, Object.keys(DOCS_CHECK_THRESHOLDS), 'thresholds');
+        for (const [key, v] of Object.entries(thresholds)) {
+            if (typeof v !== 'number' || !Number.isSafeInteger(v) || v < 0)
+                fail(`${key} must be a nonnegative safe integer`);
+        }
+        const t = {
+            ...DOCS_CHECK_THRESHOLDS,
+            ...thresholds,
+        };
+        for (const [low, high] of [
+            ['rootWarn', 'rootError'],
+            ['contentsWarn', 'contentsError'],
+            ['folderWarn', 'folderError'],
+            ['depthWarn', 'depthError'],
+            ['descriptionMin', 'descriptionMax'],
+        ]) {
+            if (t[low] > t[high])
+                fail(`${low} must not exceed ${high}`);
+        }
+    }
+    if (root.exceptions !== undefined) {
+        if (!Array.isArray(root.exceptions))
+            fail('exceptions must be an array');
+        for (const input of root.exceptions) {
+            const e = object(input, ['path', 'rule', 'reason', 'severity'], 'exception');
+            if (typeof e.path !== 'string' ||
+                !e.path.trim() ||
+                e.path.startsWith('/') ||
+                e.path.includes('\\') ||
+                e.path.split('/').includes('..'))
+                fail('exception path must be a content-root-relative bounded pattern');
+            if (!DOCS_CHECK_RULES.includes(e.rule))
+                fail(`unknown exception rule "${String(e.rule)}"`);
+            if (typeof e.reason !== 'string' || !e.reason.trim())
+                fail('every exception needs a nonempty reason');
+            if (e.severity !== undefined && !severity(e.severity))
+                fail('exception severity must be error, warn or off');
+        }
+    }
+    if (root.provenance !== undefined) {
+        const p = object(root.provenance, ['ticketPatterns', 'milestonePatterns'], 'provenance');
+        for (const [key, patterns] of Object.entries(p)) {
+            if (!Array.isArray(patterns) ||
+                patterns.some((pattern) => typeof pattern !== 'string' || !pattern.trim()))
+                fail(`${key} must be an array of nonempty regular expression strings`);
+            for (const pattern of patterns) {
+                try {
+                    RegExp(pattern, 'u');
+                }
+                catch {
+                    fail(`invalid ${key} regular expression "${pattern}"`);
+                }
+            }
+        }
+    }
+    if (root.diagramBaseRef !== undefined &&
+        (typeof root.diagramBaseRef !== 'string' ||
+            !root.diagramBaseRef.trim() ||
+            root.diagramBaseRef.startsWith('-') ||
+            /\s/.test(root.diagramBaseRef) ||
+            root.diagramBaseRef.includes(String.fromCharCode(0))))
+        fail('diagramBaseRef must be a Git ref without whitespace or leading dash');
+    return root;
+}

package/dist/config/oat-config.d.ts

@@ -1,4 +1,5 @@
 import { type WorkflowDispatchProviderValue } from './dispatch-matrix.js';
+import { type DocumentationCheckConfig } from './documentation-check.js';
 export { VALID_DISPATCH_MATRIX_TIERS, isCodexMaterializedRouteTarget, isWorkflowDispatchCandidateLadder, isWorkflowDispatchFallbackRoute, toWorkflowDispatchCandidateLadder, validateDispatchRouteTarget, type DispatchRouteTargetValidation, type WorkflowDispatchCandidate, type WorkflowDispatchCandidateLadder, type WorkflowDispatchFallbackRoute, type WorkflowDispatchLegacyMatrixCell, type WorkflowDispatchMatrixCell, type WorkflowDispatchMatrixTier, type WorkflowDispatchProviderValue, type WorkflowDispatchRoute, type WorkflowDispatchRouteEntry, type WorkflowDispatchRouteTarget, } from './dispatch-matrix.js';
 /**
  * The CLAUDE.md strategies `oat instructions sync` and
@@ -33,6 +34,7 @@ export interface OatDocumentationIa {
     verification?: 'triad' | 'agent-only' | 'none';
 }
 export interface OatDocumentationConfig {
+    check?: DocumentationCheckConfig;
     /** Repository-only mirror; the authored decision and local guidance own IA. */
     ia?: OatDocumentationIa;
     /** Content-root-relative globs excluded from reader navigation and manifests. */