@open-agent-toolkit/cli 0.0.10

package/assets/docs/contributing/skills.md

@@ -0,0 +1,68 @@
+---
+title: Writing Skills
+description: 'Contributor guide to authoring OAT skills, including runtime contracts, governance, and where to start.'
+---
+
+# Writing Skills
+
+Use this page when you are creating or updating OAT skills in `.agents/skills`.
+
+Skill behavior is defined by frontmatter plus the process contract in each `SKILL.md`. The goal is to make lifecycle behavior explicit, reviewable, and reusable across sessions.
+
+## Where Skills Live
+
+- Canonical skills live in `.agents/skills`
+- `AGENTS.md` is the session-facing registry and should stay aligned with skill frontmatter
+- OAT project and review artifacts should reference skill names consistently
+
+## Authoring Priorities
+
+- Make the mode and purpose explicit.
+- Keep prerequisites and expected artifacts concrete.
+- Spell out blocked vs allowed activities for state-advancing skills.
+- Define user-facing progress indicators for longer workflows.
+- Keep output obligations explicit so downstream skills and users know what changed.
+
+## Contract components
+
+- Mode assertion (purpose, blocked/allowed activities)
+- Preconditions and required artifacts
+- User-facing progress indicator expectations
+- Output obligations
+- Escalation/guardrail behavior
+
+## Frontmatter fields in active use
+
+- `name`
+- `description`
+- `version`
+- `disable-model-invocation`
+- `user-invocable`
+- `allowed-tools`
+
+## Practical Authoring Flow
+
+1. Decide whether you are adding a general reusable skill or an OAT-specific lifecycle skill.
+2. Add or update the skill under `.agents/skills/<name>/SKILL.md`.
+3. Keep the `AGENTS.md` skills registry synchronized with the new frontmatter.
+4. Update related docs or lifecycle references if the skill changes user-visible behavior.
+
+## Governance rules
+
+- Prefer skill-first invocation language.
+- Keep `AGENTS.md` skills table synchronized with `.agents/skills`.
+- Require explicit user approval for destructive or state-advancing transitions.
+
+## Recommended Starting Points
+
+- Use `create-oat-skill` when the new skill belongs to an OAT lifecycle or maintenance flow.
+- Use `create-agnostic-skill` when you want a reusable workflow skill that is not OAT-specific.
+- Use existing lifecycle skills as examples for progress banners, prerequisites, and artifact updates.
+
+## Reference artifacts
+
+- `.agents/skills/*/SKILL.md`
+- `AGENTS.md`
+- `.agents/skills/oat-project-implement/SKILL.md`
+- `.agents/skills/oat-project-complete/SKILL.md`
+- `.agents/skills/oat-project-review-receive/SKILL.md`

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

