@open-agent-toolkit/cli 0.0.10

package/assets/docs/quickstart.md

@@ -0,0 +1,162 @@
+---
+title: Quickstart
+description: 'Quick-start guides for interop-only, provider-agnostic tooling, and optional workflow adoption.'
+---
+
+# Quickstart
+
+## Prerequisites
+
+- Node.js `22.17.0+`
+- pnpm `10.13.1+`
+
+## Path A: Interop-only (CLI)
+
+```bash
+pnpm install
+pnpm run cli -- --help
+```
+
+### Initialize canonical structure
+
+```bash
+pnpm run cli -- init --scope project
+```
+
+Creates canonical directories and can offer stray adoption/hook installation.
+
+### Check status and sync
+
+```bash
+pnpm run cli -- status --scope all
+pnpm run cli -- sync --scope all
+```
+
+Notes:
+
+- `sync` mutates by default; use `--dry-run` to preview changes without writing.
+
+### Install or update OAT tool packs (optional)
+
+```bash
+pnpm run cli -- tools install
+# or install just the project-management pack
+pnpm run cli -- tools install project-management
+```
+
+Notes:
+
+- Installs OAT tool packs (`docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`) into canonical directories. The `core` pack is always installed at user scope for diagnostics and passive docs access.
+- `oat init tools` remains available as a backward-compatible install path.
+- If installed OAT skills are older than bundled versions, interactive runs prompt for selective updates.
+- Non-interactive runs report outdated skills without updating them.
+
+### Remove installed skills or packs (optional)
+
+```bash
+pnpm run cli -- remove skill oat-idea-scratchpad
+pnpm run cli -- remove skills --pack utility
+```
+
+Notes:
+
+- `oat remove` mutates by default; use `--dry-run` to preview deletions.
+- Managed provider views are removed alongside canonical skill deletion; unmanaged views are preserved with warnings.
+
+### Validate instruction pointers
+
+```bash
+pnpm run cli -- instructions validate
+pnpm run cli -- instructions sync
+```
+
+Notes:
+
+- `instructions validate` is read-only.
+- `instructions sync` mutates by default; use `--dry-run` to preview changes.
+- Use `instructions sync --force` if you intend to overwrite mismatched `CLAUDE.md` content.
+
+### Additional CLI commands
+
+```bash
+# Mode-aware project scaffold
+pnpm run cli -- project new my-project --mode quick
+
+# Bootstrap or maintain a docs app
+pnpm run cli -- docs init --app-name my-docs
+pnpm run cli -- docs nav sync --target-dir apps/my-docs
+
+# Manage the file-backed backlog directly
+pnpm run cli -- backlog init
+pnpm run cli -- backlog generate-id add-webhook-support --created-at 2026-03-15T14:30:00Z
+pnpm run cli -- backlog regenerate-index
+
+# Internal oat-* skill validation (primary path)
+pnpm oat:validate-skills
+```
+
+### Worktree setup
+
+Use `oat-worktree-bootstrap` for an OAT-aware guided flow when creating or resuming git worktree checkouts. It resolves worktree paths, runs bootstrap checks (`worktree:init`, tests), and validates project sync state before implementation.
+
+### Consumer usage (without pnpm scripts)
+
+When `@open-agent-toolkit/cli` is consumed as a built package or linked binary, use `oat` directly:
+
+```bash
+oat --help
+oat init --scope project
+oat tools install
+oat status --scope all
+oat sync --scope all
+oat instructions validate
+oat instructions sync
+oat remove skills --pack utility
+oat doctor --scope all
+oat project new my-project --mode spec-driven
+oat backlog init
+oat backlog regenerate-index
+```
+
+## Path B: Provider-agnostic tooling (skills + utilities)
+
+Use shared skills and helper tooling without adopting the spec-driven OAT project lifecycle.
+
+This is also the right path for plan-first ideation that can later be synced/imported into an OAT project.
+
+Start here:
+
+- [`guide/skills/index.md`](guide/skills/index.md)
+- [`guide/documentation/workflows.md`](guide/documentation/workflows.md)
+- [`guide/documentation/commands.md`](guide/documentation/commands.md)
+- [`guide/documentation/quickstart.md`](guide/documentation/quickstart.md)
+- [`reference/index.md`](reference/index.md)
+
+## Path C: Workflow layer (optional)
+
+Adopt the workflow layer when you want tracked project artifacts, explicit review gates, and resumable execution state.
+
+Start with:
+
+- [`guide/workflow/index.md`](guide/workflow/index.md)
+- [`guide/workflow/lifecycle.md`](guide/workflow/lifecycle.md)
+- [`guide/workflow/artifacts.md`](guide/workflow/artifacts.md)
+
+Typical entry points:
+
+- Spec-driven work: `oat-project-new` or `oat-project-open`, then discovery → spec → design → plan → implement
+- Quick work: `oat-project-quick-start`, then plan or lightweight design as needed before implementation
+- Imported plans: `oat-project-import-plan`, then tracked implementation and review
+
+Implementation modes:
+
+- `oat-project-implement` for sequential execution
+- `oat-project-subagent-implement` for parallel/subagent-driven execution
+
+Review and close-out:
+
+- `oat-project-review-provide` / `oat-project-review-receive`
+- `oat-project-pr-progress` or `oat-project-pr-final`
+- `oat-project-document` and `oat-project-complete` when the work is ready to close
+
+If you are importing plans from external provider plan folders, set `OAT_PROVIDER_PLAN_DIRS` before running `oat-project-import-plan`.

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

