@open-agent-toolkit/cli 0.3.28 → 0.3.30

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

@@ -0,0 +1,361 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const IA_PRESETS = [
+    'product-engineering-qa',
+    'consumer-maintainer',
+    'domain-engineering',
+    'task-type',
+    'toolkit-cli',
+    'flat-small',
+];
+/** Validate the opt-in pair before planning or writing any scaffold files. */
+export function resolvePresetSelection(preset, count) {
+    if (preset === undefined && count === undefined)
+        return {};
+    if (preset === undefined || count === undefined)
+        throw new Error('--ia-preset and --planned-pages are required together.');
+    if (!IA_PRESETS.includes(preset))
+        throw new Error(`Unknown IA preset "${preset}". Choose: ${IA_PRESETS.join(', ')}.`);
+    if (!/^\d+$/.test(String(count)) ||
+        !Number.isSafeInteger(Number(count)) ||
+        Number(count) < 1)
+        throw new Error('--planned-pages must be an integer of at least 1 (anticipated reader pages only).');
+    return { iaPreset: preset, plannedPages: Number(count) };
+}
+const engineering = {
+    path: 'engineering',
+    title: 'Engineering',
+    principle: 'Domain and implementation contracts alongside paired feature pages',
+    purpose: 'Engineering is hybrid: enter by domain or implementation contract when changing shared behavior, and by feature when following its paired Product and QA pages.',
+    sections: [
+        [
+            'Domain contracts',
+            'Place shared domain rules, interface boundaries and invariants here; link the features that depend on them.',
+        ],
+        [
+            'Feature implementation',
+            'Link implementation details for each feature to its Product intent, shared domain contracts and QA validation.',
+        ],
+        [
+            'Operations and failure modes',
+            'Place diagnosis, recovery and operational limits here; link runbooks and incident solution records.',
+        ],
+    ],
+};
+const TRACKS = {
+    'product-engineering-qa': [
+        {
+            path: 'product',
+            title: 'Product',
+            principle: 'Feature or journey',
+            purpose: 'Product readers enter by feature or journey to understand availability, intended behavior and user-visible boundaries.',
+            sections: [
+                [
+                    'Availability',
+                    'Describe who can use each feature, supported environments and known availability limits; link its feature page.',
+                ],
+                [
+                    'Journeys and behavior',
+                    'Place feature goals and ordered user journeys here, with their expected user-visible outcomes.',
+                ],
+                [
+                    'States and boundaries',
+                    'Document visible states, transitions, empty and error behavior, and what each feature excludes.',
+                ],
+            ],
+        },
+        engineering,
+        {
+            path: 'qa',
+            title: 'QA',
+            principle: 'Feature or journey with reproducible verification',
+            purpose: 'QA readers enter by feature or journey to reproduce behavior with named seeds, ready signals, exact expectations and cleanup.',
+            sections: [
+                [
+                    'Seeds and configuration',
+                    'Place reproducible test data, configuration and ready signals here; identify safe setup and cleanup.',
+                ],
+                [
+                    'Scenarios',
+                    'Organize validation by feature or journey, with actions, exact expectations and links to the supported contract.',
+                ],
+                [
+                    'Execution evidence',
+                    'Keep dated runs, observed results and discrepancies here, separate from planned automation and implemented assertions.',
+                ],
+            ],
+        },
+    ],
+    'consumer-maintainer': [
+        {
+            path: 'consumer',
+            title: 'Consumer',
+            principle: 'Reader task and supported contract',
+            purpose: 'Consumers enter by the task they need to complete and the supported contract they can rely on.',
+            sections: [
+                [
+                    'Start here',
+                    'Link the shortest supported first task, including prerequisites and a result the reader can verify.',
+                ],
+                [
+                    'Tasks',
+                    'Place bounded procedures for consumer goals here; link required inputs and verification steps.',
+                ],
+                [
+                    'Supported reference',
+                    'Collect supported interfaces, inputs, outputs and compatibility limits for consumer lookup.',
+                ],
+            ],
+        },
+        {
+            path: 'maintainer',
+            title: 'Maintainer',
+            principle: 'Change, operation and maintenance responsibility',
+            purpose: 'Maintainers enter by the responsibility they own: implementation, delivery, operations or support of the shared contract.',
+            sections: [
+                [
+                    'Implementation contracts',
+                    'Place internal interfaces, invariants and ownership boundaries here for maintainers changing behavior.',
+                ],
+                [
+                    'Delivery',
+                    'Document release preparation, compatibility checks, rollout and rollback responsibilities here.',
+                ],
+                [
+                    'Operations',
+                    'Link routine maintenance, diagnostic procedures and recovery runbooks, with their authority and safety boundaries.',
+                ],
+            ],
+        },
+    ],
+    'domain-engineering': [engineering],
+    'task-type': [
+        {
+            path: 'tutorials',
+            title: 'Tutorials',
+            principle: 'Learning by a complete safe exercise',
+            purpose: 'Learners enter through a guided exercise with a clear starting state and an independently verifiable result.',
+            sections: [
+                [
+                    'Prerequisites',
+                    'State the required knowledge, access, environment and safe starting data before the reader begins.',
+                ],
+                [
+                    'Guided exercise',
+                    'Walk through one complete learning exercise in order, explaining what each step demonstrates.',
+                ],
+                [
+                    'Expected result',
+                    'Show how to recognize a successful exercise and compare the observed result with the learning goal.',
+                ],
+            ],
+        },
+        {
+            path: 'how-to',
+            title: 'How-to',
+            principle: 'One concrete reader task',
+            purpose: 'Readers who know their goal enter by task, confirm prerequisites and follow a bounded procedure.',
+            sections: [
+                [
+                    'Prerequisites',
+                    'State the required knowledge, access, environment and safe starting data before the reader begins.',
+                ],
+                [
+                    'Procedure',
+                    'Give the ordered actions for one concrete task, including decision points and supported alternatives.',
+                ],
+                [
+                    'Verification and cleanup',
+                    'Explain how to check the task result, remove temporary resources and recover from an incomplete attempt.',
+                ],
+            ],
+        },
+        {
+            path: 'reference',
+            title: 'Reference',
+            principle: 'Lookup by supported interface or contract',
+            purpose: 'Readers enter by a named interface or contract to find exact inputs, outputs, defaults and supported limits.',
+            sections: [
+                [
+                    'Interfaces',
+                    'Describe supported commands, APIs or configuration fields with their accepted inputs and observable outputs.',
+                ],
+                [
+                    'Defaults and limits',
+                    'Record source-verified defaults, supported ranges and compatibility constraints for precise lookup.',
+                ],
+                [
+                    'Failure behavior',
+                    'Describe errors, partial outcomes and recovery expectations for each supported interface.',
+                ],
+            ],
+        },
+        {
+            path: 'explanation',
+            title: 'Explanation',
+            principle: 'Understanding concepts and tradeoffs',
+            purpose: 'Readers enter by a concept or design question to understand relationships, constraints and tradeoffs.',
+            sections: [
+                [
+                    'Concepts',
+                    'Explain the vocabulary and mental models readers need before following task or reference pages.',
+                ],
+                [
+                    'Relationships',
+                    'Show how the concepts and components depend on one another, linking their canonical contracts.',
+                ],
+                [
+                    'Tradeoffs',
+                    'Explain design choices, alternatives and constraints, linking the decisions that establish them.',
+                ],
+            ],
+        },
+    ],
+    'toolkit-cli': [
+        {
+            path: 'tools',
+            title: 'Tools',
+            principle: 'Tool, skill or command invocation',
+            purpose: 'Tool users enter by command or skill, confirm prerequisites and mutation scope, then inspect the expected output.',
+            sections: [
+                [
+                    'Invocation',
+                    'Document how to invoke each command or skill, including prerequisites and supported examples.',
+                ],
+                [
+                    'Inputs and side effects',
+                    'Describe accepted arguments and configuration, mutation scope, required approval and external effects.',
+                ],
+                [
+                    'Outputs',
+                    'Document result fields, generated artifacts, exit behavior and the next action each outcome supports.',
+                ],
+            ],
+        },
+        {
+            path: 'workflows',
+            title: 'Workflows',
+            principle: 'Reader goal across a sequence of tools',
+            purpose: 'Workflow users enter by their goal and follow an ordered sequence of tools with explicit authority and handoffs.',
+            sections: [
+                [
+                    'Starting state',
+                    'State the reader goal, required inputs, authority and ready signals before a workflow begins.',
+                ],
+                [
+                    'Sequence and handoffs',
+                    'Order the tools and decisions, naming what each step passes to the next responsible actor.',
+                ],
+                [
+                    'Completion evidence',
+                    'Define the observable result that closes the workflow and where to retain its execution evidence.',
+                ],
+            ],
+        },
+    ],
+    'flat-small': [
+        {
+            path: 'start-here',
+            title: 'Start here',
+            principle: 'Reader goal in a flat grouped index',
+            purpose: 'Readers enter by their immediate goal, using one grouped index instead of navigating a hierarchy before choosing a task.',
+            sections: [
+                [
+                    'Reader tasks',
+                    'Group links by the immediate goals readers need to accomplish, keeping each procedure focused.',
+                ],
+                [
+                    'Reference',
+                    'Link canonical interface and configuration facts for lookup without repeating them in task pages.',
+                ],
+                [
+                    'Operations',
+                    'Link routine maintenance, diagnostic procedures and recovery runbooks, with their authority and safety boundaries.',
+                ],
+            ],
+        },
+    ],
+};
+const SUPPORT_TEMPLATES = [
+    'alert-runbook',
+    'solution-record',
+    'command-reference',
+    'skill-command-guide',
+    'decisions-pointer',
+    'per-area-agents',
+];
+const TRIAD_TEMPLATES = [
+    'product-feature',
+    'engineering-feature',
+    'qa-validation',
+    'screen-spec',
+    ...SUPPORT_TEMPLATES,
+];
+export function mergeTemplateExclusion(paths = []) {
+    return [...new Set([...paths, 'contributing/templates/**'])];
+}
+function page(title, description, body) {
+    return `---\ntitle: ${JSON.stringify(title)}\ndescription: ${JSON.stringify(description)}\n---\n\n# ${title}\n\n${body}\n`;
+}
+function link(title, path, description) {
+    return `- [${title}](${path}) - ${description}`;
+}
+/** Shared narrow content plan; bodies are loaded from the bundled canonical skill. */
+export async function planPresetContent(options) {
+    const selection = resolvePresetSelection(options.iaPreset, options.plannedPages);
+    if (!selection.iaPreset)
+        return null;
+    const preset = selection.iaPreset;
+    const tracks = TRACKS[preset];
+    const flat = selection.plannedPages < 15 || preset === 'flat-small';
+    const files = [];
+    const rootLinks = [];
+    for (const track of tracks) {
+        const guideName = flat ? `${track.path}.md` : `${track.path}/start-here.md`;
+        const indexName = `${track.path}/index.md`;
+        const guideTitle = `${track.title}: choose a safe first task`;
+        const guide = `${track.purpose}\n\n## Choose the right contract\n\nIdentify your goal and supported environment before acting. Check availability, permissions and prerequisites in the repository's current source and reviewed guidance. A missing fact is a review gap, not permission to guess.\n\n## Establish a safe starting state\n\nPrefer an isolated example or read-only inspection. Record relevant configuration and inputs, avoid real personal data, and identify the owner of any external dependency. For changes, confirm approval and a cleanup or rollback route before proceeding.\n\n## Verify the result\n\nCompare the observable result with the supported contract. Keep concepts in prose; use backticks only for literals verified in source. Separate proposed automation, implemented test assertions and dated execution evidence. Escalate a discrepancy with the input, expected result and observed evidence.\n\n## Continue\n\nReturn to the [${flat ? 'documentation map' : `${track.title} map`}](index.md) to choose the next reader goal.\n`;
+        files.push({
+            name: guideName,
+            content: page(guideTitle, `Select prerequisites, boundaries and a verifiable first result for ${track.title.toLowerCase()} work.`, guide),
+        });
+        if (flat) {
+            rootLinks.push(`### ${track.title}\n\n${track.purpose}\n\n${link(guideTitle, guideName, 'Choose a safe starting state and verify the result.')}\n`);
+        }
+        else {
+            const sections = track.sections
+                .map(([title, guidance]) => `## ${title}\n\n${guidance}`)
+                .join('\n\n');
+            files.push({
+                name: indexName,
+                content: page(track.title, track.purpose, `${track.purpose}\n\nEntry principle: ${track.principle}. This track owns its canonical facts; route to shared contracts and paired pages rather than copying their claims.\n\n## Contents\n\n${link(guideTitle, 'start-here.md', 'Choose a safe starting state and verify the result.')}\n\n${sections}`),
+            });
+            rootLinks.push(link(track.title, indexName, track.purpose));
+        }
+    }
+    const contributor = options.markdown
+        ? 'contributing.md'
+        : 'contributing/index.md';
+    rootLinks.push(`${flat ? '### Contributing\n\n' : ''}${link('Contributing', contributor, 'Authoring conventions and template selection.')}\n`);
+    files.unshift({
+        name: 'index.md',
+        content: page(options.siteName, options.siteDescription?.trim() ||
+            `Reader entry points for the ${preset} model.`, `Choose the entry matching your work context. This documentation uses the ${preset} reader model; its entry principles guide placement, while page count controls materialized depth. Confirm repository-specific behavior against source before acting.\n\n## Contents\n\n${rootLinks.join('\n')}`),
+    });
+    const templates = preset === 'product-engineering-qa'
+        ? TRIAD_TEMPLATES
+        : preset === 'domain-engineering'
+            ? ['engineering-feature', ...SUPPORT_TEMPLATES]
+            : SUPPORT_TEMPLATES;
+    for (const name of templates) {
+        files.push({
+            name: `contributing/templates/${name}.md`,
+            content: await readFile(join(options.assetsRoot, 'skills', 'authoring-docs', 'references', 'page-templates', `${name}.md`), 'utf8'),
+        });
+    }
+    const table = tracks
+        .map((track) => `| ${flat ? `index.md (group: ${track.title})` : `${track.path}/`} | ${track.title} | ${track.principle} |`)
+        .join('\n');
+    const guidance = `## Preset selection\n\nAccepted selection supplied to init: ${preset}; anticipated reader pages: ${selection.plannedPages}. ${flat ? 'Reader structure is collapsed into grouped root headings.' : 'Reader directories are materialized at 15 or more anticipated pages.'} Contributor, template and toolchain pages are outside this reader-page estimate.\n\n| Location | Reader track | Entry principle |\n| --- | --- | --- |\n${table}\n\n${tracks.map((t) => t.purpose).join('\n\n')}\n\nUse contributing/templates/ as non-reader drafting assets. Screen specs are conditional on several journeys sharing a screen; no screen page or per-track AGENTS file is created automatically. Preserve canonical facts and paired links. This selection is not a persisted IA decision: complete the existing explicit approval/adoption and record-ia flow before claiming an authored IA record or config mirror. It does not initialize project management. Existing surfaces route to analyze and individually approved apply; init never restructures them.\n`;
+    return { files, guidance };
+}

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

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

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,
@@ -250,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,
@@ -276,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);
@@ -464,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.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;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,CA2EhC"}
+{"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

@@ -2,6 +2,7 @@ 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';
@@ -387,6 +388,7 @@ 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);
@@ -396,14 +398,31 @@ export async function scaffoldDocsApp(options, overrides = {}) {
         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,