@open-agent-toolkit/cli 0.0.10

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

@@ -0,0 +1,164 @@
+---
+title: Add Docs to a New Repo
+description: 'Step-by-step guide for adding an OAT-managed docs app to a repository.'
+---
+
+# Add Docs to a New Repo
+
+Use this path when you want to add an OAT-managed docs app and the docs
+analyze/apply workflow to a repository.
+
+If you are developing inside the OAT repo itself, replace `oat ...` with
+`pnpm run cli -- ...`.
+
+## What this gives you
+
+- a docs app scaffolded with OAT defaults (Fumadocs or MkDocs)
+- `index.md`-driven navigation
+- docs analysis and apply skills installed via the docs pack
+- a repeatable workflow for finding gaps, verifying claims, and applying docs changes
+
+## 1. Initialize OAT in the repo
+
+```bash
+oat init --scope project
+```
+
+This sets up the base OAT structure used by the CLI and installed tool packs.
+
+## 2. Install the docs workflow skills
+
+Preferred direct path:
+
+```bash
+oat tools install docs
+```
+
+Interactive path:
+
+```bash
+oat tools install
+```
+
+Legacy pack-specific path:
+
+```bash
+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.
+
+## 3. Scaffold the docs app
+
+```bash
+oat docs init --app-name my-docs
+```
+
+In interactive mode, you'll be prompted to choose a framework:
+
+- **Fumadocs** — Next.js-based static site with FlexSearch, Mermaid diagrams, dark/light mode, and code copy buttons
+- **MkDocs** — MkDocs Material with the OAT contributor contract
+
+Default placement:
+
+- monorepo: `apps/my-docs`
+- single-package repo: `my-docs/` at repo root
+
+You can override the target and framework explicitly:
+
+```bash
+# 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
+```
+
+## 3a. Migrating from MkDocs (optional)
+
+If you have an existing MkDocs site and want to switch to Fumadocs, use the
+migration command after scaffolding:
+
+```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.
+
+## 4. Start authoring docs with the OAT 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
+
+For **MkDocs** apps, regenerate navigation after adding or moving pages:
+
+```bash
+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:
+
+```bash
+oat docs generate-index --docs-dir docs
+```
+
+## 5. Analyze the docs surface
+
+Use the skill, not the CLI stub, for the real analysis workflow.
+
+If your host supports slash-skill invocation:
+
+```text
+/oat-docs-analyze
+```
+
+Otherwise invoke the skill by name in your agent host.
+
+What `oat-docs-analyze` checks:
+
+- index contract coverage
+- nav drift
+- stale or contradicted repo-checkable claims
+- missing or thin content coverage based on repo features
+- contributor/setup guidance gaps
+
+## 6. Review the artifact and apply approved changes
+
+Run the apply skill after analysis:
+
+```text
+/oat-docs-apply
+```
+
+`oat-docs-apply` consumes the analysis artifact, asks for approval, and applies
+only the approved, evidence-backed recommendations.
+
+Important:
+
+- `oat docs analyze` and `oat docs apply` are CLI guidance entrypoints
+- the actual analysis/apply workflow runs through the skills
+
+## Typical loop
+
+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`
+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`
+8. `/oat-docs-apply`
+9. Repeat as the codebase changes
+
+## Related docs
+
+- [`commands.md`](commands.md)
+- [`workflows.md`](workflows.md)
+- [`../../reference/docs-index-contract.md`](../../reference/docs-index-contract.md)

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

@@ -0,0 +1,67 @@
+---
+title: Docs Workflows
+description: 'Docs CLI helpers and skills for analysis and controlled documentation updates.'
+---
+
+# Docs Workflows
+
+OAT’s docs workflow combines deterministic CLI helpers with higher-judgment
+skills for analysis and controlled updates.
+
+Install the workflow skills with `oat tools install docs` (preferred) or
+`oat init tools docs` before using the analyze/apply flow in a new repo.
+
+## Docs workflow pieces
+
+### CLI helpers
+
+- `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 analyze` and `oat docs apply` expose the workflow surface in CLI help
+
+### Skills
+
+- `oat-docs-analyze` evaluates a docs surface for structure, drift, coverage,
+  contributor guidance, and docs-app contract issues
+- `oat-docs-apply` consumes the analysis artifact and applies only approved,
+  evidence-backed recommendations
+
+## Contract model
+
+The docs workflow mirrors the agent-instructions analyze/apply split:
+
+- Analyze owns discovery, evidence gathering, confidence, and disclosure decisions
+- Apply consumes the artifact, asks for approval, and must not invent new docs conventions
+
+This keeps deterministic behavior in the CLI and judgment-heavy behavior in the
+skills.
+
+## Typical flow
+
+1. Bootstrap a docs app with `oat docs init` (choose Fumadocs or MkDocs)
+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:
+   - **MkDocs:** `oat docs nav sync`
+   - **Fumadocs:** `oat docs generate-index` (runs automatically via `predev`/`prebuild` hooks)
+6. Run `oat-docs-analyze`
+7. Review the artifact and run `oat-docs-apply`
+
+## Progressive disclosure
+
+The docs workflow expects local indexes to guide discovery without forcing agents
+to open every page.
+
+- keep local topic summaries in `index.md`
+- link to deeper setup/config/reference material when full detail is not needed inline
+- let the analysis artifact decide what should be inline, link-only, omitted, or escalated to the user
+
+## Related docs
+
+- [`commands.md`](commands.md)
+- [`quickstart.md`](quickstart.md)
+- [`../../reference/docs-index-contract.md`](../../reference/docs-index-contract.md)
+- [`../../contributing/skills.md`](../../contributing/skills.md)

package/assets/docs/guide/getting-started.md

@@ -0,0 +1,63 @@
+---
+title: CLI Bootstrap
+description: 'Foundational setup via oat init for canonical directories, provider adoption, and configuration.'
+---
+
+# CLI Bootstrap
+
+This page covers foundational CLI setup commands that prepare OAT structures and configuration before provider sync or tool-pack workflows.
+
+## `oat init`
+
+Purpose:
+
+- Bootstrap canonical OAT directories for a scope
+- Detect and optionally adopt provider strays
+- Initialize sync configuration/manifest state
+- Optionally install drift warning hooks
+- Run guided setup to configure tool packs, local paths, and provider sync in one session
+
+Key behavior:
+
+- Idempotent initialization
+- Interactive adoption in TTY mode
+- JSON/non-TTY contract support
+- Establishes the base structure used by `oat status`, `oat sync`, `oat init tools`, and `oat doctor`
+- For project scope, creates canonical `.agents/skills/`, `.agents/agents/`, and `.agents/rules/` directories
+
+### Guided setup
+
+After core initialization completes, `oat init` can enter an interactive guided setup flow that walks through common post-init configuration in a single session.
+
+**Entry paths:**
+
+- **`--setup` flag** — `oat init --setup` enters guided setup directly on any repo (new or existing).
+- **Fresh init** — when `.oat/` did not exist before init, the user is automatically prompted to enter guided setup. No flag needed.
+
+**Steps (each independently skippable):**
+
+1. **Tool packs** — install OAT tool packs. The core pack (diagnostics, passive docs access) is checked by default and always installs at user scope. Other packs (`docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`) install at project scope.
+2. **Local paths** — multi-select from default gitignored artifact paths (analysis, PR, reviews, ideas). Pre-existing paths are pre-checked; only new paths are added.
+3. **Provider sync** — sync provider project views via `oat sync --scope project`.
+4. **Summary** — reports what was configured: active providers, tool packs status, local paths added/existing, and provider sync status. Includes suggested next steps.
+
+Hook install note:
+
+- The optional OAT pre-commit hook installs into Git's active hook directory.
+- If a repo uses a managed hook folder such as `.githooks/`, that path must already be configured in Git, or OAT must configure it during the prompt flow before hook install.
+
+**Non-interactive mode:** Guided setup is never triggered in non-interactive mode (`--json`, piped input, or non-TTY), even if `--setup` is passed.
+
+```bash
+# Explicit guided setup on an existing repo
+oat init --setup --scope project
+
+# Fresh init — guided setup is offered automatically
+oat init --scope project
+```
+
+Related commands:
+
+- `oat tools ...` (tool-pack install, update, remove, list, info): `tool-packs.md`
+- `oat local ...`, `oat doctor`, and other utility commands: `cli-reference.md`
+- `oat status` / `oat sync` (provider sync): `provider-sync/index.md`

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

@@ -0,0 +1,34 @@
+---
+title: Ideas Workflow
+description: 'Guide to lightweight idea capture, brainstorming, and promotion into tracked projects when the work becomes concrete.'
+---
+
+# Ideas Workflow
+
+Use the ideas workflow when you need a place to think, sketch, or explore before you are ready to commit to full project artifacts.
+
+Ideas are intentionally lighter than projects: they are usually gitignored, personal, and optimized for brainstorming rather than traceable delivery.
+
+## Contents
+
+- [Lifecycle](lifecycle.md) - Capture, ideate, refine, and summarize an idea before promotion or discard.
+
+## When Ideas Fit Better Than Projects
+
+- the problem is still fuzzy
+- you want conversational exploration before writing a plan
+- the work may never become a tracked deliverable
+- you want local-only brainstorming that should not be committed yet
+
+## Key Differences from Projects
+
+| Aspect      | Projects                                                      | Ideas                                             |
+| ----------- | ------------------------------------------------------------- | ------------------------------------------------- |
+| Location    | `.oat/projects/shared/` or configured project roots           | `.oat/ideas/` or `~/.oat/ideas/`                  |
+| State model | multi-phase lifecycle with task pointers and reviews          | lightweight brainstorming and summarization state |
+| Output      | tracked requirements, plans, implementation logs, and reviews | scratchpad-style ideation plus optional summary   |
+| Best fit    | committed delivery work                                       | exploratory thinking and early shaping            |
+
+## Promotion Path
+
+When an idea becomes concrete, summarize it and then start a tracked OAT project in quick or spec-driven mode depending on design risk.

package/assets/docs/guide/ideas/lifecycle.md

@@ -0,0 +1,106 @@
+---
+title: Ideas Lifecycle
+description: 'Ideas directory structure, state model, scratchpad flow, and promotion to projects.'
+---
+
+# Ideas Lifecycle
+
+The ideas lifecycle is intentionally lightweight compared to the project workflow.
+
+## Levels
+
+Ideas can be stored at two levels:
+
+- **Project level** (default) — `.oat/ideas/` in the current project, gitignored
+- **User level** (global) — `~/.oat/ideas/` in the home directory, for ideas not tied to a specific project
+
+All idea skills accept a `--global` flag to operate at user level. Without the flag, skills auto-detect the level by checking for an active idea pointer or existing ideas directory at each level.
+
+Each level has its own independent backlog, scratchpad, and active-idea config value.
+
+## Flow
+
+1. Quick capture: `oat-idea-scratchpad` to review or capture idea seeds
+2. Start brainstorming: `oat-idea-new` (scaffolds directory, then invokes `oat-idea-ideate`)
+3. Resume brainstorming: `oat-idea-ideate` (multiple sessions over time)
+4. Finalize: `oat-idea-summarize` (generates summary, updates backlog)
+
+## Directory structure
+
+```text
+# Project level
+.oat/ideas/
+├── backlog.md              # Aggregated list of all ideas
+├── scratchpad.md           # Quick-capture pad for idea seeds
+└── {idea-name}/
+    ├── discovery.md        # Brainstorming document
+    └── summary.md          # Generated when finalized
+
+# User level (global) — same structure
+~/.oat/ideas/
+├── backlog.md
+├── scratchpad.md
+└── {idea-name}/
+    ├── discovery.md
+    └── summary.md
+```
+
+## State model
+
+Ideas track two states in `discovery.md` frontmatter:
+
+- `brainstorming` — actively being explored
+- `summarized` — finalized with a summary document
+
+No `state.md` per idea. No HiLL gates. No knowledge base dependency.
+
+## Active idea
+
+Each level stores the active idea in its config file:
+
+- Project level: `activeIdea` in `.oat/config.local.json` (gitignored)
+- User level: `activeIdea` in `~/.oat/config.json`
+
+Read/write via CLI: `oat config get activeIdea` / `oat config set activeIdea <path>`.
+
+Ideas and projects use separate config keys and do not interfere with each other.
+
+## Scratchpad
+
+The scratchpad is a checklist for capturing idea seeds quickly. Each entry supports nested bullets for quick notes:
+
+```markdown
+- [ ] **{idea name}** - {brief summary} _(YYYY-MM-DD)_
+  - {quick note}
+  - {another note}
+```
+
+Use `oat-idea-scratchpad` to review entries or quick-capture new ones. When `oat-idea-ideate` runs without an active idea, it also shows scratchpad entries alongside existing ideas. Selecting a scratchpad entry scaffolds the idea inline.
+
+## Backlog
+
+The backlog (`backlog.md`) aggregates all ideas in three sections:
+
+- **Active Brainstorming** — ideas currently being explored
+- **Captured Ideas** — summarized and ready for future consideration
+- **Archived** — completed, abandoned, or promoted to projects
+
+## Promotion to project
+
+To promote a summarized idea to a Spec-Driven OAT project:
+
+1. Run the `oat-project-new` skill with the idea name to scaffold the project
+2. Run the `oat-project-discover` skill and use the idea's `summary.md` as the initial request
+3. Update the ideas backlog entry to Archived with reason: promoted to project
+
+## Initialization
+
+The ideas directory is created automatically by `oat-idea-new` or `oat-idea-scratchpad` on first use. Future: `oat init ideas` will scaffold the directory and copy idea skills into the project.
+
+## Reference artifacts
+
+- `{IDEAS_ROOT}/backlog.md`
+- `{IDEAS_ROOT}/scratchpad.md`
+- `{IDEAS_ROOT}/{idea-name}/discovery.md`
+- `{IDEAS_ROOT}/{idea-name}/summary.md`
+- `.oat/templates/ideas/`

package/assets/docs/guide/index.md

@@ -0,0 +1,20 @@
+---
+title: User Guide
+description: User-facing guide for operating OAT across provider sync, docs tooling, workflow execution, skills, and ideas.
+---
+
+# User Guide
+
+Use this section when you want to operate OAT as a user of the toolkit rather than contribute to the codebase itself.
+
+## Contents
+
+- [Core Concepts](concepts.md) - Mental model for canonical assets, provider views, scopes, skills, and workflow layers.
+- [Getting Started](getting-started.md) - Foundational CLI setup and guided `oat init` usage.
+- [Provider Sync](provider-sync/index.md) - Provider interoperability, drift, sync, and config behavior.
+- [Tool Packs](tool-packs.md) - Install, update, and remove bundled OAT tool packs.
+- [Documentation](documentation/index.md) - Docs app setup, docs commands, and docs workflow entry points.
+- [Workflow & Projects](workflow/index.md) - Lifecycle, project artifacts, reviews, PR flow, and repo analysis docs.
+- [Skills](skills/index.md) - Skill families and recommended entry points by use case.
+- [Ideas](ideas/index.md) - Lightweight brainstorming and idea capture flow.
+- [CLI Reference](cli-reference.md) - Scannable command-group reference for the current OAT CLI surface.

package/assets/docs/guide/provider-sync/commands.md

@@ -0,0 +1,100 @@
+---
+title: Provider Interop Commands
+description: 'CLI commands for provider status, sync, and drift management.'
+---
+
+# Provider Interop Commands
+
+## Shared conventions
+
+These command definitions inherit the cross-cutting CLI conventions in:
+
+- [`../../contributing/design-principles.md`](../../contributing/design-principles.md)
+
+## Adjacent command docs (outside provider interop scope)
+
+- `oat init` (bootstrap): `../getting-started.md`
+- `oat tools ...` (tool-pack lifecycle — install, update, remove, list, info): `../tool-packs.md`
+- `oat doctor` (cross-cutting diagnostics): `../cli-reference.md`
+
+## `oat status`
+
+Purpose:
+
+- Report `in_sync`, `drifted`, `missing`, and `stray` states
+
+Key behavior:
+
+- Scope support (`project`, `user`, `all`)
+- Optional interactive stray adoption
+- JSON output for automation
+
+## `oat sync`
+
+Purpose:
+
+- Reconcile provider views from canonical sources
+
+Key behavior:
+
+- Mutates by default; use `--dry-run` to preview
+- Strategy-aware operations (`symlink`, `copy`, `auto`)
+- Provider enable/disable honored via sync config
+
+## `oat providers list`
+
+Purpose:
+
+- Summarize adapters, detection, and mapping-level health summary
+
+## `oat providers inspect <provider>`
+
+Purpose:
+
+- Show adapter mappings and per-scope mapping state details
+
+## `oat providers set`
+
+Purpose:
+
+- Enable or disable project providers in sync config
+
+Key behavior:
+
+- Modifies `.oat/sync/config.json` to toggle provider enablement
+- Options: `--enabled <providers>`, `--disabled <providers>` (comma-separated)
+- Changes take effect on next `oat sync`
+
+## Notes
+
+- `oat init --scope project` is commonly used before provider-interop commands because it initializes `.oat/sync/config.json`.
+- `oat doctor` complements interop workflows by surfacing environment and bundled-skill version issues before or after sync operations.
+
+## Adjacent Instruction Integrity Commands
+
+These commands are documented here because they are commonly used during interop-only repo maintenance, but they are not provider sync/drift commands.
+
+## `oat instructions validate`
+
+Purpose:
+
+- Validate AGENTS.md to CLAUDE.md pointer integrity
+
+Key behavior:
+
+- Read-only validation of sibling `CLAUDE.md` pointer files for each discovered `AGENTS.md`
+- Reports `ok`, `missing`, and `content_mismatch` states
+- Exit code `0` when all entries are valid, `1` when drift is detected
+
+## `oat instructions sync`
+
+Purpose:
+
+- Repair AGENTS.md to CLAUDE.md pointer drift
+
+Key behavior:
+
+- Mutates by default; use `--dry-run` to preview changes
+- Creates missing `CLAUDE.md` pointers
+- Skips mismatched files unless `--force` is provided
+- Writes canonical pointer content `@AGENTS.md\n`

package/assets/docs/guide/provider-sync/config.md

@@ -0,0 +1,77 @@
+---
+title: 'Sync Config (`.oat/sync/config.json`)'
+description: 'Configuration schema and behavior for provider sync in .oat/sync/config.json.'
+---
+
+# Sync Config (`.oat/sync/config.json`)
+
+This document defines the project sync config used by provider-interop commands.
+
+## Location
+
+- Project scope: `.oat/sync/config.json`
+
+## Purpose
+
+`config.json` controls provider enablement and sync strategy behavior.
+
+Discovery note:
+
+- `oat config describe` includes `.oat/sync/config.json` in its catalog so you can inspect the sync/provider keys from the main config help surface.
+- Mutation ownership still lives with provider-sync commands such as `oat providers set`, not `oat config set`.
+
+It is read by:
+
+- `oat init` (provider selection and defaults)
+- `oat sync` (active provider resolution and mismatch handling)
+- `oat providers set` (explicit provider enable/disable updates)
+
+## Schema (current)
+
+```json
+{
+  "version": 1,
+  "defaultStrategy": "auto",
+  "providers": {
+    "claude": {
+      "enabled": true,
+      "strategy": "symlink"
+    },
+    "cursor": {
+      "enabled": false
+    }
+  }
+}
+```
+
+### Fields
+
+| Field                       | Required                              | Description                                                |
+| --------------------------- | ------------------------------------- | ---------------------------------------------------------- |
+| `version`                   | yes                                   | Config schema version (currently `1`)                      |
+| `defaultStrategy`           | yes                                   | Global default sync strategy: `auto`, `symlink`, or `copy` |
+| `providers`                 | no (persisted), normalized at runtime | Provider-specific overrides keyed by adapter name          |
+| `providers.<name>.enabled`  | no                                    | Explicit provider activation (`true` / `false`)            |
+| `providers.<name>.strategy` | no                                    | Per-provider strategy override (`auto`, `symlink`, `copy`) |
+
+## Behavior notes
+
+- If `providers.<name>.enabled` is:
+  - `true`: provider is active even if provider directory detection is false.
+  - `false`: provider is inactive even if directory is detected.
+  - unset: provider falls back to directory detection.
+- `defaultStrategy` is used when no provider-specific `strategy` is set.
+- At runtime, config is normalized so `providers` is always present in memory.
+
+## Recommended management flow
+
+- Initial setup (interactive): `oat init --scope project`
+- Explicit updates: `oat providers set --scope project --enabled <providers> --disabled <providers>`
+- Apply sync changes: `oat sync --scope project`
+- Inspect the sync config contract: `oat config describe sync.defaultStrategy` or `oat config describe sync.providers.<name>.enabled`
+
+## Related references
+
+- [`commands.md`](commands.md)
+- [`manifest-and-drift.md`](manifest-and-drift.md)
+- [`../../reference/oat-directory-structure.md`](../../reference/oat-directory-structure.md)