@@ -0,0 +1,211 @@
+---
+title: CLI Reference
+description: 'Scannable reference for the current OAT CLI surface, with links to the deeper guide pages for each command family.'
+---
+
+# CLI Reference
+
+Use this page when you need a quick map of the OAT CLI rather than the full command-by-command docs. It is intentionally shallow: each section points to the guide page that owns the detailed behavior.
+
+The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oat tools`, docs commands, and repo-analysis commands without adopting the full project workflow.
+
+## Contents
+
+- [Getting Started](getting-started.md) - Bootstrap a repo with `oat init`, guided setup, and initial provider adoption.
+- [Tool Packs](tool-packs.md) - Install, update, inspect, and remove bundled OAT skills and agents.
+- [Documentation Commands](documentation/commands.md) - Docs app scaffolding, migration, index generation, and nav sync.
+- [Provider Sync](provider-sync/index.md) - Sync behavior, provider capabilities, config, and drift management.
+- [Workflow & Projects](workflow/index.md) - Project lifecycle, artifacts, reviews, PR flow, and state-machine docs.
+- [Repository Analysis](workflow/repo-analysis.md) - Detailed `oat repo pr-comments ...` behavior.
+
+## Command Groups
+
+| Command group                                          | What it covers                                                                            | Go deeper                                           |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `oat init`                                             | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.       | [Getting Started](getting-started.md)               |
+| `oat tools ...`                                        | Install, inspect, update, and remove bundled OAT tool packs and assets.                   | [Tool Packs](tool-packs.md)                         |
+| `oat backlog ...`                                      | Generate backlog IDs and rebuild the managed file-backed backlog index.                   | See sections below                                  |
+| `oat config ...`                                       | Inspect resolved config values, update supported keys, and discover config ownership.     | See sections below                                  |
+| `oat docs ...`                                         | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints. | [Documentation Commands](documentation/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, execution mode, and project/artifact cleanup commands.               | [Workflow & Projects](workflow/index.md)            |
+| `oat repo ...`                                         | Repository-level analysis workflows, currently centered on PR comments.                   | [Repository Analysis](workflow/repo-analysis.md)    |
+| `oat state ...` / `oat index ...` / `oat internal ...` | Repo dashboard refresh, repo indexing, and internal validation helpers.                   | See sections below                                  |
+
+## Bootstrap and Setup
+
+### `oat init`
+
+Use `oat init` to establish the canonical OAT directory layout, sync config, provider manifest state, and optional setup hooks.
+
+Key behavior:
+
+- initializes project- or user-scope OAT directories idempotently
+- can detect and adopt provider strays during setup
+- supports guided setup for tool packs, local paths, and provider sync
+- prepares the repo for later `oat status`, `oat sync`, `oat doctor`, and workflow usage
+
+See [Getting Started](getting-started.md) for the full setup flow.
+
+## Tool Management and Local State
+
+### `oat tools ...`
+
+Use the `oat tools` group to manage bundled OAT assets:
+
+- `oat tools list` - list installed tools, versions, pack membership, and update state
+- `oat tools info <name>` - inspect one installed skill or agent
+- `oat tools outdated` - show only assets with available updates
+- `oat tools install` - install bundled packs such as `core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, or `research`
+- `oat tools update` - update a named tool, a whole pack, or everything
+- `oat tools remove` - remove installed assets
+
+Mutation commands auto-run provider sync unless you pass `--no-sync`.
+
+See [Tool Packs](tool-packs.md) for the pack lifecycle and compatibility notes.
+
+### `oat backlog ...`
+
+Use the `oat backlog` group when you want direct CLI support for the file-backed backlog under `.oat/repo/reference/backlog/`.
+
+- `oat backlog init` - scaffold `.oat/repo/reference/backlog/` with starter files and directories for a fresh repo
+- `oat backlog generate-id <filename>` - generate a unique backlog ID from a filename seed
+- `oat backlog generate-id <filename> --created-at <timestamp>` - generate a reproducible ID for a known creation timestamp
+- `oat backlog regenerate-index` - rebuild the managed backlog index table from item frontmatter
+
+Run `oat backlog init` first when the local backlog scaffold does not exist yet in a fresh repo. This command group is primarily used by the `oat-pjm-*` project-management skills, but it is also available directly when you need to inspect or repair backlog metadata by hand.
+
+### `oat local ...`
+
+`oat local` manages local-only, gitignored paths that still need to follow you between the main repo and worktrees.
+
+Common examples:
+
+- `.oat/ideas/`
+- `.oat/**/reviews/archived/`
+
+Available commands:
+
+- `oat local status` - show whether configured local paths exist and are gitignored
+- `oat local apply` - write the managed `.gitignore` section for configured paths
+- `oat local sync` - copy local paths between the main repo and a worktree
+- `oat local add` / `oat local remove` - maintain the `localPaths` config entries
+
+Use this when you want archived review history or idea scratchpads to persist locally without being committed.
+
+### `oat config ...`
+
+Use `oat config` for repo runtime config inspection and supported key mutation.
+
+- `oat config get <key>` - read one resolved config value
+- `oat config set <key> <value>` - update a supported shared or repo-local key
+- `oat config list` - show the resolved command-surface values with source information
+- `oat config describe` - list supported config surfaces and keys across shared repo, repo-local, user, and sync/provider config
+- `oat config describe <key>` - show file location, scope, default, mutability, and owning command for one key
+
+Archive lifecycle settings live here as shared repo config:
+
+- `archive.s3Uri`
+- `archive.s3SyncOnComplete`
+- `archive.summaryExportPath`
+
+When archive settings are configured, completion uploads dated archive snapshots to S3 and exports dated summary snapshots into the configured summary reference directory.
+
+Use the reference pages for file ownership and schema details:
+
+- [File Locations](../reference/file-locations.md)
+- [`.oat` Directory Structure](../reference/oat-directory-structure.md)
+
+## Instruction Integrity
+
+### `oat instructions`
+
+These commands validate and repair pointer integrity between `AGENTS.md` and sibling `CLAUDE.md` files.
+
+- `oat instructions validate` - read-only integrity check
+- `oat instructions sync` - preview or apply pointer repairs
+
+Use this command group when instruction files drift after manual edits or generated updates.
+
+## Docs Commands
+
+### `oat docs ...`
+
+The docs command group covers:
+
+- `oat docs init` - scaffold a docs app for Fumadocs or MkDocs
+- `oat docs migrate` - convert MkDocs markdown patterns to Fumadocs-friendly markdown
+- `oat docs generate-index` - regenerate the generated app-root docs index
+- `oat docs nav sync` - rebuild MkDocs navigation from `index.md` `## Contents`
+- `oat docs analyze` / `oat docs apply` - CLI entrypoints for the docs workflow skills
+
+See [Documentation Commands](documentation/commands.md) for framework-specific behavior and flags.
+
+## Provider Sync Commands
+
+### `oat status`, `oat sync`, and `oat providers ...`
+
+These commands manage the relationship between canonical OAT assets and provider-specific views.
+
+- `oat status` - inspect sync and drift state
+- `oat sync` - write provider views from canonical assets
+- `oat providers list` / `inspect` / `set` - inspect providers and control enablement
+
+Use [Provider Sync](provider-sync/index.md) for the full model, including scope, manifest, config, and safety behavior.
+
+## Workflow and Project Commands
+
+### `oat project ...`
+
+Project commands are the CLI entrypoint into the OAT lifecycle.
+
+- `oat project new <name>` - create a new project in spec-driven, quick, or import mode
+- `oat project open <name>` - activate an existing project
+- `oat project set-mode <mode>` - switch implementation between `single-thread` and `subagent-driven`
+- `oat project archive sync` - sync the latest dated remote snapshot for each archived project from the configured S3 archive into `.oat/projects/archived/`
+- `oat project archive sync <project-name>` - sync the latest dated remote snapshot for one archived project into `.oat/projects/archived/<project-name>/`
+
+### `oat cleanup ...`
+
+Cleanup commands handle lifecycle drift and stale artifacts:
+
+- `oat cleanup project` - reconcile project pointers and lifecycle state
+- `oat cleanup artifacts` - prune duplicate or stale review/reference artifacts
+
+Use [Workflow & Projects](workflow/index.md) for the full lifecycle map and related docs on artifacts, reviews, PR flow, and state transitions.
+
+## Repository Analysis
+
+### `oat repo ...`
+
+The `oat repo` command group is for repository-wide analysis work rather than single-project execution.
+
+- `oat repo pr-comments collect` - collect merged PR review comments into monthly artifacts
+- `oat repo pr-comments triage-collection` - interactively keep or discard collected comments
+
+See [Repository Analysis](workflow/repo-analysis.md) for the detailed collection, filtering, and triage workflow.
+
+## Repo State and Internal Commands
+
+### Repo state helpers
+
+- `oat state refresh` - rebuild the `.oat/state.md` dashboard for the repo
+- `oat index init` - generate a lightweight `project-index.md` for orientation
+
+### Internal helpers
+
+- `oat internal validate-oat-skills` - validate `oat-*` skill contracts and metadata
+- `oat doctor` - run environment and setup diagnostics, including installed-vs-bundled skill version checks
+
+`oat doctor` is the quickest way to confirm that your runtime, directory structure, and installed OAT assets are healthy before deeper debugging. The `/oat-doctor` skill (installed via the core pack) provides richer diagnostics with check and summary modes, including config explanations sourced from bundled documentation.
+
+## Global Options
+
+Most command groups support these global flags:
+
+| Option            | Description                                                   |
+| ----------------- | ------------------------------------------------------------- |
+| `--json`          | Emit a single JSON document instead of human-readable output. |
+| `--verbose`       | Enable debug-style logging.                                   |
+| `--scope <scope>` | Limit work to `project`, `user`, or `all`.                    |
+| `--cwd <path>`    | Override the working directory for the command.               |

