@open-agent-toolkit/cli 0.3.24 → 0.3.26

package/assets/bundle-metadata.json

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

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

@@ -212,10 +212,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
@@ -305,8 +313,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:`.

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.
@@ -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

@@ -364,8 +364,11 @@ method works without private guidance or copied exemplars.
 Existing docs default to analyze → apply of approved recommendations and exit
 before scaffolding. Replacement requires an explicit choice. A second app also
 requires an explicit choice and remains unsupported by the current CLI. This
-selection stage does not persist IA decisions, restructure trees or materialize
-preset scaffolds. Feature and QA validation page templates are a later delivery;
+proposal becomes durable only after approval: bootstrap/apply use `oat decision new`
+and an Information architecture section in the framework docs-app `AGENTS.md`
+or Markdown contributing page, plus the shared `documentation.ia` mirror.
+Authored records stay authoritative; missing/conflicting records become `ask_user`.
+Preset scaffolds and Feature/QA validation page templates are a later delivery;
 the IA Proposal template is available now.
 
 ## oat-docs-analyze
@@ -421,15 +424,16 @@ repair the analysis contract rather than asking apply to fill it in.
 ## oat-docs-apply
 
 **Invocation:** `/oat-docs-apply` after reviewing a docs analysis report.
-The skill loads the newest `.oat/repo/analysis/docs-*.md` report. You cannot
-select an older one, so rerun analysis if the newest report is not the one
-you reviewed. It then builds a recommendation plan and asks you to choose
+Supply the analysis artifact path and approved recommendation IDs. If no path
+is supplied, the skill offers the newest report for confirmation; it never
+silently changes the reviewed input. It builds a recommendation plan and asks you to choose
 `apply all`, `apply interactively` (approve, modify, or skip each item), or
 `discuss` before changing anything.
 
 **Prerequisites:** A recent, complete docs analysis artifact and an unchanged
 compatible target. Recommendations need evidence, confidence, disclosure,
-and concrete link targets where applicable. Apply also needs `jq` for
+stable unique IDs, `approval: explicit | default`, and concrete link targets
+where applicable. Apply also needs `jq` for
 tracking updates, and `gh` only if you want it to open the pull request. No
 active OAT project is required. Missing analysis or a changed target requires a fresh analysis,
 not conventions invented during apply.
@@ -442,9 +446,12 @@ execute those selected actions without broadening the work to every finding.
 
 **Expected output:** Approved changes committed on a new
 `oat/docs-<timestamp>` branch, relevant source/link checks, and declared
-navigation or generated-artifact refreshes. Markdown retains its authored
+navigation or generated-artifact refreshes, plus a structured result listing
+applied, skipped (ID/reason), and failed IDs. Markdown retains its authored
 index and needs no framework build or nav sync; Fumadocs sidebar metadata is
-regenerated from approved Contents changes, never hand-edited. The summary
+regenerated only with recorded `navOwner: nav-sync`. Hand-authored navigation
+gets approved edits and read-only Contents membership/order comparison;
+undeclared ownership becomes `ask_user`. The summary
 reports the applied plan and checks.
 
 **What it does without asking:** Nothing changes until you approve the plan.
@@ -467,6 +474,44 @@ pull request. Rerun analysis if you need a post-apply assessment, and treat
 unapproved recommendations as remaining decisions rather than completed
 work.
 
+## Approval, IA records and restructuring
+
+Every analyze recommendation has a stable ID and `approval: explicit | default`.
+`apply all` covers only non-blocked default content repairs. Docs-package updates,
+restructure blocks and work outside Markdown scope require individual approval
+by ID; unattended runs skip explicit items even when their IDs were supplied,
+with reason `explicit_requires_interactive_approval`. Kickoff consent is not
+approval of every finding. Bootstrap Step 7b uses this same artifact-plus-ID
+handoff, and apply reports unsupported scaffold work as `manual`.
+
+An approved IA record first checks target-repo PJM adoption with `oat pjm doctor
+--json`; absent/partial adoption needs initialization before `oat decision new`.
+The decision and authored section capture tracks, per-track organizing
+principles, placement and verification overlay. Config mirrors the accepted
+record without replacing it. Framework sidebar ownership is independent; Markdown
+creates no docs-root AGENTS file and runs no nav sync.
+
+A `restructure` block records source→destination mappings, both parent Contents
+changes, grep-derived inbound-link rewrites, and old-URL recovery, then lands as
+one exact-path commit per approved block. Retired pages retain a stub/archive
+pointer and parent map update. Next static export cannot use Next config
+redirects; choose an authored stub or verified host recovery, keeping unsupported
+app/host changes manual. Check rewritten relative links/anchors and the old route
+under the real base path; verify according to sidebar ownership and rerun analyze.
+
+Analyze also audits Information Architecture Fit and declared Product, QA,
+consumer and agent coverage. A top-level misroute is High when it blocks normal
+first success/verification, Medium when it causes material detours; cosmetic
+organization stays Low. Missing IA/owner raises `ask_user`.
+
+For framework apps, offline drift compares installed `@open-agent-toolkit/docs-*` packages to the
+running CLI's bundled `public-package-versions.json`, never registry latest.
+Missing installations are unverified. The recommendation includes the exact
+upgrade command. Individual tooling approval permits only docs-app `@open-agent-toolkit/docs-*`
+dependency bumps (and resulting lockfile), the admonition/frontmatter conversions
+already supported by `oat docs migrate`, and build verification. App config,
+routes and package scripts remain manual required changes.
+
 ## Related docs
 
 - [`commands.md`](commands.md)

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.
+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

@@ -94,7 +94,10 @@ Common keys in `.oat/config.json`:
 - `worktrees.root` — where OAT-managed worktrees live
 - `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. 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/public-package-versions.json

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

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.0'
+  version: '1.7.1'
 ---
 
 # Docs Analysis
