@open-agent-toolkit/cli 0.3.27 → 0.3.28

package/assets/templates/docs-app-fuma/AGENTS.md

@@ -22,6 +22,10 @@ Edit `docs/**/*.md` and their Contents, not generated app-root `index.md`, `.sou
 
 Mermaid is source. Important/mobile diagrams get matching light/dark SVG pairs, updated with the Mermaid in the same commit. Require meaningful alt text (about155 characters maximum), `role="img"`, `<title>`, `<desc>` and `aria-labelledby`, readable labels and useful viewBox. Inspect rendered diagrams in both themes; transforms do not validate diagram correctness. See the contributor contract for framework-specific asset paths and image behavior.
 
+## Install-root compatibility
+
+Before installing, follow the toolchain guide's exact `mdast-util-to-markdown: 2.1.2` policy. A new independent app gets app-root `pnpm-workspace.yaml`; a workspace member must use the existing root policy with explicit approval. Preserve settings/conflicts and never create a member-local workspace boundary. `--no-root-patch` changes only root-script handling. Verify actual resolution and keep the policy/lockfile; do not remove bold/italic content to avoid the Fumadocs handler defect.
+
 ## Commands and working directories
 
 From the **repository root**, enter this app:
@@ -30,20 +34,23 @@ From the **repository root**, enter this app:
 cd {{APP_CWD}}
 ```
 
-From the **app directory**, after edits:
+From the **repository root**, enter the app and validate after edits:
 
 ```bash
+cd {{APP_CWD}}
 pnpm docs:format
 pnpm docs:format:check
 pnpm docs:lint
 {{NAV_SYNC_CMD}}
 {{NAV_SYNC_CHECK_CMD}}
+pnpm docs:check
 pnpm build
 ```
 
-Lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; a disabled echo does not validate. From the **app directory**, regenerate the machine inventory with:
+Lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; a disabled echo does not validate. From the **repository root**, enter the app and regenerate the machine inventory with:
 
 ```bash
+cd {{APP_CWD}}
 {{GENERATE_INDEX_CMD}}
 ```
 

package/assets/templates/docs-app-fuma/docs/contributing/docs-toolchain.md

