@open-agent-toolkit/cli 0.1.22 → 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

@@ -13,6 +13,7 @@ Documentation should ship with the code it explains. This page covers the core d
 - 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
 
@@ -55,12 +56,13 @@ Documentation should ship with the code it explains. This page covers the core d
 - 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, 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:
+- 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

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/commands.md

@@ -26,6 +26,15 @@ and **MkDocs Material**.
 | `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`
 
 Use `oat docs init` to scaffold a docs app that follows the OAT docs contract.
@@ -141,11 +150,13 @@ script hooks.
 
 ## `oat docs nav sync`
 
-Use nav sync for MkDocs apps 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/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

@@ -5,13 +5,15 @@ description: 'Docs source contract: authored index.md maps, generated Fumadocs m
 
 # Docs Index Contract
 
-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.
+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 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.
 
@@ -31,28 +33,37 @@ Notes:
 - Links after `## Contents` can include short human-readable descriptions.
 - 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.
+- Prose outside `## Contents` is ignored by nav generation and remains freeform; it can explain scope, reader paths, or migration status.
 
-## Navigation generation
+## Fumadocs Generation
 
-Fumadocs and MkDocs use the same authored source, but they do not use the same generated artifact.
+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.
 
-For Fumadocs docs apps, `oat docs generate-index` walks the Markdown file tree under `docs/` and writes the app-root generated manifest, for example `apps/oat-docs/index.md`.
+`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
 ```
 
-For MkDocs docs apps, `oat docs nav sync --target-dir <docs-app-dir>` walks the docs tree from `docs/index.md` downward and updates the `nav:` entries in `mkdocs.yml`.
+`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.
 
-Generated behavior:
+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.
-- Fumadocs generated entries are ordered by the file-tree generator: `index.md` first, directories before files, then lexical order.
-- MkDocs nested entries are emitted in the order they appear under each local `## Contents` block.
-- Fumadocs generated manifests should carry an autogen warning and are rewritten by `predev` / `prebuild`.
-- MkDocs `mkdocs.yml` may contain other configuration, but its `nav:` block is derived from authored `## Contents`.
+- 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
 
@@ -66,6 +77,7 @@ Generated behavior:
 - 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, 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/workflows/index.md

@@ -7,7 +7,13 @@ description: Standalone adoption lane for tracked OAT projects, workflow lifecyc
 
 Agentic Workflows is the OAT lane for tracked, resumable work on top of the base CLI and provider-sync layers.
 
-Use this section when you want explicit project artifacts, stable task IDs, review loops, and resumable execution across longer-running work.
+Use this section when you want explicit project artifacts, stable task IDs, review loops, and resumable execution across longer-running work. The workflow layer is optional; stay with direct CLI usage when the task is straightforward and the overhead of project artifacts would outweigh the value.
+
+## Contents
+
+- [Ideas Workflow](ideas/index.md) - Lightweight idea capture, brainstorming, and promotion into tracked projects when the work becomes concrete.
+- [Workflow & Projects](projects/index.md) - Lifecycle, artifacts, reviews, PR flow, and repository analysis.
+- [Skills](skills/index.md) - Workflow-oriented skill discovery and use-case routing.
 
 ## What This Section Is
 
@@ -19,11 +25,33 @@ This section explains when workflow mode is worth the overhead, how OAT projects
 - Users who want explicit discovery, planning, implementation, and review state
 - Repos that need a repeatable human-in-the-loop execution model
 
+## When To Use Workflow Mode
+
+Use workflow mode when:
+
+- the work spans multiple sessions or contributors
+- you want explicit discovery, plan, implementation, and review artifacts
+- you need stable task sequencing and resumable execution
+- you want human-in-the-loop checkpoints around risky transitions
+
+Stay with direct CLI usage when:
+
+- the task is straightforward and bounded
+- you mainly need provider sync or a utility command
+- the overhead of project artifacts would outweigh the value
+
+## Workflow Modes In Practice
+
+- CLI only: direct commands, no tracked project artifacts
+- Quick mode: tracked work with a lighter upfront planning path
+- Spec-driven mode: explicit discovery, requirements, design, and plan artifacts
+- Import mode: an externally-authored plan imported into OAT for tracked execution
+
 ## Start Here
 