@@ -115,8 +115,9 @@ Use the five axes before presets and show two plausible two-level trees with
 5–8 representative page placements each, page jobs, nearest approved presets
 and tradeoffs. A UI alone does not justify Product/Engineering/QA; size chooses
 depth, not audience. For an existing tree respect AGENTS/contributing authority;
-conflicts are `ask_user`, with both source citations. Propose only: no IA
-persistence, restructure action or scaffold materialization in this stage.
+conflicts are `ask_user`, with both source citations. Analyze remains read-only:
+propose `record-ia` or `restructure` recommendations for apply; never persist
+IA or materialize scaffolds from analysis.
 
 ### Step 0: Resolve Docs Target and Analysis Mode
 
@@ -317,6 +318,37 @@ For each evaluated page or directory:
 In `delta` mode, always evaluate changed docs files plus the nearest parent `index.md` pages.
 In `full` mode, evaluate the whole docs surface.
 
+### Information Architecture Fit
+
+Read the authored IA decision and `## Information architecture` section in the
+docs-app AGENTS.md (Fumadocs/MkDocs) or contributing page (Markdown).
+`documentation.ia` is a repository-only mirror: compare preset, decision path,
+tracks/principles and verification overlay to those authored sources. The
+authored record is authoritative; missing/broken records or contradictory
+mirrors become `ask_user` findings. No recorded IA means `ask_user` to choose
+and record one, not an inferred preset. Keep ordinary contract analysis useful
+while those recommendations are blocked.
+
+In the artifact's **Information Architecture Fit** section, cite whether the
+landing page routes each declared audience, all declared sections exist and are
+reachable, page reader/purpose matches placement, root breadth is usable, and an
+app's docs avoid merely mirroring implementation directories. Review coverage
+only for declared readers: Product features/journeys/screens/states; QA scenario
+tables with seeds and automation references; consumer first-success/task guides;
+agent entrypoints, canonical sources and verification commands. Do not demand
+these tracks from every repository or implement the later P24 source checks.
+
+Top-level IA misroutes a declared audience: `High` when the reader cannot find
+a normal first-success or required verification path; `Medium` when that path
+is reachable but its placement causes material detours/confusion. Cite the
+declared audience, route and concrete reader impact. This rule overrides Low
+organization polish; do not upgrade purely cosmetic differences.
+
+For framework apps read `documentation.navOwner` independently of IA. Missing
+means **undeclared**: issue `ask_user` to choose `nav-sync` or `hand-authored`,
+and run only read-only membership/order comparisons. Never assume nav sync owns
+existing navigation. Markdown ignores navOwner and never runs nav sync.
+
 ### Step 4: Verify Substantive Claims Against Repo Sources
 
 Add a dedicated accuracy verification pass between page-quality assessment and nav/drift checks.
@@ -438,8 +470,8 @@ If a generated root index or manifest exists:
    files, and representative links for each finding.
 5. Prefer source-of-truth fixes over generated-file edits.
 
-If the app is Fumadocs (a `source.config.ts` beside `docs/`), its sidebar comes from
-`docs/**/meta.json` files that `oat docs nav sync` generates from `## Contents`:
+For a Fumadocs app with recorded `navOwner: nav-sync`, compare generated
+`docs/**/meta.json` with authored `## Contents`:
 
 1. Flag a docs directory with an `index.md` but no `meta.json` as a missing
    generated artifact.
@@ -463,6 +495,13 @@ If the app is Fumadocs (a `source.config.ts` beside `docs/`), its sidebar comes
    1 when either exists. The skill grants only this `--check` form; plain
    `oat docs nav sync` writes files and is not part of analysis.
 
