@open-agent-toolkit/cli 0.3.27 → 0.3.29

package/assets/skills/oat-docs-bootstrap/references/pr-ci.md

@@ -0,0 +1,89 @@
+# Pull-request docs checks
+
+Load this recipe during bootstrap config inspection, including Markdown setup.
+Present the exact workflow diff for the selected repo and get approval before
+writing it. Preserve existing triggers, jobs, permissions and steps. Existing-app
+repair remains analyze/apply work; this recipe does not authorize scaffold or CI
+replacement, deployment, or publication.
+
+## Resolve the concrete inputs
+
+Read the actual shared config and package scripts, then substitute these values
+in the existing PR workflow (or propose a new docs job if none exists):
+
+- `DOCS_ROOT`: configured repository-relative documentation root.
+- `DOCS_CONTENT`: literal root for Markdown; actual framework content directory.
+- `DOCS_TOOLING`: `markdown`, `fumadocs` or `mkdocs`.
+- `DOCS_BUILD_SCRIPT`: actual app build script (`build` for Fumadocs,
+  `docs:build` for the starter MkDocs app); empty for Markdown.
+- `DOCS_MANIFEST`: only an explicitly configured **generated Markdown inventory**,
+  such as a Fumadocs app-root `index.md`. Leave empty for Markdown unless the
+  user separately configured an external inventory. An authored Markdown index
+  or MkDocs YAML is not a generated Markdown inventory.
+
+Use Node >=22.17 and the repo's package-manager pin. Provision the selected CLI
+version through the repo's existing dependency installation; framework starters
+declare it in their app package. Add the app's `node_modules/.bin` to `GITHUB_PATH`
+when the binary is installed there. A Markdown-only repo uses its existing approved
+CLI provision; do not introduce an app, dependency install or build just for this
+recipe. For MkDocs use the selected Python environment and the existing pinned
+requirements/setup script. Do not upgrade framework or Python packages implicitly.
+In a workspace install from the workspace root; for a nested standalone app,
+install in that app. Keep existing unrelated setup steps. For Fumadocs, first
+inspect the approved effective-root `pnpm-workspace.yaml` compatibility override
+(`mdast-util-to-markdown: 2.1.2`) from Step4a; verify actual resolution and retain
+the lockfile. Do not use member-only policy, silently merge a conflicting root
+setting or claim an unconstrained install. A pending/declined root edit leaves
+setup unverified.
+
+Checkout needs full history so the read-only diagram comparison can use
+`origin/main` (or the configured `documentation.check.diagramBaseRef`). For a
+custom base fetch that ref explicitly. A missing base leaves static checks active
+but reports diagram freshness unverified; do not label that result verified.
+
+## Verification steps
+
+This concrete example uses a Fumadocs root `docs-site`. Substitute every env value
+from the inspected repo, retaining the same checker → build → configured-manifest
+order. The `oat` binary must be on PATH from the provision above. Generated manifests
+are committed; the freshness step rejects an untracked output too.
+
+```yaml
+- uses: actions/checkout@v5
+  with:
+    fetch-depth: 0
+# Keep the repo's Node/package-manager/dependency setup here.
+- name: Verify documentation
+  env:
+    DOCS_ROOT: docs-site
+    DOCS_CONTENT: docs-site/docs
+    DOCS_TOOLING: fumadocs
+    DOCS_BUILD_SCRIPT: build
+    DOCS_MANIFEST: docs-site/index.md
+  shell: bash
+  run: |
+    set -euo pipefail
+    oat docs check --target-dir "$DOCS_ROOT"
+    if [ "$DOCS_TOOLING" != markdown ]; then
+      (cd "$DOCS_ROOT" && pnpm run "$DOCS_BUILD_SCRIPT")
+    fi
+    if [ -n "$DOCS_MANIFEST" ]; then
+      git ls-files --error-unmatch -- "$DOCS_MANIFEST"
+      oat docs generate-index --docs-dir "$DOCS_CONTENT" --output "$DOCS_MANIFEST"
+      git diff --exit-code -- "$DOCS_MANIFEST"
+    fi
+```
+
+Run those exact commands locally from the repository root after installation,
+with the same concrete inputs and PATH. Record checker, real framework build and
+freshness exits separately. A seeded missing description must fail the checker;
+a stale committed configured manifest must fail the final diff. Restore fixtures
+after each control. A command-order stub is not a framework build. Markdown uses
+empty build/manifest inputs and runs only the checker.
+
+If a check fails, repair the authored metadata/maps/links or explicitly sync owned
+navigation; never remove the check, silently regenerate a hand-authored sidebar,
+or add a blanket exclusion. Review warnings and narrow reason-bearing exceptions.
+A build that regenerates an inventory does not prove committed freshness: keep
+the final Git diff after the build. Report unverified or declined CI changes in
+the bootstrap exit summary rather than claiming CI is wired.

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":"AAIA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAIhF,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAqBzC,OAAO,EAUL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EAQnB,KAAK,UAAU,EAwBhB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAGL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAGL,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAC/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,mCAAmC,EACnC,0BAA0B,EAC3B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8KpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kCAAkC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7E,2CAA2C,EAAE,CAC3C,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,gDAAgD,EAAE,CAChD,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,6CAA6C,EAAE,CAC7C,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,yBAAyB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IACxE,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC7C,mCAAmC,EAAE,OAAO,mCAAmC,CAAC;IAChF,0BAA0B,EAAE,OAAO,0BAA0B,CAAC;IAC9D,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AA85HD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAqMT"}

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"}