@open-agent-toolkit/cli 0.3.27 → 0.3.29

package/README.md

@@ -45,8 +45,16 @@ Additional useful entry points:
 
 `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.
 
+For an approved fresh reader model, pass `--ia-preset <preset> --planned-pages <count>` together. The six presets materialize reader tracks at 15 or more anticipated pages, or grouped flat headings below 15; `flat-small` always stays flat. Canonical page templates go under excluded `contributing/templates/`, with a track table in framework app-root AGENTS or Markdown contributing guidance. Existing surfaces route to analyze/apply. See [preset selection and template subsets](../../apps/oat-docs/docs/docs-tooling/commands.md#approved-preset-readers). Direct init without both inputs retains its starter; selection does not create an IA decision.
+
 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.29"
 }

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

@@ -63,6 +63,8 @@ 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 fresh empty targets, the skill obtains explicit IA approval with an anticipated reader-page count, probes `--ia-preset` and `--planned-pages`, then passes both to CLI init. The CLI materializes the selected model at 15 or more pages and collapses it into grouped root headings below 15 (always flat for `flat-small`). It also supplies relevant non-reader page templates. Existing surfaces use analyze and individually approved apply; adoption receives no preset flags. See [preset mappings and template subsets](commands.md#approved-preset-readers). Selection guidance does not replace the existing IA decision/adoption flow.
+
 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:
@@ -326,3 +328,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
 
@@ -55,9 +60,53 @@ Key behavior:
 - for framework apps, when the repo root exposes a compatible Turbo `scripts.build`, patches it to exclude the new docs app from the default root build and adds a root-level `build:docs` script
 - prints a unified diff before writing the root `package.json` change and returns a manual snippet when the patch is skipped because the build script is missing, non-Turbo, or ambiguous
 
-Markdown setup:
+### Approved preset readers
+
+Opt into an approved reader model with `--ia-preset <preset> --planned-pages <count>`.
+Both flags are required together; the count is an integer of at least 1 and covers
+anticipated reader pages, excluding contributor/toolchain/template content. No flags
+keeps the existing starter. Preset init requires an empty target and refuses existing
+docs config/ownership; use analyze and individually approved apply for existing trees.
+
+| Preset                   | Reader directories at 15 or more anticipated pages    | Templates                                   |
+| ------------------------ | ----------------------------------------------------- | ------------------------------------------- |
+| `product-engineering-qa` | `product/`, `engineering/`, `qa/`                     | All ten                                     |
+| `consumer-maintainer`    | `consumer/`, `maintainer/`                            | Six support shapes                          |
+| `domain-engineering`     | `engineering/`                                        | Engineering feature plus six support shapes |
+| `task-type`              | `tutorials/`, `how-to/`, `reference/`, `explanation/` | Six support shapes                          |
+| `toolkit-cli`            | `tools/`, `workflows/`                                | Six support shapes                          |
+| `flat-small`             | Always grouped headings in one flat root index        | Six support shapes                          |
+
+Below 15 pages, each model uses grouped root headings and flat reader pages while
+retaining its template subset. Track entries have purpose, entry principle and
+useful sections. Engineering is hybrid: domain/implementation contracts alongside
+paired feature pages; Product/QA enter by feature or journey.
+
+Templates live under `contributing/templates/`: Product feature, Engineering
+feature, QA validation, conditional Screen spec, Alert runbook, incident Solution
+record, Command reference, Skill or command guide, Decisions pointer and Per-area
+AGENTS. The six support shapes are the last six in that list. Screen pages and
+per-track AGENTS are never automatically instantiated. Bodies come from canonical
+`authoring-docs` assets, with verified-literal rules and separate planned automation,
+implemented assertions and dated execution evidence.
+
+The CLI merges `contributing/templates/**` into `documentation.nonReaderPaths`
+before nav generation. These drafts stay out of reader Contents, navigation,
+checker inventory and manifests; `excludes` remains manifest-only. Pinned MkDocs
+1.4.2 can still render excluded routes and retains `use_directory_urls: false`.
+Framework app-root AGENTS gets the track table; Markdown uses `contributing.md`,
+with no docs-root AGENTS, dependencies, sidebar, build or default manifest.
+Selection guidance is not a persisted IA decision: bootstrap still requires explicit
+approval and the existing adoption/`record-ia` flow, without implicit PJM adoption.
+
+```bash
+oat docs init --framework markdown --ia-preset toolkit-cli --planned-pages 14 --yes
+oat docs init --framework fumadocs --ia-preset product-engineering-qa --planned-pages 30 --yes
+```
+
+### Default Markdown setup
 
-- Creates only authored root `index.md` and `contributing.md` baseline pages,
+- Without preset inputs, creates only authored root `index.md` and `contributing.md` baseline pages,
   with metadata, context and real relative `.md` Contents links.
 - Records literal root/tooling/authored index and managed root guidance; no
   docs-root AGENTS, app package, dependencies, package/Turbo patch or site build.
@@ -107,6 +156,7 @@ Supported flags:
 - `--framework <markdown|fumadocs|mkdocs>` (default: `fumadocs` in non-interactive mode)
 - `--site-name <name>` (site display title or Markdown documentation title)
 - `--description <text>` (documentation description, optional)
+- `--ia-preset <preset>` and `--planned-pages <count>` (approved fresh selection; pair required, integer count >= 1)
 - `--lint <none|markdownlint-cli2>`
 - `--format <oxfmt|none>`
 - `--adopt` (Markdown only; add missing baseline files, preserve existing bytes)

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.29",
+  "docs-config": "0.3.29",
+  "docs-theme": "0.3.29",
+  "docs-transforms": "0.3.29"
 }

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

@@ -6,7 +6,7 @@ disable-model-invocation: false
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: 1.1.0
+  version: 1.2.0
 ---
 
 # Authoring Docs
@@ -116,7 +116,7 @@ Load only the references needed for the current task:
 - `references/categories.md`: API, CLI, app, service, library, framework,
   monorepo, architecture, operations, and audience-specific guidance.
 - `references/writing-style.md`: plain technical writing and Markdown rules.
-- `references/templates.md`: reusable page and handoff templates.
+- `references/templates.md`: reusable page and handoff templates, linking canonical copyable Markdown under `references/page-templates/`. Fresh approved preset init consumes those same bodies; local templates remain preferred.
 - `references/review-rubric.md`: readiness checklist and review rubric.
 
 ## Examples

package/assets/skills/authoring-docs/references/information-architecture.md

@@ -123,8 +123,11 @@ use filename/slug parity for paired features and reciprocal links. A Product
 feature must link to its QA validation and Engineering counterpart (and back).
 Quote exact UI literals only when verified against source; distinguish a user
 concept from literal screen text. Do not fabricate test IDs or independent
-verification needs. Feature and QA validation page templates are not included here;
-use the page-type guidance and IA Proposal template to plan their content.
+verification needs. Use the [Product feature](page-templates/product-feature.md),
+[Engineering feature](page-templates/engineering-feature.md) and
+[QA validation](page-templates/qa-validation.md) templates alongside the page-type
+guidance and IA Proposal template. A shared screen spec is conditional on several
+journeys using the same screen; do not manufacture one per feature.
 
 ## Navigation Principles
 

package/assets/skills/authoring-docs/references/page-templates/alert-runbook.md

@@ -0,0 +1,63 @@
+---
+title: Alert runbook
+description: Triage, recovery and verification for a specific operational alert.
+---
+
+# Alert runbook
+
+## When to use and entry criteria
+
+Name the alert/symptoms and checks that establish this runbook applies.
+
+## Production context
+
+Identify environment, affected components, customer impact and access prerequisites.
+
+## Ownership
+
+Name the responding role, escalation route and owner-review gaps.
+
+## First-five-minutes triage
+
+| Signal             | Check             | Interpretation             | Next action                   |
+| ------------------ | ----------------- | -------------------------- | ----------------------------- |
+| <observed symptom> | <read-only check> | <supported interpretation> | <numbered step or escalation> |
+
+## Procedure
+
+1. Establish scope with a read-only check.
+   **Verify:** state the expected observation and stop/escalate condition.
+2. Perform the reviewed recovery action.
+   **Verify:** state the successful observation and failure response.
+
+Warn immediately before any destructive command, state its scope and require the
+reviewed dry run first. Do not invent runnable production commands or dry-run flags.
+
+## Why this approach
+
+Explain the evidence and tradeoffs behind the recovery sequence.
+
+## Rollback
+
+Describe the inverse action, recovery prerequisites and verification, or state why
+rollback is unavailable and give the escalation route.
+
+## Verification checklist
+
+- Confirm service health and the original alert condition.
+- Confirm customer-visible recovery and absence of new side effects.
+- Record dated evidence and unresolved owner-reviewed gaps.
+
+## Writing and evidence rules
+
+Use backticks only for literals verified verbatim in source, such as commands,
+errors, labels and identifiers. Write concepts in ordinary prose. Cite the
+source location for each verified literal; label unknown facts as unknown.
+Remove drafting prompts before publishing and retain owner-review gaps explicitly.
+
+Keep these three evidence classes separate:
+
+- Planned automation: intended coverage, with owner and remaining work.
+- Implemented assertions: the test path and the exact assertion it implements.
+- Dated execution evidence: date, environment/configuration, result and evidence
+  location. Implemented assertions alone do not prove a successful execution.

package/assets/skills/authoring-docs/references/page-templates/command-reference.md

@@ -0,0 +1,55 @@
+---
+title: Command reference
+description: Verified command inputs, outputs and mutation boundaries.
+---
+
+# Command reference
+
+Source: <source location for the command registration and handler, or unknown>
+
+## Production impact
+
+State affected environments, access and operational risks; say unknown when unknown.
+
+## Command group index
+
+| Command               | Purpose       | Mutates                    |
+| --------------------- | ------------- | -------------------------- |
+| <verified invocation> | <reader goal> | <yes/no/unknown and scope> |
+
+## Shared flags
+
+List verified spelling, defaults, accepted values and applicability.
+
+## Per-command arguments
+
+For each command, describe positional arguments, flags, required combinations,
+validation and defaults. State unknown rather than inferring behavior from a name.
+
+## Outputs and JSON
+
+Describe human output and the verified --json schema where supported; otherwise
+state unsupported or unknown. Show examples only when verified from source or a run.
+
+## Exit codes
+
+List known categorical outcomes and their codes, including partial results.
+
+## Side effects
+
+Name file, config, service and remote mutations, overwrite behavior and dry-run
+support. Mark unverified effects unknown and identify the reviewing owner.
+
+## Writing and evidence rules
+
+Use backticks only for literals verified verbatim in source, such as commands,
+errors, labels and identifiers. Write concepts in ordinary prose. Cite the
+source location for each verified literal; label unknown facts as unknown.
+Remove drafting prompts before publishing and retain owner-review gaps explicitly.
+
+Keep these three evidence classes separate:
+
+- Planned automation: intended coverage, with owner and remaining work.
+- Implemented assertions: the test path and the exact assertion it implements.
+- Dated execution evidence: date, environment/configuration, result and evidence
+  location. Implemented assertions alone do not prove a successful execution.

package/assets/skills/authoring-docs/references/page-templates/decisions-pointer.md

@@ -0,0 +1,44 @@
+---
+title: Decisions pointer
+description: A curated guide to consequential decisions, not a ledger or an ADR.
+---
+
+# Decisions pointer
+
+## Where records live
+
+Link the repository's authoritative decision store. This page is not a ledger and
+is not an ADR; it routes readers to records without copying their full content.
+
+## How records are created
+
+Describe the existing repository process and required review. Do not initialize a
+new decision system or imply adoption because this template was scaffolded.
+
+## Selected decisions
+
+Curate 3–8 real records relevant to this audience, each with a one-line consequence.
+Remove the drafting row and do not fabricate records to fill a quota.
+
+| Record             | Consequence                          | Staleness flag                    |
+| ------------------ | ------------------------------------ | --------------------------------- |
+| <real record link> | <current effect on reader decisions> | <current/superseded/needs review> |
+
+## Staleness and review
+
+Identify superseded guidance, last verification and owner-review gaps. Keep the
+canonical record authoritative when this pointer becomes stale.
+
+## Writing and evidence rules
+
+Use backticks only for literals verified verbatim in source, such as commands,
+errors, labels and identifiers. Write concepts in ordinary prose. Cite the
+source location for each verified literal; label unknown facts as unknown.
+Remove drafting prompts before publishing and retain owner-review gaps explicitly.
+
+Keep these three evidence classes separate:
+
+- Planned automation: intended coverage, with owner and remaining work.
+- Implemented assertions: the test path and the exact assertion it implements.
+- Dated execution evidence: date, environment/configuration, result and evidence
+  location. Implemented assertions alone do not prove a successful execution.