@@ -12,6 +12,40 @@ This page is for documentation contributors. Follow the [contributor map](index.
 - Node.js {{NODE_REQUIREMENT}}
 - pnpm 10+
 
+## Required install-root compatibility policy
+
+The current Fumadocs Markdown handler wrapper is incompatible with
+`mdast-util-to-markdown` 2.2.0: valid bold and italic content can recurse during
+compilation. Keep authored content and framework versions; constrain this
+transitive dependency to exactly `2.1.2` at the **effective pnpm install root**.
+This is a constrained fresh install, not an unconstrained compatibility claim.
+
+For a new independent app, the CLI creates app-root `pnpm-workspace.yaml` with
+`packages: []` and this policy. Install inside that app. For a workspace member,
+the CLI creates no local workspace boundary: install from the existing workspace
+root and propose this exact addition to its `pnpm-workspace.yaml`:
+
+```yaml
+overrides:
+  mdast-util-to-markdown: 2.1.2
+```
+
+Preserve all existing `packages`, overrides and other settings. Add the one entry
+under an existing `overrides` map rather than duplicating the key. Obtain the
+repository owner's approval before editing existing policy. A conflicting version
+or declined/skipped edit remains a manual setup requirement; stop before claiming
+a successful install/build. Do not split an actual workspace member with a local
+`pnpm-workspace.yaml`, or place an ineffective override in its `package.json`.
+`--no-root-patch` controls root build scripts only and never approves dependency
+policy changes. CLI init does not merge or overwrite existing root policy.
+
+Use the repository's selected pnpm version (10+). This root YAML syntax works
+with pnpm 10 and 12; pnpm 12 ignores `package.json`'s `pnpm.overrides`, and pnpm 10
+ignores policy in a workspace member. After installation, inspect
+`pnpm why mdast-util-to-markdown` from the effective root to confirm `2.1.2`, then
+run the checker and real build below. Retain the effective root policy and
+lockfile in version control. Do not change a user-scope package-manager install.
+
 ## Install and preview
 
 From the **repository root**, enter the docs app; subsequent commands run in the **app directory**:
@@ -22,26 +56,29 @@ pnpm install
 pnpm dev
 ```
 
-Fumadocs generates a static export under `out/`. `pnpm start` expects a Next server and is not the static-export preview command; serve `out/` with a static HTTP server and mount the configured base path.
+Fumadocs generates a static export under `out/`. `cd {{APP_CWD}} && pnpm start` expects a Next server and is not the static-export preview command; serve `out/` with a static HTTP server and mount the configured base path.
 
 ## Validate before committing
 
-From the **app directory**, in this order:
+From the **repository root**, enter the app and validate in this order:
 
 ```bash
+cd {{APP_CWD}}
 pnpm docs:format
 pnpm docs:format:check
 pnpm docs:lint
 {{NAV_SYNC_CMD}}
 {{NAV_SYNC_CHECK_CMD}}
+pnpm docs:check
 pnpm build
 ```
 
 Lint is {{LINT_STATUS}}; formatting is {{FORMAT_STATUS}}. Disabled scripts print a message and are not validation. Nav sync writes only approved, owned navigation; the read-only check fails on drift or unlisted reader pages. Inspect the rendered site for navigation, links, tabs and diagrams.
 
-From the **app directory**, regenerate the machine inventory when needed:
+From the **repository root**, enter the app and regenerate the machine inventory when needed:
 
 ```bash
+cd {{APP_CWD}}
 {{GENERATE_INDEX_CMD}}
 ```
 

package/assets/templates/docs-app-fuma/docs/contributing.md

@@ -66,6 +66,7 @@ Tables, task lists, fenced code, callouts, Mermaid and `=== "Title"` tabs are su
         | Reader links | Resolve |
 
         ```bash
+        cd {{APP_CWD}}
         pnpm docs:lint
         ```
     ````
@@ -82,13 +83,16 @@ Tables, task lists, fenced code, callouts, Mermaid and `=== "Title"` tabs are su
         | Reader links | Resolve |
 
         ```bash
+        cd {{APP_CWD}}
         pnpm docs:lint
         ```
 
-Not configured: arbitrary custom components, executable notebooks, API playgrounds, diagram syntax validation or screenshot testing. Do not describe those as supported without an approved configuration and a working example. Check the actual package scripts: lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; disabled scripts only print a message.
+Not configured: arbitrary custom components, executable notebooks, API playgrounds or screenshot testing. Do not describe those as supported without an approved configuration and a working example. Check the actual package scripts: lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; disabled scripts only print a message.
 
 ## Diagrams and accessibility
 
+Run the app’s docs:check script (from the repository root: `cd {{APP_CWD}} && pnpm docs:check`) before committing. It checks reader metadata/maps/links, navigation, contributor commands and real Mermaid syntax without building the site. Errors fail; warnings prompt review. Fix authored sources, then explicitly sync owned navigation and retry.
+
 Mermaid is the diagram source of truth. Important or phone-sized diagrams also get matching `<name>-light.svg` and `<name>-dark.svg` assets. Change the Mermaid and both SVGs in the same commit, preserving nodes, edges and labels. Each SVG uses `role="img"`, a descriptive `<title>` and `<desc>` (connected with `aria-labelledby`), a legible viewBox and readable labels. Keep image alt text concise, about 155 characters or less, and describe the diagram's meaning without inventing claims.
 
 === "Syntax"
@@ -106,6 +110,8 @@ Mermaid is the diagram source of truth. Important or phone-sized diagrams also g
 
     ```mermaid
     flowchart LR
+      accTitle: Documentation edit
+      accDescr: Read the local map before making a focused edit.
       A[Read local map] --> B[Make a focused edit]
     ```
 

package/assets/templates/docs-app-fuma/docs/index.md

@@ -1,6 +1,6 @@
 ---
 title: '{{SITE_NAME}}'
-description: '{{SITE_DESCRIPTION}}'
+description: '{{PAGE_DESCRIPTION}}'
 ---
 
 # {{SITE_NAME}}

package/assets/templates/docs-app-fuma/gitignore.template

@@ -0,0 +1,12 @@
+# Dependencies
+node_modules/
+
+# Next.js build output
+.next/
+out/
+
+# fumadocs-mdx generated source
+.source/
+
+# Next.js generated types
+next-env.d.ts

package/assets/templates/docs-app-fuma/package.json.template

@@ -7,9 +7,10 @@
   "scripts": {
     "predev": "fumadocs-mdx && {{GENERATE_INDEX_CMD}}",
     "dev": "next dev",
-    "prebuild": "{{NAV_SYNC_CHECK_CMD}} && fumadocs-mdx && {{GENERATE_INDEX_CMD}}",
+    "prebuild": "{{DOCS_CHECK_CMD}} && {{NAV_SYNC_CHECK_CMD}} && fumadocs-mdx && {{GENERATE_INDEX_CMD}}",
     "build": "next build",
     "start": "next start",
+    "docs:check": "{{DOCS_CHECK_CMD}}",
     "docs:lint": "{{DOCS_LINT_SCRIPT}}",
     "docs:format": "{{DOCS_FORMAT_SCRIPT}}",
     "docs:format:check": "{{DOCS_FORMAT_CHECK_SCRIPT}}"

package/assets/templates/docs-app-fuma/pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+# Keep this policy at the actual pnpm install root, never only in a member.
+# Fumadocs currently loses Markdown handler properties introduced in 2.2.0.
+packages: []
+overrides:
+  mdast-util-to-markdown: 2.1.2

package/assets/templates/docs-app-mkdocs/AGENTS.md

@@ -32,15 +32,17 @@ From the **repository root**, enter this app:
 cd {{APP_CWD}}
 ```
 
-From the **app directory**, after edits:
+From the **repository root**, enter the app and validate after edits:
 
 ```bash
+cd {{APP_CWD}}
 pnpm docs:format
 pnpm docs:format:check
 pnpm docs:lint
 {{NAV_SYNC_CMD}}
 {{NAV_SYNC_CHECK_CMD}}
+pnpm docs:check
 pnpm docs:build
 ```
 
-Lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; a disabled echo does not validate. The existing test echo is not a check. Setup/preview details and legacy support are in the toolchain guide.
+Lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; a disabled echo does not validate. The test script runs the portable docs checker. Setup/preview details and legacy support are in the toolchain guide.

package/assets/templates/docs-app-mkdocs/docs/contributing/docs-toolchain.md

@@ -30,15 +30,17 @@ pnpm docs:dev
 
 ## Validate before committing
 
-From the **app directory**, in this order:
+From the **repository root**, enter the app and validate in this order:
 
 ```bash
+cd {{APP_CWD}}
 pnpm docs:format
 pnpm docs:format:check
 pnpm docs:lint
 {{NAV_SYNC_CMD}}
 {{NAV_SYNC_CHECK_CMD}}
+pnpm docs:check
 pnpm docs:build
 ```
 
-Lint is {{LINT_STATUS}}; formatting is {{FORMAT_STATUS}}. Disabled scripts print a message and are not validation. Nav sync writes only approved, owned navigation; the read-only check fails on navigation drift. Inspect the rendered site for navigation, links, tabs and diagrams. The existing MkDocs `test` echo is not a validation check.
+Lint is {{LINT_STATUS}}; formatting is {{FORMAT_STATUS}}. Disabled scripts print a message and are not validation. Nav sync writes only approved, owned navigation; the read-only check fails on navigation drift. Inspect the rendered site for navigation, links, tabs and diagrams. The MkDocs test script also runs the portable docs checker.

package/assets/templates/docs-app-mkdocs/docs/contributing.md

@@ -70,6 +70,7 @@ Tables, task lists, fenced code, callouts, Mermaid and `=== "Title"` tabs are su
         | Reader links | Resolve |
 
         ```bash
+        cd {{APP_CWD}}
         pnpm docs:lint
         ```
     ````
@@ -86,13 +87,16 @@ Tables, task lists, fenced code, callouts, Mermaid and `=== "Title"` tabs are su
         | Reader links | Resolve |
 
         ```bash
+        cd {{APP_CWD}}
         pnpm docs:lint
         ```
 
-Not configured: arbitrary custom components, executable notebooks, API playgrounds, diagram syntax validation or screenshot testing. Do not describe those as supported without an approved configuration and a working example. Check the actual package scripts: lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; disabled scripts only print a message.
+Not configured: arbitrary custom components, executable notebooks, API playgrounds or screenshot testing. Do not describe those as supported without an approved configuration and a working example. Check the actual package scripts: lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; disabled scripts only print a message.
 
 ## Diagrams and accessibility
 
+Run the app’s docs:check script (from the repository root: `cd {{APP_CWD}} && pnpm docs:check`) before committing. It checks reader metadata/maps/links, navigation, contributor commands and real Mermaid syntax without building the site. Errors fail; warnings prompt review. Fix authored sources, then explicitly sync owned navigation and retry.
+
 Mermaid is the diagram source of truth. Important or phone-sized diagrams also get matching `<name>-light.svg` and `<name>-dark.svg` assets. Change the Mermaid and both SVGs in the same commit, preserving nodes, edges and labels. Each SVG uses `role="img"`, a descriptive `<title>` and `<desc>` (connected with `aria-labelledby`), a legible viewBox and readable labels. Keep image alt text concise, about 155 characters or less, and describe the diagram's meaning without inventing claims.
 
 === "Syntax"
@@ -110,6 +114,8 @@ Mermaid is the diagram source of truth. Important or phone-sized diagrams also g
 
     ```mermaid
     flowchart LR
+      accTitle: Documentation edit
+      accDescr: Read the local map before making a focused edit.
       A[Read local map] --> B[Make a focused edit]
     ```
 

package/assets/templates/docs-app-mkdocs/docs/index.md

@@ -1,6 +1,6 @@
 ---
 title: '{{SITE_NAME}}'
-description: '{{SITE_DESCRIPTION}}'
+description: '{{PAGE_DESCRIPTION}}'
 ---
 
 # {{SITE_NAME}}

package/assets/templates/docs-app-mkdocs/gitignore.template

@@ -0,0 +1,8 @@
+# Dependencies
+node_modules/
+
+# MkDocs build output
+site/
+
+# Python virtual environment
+.venv/

package/assets/templates/docs-app-mkdocs/package.json.template

@@ -6,12 +6,13 @@
   "description": "MkDocs Material documentation for {{SITE_NAME}}.",
   "scripts": {
     "docs:dev": "mkdocs serve",
-    "docs:build": "{{NAV_SYNC_CHECK_CMD}} && mkdocs build",
+    "docs:build": "{{DOCS_CHECK_CMD}} && {{NAV_SYNC_CHECK_CMD}} && mkdocs build",
     "docs:setup": "sh ./setup-docs.sh",
+    "docs:check": "{{DOCS_CHECK_CMD}}",
     "docs:lint": "{{DOCS_LINT_SCRIPT}}",
     "docs:format": "{{DOCS_FORMAT_SCRIPT}}",
     "docs:format:check": "{{DOCS_FORMAT_CHECK_SCRIPT}}",
-    "test": "echo 'Documentation tests complete'"
+    "test": "{{DOCS_CHECK_CMD}}"
   },
   "devDependencies": {
     "@open-agent-toolkit/cli": "{{OAT_CLI_DEP}}"{{DEV_DEPENDENCIES}}

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/config/index.js

@@ -11,6 +11,7 @@ import { compileDispatchCeilingPreset } from '../../config/dispatch-ceiling-pres
 import { normalizeDispatchMatrix, validateDispatchRouteTarget, walkDispatchMatrix, } from '../../config/dispatch-matrix.js';
 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 { 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';
@@ -67,6 +68,7 @@ const KEY_ORDER = [
     'archive.awsRegion',
     'autoReviewAtCheckpoints',
     'lastPausedProject',
+    'documentation.check',
     'documentation.ia',
     'documentation.nonReaderPaths',
     'documentation.navOwner',
@@ -242,6 +244,17 @@ const CONFIG_CATALOG = [
         description: 'Deprecated compatibility alias for workflow.autoReviewAtHillCheckpoints. Prefer `oat config set workflow.autoReviewAtHillCheckpoints <true|false>`.',
         deprecated: { supersededBy: 'workflow.autoReviewAtHillCheckpoints' },
     },
+    {
+        key: 'documentation.check',
+        group: 'Shared Repo (.oat/config.json)',
+        scope: 'shared repo',
+        file: '.oat/config.json',
+        type: 'JSON object',
+        defaultValue: 'null (portable checker defaults)',
+        mutability: 'read/write',
+        owningCommand: 'oat config set documentation.check <JSON>',
+        description: 'Portable docs rule severities, named thresholds, reason-bearing path exceptions, provenance patterns and diagram base ref.',
+    },
     {
         key: 'documentation.ia',
         group: 'Shared Repo (.oat/config.json)',
@@ -1822,6 +1835,7 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
     const effectiveSurface = surface === 'auto' ? defaultSurfaceForKey(key) : surface;
     if (key === 'documentation.nonReaderPaths' ||
         key === 'documentation.guidance' ||
+        key === 'documentation.check' ||
         key === 'documentation.ia' ||
         key === 'documentation.navOwner') {
         const configPath = effectiveSurface === 'user'
@@ -1831,7 +1845,13 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
         const trimmed = rawValue.trim();
         let value;
         try {
-            if (key === 'documentation.nonReaderPaths') {
+            if (key === 'documentation.check') {
+                const parsed = JSON.parse(trimmed);
+                if (parsed === null)
+                    throw new Error('Expected a checker JSON object.');
+                value = normalizeDocumentationCheck(parsed);
+            }
+            else if (key === 'documentation.nonReaderPaths') {
                 const paths = parseDocumentationExcludes(rawValue);
                 value = paths.length > 0 ? paths : undefined;
             }
@@ -1848,8 +1868,10 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
                         : normalizeDocumentationGuidance(trimmed.startsWith('[') ? JSON.parse(trimmed) : trimmed, configPath, effectiveSurface === 'user' ? 'user' : 'shared');
             }
         }
-        catch {
-            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'}.`);
+        catch (error) {
+            if (key === 'documentation.check')
+                throw 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 };
         try {
@@ -2450,6 +2472,7 @@ async function unsetConfigValue(repoRoot, userConfigDir, key, surface, dependenc
 async function removeFromSurface(repoRoot, userConfigDir, key, effectiveSurface, path, dependencies) {
     if (key === 'documentation.nonReaderPaths' ||
         key === 'documentation.guidance' ||
+        key === 'documentation.check' ||
         key === 'documentation.ia' ||
         key === 'documentation.navOwner') {
         const configPath = effectiveSurface === 'user'
@@ -2577,6 +2600,15 @@ async function removeConfigPathOnDisk(configPath, path) {
     if (!isRecord(parsed)) {
         return null;
     }
+    // Checker null is malformed rather than an inherited unset sentinel.
+    if (path.join('.') === 'documentation.check' &&
+        isRecord(parsed.documentation) &&
+        Object.hasOwn(parsed.documentation, 'check')) {
+        return {
+            ...parsed,
+            documentation: withoutOwnKey(parsed.documentation, 'check'),
+        };
+    }
     const { next, removed } = removeConfigPath(parsed, path);
     return removed ? next : null;
 }

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

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createDocsCheckCommand(): Command;
+//# sourceMappingURL=check.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,48 @@
+import { buildCommandContext } from '../../../app/command-context.js';
+import { readGlobalOptions } from '../../shared/shared.utils.js';
+import { Command } from 'commander';
+import { checkDocs } from './checker.js';
+export function createDocsCheckCommand() {
+    return new Command('check')
+        .description('Read-only portable reader, navigation, command and diagram validation')
+        .option('--target-dir <dir>', 'Docs app root or literal Markdown content root')
+        .option('--rule <id...>', 'Run only these stable rule IDs (repeatable)', (values, previous) => previous.concat(values), [])
+        .action(async (options, command) => {
+        const context = buildCommandContext(readGlobalOptions(command));
+        let result;
+        try {
+            result = await checkDocs({
+                cwd: context.cwd,
+                targetDir: options.targetDir,
+                rules: options.rule,
+            });
+            process.exitCode = result.summary.errors ? 1 : 0;
+        }
+        catch (error) {
+            const message = error.message;
+            result = {
+                summary: { errors: 1, warnings: 0 },
+                findings: [
+                    {
+                        ruleId: 'configuration',
+                        severity: 'error',
+                        path: '.oat/config.json',
+                        message,
+                    },
+                ],
+            };
+            // Invalid input/config is actionable. Unexpected filesystem/runtime
+            // failures retain the CLI's separate runtime-error exit convention.
+            process.exitCode = error.code ? 2 : 1;
+        }
+        if (context.json)
+            context.logger.json(result);
+        else {
+            for (const f of result.findings) {
+                const location = `${f.path}${f.line === undefined ? '' : `:${f.line}`}`;
+                context.logger[f.severity === 'error' ? 'error' : 'warn'](`${location} [${f.ruleId}] ${f.message}`);
+            }
+            context.logger.info(`Docs check: ${result.summary.errors} error(s), ${result.summary.warnings} warning(s).`);
+        }
+    });
+}

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

@@ -0,0 +1,17 @@
+import type { DocsCheckRule } from '../../../config/documentation-check.js';
+export interface DocsFinding {
+    ruleId: DocsCheckRule | 'configuration';
+    severity: 'error' | 'warn';
+    path: string;
+    line?: number;
+    message: string;
+}
+export interface DocsCheckResult {
+    summary: {
+        errors: number;
+        warnings: number;
+    };
+    findings: DocsFinding[];
+}
+export type Report = (rule: DocsCheckRule, severity: 'error' | 'warn', path: string, message: string, line?: number) => void;
+//# sourceMappingURL=check.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"check.types.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/check.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,aAAa,GAAG,eAAe,CAAC;IACxC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AACD,MAAM,MAAM,MAAM,GAAG,CACnB,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,OAAO,GAAG,MAAM,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,KACV,IAAI,CAAC"}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,8 @@
+import type { DocsCheckResult } from './check.types.js';
+/** Read-only portable checker. Output paths are content-root-relative POSIX. */
+export declare function checkDocs(options: {
+    cwd: string;
+    targetDir?: string;
+    rules?: string[];
+}): Promise<DocsCheckResult>;
+//# sourceMappingURL=checker.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,82 @@
+import { createExclusionMatcher, isExcludedPath, } from '../../docs/shared/exclusions.js';
+import { DOCS_CHECK_RULES, } from '../../../config/documentation-check.js';
+import { checkCommands } from './commands.js';
+import { checkDiagrams } from './diagrams.js';
+import { readPage, readerFiles, resolveCheckTarget } from './files.js';
+import { checkNavigation } from './navigation.js';
+import { checkProvenance, checkReaders } from './reader-rules.js';
+/** Read-only portable checker. Output paths are content-root-relative POSIX. */
+export async function checkDocs(options) {
+    const unknown = options.rules?.find((rule) => !DOCS_CHECK_RULES.includes(rule));
+    if (unknown)
+        throw new Error(`Unknown docs check rule "${unknown}". Choose: ${DOCS_CHECK_RULES.join(', ')}.`);
+    const target = await resolveCheckTarget(options.cwd, options.targetDir);
+    const policy = target.documentation.check;
+    const findings = [];
+    const exceptions = policy?.exceptions?.map((e) => ({
+        ...e,
+        matcher: createExclusionMatcher([e.path]),
+    })) ?? [];
+    const report = (ruleId, defaultSeverity, path, message, line) => {
+        if (options.rules?.length && !options.rules.includes(ruleId))
+            return;
+        let severity = policy?.rules?.[ruleId] ?? defaultSeverity;
+        for (const e of exceptions)
+            if (e.rule === ruleId && isExcludedPath(e.matcher, path))
+                severity = e.severity ?? 'off';
+        if (severity === 'off')
+            return;
+        findings.push({
+            ruleId,
+            severity,
+            path,
+            ...(line === undefined ? {} : { line }),
+            message,
+        });
+    };
+    const pages = [];
+    for (const path of await readerFiles(target)) {
+        try {
+            const page = await readPage(target, path);
+            pages.push(page);
+            if (page.frontmatterError)
+                report('frontmatter', 'error', path, page.frontmatterError, 1);
+        }
+        catch (error) {
+            const code = error?.code;
+            const safeCode = typeof code === 'string' && /^[A-Z][A-Z0-9_]*$/.test(code)
+                ? code
+                : 'UNKNOWN';
+            report('frontmatter', 'error', path, `Cannot read documentation source (${safeCode}); check file permissions and readability.`, 1);
+        }
+    }
+    await checkReaders(target, pages, report);
+    checkProvenance(target, pages, report);
+    if (!options.rules?.length || options.rules.includes('navigation'))
+        await checkNavigation(target, report);
+    if (!options.rules?.length || options.rules.includes('commands'))
+        await checkCommands(target, pages, report);
+    if (!options.rules?.length ||
+        options.rules.some((r) => [
+            'mermaid',
+            'diagram-accessibility',
+            'diagram-pairs',
+            'diagram-freshness',
+            'image-alt',
+        ].includes(r)))
+        await checkDiagrams(target, pages, report);
+    findings.sort((a, b) => a.path < b.path
+        ? -1
+        : a.path > b.path
+            ? 1
+            : (a.line ?? 0) - (b.line ?? 0) ||
+                a.ruleId.localeCompare(b.ruleId) ||
+                a.message.localeCompare(b.message));
+    return {
+        summary: {
+            errors: findings.filter((f) => f.severity === 'error').length,
+            warnings: findings.filter((f) => f.severity === 'warn').length,
+        },
+        findings,
+    };
+}

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

@@ -0,0 +1,5 @@
+import type { Report } from './check.types.js';
+import { type CheckTarget } from './files.js';
+import type { ParsedPage } from './markdown.js';
+export declare function checkCommands(target: CheckTarget, pages: ParsedPage[], report: Report): Promise<void>;
+//# sourceMappingURL=commands.d.ts.map

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

@@ -0,0 +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"}