@open-agent-toolkit/cli 0.3.26 → 0.3.28

package/assets/public-package-versions.json

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

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

@@ -4,9 +4,9 @@ description: Run when you need to evaluate documentation structure, navigation,
 argument-hint: '[target] [--ia] [--ia-guidance <path|url>]'
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(node:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
+allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(oat docs check:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(node:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: '1.7.1'
+  version: '1.7.3'
 ---
 
 # Docs Analysis
@@ -196,7 +196,7 @@ Capture the evidence sources that will justify later findings and recommendation
 - existing `index.md` trees and repeated directory patterns
 - exact missing or stale paths, commands, and page references
 
-For framework apps, also read [Legacy scaffold checks](references/legacy-scaffold-checks.md). Apply those checks to the actual installed app, cite the observed file and source contract, and report discrepancies in Findings and Recommendations. These are read-only checks, not bootstrap post-patches. Do not change app-shell configuration during analysis or assume docs-apply can edit it; identify the manual upgrade needed when outside apply's current scope.
+For framework apps, also read [Legacy scaffold checks](references/legacy-scaffold-checks.md). Apply those checks to the actual installed app, cite the observed file and source contract, and report discrepancies in Findings and Recommendations. Include missing app-root AGENTS capability and missing page-specific Next metadata, accepting equivalent valid customized arrangements. These are read-only checks, not bootstrap scaffold repairs. Do not change app-shell configuration during analysis or assume docs-apply can edit it; identify the manual upgrade needed when outside apply's current scope.
 
 Do **not** infer docs structure conventions from a tiny sample of pages when the broader
 tree or config disagrees.
@@ -457,6 +457,17 @@ where the docs should live, and what specific subtopics the codebase shows shoul
 
 ### Step 6: Check Navigation and Drift
 
+Probe the installed `oat docs check --help`, then run its read-only
+`oat docs check --target-dir <resolved-root> --json` (or the repo’s documented
+source/local CLI equivalent). Retain exact findings and exit; errors fail while
+warning-only passes. Use stable rule IDs/locations as evidence for recommendations,
+including reader limits, contributor commands, Mermaid/SVG and provenance. It
+executes no page code or documented commands and needs no build. Missing capability
+or unusable Git diagram base is explicitly unverified. Preserve specialized local
+validators; portable success does not establish coverage or claim accuracy. Review
+narrow reason-bearing exceptions from actual config, never invent blanket
+suppressions or automatic navigation ownership.
+
 If a generated root index or manifest exists:
 
 1. Compare generated entries with the authored `## Contents` graph.

package/assets/skills/oat-docs-analyze/references/legacy-scaffold-checks.md

@@ -12,5 +12,9 @@ Evaluate existing framework apps against the current contracts below. A match pr
 | Contents links omit `.md` despite real Markdown targets                                                                                          | Medium: recommend `.md`-suffixed source links, which the build transforms into routes.                                                                                                                                                                                                                                                                                                            | Authored Contents contract and docs-transforms links plugin                 |
 | Contributing duplicates agent runtime rules rather than pointing to app-root `AGENTS.md`                                                         | Low: recommend consolidating runtime instructions into the existing agent guidance after approval; preserve custom rules.                                                                                                                                                                                                                                                                         | Docs-app guidance and contributing audience boundary                        |
 | MkDocs setup says `setup-docs.sh` creates a virtual environment, config calls `tooling` an object, or index points at an assumed `docs/index.md` | Medium: verify the actual script and `.oat/config.json`. The scaffold installs with the selected Python, uses a framework string, and seeds index/config as `mkdocs.yml`.                                                                                                                                                                                                                         | MkDocs setup script, documentation schema and scaffold config               |
+| Framework app has no app-root AGENTS.md                                                                                                          | Medium: missing current CLI scaffold capability. Recommend a CLI update and manual review of the canonical framework template; preserve existing files and never recreate a bootstrap-owned template.                                                                                                                                                                                             | Current CLI Fumadocs/MkDocs AGENTS scaffolds                                |
+| Fumadocs pages inherit only layout/site metadata                                                                                                 | Medium: inspect the catch-all page and any relevant layout/metadata producers for page-specific title and description. Recommend manual app-shell review when absent. Accept equivalent valid Next `generateMetadata`, static per-page exports or customized layouts that produce correct page-specific metadata; do not demand the template's exact spelling.                                    | Current page template and Next Metadata API                                 |
+| Reader Getting Started contains contributor toolchain setup                                                                                      | Medium: recommend moving setup into a contributor guide and restoring a first-safe-reader-result entry, with inbound links and old URLs reviewed.                                                                                                                                                                                                                                                 | Reader-first current framework scaffolds                                    |
+| MkDocs/Material is presented as the actively developed default                                                                                   | Medium: cite Material's maintenance/security window through May 5, 2027 and Zensical successor from the [upstream changelog](https://squidfunk.github.io/mkdocs-material/changelog/). Distinguish Material from MkDocs core and retained pins from current upstream maintenance.                                                                                                                  | Material upstream support statement                                         |
 
 A user-owned dynamic app may intentionally omit static export. Do not apply a static-export finding to it without evidence that static output is required. Likewise, verify commands and filenames against the target repository; these patterns identify discrepancies, not authority to overwrite customization.

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

@@ -6,7 +6,7 @@ disable-model-invocation: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: '1.2.0'
+  version: '1.2.1'
 ---
 
 # OAT Docs Authoring

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

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

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

@@ -1,17 +1,17 @@
 ---
 name: oat-docs-bootstrap
-description: 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).
+description: 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).
 argument-hint: '<optional-target-dir> [--ia-guidance <path|url>]'
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: '1.4.2'
+  version: '1.4.4'
 ---
 
 # Docs Bootstrap
 
-Bootstrap or adopt documentation in this repo and guide the user through understanding how it works. Wraps `oat docs init` with preflight detection, richer input gathering, the gated FP-15 docs-app AGENTS.md bridge, build verification, post-scaffold config inspection, and an educational walkthrough covering the `index.md` + `## Contents` navigation contract, scaffolded agent-instruction surfaces, and the OAT docs ecosystem (`oat-project-document`, `oat-docs-analyze`, `oat-docs-apply`).
+Bootstrap or adopt documentation in this repo and guide the user through understanding how it works. Wraps `oat docs init` with preflight detection, richer input gathering, CLI-owned docs-app AGENTS.md scaffolding, build verification, post-scaffold config inspection, and an educational walkthrough covering the `index.md` + `## Contents` navigation contract, scaffolded agent-instruction surfaces, and the OAT docs ecosystem (`oat-project-document`, `oat-docs-analyze`, `oat-docs-apply`).
 
 ## Prerequisites
 
@@ -23,12 +23,12 @@ Bootstrap or adopt documentation in this repo and guide the user through underst
 
 **OAT MODE: Docs Bootstrap**
 
-**Purpose:** Turn `oat docs init` scaffolding into a support-rich onboarding experience — preflight, inputs, CLI invocation with gated post-patches, build verification, config inspection, educational walkthrough, and optional content kickoff. Three paths: Markdown (authored content without an app), Fumadocs (full), and MkDocs (lean with defined minimum contract).
+**Purpose:** Turn `oat docs init` scaffolding into a support-rich onboarding experience — preflight, inputs, CLI-owned scaffold invocation, build verification, config inspection, educational walkthrough, and optional content kickoff. Three paths: Markdown (authored content without an app), Fumadocs (full), and MkDocs (lean with defined minimum contract).
 
 **BLOCKED Activities:**
 
 - No reimplementing CLI scaffold logic (the CLI remains the source of truth for template rendering, version resolution, and configuration writes)
-- No fabricating files the CLI does not create, with one documented exception: the FP-15 bridge AGENTS.md, which is written only when the CLI has not scaffolded one and whose content is migrated upstream when the CLI fix lands
+- No fabricating scaffold files the CLI does not create; report older CLI output through analyze and recommend a manual CLI/template upgrade
 - No expanding scope into content authoring (that's `oat-docs-analyze` / `oat-docs-apply` / `oat-project-document`)
 - No silent failures — every error has a surfaced remediation
 
@@ -37,9 +37,11 @@ Bootstrap or adopt documentation in this repo and guide the user through underst
 - Inspecting repo state read-only before any mutation
 - Prompting the user for richer inputs than the CLI asks for (notably a site name separate from the package/app name)
 - Invoking `oat docs init` non-interactively with collected flags
-- Applying gated, idempotent post-patches for open CLI gaps (FP-15) only when capability detection shows the CLI has not addressed them
+- Inspecting native scaffold capabilities and reporting missing current-template guidance without rewriting it
 - Running install + build and classifying failures against known patterns
 - Reading `.oat/config.json` back to verify paths and prompting for `requireForProjectCompletion`
+- Presenting concrete PR CI edits from `references/pr-ci.md`, writing only the approved diff while preserving existing workflows
+- Presenting the exact effective-install-root compatibility policy below and writing only that approved root-policy edit while preserving existing settings/conflicts
 - Narrating the scaffolded output as a chunked educational walkthrough
 - Delegating optional initial content population to `oat-docs-analyze` + `oat-docs-apply`
 
@@ -49,7 +51,7 @@ If you catch yourself:
 - Writing scaffold-template content directly instead of calling the CLI → STOP (the CLI owns templates; you own the surrounding experience)
 - Narrating AGENTS.md content word-for-word in the Walkthrough → STOP (the Walkthrough points at AGENTS.md; it does not read it aloud)
 - Expanding into full content generation → STOP (delegate to analyze/apply)
-- Applying a post-patch without running capability detection first → STOP (patches must be gated on deterministic probes and file-shape checks)
+- Recreating missing CLI scaffold content from the skill → STOP (report a missing capability and manual upgrade instead)
 
 **Recovery:**
 
@@ -112,14 +114,14 @@ OAT ▸ DOCS BOOTSTRAP
 
 ### Markdown path through the seven steps
 
-The detailed framework procedures below apply to Fumadocs/MkDocs. When the selected tooling is `markdown`, use this path for Steps 2–7 instead; never run framework post-patches, the FP-15 AGENTS bridge, dependency discovery/install, package/Turbo patches, or a site build. Step 1 remains the shared read-only detector.
+The detailed framework procedures below apply to Fumadocs/MkDocs. When the selected tooling is `markdown`, use this path for Steps 2–7 instead; never run framework scaffold repairs, docs-root AGENTS creation, dependency discovery/install, package/Turbo patches, or a site build. Step 1 remains the shared read-only detector.
 
 1. **Preflight and routing:** Read `documentation.tooling` as a non-empty string. A non-string value (including a legacy object with a `framework` field) is invalid/undeclared tooling in the CLI; surface it for a user decision before proceeding, without silently clearing or retagging it. Declared tooling is authoritative: configured Markdown uses `documentation.root` literally, including when it contains a child named `docs`; declared frameworks or unknown stacks are not plain-doc adoption candidates. With no declared tooling, check framework evidence first (`mkdocs.yml`, Fumadocs/Next config and docs-app package scripts/dependencies), then inspect the chosen dedicated content directory for authored `.md`/`.mdx` pages. A repository-root README alone is insufficient; an empty selected directory is fresh setup. For a populated plain tree, default to `oat-docs-analyze` then `oat-docs-apply` for approved repairs and exit without scaffolding. Offer **adopt and audit**, **audit only**, or **abort** when adoption is explicitly requested. Audit only delegates read-only to `oat-docs-analyze` and exits. Adoption requires the explicit user choice and CLI `--adopt`; `--yes` alone never authorizes it. An incompatible declared root/index/tooling requires a user decision, with no silent clearing or retagging. Keep the existing explicitly authorized framework replacement path when a framework is selected.
 2. **Gather inputs:** Offer “Markdown (plain files), Fumadocs, or MkDocs?” Collect documentation title (`--site-name`), dedicated relative target directory (default `docs` in every repo shape), and optional description. Reuse an existing compatible configured Markdown root. Ask no app/package name, package-manager, site-runtime, or dependency questions. Lint and format default to `none`; describe selected existing repository tools only, without installing them. Validate a nonempty title and a dedicated in-repository target, excluding the repository root and escaping symlinks. Confirm fresh setup or additive adoption, title, root, and audit handoff. `appName` is absent and `conflictResolution` is `adopt`, `audit`, `abort`, or null for this path.
    Before Markdown CLI invocation, run **Step 2.5** for fresh setup and explicitly selected adoption; it is not bypassed by this condensed path.
 
-3. **Invoke CLI:** Probe `$CLI_CMD docs init --help` and require advertised Markdown/`--adopt` support before invocation; if missing, report the needed CLI update rather than fabricating scaffold files. Run `$CLI_CMD docs init --framework markdown --target-dir <root> --site-name <title> --description <description> --lint none --format none --yes`, adding `--adopt` only for explicit adoption. Pass the selected lint/format values when using existing tools. Never pass app-only flags. An optional `--dry-run` previews file/config/guidance changes without writes; it does not count as a completed bootstrap. Capture terminal/JSON results, exact exit, created/preserved files, config changes, guidance action, and audit advice. `partial`/exit 1 with manual-required or blocked guidance means unresolved guidance; real runs may have created files, whereas dry-runs have only planned files. Report actual state and stop before claiming completion. Other refusals also stop without post-patches. For success, read config back to resolve the actual content root and authored index.
-4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions. Fresh setup creates only authored `index.md` and `contributing.md` in the target; verify no docs-root AGENTS, app package, framework config, dependencies, or root build changes. Run already documented lint/link/format checks when applicable; otherwise inspect files/links directly. Adoption preserves existing bytes and may leave missing child indexes, metadata, context, or links: record these as audit gaps for analyze/apply rather than repairing them or calling the tree fully conformant. Distinguish successful setup verification from content-conformance findings.
+3. **Invoke CLI:** Probe `$CLI_CMD docs init --help` and require advertised Markdown/`--adopt` support before invocation; if missing, report the needed CLI update rather than fabricating scaffold files. Run `$CLI_CMD docs init --framework markdown --target-dir <root> --site-name <title> --description <description> --lint none --format none --yes`, adding `--adopt` only for explicit adoption. Pass the selected lint/format values when using existing tools. Never pass app-only flags. An optional `--dry-run` previews file/config/guidance changes without writes; it does not count as a completed bootstrap. Capture terminal/JSON results, exact exit, created/preserved files, config changes, guidance action, and audit advice. `partial`/exit 1 with manual-required or blocked guidance means unresolved guidance; real runs may have created files, whereas dry-runs have only planned files. Report actual state and stop before claiming completion. Other refusals also stop without template repairs. For success, read config back to resolve the actual content root and authored index.
+4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions. Fresh setup creates only authored `index.md` and `contributing.md` in the target; verify no docs-root AGENTS, app package, framework config, dependencies, or root build changes. Run `$CLI_CMD docs check --target-dir <literal-root>` and already documented lint/link/format checks when applicable. Errors block conformance; warnings remain review items. Use `references/pr-ci.md` to present checker-only PR wiring with empty build/manifest inputs unless a generated external manifest was separately configured; apply only the approved workflow diff. Adoption preserves existing bytes and may leave missing child indexes, metadata, context, or links: record these as audit gaps for analyze/apply rather than repairing them or calling the tree fully conformant. Distinguish successful setup verification from content-conformance findings.
 5. **Inspect config:** `documentation.tooling` is the string `markdown`; `root` is the literal content directory; `index` is its authored entrypoint, normally `<root>/index.md`. Markdown introduces no `documentation.config`. Preserve unrelated config/excludes/completion settings. Verify deterministic managed root Documentation guidance names that root, Markdown tooling, authored index, and `<root>/contributing.md`; preserve manual/local guidance and surface unresolved disposition. The Step 5e completion opt-in remains available using the docs root rather than an app name, without silently changing an existing value. No nested app-config reconciliation or framework patch inspection applies.
 6. **Walkthrough:** In short chunks, show actual config and `<root>/index.md`: useful context plus the Contents map, title/description metadata, sibling `page.md` and child `section/index.md` links, exclusions and asset-only exceptions. Explain adding a page/section and updating the nearest authored map without overwriting existing context. Root AGENTS Documentation guidance and `<root>/contributing.md` establish agent/human conventions; a preexisting local AGENTS file remains authoritative, but bootstrap creates none. Authored indexes are edited directly. Optional generated inventories require explicit external output, e.g. `$CLI_CMD docs generate-index --docs-dir <root> --output .oat/docs-manifest.md`; output must stay outside the full configured content root and cannot overwrite the configured authored index even with a narrowed `--docs-dir`. Generation does not repoint `documentation.index`. Markdown bootstrap never generates a manifest automatically. Skip framework deep dives and preview-server/build commands.
 7. **Audit handoff and summary:** Offer `oat-docs-analyze` against the literal configured root, followed by `oat-docs-apply` only for approved repairs. An adopted incomplete tree needs that audit; config/guidance alone prove no full conformance. Explain `oat-project-document` for source-backed project deltas. Summarize tooling, actual root/authored index, created/preserved files, guidance/config disposition, ordered IA guidance locators/provenance and proposal recommendation/conflicts, file-check outcomes, unresolved audit gaps, optional manifest ownership, and exact skill handoff. For dry-run/partial/refusal, label the outcome accordingly rather than printing BOOTSTRAP COMPLETE. No app, install, build, patch, or dev-command fields apply.
@@ -204,7 +206,7 @@ Preflight Result:
 
 ### Step 2: Input Gatherer
 
-Collect the inputs needed to invoke `oat docs init` and apply post-scaffold patches. The skill asks for richer inputs than the CLI prompts for — most importantly, a **site name** separate from the package/app name. Ask one question at a time, surfacing defaults from the Preflight Result, and end with a coherence check before scaffold.
+Collect the inputs needed to invoke `oat docs init` and inspect its CLI-owned output. The skill asks for richer inputs than the CLI prompts for — most importantly, a **site name** separate from the package/app name. Ask one question at a time, surfacing defaults from the Preflight Result, and end with a coherence check before scaffold.
 
 Print `[2/7] Gathering inputs…` at the start of this step.
 
@@ -309,7 +311,7 @@ Resolution options:
 - **`abort`** — Stop the flow without any mutation.
   - **Allowed mutations:** None.
   - **Preserved state:** Everything.
-  - **Stop conditions:** Print a compact summary of what was detected and exit immediately. No CLI invocation, no post-patches, no Walkthrough. Example summary:
+  - **Stop conditions:** Print a compact summary of what was detected and exit immediately. No CLI invocation, no template repairs, no Walkthrough. Example summary:
 
     ```
     Aborting docs bootstrap. Nothing was changed.
@@ -404,9 +406,11 @@ through `oat-docs-analyze --ia`; it does not return to scaffold afterward.
    remains undeclared, Markdown ignores it, and no automatic nav generation is
    authorized by IA approval alone.
 
+For MkDocs/Material, disclose the legacy support status before scaffold: [Material upstream](https://squidfunk.github.io/mkdocs-material/changelog/) promises critical fixes/security updates through May 5, 2027, then maintenance ends, and identifies [Zensical](https://zensical.org/) as its successor. This is Material's window, not MkDocs core EOL or a promise that the retained old Python pins receive every fix. No implicit Python upgrade is authorized.
+
 ### Step 3: Scaffold Runner
 
-Invoke `oat docs init` with the collected inputs and then apply gated post-patches for any CLI gaps the Capability Detection sub-procedure reports as still-open. The Scaffold Runner probes CLI capabilities, invokes the CLI, and applies the AGENTS.md bridge if still needed. Template content is CLI-owned; report old-scaffold shapes through `oat-docs-analyze`.
+Invoke `oat docs init` with the collected inputs. The Scaffold Runner probes capabilities, invokes the CLI and verifies its output. The CLI owns framework app-root AGENTS.md and all template content; report missing capabilities and older scaffold shapes through `oat-docs-analyze` with a manual CLI/template upgrade recommendation. Never create a second template owner in this skill.
 
 Print `[3/7] Scaffolding…` at the start of this step.
 
@@ -414,7 +418,7 @@ Print `[3/7] Scaffolding…` at the start of this step.
 
 For an explicitly fresh Fumadocs/MkDocs app, current CLI init writes `documentation.navOwner: nav-sync` and generates navigation after successful scaffold/config. An explicitly selected new app in a repository with prior docs config is fresh creation; preserve the old app's authored files. This does not authorize regeneration of an existing app: keep undeclared/hand-authored ownership untouched and use the existing analyze/apply handoff. IA approval alone never authorizes navigation writes. Markdown and dry runs run no nav sync.
 
-Inspect the generated package scripts rather than adding a duplicate patch: Fumadocs `prebuild` and MkDocs `docs:build` run `nav sync --check`, using external `oat` from the app directory with `--target-dir .`, or source-workspace CLI with the explicit quoted repo-relative app. A stale navigation check requires fixing authored Contents and explicitly syncing owned navigation before retrying, not deleting the check or silently regenerating an undeclared owner.
+Inspect the generated package scripts rather than adding a duplicate patch: `docs:check` runs the portable checker and MkDocs `test` runs the same real check. Framework builds run the checker before navigation/build. Fumadocs `prebuild` and MkDocs `docs:build` run `nav sync --check`, using external `oat` from the app directory with `--target-dir .`, or source-workspace CLI with the explicit quoted repo-relative app. A stale navigation check requires fixing authored Contents and explicitly syncing owned navigation before retrying, not deleting the check or silently regenerating an undeclared owner.
 
 **3a. Assemble CLI flags.**
 
@@ -442,12 +446,12 @@ Do not pass flags the CLI doesn't advertise. Never assume a flag exists because
 Before CLI invocation, run `$CLI_CMD docs init --help` once. Record:
 
 - `siteNameFlag`: whether `--site-name` is advertised.
-- `agentsMdScaffoldFlag`: whether help or the installed template file list confirms native `AGENTS.md` scaffolding.
+- `agentsMdScaffold`: whether the installed framework template file list confirms native app-root `AGENTS.md` scaffolding; if unavailable, record unknown and verify actual output after invocation. Do not infer a CLI flag from this capability.
 - `noRootPatchFlag`: whether `--no-root-patch` is advertised.
 
 If the probe fails or returns no help, stop with the verbatim error and recommend updating or repairing the CLI. Never guess capabilities.
 
-After scaffolding, inspect `<appRoot>/AGENTS.md`: absent permits the FP-15 bridge; any existing file is preserved. Check template output against the current scaffold contract. Older output with missing metadata, unresolved Node-version advice, missing generated-files guidance, extension-less Contents links, duplicated agent instructions, or a Fumadocs wrapper that loses static export settings becomes a finding under `oat-docs-analyze`'s legacy scaffold checks (load that skill from installed scope and resolve `references/legacy-scaffold-checks.md` from its own directory). Record the observed path and evidence, then offer analyze; do not reinstate template patches. Ambiguous or user-authored shapes are reported for review, never overwritten.
+After scaffolding, inspect `<appRoot>/AGENTS.md`: absence is a missing-capability finding with analyze/manual upgrade advice; any existing file is preserved. No missing-file bridge is permitted. Check template output against the current scaffold contract. Older output with missing metadata, unresolved Node-version advice, missing generated-files guidance, extension-less Contents links, duplicated agent instructions, or a Fumadocs wrapper that loses static export settings becomes a finding under `oat-docs-analyze`'s legacy scaffold checks (load that skill from installed scope and resolve `references/legacy-scaffold-checks.md` from its own directory). Record the observed path and evidence, then offer analyze; do not reinstate template patches. Ambiguous or user-authored shapes are reported for review, never overwritten.
 
 **3c. Invoke the CLI.**
 
@@ -463,7 +467,7 @@ Capture both stdout and stderr. **Do not** stream output directly to the user; t
 
 - Surface the CLI's stderr **verbatim** to the user (no re-wording — the user needs to see exactly what the CLI said).
 - Print the exit code and the exact flag list that was passed.
-- **Stop the flow.** Do not apply any post-patches. Do not proceed to Build Verifier. A failed scaffold produces an undefined state; guessing at recovery is worse than letting the user diagnose.
+- **Stop the flow.** Do not repair scaffold output. Do not proceed to Build Verifier. A failed scaffold produces an undefined state; guessing at recovery is worse than letting the user diagnose.
 - Example surfaced error:
 
   ```
@@ -493,42 +497,18 @@ Capture both stdout and stderr. **Do not** stream output directly to the user; t
     capabilities: { siteNameFlag: boolean, ... } // from Capability Detection (3b)
     cliLogs: { stdout: string, stderr: string }  // retained for Walkthrough
     rootBuildPatch: { status, reason?, diff?, manualSnippet? } | null // parsed from CLI output when available
-    patchesApplied: []               // populated by the FP-15 bridge in 3d
+    appAgents: { status: cli-scaffolded | preserved | missing, path, suggestedFix? } // from 3d
   ```
 
 The Walkthrough (Step 6) and Post-Scaffold Inspector (Step 5) both consume `Scaffold Result`; keep it structured and avoid shell-side ephemeral state.
 
-**3d. Apply the remaining bridge.**
-
-FP-15 is the only post-scaffold patch. It is gated by detected capability and file absence, is idempotent, and appends `{ id, status: 'applied' | 'skipped', reason? }` to `Scaffold Result.patchesApplied`. All other scaffold content comes from the CLI template.
-
-**FP-15: AGENTS.md write-if-missing (Fumadocs/MkDocs only).**
-
-Never apply this bridge to Markdown: its root is the content directory and bootstrap must not create a docs-root AGENTS file.
-
-Gate: run **only if** `capabilities.agentsMdScaffoldFlag === false` AND `<appRoot>/AGENTS.md` does not exist on disk.
-
-- If the CLI scaffolded `AGENTS.md` itself, skip with `status: 'skipped', reason: 'CLI scaffolds AGENTS.md'`.
-- If the file already exists (user hand-authored, or a previous skill run wrote it), **never overwrite**. Skip with `status: 'skipped', reason: 'AGENTS.md already present — not overwriting'`.
-
-Procedure when gate passes:
+**3d. Verify CLI-owned agent guidance.**
 
-1. Read the template from `.agents/skills/oat-docs-bootstrap/assets/AGENTS.md.template`.
-2. Substitute placeholders:
-   - `{{SITE_NAME}}` → `{siteName}` (Input Result)
-   - `{{APP_DIR}}` → `{targetDir}` (Input Result; the scaffolded app path relative to repo root)
-   - `{{REPO_NAME}}` → `{repoName}` (Preflight Result)
-   - `{{GENERATE_INDEX_CMD}}` → derive from the scaffolded `<appRoot>/package.json`:
-     1. Parse JSON and inspect `scripts.predev` first, then `scripts.prebuild`.
-     2. Find the `fumadocs-mdx &&` segment and use the trimmed command that follows it.
-     3. If neither script contains that segment, fall back by repo shape: monorepo uses `pnpm -w run cli -- docs generate-index --docs-dir {appDir}/docs --output {appDir}/index.md`; nested-standalone and single-package use `oat docs generate-index --docs-dir docs --output index.md` from the app root.
-3. Write the rendered content to `<appRoot>/AGENTS.md`.
-4. Wrap the entire file in an HTML comment banner at the top — not for idempotency (file existence is the idempotency check), but so the user knows this file was written by the skill and can be regenerated: `<!-- Generated by oat-docs-bootstrap (FP-15 bridge). Safe to hand-edit after generation. -->`.
-5. Record `{ id: 'FP-15', status: 'applied', target: '<appRoot>/AGENTS.md' }` in `patchesApplied`.
+Inspect the actual app-root AGENTS.md and compare createdFiles with the preflight snapshot. Record `Scaffold Result.appAgents` as `cli-scaffolded`, `preserved`, or `missing`, including the path and missing-capability/manual upgrade advice. A missing file on older CLI output becomes an analyze finding; recommend updating the CLI and reviewing the current canonical framework template manually. Do not copy an asset, create a replacement file or overwrite user content. The skill ships no AGENTS template.
 
-When the CLI eventually scaffolds `AGENTS.md` natively and `agentsMdScaffoldFlag` becomes `true`, the bridge template in this skill can be retired (or folded back into the skill as a reference for how the CLI's template evolved).
+Check that Getting Started serves readers, contributor setup lives under `docs/contributing/`, and contributing points one level up to app-root AGENTS.md. Verify framework-specific authored/generated rules, IA/agent-use guidance and commands with explicit working directories. Record observed gaps rather than fixing them during bootstrap.
 
-**Design discipline:** CLI errors stop the flow. Preserve existing files, report legacy output through analyze, and apply only the absent-file AGENTS bridge. Template upgrades belong to the CLI rather than bootstrap rewrites.
+**Design discipline:** CLI errors stop the flow. Preserve existing files and report legacy output through analyze/manual upgrade. Template rendering and upgrades remain CLI-owned.
 
 ### Step 4: Build Verifier
 
@@ -538,6 +518,40 @@ Print `[4/7] Verifying build…` at the start of this step.
 
 Skip this step entirely if `Scaffold Result.scaffoldSucceeded !== true` — a failed scaffold produces an undefined state; installing and building on top of it makes things worse.
 
+**4a prerequisite: inspect and approve Fumadocs install-root policy.**
+
+Before running install, read the CLI's `installationAdvice` and the generated
+toolchain guide. Locate the actual pnpm installation root, including any enclosing
+`pnpm-workspace.yaml`; a workspace member's package is not that root. Current
+Fumadocs loses handler properties added by `mdast-util-to-markdown` 2.2.0, so valid
+bold/italic content can fail compilation. Preserve all content and framework APIs.
+The required compatibility constraint is exactly 2.1.2 in the effective root's
+`pnpm-workspace.yaml`:
+
+```yaml
+overrides:
+  mdast-util-to-markdown: 2.1.2
+```
+
+A newly scaffolded independent app has its own root YAML (`packages: []` plus
+this override); inspect it and install there. The CLI never creates this boundary
+in monorepo mode or under an enclosing pnpm workspace. For an existing workspace
+root, PRESENT the exact concrete YAML diff and obtain explicit approval before
+writing it. Preserve package globs and all unrelated settings; add the entry to
+an existing `overrides` map, never duplicate the map or replace the file. A
+conflicting existing pin requires the owner's decision; a declined/skipped edit
+stays a manual setup requirement and verification remains pending. Do not create
+a local boundary that splits a workspace member. Do not implement a policy merger
+or silently extend CLI root-package patching: it changes build scripts only,
+and `--no-root-patch` neither sets nor approves dependency policy.
+
+Honor the selected manager (pnpm 10+); effective-root YAML works in pnpm 10 and 12.
+A member-only override is ignored in 10, and 12 also ignores `package.json`'s
+`pnpm.overrides`. After install, inspect actual `pnpm why mdast-util-to-markdown`
+from that root, confirm 2.1.2, retain the root config/lockfile, then run checker and
+build. Label this a constrained fresh install; do not promise unconstrained
+resolution, change user-scope pnpm, or delete bold/italic to avoid the failure.
+
 **4a. Install dependencies.**
 
 Command varies by repo shape (from Preflight Result) and framework (Fumadocs only uses pnpm; MkDocs uses Python tooling — handled in the MkDocs Minimum Contract, Step 6):
@@ -548,6 +562,8 @@ Command varies by repo shape (from Preflight Result) and framework (Fumadocs onl
 
 For Fumadocs, capture both stdout and stderr. Print a start line (`Installing dependencies…`) and a completion line with duration.
 
+Before building, run `$CLI_CMD docs check --target-dir <configured-root>` from the repo root. Keep its JSON/findings and exit; metadata/maps/links, contributor commands and real Mermaid syntax are checked without executing page code. Errors stop verification; review warnings and route content repairs through analyze/apply. Never add blanket suppressions to pass bootstrap.
+
 **4b. Build.**
 
 Command varies by shape:
@@ -594,6 +610,7 @@ Record internally for the Post-Scaffold Inspector and Walkthrough:
 
 ```
 Verification Result:
+  installRootPolicy: { path, disposition: 'scaffolded' | 'approved' | 'manual' | 'conflict', resolvedVersion } | null
   installSucceeded: boolean
   buildSucceeded: boolean
   knownIssues: Array<{ pattern, severity: 'benign' | 'flagged' | 'surface-only' | 'auto-fixed', detail }>
@@ -648,7 +665,7 @@ If `repoShape === 'nested-standalone'`, the docs app may have its own `.oat/conf
 
 The parent config describes the repo's docs; the nested config (when present) scopes OAT operations executed from inside the docs app. Do **not** try to reconcile the two or rewrite one to match the other — they serve different scopes by design. Surface what you found; let the user decide.
 
-**5d. Drift detection (config ↔ filesystem ↔ patches).**
+**5d. Drift detection (config ↔ filesystem ↔ scaffold).**
 
 Beyond basic path existence, check for drift between the config and what the Scaffold Runner actually did:
 
@@ -676,7 +693,7 @@ If user opts in (`yes`), write `documentation.requireForProjectCompletion: true`
 
 If user opts out (default), record the decision in `InspectionState.issues` as `{ severity: 'info', detail: 'requireForProjectCompletion remains false (not opted in)' }` and move on; do not write to the config.
 
-**Write-once discipline:** 5e is the only point in this skill where `.oat/config.json` is mutated outside of the CLI's own writes. Preflight is read-only (Step 1). Input Gatherer is read-only (Step 2). Scaffold Runner's writes flow through the CLI (Step 3c). Post-patches (Step 3d) mutate scaffold output files, not the config. If you find yourself about to write `.oat/config.json` anywhere else, stop — it belongs here.
+**Write-once discipline:** 5e is the only point in this skill where `.oat/config.json` is mutated outside of the CLI's own writes. Preflight is read-only (Step 1). Input Gatherer is read-only (Step 2). Scaffold Runner's writes flow through the CLI (Step 3c). Step 3d inspects scaffold output without writing files. If you find yourself about to write `.oat/config.json` anywhere else, stop — it belongs here.
 
 **5f. Emit the Inspection Result.**
 
@@ -692,6 +709,16 @@ Inspection Result:
 
 The Walkthrough's Section D (Configuration readback) references `issues[]` verbatim — format it so it reads cleanly when printed to the user.
 
+**PR CI wiring (after config inspection):** Load `references/pr-ci.md` now.
+Resolve its concrete inputs from the inspected config/scripts, present the exact
+workflow diff, and write only after approval. Preserve existing workflow content
+and use full-history checkout/fetch for the applicable diagram base. Execute its
+checker, real framework build and configured-manifest freshness commands locally;
+record exits and unverified portions. Markdown follows the same recipe with no
+build/default manifest. Include the approved workflow path or declined/pending
+status in the exit summary. This is bootstrap setup authority, not permission to
+rewrite an existing app or introduce deployment.
+
 ### Step 6: Educational Walkthrough
 
 Narrate the scaffolded docs app as a chunked conversation, not a wall of text. The Walkthrough's job is to turn the user from "I ran a scaffold" into "I know how this docs app works". It is **not** a re-explanation of the CLI's output, nor a recitation of the AGENTS.md content — both are live files the user can read; the Walkthrough contextualizes them.
@@ -702,7 +729,7 @@ Skip this step if `Verification Result.buildSucceeded !== true` OR `Inspection R
 
 **Format discipline.** Each section below is a short spoken-style chunk (3–6 short paragraphs), references concrete paths from the `Scaffold Result` / `Inspection Result`, and ends with a single-sentence "what this means for you" takeaway. After each section, pause and check the user wants to continue: `Ready for the next section? (yes / skip to summary)`. If the user says `skip to summary`, jump directly to Step 7's Exit summary.
 
-**Audience discipline.** The Walkthrough is a **setup-time** narration — it runs once, now. The docs-app `AGENTS.md` (FP-15 bridge or CLI-scaffolded) is the **runtime** reference future agents will read when working inside the docs app. These are different audiences at different times; the Walkthrough does not duplicate the AGENTS.md content. If you find yourself reading AGENTS.md content aloud, stop — point the user at the file path instead.
+**Audience discipline.** The Walkthrough is a **setup-time** narration — it runs once, now. The docs-app `AGENTS.md` (CLI-scaffolded or existing authored) is the **runtime** reference future agents will read when working inside the docs app. These are different audiences at different times; the Walkthrough does not duplicate the AGENTS.md content. If you find yourself reading AGENTS.md content aloud, stop — point the user at the file path instead.
 
 #### Section A (both frameworks) — Your OAT documentation config
 
@@ -768,7 +795,7 @@ The docs app is surrounded by three separate places agents and humans are expect
 Narrate the three surfaces with audience + time discipline:
 
 1. **Root `AGENTS.md` `## Documentation` section** — the repo-wide pointer. A 4-line breadcrumb every agent working anywhere in the repo reads first. Written/updated by `oat docs init` (or `oat-docs-apply`). Purpose: "docs live here; here's the framework; here's the config path." Not a tutorial — a signpost.
-2. **Docs-app `AGENTS.md`** at `<appRoot>/AGENTS.md` — the ongoing reference for agents who are **working inside the docs app**, not setting it up. This is the FP-15 bridge file (or CLI-scaffolded equivalent if `capabilities.agentsMdScaffoldFlag === true`). Task-framed sections: "When you need to add a new page", "When you need to restructure navigation", "When you need to audit or bulk-edit docs". **Audience discipline:** this file exists for the agent working on docs content **six months from now**, not for the agent running this skill today. Everything in it should still be useful at that time. If content would only matter at setup time, it belongs in this Walkthrough, not in `AGENTS.md`.
+2. **Docs-app `AGENTS.md`** at `<appRoot>/AGENTS.md` — the ongoing reference for agents who are **working inside the docs app**, not setting it up. The CLI scaffolds it for both frameworks; older output without it receives analyze/manual upgrade advice, never a skill-created replacement. Task-framed sections: "When you need to add a new page", "When you need to restructure navigation", "When you need to audit or bulk-edit docs". **Audience discipline:** this file exists for the agent working on docs content **six months from now**, not for the agent running this skill today. Everything in it should still be useful at that time. If content would only matter at setup time, it belongs in this Walkthrough, not in `AGENTS.md`.
 3. **`docs/contributing.md`** — human-authoring conventions. Markdown feature reference (code blocks, mermaid, GFM alerts), frontmatter requirements, linting/formatting commands (if enabled). Not agent instructions — human reference. Agents working with docs content may read it for the Markdown feature list, but its primary audience is a human contributor.
 
 End with: "Three surfaces, three audiences, three lifetimes. Root `AGENTS.md` = repo-wide pointer. Docs-app `AGENTS.md` = future agents working inside the docs app. `contributing.md` = humans. Keeping them separate keeps each one useful."
@@ -782,6 +809,7 @@ Narrate how the Fumadocs scaffold actually works, grounded in files the user can
 - **`app/layout.tsx` — `DocsLayout` renders the chrome.** The `<DocsLayout>` component from `@open-agent-toolkit/docs-theme` wraps every docs page with the top nav, sidebar, and search UI. It accepts a `branding` prop with `title`, `logo`, etc. **Runtime insight (worth knowing):** the compiled theme bundle only forwards `branding.title` into the nav header chrome — it doesn't use it for page metadata, social cards, or browser tab titles. The CLI template also includes `export const metadata = { title, description }` in `layout.tsx`: the chrome title and the document title are two separate concerns, and both surfaces must be configured. **Anti-pattern to avoid:** passing `title` / `description` to `createDocsConfig()` in `next.config.js` is a no-op — the wrapper accepts `basePath` and `turbopack`, not metadata. If your HTML `<head>` comes back empty (no `<title>`, no meta description, no Open Graph), the `export const metadata` in `layout.tsx` is missing.
 - **`next.config.js` — `createMDX()` picks up `docs/`.** The Fumadocs MDX pipeline uses `@open-agent-toolkit/docs-config`'s `createDocsConfig()` wrapper, which under the hood calls `createMDX()` with the docs directory hardcoded to `docs/`. Both `.md` and `.mdx` files are compiled at build time; frontmatter becomes typed metadata accessible from layouts and listings. **Default to `.md`** for plain content pages — agents, linters, grep rules, and the `remark-links` plugin all handle `.md` more predictably than `.mdx`. Reach for `.mdx` only when a page actually needs a JSX component inline (an embedded `<Callout>`, an interactive widget, a custom layout). FlexSearch indexes them identically.
 - **FlexSearch static indexing.** Search is client-side — on build, Fumadocs scans every `.md`/`.mdx` file under `docs/` and emits a precomputed FlexSearch index that loads alongside the first route. No server; no search API call. That's also why renaming a page without a redirect loses deep links silently: the old index entry stops existing at the next build, and the new one doesn't know the old slug.
+- **Page metadata and agent Markdown.** The page route reads loaded title/description in `generateMetadata`; layout metadata supplies site defaults. Equivalent valid customized Next metadata arrangements are allowed. Static `/llms.txt`, `/llms-full.txt`, and `/llms/<page-slugs>/content.md` (root `/llms/content.md`) enumerate the same loaded reader `.md` set, including readers outside a hand-authored sidebar. Raw links remain source-relative; use each entry's source path and canonical rendered URL. MDX and configured non-readers are excluded.
 - **`@open-agent-toolkit/docs-theme` branding.** The theme package centralizes the nav/sidebar/footer look and forwards only a small surface of props. Don't expect `branding` to influence metadata; use the Next.js `metadata` export for that.
 - **Turbopack app root.** For `nested-standalone` only, the template passes `dirname(fileURLToPath(import.meta.url))` through `createDocsConfig({ turbopack: { root } })`. Monorepo and single-package scaffolds leave root discovery to Next.js so workspace dependencies remain reachable. This works in ESM and retains static export, trailing slashes, unoptimized images, and base-path settings. Report older wrappers to analyze instead of replacing them.
 
@@ -897,12 +925,15 @@ Config:      {configPath} (documentation section)
 Created:
   - <count> files (see `git status` or `git log -1` for the full list)
 
-Patches applied:
-  - FP-15 docs-app AGENTS.md: {applied | skipped}
+Agent guidance:
+  - App-root AGENTS.md: {cli-scaffolded | preserved | missing}
+  - Missing capability/manual upgrade advice: {path + remedy or none}
 
 Build:
   - Install: {ok | known-issue: ...}
   - Build:   {ok | known-issue: ...}
+  - Install policy: {effective-root YAML + resolved 2.1.2 | manual/conflict/pending; constrained install}
+  - PR CI: {approved workflow path + checker/build/freshness exits | declined | pending}
   - Known issues (from Verification Result.knownIssues): {list or 'none'}
 
 Inspection:
@@ -929,7 +960,7 @@ Reminder: the docs-app AGENTS.md at {appRoot}/AGENTS.md tells future agents how
 to work inside this docs app. Read it before making non-trivial doc changes.
 ```
 
-Substitute every `{placeholder}` with the actual value from `Scaffold Result`, `Verification Result`, or `Inspection Result`. If a patch was `skipped` because the CLI already handled it (e.g., `agentsMdScaffoldFlag === true`), say so explicitly rather than printing `n/a` — the user should know when the CLI has caught up with the skill.
+Substitute every `{placeholder}` with the actual value from `Scaffold Result`, `Verification Result`, or `Inspection Result`. Report whether app guidance came from the CLI, was preserved, or is missing; never print a successful scaffold capability that was not observed.
 
 For the "Next" section's `<framework-specific dev command>`, render:
 
@@ -957,20 +988,20 @@ A successful `oat-docs-bootstrap` run satisfies every invariant below. Any failu
 - Input Gatherer collected the full Input Result (framework, siteName, appName, targetDir, siteDescription, lint, format) plus any `conflictResolution` required by Preflight conflicts; all inputs validated before scaffold.
 - Conflict Resolution Contract's "Allowed mutations" completed for the chosen resolution; pre-scaffold invariant satisfied before `oat docs init` ran.
 - Scaffold Runner invoked `oat docs init` non-interactively with capability-gated flags; CLI exited zero; `Scaffold Result.appRoot` resolved from `.oat/config.json` (not from input alone).
-- Capability Detection produced a deterministic `capabilities` record before scaffold (for flag gating) and classified each patch target after scaffold (scaffold-shape / patched-shape / drift).
-- Every applied post-patch is idempotent and file-type aware: code-file patches use syntactically valid code comments when markers are useful, while rendered Markdown patches rely on content-shape checks instead of hidden FP comments. No patch ran without passing both its capability gate and its file-shape check.
+- Capability Detection produced a deterministic `capabilities` record before scaffold (for flag gating) and verified actual CLI output after scaffold (current / preserved / missing capability).
+- All scaffold files came from the CLI; missing current-template capabilities were reported with paths and analyze/manual upgrade advice, preserving existing bytes.
 - Build Verifier ran install + build with commands matching `repoShape`; failures classified against known patterns; unknown errors halted the flow before Inspector/Walkthrough.
 - Post-Scaffold Inspector verified every `documentation.*` path against disk; drift findings recorded with `suggestedFix`; nested-standalone dual-config surfaced without reconciliation.
 - `requireForProjectCompletion` decision collected from user; written to `.oat/config.json` only on opt-in; never silently default-true.
 - Walkthrough narrated setup-time context, not AGENTS.md runtime content; skipped framework-irrelevant sections; paused between sections with a `skip to summary` escape.
 - Optional Content Kickoff delegated to `oat-docs-analyze` + `oat-docs-apply` on accept; handed off with specific commands on decline.
-- Exit summary printed with actual values (not placeholders) for app, framework, patches applied, build status, inspection findings, and next-step commands.
+- Exit summary printed with actual values (not placeholders) for app, framework, agent-guidance capability, build status, inspection findings, and next-step commands.
 
-**Ratcheting invariants:**
+**Single-owner invariants:**
 
-- When a CLI capability is detected as present (`capabilities.{flag} === true`), the corresponding post-patch is **skipped** — not applied redundantly. The skill self-ratchets as CLI fixes land.
-- Every patch's `status` is recorded in `Scaffold Result.patchesApplied` as `applied` / `skipped` with a `reason`. The Exit summary surfaces this so the user sees which CLI gaps the skill had to cover vs. which the CLI handled directly.
-- When `capabilities.agentsMdScaffoldFlag === true` (CLI has added native AGENTS.md scaffolding), the FP-15 bridge in this skill is skipped and can be retired from the assets directory.
+- CLI templates own both framework app-root AGENTS files. Bootstrap never writes a replacement or rewrites current scaffold content.
+- `Scaffold Result.appAgents` records observed CLI-created/preserved/missing status with a path and remedy; capability and exit-summary claims match the actual files.
+- Older CLI output routes to analyze/manual upgrade guidance while existing Markdown behavior remains unchanged.
 
 **Stop-on-broken-state invariants:**
 
@@ -981,5 +1012,5 @@ A successful `oat-docs-bootstrap` run satisfies every invariant below. Any failu
 **Audience-discipline invariants:**
 
 - The Walkthrough narrates setup-time concepts; it does not recite the docs-app AGENTS.md word-for-word.
-- The docs-app AGENTS.md (FP-15 bridge or CLI-native) contains only guidance that would still be useful six months after scaffold — no "how this was set up" content.
+- The docs-app AGENTS.md (CLI-scaffolded or existing authored) contains only guidance that would still be useful six months after scaffold — no "how this was set up" content.
 - The three agent-instruction surfaces (root `AGENTS.md` `## Documentation`, docs-app `AGENTS.md`, `docs/contributing.md`) are kept distinct by audience + lifetime; the Walkthrough's Section D makes this explicit to the user.

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

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