@open-agent-toolkit/cli 0.1.21 → 0.1.23

package/assets/docs/cli-utilities/index.md

@@ -7,23 +7,46 @@ description: Standalone adoption lane for general OAT CLI surfaces outside provi
 
 CLI Utilities is the OAT lane for the useful command surface that does not primarily belong to Provider Sync, Docs Tooling, or tracked workflow lifecycle execution.
 
-Use this section when you want bootstrap guidance, tool-pack lifecycle details, configuration help, and general-purpose command references.
+Use this section when you want bootstrap guidance, tool-pack lifecycle details, configuration help, and general-purpose command references. It covers general-purpose setup, configuration, pack-management, and diagnostic utilities that support the rest of the toolkit without being specific to provider sync, docs tooling, or tracked workflow execution.
 
-## What This Section Is
+## Contents
+
+- [CLI Bootstrap](bootstrap.md) - Foundational `oat init` guidance outside provider-sync-specific onboarding.
+- [Tool Packs and Installed Assets](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
+- [Configuration](configuration.md) - OAT configuration guidance across shared, local, user, and provider-sync surfaces.
+- [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
+
+## What Lives Here
 
 This section collects the command groups that help you initialize OAT, manage installed packs, inspect local or config state, and use the wider CLI without implying that you are adopting provider sync or tracked workflows.
 
+Examples include:
+
+- bootstrap and setup flows such as `oat init`
+- bundled pack management through `oat tools`
+- general configuration guidance
+- utility command groups for config, local state, diagnostics, and related inspection flows
+
 ## Who It's For
 
 - Users getting OAT set up in a repo
 - Teams managing installed tool packs and local config
 - People who need a general command map without diving into workflow lifecycle docs
 
+## When To Use This Section
+
+Use CLI Utilities when:
+
+- you are first setting up OAT in a repo
+- you need to install or update OAT packs
+- you are looking for configuration or local-state inspection help
+- you need the general CLI surface without committing to one of the deeper lanes yet
+
 ## Start Here
 
-- Read [Overview](overview.md) to see what command groups live here and how this section relates to the other adoption lanes.
 - Use [CLI Bootstrap](bootstrap.md) when you are starting with `oat init`.
 - Go to [Tool Packs](tool-packs.md) when you are managing bundled OAT packs and installed assets.
+- Read [Configuration](configuration.md) for config semantics, or [Config and Local State](config-and-local-state.md) for inspection and diagnostic command groups.
 
 ## Common Tasks
 
@@ -34,7 +57,6 @@ This section collects the command groups that help you initialize OAT, manage in
 
 ## Go Deeper
 
-- [Overview](overview.md) - What belongs in CLI Utilities and when to use this section.
 - [CLI Bootstrap](bootstrap.md) - Foundational `oat init` guidance outside provider-sync-specific onboarding.
 - [Tool Packs](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
 - [Configuration](configuration.md) - OAT configuration guidance.

package/assets/docs/contributing/documentation.md

@@ -12,6 +12,8 @@ Documentation should ship with the code it explains. This page covers the core d
 - Every documentation directory must contain an `index.md`.
 - Each `index.md` must include a `## Contents` section.
 - The `## Contents` section is the machine-readable local map for sibling pages and child directories.
+- 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.
 
 ## Local workflow
 
@@ -51,19 +53,23 @@ Documentation should ship with the code it explains. This page covers the core d
 
 - Keep docs aligned with the current repo behavior and current command surface.
 - Prefer cross-links over duplicated conceptual content.
-- When you add, remove, or rename docs pages, refresh the generated docs surface:
+- Use `oat-docs-authoring` for targeted OAT/Fumadocs docs edits; it delegates
+  universal page-quality guidance to `authoring-docs` and keeps local
+  navigation, generated-index, and validation expectations in scope.
+- When you add, remove, or rename docs pages in this Fumadocs app, refresh the generated Fumadocs root index. It is a generated file-tree manifest that should be checked against authored `docs/**/index.md` maps, not hand-edited:
 
   ```bash
   pnpm -w run cli -- docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
   ```
 
+- In MkDocs apps, use `oat docs nav sync` to refresh `mkdocs.yml` instead. Do not use MkDocs nav sync as the Fumadocs regeneration step.
 - 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 the docs surface index after adding or removing pages.
+- Regenerate or freshness-check the docs surface index after adding, removing, renaming, or reordering pages.
 
 ## Related Guides
 

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

@@ -92,6 +92,8 @@ Tab groups use the existing tab transform syntax:
 
 Standard fenced code blocks support syntax highlighting and optional file-title metadata.
 
+Use a language identifier on every opening fence. In this docs app, use `bash` for shell commands because the existing examples and repo scripts are Bash-oriented; use `sh` only when the command is intentionally POSIX-shell-specific.
+
 === "Syntax"
 
     ````text

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

@@ -46,9 +46,10 @@ Legacy pack-specific path:
 oat init tools docs
 ```
 
-The docs pack installs `oat-docs-analyze`, `oat-docs-apply`,
-`oat-agent-instructions-analyze`, and `oat-agent-instructions-apply`. For this
-quickstart, the docs pair is the part you need immediately.
+The docs pack installs `authoring-docs`, `oat-docs-authoring`,
+`oat-docs-analyze`, `oat-docs-apply`, `oat-agent-instructions-analyze`, and
+`oat-agent-instructions-apply`. For this quickstart, the authoring and docs
+analysis/apply skills are the parts you need immediately.
 
 ## 3. Scaffold the docs app
 
@@ -76,7 +77,7 @@ What the skill adds over the raw CLI:
 - **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 two-`index.md` 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`).
+- **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-gated: every post-patch self-ratchets off as CLI fixes land upstream. The skill's labeled markers (`<!-- FP-NN patch -->`) are how you find them later when the CLI catches up.
@@ -115,25 +116,32 @@ root `build:docs` script is available for docs-only builds. Use
 `--no-root-patch` to opt out, or `--dry-run` to preview the diff without
 writing it.
 
-## 3a. Migrating from MkDocs (optional)
+### 3c. Existing MkDocs content
 
-If you have an existing MkDocs site and want to switch to Fumadocs, use the
-migration command after scaffolding:
+Bootstrap is not the migration workflow. If you have an existing MkDocs site
+and want to switch to Fumadocs, treat that as a separate migration workstream.
+The CLI migration helper can convert common Markdown syntax and frontmatter:
 
 ```bash
 oat docs migrate --docs-dir docs --config mkdocs.yml --apply
 ```
 
-This converts MkDocs admonitions to GFM callouts and injects frontmatter
-metadata. Run without `--apply` first to preview changes.
+Run without `--apply` first to preview changes. For a full MkDocs-to-Fumadocs
+refactor, use the assigned migration handoff guide or project plan; do not make
+`oat-docs-bootstrap` own that migration.
 
 ## 4. Start authoring docs with the OAT contract
 
+Use `oat-docs-authoring` for targeted OAT/Fumadocs content edits or local
+restructuring. It uses `authoring-docs` for the portable documentation baseline
+and adds the OAT-specific navigation, generated-index, and validation contract.
+
 Core rules:
 
 - every docs directory should have an `index.md`
 - every `index.md` should include a `## Contents` section
 - the `## Contents` section should map sibling pages and immediate child directories
+- `## Contents` links should use `.md`-suffixed relative targets, including `subdir/index.md` for child directories
 
 For **MkDocs** apps, regenerate navigation after adding or moving pages:
 
@@ -141,16 +149,18 @@ For **MkDocs** apps, regenerate navigation after adding or moving pages:
 oat docs nav sync --target-dir apps/my-docs
 ```
 
-For **Fumadocs** apps, the docs index is generated automatically via
-`predev`/`prebuild` hooks. You can also run it manually:
+For **Fumadocs** apps, the app-root docs index manifest is generated from the
+Markdown file tree automatically via `predev`/`prebuild` hooks. You can also
+run it manually:
 
 ```bash
 oat docs generate-index --docs-dir docs
 ```
 
 The generated app-root `index.md` is machine-owned and now starts with an
-`AUTOGENERATED` warning comment. Edit authored pages under `docs/`, not the
-generated root index.
+`AUTOGENERATED` warning comment. Edit authored pages and `## Contents` maps
+under `docs/`, then compare the generated manifest against those maps when
+checking freshness.
 
 ## 5. Analyze the docs surface
 
@@ -193,7 +203,7 @@ Important:
 1. `oat init --scope project`
 2. `oat tools install docs`
 3. `oat docs init --app-name my-docs`
-4. (optional) `oat docs migrate --docs-dir docs --config mkdocs.yml --apply`
+4. (optional) handle MkDocs migration as a separate workstream; use `oat docs migrate --docs-dir docs --config mkdocs.yml --apply` only for the syntax/frontmatter helper
 5. Author docs with `index.md` + `## Contents`
 6. `oat docs nav sync --target-dir apps/my-docs` (MkDocs) or `oat docs generate-index` (Fumadocs)
 7. `/oat-docs-analyze`

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

@@ -1,6 +1,6 @@
 ---
 title: Docs App Commands
-description: 'Docs scaffolding CLI surface for Fumadocs/MkDocs, migration, index generation, and nav sync.'
+description: 'Docs scaffolding CLI surface for Fumadocs/MkDocs, migration helpers, Fumadocs index generation, and MkDocs nav sync.'
 ---
 
 # Docs App Commands
@@ -11,20 +11,29 @@ and **MkDocs Material**.
 
 ## Quick Look
 
-- What it does: documents the docs-specific CLI surface for scaffolding apps, migrating markdown, generating indexes, and syncing navigation.
+- What it does: documents the docs-specific CLI surface for scaffolding apps, migrating markdown, generating Fumadocs app-root index manifests, and syncing MkDocs navigation.
 - When to use it: when you already know you are working on a docs surface and need the exact command-level behavior.
 - Primary commands: `oat docs init`, `oat docs migrate`, `oat docs generate-index`, `oat docs nav sync`
 
 ## Command surface
 
-| Command                   | Purpose                                                                              |
-| ------------------------- | ------------------------------------------------------------------------------------ |
-| `oat docs init`           | Scaffold a new docs app (Fumadocs or MkDocs).                                        |
-| `oat docs migrate`        | Convert MkDocs admonitions to GFM callouts and inject frontmatter.                   |
-| `oat docs generate-index` | Generate a docs index from the markdown file tree.                                   |
-| `oat docs nav sync`       | Regenerate `mkdocs.yml` navigation from directory `index.md` `## Contents` sections. |
-| `oat docs analyze`        | CLI entrypoint that points users to the `oat-docs-analyze` skill.                    |
-| `oat docs apply`          | CLI entrypoint that points users to the `oat-docs-apply` skill.                      |
+| Command                   | Purpose                                                                       |
+| ------------------------- | ----------------------------------------------------------------------------- |
+| `oat docs init`           | Scaffold a new docs app (Fumadocs or MkDocs).                                 |
+| `oat docs migrate`        | Convert MkDocs admonitions to GFM callouts and inject frontmatter.            |
+| `oat docs generate-index` | Generate a Fumadocs app-root docs index manifest from the Markdown file tree. |
+| `oat docs nav sync`       | Regenerate MkDocs `mkdocs.yml` navigation from directory `index.md` maps.     |
+| `oat docs analyze`        | CLI entrypoint that points users to the `oat-docs-analyze` skill.             |
+| `oat docs apply`          | CLI entrypoint that points users to the `oat-docs-apply` skill.               |
+
+## Which Generation Command To Run
+
+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`.
+- MkDocs apps use `oat docs nav sync` to regenerate the `nav:` block in `mkdocs.yml` from authored directory `index.md` `## Contents` sections.
+
+Both frameworks keep authored `## Contents` sections as the source of local discovery. The generated artifact differs by framework.
 
 ## `oat docs init`
 
@@ -109,9 +118,10 @@ oat docs migrate --docs-dir docs --config mkdocs.yml --apply
 
 ## `oat docs generate-index`
 
-Use `oat docs generate-index` to produce a markdown index from the docs file
-tree. The generated index lists all pages with titles and descriptions, organized
-by directory structure.
+Use `oat docs generate-index` to produce a generated Markdown manifest from the
+docs file tree. In Fumadocs apps this is the app-root `index.md`, outside the
+authored `docs/` source tree. The generated index lists all pages with titles
+and descriptions, organized by directory structure.
 
 Key behavior:
 
@@ -121,6 +131,7 @@ Key behavior:
 - outputs to app root (`index.md`) by default, not inside the docs directory
 - updates `documentation.index` in `.oat/config.json`
 - 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
 
 Supported flags:
@@ -139,11 +150,13 @@ script hooks.
 
 ## `oat docs nav sync`
 
-Use nav sync after adding, removing, or renaming docs pages.
+Use nav sync in MkDocs apps after adding, removing, or renaming docs pages.
 
 The command reads only the reserved `## Contents` section from each directory
 `index.md` and regenerates the `nav:` block in `mkdocs.yml`.
 
+For Fumadocs apps, regenerate the root markdown manifest with `oat docs generate-index` instead.
+
 Example:
 
 ```bash

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

@@ -7,7 +7,13 @@ description: Standalone adoption lane for docs app setup, docs commands, and doc
 
 Docs Tooling is the OAT lane for setting up, maintaining, and restructuring a documentation surface with OAT.
 
-Use this section when you are adopting the docs app workflow in a repo, maintaining generated navigation, or using the analyze/apply docs workflows.
+Use this section when you are adopting the docs app workflow in a repo, maintaining generated navigation, or using the analyze/apply docs workflows. OAT supports both Fumadocs and MkDocs: the site framework changes the surrounding app setup and generated artifacts, but the underlying documentation contract stays centered on `index.md` and `## Contents`.
+
+## Contents
+
+- [Add Docs to a New Repo](add-docs-to-a-repo.md) - Bootstrap a docs app and adopt the docs workflow in a repo.
+- [Docs App Commands](commands.md) - Docs CLI surface for init, migration, index generation, and nav sync.
+- [Docs Workflows](workflows.md) - How the docs CLI helpers pair with analyze/apply workflows.
 
 ## What This Section Is
 
@@ -21,9 +27,9 @@ This section explains how OAT supports docs surfaces, how the index contract wor
 
 ## Start Here
 
-- Read [Overview](overview.md) for the docs-tooling model and where Fumadocs versus MkDocs matters.
 - Use [Add Docs to a Repo](add-docs-to-a-repo.md) when you are bootstrapping a docs surface.
 - Go to [Commands](commands.md) when you already have a docs app and need the CLI surface.
+- Use [Workflows](workflows.md) when you want analysis-backed restructuring rather than ad hoc manual edits.
 
 ## Common Tasks
 
@@ -34,7 +40,7 @@ This section explains how OAT supports docs surfaces, how the index contract wor
 
 ## Go Deeper
 
-- [Overview](overview.md) - What docs tooling is for and how the docs contract fits together.
 - [Add Docs to a Repo](add-docs-to-a-repo.md) - Bootstrap a docs app and adopt the docs workflow in a repo.
 - [Commands](commands.md) - Docs CLI surface for init, migration, index generation, and nav sync.
 - [Workflows](workflows.md) - How the docs CLI helpers pair with analyze/apply workflows.
+- [Docs Index Contract](../reference/docs-index-contract.md) - Framework-neutral `index.md` rules plus Fumadocs and MkDocs generation notes.

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

@@ -17,12 +17,18 @@ Install the workflow skills with `oat tools install docs` (preferred) or
 
 - `oat docs init` scaffolds a docs app (Fumadocs or MkDocs)
 - `oat docs migrate` converts MkDocs admonitions to GFM callouts and injects frontmatter
-- `oat docs generate-index` generates a docs index from the markdown file tree
-- `oat docs nav sync` regenerates mkdocs.yml nav from `index.md` `## Contents` sections
+- `oat docs generate-index` generates a Fumadocs app-root docs index manifest from the Markdown file tree
+- `oat docs nav sync` regenerates MkDocs `mkdocs.yml` nav from `index.md` `## Contents` sections
 - `oat docs analyze` and `oat docs apply` expose the workflow surface in CLI help
 
 ### Skills
 
+- `authoring-docs` is the provider-agnostic baseline for evidence-first
+  technical documentation: page types, information architecture, category
+  guidance, templates, and review rubrics
+- `oat-docs-authoring` layers the OAT/Fumadocs docs-app contract on top of
+  `authoring-docs` for targeted authoring, restructuring, link repair, and
+  local navigation maintenance inside an existing OAT docs app
 - `oat-docs-bootstrap` is the guided onramp for adding a docs app to a repo —
   wraps `oat docs init` with preflight detection, richer input gathering (site
   name distinct from package name), labeled post-patches for open CLI gaps,
@@ -55,15 +61,16 @@ skills.
 ## Typical flow
 
 1. Bootstrap a docs app with `oat-docs-bootstrap` (preferred — guided, includes post-scaffold patches and walkthrough) or `oat docs init` directly (CLI-only / non-interactive workflows)
-2. (Optional) If migrating from MkDocs: `oat docs migrate --docs-dir docs --config mkdocs.yml --apply`
-3. Author docs so every directory has an `index.md` with a `## Contents` section
-4. Keep local `## Contents` sections current
-5. Sync navigation:
+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/Fumadocs authoring work, with `authoring-docs` as the universal documentation-quality baseline
+4. Author docs so every directory has an `index.md` with a `## Contents` section
+5. Keep local `## Contents` sections current
+6. Refresh generated artifacts:
    - **MkDocs:** `oat docs nav sync`
    - **Fumadocs:** `oat docs generate-index` (runs automatically via `predev`/`prebuild` hooks)
-6. Run `oat-docs-analyze`; by default it verifies the generated analysis artifact
+7. Run `oat-docs-analyze`; by default it verifies the generated analysis artifact
    through `workflow.autoArtifactReview.analysis`
-7. Review the artifact and run `oat-docs-apply`
+8. Review the artifact and run `oat-docs-apply`
 
 ## Progressive disclosure
 

package/assets/docs/guide/index.md

@@ -9,6 +9,14 @@ This page is now a compatibility router.
 
 The old catch-all User Guide is being split into clearer adoption lanes so new users can choose the part of OAT that matches what they actually need.
 
+## Contents
+
+- [Core Concepts](concepts.md) - High-level mental model while concept material is being redistributed.
+
+## Status
+
+This guide bucket remains visible so older links have a stable landing page. New docs should go into the canonical top-level sections below instead of adding more pages under `guide/`.
+
 ## Canonical Sections
 
 - [Provider Sync](../provider-sync/index.md) - Provider interoperability, drift, sync, and config behavior.

package/assets/docs/index.md

@@ -16,6 +16,7 @@ OAT is organized as three distinct capabilities that can be used together or ind
 ## Contents
 
 - [Quickstart](quickstart.md) - Canonical Start Here page for choosing the right OAT adoption path.
+- [User Guide](guide/index.md) - Legacy compatibility router for old guide links while content continues moving into the canonical sections below.
 - [Provider Sync](provider-sync/index.md) - Canonical section for provider interoperability, drift management, and canonical-to-provider sync.
 - [Agentic Workflows](workflows/index.md) - Canonical section for tracked project workflows, ideas, lifecycle execution, and workflow-oriented skills.
 - [Docs Tooling](docs-tooling/index.md) - Canonical section for docs app setup, docs commands, and docs maintenance workflows.
@@ -54,6 +55,7 @@ That page is the canonical path-selection guide. Use it to choose whether you ne
 ## Where To Go Next
 
 - New to OAT: [Quickstart](quickstart.md)
+- Following an older guide link: [User Guide](guide/index.md)
 - Need canonical-to-provider sync: [Provider Sync](provider-sync/index.md)
 - Need tracked project execution: [Agentic Workflows](workflows/index.md)
 - Need docs app or docs maintenance tooling: [Docs Tooling](docs-tooling/index.md)

package/assets/docs/provider-sync/index.md

@@ -9,21 +9,46 @@ Provider Sync is the OAT lane for keeping a canonical rules-and-skills layout in
 
 You can adopt this layer on its own. It does not require tracked OAT projects, and it is the right starting point when you mainly want interoperability and drift control.
 
+In practice, you edit the canonical layout in `.agents/` and `.oat/`, then let OAT generate or reconcile provider-specific views for Claude Code, Cursor, Copilot, Gemini, Codex, and other supported providers.
+
+## Contents
+
+- [Provider Interop Commands](commands.md) - `oat status`, `oat sync`, and `oat providers ...` behavior.
+- [Sync Config](config.md) - Provider config model, enablement, and scope semantics.
+- [Instruction Sync](instruction-sync.md) - Project-scoped `AGENTS.md` / `CLAUDE.md` validation, repair, and Claude-only adoption.
+- [Manifest and Drift](manifest-and-drift.md) - How OAT tracks synced state, stray files, and adoption decisions.
+- [Providers](providers.md) - Provider-specific mappings, capabilities, and path conventions.
+- [Provider Interop CLI Scope and Surface](scope-and-surface.md) - Canonical assets, provider views, scopes, and the sync surface area.
+
 ## What This Section Is
 
 This section explains how OAT treats `.agents/` and `.oat/` as the source of truth, how provider views are derived from those canonical assets, and how sync/adoption workflows keep everything aligned.
 
+## What OAT Treats As Canonical
+
+- canonical skills, agents, and rules under `.agents/`
+- sync state and related metadata under `.oat/`
+- provider-specific files as derived views unless they are explicitly adopted back into canonical form
+
 ## Who It's For
 
 - Teams adopting OAT primarily for provider interoperability
 - Users who want one canonical asset layout instead of hand-maintaining provider copies
 - Repos that need drift detection, adoption flows, and explicit sync control
 
+## Typical Flow
+
+1. Run `oat init` to create the base OAT layout and setup state.
+2. Inspect current sync state with `oat status`.
+3. Adjust provider enablement with `oat providers ...` if needed.
+4. Run `oat sync` to materialize provider views from canonical assets.
+5. Re-run `oat status` after edits to confirm whether anything drifted or needs adoption.
+
 ## Start Here
 
-- Read [Overview](overview.md) for the plain-language model and the first-sync flow.
 - Use [CLI Bootstrap](../cli-utilities/bootstrap.md) when you are bootstrapping OAT and want the sync-relevant setup path.
 - Go to [Commands](commands.md) once you are actively using `oat status`, `oat sync`, and `oat providers`.
+- Read [Scope and Surface](scope-and-surface.md) when you need the canonical/provider-view mental model.
 
 ## Common Tasks
 
@@ -35,7 +60,6 @@ This section explains how OAT treats `.agents/` and `.oat/` as the source of tru
 
 ## Go Deeper
 
-- [Overview](overview.md) - What provider sync is, when to use it, and what a typical sync loop looks like.
 - [CLI Bootstrap](../cli-utilities/bootstrap.md) - Foundational setup before first sync.
 - [Scope and Surface](scope-and-surface.md) - Canonical assets, provider views, scopes, and the sync surface area.
 - [Commands](commands.md) - `oat status`, `oat sync`, and `oat providers ...` behavior.

package/assets/docs/reference/cli-reference.md

@@ -20,21 +20,36 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 - [Workflow & Projects](../workflows/projects/index.md) - Project lifecycle, artifacts, reviews, PR flow, and state-machine docs.
 - [Repository PR Comment Analysis](../workflows/projects/repo-analysis.md) - Detailed `oat repo pr-comments ...` behavior.
 
+## Full CLI Reference Expansion Path
+
+Keep this page as the command-family map. Fuller command coverage should live either in the owning section for a command family or in generated/semi-generated reference pages that link back here.
+
+Each full command reference should include:
+
+- exact arguments, flags, defaults, aliases, and mutually exclusive options
+- output examples, including `--json` shapes where the CLI supports JSON
+- exit behavior for success, validation errors, missing state, and non-interactive blockers
+- side effects such as file writes, generated artifacts, config mutations, branch/commit behavior, and network calls
+- non-interactive usage guidance, including required flags and scripting-safe forms
+- source or test references for behavior that is easy to drift, marking unknown exit-code behavior as unknown instead of inventing a contract
+
+The first practical expansion path is to keep improving the existing owners: [Docs App Commands](../docs-tooling/commands.md), [Provider Interop Commands](../provider-sync/commands.md), [Config and Local State](../cli-utilities/config-and-local-state.md), [Tool Packs](../cli-utilities/tool-packs.md), [Workflow & Projects](../workflows/projects/index.md), and [Repository PR Comment Analysis](../workflows/projects/repo-analysis.md).
+
 ## Command Groups
 
-| Command group                                   | What it covers                                                                                                                          | Go deeper                                                                      |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| `oat init`                                      | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.                                                     | [CLI Bootstrap](../cli-utilities/bootstrap.md)                                 |
-| `oat tools ...`                                 | Install, inspect, update, and remove bundled OAT tool packs and assets.                                                                 | [Tool Packs](../cli-utilities/tool-packs.md)                                   |
-| `oat pjm ...`                                   | Initialize the project-management repo-reference surface after installing the project-management pack.                                  | [Install vs. initialize](../cli-utilities/tool-packs.md#install-vs-initialize) |
-| `oat backlog ...` / `oat local ...`             | File-backed backlog helpers, local path sync, and local-only operational support.                                                       | [Config and Local State](../cli-utilities/config-and-local-state.md)           |
-| `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                    | [Config and Local State](../cli-utilities/config-and-local-state.md)           |
-| `oat state ...` / `oat index ...` / `internal`  | Repo dashboard refresh, repo indexing, validation helpers, and diagnostics.                                                             | [Config and Local State](../cli-utilities/config-and-local-state.md)           |
-| `oat docs ...`                                  | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints.                                               | [Docs Tooling Commands](../docs-tooling/commands.md)                           |
-| `oat status` / `oat sync` / `oat providers ...` | Provider sync, drift inspection, provider configuration, and adoption behavior.                                                         | [Provider Sync](../provider-sync/index.md)                                     |
+| Command group                                   | What it covers                                                                                                                                            | Go deeper                                                                      |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `oat init`                                      | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.                                                                       | [CLI Bootstrap](../cli-utilities/bootstrap.md)                                 |
+| `oat tools ...`                                 | Install, inspect, update, and remove bundled OAT tool packs and assets.                                                                                   | [Tool Packs](../cli-utilities/tool-packs.md)                                   |
+| `oat pjm ...`                                   | Initialize the project-management repo-reference surface after installing the project-management pack.                                                    | [Install vs. initialize](../cli-utilities/tool-packs.md#install-vs-initialize) |
+| `oat backlog ...` / `oat local ...`             | File-backed backlog helpers, local path sync, and local-only operational support.                                                                         | [Config and Local State](../cli-utilities/config-and-local-state.md)           |
+| `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                                      | [Config and Local State](../cli-utilities/config-and-local-state.md)           |
+| `oat state ...` / `oat index ...` / `internal`  | Repo dashboard refresh, repo indexing, validation helpers, and diagnostics.                                                                               | [Config and Local State](../cli-utilities/config-and-local-state.md)           |
+| `oat docs ...`                                  | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints.                                                                 | [Docs Tooling Commands](../docs-tooling/commands.md)                           |
+| `oat status` / `oat sync` / `oat providers ...` | Provider sync, drift inspection, provider configuration, and adoption behavior.                                                                           | [Provider Sync](../provider-sync/index.md)                                     |
 | `oat project ...` / `oat cleanup ...`           | Project scaffolding, active-project status inspection, tracked-project listing, plan validation, archive creation, and project/artifact cleanup commands. | [Workflow & Projects](../workflows/projects/index.md)                          |
-| `oat review ...`                                | Review artifact discovery helpers, including latest-review resolution for project and ad-hoc review flows.                             | [Reviews](../workflows/projects/reviews.md)                                    |
-| `oat repo ...`                                  | Repository-level workflows such as archive sync and PR-comment analysis.                                                                 | [Repository Analysis](../workflows/projects/repo-analysis.md)                  |
+| `oat review ...`                                | Review artifact discovery helpers, including latest-review resolution for project and ad-hoc review flows.                                                | [Reviews](../workflows/projects/reviews.md)                                    |
+| `oat repo ...`                                  | Repository-level workflows such as archive sync and PR-comment analysis.                                                                                  | [Repository Analysis](../workflows/projects/repo-analysis.md)                  |
 
 Notable commands introduced in the current CLI surface:
 

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

@@ -1,17 +1,21 @@
 ---
 title: Docs Index Contract
-description: 'Navigation generation contract: index.md format and authoring guidance.'
+description: 'Docs source contract: authored index.md maps, generated Fumadocs manifests, and MkDocs nav sync.'
 ---
 
 # Docs Index Contract
 
-OAT docs navigation is generated from each directory `index.md`, not from hand-maintained `mkdocs.yml` trees.
+OAT docs navigation starts from authored `docs/**/index.md` files. Each `## Contents` section is the local source of truth for sibling pages and child directories. Generated artifacts are derived from docs source and should not be edited directly. The framework determines which generated artifact is produced, but the authored `## Contents` contract is the same for humans and agents.
 
 ## Rules
 
 - Every documentation directory must contain an `index.md`.
 - Every `index.md` must include a `## Contents` section.
-- The `## Contents` section is the only machine-readable source used by `oat docs nav sync`.
+- 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 MkDocs, run `oat docs nav sync` after adding, removing, renaming, or reordering pages. It regenerates `mkdocs.yml` from authored `## Contents` maps and preserves the order declared in each local map.
 
 ## `## Contents` format
 
@@ -28,23 +32,53 @@ Notes:
 
 - Links after `## Contents` can include short human-readable descriptions.
 - Child directories should link to their `index.md`.
-- Prose outside `## Contents` is ignored by nav generation and remains freeform.
+- 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.
 
-## Navigation generation
+## Fumadocs Generation
 
-`oat docs nav sync --target-dir <docs-app-dir>` walks the docs tree from `docs/index.md` downward and regenerates `mkdocs.yml` `nav` entries from the discovered `index.md` files.
+For this Fumadocs app, rendered page routing and sidebar data come from the Fumadocs file/source pipeline over `apps/oat-docs/docs`. The generated root manifest, `apps/oat-docs/index.md`, is an inventory for agents and tooling; it is not the rendered sidebar/page-tree source.
 
-Generated behavior:
+`oat docs generate-index` walks the Markdown file tree under `docs/` and writes the app-root generated manifest. The app scripts run:
+
+```bash
+fumadocs-mdx
+pnpm -w run cli -- docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
+```
+
+`oat docs generate-index` rewrites the generated root manifest from the docs source tree. It is the command to use after adding, removing, or retiring pages in this Fumadocs app. Do not use `oat docs nav sync` as the Fumadocs regeneration step.
+
+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.
+- Generated manifests should carry an autogen warning and are rewritten by `predev` / `prebuild`.
+
+## MkDocs Nav Sync
+
+MkDocs apps use `oat docs nav sync --target-dir <docs-app-dir>` to walk the docs tree from `docs/index.md` downward and regenerate the `nav:` block in `mkdocs.yml` from discovered directory `index.md` files.
+
+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.
+- `mkdocs.yml` may contain other configuration, but its `nav:` block is derived from authored `## Contents`.
+
+## Generated-file boundaries
+
+- Edit authored files under `docs/`, especially the nearest `index.md` and `## Contents`.
+- Do not hand-edit a Fumadocs app-root generated `index.md`; regenerate it from the docs source tree.
+- Do not hand-maintain MkDocs `nav:` entries when the local workflow uses `oat docs nav sync`.
+- If a Fumadocs generated manifest lists pages that are missing from authored `## Contents`, treat that as authored-source drift or intentional generator-inventory behavior to verify before relying on the generated file as navigation evidence.
 
 ## Authoring guidance
 
 - Use `index.md` as the local discovery surface for humans and agents.
 - Add a short topic description next to each link so agents can choose the right file without opening every page.
-- Update `## Contents` whenever you add, remove, or rename docs files in a directory.
+- Update `## Contents` whenever you add, remove, rename, or reorder docs files in a directory.
+- Regenerate the framework-specific artifact after structural changes: `generate-index` for Fumadocs root manifests, `nav sync` for MkDocs `mkdocs.yml`.
+- Refresh or freshness-check the generated artifact before committing structural docs changes.
 
 ## If You Are Trying To...
 

package/assets/docs/reference/index.md

@@ -13,7 +13,7 @@ Contributor how-to material now lives under `contributing/`, and user-facing rou
 
 - [CLI Reference](cli-reference.md) - Shallow map of the OAT command surface with links to owning sections.
 - [File Locations](file-locations.md) - Where core OAT files, assets, and artifacts live.
-- [Docs Index Contract](docs-index-contract.md) - Rules for directory `index.md` files and reserved `## Contents` sections.
+- [Docs Index Contract](docs-index-contract.md) - Authored `index.md` maps, `.md` links, generated Fumadocs manifests, and MkDocs nav sync boundaries.
 - [OAT Directory Structure](oat-directory-structure.md) - Canonical `.oat/` tree map and the role of each major directory.
 - [Troubleshooting](troubleshooting.md) - Common issues, diagnostics, and remediation guidance.