@open-agent-toolkit/cli 0.3.27 → 0.3.29

package/dist/commands/docs/check/reader-rules.js

@@ -0,0 +1,214 @@
+import { dirname, extname, join, resolve } from 'node:path';
+import { parseIndexContents, resolveEntryTarget, } from '../../docs/nav/contents.js';
+import { isExcludedPath } from '../../docs/shared/exclusions.js';
+import { DOCS_CHECK_THRESHOLDS } from '../../../config/documentation-check.js';
+import { containedFile, inside, posix, present, readerDirectories, } from './files.js';
+import { nodeText } from './markdown.js';
+export async function checkReaders(target, pages, report) {
+    const t = {
+        ...DOCS_CHECK_THRESHOLDS,
+        ...target.documentation.check?.thresholds,
+    };
+    const byPath = new Map(pages.map((p) => [p.path, p]));
+    const dirs = readerDirectories(pages.map((p) => p.path));
+    const separators = new Map();
+    for (const dir of dirs) {
+        const path = posix(join(dir, 'index.md'));
+        const page = byPath.get(path);
+        let grouped = false;
+        if (!page)
+            report('directory-index', 'error', path, 'Reader-bearing directory needs index.md with a nonempty ## Contents map.');
+        else {
+            try {
+                const entries = parseIndexContents(page.body, path, {
+                    locations: true,
+                });
+                const retained = [];
+                for (const entry of entries) {
+                    const lexical = resolve(target.contentRoot, dir, entry.href.split('#')[0] ?? '');
+                    if (inside(target.contentRoot, lexical) &&
+                        isExcludedPath(target.matcher, posix(lexical.slice(target.contentRoot.length + 1))))
+                        continue;
+                    retained.push(entry);
+                    if (entry.description && /(?:\.\.\.|…)\s*$/.test(entry.description))
+                        report('contents-description', 'error', path, 'Contents description is truncated; finish the sentence.', entry.line);
+                    if (entry.separator)
+                        separators.set(entry.separator, { path, line: entry.line });
+                    try {
+                        // Existing strict Contents resolution owns local map semantics.
+                        await resolveEntryTarget(target.contentRoot, join(target.contentRoot, dir), dir, entry, ['.md', '.mdx'], target.matcher);
+                    }
+                    catch (error) {
+                        report('directory-index', 'error', path, String(error.message), entry.line);
+                    }
+                }
+                grouped = retained.some((e) => e.group !== undefined);
+                if (dir === '.' && !grouped) {
+                    if (retained.length > t.rootError)
+                        report('root-width', 'error', path, `Flat root has ${retained.length} Contents links; maximum ${t.rootError}.`);
+                    else if (retained.length > t.rootWarn)
+                        report('root-width', 'warn', path, `Flat root has ${retained.length} Contents links; group above ${t.rootWarn}.`);
+                }
+                const catalog = page.frontmatter.catalog === true ||
+                    page.source.includes('<!-- AUTOGENERATED by `oat docs generate-index`.');
+                if (!grouped && !catalog) {
+                    if (retained.length > t.contentsError)
+                        report('contents-width', 'error', path, `Ungrouped Contents has ${retained.length} links; maximum ${t.contentsError}.`);
+                    else if (retained.length > t.contentsWarn)
+                        report('contents-width', 'warn', path, `Ungrouped Contents has ${retained.length} links; group above ${t.contentsWarn}.`);
+                }
+                const contentsHeading = page.nodes.find((n) => n.type === 'heading' &&
+                    n.depth === 2 &&
+                    nodeText(n).trim() === 'Contents');
+                const words = page.nodes
+                    .filter((n) => n.type === 'paragraph' &&
+                    (n.position?.end.line ?? Infinity) <
+                        (contentsHeading?.position?.start.line ?? 0))
+                    .map(nodeText)
+                    .join(' ')
+                    .trim()
+                    .split(/\s+/)
+                    .filter(Boolean).length;
+                if (words < t.overviewWords)
+                    report('overview', 'warn', path, `Overview has ${words} words; use at least ${t.overviewWords} before Contents.`);
+            }
+            catch (error) {
+                report('directory-index', 'error', path, error.message);
+            }
+        }
+        const count = pages.filter((p) => dirname(p.path) === dir).length;
+        const child = dirs.some((d) => d !== dir && (dir === '.' || d.startsWith(`${dir}/`)));
+        if (!child) {
+            if (count === 1 && page)
+                report('leaf-size', 'error', path, 'Index-only leaf has no reader destination; flatten it or add its reader pages.');
+            else if (count === 2)
+                report('leaf-size', 'warn', path, 'Leaf has only two direct reader pages including index.md; consider flattening.');
+        }
+        if (!grouped) {
+            if (count > t.folderError)
+                report('folder-size', 'error', path, `Folder has ${count} direct reader pages including index; maximum ${t.folderError} without groups.`);
+            else if (count > t.folderWarn)
+                report('folder-size', 'warn', path, `Folder has ${count} direct reader pages including index; group above ${t.folderWarn}.`);
+        }
+        const depth = dir === '.' ? 0 : dir.split('/').length;
+        if (depth >= t.depthError)
+            report('depth', 'error', path, `Directory depth ${depth}; error at ${t.depthError} (content root is 0).`);
+        else if (depth >= t.depthWarn)
+            report('depth', 'warn', path, `Directory depth ${depth}; warning at ${t.depthWarn} (content root is 0).`);
+    }
+    if (separators.size > 1)
+        for (const { path, line } of separators.values())
+            report('contents-separator', 'warn', path, `Contents separators differ within this tree (${[...separators.keys()].sort().join(', ')}).`, line);
+    for (const p of pages) {
+        if (!p.frontmatterError) {
+            const desc = p.frontmatter.description;
+            if (typeof desc !== 'string' || !desc.trim())
+                report('description', 'error', p.path, 'Frontmatter description is required and must be nonempty.', 1);
+            else if (desc.trim().length < t.descriptionMin ||
+                desc.trim().length > t.descriptionMax)
+                report('description', 'warn', p.path, `Description has ${desc.trim().length} characters; expected ${t.descriptionMin}–${t.descriptionMax}.`, 1);
+        }
+        const h1 = p.nodes.filter((n) => n.type === 'heading' && n.depth === 1);
+        if (h1.length !== 1)
+            report('h1', 'error', p.path, `Expected one real H1; found ${h1.length}.`, h1[1]?.position?.start.line ?? 1);
+        const reference = p.frontmatter.type === 'reference' ||
+            /(?:^|\/)references?(?:\/|$)/.test(p.path);
+        const lines = p.source.split(/\r?\n/).length - (p.source.endsWith('\n') ? 1 : 0);
+        const limit = reference ? t.referenceLines : t.pageLines;
+        if (lines > limit)
+            report('page-length', 'warn', p.path, `Page has ${lines} physical source lines; limit ${limit}${reference ? ' for reference pages' : ''}.`);
+        const h3 = p.nodes.filter((n) => n.type === 'heading' && n.depth === 3).length;
+        if (reference && h3 > t.referenceH3)
+            report('page-length', 'warn', p.path, `Reference page has ${h3} real H3 headings; limit ${t.referenceH3}.`);
+        for (const link of p.links) {
+            const href = link.href;
+            if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(href))
+                continue;
+            let pathname;
+            let anchor;
+            try {
+                const hash = href.indexOf('#');
+                pathname = decodeURIComponent((hash < 0 ? href : href.slice(0, hash)).split('?')[0]);
+                anchor = hash < 0 ? '' : decodeURIComponent(href.slice(hash + 1));
+            }
+            catch {
+                report('links', 'error', p.path, `Malformed percent encoding in link "${href}".`, link.line);
+                continue;
+            }
+            if (!pathname) {
+                if (anchor && !p.anchors.has(anchor))
+                    report('links', 'error', p.path, `Unresolved anchor "${href}".`, link.line);
+                continue;
+            }
+            if (pathname.startsWith('~/'))
+                continue; // provenance reports it, never read home paths
+            const file = pathname.startsWith('/')
+                ? resolve(target.contentRoot, `.${pathname}`)
+                : resolve(target.contentRoot, dirname(p.path), pathname);
+            if (!inside(target.contentRoot, file))
+                continue; // provenance warns without outside IO
+            const relativePath = posix(file.slice(target.contentRoot.length + 1));
+            if (isExcludedPath(target.matcher, relativePath))
+                continue;
+            let resolved = file;
+            let isFile = await containedFile(target.contentRoot, file);
+            if (!isFile && !extname(pathname)) {
+                for (const suffix of ['.md', '.mdx', '/index.md'])
+                    if (await containedFile(target.contentRoot, file + suffix)) {
+                        resolved = file + suffix;
+                        isFile = true;
+                        break;
+                    }
+            }
+            // Framework public assets have a separate explicit allowed root. Rendered
+            // absolute routes are validated only when they identify a reader file.
+            if (!isFile && pathname.startsWith('/') && link.image) {
+                const publicRoot = join(target.appRoot, 'public');
+                isFile =
+                    (await present(publicRoot)) &&
+                        (await containedFile(publicRoot, resolve(publicRoot, `.${pathname}`)));
+            }
+            if (!isFile &&
+                pathname.startsWith('/') &&
+                !link.image &&
+                !/\.mdx?$/.test(pathname))
+                continue;
+            if (!isFile)
+                report('links', 'error', p.path, `Unresolved in-root link "${href}".`, link.line);
+            else if (anchor && /\.mdx?$/.test(resolved)) {
+                const destination = byPath.get(posix(resolved.slice(target.contentRoot.length + 1)));
+                if (destination && !destination.anchors.has(anchor))
+                    report('links', 'error', p.path, `Unresolved anchor "${href}".`, link.line);
+            }
+        }
+    }
+}
+export function checkProvenance(target, pages, report) {
+    const patterns = [
+        /\.oat\//u,
+        /\b[Bb][Ll]-[\w-]+/u,
+        /(?:~\/|\/Users\/|\/home\/)/u,
+        ...(target.documentation.check?.provenance?.ticketPatterns ?? []).map((p) => new RegExp(p, 'u')),
+        ...(target.documentation.check?.provenance?.milestonePatterns ?? []).map((p) => new RegExp(p, 'u')),
+    ];
+    for (const p of pages) {
+        p.source.split(/\r?\n/).forEach((text, line) => {
+            if (patterns.some((pattern) => pattern.test(text)))
+                report('provenance', 'warn', p.path, 'Reader page contains a planning/backlog/home path or configured ticket/milestone pattern; remove it or record a reason-bearing decision-pointer exception.', line + 1);
+        });
+        for (const link of p.links) {
+            if (/^(?:[a-z][a-z\d+.-]*:|\/)/i.test(link.href))
+                continue;
+            const href = link.href.split(/[?#]/)[0];
+            let decoded;
+            try {
+                decoded = decodeURIComponent(href);
+            }
+            catch {
+                continue;
+            }
+            if (!inside(target.contentRoot, resolve(target.contentRoot, dirname(p.path), decoded)))
+                report('provenance', 'warn', p.path, `Link "${link.href}" escapes the docs root; target was not read.`, link.line);
+        }
+    }
+}

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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,wBAAgB,iBAAiB,IAAI,OAAO,CAU3C"}

package/dist/commands/docs/index.js

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

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

@@ -0,0 +1,23 @@
+export declare const IA_PRESETS: readonly ['product-engineering-qa', 'consumer-maintainer', 'domain-engineering', 'task-type', 'toolkit-cli', 'flat-small'];
+export type IaPreset = (typeof IA_PRESETS)[number];
+export interface PresetSelection {
+    iaPreset?: IaPreset;
+    plannedPages?: number;
+}
+/** Validate the opt-in pair before planning or writing any scaffold files. */
+export declare function resolvePresetSelection(preset?: string, count?: string | number): PresetSelection;
+export declare function mergeTemplateExclusion(paths?: string[]): string[];
+/** Shared narrow content plan; bodies are loaded from the bundled canonical skill. */
+export declare function planPresetContent(options: PresetSelection & {
+    assetsRoot: string;
+    siteName: string;
+    siteDescription?: string;
+    markdown: boolean;
+}): Promise<{
+    files: {
+        name: string;
+        content: string;
+    }[];
+    guidance: string;
+} | null>;
+//# sourceMappingURL=content.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/content.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,UAAU,YACrB,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,YAAY,CACJ,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AACnD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CACpC,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GACtB,eAAe,CAiBjB;AAmSD,wBAAgB,sBAAsB,CAAC,KAAK,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAErE;AAQD,sFAAsF;AACtF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,eAAe,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;CACnB,GACA,OAAO,CAAC;IACT,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAAC,CAwFR"}

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

@@ -9,6 +9,7 @@ interface DocsInitExecutionResult {
     createdFiles: string[];
     appRoot: string;
     rootPackagePatch?: RootPackagePatchResult;
+    installationAdvice?: string[];
     dryRun?: boolean;
     plannedFiles?: string[];
     preservedFiles?: string[];

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":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,mBAAmB,EAGxB,sBAAsB,EAEvB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAU5C,OAAO,EAIL,KAAK,uBAAuB,EAK7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,gBAAgB,CAAC;AAgBxB,UAAU,uBAAuB;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/C,YAAY,CAAC,EACT,SAAS,GACT,SAAS,GACT,WAAW,GACX,QAAQ,GACR,eAAe,CAAC;IACpB,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,UAAU,GAAG,QAAQ,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAED,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,uBAAuB,GAAG,IAAI,CAAC,CAAC;IAC7C,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AA2MD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAoC7E;AA0QD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CAiET"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"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"}