@open-agent-toolkit/cli 0.3.33 → 0.3.35

package/README.md

@@ -49,7 +49,7 @@ For an approved fresh reader model, pass `--ia-preset <preset> --planned-pages <
 
 Fumadocs static exports include `llms.txt`, `llms-full.txt` and `llms/<page-slugs>/content.md` (root `llms/content.md`) for loaded `.md` readers. These retain authored Markdown and source-relative-link guidance; configured non-readers and MDX are excluded. Use authored Contents maps and `oat docs nav sync`, followed by `--check`, for navigation changes.
 
-`oat docs check [--target-dir <dir>] [--rule <id>...] [--json]` performs read-only reader, navigation, contributor-command and Mermaid/SVG checks without a site build. Errors exit 1; warnings exit 0. Configure validated severities, numeric thresholds and reason-bearing exceptions under `documentation.check`. Mermaid syntax parsing lazily uses a real DOM with strict sanitization and no script/resource execution; Node 22.17 remains the minimum. See [checker rules and configuration](../../apps/oat-docs/docs/docs-tooling/check.md).
+`oat docs check [--target-dir <dir>] [--rule <id>...] [--json]` performs read-only reader, navigation, contributor-command and Mermaid/SVG checks without a site build. Errors exit 1; warnings exit 0. Configure validated severities, numeric thresholds and reason-bearing exceptions under `documentation.check`. Mermaid syntax parsing lazily loads the pinned Pele parser, which needs no DOM and never renders; Node 22.17 remains the minimum. See [checker rules and configuration](../../apps/oat-docs/docs/docs-tooling/check.md).
 
 `oat docs literals [--target-dir <dir>] --page <content-relative-reader.md> --source-root <repo-relative-dir> [--source-exclude <pattern>] --json` supplies read-only inline-code occurrence candidates for a matching triad IA mirror. Repeat each single-value selection flag as needed. Sources stay within narrow explicit implementation roots; searched/skipped evidence and first source physical lines are reported. Once-only strict HTML entity decoding and case-sensitive line-local substring matching do not establish runtime validity; analyze judges canonical relevance and authored IA acceptance. Completed not-found/not-applicable exits 0, input/config errors 1, unexpected failures 2. See [literal helper scope and limits](../../apps/oat-docs/docs/docs-tooling/commands.md#oat-docs-literals).
 

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.33"
+  "oatVersion": "0.3.35"
 }

package/assets/docs/contributing/documentation.md

@@ -13,6 +13,7 @@ Documentation should ship with the code it explains. This page covers the core d
 - Each `index.md` must include a `## Contents` section.
 - The `## Contents` section is the machine-readable local map for sibling pages and child directories.
 - Use `.md`-suffixed relative links in `## Contents`: `[Page](page.md)` for leaf pages and `[Section](subdir/index.md)` for child directories.
+- A directory whose `index.md` is its only reader page, with no child sections, may instead list same-page heading anchors (`[Setup](#setup)`) as an in-page table of contents; anywhere else, Contents links must target pages or sections.
 - Fumadocs and MkDocs share this authored contract, but they regenerate different artifacts.
 
 Within Contents, use dash-only link bullets with optional descriptions. A `### Label` introduces a group containing at least one authored entry; entries before the first group stay ungrouped. `*`/`+` link bullets and empty groups produce file/line errors. The map ends at the next level-two heading, and fenced examples are ignored. A self-index link retains landing-page behavior. Missing Contents retains deterministic manifest fallback, while strict nav still requires maps and reports unlisted reader pages.

package/assets/docs/docs-tooling/check.md

@@ -91,23 +91,23 @@ recursive tabs participate.
 
 | Rule ID                 | Default behavior                                                                                                                                                                                                                                                                                                                    |
 | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `directory-index`       | Error for a reader-bearing directory without `index.md` and a nonempty dash-bullet Contents map, invalid map grammar or unresolved strict Contents target. Ancestors of reader pages participate.                                                                                                                                   |
+| `directory-index`       | Error for a reader-bearing directory without `index.md` and a nonempty dash-bullet Contents map, invalid map grammar or unresolved strict Contents target. Ancestors of reader pages participate. A same-page anchor such as `#setup` is not a Contents target, except in an index-only leaf.                                       |
 | `root-width`            | Flat root Contents links warn above `rootWarn: 10`, error above `rootError: 14`. Real groups exempt the width.                                                                                                                                                                                                                      |
 | `contents-width`        | Ungrouped Contents links warn above `contentsWarn: 10`, error above `contentsError: 15`. `catalog: true` or the recognized OAT generated-index marker exempts only this width rule.                                                                                                                                                 |
