@open-agent-toolkit/cli 0.3.25 → 0.3.27

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

@@ -2,10 +2,15 @@ import { readdir, readFile, 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 { buildDocsCommands } from './docs-commands.js';
+import { buildDocsCommands, shellQuote } from './docs-commands.js';
 import { applyMarkdownDocsPlan, planMarkdownDocs } from './markdown.js';
 import { getTemplateDir } from './resolve-options.js';
 const MKDOCS_TEMPLATE_FILES = [
+    { source: 'AGENTS.md', destination: 'AGENTS.md' },
+    ...['index.md', 'docs-toolchain.md'].map((name) => ({
+        source: join('docs', 'contributing', name),
+        destination: join('docs', 'contributing', name),
+    })),
     { source: '.gitignore', destination: '.gitignore' },
     { source: 'mkdocs.yml', destination: 'mkdocs.yml' },
     { source: 'package.json.template', destination: 'package.json' },
@@ -22,6 +27,15 @@ const MKDOCS_TEMPLATE_FILES = [
     },
 ];
 const FUMA_TEMPLATE_FILES = [
+    { source: 'AGENTS.md', destination: 'AGENTS.md' },
+    ...['index.md', 'docs-toolchain.md'].map((name) => ({
+        source: join('docs', 'contributing', name),
+        destination: join('docs', 'contributing', name),
+    })),
+    ...['llms.txt', 'llms-full.txt', 'llms/[...slug]'].map((route) => ({
+        source: join('app', route, 'route.ts'),
+        destination: join('app', route, 'route.ts'),
+    })),
     { source: '.gitignore', destination: '.gitignore' },
     { source: 'next.config.js', destination: 'next.config.js' },
     { source: 'postcss.config.mjs', destination: 'postcss.config.mjs' },
@@ -135,16 +149,6 @@ export async function resolveOatDepContext(repoRoot, assetsRoot) {
     };
     return { isOatRepo, localPackages, oatPackageVersions };
 }
-function buildDevDependencies(lint, format) {
-    const entries = [];
-    if (lint === 'markdownlint-cli2') {
-        entries.push('    "markdownlint-cli2": "^0.13.0"');
-    }
-    if (format === 'oxfmt') {
-        entries.push('    "oxfmt": "^0.36.0"');
-    }
-    return entries.join(',\n');
-}
 function buildFumaDevDependencies(lint, format) {
     const entries = [];
     if (lint === 'markdownlint-cli2') {
@@ -158,9 +162,17 @@ function buildFumaDevDependencies(lint, format) {
     }
     return `,\n${entries.join(',\n')}`;
 }
+function jsonStringContent(value) {
+    return JSON.stringify(value).slice(1, -1);
+}
+function buildNavSyncCheckCmd(isOatRepo, targetDir) {
+    return isOatRepo
+        ? `pnpm -w run cli:source -- docs nav sync --target-dir ${shellQuote(targetDir)} --check`
+        : 'oat docs nav sync --target-dir . --check';
+}
 function buildGenerateIndexCmd(isOatRepo, targetDir) {
     if (isOatRepo) {
-        return `pnpm -w run cli:source -- docs generate-index --docs-dir ${targetDir}/docs --output ${targetDir}/index.md`;
+        return `pnpm -w run cli:source -- docs generate-index --docs-dir ${shellQuote(`${targetDir}/docs`)} --output ${shellQuote(`${targetDir}/index.md`)}`;
     }
     return 'oat docs generate-index --docs-dir docs --output index.md';
 }
@@ -221,9 +233,10 @@ async function buildPackageManagerField(options, appRoot, dependencies) {
     const version = normalizePnpmVersion(await dependencies.detectPnpmVersion());
     return `,\n  "packageManager": ${JSON.stringify(`pnpm@${version}`)}`;
 }
-function renderTemplate(template, options, depContext, packageManagerField, nodeRequirement) {
+function renderTemplate(template, options, depContext, packageManagerField, nodeRequirement, packageJson) {
     const repoName = basename(options.repoRoot);
     const commands = buildDocsCommands(options.repoShape, options.targetDir, options.appName);
+    const command = packageJson ? jsonStringContent : (value) => value;
     const replacements = {
         '// {{TURBOPACK_ROOT_IMPORTS}}\n': options.repoShape === 'nested-standalone'
             ? "import { dirname } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n"
@@ -231,6 +244,7 @@ function renderTemplate(template, options, depContext, packageManagerField, node
         '  // {{TURBOPACK_ROOT_OPTION}}\n': options.repoShape === 'nested-standalone'
             ? '  turbopack: { root: dirname(fileURLToPath(import.meta.url)) },\n'
             : '',
+        '{{OAT_CONFIG_RELATIVE_PATH}}': `./${relative(resolve(options.repoRoot, options.targetDir), join(options.repoRoot, '.oat/config.json')).replaceAll('\\', '/')}`,
         '{{APP_NAME}}': options.appName,
         '{{NODE_REQUIREMENT}}': nodeRequirement,
         '{{PACKAGE_NAME}}': options.appName,
@@ -252,11 +266,16 @@ function renderTemplate(template, options, depContext, packageManagerField, node
         '{{DOCS_FORMAT_CHECK_SCRIPT}}': options.format === 'oxfmt'
             ? "oxfmt --check 'docs/**/*.md'"
             : "echo 'docs format check disabled'",
-        '{{DEV_DEPENDENCIES}}': buildDevDependencies(options.lint, options.format),
+        '{{DEV_DEPENDENCIES}}': buildFumaDevDependencies(options.lint, options.format),
         '{{FUMA_DEV_DEPENDENCIES}}': buildFumaDevDependencies(options.lint, options.format),
         '{{REPO_NAME}}': repoName,
         '{{APP_DIR}}': options.targetDir,
-        '{{GENERATE_INDEX_CMD}}': buildGenerateIndexCmd(depContext.isOatRepo, options.targetDir),
+        '{{APP_CWD}}': shellQuote(options.targetDir),
+        '{{LINT_STATUS}}': options.lint === 'none' ? 'disabled' : 'enabled (markdownlint-cli2)',
+        '{{FORMAT_STATUS}}': options.format === 'none' ? 'disabled' : 'enabled (oxfmt)',
+        '{{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)),
         '{{OAT_DOCS_CONFIG_DEP}}': oatDepVersion(depContext, 'docs-config'),
         '{{OAT_DOCS_THEME_DEP}}': oatDepVersion(depContext, 'docs-theme'),
         '{{OAT_DOCS_TRANSFORMS_DEP}}': oatDepVersion(depContext, 'docs-transforms'),
@@ -285,12 +304,14 @@ export function buildDocumentationConfig(framework, targetDir) {
         return {
             root: targetDir,
             tooling: 'fumadocs',
+            navOwner: 'nav-sync',
             index: join(targetDir, 'index.md'),
         };
     }
     return {
         root: targetDir,
         tooling: 'mkdocs',
+        navOwner: 'nav-sync',
         config: join(targetDir, 'mkdocs.yml'),
         index: join(targetDir, 'mkdocs.yml'),
     };
@@ -354,7 +375,7 @@ export async function scaffoldDocsApp(options, overrides = {}) {
         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);
+        const rendered = renderTemplate(template, options, depContext, packageManagerField, nodeRequirement, templateFile.destination === 'package.json');
         await ensureDir(dirname(destination));
         await writeFile(destination, rendered, 'utf8');
         createdFiles.push(templateFile.destination);

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

@@ -1,21 +1,31 @@
+import { type ExclusionMatcher } from '../../docs/shared/exclusions.js';
 export interface DocsContentsEntry {
     title: string;
     href: string;
+    group?: {
+        title: string;
+        line: number;
+    };
 }
-export declare function parseIndexContents(markdown: string, sourcePath?: string): DocsContentsEntry[];
+/** Shared discovery lets inventory generation retain its no-map fallback. */
+export declare function hasIndexContents(markdown: string): boolean;
+export declare function parseIndexContents(markdown: string, sourcePath?: string, options?: {
+    allowEmpty?: boolean;
+}): DocsContentsEntry[];
 export type DocsNavTree = Array<Record<string, DocsNavTree | string> | string>;
 interface BuildDocsNavTreeOptions {
     docsRoot: string;
     dirRelativePath?: string;
     visitedDirectories?: Set<string>;
+    nonReaderPaths?: readonly string[];
 }
 export declare function resolveEntryTarget(docsRoot: string, directoryPath: string, dirRelativePath: string, entry: DocsContentsEntry, 
 /**
  * Page extensions a Contents link may target. MkDocs renders only `.md`;
  * Fumadocs also renders `.mdx` pages.
  */
-pageExtensions?: readonly string[]): Promise<{
-    kind: 'page' | 'section';
+pageExtensions?: readonly string[], matcher?: ExclusionMatcher): Promise<{
+    kind: 'page' | 'section' | 'excluded';
     path: string;
 }>;
 export declare function buildDocsNavTree(options: BuildDocsNavTreeOptions): Promise<DocsNavTree>;

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":"AAKA,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAa,GACtB,iBAAiB,EAAE,CAqCrB;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;CAClC;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,GAC1C,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAmErD;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CA8DtB"}
+{"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"}

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

@@ -1,28 +1,75 @@
 import { readFile } from 'node:fs/promises';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+import { createExclusionMatcher, isExcludedPath, } from '../../docs/shared/exclusions.js';
 import { dirExists, fileExists } from '../../../fs/io.js';
-export function parseIndexContents(markdown, sourcePath = 'index.md') {
-    const lines = markdown.split(/\r?\n/);
-    const contentsHeadingIndex = lines.findIndex((line) => /^##\s+Contents\s*$/.test(line.trim()));
-    if (contentsHeadingIndex < 0) {
+/** Mask fenced examples without changing authored source line numbers. */
+function unfencedLines(markdown) {
+    let fence;
+    return markdown.split(/\r?\n/).map((line) => {
+        if (fence) {
+            const closing = line.match(/^ {0,3}(`{3,}|~{3,})[ \t]*$/);
+            if (closing &&
+                closing[1][0] === fence.marker &&
+                closing[1].length >= fence.length) {
+                fence = undefined;
+            }
+            return '';
+        }
+        const opening = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+        if (opening && (opening[1][0] === '~' || !opening[2].includes('`'))) {
+            fence = { marker: opening[1][0], length: opening[1].length };
+            return '';
+        }
+        return line;
+    });
+}
+function contentsHeadingIndex(lines) {
+    return lines.findIndex((line) => /^##\s+Contents\s*$/.test(line.trim()));
+}
+/** Shared discovery lets inventory generation retain its no-map fallback. */
+export function hasIndexContents(markdown) {
+    return contentsHeadingIndex(unfencedLines(markdown)) >= 0;
+}
+export function parseIndexContents(markdown, sourcePath = 'index.md', options = {}) {
+    const lines = unfencedLines(markdown);
+    const headingIndex = contentsHeadingIndex(lines);
+    if (headingIndex < 0) {
         throw new Error(`Missing required ## Contents section in ${sourcePath}`);
     }
-    const sectionLines = lines.slice(contentsHeadingIndex + 1);
-    const nextHeadingIndex = sectionLines.findIndex((line) => /^##\s+/.test(line.trim()));
-    const contentsLines = nextHeadingIndex >= 0
-        ? sectionLines.slice(0, nextHeadingIndex)
-        : sectionLines;
-    const entries = contentsLines
-        .map((line) => line.match(/^\s*-\s+\[([^\]]+)\]\(([^)]+)\)/))
-        .filter((match) => match !== null)
-        .map((match) => {
-        const [, title = '', href = ''] = match;
-        return {
-            title: title.trim(),
-            href: href.trim(),
-        };
-    });
-    if (entries.length === 0) {
+    const entries = [];
+    let group;
+    let groupEntries = 0;
+    const checkGroup = () => {
+        if (group && groupEntries === 0) {
+            throw new Error(`${sourcePath}:${group.line}: Contents group "${group.title}" has no entries`);
+        }
+    };
+    for (let i = headingIndex + 1; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (/^##\s+/.test(line.trim()))
+            break;
+        const heading = line.match(/^###\s+(.+?)\s*$/);
+        if (heading) {
+            checkGroup();
+            group = { title: heading[1].trim(), line: i + 1 };
+            groupEntries = 0;
+            continue;
+        }
+        if (/^\s*[*+]\s+\[[^\]]+\]\([^)]+\)/.test(line)) {
+            throw new Error(`${sourcePath}:${i + 1}: Contents links must use a dash (-) bullet`);
+        }
+        const match = line.match(/^\s*-\s+\[([^\]]+)\]\(([^)]+)\)/);
+        if (match) {
+            entries.push({
+                title: match[1].trim(),
+                href: match[2].trim(),
+                ...(group ? { group } : {}),
+            });
+            groupEntries += 1;
+        }
+    }
+    checkGroup();
+    if (entries.length === 0 && !options.allowEmpty) {
         throw new Error(`No machine-readable links found under ## Contents in ${sourcePath}`);
     }
     return entries;
@@ -35,7 +82,7 @@ export async function resolveEntryTarget(docsRoot, directoryPath, dirRelativePat
  * Page extensions a Contents link may target. MkDocs renders only `.md`;
  * Fumadocs also renders `.mdx` pages.
  */
-pageExtensions = ['.md']) {
+pageExtensions = ['.md'], matcher) {
     const href = entry.href.split('#', 1)[0]?.trim() ?? '';
     if (!href) {
         throw new Error(`Invalid contents link "${entry.href}" in ${join(docsRoot, dirRelativePath, 'index.md')}`);
@@ -53,6 +100,9 @@ pageExtensions = ['.md']) {
         relativeTargetPath.length === 0) {
         throw new Error(`Contents link "${entry.href}" escapes the docs directory from ${join(docsRoot, dirRelativePath, 'index.md')}`);
     }
+    if (matcher && isExcludedPath(matcher, relativeTargetPath)) {
+        return { kind: 'excluded', path: relativeTargetPath };
+    }
     if (!(await fileExists(targetPath))) {
         throw new Error(`Contents link "${entry.href}" in ${join(docsRoot, dirRelativePath, 'index.md')} does not resolve to a Markdown file`);
     }
@@ -80,17 +130,27 @@ export async function buildDocsNavTree(options) {
     }
     const indexMarkdown = await readFile(indexPath, 'utf8');
     const contentsEntries = parseIndexContents(indexMarkdown, indexPath);
+    const matcher = createExclusionMatcher(options.nonReaderPaths ?? []);
     const nav = dirRelativePath === '.'
         ? [{ Home: 'index.md' }]
         : [toPosixPath(join(dirRelativePath, 'index.md'))];
+    let currentGroup;
+    let groupNav = nav;
     for (const entry of contentsEntries) {
-        const resolvedTarget = await resolveEntryTarget(options.docsRoot, directoryPath, dirRelativePath, entry);
+        const resolvedTarget = await resolveEntryTarget(options.docsRoot, directoryPath, dirRelativePath, entry, ['.md'], matcher);
+        if (resolvedTarget.kind === 'excluded')
+            continue;
         if (resolvedTarget.kind === 'section' &&
             resolvedTarget.path === toPosixPath(join(dirRelativePath, 'index.md'))) {
             continue;
         }
+        if (entry.group !== currentGroup) {
+            currentGroup = entry.group;
+            groupNav = [];
+            nav.push({ [currentGroup.title]: groupNav });
+        }
         if (resolvedTarget.kind === 'page') {
-            nav.push({ [entry.title]: resolvedTarget.path });
+            groupNav.push({ [entry.title]: resolvedTarget.path });
             continue;
         }
         const childDirRelativePath = toPosixPath(dirname(resolvedTarget.path));
@@ -99,11 +159,12 @@ export async function buildDocsNavTree(options) {
         }
         const childVisitedDirectories = new Set(visitedDirectories);
         childVisitedDirectories.add(childDirRelativePath);
-        nav.push({
+        groupNav.push({
             [entry.title]: await buildDocsNavTree({
                 docsRoot: options.docsRoot,
                 dirRelativePath: childDirRelativePath,
                 visitedDirectories: childVisitedDirectories,
+                nonReaderPaths: options.nonReaderPaths,
             }),
         });
     }

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

@@ -54,5 +54,6 @@ export declare function syncFumadocsNavigation(options: {
     docsRoot: string;
     /** Compute and compare only; never write. */
     check?: boolean;
+    nonReaderPaths?: readonly string[];
 }): Promise<SyncFumadocsNavigationResult>;
 //# sourceMappingURL=fumadocs.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"fumadocs.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/fumadocs.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAyDD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoCvE;AA8BD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAoLD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAkExC"}
+{"version":3,"file":"fumadocs.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/fumadocs.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA6DD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoCvE;AAsCD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAqND;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,4BAA4B,CAAC,CA8ExC"}

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

@@ -1,9 +1,10 @@
 import { readdir, readFile, writeFile } from 'node:fs/promises';
 import { basename, extname, join, posix } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
+import { createExclusionMatcher, } from '../../docs/shared/exclusions.js';
 import { getFrontmatterBlock, parseFrontmatterScalarFields, } from '../../shared/frontmatter.js';
 import { fileExists } from '../../../fs/io.js';
-import { parseIndexContents, resolveEntryTarget } from './contents.js';
+import { parseIndexContents, resolveEntryTarget, } from './contents.js';
 const PAGE_EXTENSIONS = ['.md', '.mdx'];
 const GROUP_FOLDER = /^\(.+\)$/;
 // The `pages` item grammar of the fumadocs-core 16.10.2 page-tree builder
@@ -18,7 +19,7 @@ const FENCE = /^\s*(```|~~~)/;
 function parentDir(path) {
     return posix.dirname(path);
 }
-async function inventoryDocs(docsRoot) {
+async function inventoryDocs(docsRoot, matcher) {
     const directories = [];
     const pages = [];
     async function walk(relativeDir) {
@@ -32,11 +33,14 @@ async function inventoryDocs(docsRoot) {
             }
             const entryPath = posix.join(relativeDir, entry.name);
             if (entry.isDirectory()) {
+                if (matcher.excludesDirectory(entryPath))
+                    continue;
                 await walk(entryPath);
             }
             else if (entry.isFile() &&
                 PAGE_EXTENSIONS.includes(extname(entry.name))) {
-                pages.push(entryPath);
+                if (!matcher.excludesFile(entryPath))
+                    pages.push(entryPath);
             }
         }
     }
@@ -100,7 +104,7 @@ export function resolveFolderTitle(markdown) {
  * slugs plugin with the scaffolded `baseUrl: '/'`: group folders are dropped,
  * segments are URI-encoded, and an `index` file maps to its folder.
  */
-function pageUrl(pagePath) {
+function pageUrl(pagePath, nonIndexUrls = new Set()) {
     const slugs = parentDir(pagePath)
         .split('/')
         .filter((segment) => segment.length > 0 && segment !== '.')
@@ -110,7 +114,12 @@ function pageUrl(pagePath) {
     if (name !== 'index') {
         slugs.push(encodeURI(name));
     }
-    return `/${slugs.join('/')}`;
+    const url = `/${slugs.join('/')}`;
+    // core16.10.2 defers index slugs and appends /index when a non-index
+    // page has already claimed the folder URL.
+    return name === 'index' && nonIndexUrls.has(url)
+        ? `${url.replace(/\/$/, '')}/index`
+        : url;
 }
 /** Whether the Fumadocs page-tree builder reads `item` as a directive, not a path. */
 function isFumadocsDirective(item) {
@@ -135,9 +144,11 @@ function hrefFragment(href) {
 /**
  * Build one folder's `pages` from its index.md Contents map.
  *
- * A page in this folder or an immediate subfolder is referenced by name. Any
- * other target becomes a Fumadocs link entry, so no page is claimed by two
- * folders. There is never a `"..."` rest entry: pages the Contents map does
+ * A page in this folder or an immediate subfolder is referenced by name.
+ * Local same-name page/folder collisions use a precise source-file item, as
+ * does `../contributing.md` from its own contributing/ map: pinned core16.10.2
+ * selects the folder first for an extensionless reference. Other non-local
+ * targets become link entries. There is never a `"..."` rest entry: pages the Contents map does
  * not list stay out of the tree and are reported instead.
  */
 /**
@@ -150,13 +161,15 @@ function hrefFragment(href) {
  * only if `pages` lists it.
  */
 function hasImplicitIndex(relativeDir, existing) {
-    if (relativeDir === '.' || existing?.root === true) {
+    if (relativeDir === '.' ||
+        existing?.root === true ||
+        (typeof existing?.root === 'string' && existing.root.trim().length > 0)) {
         return false;
     }
     const pagesIndex = existing?.pagesIndex;
     return pagesIndex === undefined || pagesIndex === 'index';
 }
-async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex) {
+async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex, matcher, inventory, nonIndexUrls) {
     const indexPath = join(docsRoot, relativeDir, 'index.md');
     const entries = parseIndexContents(markdown, indexPath);
     // A folder the loader gives no implicit index (the docs root, a `root: true`
@@ -164,11 +177,23 @@ async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex)
     // `index` would demote the folder index to an ordinary child, so it is left
     // implicit.
     const pages = implicitIndex ? [] : ['index'];
+    let currentGroup;
     for (const entry of entries) {
-        const target = await resolveEntryTarget(docsRoot, join(docsRoot, relativeDir), relativeDir, entry, PAGE_EXTENSIONS);
+        const target = await resolveEntryTarget(docsRoot, join(docsRoot, relativeDir), relativeDir, entry, PAGE_EXTENSIONS, matcher);
+        if (target.kind === 'excluded')
+            continue;
         const targetDir = parentDir(target.path);
         let item;
-        if (target.kind === 'section' && targetDir === relativeDir) {
+        if (target.kind === 'page' &&
+            (targetDir === relativeDir ||
+                target.path.slice(0, -extname(target.path).length) === relativeDir) &&
+            inventory.directories.includes(target.path.slice(0, -extname(target.path).length))) {
+            // An extensionless reference selects the same-name folder first.
+            // Keep source identity only in local/owning placement. A nonlocal map
+            // needs an authored URL link: core16.10.2 globally dedups source refs.
+            item = toFumadocsPageItem(posix.relative(relativeDir, target.path));
+        }
+        else if (target.kind === 'section' && targetDir === relativeDir) {
             continue;
         }
         else if (target.kind === 'section' &&
@@ -179,9 +204,15 @@ async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex)
             item = toFumadocsPageItem(basename(target.path, extname(target.path)));
         }
         else {
-            item = `[${entry.title}](${pageUrl(target.path)}${hrefFragment(entry.href)})`;
+            item = `[${entry.title}](${pageUrl(target.path, nonIndexUrls)}${hrefFragment(entry.href)})`;
         }
         if (!pages.includes(item)) {
+            if (entry.group !== currentGroup) {
+                currentGroup = entry.group;
+                // A leading space prevents the loader treating a literal [label] as an icon.
+                const title = currentGroup.title;
+                pages.push(`---${title.startsWith('[') ? ' ' : ''}${title}---`);
+            }
             pages.push(item);
         }
     }
@@ -213,6 +244,7 @@ function mergeMeta(existing, meta) {
     };
 }
 function collectUnlisted(inventory, metas, implicitIndexDirs) {
+    const pagePaths = new Set(inventory.pages);
     const reachableDirs = new Set();
     const reachablePages = new Set();
     const pagesByFlattenPath = new Map(inventory.pages.map((page) => [
@@ -242,7 +274,9 @@ function collectUnlisted(inventory, metas, implicitIndexDirs) {
                 visit(itemPath);
                 continue;
             }
-            const page = pagesByFlattenPath.get(itemPath);
+            const page = pagePaths.has(itemPath)
+                ? itemPath
+                : pagesByFlattenPath.get(itemPath);
             if (page) {
                 reachablePages.add(page);
             }
@@ -274,13 +308,18 @@ function collectUnlisted(inventory, metas, implicitIndexDirs) {
  */
 export async function syncFumadocsNavigation(options) {
     const { docsRoot } = options;
-    const inventory = await inventoryDocs(docsRoot);
+    const matcher = createExclusionMatcher(options.nonReaderPaths ?? []);
+    const inventory = await inventoryDocs(docsRoot, matcher);
+    const nonIndexUrls = new Set(inventory.pages
+        .filter((page) => basename(page, extname(page)) !== 'index')
+        .map((page) => pageUrl(page)));
     const metas = new Map();
     const existingMetas = new Map();
     const implicitIndexDirs = new Set();
     for (const relativeDir of inventory.directories) {
         const indexPath = join(docsRoot, relativeDir, 'index.md');
-        if (!(await fileExists(indexPath))) {
+        if (matcher.excludesFile(posix.join(relativeDir, 'index.md')) ||
+            !(await fileExists(indexPath))) {
             continue;
         }
         // Index handling depends on the effective metadata, which keeps the
@@ -295,7 +334,7 @@ export async function syncFumadocsNavigation(options) {
         const title = resolveFolderTitle(markdown);
         metas.set(relativeDir, {
             ...(title === undefined ? {} : { title }),
-            pages: await buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex),
+            pages: await buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex, matcher, inventory, nonIndexUrls),
         });
     }
     if (!metas.has('.')) {

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

@@ -12,6 +12,7 @@ interface SyncDocsNavigationOptions {
     configuredTooling?: string | null;
     /** Compute the navigation and compare it with the files; write nothing. */
     check?: boolean;
+    nonReaderPaths?: readonly string[];
 }
 interface MkDocsNavigationResult {
     framework: 'mkdocs';
@@ -35,6 +36,7 @@ type SyncDocsNavigationResult = MkDocsNavigationResult | FumadocsNavigationResul
 interface DocsNavSyncDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;
     resolveConfiguredTooling: (cwd: string, appRoot: string) => Promise<string | null>;
+    resolveNonReaderPaths?: (cwd: string, appRoot: string) => Promise<string[]>;
     syncDocsNavigation: (options: SyncDocsNavigationOptions) => Promise<SyncDocsNavigationResult>;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/sync.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAG5C,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAOrD,UAAU,yBAAyB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,sBAAsB;IAC9B,SAAS,EAAE,QAAQ,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,WAAW,CAAC;IACjB,uEAAuE;IACvE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,UAAU,wBAAwB;IAChC,SAAS,EAAE,UAAU,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,KAAK,wBAAwB,GACzB,sBAAsB,GACtB,wBAAwB,CAAC;AAE7B,UAAU,uBAAuB;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,wBAAwB,EAAE,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,kBAAkB,EAAE,CAClB,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACxC;AAsBD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,GAChC,OAAO,CAAC,gBAAgB,CAAC,CAe3B;AAqDD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CA0CnC;AAmJD,wBAAgB,wBAAwB,CACtC,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CA4BT"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/sync.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAG5C,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAOrD,UAAU,yBAAyB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,UAAU,sBAAsB;IAC9B,SAAS,EAAE,QAAQ,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,WAAW,CAAC;IACjB,uEAAuE;IACvE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,UAAU,wBAAwB;IAChC,SAAS,EAAE,UAAU,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,KAAK,wBAAwB,GACzB,sBAAsB,GACtB,wBAAwB,CAAC;AAE7B,UAAU,uBAAuB;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,wBAAwB,EAAE,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,kBAAkB,EAAE,CAClB,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACxC;AAsBD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,GAChC,OAAO,CAAC,gBAAgB,CAAC,CAe3B;AAuED,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CA8CnC;AAuJD,wBAAgB,wBAAwB,CACtC,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CA4BT"}

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

@@ -58,9 +58,24 @@ async function resolveConfiguredTooling(cwd, appRoot) {
         return null;
     }
 }
+async function resolveNonReaderPaths(cwd, appRoot) {
+    let repoRoot;
+    try {
+        repoRoot = await resolveProjectRoot(cwd);
+    }
+    catch {
+        return [];
+    } // Explicit app targets also work outside a configured repository.
+    const config = await readOatConfig(repoRoot);
+    const root = config.documentation?.root?.trim();
+    return root && resolve(repoRoot, root) === appRoot
+        ? (config.documentation?.nonReaderPaths ?? [])
+        : [];
+}
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
     resolveConfiguredTooling,
+    resolveNonReaderPaths,
     syncDocsNavigation,
 };
 function replaceTopLevelYamlSection(source, key, replacement) {
@@ -90,6 +105,7 @@ export async function syncDocsNavigation(options) {
         const result = await syncFumadocsNavigation({
             docsRoot,
             check: options.check,
+            nonReaderPaths: options.nonReaderPaths,
         });
         return {
             framework,
@@ -99,7 +115,10 @@ export async function syncDocsNavigation(options) {
         };
     }
     const mkdocsPath = join(options.appRoot, 'mkdocs.yml');
-    const nav = await buildDocsNavTree({ docsRoot });
+    const nav = await buildDocsNavTree({
+        docsRoot,
+        nonReaderPaths: options.nonReaderPaths,
+    });
     const mkdocsSource = await readFile(mkdocsPath, 'utf8');
     const navSection = YAML.stringify({ nav }).trimEnd();
     const updatedMkdocsSource = replaceTopLevelYamlSection(mkdocsSource, 'nav', navSection);
@@ -198,6 +217,7 @@ async function runDocsNavSyncCommand(context, options, dependencies) {
             appRoot,
             configuredTooling: await dependencies.resolveConfiguredTooling(context.cwd, appRoot),
             check: options.check === true,
+            nonReaderPaths: await dependencies.resolveNonReaderPaths?.(context.cwd, appRoot),
         });
         if (options.check) {
             process.exitCode = reportCheckResult(context, targetDir, result) ? 0 : 1;

package/dist/commands/docs/shared/exclusions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A compiled exclusion list.
+ *
+ * Files and directories are asked separately so a trailing-slash pattern can
+ * mean "directories only" while every other pattern applies to both.
+ */
+export interface ExclusionMatcher {
+    excludesFile: (relativePath: string) => boolean;
+    excludesDirectory: (relativePath: string) => boolean;
+}
+/**
+ * Compile exclusion globs matched against **docs-root-relative POSIX paths**
+ * (`api/auth.md`, `api/nested`), never against absolute or CWD-relative ones.
+ *
+ * Grammar, defined once and documented in
+ * `apps/oat-docs/docs/reference/oat-directory-structure.md`:
+ *
+ * - `*` matches any run of characters inside a single path segment.
+ * - `**` spans `/` only as a whole segment, where it covers zero or more
+ *   segments: `**\/CLAUDE.md` matches `CLAUDE.md` and `api/CLAUDE.md`. Inside a
+ *   segment (`a**b`) it is an ordinary single-segment wildcard.
+ * - Patterns are anchored at both ends against the whole relative path, so a
+ *   bare `CLAUDE.md` matches only the root-level file. Use `**\/CLAUDE.md` for
+ *   every depth.
+ * - A trailing `/` restricts a pattern to directories: `drafts/` prunes the
+ *   `drafts` directory and everything beneath it, and never matches a file.
+ *   Without it, a pattern that matches a directory path prunes it too.
+ * - Matching is case-sensitive, `/` is the separator on every platform, and
+ *   `*` is the only metacharacter — `.`, `+`, and friends are literal.
+ *
+ * Entries are trimmed; a leading `./` or `/` is stripped so both spellings
+ * anchor at the docs root. Blank entries are ignored.
+ */
+export declare function createExclusionMatcher(patterns: readonly string[]): ExclusionMatcher;
+/** Explicit Contents targets must also respect pruned ancestor directories. */
+export declare function isExcludedPath(matcher: ExclusionMatcher, path: string, directory?: boolean): boolean;
+//# sourceMappingURL=exclusions.d.ts.map

package/dist/commands/docs/shared/exclusions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclusions.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/shared/exclusions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;IAChD,iBAAiB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;CACtD;AAmHD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,gBAAgB,CAwClB;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAC5B,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,MAAM,EACZ,SAAS,UAAQ,GAChB,OAAO,CAQT"}