@@ -0,0 +1,53 @@
+---
+title: Docs Index Contract
+description: 'Navigation generation contract: index.md format and authoring guidance.'
+---
+
+# Docs Index Contract
+
+OAT docs navigation is generated from each directory `index.md`, not from hand-maintained `mkdocs.yml` trees.
+
+## Rules
+
+- Every documentation directory must contain an `index.md`.
+- Every `index.md` must include a `## Contents` section.
+- The `## Contents` section is the only machine-readable source used by `oat docs nav sync`.
+- `overview.md` is deprecated. Replace it with `index.md`, or convert it to a descriptive leaf page when the directory already has its own `index.md`.
+
+## `## Contents` format
+
+Use Markdown bullet links for sibling pages and child directories:
+
+```md
+## Contents
+
+- [Getting Started](getting-started.md) - Setup and local workflow.
+- [Reference](reference/index.md) - Reference pages for the subsystem.
+```
+
+Notes:
+
+- Links after `## Contents` can include short human-readable descriptions.
+- Child directories should link to their `index.md`.
+- Prose outside `## Contents` is ignored by nav generation and remains freeform.
+
+## Navigation generation
+
+`oat docs nav sync --target-dir <docs-app-dir>` walks the docs tree from `docs/index.md` downward and regenerates `mkdocs.yml` `nav` entries from the discovered `index.md` files.
+
+Generated behavior:
+
+- Root `docs/index.md` becomes `Home`.
+- Child directory `index.md` files become section landing pages.
+- Nested entries are emitted in the order they appear under each local `## Contents` block.
+
+## Authoring guidance
+
+- Use `index.md` as the local discovery surface for humans and agents.
+- Add a short topic description next to each link so agents can choose the right file without opening every page.
+- Update `## Contents` whenever you add, remove, or rename docs files in a directory.
+
+## If You Are Trying To...
+
+- learn the docs workflow or docs commands as a user, start with [Documentation](../guide/documentation/index.md)
+- contribute or restructure docs in this repo, pair this contract with [Contributing to OAT Docs](../contributing/documentation.md)

package/assets/docs/reference/file-locations.md