+For `hand-authored` or undeclared Fumadocs navigation, compare current meta.json
+membership/order with Contents without assuming strict generator output; do not
+flag rest entries merely because they are hand-authored. Report missing reader
+routes and differences with local ownership evidence; recommend no automatic
+regeneration. For nav-sync-owned MkDocs, use the same explicit-target read-only
+`oat docs nav sync --check --target-dir <docs-app-dir>`.
+
 If `mkdocs.yml` exists:
 
 1. Compare nav entries with the docs tree.
@@ -476,6 +515,53 @@ site nav generation or builds. Lack of `mkdocs.yml`, a generated manifest, or an
 app package is expected, not a migration finding. For other unconfigured surfaces,
 record whether app migration is relevant only when evidence or user intent supports it.
 
+### Offline docs-package drift
+
+For framework apps read their package.json and installed docs packages against
+the running CLI's bundled `assets/public-package-versions.json`, without network.
+Run this skill's production helper after resolving this skill's own directory:
+
+```bash
+node "$SKILL_DIR/scripts/package-drift.mjs" --app "<docs-app-dir>" --cli "$(command -v oat)"
+```
+
+If a package-manager wrapper prevents locating the CLI root, discover the bundle
+from that invoked installation offline. Inspect `command -v oat` and, for a shell
+shim, read its `exec` lines or `cmd-shim-target` comment (for example,
+`sed -n '1,160p' "$(command -v oat)"`). Resolve a relative JavaScript target from
+the shim's directory; do not evaluate copied shell text. Locate that target's
+package root containing `package.json` named `@open-agent-toolkit/cli` and
+`assets/public-package-versions.json`. `pnpm root -g` or `npm root -g` can help
+locate it, but newer pnpm installations may nest it in a hashed directory; use
+the actual shim target, never another checkout's bundle. Bind the inspected paths:
+
+```bash
+OAT_INSTALLED_ENTRY="<absolute JavaScript target from the invoked shim>"
+OAT_INSTALLED_ROOT="<that installed @open-agent-toolkit/cli package root>"
+# Both must equal the invoked oat version; stop if either differs.
+test "$(node "$OAT_INSTALLED_ENTRY" --version)" = "$(oat --version)" &&
+  test "$(node -p 'JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).version' "$OAT_INSTALLED_ROOT/package.json")" = "$(oat --version)" &&
+  node "$SKILL_DIR/scripts/package-drift.mjs" --app "<docs-app-dir>" --versions "$OAT_INSTALLED_ROOT/assets/public-package-versions.json"
+```
+
+Never substitute registry latest or this target repo's package version. Missing
+bundle metadata, missing installed packages, or non-orderable versions (including
+prereleases) mean unverified, never an upgrade. The helper compares stable numeric
+version components: older installed packages are `drift`; equal versions are
+`current`; newer installed packages are `ahead`, with no upgrade command. For
+`ahead`, report that the running CLI is stale and ask the operator to update or
+select the intended CLI installation before re-analysis; do not recommend a docs
+package downgrade. `unverified` also has no package command and needs manual
+verification. Neither status authorizes a tooling update.
+
+The helper reports declared and installed versions, target versions and commands
+for orderable targets. If the app uses a different package manager, translate the
+command to its documented equivalent preserving package, exact target and
+dependency section. Cite the manifest, installed package path, bundle path and
+exact command. Report older-package drift as `tooling-update`, `approval: explicit`;
+describe unsupported scaffold repairs separately as `manual`. Markdown has no
+app-package drift check. This helper reads only and never upgrades anything.
+
 ### Step 7: Severity-Rate Findings
 
 Use these defaults:
@@ -485,6 +571,19 @@ Use these defaults:
 - `Medium`: incomplete `## Contents`, `overview.md` still in use, plugin/contributor guidance gaps, moderate duplication
 - `Low`: polish, wording, or organization improvements
 
+### Recommendation handoff
+
+Give every recommendation a unique stable ID (`R-001`, etc.) and
+`approval: explicit | default`; preserve IDs through review and never reuse a
+retired ID for a different change. `explicit` covers docs-package updates,
+restructure blocks and anything outside the Markdown scope (including authored
+IA decision/config writes). `default` covers ordinary in-scope content repairs.
+Missing evidence, `omit` and `ask_user` remain independent blockers regardless
+of approval class. Capture exact targets and commands; an explicit class is not
+permission to perform unsupported work. Apply's one input is this artifact plus
+a list of approved recommendation IDs. Blanket or unattended approval never
+covers explicit recommendations; apply reports skipped IDs with reasons.
+
 ### Step 8: Write Analysis Artifact
 
 Use `references/analysis-artifact-template.md`.
