@open-agent-toolkit/cli 0.3.26 → 0.3.28

package/README.md

@@ -41,6 +41,18 @@ Additional useful entry points:
 - `oat repo archive sync`
 - `oat doctor`
 
+## Docs scaffolding
+
+`oat docs init --framework fumadocs --app-name my-docs` creates a docs app with app-root `AGENTS.md`, a reader-first Getting Started stub and contributor/toolchain guides. The CLI owns these templates for both Fumadocs and legacy MkDocs; the bootstrap skill guides inspection and setup. Existing files and plain Markdown adoption are preserved.
+
+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.26"
+  "oatVersion": "0.3.28"
 }

package/assets/docs/contributing/documentation.md

@@ -15,9 +15,43 @@ Documentation should ship with the code it explains. This page covers the core d
 - Use `.md`-suffixed relative links in `## Contents`: `[Page](page.md)` for leaf pages and `[Section](subdir/index.md)` for child directories.
 - Fumadocs and MkDocs share this authored contract, but they regenerate different artifacts.
 
+Within Contents, use dash-only link bullets with optional descriptions. A `### Label` introduces a group containing at least one authored entry; entries before the first group stay ungrouped. `*`/`+` link bullets and empty groups produce file/line errors. The map ends at the next level-two heading, and fenced examples are ignored. A self-index link retains landing-page behavior. Missing Contents retains deterministic manifest fallback, while strict nav still requires maps and reports unlisted reader pages.
+
+```markdown
+## Contents
+
+- [Reader guide](guide.md) - Reach a useful result.
+
+### More detail
+
+- [Reference](reference/index.md) - Local reference map.
+```
+
+| Surface                                            | Authored or generated                                       |
+| -------------------------------------------------- | ----------------------------------------------------------- |
+| `docs/**/*.md`, including directory indexes        | Authored reader content and local maps                      |
+| App `AGENTS.md`, config, source loader and scripts | Authored working rules and tooling                          |
+| `docs/**/meta.json`                                | Committed derived sidebar; regenerate with nav sync         |
+| App-root `index.md`                                | Generated Markdown inventory; predev/prebuild regenerate it |
+| `.source/`, `.next/`, `out/`                       | Generated collection/build/export; never edit               |
+
+`documentation.navOwner: nav-sync` authorizes navigation generation. Agree ownership before changing hand-authored or undeclared navigation. `documentation.nonReaderPaths` excludes non-reader content from nav, manifests and the Fumadocs collection; explicit Contents links do not override it. `documentation.excludes` affects only the manifest. Do not use exclusions to conceal an unlisted reader page.
+
+To add a page, choose its scope from the nearest map, add title/description frontmatter and one H1, then update Contents. To move or rename, update both maps and inbound links in the same commit, and agree how old published URLs will resolve (redirect or static recovery page). Add a child `index.md` when adding a directory. Use `.md`-suffixed source links; the link transform produces rendered routes.
+
+## Supported features and diagrams
+
+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, 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; 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
 
-1. Start the dev server from the repo root:
+All commands below run from the **repository root**. Contributor setup is in [Code Contributions](code.md).
+
+1. Start the dev server:
 
    ```bash
    pnpm dev:docs
@@ -47,8 +81,18 @@ Documentation should ship with the code it explains. This page covers the core d
 
    ```bash
    pnpm --filter oat-docs docs:format
+   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.
@@ -70,16 +114,14 @@ Documentation should ship with the code it explains. This page covers the core d
 
   ```bash
   pnpm -w run cli:source -- docs nav sync --target-dir apps/oat-docs
+  pnpm -w run cli:source -- docs nav sync --target-dir apps/oat-docs --check
+  pnpm docs:validate
   ```
 
 - In MkDocs apps, the same `oat docs nav sync` command refreshes the `nav:` block in `mkdocs.yml` instead.
 - Use [Markdown Features](markdown-features.md) for supported syntax and examples.
 
-## Agent guidance
-
-- Treat `index.md` plus its `## Contents` section as the local discovery source of truth.
-- Prefer linking to source files and commands explicitly when documenting behavior.
-- Regenerate or freshness-check the docs surface index after adding, removing, renaming, or reordering pages.
+Agent working rules: `../../AGENTS.md` (app-root source file).
 
 ## Related Guides
 

