@open-agent-toolkit/cli 0.3.27 → 0.3.28

package/README.md

@@ -47,6 +47,12 @@ Additional useful entry points:
 
 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).
+
+Fumadocs starters constrain `mdast-util-to-markdown` to 2.1.2 for the current upstream handler compatibility defect. New independent install roots get `pnpm-workspace.yaml`; workspace members get manual setup advice for the existing root YAML, with approval/conflict preservation in bootstrap. No member-local boundary or root dependency-policy merge is performed; `--no-root-patch` still controls build scripts only. Keep the effective policy and lockfile and verify actual resolution before building.
+
+Framework starters expose `docs:check` and run it before build; MkDocs `test` is a real check. Bootstrap proposes approved PR CI edits with explicit generated-manifest freshness. Markdown needs neither an app build nor a default manifest.
+
 ## Update Notifications
 
 On ordinary interactive command runs, OAT may print a passive notice when npm's stable `latest` CLI version is newer than the installed version. The cache normally limits checks to once every 24 hours and same-version notices to once every 72 hours; overlapping CLI processes can each perform a check or print a notice.

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.27"
+  "oatVersion": "0.3.28"
 }

package/assets/docs/contributing/documentation.md

@@ -43,9 +43,9 @@ To add a page, choose its scope from the nearest map, add title/description fron
 
 Use **Markdown → existing transform → MDX** in that order. Tables, task lists, fenced code, callouts, nested tabs and Mermaid are configured. MDX is for actual JSX/component needs and is excluded from the Markdown manifest and agent endpoints. See [Markdown Features](markdown-features.md) for paired Syntax/Rendered examples.
 
-Not configured: executable notebooks, API playgrounds, diagram syntax validation or screenshot testing. A successful build or Mermaid transform test does not prove diagram validity. Keep language labels on code fences and use `bash` for shell commands.
+Not configured: executable notebooks, API playgrounds, screenshot testing. The portable checker validates Mermaid syntax with the installed parser; a successful build alone does not prove diagram validity or visual correctness. Keep language labels on code fences and use `bash` for shell commands.
 
-Mermaid is diagram source. Important or phone-sized diagrams also get matching light/dark SVGs under `public/diagrams/`, linked as `/diagrams/name-light.svg` and `/diagrams/name-dark.svg`; the theme adds the base path, selects the theme and supports zoom. Update source and both SVGs in the same commit. Use descriptive SVG `<title>`/`<desc>` with `role="img"` and `aria-labelledby`, readable labels and concise meaningful image alt text (about 155 characters or less).
+Mermaid is diagram source; include `accTitle` and `accDescr`. Important or phone-sized diagrams also get matching light/dark SVGs under `public/diagrams/`, linked as `/diagrams/name-light.svg` and `/diagrams/name-dark.svg`; the theme adds the base path, selects the theme and supports zoom. Update source and both SVGs in the same commit. Use descriptive SVG `<title>`/`<desc>` with `role="img"` and `aria-labelledby`, readable labels and concise meaningful image alt text (about 155 characters or less).
 
 ## Local workflow
 