@@ -0,0 +1,109 @@
+---
+title: File Locations
+description: 'Canonical locations for agent assets, OAT config, projects, ideas, and templates.'
+---
+
+# File Locations
+
+For detailed `.oat/` tree semantics, see:
+
+- [`oat-directory-structure.md`](oat-directory-structure.md)
+
+## Canonical agent assets
+
+- Skills: `.agents/skills/`
+- Agents/subagents: `.agents/agents/`
+- Rules: `.agents/rules/`
+
+## OAT runtime/state
+
+- Repo runtime config (non-sync settings): `.oat/config.json`
+- Local runtime config (per-developer state): `.oat/config.local.json`
+- Active idea: `activeIdea` in `.oat/config.local.json` (repo) or `~/.oat/config.json` (user)
+- Projects root config: `projects.root` in `.oat/config.json` (read via `oat config get projects.root`)
+- Archive config: `archive.s3Uri`, `archive.s3SyncOnComplete`, and `archive.summaryExportPath` in `.oat/config.json`
+- Project manifests/config: `.oat/sync/`
+
+Config discovery via CLI:
+
+- `oat config describe` lists the supported config surfaces and keys across `.oat/config.json`, `.oat/config.local.json`, `~/.oat/config.json`, and `.oat/sync/config.json`.
+- `oat config describe <key>` shows file location, scope, default, mutability, and the owning command for one key.
+- `oat config list` shows the currently resolved values for the repo-local/shared command surface.
+
+Config ownership note:
+
+- `.oat/config.json` is the canonical home for shared non-sync settings (for example, `worktrees.root`, `projects.root`).
+- `.oat/config.local.json` is the canonical home for per-developer lifecycle state (for example, `activeProject`, `lastPausedProject`, `activeIdea`).
+- `~/.oat/config.json` is the canonical home for user-level state (for example, `activeIdea` at global scope).
+- `.oat/sync/config.json` remains the sync/provider config contract.
+- Legacy `.oat/active-project` / `.oat/projects-root` / `.oat/active-idea` files may still exist as inert compatibility artifacts in some repos/worktrees.
+
+## OAT workflow
+
+- Templates: `.oat/templates/`
+- Runtime sync state: `.oat/sync/`
+- Repo knowledge: `.oat/repo/knowledge/`
+- Repo reference docs: `.oat/repo/reference/`
+- Repo reviews: `.oat/repo/reviews/`
+- Repo archive: `.oat/repo/archive/`
+
+## Project artifact trees
+
+- Shared: `.oat/projects/shared/<project>/`
+- Local: `.oat/projects/local/<project>/`
+- Archived: `.oat/projects/archived/<project>/`
+
+Archive sync surfaces:
+
+- Local archive root: `.oat/projects/archived/`
+- Remote archive base: `archive.s3Uri` in `.oat/config.json`
+- Archive sync command: `oat project archive sync` or `oat project archive sync <project-name>`
+- Remote archive snapshot shape: `<archive.s3Uri>/<repo-slug>/projects/YYYYMMDD-<project-name>/`
+- Summary export target: `<repo>/<archive.summaryExportPath>/YYYYMMDD-<project-name>.md` when configured
+
+## Ideas — project level (gitignored)
+
+- Ideas root: `.oat/ideas/`
+- Backlog: `.oat/ideas/backlog.md`
+- Scratchpad: `.oat/ideas/scratchpad.md`
+- Per-idea: `.oat/ideas/<idea-name>/`
+- Active idea: `activeIdea` in `.oat/config.local.json`
+- Idea templates: `.oat/templates/ideas/`
+
+## Ideas — user level (global)
+
+- Ideas root: `~/.oat/ideas/`
+- Backlog: `~/.oat/ideas/backlog.md`
+- Scratchpad: `~/.oat/ideas/scratchpad.md`
+- Per-idea: `~/.oat/ideas/<idea-name>/`
+- Active idea: `activeIdea` in `~/.oat/config.json`
+
+## CLI code
+
+- `packages/cli/src/commands/`
+- `packages/cli/src/commands/cleanup/`
+- `packages/cli/src/commands/cleanup/project/`
+- `packages/cli/src/commands/cleanup/artifacts/`
+- `packages/cli/src/commands/docs/` — `oat docs` command family
+- `packages/cli/src/commands/docs/init/` — scaffold a docs app (Fumadocs or MkDocs)
+- `packages/cli/src/commands/docs/migrate/` — convert MkDocs admonitions to GFM callouts
+- `packages/cli/src/commands/docs/index-generate/` — generate a docs index from markdown files
+- `packages/cli/src/commands/docs/nav/` — regenerate mkdocs.yml nav from index.md sections
+- `packages/cli/src/commands/instructions/`
+- `packages/cli/src/commands/project/`
+- `packages/cli/src/commands/internal/`
+- `packages/cli/src/engine/`
+- `packages/cli/src/providers/`
+- `packages/cli/src/manifest/`
+- `packages/cli/src/drift/`
+
+## Docs shared packages
+
+- `packages/docs-config/` — config factories for Fumadocs (`createDocsConfig`, `createSourceConfig`, `createSearchConfig`)
+- `packages/docs-theme/` — shared React components for Fumadocs apps (`DocsLayout`, `DocsPage`, `Mermaid`)
+- `packages/docs-transforms/` — remark plugins for docs processing (`remarkTabs`, `remarkMermaid`)
+
+## Docs scaffold templates
+
+- `.oat/templates/docs-app-fuma/` — Fumadocs (Next.js) scaffold template
+- `.oat/templates/docs-app-mkdocs/` — MkDocs Material scaffold template