package/assets/docs/contributing/markdown-features.md

@@ -79,7 +79,7 @@ theme.
 
 A diagram that needs to read well, especially on a phone, gets a hand-drawn SVG
 pair next to its Mermaid source. Mermaid stays the source of truth: when you
-change the Mermaid, update both SVGs in the same change.
+change the Mermaid, update both SVGs in the same commit, preserving nodes, edges and labels. Give each SVG `role="img"` and descriptive `<title>`/`<desc>` elements connected by `aria-labelledby`; keep labels readable and Markdown alt text concise (about 155 characters or less).
 
 === "Syntax"
 
@@ -150,8 +150,20 @@ Use a language identifier on every opening fence. In this docs app, use `bash` f
 
 ## Authoring Reminder
 
-After adding or reorganizing docs pages, refresh the generated docs surface:
+After adding, moving or renaming pages, update both authored maps and inbound links. From the **repository root**, refresh and validate the generated surfaces:
 
 ```bash
 pnpm -w run cli:source -- docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
 ```
+
+```bash
+pnpm -w run cli:source -- docs nav sync --target-dir apps/oat-docs
+pnpm -w run cli:source -- docs nav sync --target-dir apps/oat-docs --check
+pnpm --filter oat-docs docs:format
+pnpm --filter oat-docs docs:format:check
+pnpm --filter oat-docs docs:lint
+pnpm docs:validate
+pnpm build:docs
+```
+
+These checks cover navigation, source contracts, formatting and build output. Inspect rendered tabs and diagrams too; they do not validate Mermaid syntax or accessibility automatically. Agent rules live in `../../AGENTS.md` (app-root source file).

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

@@ -63,20 +63,21 @@ Choose Markdown files or a framework app, using the guided skill or direct CLI.
 
 The docs-bootstrap skill offers Markdown, Fumadocs, and MkDocs. Configured tooling is authoritative; framework evidence is checked before plain-directory evidence. A root README alone does not trigger adoption, and an empty selected target stays fresh setup. Markdown uses file checks and an adopt/audit handoff, with no app questions, dependencies, framework patches, docs-root AGENTS, or site build.
 
-For framework apps, it wraps `oat docs init` with a seven-step guided flow: preflight detection (repo shape + existing-setup conflict surfacing), richer input gathering (including a site name distinct from the package name), the CLI invocation itself, labeled post-patches for open CLI gaps, install + build verification, post-scaffold config inspection, and a chunked educational walkthrough.
+For framework apps, it wraps `oat docs init` with a seven-step guided flow: preflight detection (repo shape + existing-setup conflict surfacing), richer input gathering (including a site name distinct from the package name), the CLI invocation itself, CLI-owned scaffold inspection, install + build verification, post-scaffold config inspection, and a chunked educational walkthrough.
 
 What the framework path adds over the raw CLI:
 
 - **Preflight + conflict resolution.** Detects existing `documentation` config / docs app dir / root `AGENTS.md` section and walks a deliberate resolution choice (replace, abort, repair, or deferred second-app) before any mutation.
 - **Richer inputs.** Asks for a **site name** separate from the package name, so layout branding and page metadata converge on the same display title. `createDocsConfig()` handles runtime configuration, not titles.