@@ -506,7 +605,8 @@ Populate the artifact with:
 - Accuracy verification verdicts for repo-checkable claims
 - Content opportunities for missing or thin docs coverage
 - Navigation/drift findings
-- Ordered recommendations
+- Information Architecture Fit and offline package drift
+- Ordered recommendations with stable IDs and approval classes
 - Exact evidence references for each finding and recommendation
 - Confidence for each recommendation
 - Progressive disclosure decisions (`inline`, `link_only`, `omit`, `ask_user`)

package/assets/skills/oat-docs-analyze/references/analysis-artifact-template.md

@@ -27,6 +27,39 @@ oat_analysis_commit: { commitHash }
 
 Do not copy private guidance contents or persist an IA decision from this report.
 
+## Information Architecture Fit
+
+- Authored decision and Information architecture section: {paths/lines or missing}
+- Config mirror: {preset, decision, tracks/principles, verification; agrees/conflicts}
+- Missing IA / conflicting authority: {ask_user recommendation ID or none}
+- Sidebar owner: {nav-sync / hand-authored / undeclared; Markdown: ignored}
+- Undeclared framework owner: {ask_user recommendation ID or none}
+
+| Declared reader/track                                    | Landing route and section reachability | Placement/coverage evidence               | Reader impact                                                  | Severity              |
+| -------------------------------------------------------- | -------------------------------------- | ----------------------------------------- | -------------------------------------------------------------- | --------------------- |
+| {Product / QA / consumer / agent / other declared track} | {exact links}                          | {sources; page purpose; missing coverage} | {blocked first success/verification, material detour, or none} | {High / Medium / N/A} |
+
+Assess root breadth and implementation-directory mirroring using reader evidence.
+Do not invent missing audiences or choose an IA without approval.
+
+## Offline Package Drift
+
+- Bundle metadata: {running CLI public-package-versions.json path or unverified}
+- Docs app manifest: {path; Markdown: not applicable}
+
+| Package                       | Declared / installed                | Bundled   | Status                                 | Exact upgrade command                                                          | Recommendation ID                                       |
+| ----------------------------- | ----------------------------------- | --------- | -------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------- |
+| {@open-agent-toolkit/docs-\*} | {range / actual version or missing} | {version} | {current / drift / ahead / unverified} | {drift only: helper upgrade command adapted to actual manager; otherwise none} | {drift only: R-NNN; approval: explicit; otherwise none} |
+
+Only older installed packages (`drift`) receive a package-upgrade command and
+stable recommendation ID with `approval: explicit`. `current` needs no tooling
+recommendation, even if the helper emits a reinstall command. For `ahead`, select
+or update the intended CLI installation, then re-analyze; do not recommend a docs
+package downgrade. `unverified` requires manual verification before a package
+recommendation.
+
+Unsupported app config/routes/scripts: {manual changes required; never automatic}.
+
 ## Summary
 
 - **Files evaluated:** {N}
@@ -270,14 +303,18 @@ canonical docs/config/examples.
 
 1. **{Action}** — {rationale}
    - Target: `{path}`
-   - Action Type: {create / update / move / scaffold / sync-nav}
+   - ID: {R-NNN; unique and stable}
+   - approval: {explicit | default}
+   - Action Type: {create / update / move / scaffold / sync-nav / record-ia / restructure / tooling-update / manual}
    - Evidence: {exact refs}
    - Confidence: {high | medium | low}
    - Disclosure: {inline | link_only | omit | ask_user}
    - Link Targets: {path or URL / N/A}
 2. **{Action}** — {rationale}
    - Target: `{path}`
-   - Action Type: {create / update / move / scaffold / sync-nav}
+   - ID: {R-NNN; unique and stable}
+   - approval: {explicit | default}
+   - Action Type: {create / update / move / scaffold / sync-nav / record-ia / restructure / tooling-update / manual}
    - Evidence: {exact refs}
    - Confidence: {high | medium | low}
    - Disclosure: {inline | link_only | omit | ask_user}
@@ -286,6 +323,9 @@ canonical docs/config/examples.
 
 ## Apply Contract
 
+- `oat-docs-apply` input is this artifact path plus approved recommendation IDs.
+- Every recommendation has a unique stable ID and approval: explicit | default.
+- Explicit items need individual approval by ID; blanket/unattended approval skips them and reports the reason.
 - `oat-docs-apply` may only implement recommendations backed by evidence in this artifact.
 - Findings based on contradicted claims must be resolved against cited repo sources before `oat-docs-apply` acts on them.
 - Generated artifacts must not be hand-edited by `oat-docs-apply`. If a