package/assets/docs/reference/index.md

@@ -0,0 +1,29 @@
+---
+title: Reference
+description: 'Durable reference material for OAT file locations, docs contracts, directory structure, and troubleshooting.'
+---
+
+# Reference
+
+Use this section for durable facts and contracts that should stay stable even as the guide and contributing flows evolve.
+
+Contributor how-to material now lives under `contributing/`, and audience-routing guidance lives under `guide/`.
+
+## Contents
+
+- [File Locations](file-locations.md) - Where core OAT files, assets, and artifacts live.
+- [Docs Index Contract](docs-index-contract.md) - Rules for directory `index.md` files and reserved `## Contents` sections.
+- [OAT Directory Structure](oat-directory-structure.md) - Canonical `.oat/` tree map and the role of each major directory.
+- [Troubleshooting](troubleshooting.md) - Common issues, diagnostics, and remediation guidance.
+
+## What Belongs Here
+
+- stable file and directory contracts
+- docs-system rules that other pages should link to instead of re-explaining
+- troubleshooting material that remains relevant across workflow and docs changes
+
+## Related Sections
+
+- [CLI Reference](../guide/cli-reference.md) for the command-surface map
+- [Documentation](../guide/documentation/index.md) for docs app setup and workflow guidance
+- [Contributing](../contributing/index.md) for code, docs, and skill-authoring practices

package/assets/docs/reference/oat-directory-structure.md