-- **AGENTS.md bridge.** FP-15 writes a task-framed `<appRoot>/AGENTS.md` only when the CLI does not scaffold it and no file already exists. Template content, metadata, command context, Node requirements, Contents links and generated-files guidance are CLI-owned. For nested-standalone repos only, the Fumadocs template passes an ESM-safe Turbopack root through `createDocsConfig` while preserving static export settings. Monorepo and single-package scaffolds use Next.js root discovery. Older scaffold shapes become analyze findings rather than post-patches.
+- **CLI-owned guidance.** Fresh Fumadocs and MkDocs apps include app-root `AGENTS.md`, a reader-first Getting Started stub, a human contributor entry and `docs/contributing/docs-toolchain.md`. Commands state their working directory. Bootstrap observes this output; older CLIs missing it get analyze/manual CLI-template upgrade advice, rather than a second template owner. Existing and Markdown surfaces are preserved. Nested-standalone Fumadocs still uses the ESM-safe Turbopack root while monorepo and single-package apps use Next root discovery.
+- **Agent Markdown.** Fumadocs exports `/llms.txt`, `/llms-full.txt` and `/llms/<page-slugs>/content.md` (root `/llms/content.md`) from loaded `.md` readers. MDX and configured non-readers are excluded. Source headers identify how to resolve authored relative links; rendered and Markdown URLs include the deployment base path once.
 - **Build verification.** Runs install + build, classifies failures against known patterns, stops on unknown errors rather than guessing.
 - **Config inspection.** Reads `.oat/config.json` back, verifies paths exist on disk, handles the nested-standalone dual-config case, and collects the `requireForProjectCompletion` opt-in explicitly.
 - **Root-build explanation.** When the CLI safely patches a compatible Turbo root `build` script, the walkthrough explains why the filter was added, shows the diff shape, and documents how to adjust or revert it. When the CLI skips the patch, the walkthrough relays the recommended manual snippet.
 - **Educational walkthrough.** Seven sections covering the `documentation` config, the authored-source/generated-navigation model, the `## Contents` contract (with extension discipline), the three agent-instruction surfaces (root `AGENTS.md` pointer / docs-app `AGENTS.md` / `docs/contributing.md`), Fumadocs internals (or MkDocs Minimum Contract), and the OAT docs ecosystem (`oat-project-document`, `oat-docs-analyze`, `oat-docs-apply`).
 - **Optional content kickoff.** Hands off to `oat-docs-analyze` + `oat-docs-apply` if you want to populate initial repo-specific content immediately.
 
-Capability detection gates the remaining AGENTS bridge. Existing files are preserved; use analyze and reviewed recommendations to address older scaffold output.
+Missing app-root `AGENTS.md` from an older CLI is reported as a missing capability with analyze/manual CLI-template upgrade advice. Existing files are preserved; use analyze and reviewed recommendations to address older scaffold output.
 
 ### 3b. Direct CLI (deterministic / non-interactive)
 
@@ -105,7 +106,7 @@ oat docs init --app-name my-docs --framework fumadocs --yes
 oat docs init --app-name my-docs --framework mkdocs --yes
 ```
 
-Use 3b when you want a fully headless scaffold (CI, automation) and can accept the raw CLI output without the guided post-patches.
+Use 3b when you want a fully headless scaffold (CI, automation) and can accept the raw CLI output without the guided walkthrough.
 
 For compatible Turbo monorepos, the CLI also patches the repo-root
 `package.json` by default so root `pnpm build` excludes the new docs app and a
@@ -298,11 +299,11 @@ Important:
 three kinds of documentation. In all three, each folder's `index.md` has a
 `## Contents` list of its pages.
 
-| Framework      | Choose it when                                                       | What you give up                                                                                                       |
-| -------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Plain Markdown | People and agents read the docs in the repository; no site is needed | A rendered site and search. You keep each `## Contents` list up to date by hand                                        |
-| Fumadocs       | A Node/pnpm repository wants a hosted docs site                      | An app with dependencies and a build. A page missing from its folder's `## Contents` list is hidden from the sidebar   |
-| MkDocs         | The team already uses Python and MkDocs Material                     | Python setup (`setup-docs.sh` runs `pip install`). `oat docs nav sync` rewrites the whole `nav:` block of `mkdocs.yml` |
+| Framework       | Choose it when                                                       | What you give up                                                                                                       |
+| --------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Plain Markdown  | People and agents read the docs in the repository; no site is needed | A rendered site and search. You keep each `## Contents` list up to date by hand                                        |
+| Fumadocs        | A Node/pnpm repository wants a hosted docs site                      | An app with dependencies and a build. A page missing from its folder's `## Contents` list is hidden from the sidebar   |
+| MkDocs (legacy) | The team already uses Python and MkDocs Material                     | Python setup (`setup-docs.sh` runs `pip install`). `oat docs nav sync` rewrites the whole `nav:` block of `mkdocs.yml` |
 
 When nothing chooses for it (a non-interactive run or `--yes`), `oat docs init`
 uses Fumadocs. That is only a default; pick the smallest option your readers
