@open-agent-toolkit/cli 0.3.25 → 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.25"
+  "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
@@ -212,10 +213,18 @@ oat docs nav sync --target-dir apps/my-docs
 
 Generated Fumadocs `meta.json` is strict: a page no `## Contents` map lists
 stays out of the sidebar. The `prebuild` script that `oat docs init` scaffolds
-for Fumadocs does not run the read-only check. To make builds fail on stale
-navigation or an unlisted page, as `apps/oat-docs` does, append
-`&& oat docs nav sync --check` to it; the script runs from the app directory,
-which `--target-dir` defaults to.
+for Fumadocs runs the read-only check before generation/build; fresh MkDocs
+`docs:build` does too. Init explicitly seeds `documentation.navOwner: nav-sync`
+and generates navigation after successful scaffold/config. External scripts select
+`--target-dir .` from the app directory; source-workspace scripts select the
+repo-relative app and quote paths with spaces. Existing apps are not rewritten:
+bootstrap sends undeclared/hand-authored ownership through analyze/apply.
+
+Use shared `documentation.nonReaderPaths` for drafts/page templates with the
+[bounded glob grammar](commands.md#exclusion-patterns). Nav, nav checks and
+manifests omit matches even when Contents links them; `documentation.excludes`
+stays manifest-only. OAT's Fumadocs collections also omit their rendering. Pinned
+MkDocs 1.4.2 still renders those routes; nav exclusion does not make content private.
 
 **Fumadocs** apps also have an app-root docs index manifest, generated from
 the Markdown file tree automatically via `predev`/`prebuild` hooks. You can
@@ -290,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
@@ -305,8 +314,8 @@ need.
 - If a Node/pnpm team wants a hosted site, choose Fumadocs. Its build hooks
   regenerate the app-root `index.md` inventory but not the sidebar files, so run
   `oat docs nav sync` after adding, moving, or renaming pages, commit the
-  `meta.json` files it writes, and add `oat docs nav sync --check` to your build
-  or CI yourself, because the scaffold does not.
+  `meta.json` files it writes. Fresh scaffold builds already run the read-only
+  check; older apps can add it explicitly after choosing nav-sync ownership.
 - If your team uses Python and MkDocs Material, choose MkDocs. Run
   `oat docs nav sync --check` to see what would change before letting nav sync
   rewrite `nav:`.
@@ -315,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

@@ -31,7 +31,7 @@ or **MkDocs Material**.
 Use the framework-specific generated-artifact command:
 
 - Fumadocs apps run `fumadocs-mdx` and `oat docs generate-index`. In this repo, `predev` and `prebuild` regenerate `apps/oat-docs/index.md` from `apps/oat-docs/docs`. Run `oat docs nav sync` yourself after structural changes to rewrite the committed `meta.json` sidebar files from authored directory `index.md` `## Contents` sections; the hooks never write them. `prebuild` runs `oat docs nav sync --check`, so a build fails when those files are stale or a page is unlisted.
-- MkDocs apps use `oat docs nav sync` to regenerate the `nav:` block in `mkdocs.yml` from authored directory `index.md` `## Contents` sections.
+- MkDocs apps use `oat docs nav sync` to regenerate the `nav:` block in `mkdocs.yml` from authored directory `index.md` `## Contents` sections. Fresh scaffolds run its read-only `--check` in `docs:build`.
 
 Markdown needs no generation command or site build; optional inventories require
 explicit external output and retain the authored config index. Both frameworks keep authored `## Contents` sections as the source of local discovery. The generated artifact differs by framework.
@@ -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:
 
@@ -50,6 +50,8 @@ Key behavior:
   to `apps/<app-name>` for monorepos
 - framework apps default to `<app-name>/` at repo root for single-package repos
 - sets `documentation.tooling`, `documentation.root`, and `documentation.index` in `.oat/config.json`
+- fresh Fumadocs/MkDocs creation explicitly seeds `documentation.navOwner: nav-sync` and generates navigation after successful scaffold/config, including an explicitly selected new app in a repo with prior docs config; the old app is not rewritten
+- existing app directories are refused rather than regenerated; bootstrap routes existing framework surfaces through analyze/apply, and Markdown/dry runs never sync navigation
 - for framework apps, when the repo root exposes a compatible Turbo `scripts.build`, patches it to exclude the new docs app from the default root build and adds a root-level `build:docs` script
 - prints a unified diff before writing the root `package.json` change and returns a manual snippet when the patch is skipped because the build script is missing, non-Turbo, or ambiguous
 
@@ -90,12 +92,12 @@ Fumadocs scaffold:
 
 - thin Next.js app importing from `@open-agent-toolkit/docs-config`, `@open-agent-toolkit/docs-theme`, `@open-agent-toolkit/docs-transforms`
 - static export (`output: 'export'`) with FlexSearch, Mermaid diagrams, dark/light mode
-- `predev`/`prebuild` hooks run `oat docs generate-index` automatically
+- `predev`/`prebuild` hooks run `oat docs generate-index` automatically; `prebuild` first runs `oat docs nav sync --target-dir . --check` (source-workspace scripts explicitly select the repo-relative app)
 - starter docs: `docs/index.md`, `docs/getting-started.md`, `docs/contributing.md`
 
 MkDocs scaffold:
 
-- MkDocs Material with OAT contributor contract (unchanged from previous behavior)
+- MkDocs Material with OAT contributor contract; `docs:build` first runs `oat docs nav sync --target-dir . --check` (source workspaces select the app explicitly)
 - includes `docs/index.md`, `docs/contributing.md`, and the local tooling needed to run the app
 
 Supported flags:
@@ -174,10 +176,10 @@ Key behavior:
 - writes configuration only for the Fumadocs manifest transition — recording the manifest it just wrote inside `documentation.root` in `documentation.index`, when `documentation.tooling` is `fumadocs` or the config declares neither `tooling` nor `config`. Markdown and MkDocs configurations are never written, and `documentation.root` and `documentation.config` are never modified
 - prepends an `AUTOGENERATED` warning comment to the output and rewrites the file on every run; do not hand-edit the generated `index.md`
 - should be freshness-checked against authored `docs/**/index.md` `## Contents` maps before treating it as navigation evidence
-- sorting: `index.md` first, then directories before files, then lexical
-- reports the derived docs directory in human output and as `docsDir` / `docsDirSource` under `--json`, alongside `excludes` — the effective exclusion list, `documentation.excludes` merged with the `--exclude` flags exactly as it was handed to the generator
+- ordering: authored local Contents orders surviving direct entries in the hierarchical inventory; cross-directory links order the containing entry without duplicates. Child directory titles use index frontmatter, then H1, then slug. Remaining entries use index/directories/files/lexical fallback and are flagged `[unlisted in Contents]` when Contents exists. Missing Contents keeps fallback; malformed present Contents is an error
+- reports the derived docs directory in human output and as `docsDir` / `docsDirSource` under `--json`, alongside `excludes` — the effective exclusion list, `documentation.excludes`, applicable `documentation.nonReaderPaths`, then the `--exclude` flags, exactly as handed to the generator
 - says where to look when a manifest is empty rather than reporting a bare `0 entries`: which exclusion patterns were active, or that the docs directory held no indexable pages. The wording is observational — the command reports indexed entries, not pattern matches, so it names the exclusions without asserting they are the cause. An empty manifest is a report, not a failure — the file is still written, so a stale index is never left behind, and the command still exits `0`
-- omits pages matching the exclusion list. Nothing is excluded by default; once listed, non-page Markdown such as `CLAUDE.md` or `AGENTS.md` stops reaching the manifest. Patterns come from `documentation.excludes` in `.oat/config.json` and from repeated `--exclude` flags, and the flags **extend** the configured list rather than replacing it. A directory left empty by exclusion emits no heading, and an empty list produces byte-identical output to no exclusions at all
+- omits pages matching the exclusion list. Nothing is excluded by default; once listed, non-page Markdown such as `CLAUDE.md` or `AGENTS.md` stops reaching the manifest. Manifest-only patterns come from `documentation.excludes` in `.oat/config.json` and from repeated `--exclude` flags; matching-root `documentation.nonReaderPaths` also applies, and the flags **extend** the configured list rather than replacing it. A directory left empty by exclusion emits no heading, and an empty list produces byte-identical output to no exclusions at all
 
 Supported flags:
 
@@ -227,7 +229,7 @@ script hooks.
 Use nav sync after adding, removing, renaming, or reordering docs pages.
 
 The command reads only the reserved `## Contents` section from each directory
-`index.md`. It detects the framework from the app directory:
+`index.md`. Starting in 0.3.26, the shared parser reports malformed Contents in both nav sync and manifest generation. Dash links preserve authored order; `### <Label>` groups become Fumadocs separators or MkDocs nested lists. Empty authored groups and `*`/`+` link bullets report file/line errors: add a dash link/remove the heading, or change the bullet to `-`. See the [shared grammar](../reference/docs-index-contract.md#-contents-format). It detects the framework from the app directory:
 
 Plain Markdown needs file/link checks and authored Contents maintenance, without
 site nav generation. Framework apps generate navigation as follows:
@@ -245,8 +247,9 @@ site nav generation. Framework apps generate navigation as follows:
 Use `--check` in builds and CI. It computes the same navigation, writes
 nothing, and exits 1 when any generated file would change or, for Fumadocs,
 any page or folder is unlisted, naming each one (`stale` and `unlisted` in
-`--json`). This repository's `apps/oat-docs` `prebuild` runs it, so
-`pnpm build:docs` fails on stale navigation.
+`--json`). Fresh Fumadocs `prebuild` and MkDocs `docs:build` scripts run it with explicit app selection, preserving external `oat` versus source-workspace CLI commands and quoting paths with spaces. This repository's `apps/oat-docs` `prebuild` also runs it, so `pnpm build:docs` fails on stale navigation.
+
+Shared `documentation.nonReaderPaths` uses the exclusion grammar above, relative to the configured content root. Navigation inventory, explicit Contents links, `--check` and manifests omit matches; excluded metadata is never cleaned or rewritten. An unrelated explicit target does not inherit the setting. `documentation.excludes` stays manifest-only. OAT Fumadocs source collections omit non-readers from rendering too; pinned MkDocs 1.4.2 omits them from nav/manifest but still renders their routes (no rendering-exclusion support).
 
 Fumadocs apps also regenerate the root markdown manifest with
 `oat docs generate-index`; the two commands write different artifacts.

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/reference/cli-reference.md

@@ -233,7 +233,7 @@ Notable commands introduced in the current CLI surface:
 - `--local` — write to or remove from `.oat/config.local.json` (per-developer repo state, gitignored)
 - `--user` — write to or remove from `~/.oat/config.json` (user-level fallback, applies across all repos)
 
-When no flag is passed, the CLI picks a sensible default per key type: structural keys (`projects.root`, `documentation.*`, etc.) go to shared, state keys (`activeProject`, etc.) go to local, workflow preferences (`workflow.*`) go to local. Pass at most one flag — the command rejects multiple surface flags. `documentation.guidance` is shared by default and also accepts `--user`; use a path/URL string or a JSON string array, not a comma-separated list. `documentation.ia` accepts the [recorded IA JSON shape](configuration.md#shared-repo-config-you-will-touch-most-often) and `documentation.navOwner` accepts `nav-sync` or `hand-authored`; both are shared-only. Unset owner means undeclared, and Markdown ignores it. IA is an atomic value in get/dump, not a set of separately configurable child keys.
+When no flag is passed, the CLI picks a sensible default per key type: structural keys (`projects.root`, `documentation.*`, etc.) go to shared, state keys (`activeProject`, etc.) go to local, workflow preferences (`workflow.*`) go to local. Pass at most one flag — the command rejects multiple surface flags. `documentation.guidance` is shared by default and also accepts `--user`; use a path/URL string or a JSON string array, not a comma-separated list. `documentation.ia` accepts the [recorded IA JSON shape](configuration.md#shared-repo-config-you-will-touch-most-often) and `documentation.navOwner` accepts `nav-sync` or `hand-authored`; both are shared-only. Unset owner means undeclared, and Markdown ignores it. IA is an atomic value in get/dump, not a set of separately configurable child keys. `documentation.nonReaderPaths` is also shared-only and uses a comma-separated glob list on `set`, stored as an array; empty clears it. It omits matching reader paths from nav/check/manifest and supported Fumadocs collections, while `documentation.excludes` remains manifest-only. See [non-reader configuration](configuration.md#shared-repo-config-you-will-touch-most-often).
 
 Per-key restrictions apply identically to `set` and `unset`: structural keys can only be written at shared scope, most state keys can only be written at local scope (`activeIdea` is the exception — it accepts both local and user), and workflow preference keys accept any non-auto surface. Legacy `autoReviewAtCheckpoints` remains shared-only; prefer `workflow.autoReviewAtHillCheckpoints`.
 

package/assets/docs/reference/configuration.md

@@ -95,8 +95,9 @@ Common keys in `.oat/config.json`:
 - `git.defaultBranch` — base branch fallback for PR workflows
 - `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership. With tooling `markdown`, root is the literal content directory (including nested `docs`) and `documentation.index` is authored `<root>/index.md`; Markdown adds no framework config. Framework roots retain app/source semantics. Use `oat docs init --framework markdown` or explicit `--adopt` for setup; optional manifests need external output and never change the authored index. See [Documentation path resolution](oat-directory-structure.md#documentation-path-resolution)
 - `documentation.ia` — shared repository-only mirror of the accepted authored IA. Set JSON with required `preset` and repo-relative `decision`, optional `tracks: [{path, principle}]`, and optional `verification: "triad" | "agent-only" | "none"`. The decision record plus Information architecture section in framework docs-app `AGENTS.md` or Markdown contributing page remain authoritative. Use `oat config set documentation.ia '{"preset":"Flat Small","decision":".oat/repo/reference/decisions/DR-example.md","verification":"none"}'`; unset removes the mirror only. Invalid shapes/paths are rejected; neither `--user` nor `--local` is supported.
-- `documentation.navOwner` — shared `nav-sync | hand-authored`, independent of recorded IA, for Fumadocs/MkDocs only. Set with `oat config set documentation.navOwner hand-authored`. Absent is undeclared (`get --json` reports null/default), never implied nav-sync; analyze asks the operator and no automatic regeneration is authorized. Markdown ignores this field. This config support does not change CLI scaffold defaults or explicit nav-sync command behavior.
+- `documentation.navOwner` — shared `nav-sync | hand-authored`, independent of recorded IA, for Fumadocs/MkDocs only. Set with `oat config set documentation.navOwner hand-authored`. Absent is undeclared (`get --json` reports null/default), never implied nav-sync; analyze asks the operator and no automatic regeneration is authorized. Markdown ignores this field. Fresh Fumadocs/MkDocs init explicitly seeds nav-sync and generates navigation after scaffold/config succeeds. Existing apps are not regenerated through bootstrap; explicit nav-sync commands retain their behavior.
 - `documentation.guidance` — advisory Markdown IA source paths/URLs, as a string or ordered non-empty string array. Repo config overrides user config; explicit skill input overrides both. Absent values use the installed `authoring-docs` IA reference. Use `oat config set documentation.guidance ./docs/ia/index.md` or `oat config set documentation.guidance '["~/guidance/index.md","https://example.com/docs/index.md"]' --user`. Arrays retain order; commas in paths are literal. `--local` is unsupported. `get --json` reports `shared`, `user`, or `default` provenance; `unset` reveals the next tier. Only locators are stored, with unrelated config fields preserved. Sources stay read-only, external packs have `index.md` and `## Contents`, and local AGENTS/contributing rules remain authoritative. Conflicts become `ask_user`. See [IA selection](../docs-tooling/workflows.md#ia-selection-and-guidance).
+- `documentation.nonReaderPaths` — shared repository-only array of content-root-relative globs for drafts/templates. Set with `oat config set documentation.nonReaderPaths 'templates/,drafts/**'`; empty value clears and `unset` removes it. Entries are trimmed/de-duplicated; non-arrays, empty or non-string entries are rejected. Local/user writes are refused. The [bounded grammar](../docs-tooling/commands.md#exclusion-patterns) matches nav inventory, explicit Contents targets, nav checks and manifests only for the configured app/content root; excluded metadata is not rewritten. Fumadocs source collections also exclude rendering when wired through OAT source config. Pinned MkDocs 1.4.2 still renders excluded pages as routes; only nav/manifest exclusion is supported.
 - `documentation.excludes` — a JSON array of globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. `oat config set` takes the list as one comma-separated value (`"a/**,b.md"`) and stores it as an array; repeated `--exclude` flags extend it, and an empty value clears the key
 - `documentation.requireForProjectCompletion` — whether docs sync is a completion gate
 - `instructions.claude.shims` — how `oat instructions sync` keeps a `CLAUDE.md` beside each `AGENTS.md`: `none` (the default: no shims; sync removes the ones OAT created and warns about any other `CLAUDE.md`, all or nothing: it removes none while any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` has content of its own; see [All or nothing](../provider-sync/instruction-sync.md#all-or-nothing)), `pointer`, `symlink`, or `copy`. The `--strategy` flag overrides it for one run. Set it with `oat config set instructions.claude.shims pointer` when contributors need `CLAUDE.md` (see [Claude Code and AGENTS.md](../provider-sync/instruction-sync.md#claude-code-and-agentsmd)); `oat config unset` returns to `none`. Any other value is rejected with exit code `2` rather than read as unset, and `oat config set` can still replace it

package/assets/docs/reference/docs-index-contract.md

@@ -15,23 +15,28 @@ OAT docs navigation starts from authored `docs/**/index.md` files. Each `## Cont
 - The `## Contents` section is the machine-readable local map for sibling pages and child directories.
 - Every `## Contents` link should use a `.md`-suffixed relative target, including child directory links such as `subdir/index.md`.
 - Do not hand-edit generated navigation or generated root-index artifacts.
-- For Fumadocs, refresh or freshness-check the generated app-root manifest after adding, removing, or renaming Markdown files. Compare that manifest against authored `## Contents` maps for drift; reordering `## Contents` does not reorder the generated manifest's file-tree sort.
+- For Fumadocs, refresh or freshness-check the generated app-root manifest after adding, removing, or renaming Markdown files. Compare that manifest against authored `## Contents` maps for drift; the manifest follows each local Contents order, with deterministic unlisted fallback entries.
 - Run `oat docs nav sync` after adding, removing, renaming, or reordering pages. It regenerates the framework's navigation from authored `## Contents` maps and preserves the order declared in each local map: the `nav:` block in `mkdocs.yml` for MkDocs, and one `meta.json` per docs directory for Fumadocs.
 
 ## `## Contents` format
 
-Use Markdown bullet links for sibling pages and child directories:
+Use dash-prefixed Markdown links for sibling pages and child directories. Optional third-level headings start ordered groups:
 
 ```md
 ## Contents
 
 - [Getting Started](getting-started.md) - Setup and local workflow.
+
+### Reference
+
 - [Reference](reference/index.md) - Reference pages for the subsystem.
 ```
 
 Notes:
 
 - Links after `## Contents` can include short human-readable descriptions.
+- Groups start at `### <Label>` and end at the next group or the next second-level heading. Links before the first group remain ungrouped. Fumadocs emits `---Label---` before the first retained entry; MkDocs emits a labeled nested list. Filtering a self-index or non-reader link never leaves an empty separator.
+- A group with no authored entries is an error with its file and line; add a dash link or remove the empty heading. A `*` or `+` link bullet is also an error with file and line; replace it with `-`.
 - Child directories should link to their `index.md`.
 - Leaf pages should link to their `.md` filename.
 - Prose outside `## Contents` is ignored by nav generation and remains freeform; it can explain scope, reader paths, or migration status.
@@ -65,8 +70,8 @@ pnpm -w run cli:source -- docs generate-index --docs-dir apps/oat-docs/docs --ou
 
 Fumadocs generated behavior:
 
-- Generated entries are ordered by the file-tree generator: `index.md` first, directories before files, then lexical order.
-- Reordering a `## Contents` block does not reorder the generated manifest's file-tree sort.
+- The inventory stays hierarchical. Each local Contents orders its surviving direct entries; a cross-directory link orders its containing direct entry without duplicating the page. Child directory titles come from their index frontmatter title, then H1, then slug, independently of nav labels.
+- Remaining entries use deterministic index/directories/files/lexical fallback and carry `[unlisted in Contents]` when a Contents map exists. With no Contents map the inventory keeps its fallback order; malformed present Contents reports the shared grammar errors.
 - Generated manifests should carry an autogen warning and are rewritten by `predev` / `prebuild`.
 
 ## Fumadocs Nav Sync
@@ -75,7 +80,7 @@ In a Fumadocs app (detected by its `source.config.ts`), `oat docs nav sync --tar
 
 Fumadocs generated behavior:
 
-- `pages` follows the order of the directory's `## Contents` links. The root list starts with `index`; a child directory appears by its folder name, and its own `index.md` becomes that folder's landing page. A folder whose `meta.json` keeps `root: true` also lists `index` first, because Fumadocs gives a root folder no implicit landing page.
+- `pages` follows the order of the directory's `## Contents` links. The root list starts with `index`; a child directory appears by its folder name, and its own `index.md` becomes that folder's landing page. A folder whose `meta.json` keeps `root: true` or a nonempty trimmed string also lists `index` first, because Fumadocs gives a root folder no implicit landing page. OAT source config narrowly adapts the pinned metadata schema to accept these named roots.
 - Navigation is strict: there is no `"..."` rest entry. A page or folder that no `## Contents` map lists stays out of the sidebar, and the command reports it by path in its human output and in `--json` (`unlisted`). Add the page to its directory's `## Contents` map to show it.
 - A `## Contents` link to a page in another directory is written as a Fumadocs link entry such as `[Writing Skills](/contributing/skills)`, so each page belongs to exactly one folder.
 - A page or folder whose name Fumadocs would read as a `pages` directive, such as `!hidden`, `z...a`, `...name`, or `---`, is written in the local-path form `./!hidden` so it stays a page entry.
@@ -94,9 +99,17 @@ MkDocs generated behavior:
 
 - Root `docs/index.md` becomes `Home`.
 - Child directory `index.md` files become section landing pages.
-- Nested entries are emitted in the order they appear under each local `## Contents` block.
+- Nested entries are emitted in the order they appear under each local `## Contents` block, including labeled groups.
 - `mkdocs.yml` may contain other configuration, but its `nav:` block is derived from authored `## Contents`.
 
+## Non-reader paths and ownership
+
+Shared `documentation.nonReaderPaths` declares drafts/templates outside the reader tree using the [bounded exclusion grammar](../docs-tooling/commands.md#exclusion-patterns), relative to the content root. It applies only to the configured app/content root. Navigation inventory, explicit Contents links, read-only nav checks and manifests skip matches; an explicit link does not override an exclusion. Excluded subtrees are not read, rewritten or cleaned by nav sync. A missing reader entry remains an error in Fumadocs `--check`. Existing `documentation.excludes` affects manifests only.
+
+Fumadocs collections also omit matching pages and metadata when `defineDocs` uses OAT's `docs` and `meta` source options with an explicit repository config path. The pinned MkDocs 1.4.2 has no configurable rendering exclusion: these pages leave navigation and manifests but still render as routes. This setting is not a way to keep private content out of a MkDocs site.
+
+Fresh Fumadocs/MkDocs init explicitly writes `documentation.navOwner: nav-sync` and generates navigation after scaffold/config succeeds. Their generated `prebuild` / `docs:build` scripts run `nav sync --check`. Existing hand-authored or undeclared surfaces are preserved through bootstrap and use analyze/apply to choose ownership; absence never implies permission to regenerate. Markdown has no sidebar or nav sync.
+
 ## Generated-file boundaries
 
 - Edit authored files under the resolved content root (`docs/` inside framework apps, or the literal configured Markdown root), especially the nearest `index.md` and `## Contents`.

package/assets/docs/reference/oat-directory-structure.md

@@ -124,6 +124,7 @@ Current schema keys:
 | `documentation.tooling`                                    | `string`                   | -                        | Documentation tooling identifier (`markdown`, `mkdocs`, or `fumadocs`); parsing remains permissive                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `documentation.config`                                     | `string`                   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `documentation.index`                                      | `string`                   | -                        | Path to the docs surface entry point: authored `<root>/index.md` for Markdown, the generated app-root manifest `<root>/index.md` for Fumadocs, `mkdocs.yml` for MkDocs. Set by `oat docs init`. `oat docs generate-index` writes it only for the Fumadocs manifest transition and never for Markdown or MkDocs.                                                                                                                                                                                     |
+| `documentation.nonReaderPaths`                             | `string[]`                 | -                        | Shared-only content-root-relative bounded globs omitted from nav inventory/Contents/check/manifest and, with OAT source config, Fumadocs rendering. MkDocs 1.4.2 still renders routes. See [Non-reader paths](#non-reader-paths).                                                                                                                                                                                                                                                                   |
 | `documentation.excludes`                                   | `string[]`                 | -                        | Globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. See [Excluding pages from the generated index](#excluding-pages-from-the-generated-index).                                                                                                                                                                                                                                                                                                 |
 | `documentation.requireForProjectCompletion`                | `boolean`                  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `git.defaultBranch`                                        | `string`                   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                                                                                                                                                                                                                                                                                                                                  |
@@ -195,6 +196,18 @@ A legacy source root with no `docs` child resolves `--docs-dir` and `--output` t
 
 **Configuration writes.** The only configuration write generation performs is the Fumadocs manifest transition: when the written manifest lies inside `documentation.root` and `documentation.tooling` is `fumadocs`, the repo-relative output path is recorded in `documentation.index`. A config that declares neither `documentation.tooling` nor `documentation.config` is treated as the same Fumadocs-shaped case. Any other declared tooling — `markdown` and `mkdocs` included — is never written, and neither are `documentation.root` and `documentation.config`. The value is always repo-relative: when `documentation.root` points outside the repository, the manifest is still generated but the key is left untouched rather than recording a machine-specific path.
 
+### Non-reader paths
+
+`documentation.nonReaderPaths` declares drafts/templates outside the reader tree. It uses the bounded grammar below, relative to the configured content root (literal Markdown root or framework app's `docs/`). Nav inventory, explicit Contents targets, read-only nav checks and generated manifests skip matches; excluded subtrees and their metadata are never rewritten or cleaned. The setting applies only to the matching configured app/content root, not an unrelated explicit target. Fumadocs rendering uses the same exclusions through OAT source config's collection options. Pinned MkDocs 1.4.2 cannot exclude rendering: nav/manifest omission leaves routes in the build.
+
+```bash
+oat config set documentation.nonReaderPaths 'templates/,drafts/**'
+oat config set documentation.nonReaderPaths ''
+oat config unset documentation.nonReaderPaths
+```
+
+This is shared repository config only; `--local` and `--user` are rejected. Entries are trimmed and de-duplicated, with malformed values rejected and repairable through `set`. `documentation.excludes` remains manifest-only.
+
 ### Excluding pages from the generated index
 
 `documentation.excludes` and the repeatable `--exclude <glob>` flag feed one matcher. Flags **extend** the configured list rather than replacing it, so a one-off exclusion cannot silently republish pages the repository deliberately excluded. A directory left empty by exclusion emits no heading, and an empty list produces byte-identical output to no exclusions at all.

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