@@ -0,0 +1,236 @@
+---
+title: '`.oat` Directory Structure'
+description: 'Canonical .oat/ tree reference: config, projects, sync state, templates, and per-file purpose.'
+---
+
+# `.oat` Directory Structure
+
+This document is the canonical reference for what lives under `.oat/`, what each file or directory does, and which parts are source-of-truth vs generated runtime state.
+
+## Scope model
+
+OAT uses two scopes for `.oat` data:
+
+- Project scope: `<repo>/.oat/`
+- User scope: `~/.oat/`
+
+Project scope is used for project workflows and repo-local sync state. User scope is used for global ideas and user-level sync state.
+
+## Top-level project `.oat/` layout
+
+```text
+.oat/
+  config.json
+  config.local.json
+  projects/
+    shared/
+    local/
+    archived/
+  ideas/
+  sync/
+    manifest.json
+    config.json
+  templates/
+  scripts/
+  repo/
+    knowledge/
+    reference/
+    reviews/
+    archive/
+```
+
+## Top-level entries
+
+| Path                     | Purpose                                          | Notes                                                                                                   |
+| ------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `.oat/config.json`       | Shared repo runtime config for non-sync settings | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, and `documentation.*`     |
+| `.oat/config.local.json` | Local per-developer runtime state                | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                 |
+| `.oat/projects/`         | OAT project artifacts                            | `shared`, `local`, `archived` scopes                                                                    |
+| `.oat/ideas/`            | Project-level ideas store                        | Often gitignored                                                                                        |
+| `.oat/sync/`             | Interop sync state/config                        | See details below                                                                                       |
+| `.oat/templates/`        | Artifact templates used by OAT skills            | Source for scaffolding. Includes `docs-app-fuma/` (Fumadocs) and `docs-app-mkdocs/` (MkDocs) templates. |
+| `.oat/repo/`             | Repo-level knowledge/reference/review artifacts  | Durable operational records                                                                             |
+
+## `.oat/sync/` details
+
+| Path                      | Purpose                                                           |
+| ------------------------- | ----------------------------------------------------------------- |
+| `.oat/sync/manifest.json` | Records sync-managed provider entries and drift contract state    |
+| `.oat/sync/config.json`   | Sync behavior config (default strategy + provider-level settings) |
+
+`config.json` currently includes:
+
+- `version`
+- `defaultStrategy`
+- `providers.<provider>.enabled`
+- `providers.<provider>.strategy` (optional override)
+
+Primary ways this file is managed:
+
+- `oat init --scope project` (interactive provider selection)
+- `oat providers set --scope project --enabled ... --disabled ...`
+
+## Config ownership (current)
+
+Current config ownership:
+
+- `.oat/config.json` owns shared non-sync repo settings (including `worktrees.root`, `projects.root`, and `documentation.*`).
+- `.oat/config.local.json` owns per-developer project lifecycle state (`activeProject`, `lastPausedProject`, `activeIdea`).
+- `~/.oat/config.json` owns user-level state (`activeIdea` at global scope).
+- `.oat/sync/config.json` continues to own sync/provider behavior.
+
+CLI discovery surfaces:
+
+- `oat config describe` lists the supported config surfaces and keys across shared repo, repo-local, user, and sync/provider config.
+- `oat config describe <key>` prints scope, file, default, mutability, owning command, and description for one config key.
+- `oat config list` prints the resolved values for the repo-scoped/local command surface.
+
+Legacy `.oat/active-project` / `.oat/projects-root` / `.oat/active-idea` files may still be present in some environments but are no longer the canonical source in migrated command paths.
+
+### `.oat/config.json` schema
+
+Current schema keys:
+
+| Key                                         | Type       | Default                  | Description                                                                                                                                                                               |
+| ------------------------------------------- | ---------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`                                   | `number`   | `1`                      | Schema version                                                                                                                                                                            |
+| `worktrees.root`                            | `string`   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                              |
+| `projects.root`                             | `string`   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                   |
+| `localPaths`                                | `string[]` | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                               |
+| `documentation.root`                        | `string`   | -                        | Root directory containing documentation source files (e.g., `apps/docs/docs`)                                                                                                             |
+| `documentation.tooling`                     | `string`   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                               |
+| `documentation.config`                      | `string`   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                    |
+| `documentation.index`                       | `string`   | -                        | Path to the docs surface entry point (e.g., `index.md` for Fumadocs, `mkdocs.yml` for MkDocs). Set by `oat docs init` and updated by `oat docs generate-index`.                           |
+| `documentation.requireForProjectCompletion` | `boolean`  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                             |
+| `git.defaultBranch`                         | `string`   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                        |
+| `autoReviewAtCheckpoints`                   | `boolean`  | `false`                  | When `true`, completing a plan phase checkpoint automatically spawns a subagent code review. Can be overridden per-project via `oat_auto_review_at_checkpoints` in `plan.md` frontmatter. |
+| `archive.s3Uri`                             | `string`   | -                        | Base S3 URI for repo-scoped archived project sync, for example `s3://bucket/oat-archive`                                                                                                  |
+| `archive.s3SyncOnComplete`                  | `boolean`  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                |
+| `archive.summaryExportPath`                 | `string`   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                         |
+
+All `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`.
+The `git.defaultBranch` key is auto-detected during `oat init` and can be overridden via `oat config set git.defaultBranch <branch>`.
+Archive settings are managed via `oat config get/set`, and `oat config describe archive.s3Uri` (or the other archive keys) shows the lifecycle and ownership details from the CLI.
+
+Example:
+
+```json
+{
+  "version": 1,
+  "projects": {
+    "root": ".oat/projects/shared"
+  },
+  "worktrees": {
+    "root": ".worktrees"
+  },
+  "documentation": {
+    "root": "apps/docs/docs",
+    "tooling": "mkdocs",
+    "config": "mkdocs.yml",
+    "requireForProjectCompletion": false
+  }
+}
+```
+
+### Worktree root precedence
+
+When resolving the worktree root directory, `oat-worktree-bootstrap` uses this strict precedence (stops at the first match):
+
+1. **`--path <root>` flag** — Explicit CLI override (highest priority)
+2. **`OAT_WORKTREES_ROOT` env var** — Environment-level override
+3. **`.oat/config.json` `worktrees.root`** — Persisted project config
+4. **First existing directory** (checked in order):
+   - `<repo>/.worktrees`
+   - `<repo>/worktrees`
+   - `../<repo-name>-worktrees`
+5. **Fallback default** — `../<repo-name>-worktrees`
+
+For repo-relative values (levels 3-4), paths are resolved from the repository root. If the resolved root is project-local (`.worktrees` or `worktrees`), the skill verifies it is git-ignored before creating new worktrees.
+
+## Project artifact structure
+
+Each OAT project lives under:
+
+- `.oat/projects/shared/<project>/`
+- `.oat/projects/local/<project>/`
+- `.oat/projects/archived/<project>/`
+
+Archive sync behavior:
+
+- `oat-project-complete` always archives locally into `.oat/projects/archived/<project>/`.
+- If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, completion also uploads a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/`.
+- `oat project archive sync` syncs all repo archived projects down from S3 into `.oat/projects/archived/`.
+- `oat project archive sync <project-name>` syncs the latest dated remote snapshot for a single project into `.oat/projects/archived/<project-name>/`.
+- Default archive sync is non-destructive toward unrelated local-only archive data, but it does replace a local project archive when a newer dated remote snapshot is selected for that same project.
+
+Typical contents:
+
+```text
+<project>/
+  state.md
+  discovery.md
+  spec.md
+  design.md
+  plan.md
+  implementation.md
+  summary.md
+  reviews/
+  pr/
+  references/
+```
+
+### Core artifact roles
+
+| File                    | Purpose                                                                                                                                                                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `state.md`              | Lifecycle routing state (`oat_phase`, status, current task pointers)                                                                                                                                                           |
+| `discovery.md`          | Problem framing and requirements discovery notes                                                                                                                                                                               |
+| `spec.md`               | Formalized requirements                                                                                                                                                                                                        |
+| `design.md`             | Technical architecture/design decisions                                                                                                                                                                                        |
+| `plan.md`               | Executable task/phase plan and review table                                                                                                                                                                                    |
+| `implementation.md`     | Execution log, progress table, outcomes, verification history                                                                                                                                                                  |
+| `summary.md`            | Institutional memory artifact — generated from project artifacts by `oat-project-summary`. Contains overview, key decisions, design deltas, challenges, follow-up items. Used as PR description source and archive cover page. |
+| `reviews/*.md`          | Active tracked review artifacts awaiting receive/closeout                                                                                                                                                                      |
+| `reviews/archived/*.md` | Local-only historical review artifacts after receive/closeout                                                                                                                                                                  |
+| `pr/*.md`               | PR description artifacts                                                                                                                                                                                                       |
+| `references/*`          | Imported or supporting source material                                                                                                                                                                                         |
+
+Not all workflow modes require every artifact:
+
+- `spec-driven`: discovery + spec + design + plan + implementation
+- `quick`: discovery + plan + implementation (spec/design optional)
+- `import`: imported plan + implementation (spec/design optional)
+
+## `.oat/repo/` structure
+
+| Path                   | Purpose                                                   |
+| ---------------------- | --------------------------------------------------------- |
+| `.oat/repo/knowledge/` | Generated codebase knowledge indexes                      |
+| `.oat/repo/reference/` | Repo-level reference docs (backlog, external plans, etc.) |
+| `.oat/repo/reviews/`   | Repo-scoped review artifacts (ad-hoc/non-project)         |
+| `.oat/repo/archive/`   | Archived repo-level artifacts                             |
+
+## User scope (`~/.oat/`)
+
+Common user-scope entries:
+
+```text
+~/.oat/
+  config.json
+  ideas/
+  sync/
+    manifest.json
+```
+
+User scope is primarily for:
+
+- User-level ideas
+- User-level provider sync state where applicable
+
+## Practical guidance
+
+- Treat `.oat/templates/` as scaffolding source.
+- Treat `.oat/config.json` + `.oat/config.local.json` as OAT runtime config/state (`oat config get/set/list/describe` is the preferred interface).
+- Treat `.oat/sync/manifest.json` and `.oat/sync/config.json` as sync runtime state/config.
+- Treat project artifacts under `.oat/projects/**` as lifecycle source-of-truth for workflow execution.
+- Keep `state.md`, `plan.md`, and `implementation.md` consistent after each workflow step.

package/assets/docs/reference/troubleshooting.md

@@ -0,0 +1,63 @@
+---
+title: Troubleshooting
+description: 'Common issues and fixes for skills visibility, worktrees, sync, and manifest problems.'
+---
+
+# Troubleshooting
+
+## Skills not visible in host UI
+
+- Run: `pnpm run cli -- sync --scope all`
+- Reload/restart host app session
+- Verify `AGENTS.md` skills table matches `.agents/skills/*/SKILL.md`
+
+## Worktree checkout missing provider links
+
+- Run: `pnpm run worktree:init`
+- This command installs dependencies, builds the workspace, and runs `oat sync --scope project`.
+
+## Codex appears detected but no skill sync actions are listed
+
+Expected for native-read skill mappings. Codex can read canonical skills without mirrored provider writes.
+
+## `sync` reports provider config mismatch
+
+- For interactive runs, select detected providers to enable when prompted.
+- For non-interactive runs, configure providers explicitly:
+  - `oat providers set --scope project --enabled <providers> --disabled <providers>`
+- Re-run `oat sync --scope project` after updating config.
+
+## `instructions validate` reports `missing` or `content_mismatch`
+
+- Run `oat instructions sync` to preview changes.
+- Run `oat instructions sync` to create missing pointer files.
+- If mismatched `CLAUDE.md` files should be overwritten, run `oat instructions sync --force`.
+- Re-run `oat instructions validate` and confirm status is `ok`.
+
+## `doctor` warns about canonical directories
+
+- Run `oat init` for the relevant scope.
+- Re-run `oat doctor` after initialization.
+
+## `doctor` warns about outdated installed OAT skills
+
+- Run `oat init tools` to install/update bundled OAT tool packs.
+- In TTY mode, select which outdated skills to update when prompted.
+- In non-interactive mode, rerun the relevant pack subcommand with `--force` if you want to overwrite outdated installed skills.
+
+## Manifest not found or invalid
+
+- Missing manifest: run `sync` or `init`
+- Invalid manifest: repair/remove file and rerun
+
+## Status/output mismatches with lifecycle expectations
+
+- Reconcile `state.md`, `plan.md` review table, and `implementation.md`.
+- Ensure phase/review status has been updated after reviews and fix cycles.
+
+## Reference artifacts
+
+- `.oat/projects/<scope>/<project>/implementation.md`
+- `.oat/projects/<scope>/<project>/reviews/`
+- `packages/cli/src/commands/doctor/index.ts`
+- `packages/cli/src/commands/instructions/`

package/assets/public-package-versions.json

@@ -0,0 +1,6 @@
+{
+  "cli": "0.0.10",
+  "docs-config": "0.0.10",
+  "docs-theme": "0.0.10",
+  "docs-transforms": "0.0.10"
+}