@@ -323,3 +324,15 @@ need.
   existing MkDocs site with `oat init --setup` instead of `oat docs init`. When
   moving an MkDocs site to Fumadocs, `oat docs migrate` converts MkDocs syntax
   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
 
@@ -40,7 +45,7 @@ explicit external output and retain the authored config index. Both frameworks k
 
 Use `oat docs init` to bootstrap Markdown documentation or scaffold a framework app.
 
-> **Consider the `oat-docs-bootstrap` skill instead.** The skill wraps `oat docs init` with preflight detection, richer input gathering (site name distinct from package name), capability-gated post-patches that close open CLI gaps (site-title metadata, Turbopack root, template-content fixes, docs-app `AGENTS.md` bridge, `## Contents` link extensions, `contributing.md` three-surfaces cleanup), build verification, config inspection, and a seven-section educational walkthrough. See [Add Docs to a Repo §3a](add-docs-to-a-repo.md#3a-preferred-the-oat-docs-bootstrap-skill-guided) for the full flow. The CLI documented here remains the authoritative surface for flags and is the right choice when you need a deterministic, non-interactive scaffold (CI, automation).
+> **Consider the `oat-docs-bootstrap` skill instead.** The skill wraps `oat docs init` with preflight detection, richer input gathering (site name distinct from package name), capability probing and verification of CLI-owned scaffolds (including framework app-root `AGENTS.md`), build verification, config inspection, and a seven-section educational walkthrough. Missing capabilities or older scaffold gaps lead to CLI update advice or an analyze handoff with manual CLI/template upgrade recommendations. See [Add Docs to a Repo §3a](add-docs-to-a-repo.md#3a-preferred-the-oat-docs-bootstrap-skill-guided) for the full flow. The CLI documented here remains the authoritative surface for flags and is the right choice when you need a deterministic, non-interactive scaffold (CI, automation).
 
 Key behavior:
 

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

@@ -31,7 +31,7 @@ Install the workflow skills with `oat tools install docs` (preferred) or
   local navigation maintenance inside an existing OAT documentation surface
 - `oat-docs-bootstrap` is the guided onramp for Markdown setup/adoption or adding a docs app —
   wraps `oat docs init` with preflight detection, richer input gathering (site
-  name distinct from package name), labeled post-patches for open CLI gaps,
+  name distinct from package name), capability probing and CLI-owned scaffold inspection,
   file-level verification for Markdown or framework build verification, config
   inspection, and an educational walkthrough
 - `oat-docs-analyze` evaluates a docs surface for structure, drift, coverage,
@@ -96,8 +96,8 @@ Diagram: bootstrap once, then analyze, approve and apply only agreed improvement
 - **Setup, once.** `oat-docs-bootstrap` checks the repo without writing, asks
   you to confirm its inputs, then runs `oat docs init`. Plain Markdown setup validates authored files,
   configuration and guidance without installing app dependencies or building a
-  site. Fumadocs and MkDocs setup adds the relevant post-patches, installation,
-  build verification and walkthrough.
+  site. Fumadocs and MkDocs setup inspects CLI-owned scaffold output, installs
+  dependencies, verifies the build and provides a walkthrough.
 - **Analyze.** `oat-docs-analyze` never edits docs. It writes an analysis
   artifact under `.oat/repo/analysis/` (and updates OAT tracking).
 - **Approve.** `oat-docs-apply` builds a plan from the newest artifact and
@@ -109,7 +109,7 @@ Diagram: bootstrap once, then analyze, approve and apply only agreed improvement
   marked as needing confirmation are confirmed again before they are written.
 - **Repeat.** Re-run analyze afterwards to confirm the result.
 
-1. Bootstrap or explicitly adopt a documentation surface with `oat-docs-bootstrap` (preferred — guided, includes post-scaffold patches and walkthrough) or `oat docs init` directly (CLI-only / non-interactive workflows)
+1. Bootstrap or explicitly adopt a documentation surface with `oat-docs-bootstrap` (preferred — guided, includes capability probing, scaffold verification and walkthrough) or `oat docs init` directly (CLI-only / non-interactive workflows)
 2. (Optional) If migrating from MkDocs, handle that as a separate migration workstream; `oat docs migrate --docs-dir docs --config mkdocs.yml --apply` is only the syntax/frontmatter helper
 3. Use `oat-docs-authoring` for targeted OAT Markdown/Fumadocs authoring work, with `authoring-docs` as the universal documentation-quality baseline
 4. Keep authored context and title/description metadata, with an `index.md` and useful `## Contents` in each non-excluded Markdown-bearing directory; preserve asset-only exceptions and local instructions
@@ -296,8 +296,12 @@ configuration, and links.
 **Fumadocs or MkDocs path:** Use this when you want a built documentation
 site. The skill gathers app inputs (the visible site title and the package
 name are different inputs), probes which capabilities the installed CLI
-supports, runs the scaffold, and applies only the relevant post-patches (the
-skill's labeled fixes for known gaps in the CLI's scaffold output).
+supports, runs the CLI scaffold, and inspects the output. Current CLI templates
+own the app-root `AGENTS.md` and framework content. Missing `--site-name` support
+stops bootstrap before scaffolding with CLI update advice. Missing app guidance
+or older scaffold gaps become analyze findings with manual CLI/template upgrade
+recommendations; bootstrap preserves existing files and supplies no replacement
+AGENTS template.
 Verification installs dependencies and runs a build. If a docs app already
 exists, the default repair route runs analyze then apply and exits. An explicit
 `replace` choice deletes the existing app; a second app remains unsupported.
@@ -306,10 +310,10 @@ exists, the default repair route runs analyze then apply and exits. An explicit
 runs `oat docs init`, which writes the `documentation` section of
 `.oat/config.json` and adds or updates a managed `## Documentation` section
 in the root `AGENTS.md`. This happens on both paths. On the Fumadocs or
-MkDocs path it also scaffolds the app, applies post-patches, installs
-dependencies, runs a build, and may patch the root `package.json` so the
-default build leaves the docs app out. It may also write an `AGENTS.md`
-inside the new app when the CLI did not create one. Only after you confirm:
+MkDocs path the CLI also scaffolds the app, including its app-root `AGENTS.md`,
+and may patch the root `package.json` so the default build leaves the docs app
+out. Bootstrap inspects that output, installs dependencies and runs a build.
+Only after you confirm:
 the `replace` choice deletes the existing docs app directory and clears its
 `documentation` config and root `AGENTS.md` section (it refuses only when
 that directory has uncommitted changes); answering yes to the
@@ -519,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/getting-started/tool-packs.md

@@ -976,9 +976,11 @@ The `docs` pack contains active documentation and instruction-governance
 workflows:
 
 - **oat-docs-bootstrap** — Guide users through Markdown setup/adoption or a docs app
-  end-to-end: preflight detection, input gathering, scaffold (via `oat docs
-init`) with capability-gated post-patches, build verification, config
-  inspection, and an educational walkthrough.
+  end-to-end: preflight detection, input gathering, scaffold via `oat docs init`,
+  capability probing, CLI-owned scaffold inspection, build verification,
+  config inspection, and an educational walkthrough. Current CLI templates own
+  framework app-root `AGENTS.md`; missing capabilities or older scaffold gaps
+  lead to CLI update advice or analyze/manual CLI/template upgrade recommendations.
 - **oat-docs-analyze** — Analyze a docs surface for contract coverage, nav
   drift, stale claims, and coverage gaps.
 - **oat-docs-apply** — Apply only approved, evidence-backed docs-analysis

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/docs/skills/index.md

@@ -267,14 +267,14 @@ Visibility reports source metadata: “user” is `user-invocable` and “model
 
 ### Docs workflows
 
-| Skill                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Visibility                        | Needs an active project? |
-| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------ |
-| [`authoring-docs`](../docs-tooling/workflows.md#authoring-docs)         | Use when creating, restructuring, migrating, auditing, or reviewing technical documentation for software projects. Provides evidence-first, provider-portable Markdown authoring standards.                                                                                                                                                                                                                                                                                        | user: true; model disabled: false | No                       |
-| [`oat-docs`](../docs-tooling/workflows.md#oat-docs)                     | Use when a user asks questions about OAT workflows, CLI commands, skill authoring, configuration, or project lifecycle. Answers questions by reading locally-bundled OAT documentation.                                                                                                                                                                                                                                                                                            | user: true; model disabled: false | No                       |
-| [`oat-docs-analyze`](../docs-tooling/workflows.md#oat-docs-analyze)     | Run when you need to evaluate documentation structure, navigation, and coverage against the OAT documentation contract. Produces a severity-rated analysis artifact for oat-docs-apply.                                                                                                                                                                                                                                                                                            | user: true; model disabled: true  | No                       |
-| [`oat-docs-apply`](../docs-tooling/workflows.md#oat-docs-apply)         | Run when you have a docs analysis artifact and want to generate or update documentation structure and content. Creates a branch, applies approved changes, and optionally opens a PR.                                                                                                                                                                                                                                                                                              | user: true; model disabled: true  | No                       |
-| [`oat-docs-authoring`](../docs-tooling/workflows.md#oat-docs-authoring) | Use when authoring or restructuring targeted content inside an existing OAT Markdown surface or OAT/Fumadocs docs app. Preserves OAT docs navigation, generated indexes, and validation boundaries.                                                                                                                                                                                                                                                                                | user: true; model disabled: false | No                       |
-| [`oat-docs-bootstrap`](../docs-tooling/workflows.md#oat-docs-bootstrap) | Use when bootstrapping or adopting an OAT documentation surface in a repo. Guides the user through preflight detection, richer input gathering than the raw CLI, `oat docs init` invocation with gated post-patches for open CLI gaps, build verification, post-scaffold config inspection, and an educational walkthrough. Supports plain Markdown (file-level path), Fumadocs (full path), and MkDocs (lean path with defined minimum contract). | user: true; model disabled: true  | Optional                 |
+| Skill                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                         | Visibility                        | Needs an active project? |
+| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------ |
+| [`authoring-docs`](../docs-tooling/workflows.md#authoring-docs)         | Use when creating, restructuring, migrating, auditing, or reviewing technical documentation for software projects. Provides evidence-first, provider-portable Markdown authoring standards.                                                                                                                                                                                                                                                         | user: true; model disabled: false | No                       |
+| [`oat-docs`](../docs-tooling/workflows.md#oat-docs)                     | Use when a user asks questions about OAT workflows, CLI commands, skill authoring, configuration, or project lifecycle. Answers questions by reading locally-bundled OAT documentation.                                                                                                                                                                                                                                                             | user: true; model disabled: false | No                       |
+| [`oat-docs-analyze`](../docs-tooling/workflows.md#oat-docs-analyze)     | Run when you need to evaluate documentation structure, navigation, and coverage against the OAT documentation contract. Produces a severity-rated analysis artifact for oat-docs-apply.                                                                                                                                                                                                                                                             | user: true; model disabled: true  | No                       |
+| [`oat-docs-apply`](../docs-tooling/workflows.md#oat-docs-apply)         | Run when you have a docs analysis artifact and want to generate or update documentation structure and content. Creates a branch, applies approved changes, and optionally opens a PR.                                                                                                                                                                                                                                                               | user: true; model disabled: true  | No                       |
+| [`oat-docs-authoring`](../docs-tooling/workflows.md#oat-docs-authoring) | Use when authoring or restructuring targeted content inside an existing OAT Markdown surface or OAT/Fumadocs docs app. Preserves OAT docs navigation, generated indexes, and validation boundaries.                                                                                                                                                                                                                                                 | user: true; model disabled: false | No                       |
+| [`oat-docs-bootstrap`](../docs-tooling/workflows.md#oat-docs-bootstrap) | Use when bootstrapping or adopting an OAT documentation surface in a repo. Guides the user through preflight detection, richer input gathering than the raw CLI, CLI-owned `oat docs init` scaffolding, build verification, post-scaffold config inspection, and an educational walkthrough. Supports plain Markdown (file-level path), Fumadocs (full path), and MkDocs (lean path with defined minimum contract). | user: true; model disabled: true  | Optional                 |
 
 ### Explainer Kit