package/assets/docs/guide/concepts.md

@@ -0,0 +1,88 @@
+---
+title: Core Concepts
+description: Mental model for canonical assets, provider views, scopes, skills, and the optional workflow layer.
+---
+
+# Core Concepts
+
+OAT combines a provider-sync layer, reusable skills and CLI tooling, and an optional workflow system. This page gives the high-level mental model so the detailed docs are easier to navigate.
+
+## Capability Stack
+
+```mermaid
+flowchart TD
+  BASE["Provider sync + CLI\ncanonical assets, status, sync, docs commands"] --> MIDDLE["Reusable skills + tooling\nideas, docs workflows, repo helpers"]
+  MIDDLE --> TOP["Optional workflow layer\ntracked projects, reviews, PR flow, HiLL"]
+```
+
+## Canonical Assets and Provider Views
+
+OAT keeps canonical assets in repo-controlled locations and projects provider-specific views from that source of truth. The canonical form is what you edit and review directly; provider views are synchronized outputs that let Claude Code, Cursor, Copilot, Gemini, and Codex consume the same intent in their native layouts.
+
+```mermaid
+flowchart LR
+  SKILLS[".agents/skills/"] --> OAT["oat sync"]
+  AGENTS[".agents/agents/"] --> OAT
+  RULES[".agents/rules/"] --> OAT
+  OAT --> CLAUDE[".claude/"]
+  OAT --> CURSOR[".cursor/"]
+  OAT --> COPILOT[".github/"]
+  OAT --> GEMINI[".gemini/"]
+  OAT --> CODEX[".codex/"]
+```
+
+Use these docs next:
+
+- [Provider Sync](provider-sync/index.md)
+- [Reference](../reference/index.md)
+
+## Sync, Drift, and Adoption
+
+`oat sync` applies canonical content to provider views, while `oat status` reports whether a provider is in sync, drifted, or missing content. Drift is expected when provider-side files diverge from canonical content; OAT now also covers canonical rule sync and stray adoption so you can bring unmanaged files back under the canonical model deliberately.
+
+Use these docs next:
+
+- [Provider Sync Commands](provider-sync/commands.md)
+- [Manifest and Drift](provider-sync/manifest-and-drift.md)
+
+## Scopes
+
+Most OAT operations run in one of three scopes: `project`, `user`, or `all`. Project scope targets the current repository, user scope targets user-level installations, and `all` evaluates both. The same scope model appears across sync, status, and provider configuration commands, so it is worth learning early.
+
+Use these docs next:
+
+- [Scope and Surface](provider-sync/scope-and-surface.md)
+- [CLI Reference](cli-reference.md)
+
+## Skills and CLI Commands
+
+Skills are structured workflow instructions stored in `.agents/skills`, while CLI commands provide direct operational entry points like `oat init`, `oat sync`, or `oat docs init`. Some capabilities are primarily CLI-driven, some are primarily skill-driven, and some combine both. As a rule: use the CLI for direct system actions and use skills when you want guided lifecycle execution.
+
+Use these docs next:
+
+- [Skills](skills/index.md)
+- [Contributing Skills](../contributing/skills.md)
+
+## The Three Usage Modes
+
+OAT can be adopted in three layers:
+
+1. Provider sync and CLI interop only
+2. Provider-agnostic tooling and reusable skills
+3. Optional workflow/project lifecycle
+
+These layers stack. You can stay at the interop layer, use only the tooling layer, or adopt the full lifecycle when you need tracked discovery, planning, implementation, review, and PR flow.
+
+Use these docs next:
+
+- [Quickstart](../quickstart.md)
+- [Workflow & Projects](workflow/index.md)
+
+## Human-in-the-Loop Lifecycle
+
+The workflow system supports explicit checkpoints so a project can pause at selected moments for approval or direction. At the workflow level, HiLL gates control lifecycle routing across discovery, spec, design, plan, and implementation. During implementation, plan-phase checkpoints control where execution pauses between plan phases.
+
+Use these docs next:
+
+- [Workflow & Projects](workflow/index.md)
+- [Hill Checkpoints](workflow/hill-checkpoints.md)