-| `leaf-size`             | Direct reader pages include index. A leaf has no reader-bearing child directory: index-only errors; two total pages warn.                                                                                                                                                                                                           |
+| `leaf-size`             | Direct reader pages include index. A leaf has no reader-bearing child directory. An index-only leaf (its `index.md` is the only reader page) warns: it renders as a single-page section, so flattening it is a suggestion. Two total pages warn.                                                                                    |
 | `folder-size`           | Direct reader pages including index warn above `folderWarn: 12`, error above `folderError: 20`, unless the index has real groups.                                                                                                                                                                                                   |
 | `depth`                 | Content root is depth 0; warn at `depthWarn: 4`, error at `depthError: 5`.                                                                                                                                                                                                                                                          |
 | `page-length`           | Warn above `pageLines: 500` physical source lines. Explicit `type: reference` or `reference`/`references` path segments use `referenceLines: 1000` and warn above `referenceH3: 40` real H3 headings. No default length error limit. `line` is the first physical line past the line limit, or the first H3 past the heading limit. |
 | `frontmatter`           | Unreadable source, invalid YAML or a non-mapping frontmatter document errors. Read failures use relative paths and safe error codes; invalid metadata skips description validation while independent body checks continue at physical positions.                                                                                    |
 | `description`           | Missing/empty frontmatter description errors; character lengths below `descriptionMin: 40` or above `descriptionMax: 160` warn.                                                                                                                                                                                                     |
 | `h1`                    | Error unless each page has exactly one real H1.                                                                                                                                                                                                                                                                                     |
-| `links`                 | Error for unresolved in-root source links/anchors. No network checking. Ordinary escaping links are provenance warnings and their targets are not read. Contents links retain stricter local-map rules.                                                                                                                             |
+| `links`                 | Error for unresolved in-root source links/anchors. No network checking. Ordinary escaping links are provenance warnings and their targets are not read. Contents links retain stricter local-map rules; the same-page anchors an index-only leaf may list in Contents are checked here, against that page's headings.               |
 | `contents-description`  | Error for descriptions ending in an ellipsis/truncation.                                                                                                                                                                                                                                                                            |
 | `overview`              | Warn below `overviewWords: 10` before Contents.                                                                                                                                                                                                                                                                                     |
 | `contents-separator`    | Warn when Contents descriptions mix separators in a tree.                                                                                                                                                                                                                                                                           |
 | `navigation`            | Error for explicit navigation drift. Nav-sync freshness stays strict; hand-authored/undeclared compare membership and order only (separators, labels, links and borrows are not compared), and absent optional meta/pages/nav skips comparison. Markdown skips it.                                                                  |
 | `commands`              | Error for missing literal contributor scripts; framework app targets try the app package first, then the repository root. Implicit pnpm shorthand also accepts installed package/workspace `.bin` entries. Explicit pnpm run/npm run stays script-only; unresolved context errors; echo scripts warn.                               |
-| `mermaid`               | Parse every real Mermaid fence using the pinned Mermaid parser. Invalid syntax errors.                                                                                                                                                                                                                                              |
+| `mermaid`               | Parse every real Mermaid fence with the pinned Pele parser. Invalid syntax errors, with the diagram line and column.                                                                                                                                                                                                                |
 | `diagram-pairs`         | Diagram light/dark SVG siblings and both page references are required. Conventional diagram paths and explicit paired references participate; ordinary logos are not diagrams.                                                                                                                                                      |
 | `diagram-accessibility` | Mermaid missing `accTitle`/`accDescr` warns. SVGs require `role="img"`, nonempty title/desc. Rendered diagrams without page-visible explanatory text or an associated long description warn.                                                                                                                                        |
 | `diagram-freshness`     | Warn when changed Mermaid lacks both associated SVG changes; association follows the actual section/tab group. Missing usable Git comparison is explicitly unverified.                                                                                                                                                              |
@@ -140,9 +140,9 @@ binary shorthand may be reported missing. Use `pnpm exec` for explicit binary ex
 
 ## Diagram comparison and limits
 
-Syntax validation lazily loads the pinned Mermaid parser with a real Node DOM
-and strict sanitization; script execution and resource loading stay disabled.
-It does not render or prove semantic/visual correctness. Inspect both themes
+Syntax validation lazily loads the pinned Pele parser, which reads Mermaid
+syntax without a DOM and never renders, runs scripts or loads resources.
+It does not prove semantic/visual correctness. Inspect both themes
 for important diagrams. Put meaningful `accTitle` and `accDescr` in Mermaid,
 keep SVG title/desc and page explanations, and change both theme SVGs with source.
 

package/assets/docs/reference/docs-index-contract.md

@@ -39,6 +39,7 @@ Notes:
 - A group with no authored entries is an error with its file and line; add a dash link or remove the empty heading. A `*` or `+` link bullet is also an error with file and line; replace it with `-`.
 - Child directories should link to their `index.md`.
 - Leaf pages should link to their `.md` filename.
+- An index-only leaf, a directory whose `index.md` is its only reader page and that has no child sections, may list same-page heading anchors such as `[Setup](#setup)` as an in-page table of contents. Each must be a valid Markdown link; a destination Markdown renders as plain text, such as `(#set up)`, is an error. Nav sync adds no navigation entry for them, `oat docs check` reports an anchor whose heading does not exist, and the `leaf-size` rule warns that the section could be flattened. In any other directory a same-page anchor in Contents is an error: link a page or section instead.
 - Prose outside `## Contents` is ignored by nav generation and remains freeform; it can explain scope, reader paths, or migration status.
 
 ## Plain Markdown Ownership

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.33",
-  "docs-config": "0.3.33",
-  "docs-theme": "0.3.33",
-  "docs-transforms": "0.3.33"
+  "cli": "0.3.35",
+  "docs-config": "0.3.35",
+  "docs-theme": "0.3.35",
+  "docs-transforms": "0.3.35"
 }