-- Read [Overview](overview.md) to decide whether you want workflow mode or just direct CLI usage.
 - Use [Skills](skills/index.md) when you want task-oriented guidance on the most useful workflow skills.
 - Go to [Workflow & Projects](projects/index.md) when you need the lifecycle and artifact model in detail.
+- Use [Ideas](ideas/index.md) when the work is still exploratory.
 
 ## Common Tasks
 
@@ -34,7 +62,6 @@ This section explains when workflow mode is worth the overhead, how OAT projects
 
 ## Go Deeper
 
-- [Overview](overview.md) - What the workflow layer adds and when to use it.
 - [Skills](skills/index.md) - Workflow-oriented skill discovery and use-case routing.
 - [Ideas](ideas/index.md) - Idea capture, refinement, and promotion flows.
 - [Workflow & Projects](projects/index.md) - Lifecycle, artifacts, reviews, PR flow, and repository analysis.

package/assets/docs/workflows/projects/index.md

@@ -9,6 +9,20 @@ Use this section when you want the detailed lifecycle and artifact model behind
 
 Projects are where the workflow layer becomes concrete: lifecycle phases, `state.md`, `plan.md`, review gates, PR flow, and repository-analysis helpers all live here.
 
+## Contents
+
+- [Lifecycle](lifecycle.md) - End-to-end flow from discovery through completion.
+- [Design Modes](design-modes.md) - How full design balances collaborative, selective collaborative, and draft-and-review interaction.
+- [HiLL Checkpoints](hill-checkpoints.md) - Human-in-the-Loop Lifecycle configuration and approval behavior.
+- [Dispatch Ceiling](dispatch-ceiling.md) - Provider-neutral ceiling model and provider-specific enforcement.
+- [Project Artifacts](artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
+- [Implementation Execution](implementation-execution.md) - Phase dispatch, runtime selection, review/fix loop, and dry-run behavior.
+- [Project Splitting](splitting.md) - How broad discoveries or brainstorms become coordination parents and child projects.
+- [State Machine](state-machine.md) - Lifecycle and review status transitions across a project.
+- [Reviews](reviews.md) - How review request/receive loops work inside OAT projects.
+- [PR Flow](pr-flow.md) - Progress and final PR generation expectations.
+- [Repository PR Comment Analysis](repo-analysis.md) - Repo-wide PR comment collection and triage workflows.
+
 ## What This Section Is
 
 This sub-section is the deep technical surface for how tracked OAT projects execute and how their artifacts, reviews, and PR states fit together.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.22",
-  "docs-config": "0.1.22",
-  "docs-theme": "0.1.22",
-  "docs-transforms": "0.1.22"
+  "cli": "0.1.23",
+  "docs-config": "0.1.23",
+  "docs-theme": "0.1.23",
+  "docs-transforms": "0.1.23"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.1.22"
+    "@open-agent-toolkit/control-plane": "0.1.23"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

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

@@ -1,33 +0,0 @@
----
-title: CLI Utilities Overview
-description: Plain-language explanation of the OAT CLI surface that lives outside provider sync, docs tooling, and tracked workflows.
----
-
-# CLI Utilities Overview
-
-Not every OAT command belongs to a single product lane. Some commands are general-purpose setup, configuration, pack-management, or diagnostic utilities that support the rest of the toolkit without being specific to provider sync, docs tooling, or tracked workflow execution.
-
-That is what this section covers.
-
-## What Lives Here
-
-- 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
-
-## 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
-
-## Continue Here
-
-- [CLI Bootstrap](bootstrap.md) for initial setup
-- [Tool Packs](tool-packs.md) for pack lifecycle management
-- [Configuration](configuration.md) for config semantics
-- [Config and Local State](config-and-local-state.md) for the wider utility command map

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

@@ -1,31 +0,0 @@
----
-title: Docs Tooling Overview
-description: Plain-language explanation of OAT docs support, docs app choices, and the index contract.
----
-
-# Docs Tooling Overview
-
-OAT can help bootstrap and maintain a structured docs surface, not just code and provider assets. The docs tooling is built around a simple contract: each directory owns an `index.md`, and that index owns a `## Contents` section that supports local discovery and generated navigation.
-
-OAT supports both Fumadocs and MkDocs. The site framework changes the surrounding app setup, but the underlying documentation contract stays the same.
-
-## When To Use This Section
-
-Use Docs Tooling when:
-
-- you are adding a docs app to a repo
-- you need to keep index pages and nav structure in sync
-- you want a controlled analyze/apply loop for docs restructuring work
-
-## Typical Flow
-
-1. Bootstrap or adopt a docs app in the repo.
-2. Use the docs commands to generate or sync index/navigation structure.
-3. Apply the docs workflow when you want analysis-backed restructuring rather than ad hoc manual edits.
-
-## Continue Here
-
-- [Add Docs to a Repo](add-docs-to-a-repo.md) for initial setup
-- [Commands](commands.md) for the CLI surface
-- [Workflows](workflows.md) for governed docs changes
-- [Docs Index Contract](../reference/docs-index-contract.md) for the underlying rules

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

@@ -1,38 +0,0 @@
----
-title: Provider Sync Overview
-description: Plain-language explanation of canonical assets, provider views, and the first-sync loop.
----
-
-# Provider Sync Overview
-
-Provider sync lets OAT manage one canonical set of agent assets and then project those assets into provider-specific views. In practice, that means you edit the canonical layout in `.agents/` and `.oat/`, then let OAT generate or reconcile the provider copies.
-
-This is useful when you want consistent instructions, skills, and rules across multiple providers without treating each provider directory as a long-lived hand-maintained source of truth.
-
-## 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
-
-## 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.
-
-## When To Use This Section
-
-Use Provider Sync when:
-
-- you want to adopt OAT incrementally, without committing to tracked project workflows yet
-- you need a clear model for drift, strays, and adoption
-- you want to understand which files should be edited directly and which should be regenerated
-
-## Continue Here
-
-- [CLI Bootstrap](../cli-utilities/bootstrap.md) for the first sync setup flow
-- [Scope and Surface](scope-and-surface.md) for the canonical/provider-view model
-- [Commands](commands.md) for the exact CLI behavior

package/assets/docs/workflows/overview.md

@@ -1,38 +0,0 @@
----
-title: Agentic Workflows Overview
-description: Plain-language explanation of when to use tracked OAT projects versus direct CLI usage.
----
-
-# Agentic Workflows Overview
-
-OAT workflow mode adds a tracked lifecycle on top of the base CLI. Instead of just running commands directly, you work through explicit project artifacts such as `state.md`, `plan.md`, and `implementation.md`, with stable task IDs and review checkpoints.
-
-That extra structure is optional. You only need it when the work is large enough, risky enough, or long-lived enough that resumability and explicit coordination matter.
-
-## When To Use Workflow Mode
-
-Use workflow mode when:
-
-- the work spans multiple sessions or contributors
-- you want explicit discovery, plan, implementation, and review artifacts
-- you need stable task sequencing and resumable execution
-- you want human-in-the-loop checkpoints around risky transitions
-
-Stay with direct CLI usage when:
-
-- the task is straightforward and bounded
-- you mainly need provider sync or a utility command
-- the overhead of project artifacts would outweigh the value
-
-## Workflow Modes In Practice
-
-- CLI only: direct commands, no tracked project artifacts
-- Quick mode: tracked work with a lighter upfront planning path
-- Spec-driven mode: explicit discovery, requirements, design, and plan artifacts
-- Import mode: an externally-authored plan imported into OAT for tracked execution
-
-## Continue Here
-
-- [Skills](skills/index.md) for task-oriented workflow skill discovery
-- [Ideas](ideas/index.md) for lightweight capture and refinement
-- [Workflow & Projects](projects/index.md) for the lifecycle, artifact, and review model