package/assets/docs/guide/configuration.md

@@ -0,0 +1,130 @@
+---
+title: Configuration
+description: 'How OAT configuration is split across shared repo, repo-local, user, and provider-sync surfaces.'
+---
+
+# Configuration
+
+Use this guide when you need to answer two questions quickly:
+
+1. Which config file owns a setting?
+2. Which CLI command should I use to inspect or change it?
+
+For the deep file-by-file reference, see:
+
+- [File Locations](../reference/file-locations.md)
+- [`.oat` Directory Structure](../reference/oat-directory-structure.md)
+- [Sync Config (`.oat/sync/config.json`)](provider-sync/config.md)
+
+## The four config surfaces
+
+| Surface              | File                     | Typical contents                                                                                                 | Primary CLI surface                        |
+| -------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| Shared repo config   | `.oat/config.json`       | Repo-wide non-sync settings such as `projects.root`, `git.defaultBranch`, `documentation.*`, and `archive.*`     | `oat config get/set/list/describe`         |
+| Repo-local config    | `.oat/config.local.json` | Per-developer state for this checkout, such as `activeProject`, `lastPausedProject`, and repo-local `activeIdea` | `oat config get/set/list/describe`         |
+| User config          | `~/.oat/config.json`     | User-level state such as global `activeIdea` fallback                                                            | `oat config describe`                      |
+| Provider sync config | `.oat/sync/config.json`  | Provider enablement and sync strategy settings                                                                   | `oat providers set`, `oat config describe` |
+
+The main split is:
+
+- `.oat/config.json` for shared repo behavior
+- `.oat/config.local.json` for local developer state
+- `~/.oat/config.json` for user-scope fallback state
+- `.oat/sync/config.json` for provider sync only
+
+## The fastest way to inspect config
+
+Use `oat config` as the primary discovery surface:
+
+```bash
+oat config list
+oat config get projects.root
+oat config describe
+oat config describe archive.s3Uri
+oat config describe sync.providers.github.enabled
+```
+
+What each command is for:
+
+- `oat config list` shows the currently resolved command-surface values for shared and repo-local keys.
+- `oat config get <key>` reads one supported key value.
+- `oat config set <key> <value>` updates supported shared or repo-local keys.
+- `oat config describe` shows the supported config catalog across shared repo, repo-local, user, and sync/provider surfaces.
+- `oat config describe <key>` shows file, scope, default, mutability, owning command, and description for one key.
+
+## Shared repo config you will touch most often
+
+Common keys in `.oat/config.json`:
+
+- `projects.root` — where tracked projects live
+- `worktrees.root` — where OAT-managed worktrees live
+- `git.defaultBranch` — base branch fallback for PR workflows
+- `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership
+- `documentation.requireForProjectCompletion` — whether docs sync is a completion gate
+- `archive.s3Uri` — base S3 archive prefix
+- `archive.s3SyncOnComplete` — upload archived projects to S3 during completion
+- `archive.summaryExportPath` — export `summary.md` into a durable tracked directory during completion
+
+Archive example:
+
+```bash
+oat config set archive.s3Uri s3://example-bucket/oat-archive
+oat config set archive.s3SyncOnComplete true
+oat config set archive.summaryExportPath .oat/repo/reference/project-summaries
+```
+
+With those values configured:
+
+- `oat-project-complete` still archives locally into `.oat/projects/archived/<project>/`
+- completion also attempts an S3 upload when AWS CLI is available and configured, storing dated snapshots such as `<archive.s3Uri>/<repo-slug>/projects/20260401-my-project/`
+- completion also copies `summary.md` into `<archive.summaryExportPath>/20260401-my-project.md`
+- `oat project archive sync` can later pull archive data back down from S3 and materialize the latest snapshot into the local bare archive path `.oat/projects/archived/<project>/`
+
+## Repo-local and user state
+
+Use `.oat/config.local.json` for checkout-specific workflow state:
+
+- `activeProject`
+- `lastPausedProject`
+- repo-scoped `activeIdea`
+
+Use `~/.oat/config.json` for user fallback state when no repo-local value is set:
+
+- `activeIdea`
+
+In practice, you usually inspect these via:
+
+```bash
+oat config get activeProject
+oat config get lastPausedProject
+oat config describe activeIdea
+```
+
+## Provider sync config is different
+
+Provider sync settings are intentionally documented in the same discovery flow, but they are not owned by `oat config set`.
+
+Examples:
+
+```bash
+oat config describe sync.defaultStrategy
+oat config describe sync.providers.<name>.enabled
+oat providers set --scope project --enabled claude,codex
+```
+
+Use:
+
+- `oat config describe ...` to understand sync keys
+- `oat providers set ...` to mutate sync/provider settings
+
+For the provider-sync schema details, use [Sync Config (`.oat/sync/config.json`)](provider-sync/config.md).
+
+## Recommended workflow
+
+When you are unsure where a setting lives:
+
+1. Run `oat config describe`.
+2. Run `oat config describe <key>` for the key you care about.
+3. Use the owning command shown there.
+
+That keeps config discovery centralized without forcing you to remember which settings belong to workflow state versus provider sync.

package/assets/docs/guide/documentation/commands.md

@@ -0,0 +1,157 @@
+---
+title: Docs App Commands
+description: 'Docs scaffolding CLI surface for Fumadocs/MkDocs, migration, index generation, and nav sync.'
+---
+
+# Docs App Commands
+
+OAT includes a dedicated docs command family for bootstrapping and maintaining
+documentation apps. Two frameworks are supported: **Fumadocs** (Next.js-based)
+and **MkDocs Material**.
+
+## 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.                      |
+
+## `oat docs init`
+
+Use `oat docs init` to scaffold a docs app that follows the OAT docs contract.
+
+Key behavior:
+
+- prompts for framework choice (Fumadocs or MkDocs) in interactive mode
+- detects monorepo vs single-package repo shape
+- defaults to `apps/<app-name>` for monorepos
+- defaults to `<app-name>/` at repo root for single-package repos
+- sets `documentation.tooling`, `documentation.root`, and `documentation.index` in `.oat/config.json`
+
+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
+- starter docs: `docs/index.md`, `docs/getting-started.md`, `docs/contributing.md`
+
+MkDocs scaffold:
+
+- MkDocs Material with OAT contributor contract (unchanged from previous behavior)
+- includes `docs/index.md`, `docs/contributing.md`, and the local tooling needed to run the app
+
+Supported flags:
+
+- `--app-name <name>`
+- `--target-dir <path>`
+- `--framework <fumadocs|mkdocs>` (default: `fumadocs` in non-interactive mode)
+- `--description <text>` (site description, optional)
+- `--format <oxfmt|none>`
+- `--yes`
+
+Examples:
+
+```bash
+# Interactive (prompts for framework choice)
+oat docs init --app-name my-docs
+
+# Fumadocs (non-interactive)
+oat docs init --app-name my-docs --framework fumadocs --yes
+
+# MkDocs (non-interactive)
+oat docs init --app-name my-docs --framework mkdocs --yes
+```
+
+## `oat docs migrate`
+
+Use `oat docs migrate` to convert MkDocs-flavored markdown to GFM-compatible
+format for Fumadocs.
+
+Key behavior:
+
+- converts MkDocs `!!!` / `???` admonition syntax to GFM `> [!TYPE]` blockquote callouts
+- maps 14 MkDocs admonition types to 5 GFM types (NOTE, WARNING, TIP, IMPORTANT, CAUTION)
+- injects `title` frontmatter from `mkdocs.yml` nav entries (falls back to first `# heading`, then filename)
+- seeds empty `description: ""` frontmatter when missing
+- dry-run by default; use `--apply` to write changes
+
+Supported flags:
+
+- `--docs-dir <path>` (default: `docs`)
+- `--config <path>` (path to `mkdocs.yml` for nav title extraction)
+- `--apply` (write changes to disk; default is dry-run)
+
+Example:
+
+```bash
+# Preview changes
+oat docs migrate --docs-dir docs --config mkdocs.yml
+
+# Apply changes
+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.
+
+Key behavior:
+
+- recursively walks the docs directory
+- extracts page titles from frontmatter (falls back to first `# heading`, then filename title-case)
+- includes descriptions from frontmatter when present
+- outputs to app root (`index.md`) by default, not inside the docs directory
+- updates `documentation.index` in `.oat/config.json`
+- sorting: `index.md` first, then directories before files, then lexical
+
+Supported flags:
+
+- `--docs-dir <path>` (default: `docs`)
+- `--output <path>` (default: `index.md` at app root)
+
+Example:
+
+```bash
+oat docs generate-index --docs-dir docs
+```
+
+The Fumadocs scaffold runs this automatically via `predev`/`prebuild` npm
+script hooks.
+
+## `oat docs nav sync`
+
+Use nav sync 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`.
+
+Example:
+
+```bash
+oat docs nav sync --target-dir apps/oat-docs
+```
+
+Related reference:
+
+- [`../../reference/docs-index-contract.md`](../../reference/docs-index-contract.md)
+
+## `oat docs analyze` and `oat docs apply`
+
+These CLI commands intentionally reserve the docs workflow surface without
+duplicating the skill logic in Commander handlers.
+
+- `oat docs analyze` routes users to the `oat-docs-analyze` workflow
+- `oat docs apply` routes users to the `oat-docs-apply` workflow
+
+Use the CLI entrypoints when you want discoverable command help. Use the skills
+when you want the actual docs analysis/apply execution flow.
+
+Related docs:
+
+- [`workflows.md`](workflows.md)

package/assets/docs/guide/documentation/index.md

@@ -0,0 +1,27 @@
+---
+title: Documentation
+description: 'Guide to OAT documentation app setup, docs commands, and docs analysis/apply workflows.'
+---
+
+# Documentation
+
+Use this section when you are setting up, maintaining, or restructuring a docs surface with OAT.
+
+OAT supports both Fumadocs and MkDocs. In either case, the core contract is the same: each directory gets an `index.md`, and each index owns a `## Contents` section that supports local discovery and generated navigation.
+
+## Contents
+
+- [Quickstart](quickstart.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 `oat-docs-analyze` and `oat-docs-apply`.
+
+## Choose an Entry Point
+
+- Start with [Quickstart](quickstart.md) when you are adding a docs app to a repo.
+- Use [Commands](commands.md) when you already have a docs app and need the exact CLI surface.
+- Use [Workflows](workflows.md) when you want a controlled analyze/apply loop for docs changes instead of manual edits.
+
+## Related Reference
+
+- [Docs Index Contract](../../reference/docs-index-contract.md) - Rules for `index.md` and `## Contents`.
+- [CLI Reference](../cli-reference.md) - Shallow map of the full OAT CLI surface.