@@ -84,6 +84,15 @@ All commands below run from the **repository root**. Contributor setup is in [Co
    pnpm --filter oat-docs docs:format:check
    ```
 
+Run portable validation from the repository root before committing:
+
+```bash
+pnpm --filter oat-docs docs:check
+pnpm docs:validate
+```
+
+The first command checks reader structure/metadata/links, contributor commands, navigation and diagrams without a build. Errors fail; warnings prompt review. The second retains flagship hosted README/catalog/live-consumer checks too. See [Check Documentation](../docs-tooling/check.md) for policy, counting and repair guidance.
+
 ## Authoring Expectations
 
 - Keep docs aligned with the current repo behavior and current command surface.

package/assets/docs/docs-tooling/add-docs-to-a-repo.md

@@ -326,3 +326,13 @@ need.
   and frontmatter; it only previews changes until you pass `--apply`.
 
 MkDocs/Material scaffolding is **legacy**; its existing Python pins remain unchanged. [Material's changelog](https://squidfunk.github.io/mkdocs-material/changelog/) says Material receives critical/security fixes through May 5, 2027 and names Zensical as its successor. That lifecycle belongs to Material, not MkDocs core, and does not promise that the scaffold's older pins contain the latest fixes. Pinned MkDocs 1.4.2 still renders configured non-reader routes even though OAT omits them from navigation and manifests.
+
+## Verify the scaffold in PR CI
+
+Current framework starters run `docs:check` before build and MkDocs `test` runs the same checker. Bootstrap presents concrete CI edits after inspecting config: checker, actual framework build, then regeneration and Git diff of a configured generated Markdown inventory. It preserves existing workflow content and writes only the approved diff. Use full-history checkout/fetch for diagram comparisons. Markdown gets checker-only wiring unless an external manifest was separately configured. See [Check Documentation](check.md) for diagnostics and repair.
+
+## Fumadocs install-root compatibility
+
+Current Fumadocs needs exact `mdast-util-to-markdown: 2.1.2` to avoid the upstream bold/italic handler recursion in 2.2.0. CLI init creates a small `pnpm-workspace.yaml` only for a new independent app that is its own installation root. A real workspace member gets no local boundary: bootstrap presents the exact root YAML override for approval, preserving package globs, unrelated settings and conflicting pins. Declined/skipped edits remain manual and build verification stays pending. `--no-root-patch` controls root build scripts only.
+
+Use effective-root `pnpm-workspace.yaml` for pnpm 10+ (including 12, which ignores `package.json`'s `pnpm.overrides`); member-only policy is ineffective. After installing from the actual root, inspect `pnpm why mdast-util-to-markdown`, confirm 2.1.2 and retain root config/lockfile. Run the checker and real build with all authored content preserved. This is a constrained fresh-install policy, not a framework upgrade or an unconstrained resolution claim.

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

@@ -0,0 +1,154 @@
+---
+title: Check Documentation
+description: Validate reader structure, links, navigation, contributor commands and accessible diagram sources without building a site.
+---
+
+# Check Documentation
+
+Run the portable checker before committing documentation. It reads authored
+Markdown/MDX, config, local package scripts and diagram assets; it never builds a
+site, runs page scripts or MDX, executes documented commands, or fetches links.
+
+```bash
+oat docs check
+oat docs check --target-dir docs-site
+oat docs check --rule description h1 --rule links --json
+```
+
+Omitted targets use `documentation.root`, then the existing `docs` fallback.
+Framework app roots resolve to their content directory. A literal Markdown root
+stays literal even with a child named `docs`. Paths in findings are deterministic,
+content-root-relative POSIX paths; physical line locations are included when
+available, including nested supported tabs. No sidebar or default manifest is
+required for Markdown.
+
+## Results and repair
+
+Errors exit **1**; warning-only runs exit **0**. System/runtime failures retain
+exit **2**. Unknown rule IDs and malformed checker config are actionable
+`configuration` findings. JSON has exactly these top-level keys:
+
+```json
+{
+  "summary": { "errors": 1, "warnings": 0 },
+  "findings": [
+    {
+      "ruleId": "description",
+      "severity": "error",
+      "path": "guide.md",
+      "line": 1,
+      "message": "Frontmatter description is required and must be nonempty."
+    }
+  ]
+}
+```
+
+Fix the authored page, its local Contents map and inbound links together. For
+owned generated navigation, run `oat docs nav sync`, then rerun the checker.
+Hand-authored or undeclared navigation is compared for membership/order without
+requiring generated display labels, title fields or YAML formatting; do not
+silently regenerate it. Missing optional Fumadocs metadata, metadata objects without
+`pages`, and absent MkDocs `nav` skip comparison. Present `pages` must be an array;
+explicit entries still compare membership/order. Implicit Fumadocs order is not
+compared. Nav-sync ownership retains its existing strict read-only freshness check. Generated inventories are separate: regenerate configured output
+and check its Git diff after the build. A build that rewrites the inventory does
+not prove the committed copy was fresh.
+
+The framework starters provide `docs:check`; MkDocs `test` runs the checker too.
+Both build scripts run it before navigation/build. In OAT's workspace, from the
+repository root use `pnpm --filter oat-docs docs:check`. The existing
+`pnpm docs:validate` also keeps OAT-specific hosted README, skill catalog and
+live-consumer checks. Review warnings; avoid blanket suppressions.
+
+## Stable rules and default counting
+
+Threshold names below are keys of `documentation.check.thresholds`. Comparisons
+are strictly **above** the stated limits except depth, which triggers **at** its
+threshold. Counts use authored reader `.md`/`.mdx` files and real Markdown nodes;
+fenced examples do not become headings, links, groups or diagrams. YAML
+frontmatter, GFM/reference links, explicit heading IDs, static HTML and supported
+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.                                                |
+| `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.                                                                                                                        |
+| `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.             |
+| `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.                                          |
+| `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 using declared ownership semantics; hand-authored/undeclared absent optional meta/pages/nav skips comparison. Nav-sync freshness stays strict; Markdown skips it.                                            |
+| `commands`              | Error for missing literal contributor scripts; 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.                                                                                                                                                           |
+| `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.                                                                           |
+| `image-alt`             | Warn for empty, filename/slug-like or longer than `altMax: 155` image alt text.                                                                                                                                                                  |
+| `provenance`            | Warn for planning/backlog/home paths, configured ticket/milestone patterns and ordinary links escaping the root. Legitimate reader docs remain visible.                                                                                          |
+
+These are lint limits, distinct from authoring targets for concise pages and
+focused maps. `documentation.nonReaderPaths` uses the existing
+[bounded matcher](commands.md#exclusion-patterns) for reader inventory and checks.
+`documentation.excludes` remains manifest-only and cannot hide reader defects.
+
+## Contributor command context
+
+Literal pnpm script and npm run examples in `contributing.md`/`.mdx` and
+`contributing/**` are checked against package manifests. Each code block starts
+at the repository root. Use executable `cd`, `-w`/`--workspace-root`, `--dir` or
+literal `--filter` selection to establish another context. Prose such as “from
+the app directory” alone does not change it. Built-in package-manager commands
+and illustrative placeholders are recognized; commands are never run.
+
+Implicit pnpm shorthand (for example, `pnpm tsc`) may use an installed entry in
+that package's or the workspace root's `node_modules/.bin`. Only its presence is
+checked. Explicit `pnpm run tsc` and `npm run tsc` still require a package script.
+System PATH lookup is outside this check; before dependencies are installed, a
+binary shorthand may be reported missing. Use `pnpm exec` for explicit binary examples.
+
+## 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
+for important diagrams. Put meaningful `accTitle` and `accDescr` in Mermaid,
+keep SVG title/desc and page explanations, and change both theme SVGs with source.
+
+Freshness uses the merge base against `documentation.check.diagramBaseRef`
+(default `origin/main` when available), plus committed, staged, unstaged and
+untracked changes. It never mutates Git. PR checkout/fetch must provide the base;
+without one, static validation still runs and freshness is reported unverified.
+Bootstrap supplies concrete checker → framework build → configured-manifest
+freshness CI guidance. Markdown runs only the checker unless an external generated
+manifest was explicitly configured.
+
+## Configure narrow policy
+
+`documentation.check` is a shared repository object preserved by real config
+commands. Rule values are `error`, `warn` or `off`; `--rule` selects checks without
+changing policy. `frontmatter` and `mermaid` govern syntax independently from
+`description` and `diagram-accessibility`; metadata/accessibility exceptions do
+not suppress syntax or body findings. Explicit `warn`/`off` settings or exceptions
+for the syntax rule itself remain supported. Exceptions use the same bounded path matcher, a stable rule ID
+and a mandatory nonempty reason; omitted exception severity means `off`.
+
+```bash
+oat config set documentation.check '{"rules":{"image-alt":"warn"},"thresholds":{"referenceLines":1200},"exceptions":[{"path":"reference/decisions.md","rule":"provenance","reason":"Reader-facing decision pointers preserve canonical rationale."}],"provenance":{"ticketPatterns":["TICKET-[0-9]+"],"milestonePatterns":["Milestone [0-9]+"]},"diagramBaseRef":"origin/main"}'
+oat config get documentation.check --json
+oat config dump --json
+oat config unset documentation.check --shared
+```
+
+Numeric thresholds are nonnegative safe integers with ordered warn/error and
+min/max pairs. Patterns must compile as regular expressions. Unknown names,
+invalid values, blank reasons and escaping exception paths are rejected rather
+than silently dropped. Keep decision-pointer exceptions narrow and justified;
+metadata/maps/links should normally be repaired in source.

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

@@ -13,18 +13,23 @@ or **MkDocs Material**.
 
 - What it does: documents the docs-specific CLI surface for scaffolding apps, migrating markdown, generating Fumadocs app-root index manifests, and syncing MkDocs or Fumadocs navigation.
 - When to use it: when you already know you are working on a docs surface and need the exact command-level behavior.
-- Primary commands: `oat docs init`, `oat docs migrate`, `oat docs generate-index`, `oat docs nav sync`
+- Primary commands: `oat docs init`, `oat docs migrate`, `oat docs generate-index`, `oat docs nav sync`, `oat docs check`
 
 ## Command surface
 
-| Command                   | Purpose                                                                   |
-| ------------------------- | ------------------------------------------------------------------------- |
-| `oat docs init`           | Set up Markdown files or a docs app; additively adopt Markdown.           |
-| `oat docs migrate`        | Convert MkDocs admonitions to GFM callouts and inject frontmatter.        |
-| `oat docs generate-index` | Generate a manifest from Markdown files, outside authored content.        |
-| `oat docs nav sync`       | Regenerate `mkdocs.yml` nav or Fumadocs `meta.json` from `index.md` maps. |
-| `oat docs analyze`        | CLI entrypoint that points users to the `oat-docs-analyze` skill.         |
-| `oat docs apply`          | CLI entrypoint that points users to the `oat-docs-apply` skill.           |
+| Command                   | Purpose                                                                               |
+| ------------------------- | ------------------------------------------------------------------------------------- |
+| `oat docs init`           | Set up Markdown files or a docs app; additively adopt Markdown.                       |
+| `oat docs migrate`        | Convert MkDocs admonitions to GFM callouts and inject frontmatter.                    |
+| `oat docs generate-index` | Generate a manifest from Markdown files, outside authored content.                    |
+| `oat docs nav sync`       | Regenerate `mkdocs.yml` nav or Fumadocs `meta.json` from `index.md` maps.             |
+| `oat docs check`          | Read-only reader, navigation, command and diagram checks; errors fail, warnings pass. |
+| `oat docs analyze`        | CLI entrypoint that points users to the `oat-docs-analyze` skill.                     |
+| `oat docs apply`          | CLI entrypoint that points users to the `oat-docs-apply` skill.                       |
+
+## `oat docs check`
+
+Run `oat docs check [--target-dir <dir>] [--rule <id>...] [--json]` before committing. It resolves the configured root, validates real reader files without a site build, and emits deterministic findings. Errors exit 1; warning-only exits 0. See [Check Documentation](check.md) for stable rule IDs, counting, narrow policy/exception settings and the exact JSON contract.
 
 ## Which Generation Command To Run
 

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

@@ -13,6 +13,7 @@ Use this section when you are adopting the docs app workflow in a repo, maintain
 
 - [Add or Adopt Docs in a Repo](add-docs-to-a-repo.md) - Set up Markdown or a docs app and safely adopt existing Markdown.
 - [Documentation Commands](commands.md) - Docs CLI surface for init, migration, index generation, and nav sync.
+- [Check Documentation](check.md) - Portable reader, navigation, command and diagram validation.
 - [Docs Workflows](workflows.md) - How the docs CLI helpers pair with analyze/apply workflows.
 - [Improve Agent Instructions](agent-instructions.md) - Analyze instruction gaps and apply approved evidence-backed changes.
 

package/assets/docs/docs-tooling/meta.json

@@ -1,4 +1,10 @@
 {
   "title": "Docs Tooling",
-  "pages": ["add-docs-to-a-repo", "commands", "workflows", "agent-instructions"]
+  "pages": [
+    "add-docs-to-a-repo",
+    "commands",
+    "check",
+    "workflows",
+    "agent-instructions"
+  ]
 }

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

@@ -523,3 +523,7 @@ routes and package scripts remain manual required changes.
 - [Improve Agent Instructions](agent-instructions.md)
 - [`../reference/docs-index-contract.md`](../reference/docs-index-contract.md)
 - [`../contributing/skills.md`](../contributing/skills.md)
+
+## Portable checks and PR CI
+
+Run `oat docs check` before proposing repairs. Its findings feed analysis and approved apply work; it does not rewrite sources or grant navigation ownership. Bootstrap uses its concrete PR CI recipe to propose checker, real framework build and configured generated-manifest freshness steps while preserving existing workflows. Approve the exact workflow diff before writes. Markdown has no build or default manifest step. Full Git history/fetch enables the diagram base comparison. See [Check Documentation](check.md).

package/assets/docs/reference/cli-reference.md

@@ -78,6 +78,8 @@ Git retries include prior outputs only with HEAD ownership evidence, while
 no-Git retries report current-pass mutations. See [Backlog
 Lifecycle](../workflows/backlog-and-planning/backlog-lifecycle.md).
 
+`oat docs check [--target-dir <dir>] [--rule <id>...] [--json]` validates reader structure, links, navigation, contributor commands and diagrams without a site build. Errors exit 1; warning-only exits 0. See [Check Documentation](../docs-tooling/check.md) for rules/config and JSON.
+
 ## Command Groups
 
 | Command group                                   | What it covers                                                                                                                                                                                                             | Go deeper                                                                                   |

package/assets/docs/reference/configuration.md

@@ -99,6 +99,7 @@ Common keys in `.oat/config.json`:
 - `documentation.guidance` — advisory Markdown IA source paths/URLs, as a string or ordered non-empty string array. Repo config overrides user config; explicit skill input overrides both. Absent values use the installed `authoring-docs` IA reference. Use `oat config set documentation.guidance ./docs/ia/index.md` or `oat config set documentation.guidance '["~/guidance/index.md","https://example.com/docs/index.md"]' --user`. Arrays retain order; commas in paths are literal. `--local` is unsupported. `get --json` reports `shared`, `user`, or `default` provenance; `unset` reveals the next tier. Only locators are stored, with unrelated config fields preserved. Sources stay read-only, external packs have `index.md` and `## Contents`, and local AGENTS/contributing rules remain authoritative. Conflicts become `ask_user`. See [IA selection](../docs-tooling/workflows.md#ia-selection-and-guidance).
 - `documentation.nonReaderPaths` — shared repository-only array of content-root-relative globs for drafts/templates. Set with `oat config set documentation.nonReaderPaths 'templates/,drafts/**'`; empty value clears and `unset` removes it. Entries are trimmed/de-duplicated; non-arrays, empty or non-string entries are rejected. Local/user writes are refused. The [bounded grammar](../docs-tooling/commands.md#exclusion-patterns) matches nav inventory, explicit Contents targets, nav checks and manifests only for the configured app/content root; excluded metadata is not rewritten. Fumadocs source collections also exclude rendering when wired through OAT source config. Pinned MkDocs 1.4.2 still renders excluded pages as routes; only nav/manifest exclusion is supported.
 - `documentation.excludes` — a JSON array of globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. `oat config set` takes the list as one comma-separated value (`"a/**,b.md"`) and stores it as an array; repeated `--exclude` flags extend it, and an empty value clears the key
+- `documentation.check` — shared checker policy: stable rule severities, named numeric thresholds, reason-bearing bounded path/rule exceptions, ticket/milestone regex patterns and optional diagram base ref. Set/get/dump/unset preserve and validate the object. See [Check Documentation](../docs-tooling/check.md#configure-narrow-policy) for exact fields/defaults and repair commands.
 - `documentation.requireForProjectCompletion` — whether docs sync is a completion gate
 - `instructions.claude.shims` — how `oat instructions sync` keeps a `CLAUDE.md` beside each `AGENTS.md`: `none` (the default: no shims; sync removes the ones OAT created and warns about any other `CLAUDE.md`, all or nothing: it removes none while any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` has content of its own; see [All or nothing](../provider-sync/instruction-sync.md#all-or-nothing)), `pointer`, `symlink`, or `copy`. The `--strategy` flag overrides it for one run. Set it with `oat config set instructions.claude.shims pointer` when contributors need `CLAUDE.md` (see [Claude Code and AGENTS.md](../provider-sync/instruction-sync.md#claude-code-and-agentsmd)); `oat config unset` returns to `none`. Any other value is rejected with exit code `2` rather than read as unset, and `oat config set` can still replace it
 - `instructions.claude.excludes` — a JSON array of repository-relative directories that `oat instructions sync` and `oat instructions validate` must not treat as pointer sites, additive to the documentation content root they already skip by default (see [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees)). `oat config set` takes the list as one comma-separated value (`"vendor/generated,apps/oat-docs/docs"`) and stores it as an array of repository-relative POSIX paths, trimmed and de-duplicated; an empty value clears the key, and `oat config unset instructions.claude.excludes` removes it. An entry that could never exclude anything — an absolute path, or one escaping the repository with `..` — is rejected with exit code `1` rather than stored. A structurally malformed value already on disk (a non-array, or an empty or non-string entry) is rejected with exit code `2` and a repair message, and `oat config set` can still replace it. Entries that are well formed but cannot exclude anything — among them absolute paths, paths escaping the repository, paths that match no directory (matching is case-sensitive, and the warning names the on-disk spelling when the path differs only in case), paths that resolve elsewhere through a symlink (the warning names the resolved target instead of blaming case-sensitivity), and the unexcludable `.oat/repo` carve-in root — never abort the command; they are reported as warnings and are not counted as protection. Warnings go to stderr in human mode and to the `exclusionWarnings` field under `--json`

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.27",
-  "docs-config": "0.3.27",
-  "docs-theme": "0.3.27",
-  "docs-transforms": "0.3.27"
+  "cli": "0.3.28",
+  "docs-config": "0.3.28",
+  "docs-theme": "0.3.28",
+  "docs-transforms": "0.3.28"
 }

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

@@ -4,9 +4,9 @@ description: Run when you need to evaluate documentation structure, navigation,
 argument-hint: '[target] [--ia] [--ia-guidance <path|url>]'
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(node:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
+allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(oat docs check:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(node:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: '1.7.2'
+  version: '1.7.3'
 ---
 
 # Docs Analysis
@@ -457,6 +457,17 @@ where the docs should live, and what specific subtopics the codebase shows shoul
 
 ### Step 6: Check Navigation and Drift
 
+Probe the installed `oat docs check --help`, then run its read-only
+`oat docs check --target-dir <resolved-root> --json` (or the repo’s documented
+source/local CLI equivalent). Retain exact findings and exit; errors fail while
+warning-only passes. Use stable rule IDs/locations as evidence for recommendations,
+including reader limits, contributor commands, Mermaid/SVG and provenance. It
+executes no page code or documented commands and needs no build. Missing capability
+or unusable Git diagram base is explicitly unverified. Preserve specialized local
+validators; portable success does not establish coverage or claim accuracy. Review
+narrow reason-bearing exceptions from actual config, never invent blanket
+suppressions or automatic navigation ownership.
+
 If a generated root index or manifest exists:
 
 1. Compare generated entries with the authored `## Contents` graph.

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.0'
+  version: '1.2.1'
 ---
 
 # OAT Docs Authoring

package/assets/skills/oat-docs-authoring/references/validation.md

@@ -45,6 +45,10 @@ When navigation, file placement, or `## Contents` changes:
 If generated output is ignored, absent by policy, or cannot be produced in the
 current environment, record the exact reason in the handoff.
 
+## Portable checker
+
+Run the installed `oat docs check --target-dir <resolved-root> --json` when available, or the repository’s documented source/local CLI equivalent. It is read-only and needs no site build. Keep findings and exit: errors fail, warning-only passes. Review warnings, repair authored metadata/maps/links and explicitly sync owned navigation; never add blanket exclusions to pass. Missing CLI capability is unverified, not a successful check. Preserve existing app-specific validators. See the installed checker command docs for stable rule IDs and narrow reason-bearing `documentation.check` exceptions.
+
 ## Local Contract Checks
 
 Before finishing:

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: '1.4.3'
+  version: '1.4.4'
 ---
 
 # Docs Bootstrap
@@ -40,6 +40,8 @@ Bootstrap or adopt documentation in this repo and guide the user through underst
 - Inspecting native scaffold capabilities and reporting missing current-template guidance without rewriting it
 - Running install + build and classifying failures against known patterns
 - Reading `.oat/config.json` back to verify paths and prompting for `requireForProjectCompletion`
+- Presenting concrete PR CI edits from `references/pr-ci.md`, writing only the approved diff while preserving existing workflows
+- Presenting the exact effective-install-root compatibility policy below and writing only that approved root-policy edit while preserving existing settings/conflicts
 - Narrating the scaffolded output as a chunked educational walkthrough
 - Delegating optional initial content population to `oat-docs-analyze` + `oat-docs-apply`
 
@@ -119,7 +121,7 @@ The detailed framework procedures below apply to Fumadocs/MkDocs. When the selec
    Before Markdown CLI invocation, run **Step 2.5** for fresh setup and explicitly selected adoption; it is not bypassed by this condensed path.
 
 3. **Invoke CLI:** Probe `$CLI_CMD docs init --help` and require advertised Markdown/`--adopt` support before invocation; if missing, report the needed CLI update rather than fabricating scaffold files. Run `$CLI_CMD docs init --framework markdown --target-dir <root> --site-name <title> --description <description> --lint none --format none --yes`, adding `--adopt` only for explicit adoption. Pass the selected lint/format values when using existing tools. Never pass app-only flags. An optional `--dry-run` previews file/config/guidance changes without writes; it does not count as a completed bootstrap. Capture terminal/JSON results, exact exit, created/preserved files, config changes, guidance action, and audit advice. `partial`/exit 1 with manual-required or blocked guidance means unresolved guidance; real runs may have created files, whereas dry-runs have only planned files. Report actual state and stop before claiming completion. Other refusals also stop without template repairs. For success, read config back to resolve the actual content root and authored index.
-4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions. Fresh setup creates only authored `index.md` and `contributing.md` in the target; verify no docs-root AGENTS, app package, framework config, dependencies, or root build changes. Run already documented lint/link/format checks when applicable; otherwise inspect files/links directly. Adoption preserves existing bytes and may leave missing child indexes, metadata, context, or links: record these as audit gaps for analyze/apply rather than repairing them or calling the tree fully conformant. Distinguish successful setup verification from content-conformance findings.
+4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions. Fresh setup creates only authored `index.md` and `contributing.md` in the target; verify no docs-root AGENTS, app package, framework config, dependencies, or root build changes. Run `$CLI_CMD docs check --target-dir <literal-root>` and already documented lint/link/format checks when applicable. Errors block conformance; warnings remain review items. Use `references/pr-ci.md` to present checker-only PR wiring with empty build/manifest inputs unless a generated external manifest was separately configured; apply only the approved workflow diff. Adoption preserves existing bytes and may leave missing child indexes, metadata, context, or links: record these as audit gaps for analyze/apply rather than repairing them or calling the tree fully conformant. Distinguish successful setup verification from content-conformance findings.
 5. **Inspect config:** `documentation.tooling` is the string `markdown`; `root` is the literal content directory; `index` is its authored entrypoint, normally `<root>/index.md`. Markdown introduces no `documentation.config`. Preserve unrelated config/excludes/completion settings. Verify deterministic managed root Documentation guidance names that root, Markdown tooling, authored index, and `<root>/contributing.md`; preserve manual/local guidance and surface unresolved disposition. The Step 5e completion opt-in remains available using the docs root rather than an app name, without silently changing an existing value. No nested app-config reconciliation or framework patch inspection applies.
 6. **Walkthrough:** In short chunks, show actual config and `<root>/index.md`: useful context plus the Contents map, title/description metadata, sibling `page.md` and child `section/index.md` links, exclusions and asset-only exceptions. Explain adding a page/section and updating the nearest authored map without overwriting existing context. Root AGENTS Documentation guidance and `<root>/contributing.md` establish agent/human conventions; a preexisting local AGENTS file remains authoritative, but bootstrap creates none. Authored indexes are edited directly. Optional generated inventories require explicit external output, e.g. `$CLI_CMD docs generate-index --docs-dir <root> --output .oat/docs-manifest.md`; output must stay outside the full configured content root and cannot overwrite the configured authored index even with a narrowed `--docs-dir`. Generation does not repoint `documentation.index`. Markdown bootstrap never generates a manifest automatically. Skip framework deep dives and preview-server/build commands.
 7. **Audit handoff and summary:** Offer `oat-docs-analyze` against the literal configured root, followed by `oat-docs-apply` only for approved repairs. An adopted incomplete tree needs that audit; config/guidance alone prove no full conformance. Explain `oat-project-document` for source-backed project deltas. Summarize tooling, actual root/authored index, created/preserved files, guidance/config disposition, ordered IA guidance locators/provenance and proposal recommendation/conflicts, file-check outcomes, unresolved audit gaps, optional manifest ownership, and exact skill handoff. For dry-run/partial/refusal, label the outcome accordingly rather than printing BOOTSTRAP COMPLETE. No app, install, build, patch, or dev-command fields apply.
@@ -416,7 +418,7 @@ Print `[3/7] Scaffolding…` at the start of this step.
 
 For an explicitly fresh Fumadocs/MkDocs app, current CLI init writes `documentation.navOwner: nav-sync` and generates navigation after successful scaffold/config. An explicitly selected new app in a repository with prior docs config is fresh creation; preserve the old app's authored files. This does not authorize regeneration of an existing app: keep undeclared/hand-authored ownership untouched and use the existing analyze/apply handoff. IA approval alone never authorizes navigation writes. Markdown and dry runs run no nav sync.
 
-Inspect the generated package scripts rather than adding a duplicate patch: Fumadocs `prebuild` and MkDocs `docs:build` run `nav sync --check`, using external `oat` from the app directory with `--target-dir .`, or source-workspace CLI with the explicit quoted repo-relative app. A stale navigation check requires fixing authored Contents and explicitly syncing owned navigation before retrying, not deleting the check or silently regenerating an undeclared owner.
+Inspect the generated package scripts rather than adding a duplicate patch: `docs:check` runs the portable checker and MkDocs `test` runs the same real check. Framework builds run the checker before navigation/build. Fumadocs `prebuild` and MkDocs `docs:build` run `nav sync --check`, using external `oat` from the app directory with `--target-dir .`, or source-workspace CLI with the explicit quoted repo-relative app. A stale navigation check requires fixing authored Contents and explicitly syncing owned navigation before retrying, not deleting the check or silently regenerating an undeclared owner.
 
 **3a. Assemble CLI flags.**
 
@@ -516,6 +518,40 @@ Print `[4/7] Verifying build…` at the start of this step.
 
 Skip this step entirely if `Scaffold Result.scaffoldSucceeded !== true` — a failed scaffold produces an undefined state; installing and building on top of it makes things worse.
 
+**4a prerequisite: inspect and approve Fumadocs install-root policy.**
+
+Before running install, read the CLI's `installationAdvice` and the generated
+toolchain guide. Locate the actual pnpm installation root, including any enclosing
+`pnpm-workspace.yaml`; a workspace member's package is not that root. Current
+Fumadocs loses handler properties added by `mdast-util-to-markdown` 2.2.0, so valid
+bold/italic content can fail compilation. Preserve all content and framework APIs.
+The required compatibility constraint is exactly 2.1.2 in the effective root's
+`pnpm-workspace.yaml`:
+
+```yaml
+overrides:
+  mdast-util-to-markdown: 2.1.2
+```
+
+A newly scaffolded independent app has its own root YAML (`packages: []` plus
+this override); inspect it and install there. The CLI never creates this boundary
+in monorepo mode or under an enclosing pnpm workspace. For an existing workspace
+root, PRESENT the exact concrete YAML diff and obtain explicit approval before
+writing it. Preserve package globs and all unrelated settings; add the entry to
+an existing `overrides` map, never duplicate the map or replace the file. A
+conflicting existing pin requires the owner's decision; a declined/skipped edit
+stays a manual setup requirement and verification remains pending. Do not create
+a local boundary that splits a workspace member. Do not implement a policy merger
+or silently extend CLI root-package patching: it changes build scripts only,
+and `--no-root-patch` neither sets nor approves dependency policy.
+
+Honor the selected manager (pnpm 10+); effective-root YAML works in pnpm 10 and 12.
+A member-only override is ignored in 10, and 12 also ignores `package.json`'s
+`pnpm.overrides`. After install, inspect actual `pnpm why mdast-util-to-markdown`
+from that root, confirm 2.1.2, retain the root config/lockfile, then run checker and
+build. Label this a constrained fresh install; do not promise unconstrained
+resolution, change user-scope pnpm, or delete bold/italic to avoid the failure.
+
 **4a. Install dependencies.**
 
 Command varies by repo shape (from Preflight Result) and framework (Fumadocs only uses pnpm; MkDocs uses Python tooling — handled in the MkDocs Minimum Contract, Step 6):
@@ -526,6 +562,8 @@ Command varies by repo shape (from Preflight Result) and framework (Fumadocs onl
 
 For Fumadocs, capture both stdout and stderr. Print a start line (`Installing dependencies…`) and a completion line with duration.
 
+Before building, run `$CLI_CMD docs check --target-dir <configured-root>` from the repo root. Keep its JSON/findings and exit; metadata/maps/links, contributor commands and real Mermaid syntax are checked without executing page code. Errors stop verification; review warnings and route content repairs through analyze/apply. Never add blanket suppressions to pass bootstrap.
+
 **4b. Build.**
 
 Command varies by shape:
@@ -572,6 +610,7 @@ Record internally for the Post-Scaffold Inspector and Walkthrough:
 
 ```
 Verification Result:
+  installRootPolicy: { path, disposition: 'scaffolded' | 'approved' | 'manual' | 'conflict', resolvedVersion } | null
   installSucceeded: boolean
   buildSucceeded: boolean
   knownIssues: Array<{ pattern, severity: 'benign' | 'flagged' | 'surface-only' | 'auto-fixed', detail }>
@@ -670,6 +709,16 @@ Inspection Result:
 
 The Walkthrough's Section D (Configuration readback) references `issues[]` verbatim — format it so it reads cleanly when printed to the user.
 
+**PR CI wiring (after config inspection):** Load `references/pr-ci.md` now.
+Resolve its concrete inputs from the inspected config/scripts, present the exact
+workflow diff, and write only after approval. Preserve existing workflow content
+and use full-history checkout/fetch for the applicable diagram base. Execute its
+checker, real framework build and configured-manifest freshness commands locally;
+record exits and unverified portions. Markdown follows the same recipe with no
+build/default manifest. Include the approved workflow path or declined/pending
+status in the exit summary. This is bootstrap setup authority, not permission to
+rewrite an existing app or introduce deployment.
+
 ### Step 6: Educational Walkthrough
 
 Narrate the scaffolded docs app as a chunked conversation, not a wall of text. The Walkthrough's job is to turn the user from "I ran a scaffold" into "I know how this docs app works". It is **not** a re-explanation of the CLI's output, nor a recitation of the AGENTS.md content — both are live files the user can read; the Walkthrough contextualizes them.
@@ -883,6 +932,8 @@ Agent guidance:
 Build:
   - Install: {ok | known-issue: ...}
   - Build:   {ok | known-issue: ...}
+  - Install policy: {effective-root YAML + resolved 2.1.2 | manual/conflict/pending; constrained install}
+  - PR CI: {approved workflow path + checker/build/freshness exits | declined | pending}
   - Known issues (from Verification Result.knownIssues): {list or 'none'}
 
 Inspection:

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.