@open-agent-toolkit/cli 0.3.26 → 0.3.27

package/README.md

@@ -41,6 +41,12 @@ Additional useful entry points:
 - `oat repo archive sync`
 - `oat doctor`
 
+## Docs scaffolding
+
+`oat docs init --framework fumadocs --app-name my-docs` creates a docs app with app-root `AGENTS.md`, a reader-first Getting Started stub and contributor/toolchain guides. The CLI owns these templates for both Fumadocs and legacy MkDocs; the bootstrap skill guides inspection and setup. Existing files and plain Markdown adoption are preserved.
+
+Fumadocs static exports include `llms.txt`, `llms-full.txt` and `llms/<page-slugs>/content.md` (root `llms/content.md`) for loaded `.md` readers. These retain authored Markdown and source-relative-link guidance; configured non-readers and MDX are excluded. Use authored Contents maps and `oat docs nav sync`, followed by `--check`, for navigation changes.
+
 ## Update Notifications
 
 On ordinary interactive command runs, OAT may print a passive notice when npm's stable `latest` CLI version is newer than the installed version. The cache normally limits checks to once every 24 hours and same-version notices to once every 72 hours; overlapping CLI processes can each perform a check or print a notice.

package/assets/bundle-metadata.json

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

package/assets/docs/contributing/documentation.md

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

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

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

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

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

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

@@ -40,7 +40,7 @@ explicit external output and retain the authored config index. Both frameworks k
 
 Use `oat docs init` to bootstrap Markdown documentation or scaffold a framework app.
 
-> **Consider the `oat-docs-bootstrap` skill instead.** The skill wraps `oat docs init` with preflight detection, richer input gathering (site name distinct from package name), capability-gated post-patches that close open CLI gaps (site-title metadata, Turbopack root, template-content fixes, docs-app `AGENTS.md` bridge, `## Contents` link extensions, `contributing.md` three-surfaces cleanup), build verification, config inspection, and a seven-section educational walkthrough. See [Add Docs to a Repo §3a](add-docs-to-a-repo.md#3a-preferred-the-oat-docs-bootstrap-skill-guided) for the full flow. The CLI documented here remains the authoritative surface for flags and is the right choice when you need a deterministic, non-interactive scaffold (CI, automation).
+> **Consider the `oat-docs-bootstrap` skill instead.** The skill wraps `oat docs init` with preflight detection, richer input gathering (site name distinct from package name), capability probing and verification of CLI-owned scaffolds (including framework app-root `AGENTS.md`), build verification, config inspection, and a seven-section educational walkthrough. Missing capabilities or older scaffold gaps lead to CLI update advice or an analyze handoff with manual CLI/template upgrade recommendations. See [Add Docs to a Repo §3a](add-docs-to-a-repo.md#3a-preferred-the-oat-docs-bootstrap-skill-guided) for the full flow. The CLI documented here remains the authoritative surface for flags and is the right choice when you need a deterministic, non-interactive scaffold (CI, automation).
 
 Key behavior:
 

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

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

package/assets/docs/getting-started/tool-packs.md

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

package/assets/docs/skills/index.md

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

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

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

@@ -6,7 +6,7 @@ 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
 metadata:
-  version: '1.7.1'
+  version: '1.7.2'
 ---
 
 # 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.

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.