@open-agent-toolkit/cli 0.3.31 → 0.3.33

package/dist/commands/config/index.js

@@ -12,6 +12,7 @@ import { normalizeDispatchMatrix, validateDispatchRouteTarget, walkDispatchMatri
 import { formatDispatchNotices, terminalReviewerNoticesForMatrix, } from '../../config/dispatch-notices.js';
 import { dispatchPolicyModeDescription, dispatchPolicyPolicyDescription, managedDispatchPolicyValueList, } from '../../config/dispatch-policy-options.js';
 import { normalizeDocumentationCheck } from '../../config/documentation-check.js';
+import { DocumentationIaPresetError } from '../../config/documentation-ia.js';
 import { parseJsonConfig } from '../../config/json.js';
 import { DEFAULT_INSTRUCTION_SYNC_STRATEGY, INSTRUCTION_SYNC_STRATEGIES, VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, isValidProjectLogDigestBound, normalizeWorkflowPostImplementSequence, normalizeDocumentationGuidance, normalizeDocumentationIa, normalizeDocumentationNavOwner, readOatConfig, readOatConfigForDefaultScopeRepair, readOatConfigForDocumentationExcludesRepair, readOatConfigForInstructionPointerExcludesRepair, readOatConfigForInstructionSyncStrategyRepair, readOatConfigWithWarnings, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, VALID_POST_IMPLEMENT_LEGACY_SEQUENCES, } from '../../config/oat-config.js';
 import { getOwnKey, setOwnKey } from '../../config/own-keys.js';
@@ -76,6 +77,7 @@ const KEY_ORDER = [
     'documentation.root',
     'documentation.tooling',
     'documentation.config',
+    'documentation.index',
     'documentation.excludes',
     'documentation.requireForProjectCompletion',
     'explainers.defaults.style',
@@ -321,6 +323,17 @@ const CONFIG_CATALOG = [
         owningCommand: 'oat config set documentation.config <value>',
         description: 'Repository-relative path to the primary documentation tool config file.',
     },
+    {
+        key: 'documentation.index',
+        group: 'Shared Repo (.oat/config.json)',
+        file: '.oat/config.json',
+        scope: 'shared repo',
+        type: 'string',
+        defaultValue: 'unset',
+        mutability: 'read/write',
+        owningCommand: 'oat config set documentation.index <value>',
+        description: 'Repository-relative docs index path. Markdown: the authored root index.md. Fumadocs: the generated app-root manifest; MkDocs: mkdocs.yml. oat docs init writes it and oat docs generate-index updates the Fumadocs transition.',
+    },
     {
         key: 'documentation.nonReaderPaths',
         group: 'Shared Repo (.oat/config.json)',
@@ -329,7 +342,7 @@ const CONFIG_CATALOG = [
         type: 'string[]',
         defaultValue: 'unset',
         mutability: 'read/write',
-        owningCommand: 'oat config set documentation.nonReaderPaths <glob[,glob...]>',
+        owningCommand: 'oat config set documentation.nonReaderPaths <glob[,glob...]|JSON-array>',
         description: 'Content-root-relative globs excluded from reader navigation, manifest and supported framework rendering. Empty clears the key.',
     },
     {
@@ -340,7 +353,7 @@ const CONFIG_CATALOG = [
         type: 'string[]',
         defaultValue: 'unset',
         mutability: 'read/write',
-        owningCommand: 'oat config set documentation.excludes <glob[,glob...]>',
+        owningCommand: 'oat config set documentation.excludes <glob[,glob...]|JSON-array>',
         description: 'Comma-separated globs, relative to the docs directory, excluded from `oat docs generate-index`. Repeated `--exclude` flags extend this list; an empty value clears the key.',
     },
     {
@@ -1112,7 +1125,24 @@ function parseInstructionPointerExcludes(rawValue) {
     }
     return normalized;
 }
-function parseDocumentationExcludes(rawValue) {
+function parseDocumentationExcludes(rawValue, key) {
+    const trimmed = rawValue.trim();
+    // A glob list may be given as a JSON array (which also keeps braces such as
+    // `{a,b}` intact). Anything else that looks like JSON is a mistake, never a
+    // literal glob.
+    if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (!Array.isArray(parsed) ||
+            parsed.some((entry) => typeof entry !== 'string' || entry.trim().length === 0))
+            throw new Error(`Invalid ${key} value: a value starting with [ or { must be a JSON array of non-empty strings; otherwise use comma-separated globs.`);
+        return [...new Set(parsed.map((entry) => entry.trim()))];
+    }
     const parsed = rawValue
         .split(',')
         .map((entry) => entry.trim())
@@ -1852,7 +1882,7 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
                 value = normalizeDocumentationCheck(parsed);
             }
             else if (key === 'documentation.nonReaderPaths') {
-                const paths = parseDocumentationExcludes(rawValue);
+                const paths = parseDocumentationExcludes(rawValue, 'documentation.nonReaderPaths');
                 value = paths.length > 0 ? paths : undefined;
             }
             else if (key === 'documentation.ia') {
@@ -1869,8 +1899,13 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
             }
         }
         catch (error) {
-            if (key === 'documentation.check')
+            if (key === 'documentation.check' ||
+                key === 'documentation.nonReaderPaths')
                 throw error;
+            if (error instanceof DocumentationIaPresetError)
+                throw new Error(`Invalid ${key} value: ${error.detail}.`, {
+                    cause: error,
+                });
             throw new Error(`Invalid ${key} value: ${key === 'documentation.ia' ? 'expected IA JSON with preset, repo-relative decision, optional tracks and verification' : key === 'documentation.navOwner' ? 'expected nav-sync or hand-authored' : 'expected a non-empty path/URL string or ordered non-empty string array'}.`, { cause: error });
         }
         let raw = { version: 1 };
@@ -2101,8 +2136,11 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
         else if (key === 'documentation.config') {
             doc.config = normalizeSharedRoot(rawValue);
         }
+        else if (key === 'documentation.index') {
+            doc.index = normalizeSharedRoot(rawValue);
+        }
         else if (key === 'documentation.excludes') {
-            const excludes = parseDocumentationExcludes(rawValue);
+            const excludes = parseDocumentationExcludes(rawValue, 'documentation.excludes');
             if (excludes.length === 0) {
                 // Unlike the scalar shared keys, an empty value is the documented way
                 // to clear this list rather than an error.
@@ -2260,9 +2298,9 @@ function withoutOwnKey(record, key) {
  *
  * Pruning is strictly "the object has no remaining own keys". That is what
  * keeps a prune from destroying a sibling the `oat config` catalog does not
- * expose — `documentation.index` is parsed by `config/oat-config.ts` but is
- * not a `ConfigKey`, so an unset of the last catalogued `documentation.*` key
- * leaves the parent in place while it is still present.
+ * expose (such as a key a newer CLI wrote): an unset of the last catalogued
+ * `documentation.*` key leaves the parent in place while any other key is
+ * still present.
  *
  * A missing path, a `null`/`undefined` leaf, or a non-object in the middle of
  * the path all report `removed: false`, which the caller surfaces as the

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/check.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,sBAAsB,IAAI,OAAO,CA4DhD"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/check.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,sBAAsB,IAAI,OAAO,CA6DhD"}

package/dist/commands/docs/check/check.js

@@ -15,6 +15,7 @@ export function createDocsCheckCommand() {
                 cwd: context.cwd,
                 targetDir: options.targetDir,
                 rules: options.rule,
+                onNotice: (message) => context.logger.warn(message),
             });
             process.exitCode = result.summary.errors ? 1 : 0;
         }

package/dist/commands/docs/check/checker.d.ts

@@ -4,5 +4,7 @@ export declare function checkDocs(options: {
     cwd: string;
     targetDir?: string;
     rules?: string[];
+    /** Receives human notices; they never enter the JSON result. */
+    onNotice?: (message: string) => void;
 }): Promise<DocsCheckResult>;
 //# sourceMappingURL=checker.d.ts.map

package/dist/commands/docs/check/checker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checker.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/checker.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAuB,MAAM,eAAe,CAAC;AAQ1E,gFAAgF;AAChF,wBAAsB,SAAS,CAAC,OAAO,EAAE;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,eAAe,CAAC,CAwF3B"}
+{"version":3,"file":"checker.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/checker.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAuB,MAAM,eAAe,CAAC;AAQ1E,gFAAgF;AAChF,wBAAsB,SAAS,CAAC,OAAO,EAAE;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC,GAAG,OAAO,CAAC,eAAe,CAAC,CAyF3B"}

package/dist/commands/docs/check/checker.js

@@ -11,6 +11,8 @@ export async function checkDocs(options) {
     if (unknown)
         throw new Error(`Unknown docs check rule "${unknown}". Choose: ${DOCS_CHECK_RULES.join(', ')}.`);
     const target = await resolveCheckTarget(options.cwd, options.targetDir);
+    for (const notice of target.notices)
+        options.onNotice?.(notice);
     const policy = target.documentation.check;
     const findings = [];
     const exceptions = policy?.exceptions?.map((e) => ({

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

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/commands.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgI7C,wBAAsB,aAAa,CACjC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAyJf"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/commands.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgI7C,wBAAsB,aAAa,CACjC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAkNf"}

package/dist/commands/docs/check/commands.js

@@ -111,6 +111,38 @@ export async function checkCommands(target, pages, report) {
     if (!docs.length)
         return;
     const manifests = await packages(target);
+    // A framework app's own contributing pages usually speak from the app
+    // directory. Its package is tried first; the repository root remains the
+    // fallback context, so pages written from the repository root still resolve.
+    // Literal Markdown roots keep the repository-root context only.
+    const appContext = target.framework !== 'markdown' &&
+        target.appRoot !== target.repoRoot &&
+        manifests.some((item) => item.root === target.appRoot)
+        ? target.appRoot
+        : undefined;
+    const manifestName = (pkg, labelled) => {
+        const name = posix(relative(target.repoRoot, join(pkg.root, 'package.json'))) ||
+            'package.json';
+        if (!labelled)
+            return name;
+        return pkg.root === target.appRoot
+            ? `${name} (app root)`
+            : pkg.root === target.repoRoot
+                ? `${name} (repository root)`
+                : name;
+    };
+    const lookup = async (root) => {
+        if (!root || !inside(target.repoRoot, root) || !(await present(root)))
+            return undefined;
+        let current = root;
+        while (inside(target.repoRoot, current)) {
+            const pkg = manifests.find((item) => item.root === current);
+            if (pkg || current === target.repoRoot)
+                return pkg;
+            current = dirname(current);
+        }
+        return undefined;
+    };
     for (const p of docs)
         for (const node of p.nodes) {
             if (node.type !== 'code' && node.type !== 'inlineCode')
@@ -119,7 +151,11 @@ export async function checkCommands(target, pages, report) {
                 node.lang &&
                 !['sh', 'shell', 'bash', 'zsh', 'console', 'powershell'].includes(node.lang))
                 continue;
-            let cwd = target.repoRoot;
+            // Each block starts in the repository-root context and, for framework
+            // apps, also in the app-root context; literal `cd` moves both.
+            let contexts = appContext
+                ? [appContext, target.repoRoot]
+                : [target.repoRoot];
             const start = node.position?.start;
             const openingLine = p.source.split(/\r?\n/).at((start?.line ?? 1) - 1) ?? '';
             const fenced = node.type === 'code' &&
@@ -137,36 +173,34 @@ export async function checkCommands(target, pages, report) {
                         continue;
                     const words = tokens(segment);
                     if (words[0] === 'cd') {
-                        cwd =
-                            words[1] && !illustrative(words[1]) && cwd
-                                ? resolve(cwd, words[1])
-                                : undefined;
+                        contexts = contexts.map((cwd) => words[1] && !illustrative(words[1]) && cwd
+                            ? resolve(cwd, words[1])
+                            : undefined);
                         continue;
                     }
                     const manager = words.findIndex((w) => w === 'pnpm' || w === 'npm');
                     if (manager < 0)
                         continue;
                     const kind = words[manager];
-                    let root = cwd;
+                    const moves = [];
                     let filter;
                     let index = manager + 1;
                     while (words[index]?.startsWith('-')) {
                         const option = words[index++];
                         if (['-w', '--workspace-root'].includes(option))
-                            root = target.repoRoot;
+                            moves.push(() => target.repoRoot);
                         else if (option === '--filter' || option === '-F')
                             filter = words[index++];
                         else if (option.startsWith('--filter='))
                             filter = option.slice(9);
                         else if (['--dir', '-C', '--prefix'].includes(option)) {
                             const dir = words[index++];
-                            root =
-                                root && dir && !illustrative(dir)
-                                    ? resolve(root, dir)
-                                    : undefined;
+                            moves.push((root) => root && dir && !illustrative(dir)
+                                ? resolve(root, dir)
+                                : undefined);
                         }
                         else if (['-r', '--recursive', '--workspace'].includes(option))
-                            root = undefined;
+                            moves.push(() => undefined);
                     }
                     let script = words[index];
                     if (!script)
@@ -190,29 +224,32 @@ export async function checkCommands(target, pages, report) {
                         illustrative(script) ||
                         (filter && illustrative(filter)))
                         continue;
-                    let pkg;
+                    const candidates = [];
                     if (filter) {
                         const selected = manifests.filter((item) => item.name === filter ||
                             (filter.startsWith('./') &&
                                 posix(relative(target.repoRoot, item.root)) ===
                                     filter.slice(2)));
                         if (selected.length === 1)
-                            pkg = selected[0];
+                            candidates.push(selected[0]);
                     }
-                    else if (root &&
-                        inside(target.repoRoot, root) &&
-                        (await present(root))) {
-                        let current = root;
-                        while (inside(target.repoRoot, current)) {
-                            pkg = manifests.find((item) => item.root === current);
-                            if (pkg || current === target.repoRoot)
-                                break;
-                            current = dirname(current);
+                    else {
+                        for (const cwd of contexts) {
+                            const pkg = await lookup(moves.reduce((root, move) => move(root), cwd));
+                            if (pkg && !candidates.includes(pkg))
+                                candidates.push(pkg);
                         }
                     }
-                    if (!pkg)
+                    if (!candidates.length) {
                         report('commands', 'error', p.path, `Cannot resolve package context for ${kind} ${script}${filter ? ` (--filter ${filter})` : ''}; use literal cd, -w or --filter.`, line);
-                    else if (!Object.hasOwn(pkg.scripts ?? {}, script)) {
+                        continue;
+                    }
+                    let pkg;
+                    for (const candidate of candidates) {
+                        if (Object.hasOwn(candidate.scripts ?? {}, script)) {
+                            pkg = candidate;
+                            break;
+                        }
                         // pnpm shorthand can invoke an installed local binary. Explicit run
                         // remains script-only; never execute a binary or search system PATH.
                         const installedBinary = kind === 'pnpm' &&
@@ -220,12 +257,19 @@ export async function checkCommands(target, pages, report) {
                             !/[\\/]/.test(script) &&
                             script !== '.' &&
                             script !== '..' &&
-                            (await Promise.all([pkg.root, target.repoRoot].map((binRoot) => present(join(binRoot, 'node_modules/.bin', script))))).some(Boolean);
-                        if (!installedBinary)
-                            report('commands', 'error', p.path, `Script "${script}" does not exist in ${posix(relative(target.repoRoot, join(pkg.root, 'package.json'))) || 'package.json'}.`, line);
+                            (await Promise.all([candidate.root, target.repoRoot].map((binRoot) => present(join(binRoot, 'node_modules/.bin', script))))).some(Boolean);
+                        if (installedBinary) {
+                            pkg = candidate;
+                            break;
+                        }
                     }
-                    else if (/^\s*echo(?:\s|$)/.test(pkg.scripts[script]))
-                        report('commands', 'warn', p.path, `Script "${script}" is an echo stub in ${posix(relative(target.repoRoot, join(pkg.root, 'package.json')))}.`, line);
+                    if (!pkg)
+                        report('commands', 'error', p.path, `Script "${script}" does not exist in ${candidates
+                            .map((candidate) => manifestName(candidate, candidates.length > 1))
+                            .join(' or ')}.`, line);
+                    else if (Object.hasOwn(pkg.scripts ?? {}, script) &&
+                        /^\s*echo(?:\s|$)/.test(pkg.scripts[script]))
+                        report('commands', 'warn', p.path, `Script "${script}" is an echo stub in ${manifestName(pkg, false)}.`, line);
                 }
             }
         }

package/dist/commands/docs/check/files.d.ts

@@ -11,6 +11,8 @@ export interface CheckTarget {
     framework: 'markdown' | 'fumadocs' | 'mkdocs';
     documentation: OatDocumentationConfig;
     matcher: ExclusionMatcher;
+    /** Human notices about how an explicit target was interpreted. */
+    notices: string[];
 }
 export declare function resolveCheckTarget(cwd: string, targetDir?: string): Promise<CheckTarget>;
 export declare function readerFiles(target: CheckTarget): Promise<string[]>;

package/dist/commands/docs/check/files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/files.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAExD,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1C;AACD,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ1D;AACD,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAa5D;AAKD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC9C,aAAa,EAAE,sBAAsB,CAAC;IACtC,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AACD,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,CAAC,CAiEtB;AACD,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBxE;AACD,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,UAAU,CAAC,CAKrB;AACD,+EAA+E;AAC/E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAMlB;AACD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAU3D"}
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/files.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAExD,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1C;AACD,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ1D;AACD,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAa5D;AAKD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC9C,aAAa,EAAE,sBAAsB,CAAC;IACtC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AACD,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,CAAC,CAiFtB;AACD,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA6BxE;AACD,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,UAAU,CAAC,CAKrB;AACD,+EAA+E;AAC/E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAMlB;AACD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAU3D"}

package/dist/commands/docs/check/files.js

@@ -70,6 +70,16 @@ export async function resolveCheckTarget(cwd, targetDir) {
         throw new Error(`Docs content directory does not exist: ${contentRoot}. Set documentation.root or pass --target-dir.`);
     const matchesContent = configuredContentPath !== undefined && configuredContentPath === appRoot;
     const documentation = matching || matchesContent ? doc : {};
+    const notices = [];
+    if (targetDir !== undefined && configured && doc.root && !matching) {
+        const configuredTooling = doc.tooling === 'fumadocs' || doc.tooling === 'mkdocs'
+            ? doc.tooling
+            : undefined;
+        if (matchesContent && configuredTooling && framework === 'markdown')
+            notices.push(`Notice: --target-dir ${targetDir} is the content directory of the configured ${configuredTooling} app ${doc.root}; it is checked as Markdown, so navigation is skipped. Pass --target-dir ${doc.root} to include navigation.`);
+        else if (!matchesContent)
+            notices.push(`Notice: --target-dir ${targetDir} is not the configured documentation.root (${doc.root}); checking it as ${framework === 'markdown' ? 'a literal Markdown root' : `a ${framework} app`} without the configured documentation policy. Omit --target-dir to check ${doc.root}.`);
+    }
     return {
         repoRoot,
         appRoot,
@@ -77,6 +87,7 @@ export async function resolveCheckTarget(cwd, targetDir) {
         framework,
         documentation,
         matcher: createExclusionMatcher(documentation.nonReaderPaths ?? []),
+        notices,
     };
 }
 export async function readerFiles(target) {
@@ -87,6 +98,11 @@ export async function readerFiles(target) {
         });
         for (const e of entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
             const path = posix(join(dir, e.name));
+            // Installed dependencies and hidden tool state (.git, .oat, .next, ...)
+            // are never reader content, even under a broad explicit target.
+            if (e.isDirectory() &&
+                (e.name === 'node_modules' || e.name.startsWith('.')))
+                continue;
             if (e.isDirectory() && !isExcludedPath(target.matcher, path, true))
                 await walk(path);
             else if (e.isFile() &&

package/dist/commands/docs/check/navigation.d.ts

@@ -1,4 +1,10 @@
 import type { Report } from './check.types.js';
-import { type CheckTarget } from './files.js';
+import type { CheckTarget } from './files.js';
+/**
+ * `navOwner: nav-sync` keeps strict generated freshness. Hand-authored and
+ * undeclared navigation gets the membership-and-order comparison (issue #367
+ * P21/G5): separators, labels, links, rest entries and borrowed pages are the
+ * author's presentation, never generator output to match.
+ */
 export declare function checkNavigation(target: CheckTarget, report: Report): Promise<void>;
 //# sourceMappingURL=navigation.d.ts.map

package/dist/commands/docs/check/navigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/navigation.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAgCpD,wBAAsB,eAAe,CACnC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAmGf"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/navigation.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CA0Df"}

package/dist/commands/docs/check/navigation.js

@@ -1,41 +1,12 @@
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { isDeepStrictEqual } from 'node:util';
-import { buildDocsNavTree } from '../../docs/nav/contents.js';
 import { syncFumadocsNavigation } from '../../docs/nav/fumadocs.js';
+import { compareFumadocsMembership, compareMkDocsMembership, } from '../../docs/nav/membership.js';
 import { syncDocsNavigation } from '../../docs/nav/sync.js';
-import YAML from 'yaml';
-import { present } from './files.js';
-function pageIdentity(item) {
-    // Hand-authored collision links can use their own display labels.
-    return item.replace(/^\[[^\]]*\]\((.*)\)$/, '[]($1)').replace(/^\.\//, '');
-}
-function navIdentity(value, expected) {
-    if (!Array.isArray(value))
-        return value;
-    return value.map((item, index) => {
-        if (typeof item === 'string')
-            return item;
-        if (typeof item !== 'object' || item === null)
-            return item;
-        const entry = Object.entries(item)[0];
-        if (!entry)
-            return item;
-        const expectedItem = Array.isArray(expected) ? expected[index] : undefined;
-        const children = expectedItem && typeof expectedItem === 'object'
-            ? Object.values(expectedItem)[0]
-            : undefined;
-        // The Contents-derived tree identifies sections by their direct landing path.
-        // Actual landing/page labels are presentation; explicit group labels remain meaningful.
-        const section = Array.isArray(children) &&
-            children.some((child) => typeof child === 'string' && child.endsWith('/index.md'));
-        return Array.isArray(entry[1])
-            ? {
-                [section ? '$section' : entry[0]]: navIdentity(entry[1], children),
-            }
-            : entry[1];
-    });
-}
+/**
+ * `navOwner: nav-sync` keeps strict generated freshness. Hand-authored and
+ * undeclared navigation gets the membership-and-order comparison (issue #367
+ * P21/G5): separators, labels, links, rest entries and borrowed pages are the
+ * author's presentation, never generator output to match.
+ */
 export async function checkNavigation(target, report) {
     if (target.framework === 'markdown')
         return;
@@ -48,31 +19,14 @@ export async function checkNavigation(target, report) {
                 check: true,
                 nonReaderPaths,
             });
-            for (const file of result.metaFiles) {
-                let stale = file.changed;
-                if (!generated) {
-                    if (!(await present(join(target.contentRoot, file.path))))
-                        continue;
-                    try {
-                        const actual = JSON.parse(await readFile(join(target.contentRoot, file.path), 'utf8'));
-                        if (actual &&
-                            typeof actual === 'object' &&
-                            !Array.isArray(actual) &&
-                            !Object.hasOwn(actual, 'pages'))
-                            continue;
-                        stale =
-                            !Array.isArray(actual.pages) ||
-                                !isDeepStrictEqual(actual.pages.map((p) => typeof p === 'string' ? pageIdentity(p) : p), file.meta.pages.map(pageIdentity));
-                    }
-                    catch {
-                        report('navigation', 'error', file.path, 'Cannot read or parse meta.json; check file permissions and JSON syntax.');
-                        continue;
-                    }
-                }
-                if (stale)
-                    report('navigation', 'error', file.path, generated
-                        ? 'Generated navigation is stale; run oat docs nav sync.'
-                        : 'Navigation membership/order differs from authored Contents; update pages or Contents.');
+            if (generated) {
+                for (const file of result.metaFiles)
+                    if (file.changed)
+                        report('navigation', 'error', file.path, 'Generated navigation is stale; run oat docs nav sync.');
+            }
+            else {
+                for (const issue of await compareFumadocsMembership(target.contentRoot, result.metaFiles))
+                    report('navigation', 'error', issue.path, issue.message, issue.line);
             }
             for (const path of result.unlisted)
                 report('navigation', 'error', path, 'Reader page/folder is unlisted in authored Contents and would be hidden from navigation.');
@@ -87,15 +41,12 @@ export async function checkNavigation(target, report) {
                 report('navigation', 'error', path, 'Generated navigation is stale; run oat docs nav sync.');
         }
         else {
-            const expected = await buildDocsNavTree({
+            for (const issue of await compareMkDocsMembership({
+                appRoot: target.appRoot,
                 docsRoot: target.contentRoot,
                 nonReaderPaths,
-            });
-            const actual = YAML.parse(await readFile(join(target.appRoot, 'mkdocs.yml'), 'utf8'));
-            if (!actual || !Object.hasOwn(actual, 'nav'))
-                return;
-            if (!isDeepStrictEqual(navIdentity(actual.nav, expected), navIdentity(expected, expected)))
-                report('navigation', 'error', 'mkdocs.yml', 'Navigation membership/order differs from authored Contents; update nav or Contents.');
+            }))
+                report('navigation', 'error', issue.path, issue.message, issue.line);
         }
     }
     catch (error) {

package/dist/commands/docs/check/reader-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reader-rules.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/reader-rules.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAuVf;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,IAAI,CA+CN"}
+{"version":3,"file":"reader-rules.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/reader-rules.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CA4Vf;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,IAAI,CA+CN"}

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

@@ -116,10 +116,15 @@ export async function checkReaders(target, pages, report) {
         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;
+            report('page-length', 'warn', p.path, `Page has ${lines} physical source lines; limit ${limit}${reference ? ' for reference pages' : ''}.`, 
+            // The first physical line past the limit.
+            limit + 1);
+        const h3Nodes = p.nodes.filter((n) => n.type === 'heading' && n.depth === 3);
+        const h3 = h3Nodes.length;
         if (reference && h3 > t.referenceH3)
-            report('page-length', 'warn', p.path, `Reference page has ${h3} real H3 headings; limit ${t.referenceH3}.`);
+            report('page-length', 'warn', p.path, `Reference page has ${h3} real H3 headings; limit ${t.referenceH3}.`, 
+            // The first H3 past the limit.
+            h3Nodes[t.referenceH3]?.position?.start.line ?? 1);
         for (const link of p.links) {
             const href = link.href;
             if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(href))

package/dist/commands/docs/index-generate/generator.d.ts

@@ -17,5 +17,13 @@ export interface GenerateIndexOptions {
     excludes?: string[];
 }
 export declare function generateIndex(docsDir: string, options?: GenerateIndexOptions): Promise<IndexEntry[]>;
-export declare function renderIndex(entries: IndexEntry[]): string;
+export interface RenderIndexOptions {
+    /**
+     * POSIX path from the manifest's directory to the indexed docs directory.
+     * Entry paths are docs-relative; this prefix makes each link resolve from
+     * the file the manifest is written to.
+     */
+    linkBase?: string;
+}
+export declare function renderIndex(entries: IndexEntry[], options?: RenderIndexOptions): string;
 //# sourceMappingURL=generator.d.ts.map

package/dist/commands/docs/index-generate/generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/generator.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,YAAY,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAgLD,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,UAAU,EAAE,CAAC,CAMvB;AAuBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAMzD"}
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/generator.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,YAAY,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAgLD,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,UAAU,EAAE,CAAC,CAMvB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAyCD,wBAAgB,WAAW,CACzB,OAAO,EAAE,UAAU,EAAE,EACrB,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAMR"}

package/dist/commands/docs/index-generate/generator.js

@@ -1,5 +1,5 @@
 import { readdir, readFile } from 'node:fs/promises';
-import { join, relative, resolve } from 'node:path';
+import { join, posix, relative, resolve } from 'node:path';
 import { hasIndexContents, parseIndexContents, } from '../../docs/nav/contents.js';
 import { resolveFolderTitle } from '../../docs/nav/fumadocs.js';
 import { createExclusionMatcher, } from '../../docs/shared/exclusions.js';
@@ -151,24 +151,35 @@ async function collectEntries(docsDir, relativeBase, matcher) {
 export async function generateIndex(docsDir, options = {}) {
     return collectEntries(docsDir, '', createExclusionMatcher(options.excludes ?? []));
 }
-function renderEntries(entries, indent) {
+/**
+ * Percent-encode the characters that end, split or rewrite a CommonMark link
+ * destination (whitespace, `#`, `?`, parentheses, angle brackets, `&` entity
+ * starts and `\` escapes) and `%` itself, as UTF-8 bytes, so any supported
+ * filesystem path renders as a resolvable link.
+ */
+function linkDestination(path) {
+    return path.replace(/[%\s#?()<>&\\]/g, (char) => [...Buffer.from(char, 'utf8')]
+        .map((byte) => `%${byte.toString(16).toUpperCase().padStart(2, '0')}`)
+        .join(''));
+}
+function renderEntries(entries, indent, linkBase) {
     const lines = [];
     const prefix = '  '.repeat(indent);
     for (const entry of entries) {
         if (entry.children) {
             lines.push(`${prefix}- ${entry.title}${entry.unlisted ? ' [unlisted in Contents]' : ''}`);
-            lines.push(...renderEntries(entry.children, indent + 1));
+            lines.push(...renderEntries(entry.children, indent + 1, linkBase));
         }
         else {
             const desc = entry.description ? ` — ${entry.description}` : '';
-            lines.push(`${prefix}- [${entry.title}](${entry.path})${desc}${entry.unlisted ? ' [unlisted in Contents]' : ''}`);
+            lines.push(`${prefix}- [${entry.title}](${linkDestination(linkBase ? posix.join(linkBase, entry.path) : entry.path)})${desc}${entry.unlisted ? ' [unlisted in Contents]' : ''}`);
         }
     }
     return lines;
 }
-export function renderIndex(entries) {
+export function renderIndex(entries, options = {}) {
     if (entries.length === 0) {
         return '';
     }
-    return `${renderEntries(entries, 0).join('\n')}\n`;
+    return `${renderEntries(entries, 0, options.linkBase ?? '').join('\n')}\n`;
 }