@open-agent-toolkit/cli 0.3.24 → 0.3.26

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

@@ -135,16 +135,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 +148,22 @@ function buildFumaDevDependencies(lint, format) {
     }
     return `,\n${entries.join(',\n')}`;
 }
+function shellQuote(value) {
+    return /^[a-zA-Z0-9_./-]+$/.test(value)
+        ? value
+        : `'${value.replaceAll("'", "'\\''")}'`;
+}
+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';
 }
@@ -231,6 +234,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 +256,12 @@ 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),
+        '{{GENERATE_INDEX_CMD}}': jsonStringContent(buildGenerateIndexCmd(depContext.isOatRepo, options.targetDir)),
+        '{{NAV_SYNC_CHECK_CMD}}': jsonStringContent(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 +290,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'),
     };

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;AA8BD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAkMD;;;;;;;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,CAuExC"}

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);
             }
         }
     }
@@ -150,13 +154,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) {
     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,8 +170,11 @@ 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) {
@@ -182,6 +191,12 @@ async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex)
             item = `[${entry.title}](${pageUrl(target.path)}${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);
         }
     }
@@ -274,13 +289,15 @@ 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 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 +312,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),
         });
     }
     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"}