package/assets/skills/oat-docs-analyze/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(oat docs check:*), Bash(oat docs literals:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(node:*), Bash(command -v:*), Bash(sed:*), Bash(npm root -g:*), Bash(test:*), Bash(oat --version), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: '1.9.0'
+  version: '1.9.1'
 ---
 
 # Docs Analysis

package/assets/skills/oat-docs-analyze/references/quality-checklist.md

@@ -15,7 +15,9 @@ Use this checklist when evaluating a docs surface.
 - Parent `## Contents` maps include immediate child directories that contain
   docs.
 - Single-page directories still expose a useful `index.md` entrypoint or local
-  section map.
+  section map. An index-only leaf may list same-page heading anchors in
+  `## Contents`; treat it as a flattening suggestion (`leaf-size` warning), not
+  a broken map.
 - Asset-only directories are exempt when they contain no Markdown content and
   are not linked as navigable docs sections.
 - `overview.md` is not used as the directory entrypoint.

package/assets/skills/oat-docs-authoring/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: '1.2.1'
+  version: '1.2.2'
 ---
 
 # OAT Docs Authoring

package/assets/skills/oat-docs-authoring/references/oat-fumadocs-contract.md

@@ -29,7 +29,12 @@ Use file-path-friendly relative Markdown links:
 - child directory: `[Section](section/index.md)`;
 - avoid extensionless local docs links for new authored navigation entries;
 - preserve anchors only when the target heading exists and the local renderer
-  supports the anchor.
+  supports the anchor;
+- index-only leaf (its `index.md` is the directory's only reader page and it
+  has no child sections): may list same-page heading anchors such as `[Setup](#setup)` as an in-page table
+  of contents. They add no navigation entry, and `oat docs check` warns
+  (`leaf-size`) that the section could be flattened. Anywhere else a same-page
+  anchor in Contents is an error.
 
 Existing extensionless links are drift, not precedent. Normalize them only when
 the task scope or an approved recommendation covers that change.

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;IACjB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC,GAAG,OAAO,CAAC,eAAe,CAAC,CAyF3B"}
+{"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,CAiG3B"}

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

@@ -55,7 +55,10 @@ export async function checkDocs(options) {
     await checkReaders(target, pages, report);
     checkProvenance(target, pages, report);
     if (!options.rules?.length || options.rules.includes('navigation'))
-        await checkNavigation(target, report);
+        await checkNavigation(target, report, (ruleId, path, line) => findings.some((f) => f.severity === 'error' &&
+            f.ruleId === ruleId &&
+            f.path === path &&
+            f.line === line));
     if (!options.rules?.length || options.rules.includes('commands'))
         await checkCommands(target, pages, report);
     if (!options.rules?.length ||

package/dist/commands/docs/check/mermaid-runtime.d.ts

@@ -1,3 +1,3 @@
-/** Lazy, real Node DOM for Mermaid syntax parsing only. Never renders SVG. */
+/** Mermaid syntax check with the pinned, DOM-free Pele parser. Never renders. */
 export declare function parseMermaid(source: string): Promise<void>;
 //# sourceMappingURL=mermaid-runtime.d.ts.map

package/dist/commands/docs/check/mermaid-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mermaid-runtime.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/mermaid-runtime.ts"],"names":[],"mappings":"AA6CA,8EAA8E;AAC9E,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAehE"}
+{"version":3,"file":"mermaid-runtime.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/mermaid-runtime.ts"],"names":[],"mappings":"AAyBA,iFAAiF;AACjF,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhE"}

package/dist/commands/docs/check/mermaid-runtime.js

@@ -1,57 +1,32 @@
 let runtime;
-let queue = Promise.resolve();
-async function withDom(dom, action) {
-    const keys = ['window', 'document'];
-    const saved = keys.map((key) => Object.getOwnPropertyDescriptor(globalThis, key));
-    Object.defineProperty(globalThis, 'window', {
-        configurable: true,
-        value: dom.window,
-    });
-    Object.defineProperty(globalThis, 'document', {
-        configurable: true,
-        value: dom.window.document,
-    });
-    try {
-        return await action();
-    }
-    finally {
-        keys.forEach((key, index) => {
-            const descriptor = saved[index];
-            if (descriptor)
-                Object.defineProperty(globalThis, key, descriptor);
-            else
-                Reflect.deleteProperty(globalThis, key);
-        });
-    }
+/**
+ * Pele reports syntax errors in Mermaid's multi-line form: a "Parse error on
+ * line N:" header, the offending source line, a caret line and the expected
+ * tokens. Keep only the explanation and append the diagram-relative position.
+ */
+function conciseMessage(error) {
+    const message = error.snippet
+        ? error.message.replace(error.snippet, '')
+        : error.message;
+    const detail = message
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line && !/^Parse error on line \d+:?$/.test(line))
+        .join(' ');
+    return error.line > 0
+        ? `${detail} (diagram line ${error.line}, column ${error.column})`
+        : detail;
 }
-async function loadRuntime() {
-    const { JSDOM } = await import('jsdom');
-    // Defaults intentionally disable script execution and external resources.
-    const dom = new JSDOM('');
+/** Mermaid syntax check with the pinned, DOM-free Pele parser. Never renders. */
+export async function parseMermaid(source) {
+    runtime ??= import('pele');
+    const pele = await runtime;
     try {
-        const mermaid = await withDom(dom, async () => (await import('mermaid')).default);
-        process.once('beforeExit', () => dom.window.close());
-        return { dom, mermaid };
+        pele.parse(source);
     }
     catch (error) {
-        dom.window.close();
+        if (error instanceof pele.PeleError)
+            throw new Error(conciseMessage(error), { cause: error });
         throw error;
     }
 }
-/** Lazy, real Node DOM for Mermaid syntax parsing only. Never renders SVG. */
-export async function parseMermaid(source) {
-    const result = queue.then(async () => {
-        runtime ??= loadRuntime();
-        const { dom, mermaid } = await runtime;
-        await withDom(dom, async () => {
-            mermaid.initialize({
-                startOnLoad: false,
-                securityLevel: 'strict',
-                logLevel: 'fatal',
-            });
-            await mermaid.parse(source);
-        });
-    });
-    queue = result.catch(() => undefined);
-    await result;
-}

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

@@ -1,10 +1,14 @@
 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.
+ *
+ * `reported` tells whether an error-severity finding already exists for a
+ * rule, path and line. A policy-downgraded finding does not count: the defect
+ * still stops navigation, so navigation keeps reporting it as an error.
  */
-export declare function checkNavigation(target: CheckTarget, report: Report): Promise<void>;
+export declare function checkNavigation(target: CheckTarget, report: Report, reported: (ruleId: string, path: string, line?: number) => boolean): 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":"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"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/navigation.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE1D;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,GACjE,OAAO,CAAC,IAAI,CAAC,CAyEf"}

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

@@ -1,13 +1,20 @@
+import { relative } from 'node:path';
+import { DocsContentsError } 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 { inside, posix } 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.
+ *
+ * `reported` tells whether an error-severity finding already exists for a
+ * rule, path and line. A policy-downgraded finding does not count: the defect
+ * still stops navigation, so navigation keeps reporting it as an error.
  */
-export async function checkNavigation(target, report) {
+export async function checkNavigation(target, report, reported) {
     if (target.framework === 'markdown')
         return;
     try {
@@ -50,6 +57,19 @@ export async function checkNavigation(target, report) {
         }
     }
     catch (error) {
+        if (error instanceof DocsContentsError &&
+            inside(target.contentRoot, error.indexPath)) {
+            // Navigation stops at the first invalid Contents map. directory-index
+            // resolves every map the same way and reports each defect at its own
+            // index.md, so repeat it here only when that rule did not report it as
+            // an error: it was not selected, policy downgraded it, or the defect is
+            // framework-only (MkDocs nav accepts only .md targets, while the reader
+            // check also accepts .mdx).
+            const path = posix(relative(target.contentRoot, error.indexPath));
+            if (!reported('directory-index', path, error.line))
+                report('navigation', 'error', path, error.message, error.line);
+            return;
+        }
         report('navigation', 'error', 'index.md', error.message);
     }
 }

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,CA4Vf;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":"AAUA,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,CAgWf;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

@@ -1,5 +1,5 @@
 import { dirname, extname, join, resolve } from 'node:path';
-import { parseIndexContents, resolveEntryTarget, } from '../../docs/nav/contents.js';
+import { isIndexOnlyLeaf, parseIndexContents, resolveEntryTarget, } from '../../docs/nav/contents.js';
 import { isExcludedPath } from '../../docs/shared/exclusions.js';
 import { DOCS_CHECK_THRESHOLDS } from '../../../config/documentation-check.js';
 import { containedFile, inside, posix, present, readerDirectories, } from './files.js';
@@ -10,11 +10,13 @@ export async function checkReaders(target, pages, report) {
         ...target.documentation.check?.thresholds,
     };
     const byPath = new Map(pages.map((p) => [p.path, p]));
-    const dirs = readerDirectories(pages.map((p) => p.path));
+    const pagePaths = pages.map((p) => p.path);
+    const dirs = readerDirectories(pagePaths);
     const separators = new Map();
     for (const dir of dirs) {
         const path = posix(join(dir, 'index.md'));
         const page = byPath.get(path);
+        const indexOnlyLeaf = isIndexOnlyLeaf(dir, pagePaths);
         let grouped = false;
         if (!page)
             report('directory-index', 'error', path, 'Reader-bearing directory needs index.md with a nonempty ## Contents map.');
@@ -36,7 +38,9 @@ export async function checkReaders(target, pages, report) {
                         separators.set(entry.separator, { path, line: entry.line });
                     try {
                         // Existing strict Contents resolution owns local map semantics.
-                        await resolveEntryTarget(target.contentRoot, join(target.contentRoot, dir), dir, entry, ['.md', '.mdx'], target.matcher);
+                        // Leaf same-page anchors resolve without error; the links rule
+                        // below reports any that name a missing heading.
+                        await resolveEntryTarget(target.contentRoot, join(target.contentRoot, dir), dir, entry, ['.md', '.mdx'], target.matcher, { indexOnlyLeaf });
                     }
                     catch (error) {
                         report('directory-index', 'error', path, String(error.message), entry.line);
@@ -78,12 +82,11 @@ export async function checkReaders(target, pages, report) {
         }
         const count = pages.filter((p) => dirname(p.path) === dir).length;
         const child = dirs.some((d) => d !== dir && (dir === '.' || d.startsWith(`${dir}/`)));
-        if (!child) {
-            if (count === 1 && page)
-                report('leaf-size', 'error', path, 'Index-only leaf has no reader destination; flatten it or add its reader pages.');
-            else if (count === 2)
-                report('leaf-size', 'warn', path, 'Leaf has only two direct reader pages including index.md; consider flattening.');
-        }
+        // A single-page section renders fine, so its shape is a style suggestion.
+        if (indexOnlyLeaf)
+            report('leaf-size', 'warn', path, 'Index-only leaf; consider flattening it to a single page or adding reader pages.');
+        else if (!child && count === 2)
+            report('leaf-size', 'warn', path, 'Leaf has only two direct reader pages including index.md; consider flattening.');
         if (!grouped) {
             if (count > t.folderError)
                 report('folder-size', 'error', path, `Folder has ${count} direct reader pages including index; maximum ${t.folderError} without groups.`);

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

@@ -5,11 +5,45 @@ export interface DocsContentsEntry {
     line?: number;
     description?: string;
     separator?: string;
+    /**
+     * The authored line from the link's opening `[` onward. `href` is captured
+     * only up to the first `)`, so Markdown-level validation reads this instead.
+     */
+    source?: string;
     group?: {
         title: string;
         line: number;
     };
 }
+/**
+ * A defect in one index.md Contents map. `indexPath` is the index file that
+ * contains it, as the caller named it, and `line` the entry line when the
+ * entries were parsed with locations, so a consumer that only sees the thrown
+ * error can still report it against the file that contains it.
+ */
+export declare class DocsContentsError extends Error {
+    readonly indexPath: string;
+    readonly line?: number | undefined;
+    constructor(message: string, indexPath: string, line?: number | undefined);
+}
+export interface DocsInventory {
+    /** Docs-relative POSIX directory paths, `.` for the docs root. */
+    directories: string[];
+    /** Docs-relative POSIX page paths. */
+    pages: string[];
+}
+/** Reader page extensions: Fumadocs renders `.md` and `.mdx` pages. */
+export declare const PAGE_EXTENSIONS: readonly string[];
+/** Every non-excluded directory and reader page under the docs root. */
+export declare function inventoryDocs(docsRoot: string, matcher: ExclusionMatcher): Promise<DocsInventory>;
+/**
+ * Whether a directory is an index-only leaf: its own `index.md` is the only
+ * reader page in it or below it, so it renders as a single-page section.
+ * `pagePaths` are docs-relative POSIX reader page paths.
+ */
+export declare function isIndexOnlyLeaf(dirRelativePath: string, pagePaths: readonly string[]): boolean;
+/** A Contents href naming a heading on the same page, such as `#setup`. */
+export declare function isSamePageAnchor(href: string): boolean;
 /** 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?: {
@@ -22,14 +56,28 @@ interface BuildDocsNavTreeOptions {
     dirRelativePath?: string;
     visitedDirectories?: Set<string>;
     nonReaderPaths?: readonly string[];
+    /** Reader page inventory; the root call computes it once. */
+    pagePaths?: readonly string[];
 }
+/**
+ * Resolve one Contents entry to the page or section it places in navigation.
+ *
+ * Contents is machine-readable navigation, so every entry must target a page
+ * or a section index. The one exception is an index-only leaf: a single-page
+ * section may list same-page heading anchors as an in-page table of contents.
+ * Those resolve to `anchor` and place nothing in navigation; the `links` check
+ * rule validates that each heading exists.
+ */
 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[], matcher?: ExclusionMatcher): Promise<{
-    kind: 'page' | 'section' | 'excluded';
+pageExtensions?: readonly string[], matcher?: ExclusionMatcher, options?: {
+    /** The directory is an index-only leaf (see {@link isIndexOnlyLeaf}). */
+    indexOnlyLeaf?: boolean;
+}): Promise<{
+    kind: 'page' | 'section' | 'excluded' | 'anchor';
     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":"AAGA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kCAAkC,CAAC;AAG1C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,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,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,iBAAiB,EAAE,CA8DrB;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"}
+{"version":3,"file":"contents.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/contents.ts"],"names":[],"mappings":"AAWA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kCAAkC,CAAC;AAK1C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAGxC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;IAHxB,YACE,OAAO,EAAE,MAAM,EACN,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,YAAA,EAIvB;CACF;AAED,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,sCAAsC;IACtC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAoB,CAAC;AAElE,wEAAwE;AACxE,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CA8BxB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAUT;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AA+DD,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,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,iBAAiB,EAAE,CAqErB;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;IACnC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAMD;;;;;;;;GAQG;AACH,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,EAC1B,OAAO,GAAE;IACP,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;CACpB,GACL,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IACjD,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAyED;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CAkFtB"}

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

@@ -1,7 +1,99 @@
-import { readFile } from 'node:fs/promises';
-import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, posix, relative, resolve, } from 'node:path';
 import { createExclusionMatcher, isExcludedPath, } from '../../docs/shared/exclusions.js';
 import { dirExists, fileExists } from '../../../fs/io.js';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+/**
+ * A defect in one index.md Contents map. `indexPath` is the index file that
+ * contains it, as the caller named it, and `line` the entry line when the
+ * entries were parsed with locations, so a consumer that only sees the thrown
+ * error can still report it against the file that contains it.
+ */
+export class DocsContentsError extends Error {
+    indexPath;
+    line;
+    constructor(message, indexPath, line) {
+        super(message);
+        this.indexPath = indexPath;
+        this.line = line;
+        this.name = 'DocsContentsError';
+    }
+}
+/** Reader page extensions: Fumadocs renders `.md` and `.mdx` pages. */
+export const PAGE_EXTENSIONS = ['.md', '.mdx'];
+/** Every non-excluded directory and reader page under the docs root. */
+export async function inventoryDocs(docsRoot, matcher) {
+    const directories = [];
+    const pages = [];
+    async function walk(relativeDir) {
+        directories.push(relativeDir);
+        const entries = await readdir(join(docsRoot, relativeDir), {
+            withFileTypes: true,
+        });
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+                continue;
+            }
+            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))) {
+                if (!matcher.excludesFile(entryPath))
+                    pages.push(entryPath);
+            }
+        }
+    }
+    await walk('.');
+    directories.sort();
+    pages.sort();
+    return { directories, pages };
+}
+/**
+ * Whether a directory is an index-only leaf: its own `index.md` is the only
+ * reader page in it or below it, so it renders as a single-page section.
+ * `pagePaths` are docs-relative POSIX reader page paths.
+ */
+export function isIndexOnlyLeaf(dirRelativePath, pagePaths) {
+    const prefix = dirRelativePath === '.' ? '' : `${dirRelativePath}/`;
+    const ownIndex = `${prefix}index.md`;
+    let hasIndex = false;
+    for (const path of pagePaths) {
+        if (!path.startsWith(prefix))
+            continue;
+        if (path !== ownIndex)
+            return false;
+        hasIndex = true;
+    }
+    return hasIndex;
+}
+/** A Contents href naming a heading on the same page, such as `#setup`. */
+export function isSamePageAnchor(href) {
+    return href.trim().startsWith('#');
+}
+const inlineMarkdown = unified().use(remarkParse);
+/**
+ * Whether a Contents entry is a real Markdown link to a same-page fragment.
+ * The Contents grammar is line-based, so it captures destinations such as
+ * `#a b`, `#a(b` or `#a\` that Markdown does not parse as links; those render
+ * as plain text and no link rule would ever validate them. The CommonMark
+ * parser the reader check uses decides, over the authored link text rather
+ * than the `href` truncated at the first `)`, so balanced `#a(b)` and escaped
+ * `#a\(b\)` fragments stay links. The links rule then checks the URL remark
+ * parsed against the page's headings.
+ */
+function isMarkdownSamePageLink(entry) {
+    const tree = inlineMarkdown.parse(entry.source ?? `[${entry.title}](${entry.href})`);
+    const paragraph = tree.children?.length === 1 ? tree.children[0] : undefined;
+    const link = paragraph?.type === 'paragraph' ? paragraph.children?.[0] : undefined;
+    return (link?.type === 'link' &&
+        link.position?.start.offset === 0 &&
+        (link.url ?? '').startsWith('#'));
+}
 /** Mask fenced examples without changing authored source line numbers. */
 function unfencedLines(markdown) {
     let fence;
@@ -34,14 +126,14 @@ 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}`);
+        throw new DocsContentsError(`Missing required ## Contents section in ${sourcePath}`, sourcePath);
     }
     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`);
+            throw new DocsContentsError(`${sourcePath}:${group.line}: Contents group "${group.title}" has no entries`, sourcePath);
         }
     };
     for (let i = headingIndex + 1; i < lines.length; i += 1) {
@@ -56,7 +148,7 @@ export function parseIndexContents(markdown, sourcePath = 'index.md', options =
             continue;
         }
         if (/^\s*[*+]\s+\[[^\]]+\]\([^)]+\)/.test(line)) {
-            throw new Error(`${sourcePath}:${i + 1}: Contents links must use a dash (-) bullet`);
+            throw new DocsContentsError(`${sourcePath}:${i + 1}: Contents links must use a dash (-) bullet`, sourcePath);
         }
         const match = line.match(/^\s*-\s+\[([^\]]+)\]\(([^)]+)\)/);
         if (match) {
@@ -72,6 +164,7 @@ export function parseIndexContents(markdown, sourcePath = 'index.md', options =
                             .replace(/^\s*[-–—:]\s*/, '')
                             .trim(),
                         separator: /^\s*([-–—:])/.exec(line.slice(match[0].length))?.[1],
+                        source: line.slice(match[0].indexOf('[')),
                     }
                     : {}),
             });
@@ -80,22 +173,47 @@ export function parseIndexContents(markdown, sourcePath = 'index.md', options =
     }
     checkGroup();
     if (entries.length === 0 && !options.allowEmpty) {
-        throw new Error(`No machine-readable links found under ## Contents in ${sourcePath}`);
+        throw new DocsContentsError(`No machine-readable links found under ## Contents in ${sourcePath}`, sourcePath);
     }
     return entries;
 }
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }
+/**
+ * Resolve one Contents entry to the page or section it places in navigation.
+ *
+ * Contents is machine-readable navigation, so every entry must target a page
+ * or a section index. The one exception is an index-only leaf: a single-page
+ * section may list same-page heading anchors as an in-page table of contents.
+ * Those resolve to `anchor` and place nothing in navigation; the `links` check
+ * rule validates that each heading exists.
+ */
 export async function resolveEntryTarget(docsRoot, directoryPath, dirRelativePath, entry, 
 /**
  * Page extensions a Contents link may target. MkDocs renders only `.md`;
  * Fumadocs also renders `.mdx` pages.
  */
-pageExtensions = ['.md'], matcher) {
+pageExtensions = ['.md'], matcher, options = {}) {
+    const indexPath = join(docsRoot, dirRelativePath, 'index.md');
+    const fail = (message) => {
+        throw new DocsContentsError(message, indexPath, entry.line);
+    };
+    if (isSamePageAnchor(entry.href)) {
+        if (!options.indexOnlyLeaf) {
+            fail(`Contents link "${entry.href}" in ${indexPath} is a same-page anchor; Contents must link pages or sections unless index.md is the only reader page in its directory and it has no child sections.`);
+        }
+        if (!isMarkdownSamePageLink(entry)) {
+            fail(`Contents link "${entry.href}" in ${indexPath} is not a valid Markdown link; fix its destination (escape or remove spaces and unbalanced parentheses).`);
+        }
+        return {
+            kind: 'anchor',
+            path: toPosixPath(posix.join(dirRelativePath, 'index.md')),
+        };
+    }
     const href = entry.href.split('#', 1)[0]?.trim() ?? '';
     if (!href) {
-        throw new Error(`Invalid contents link "${entry.href}" in ${join(docsRoot, dirRelativePath, 'index.md')}`);
+        fail(`Invalid contents link "${entry.href}" in ${indexPath}`);
     }
     let targetPath = resolve(directoryPath, href);
     if (!href.endsWith('.md')) {
@@ -108,16 +226,16 @@ pageExtensions = ['.md'], matcher) {
     if (relativeTargetPath.startsWith('../') ||
         relativeTargetPath === '..' ||
         relativeTargetPath.length === 0) {
-        throw new Error(`Contents link "${entry.href}" escapes the docs directory from ${join(docsRoot, dirRelativePath, 'index.md')}`);
+        fail(`Contents link "${entry.href}" escapes the docs directory from ${indexPath}`);
     }
     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`);
+        fail(`Contents link "${entry.href}" in ${indexPath} does not resolve to a Markdown file`);
     }
     if (!pageExtensions.includes(extname(targetPath))) {
-        throw new Error(`Contents link "${entry.href}" in ${join(docsRoot, dirRelativePath, 'index.md')} must point to a Markdown file or directory index`);
+        fail(`Contents link "${entry.href}" in ${indexPath} must point to a Markdown file or directory index`);
     }
     if (basename(targetPath) === 'index.md') {
         return {
@@ -139,16 +257,20 @@ export async function buildDocsNavTree(options) {
         throw new Error(`Missing required index.md at ${indexPath}`);
     }
     const indexMarkdown = await readFile(indexPath, 'utf8');
-    const contentsEntries = parseIndexContents(indexMarkdown, indexPath);
+    const contentsEntries = parseIndexContents(indexMarkdown, indexPath, {
+        locations: true,
+    });
     const matcher = createExclusionMatcher(options.nonReaderPaths ?? []);
+    const pagePaths = options.pagePaths ?? (await inventoryDocs(options.docsRoot, matcher)).pages;
+    const indexOnlyLeaf = isIndexOnlyLeaf(dirRelativePath, pagePaths);
     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, ['.md'], matcher);
-        if (resolvedTarget.kind === 'excluded')
+        const resolvedTarget = await resolveEntryTarget(options.docsRoot, directoryPath, dirRelativePath, entry, ['.md'], matcher, { indexOnlyLeaf });
+        if (resolvedTarget.kind === 'excluded' || resolvedTarget.kind === 'anchor')
             continue;
         if (resolvedTarget.kind === 'section' &&
             resolvedTarget.path === toPosixPath(join(dirRelativePath, 'index.md'))) {
@@ -175,6 +297,7 @@ export async function buildDocsNavTree(options) {
                 dirRelativePath: childDirRelativePath,
                 visitedDirectories: childVisitedDirectories,
                 nonReaderPaths: options.nonReaderPaths,
+                pagePaths,
             }),
         });
     }

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":"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;AAOD,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAGlD,CAAC;AACH,eAAO,MAAM,kBAAkB,QACoB,CAAC;AACpD,eAAO,MAAM,aAAa,QAC6D,CAAC;AAmDxF;;;;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;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,QAAQ,EAAE,MAAM,EAChB,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,GAC5C,MAAM,CAgBR;AAYD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAOD;;;;;;;;;GASG;AACH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GACvC,OAAO,CAUT;AA8KD;;;;;;;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"}
+{"version":3,"file":"fumadocs.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/fumadocs.ts"],"names":[],"mappings":"AAwBA;;;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;AAMD,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAGlD,CAAC;AACH,eAAO,MAAM,kBAAkB,QACoB,CAAC;AACpD,eAAO,MAAM,aAAa,QAC6D,CAAC;AASxF;;;;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;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,QAAQ,EAAE,MAAM,EAChB,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,GAC5C,MAAM,CAgBR;AAYD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAOD;;;;;;;;;GASG;AACH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GACvC,OAAO,CAUT;AAkLD;;;;;;;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,11 +1,10 @@
-import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { 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';
-const PAGE_EXTENSIONS = ['.md', '.mdx'];
+import { inventoryDocs, isIndexOnlyLeaf, PAGE_EXTENSIONS, parseIndexContents, resolveEntryTarget, } from './contents.js';
 const GROUP_FOLDER = /^\(.+\)$/;
 // The `pages` item grammar of the fumadocs-core 16.10.2 page-tree builder
 // (`resolveFolderItem`): exact rest entries, separators, links, and the
@@ -22,36 +21,6 @@ const FENCE = /^\s*(```|~~~)/;
 function parentDir(path) {
     return posix.dirname(path);
 }
-async function inventoryDocs(docsRoot, matcher) {
-    const directories = [];
-    const pages = [];
-    async function walk(relativeDir) {
-        directories.push(relativeDir);
-        const entries = await readdir(join(docsRoot, relativeDir), {
-            withFileTypes: true,
-        });
-        for (const entry of entries) {
-            if (entry.name.startsWith('.') || entry.name === 'node_modules') {
-                continue;
-            }
-            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))) {
-                if (!matcher.excludesFile(entryPath))
-                    pages.push(entryPath);
-            }
-        }
-    }
-    await walk('.');
-    directories.sort();
-    pages.sort();
-    return { directories, pages };
-}
 /**
  * Reduce a Markdown heading to the plain text a sidebar shows: images and
  * links keep their text, code spans keep their content, and emphasis and
@@ -174,7 +143,8 @@ export function hasImplicitIndex(relativeDir, existing) {
 }
 async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex, matcher, inventory, nonIndexUrls) {
     const indexPath = join(docsRoot, relativeDir, 'index.md');
-    const entries = parseIndexContents(markdown, indexPath);
+    const entries = parseIndexContents(markdown, indexPath, { locations: true });
+    const indexOnlyLeaf = isIndexOnlyLeaf(relativeDir, inventory.pages);
     // A folder the loader gives no implicit index (the docs root, a `root: true`
     // folder) must list `index` to show its landing page. Elsewhere, listing
     // `index` would demote the folder index to an ordinary child, so it is left
@@ -182,8 +152,10 @@ async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex,
     const pages = implicitIndex ? [] : ['index'];
     let currentGroup;
     for (const entry of entries) {
-        const target = await resolveEntryTarget(docsRoot, join(docsRoot, relativeDir), relativeDir, entry, PAGE_EXTENSIONS, matcher);
-        if (target.kind === 'excluded')
+        const target = await resolveEntryTarget(docsRoot, join(docsRoot, relativeDir), relativeDir, entry, PAGE_EXTENSIONS, matcher, { indexOnlyLeaf });
+        // Same-page anchors in an index-only leaf are an in-page table of
+        // contents, not navigation.
+        if (target.kind === 'excluded' || target.kind === 'anchor')
             continue;
         const targetDir = parentDir(target.path);
         let item;

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

@@ -1 +1 @@
-{"version":3,"file":"membership.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/membership.ts"],"names":[],"mappings":"AAMA,OAAO,EAML,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,YAAY,CAAC;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAqHD;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,gBAAgB,EAAE,GACrC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAoS/B;AAeD;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAwEhC"}
+{"version":3,"file":"membership.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/membership.ts"],"names":[],"mappings":"AAMA,OAAO,EAML,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,YAAY,CAAC;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAoHD;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,gBAAgB,EAAE,GACrC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAoS/B;AAeD;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAwEhC"}

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

@@ -1,9 +1,8 @@
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { extname, join, posix } from 'node:path';
 import YAML from 'yaml';
-import { buildDocsNavTree } from './contents.js';
+import { buildDocsNavTree, PAGE_EXTENSIONS } from './contents.js';
 import { FUMADOCS_LINK, FUMADOCS_REST_ITEMS, FUMADOCS_SEPARATOR, hasImplicitIndex, pageUrl, } from './fumadocs.js';
-const PAGE_EXTENSIONS = ['.md', '.mdx'];
 const URL_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
 function lineOf(source, needle) {
     const index = source.indexOf(needle);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.3.33",
+  "version": "0.3.35",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -32,21 +32,19 @@
     "commander": "^12.1.0",
     "entities": "6.0.1",
     "github-slugger": "2.0.0",
-    "jsdom": "29.1.1",
     "jsonc-parser": "3.2.1",
-    "mermaid": "11.12.3",
     "ora": "^9.0.0",
     "parse5": "7.3.0",
+    "pele": "1.10.0",
     "remark-gfm": "4.0.1",
     "remark-parse": "11.0.0",
     "unified": "11.0.5",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.3.33",
-    "@open-agent-toolkit/docs-transforms": "0.3.33"
+    "@open-agent-toolkit/control-plane": "0.3.35",
+    "@open-agent-toolkit/docs-transforms": "0.3.35"
   },
   "devDependencies": {
-    "@types/jsdom": "28.0.3",
     "@types/node": "^22.10.0",
     "tsc-alias": "^1.8.10",
     "tsx": "^4.21.0",