@open-agent-toolkit/cli 0.0.10

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

@@ -0,0 +1,65 @@
+---
+title: Provider Sync
+description: 'User guide for adopting OAT across provider surfaces, managing drift, and syncing canonical assets into provider views.'
+---
+
+# Provider Sync
+
+Use this section when you want OAT to project a canonical rules-and-skills layout into provider-specific surfaces such as Claude, Cursor, Copilot, Gemini, or Codex.
+
+Provider sync is a standalone path. You can adopt it without using tracked OAT projects, and then layer workflow artifacts on top later if you need them.
+
+## Contents
+
+- [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.
+- [Providers](providers.md) - Provider-specific mappings, capabilities, and path conventions.
+- [Manifest and Drift](manifest-and-drift.md) - How OAT tracks synced state, stray files, and adoption decisions.
+- [Config](config.md) - Provider config model, enablement, and scope semantics.
+
+## What This Section Covers
+
+- canonical assets in `.agents/skills`, `.agents/agents`, and `.agents/rules`
+- derived provider views that should be treated as synced outputs unless explicitly adopted
+- drift detection, stray discovery, and adoption decisions when provider files change
+- command behavior for inspecting sync state, configuring providers, and writing synced output
+
+## Sync Flow
+
+```mermaid
+flowchart LR
+  CANON["Canonical assets\n.agents/ + .oat/"] --> STATUS["oat status"]
+  STATUS --> SYNC["oat sync"]
+  SYNC --> PROVIDERS["Provider views"]
+  PROVIDERS --> DRIFT{"Drift or strays?"}
+  DRIFT -->|No| OK["In sync"]
+  DRIFT -->|Yes| ADOPT["Adopt or reconcile"]
+  ADOPT --> CANON
+```
+
+## Typical Flow
+
+1. Run `oat init` to create canonical OAT directories and base config.
+2. Inspect current state with `oat status`.
+3. Enable or adjust providers with `oat providers ...` as needed.
+4. Run `oat sync` to materialize provider views from canonical assets.
+5. Re-run `oat status` after edits to confirm drift, adoption, or sync needs.
+
+## Canonical Rules and Adoption
+
+Recent OAT changes moved more behavior into canonical rules plus explicit adoption flows. In practice that means:
+
+- treat `.agents/` and `.oat/` content as the source of truth
+- use sync and adoption workflows to pull provider-side edits back into canonical form
+- avoid maintaining long-lived, hand-edited provider copies when the canonical source can own the change
+
+## Related Contributor Docs
+
+- [Hooks and Safety](../../contributing/hooks-and-safety.md) - Operational safety guidance for hooks, mutation commands, and synced changes.
+- [Writing Skills](../../contributing/skills.md) - Contributor guidance when sync behavior depends on skill authoring changes.
+
+## If You Are Trying To...
+
+- operate sync, drift, or provider configuration as a user, stay in this section
+- change hook behavior or understand mutation safety, jump to [Hooks and Safety](../../contributing/hooks-and-safety.md)
+- update canonical skills that later sync into provider views, jump to [Writing Skills](../../contributing/skills.md)

package/assets/docs/guide/provider-sync/manifest-and-drift.md

@@ -0,0 +1,55 @@
+---
+title: Manifest and Drift
+description: 'Manifest tracking, drift states, and stray adoption for canonical-to-provider reconciliation.'
+---
+
+# Manifest and Drift
+
+## Manifest locations
+
+- Project: `.oat/sync/manifest.json`
+- User: `~/.oat/sync/manifest.json`
+
+## Manifest purpose
+
+Tracks managed mappings so the CLI can:
+
+- detect drift safely
+- avoid deleting unmanaged provider content
+- execute scoped removals only for managed entries
+
+For transformed mappings such as project-scoped rules, the manifest stores hashes for the rendered provider output that was actually written, not the canonical source markdown. This keeps drift detection aligned with the on-disk managed file.
+
+## Drift states
+
+- `in_sync`
+- `drifted`
+- `missing`
+- `stray`
+
+`drifted` reasons currently include:
+
+- `modified`
+- `broken`
+- `replaced`
+
+Rendered rule files participate in the same drift states as other managed copies. If a provider rule file is edited directly, drift is computed against the expected rendered output for that provider.
+
+## Stray adoption
+
+`oat init` and `oat status` can offer adoption of unmanaged provider entries into canonical `.agents`.
+
+For rules, adoption maps provider-native files back into `.agents/rules/*.md`:
+
+- Claude: `.claude/rules/*.md`
+- Cursor: `.cursor/rules/*.mdc`
+- Copilot: `.github/instructions/*.instructions.md`
+
+After adoption, `oat sync` regenerates the managed provider copies from the canonical rule file.
+
+## Reference artifacts
+
+- `.oat/projects/<scope>/<project>/spec.md` (FR2, FR3, FR6)
+- `.oat/projects/<scope>/<project>/design.md`
+- `packages/cli/src/manifest/**`
+- `packages/cli/src/drift/**`

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

@@ -0,0 +1,67 @@
+---
+title: Providers
+description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemini, and Codex adapters.'
+---
+
+# Providers
+
+## Provider Quick Browse
+
+=== "Claude"
+
+    - Project: `.agents/skills` -> `.claude/skills`, `.agents/agents` -> `.claude/agents`, `.agents/rules` -> `.claude/rules`
+    - User: `~/.agents/skills` -> `~/.claude/skills`, `~/.agents/agents` -> `~/.claude/agents`
+    - Rule files stay `.md` and are rendered with Claude-compatible frontmatter when needed
+
+=== "Cursor"
+
+    - Project: `.agents/skills` -> `.cursor/skills`, `.agents/agents` -> `.cursor/agents`, `.agents/rules` -> `.cursor/rules`
+    - User: `~/.agents/skills` -> `~/.cursor/skills`, `~/.agents/agents` -> `~/.cursor/agents`
+    - Subagent invocation in Cursor is prompt-driven (`/name` or natural mention), not `subagent_type`
+    - Rule files render as `.cursor/rules/*.mdc`
+
+=== "Copilot"
+
+    - Project: `.agents/skills` -> `.github/skills`, `.agents/agents` -> `.github/agents`, `.agents/rules` -> `.github/instructions`
+    - User: `~/.agents/skills` -> `~/.copilot/skills`, `~/.agents/agents` -> `~/.copilot/agents`
+    - Rule files render as `.github/instructions/*.instructions.md`
+    - Comma-containing globs are not supported for Copilot rule sync because Copilot uses a comma-separated `applyTo` field
+
+=== "Gemini"
+
+    - Project: native-read canonical mappings (`.agents/skills` and `.agents/agents`)
+    - User: native-read canonical mappings (`~/.agents/skills` and `~/.agents/agents`)
+    - Gemini provider sync does not mirror to a provider-specific directory because canonical paths are read directly
+
+=== "Codex"
+
+    - Skills are native-read from `.agents/skills` (no mirrored sync action for skill mappings)
+    - Agents are native-read from `.agents/agents` for canonical source-of-truth workflows
+    - Canonical markdown agents in `.agents/agents/*.md` are exported to Codex runtime roles:
+      - `.codex/agents/<role>.toml`
+      - `.codex/config.toml` (`[features] multi_agent = true`, `[agents.<role>]` upserts)
+    - Codex role files include OAT managed provenance headers and are regenerated by `oat sync --scope project`
+    - Aggregate Codex config drift metadata (`aggregateConfigHash`) is emitted in sync/status codex extension output and intentionally not stored as a separate manifest row
+    - User-scope Codex role generation (`~/.codex`) remains deferred
+    - Codex multi-agent dispatch uses config-defined roles (`[agents.<name>]`) and `agent_type`
+    - Codex subagent workflows require `[features] multi_agent = true` in active Codex config layers
+
+## Scope rules
+
+- Project scope: skills + agents + rules
+- User scope: skills + agents (provider mappings vary by adapter)
+- Rules are project-scoped only in this release
+- Codex user-scope role generation under `~/.codex` remains deferred in this release
+
+## Adoption model
+
+- Stray adoption is available in `oat init` and `oat status`.
+- Adoption reconciles canonical plus the adopted provider first.
+- Rule adoption normalizes provider filenames back to canonical `.agents/rules/*.md` entries before cross-provider fanout.
+- Cross-provider fanout is explicit via `oat sync --scope all`.
+
+## Reference artifacts
+
+- `.oat/projects/<scope>/<project>/spec.md` (FR5)
+- `packages/cli/src/providers/**`
+- `packages/cli/src/providers/shared/adapter.utils.ts`

package/assets/docs/guide/provider-sync/scope-and-surface.md

@@ -0,0 +1,64 @@
+---
+title: Provider Interop CLI Scope and Surface
+description: 'Scope boundaries and design principles for canonical-to-provider asset management.'
+---
+
+# Provider Interop CLI Scope and Surface
+
+The provider interop CLI in `packages/cli` manages canonical agent assets under `.agents/` and reconciles provider-specific views.
+
+This capability is intentionally independent from OAT workflow artifacts. Teams can adopt provider interoperability usage (`status`, `sync`, `providers ...`) plus optional instruction-pointer integrity checks (`instructions validate/sync`) without using discovery/spec/design/plan/implement project workflows.
+
+## Scope
+
+- Canonical directories: `.agents/skills`, `.agents/agents`, `.agents/rules`
+- Managed provider views: `.claude/*`, `.cursor/*`, `.github/*`, `.copilot/*`, `.codex/*` (where applicable)
+- Native-read providers may use canonical `.agents/*` directly without mirrored provider directories (for example, Gemini and Codex canonical mappings)
+- Manifest tracking: `.oat/sync/manifest.json` (project) and `~/.oat/sync/manifest.json` (user)
+
+Rules are currently project-scoped canonical content. Unlike skills and agents, synced rule files for Claude, Cursor, and Copilot are rendered copies with provider-specific frontmatter and filename extensions.
+
+## Design principles
+
+- Mutate by default; `--dry-run` to preview
+- Explicit `--dry-run` for safe preview of mutations
+- Scoped destructive actions only for manifest-tracked entries
+- Cross-provider compatibility via adapters
+- Canonical `.agents/agents` is source of truth for subagents; provider views are derived
+- Canonical `.agents/rules` is source of truth for rules; provider rule files are derived rendered copies
+
+## Implemented command surface
+
+- `oat status`
+- `oat sync`
+- `oat providers list`
+- `oat providers inspect`
+- `oat providers set`
+
+## Adjacent CLI commands (commonly used with provider interop)
+
+- `oat init` (bootstrap canonical structure and sync config) — see `../getting-started.md`
+- `oat tools ...` (install/update/remove/list/inspect tools) — see `../tool-packs.md`
+- `oat doctor` (environment + skill-version diagnostics) — see `../cli-reference.md`
+
+## Provider enablement model
+
+- Project provider enablement is stored in `.oat/sync/config.json` (`providers.<name>.enabled`).
+- `oat init --scope project` (interactive) prompts for supported providers and persists explicit true/false values.
+- `oat sync --scope project` uses config-aware provider activation and can prompt to remediate detected mismatches.
+- Codex project-scope subagent sync is generated output (`.codex/agents/*.toml` + `.codex/config.toml`) computed at command layer after path-mapping sync.
+- Codex aggregate config drift is reported via sync/status extension metadata (`aggregateConfigHash`); it is not persisted as a separate manifest schema entry.
+- Codex user-scope role generation remains intentionally deferred in this release.
+
+## Non-interop namespaces in the same CLI
+
+- `oat project new <name>` (workflow/project scaffolding)
+- `oat instructions validate` / `oat instructions sync` (AGENTS.md to CLAUDE.md pointer integrity)
+- `oat internal validate-oat-skills` (internal maintenance)
+
+## Reference artifacts
+
+- `.oat/projects/<scope>/<project>/spec.md`
+- `.oat/projects/<scope>/<project>/design.md`
+- `.oat/projects/<scope>/<project>/plan.md`
+- `.oat/projects/<scope>/<project>/implementation.md`

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

@@ -0,0 +1,115 @@
+---
+title: Skills
+description: 'User-facing guide to OAT skill families, recommended entry points, and where contributor-facing skill authoring docs live.'
+---
+
+# Skills
+
+Use this section when you want to choose the right OAT skill for a task. If you are writing or changing skills, jump to the contributor docs instead.
+
+## Contents
+
+- [Writing Skills](../../contributing/skills.md) - Contributor guide to skill authoring, contracts, and governance.
+- [Docs Workflows](../documentation/workflows.md) - How docs CLI helpers and docs skills work together.
+
+## Key Skills by Use Case
+
+- Start a new tracked project: `oat-project-new` or `oat-project-quick-start`
+- Resume an existing project: `oat-project-open` and `oat-project-progress`
+- Execute a ready plan: `oat-project-implement`
+- Import an existing plan: `oat-project-import-plan`
+- Retroactively capture existing work: `oat-project-capture`
+- Run or receive reviews: `oat-project-review-provide`, `oat-project-review-receive`, or the non-project review variants
+- Manage the repo backlog and reference docs: `oat-pjm-add-backlog-item`, `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
+- Work on docs surfaces: `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
+- Research a topic in depth: `deep-research`
+- Analyze an artifact, codebase, or document: `analyze`
+- Compare options with domain-aware dimensions: `compare`
+- Verify a claim adversarially: `skeptic`
+- Merge multiple analysis artifacts: `synthesize`
+- Capture or refine ideas: `oat-idea-new`, `oat-idea-ideate`, `oat-idea-scratchpad`, `oat-idea-summarize`
+
+## If You Are Trying To...
+
+- choose the right skill for a task, stay in this guide page
+- write or update a skill, use [Writing Skills](../../contributing/skills.md)
+- understand how docs-specific skills fit with docs commands, use [Docs Workflows](../documentation/workflows.md)
+
+## Full Catalog
+
+=== "Project lifecycle"
+
+    - `oat-project-new`
+    - `oat-project-quick-start`
+    - `oat-project-import-plan`
+    - `oat-project-promote-spec-driven`
+    - `oat-project-open`
+    - `oat-project-clear-active`
+    - `oat-project-discover`
+    - `oat-project-spec`
+    - `oat-project-design`
+    - `oat-project-plan`
+    - `oat-project-plan-writing`
+    - `oat-project-implement`
+    - `oat-project-subagent-implement`
+    - `oat-project-progress`
+    - `oat-project-next`
+    - `oat-project-capture`
+    - `oat-project-reconcile`
+    - `oat-project-review-provide`
+    - `oat-project-review-receive`
+    - `oat-project-review-receive-remote`
+    - `oat-project-pr-progress`
+    - `oat-project-pr-final`
+    - `oat-project-document`
+    - `oat-project-complete`
+
+=== "Ideas"
+
+    - `oat-idea-new`
+    - `oat-idea-ideate`
+    - `oat-idea-scratchpad`
+    - `oat-idea-summarize`
+
+=== "Docs and instructions"
+
+    - `oat-docs-analyze`
+    - `oat-docs-apply`
+    - `oat-agent-instructions-analyze`
+    - `oat-agent-instructions-apply`
+
+=== "Review, backlog, and maintenance"
+
+    - `oat-review-provide`
+    - `oat-review-receive`
+    - `oat-review-receive-remote`
+    - `oat-repo-knowledge-index`
+    - `oat-repo-maintainability-review`
+    - `oat-pjm-add-backlog-item`
+    - `oat-pjm-update-repo-reference`
+    - `oat-pjm-review-backlog`
+    - `docs-completed-projects-gap-review`
+
+=== "Research"
+
+    - `deep-research`
+    - `analyze`
+    - `compare`
+    - `skeptic`
+    - `synthesize`
+
+=== "Scaffolding and utility"
+
+    - `oat-worktree-bootstrap`
+    - `oat-worktree-bootstrap-auto`
+    - `create-oat-skill`
+    - `create-agnostic-skill`
+    - `create-pr-description`
+    - `create-ticket`
+    - `codex-skill`
+
+## Discovery Source
+
+`AGENTS.md` is the session-facing registry. It should stay aligned with skill frontmatter and the canonical skill directories under `.agents/skills/`.
+
+Legacy compatibility note: `review-backlog` and `update-repo-reference` may still exist in some environments, but prefer the `oat-pjm-*` family for the current file-backed backlog/reference workflow.

package/assets/docs/guide/tool-packs.md

@@ -0,0 +1,167 @@
+---
+title: Tool Packs and Installed Assets
+description: 'Tool-pack lifecycle commands (oat tools) for installing, updating, and removing skills.'
+---
+
+# Tool Packs and Installed Assets
+
+This page covers CLI commands that manage bundled OAT tool packs and installed OAT skill/agent assets in canonical directories.
+
+## Bundled packs at a glance
+
+- `core` - foundational diagnostics and docs access (`oat-doctor`, `oat-docs`)
+- `docs` - docs and agent-instructions governance workflows
+- `workflows` - project lifecycle skills, reviewer agents, and core project templates
+- `ideas` - lightweight ideation and promotion flows
+- `utility` - review and repo-maintenance helpers
+- `project-management` - file-backed backlog/reference skills plus backlog and roadmap templates
+- `research` - research, analysis, comparison, and synthesis skills
+
+## `oat tools` command group
+
+The `oat tools` command group provides a unified interface for managing installed tools (skills and agents) across scopes.
+
+### `oat tools list`
+
+Purpose:
+
+- List all installed tools with version, pack membership, scope, and update status
+
+Key behavior:
+
+- Scans installed skills and agents across project and user scopes
+- Displays version, pack (`core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`, `custom`), and status (`current`, `outdated`, `newer`, `not-bundled`)
+- Supports `--scope` filtering and `--json` output
+
+### `oat tools outdated`
+
+Purpose:
+
+- Show only tools that have available updates (status `outdated`)
+
+Key behavior:
+
+- Filters scan results to tools where the installed version is older than the bundled version
+- Displays installed and available versions side by side
+- Supports `--scope` filtering and `--json` output
+
+### `oat tools info <name>`
+
+Purpose:
+
+- Show detailed information about a single installed tool
+
+Key behavior:
+
+- Displays name, type (skill/agent), version, bundled version, pack, scope, and status
+- Reports whether the tool is invocable (for skills) and whether an update is available
+- Returns exit code 1 if the tool is not found in any scope
+
+### `oat tools install`
+
+Purpose:
+
+- Install bundled OAT tool packs (`core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`)
+
+Key behavior:
+
+- Same pack selection and install flow as `oat init tools`
+- Pack-oriented install subcommands: `core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`
+- Tracks installed vs bundled skill versions and reports outdated skills
+- Interactive runs can prompt to update selected outdated skills
+- Auto-sync runs automatically after successful install (provider views are updated)
+- Use `--no-sync` to skip auto-sync
+
+### `oat tools update`
+
+Purpose:
+
+- Update installed tools to the latest bundled versions
+
+Key behavior:
+
+- Accepts a tool name, `--pack <pack>`, or `--all` (mutually exclusive)
+- Compares installed versions against bundled versions and copies updated assets
+- For `--pack <pack>` and `--all`, an already-installed pack is reconciled to include newly added bundled skills or agents in that same scope
+- Dry-run mode with `--dry-run`; auto-sync after mutations by default
+- Use `--no-sync` to skip auto-sync
+- Reports tools that are already current, newer than bundled, or not bundled (custom)
+
+### `oat tools remove`
+
+Purpose:
+
+- Remove installed tools (skills and agents)
+
+Key behavior:
+
+- Accepts a tool name, `--pack <pack>`, or `--all` (mutually exclusive)
+- Removes skill directories and agent `.md` files from canonical locations
+- Dry-run mode with `--dry-run`; auto-sync after mutations by default
+- Use `--no-sync` to skip auto-sync
+
+## Core pack
+
+The `core` pack contains foundational diagnostic and documentation skills:
+
+- **oat-doctor** — Setup diagnostics with two modes: check mode (terse `brew doctor`-style warnings with fix commands) and summary mode (full dashboard of installed packs, config values, and sync status).
+- **oat-docs** — Interactive Q&A skill backed by locally-bundled OAT documentation at `~/.oat/docs/`.
+
+Key behavior:
+
+- Core pack always installs at **user scope** (`~/.agents/skills/`), regardless of the `--scope` flag. This ensures core skills are available in any directory.
+- Core is checked by default in the `oat init tools` guided setup.
+- Installation also bundles OAT documentation to `~/.oat/docs/` for the oat-docs skill.
+- `oat tools update --pack core` refreshes both skills and `~/.oat/docs/` documentation.
+- `oat tools update --all` also refreshes `~/.oat/docs/` when an installed core pack is reconciled.
+
+## Docs pack
+
+The `docs` pack contains active documentation and instruction-governance
+workflows:
+
+- **oat-docs-analyze** — Analyze a docs surface for contract coverage, nav
+  drift, stale claims, and coverage gaps.
+- **oat-docs-apply** — Apply only approved, evidence-backed docs-analysis
+  recommendations.
+- **oat-agent-instructions-analyze** — Evaluate `AGENTS.md` and provider
+  instruction coverage, quality, and drift.
+- **oat-agent-instructions-apply** — Generate or update approved instruction
+  files from an analysis artifact.
+
+Key behavior:
+
+- Docs pack installs at the selected scope, typically `project`.
+- It complements the `core` pack: `oat-docs` answers questions from bundled
+  docs, while the `docs` pack adds analyze/apply workflows.
+- `oat tools install docs` is the preferred install path; `oat init tools docs`
+  remains available for backward compatibility.
+- `oat tools update --pack docs` and `oat tools remove --pack docs` manage the
+  workflow skills as a unit.
+
+### Auto-sync behavior
+
+All mutation commands (`install`, `update`, `remove`) automatically run `oat sync --scope <scope>` after successful operations. This ensures provider views stay in sync with canonical assets without manual intervention.
+
+Use `--no-sync` on any mutation command to skip this step.
+
+## Legacy commands
+
+### `oat init tools`
+
+The `oat init tools` command remains available for backward compatibility. It has the same install behavior as `oat tools install` but does not include auto-sync — you must run `oat sync --scope ...` manually after install.
+
+### `oat remove`
+
+The `oat remove` command group remains available for backward compatibility. It provides skill removal with dry-run/apply semantics and managed provider-view cleanup.
+
+- `oat remove skill <name>` — remove one installed skill by name
+- `oat remove skills --pack <pack>` — remove all installed skills from a bundled pack
+
+These commands mutate by default; use `--dry-run` to preview deletions.
+
+Related docs:
+
+- Bootstrap (`oat init`): `getting-started.md`
+- Provider sync (`oat status`, `oat sync`, `oat providers ...`): `provider-sync/index.md`
+- Diagnostics and local-state commands: `cli-reference.md`

package/assets/docs/guide/workflow/artifacts.md

@@ -0,0 +1,44 @@
+---
+title: Project Artifacts
+description: 'Project artifact contracts: state.md, spec.md, design.md, plan.md, and implementation.md.'
+---
+
+# Project Artifacts
+
+Project artifacts live under `.oat/projects/<scope>/<project>/`.
+
+## Core artifacts
+
+- `state.md`: lifecycle state and checkpoint metadata
+- `discovery.md`: problem framing, constraints, solution space exploration (for exploratory requests), and discovery outcomes
+- `spec.md`: requirements + acceptance criteria
+- `design.md`: architecture and implementation approach (full in spec-driven mode; optional lightweight version in quick mode covering architecture, components, and testing strategy)
+- `plan.md`: phase/task breakdown and review tracking
+- `implementation.md`: execution log, verification, final summary
+- `summary.md`: institutional memory artifact — generated from project artifacts at closeout, used as PR description source and archive cover page
+
+Mode-sensitive notes:
+
+- `state.md` includes workflow mode metadata (`spec-driven`, `quick`, `import`) for routing.
+- `spec.md` and `design.md` are required in spec-driven mode, optional in quick/import mode. Quick mode offers a lightweight `design.md` (architecture, components, testing strategy) at a post-discovery decision point.
+- `plan.md` remains canonical execution artifact across all modes.
+
+## Supporting artifacts
+
+- `summary.md`: generated by `oat-project-summary` — re-runnable, tracks its own state via frontmatter for incremental updates after revisions
+- `reviews/*.md`: phase/final review files
+- `pr/*.md`: generated PR descriptions
+- `references/imported-plan.md`: preserved source plan for import mode
+
+## Contract
+
+Artifacts are the project system of record; automation and routing should derive from these files, not memory.
+
+## Reference artifacts
+
+- `.oat/templates/*.md`
+- `.oat/projects/<scope>/<project>/spec.md`
+- `.oat/projects/<scope>/<project>/design.md`
+- `.oat/projects/<scope>/<project>/plan.md`
+- `.oat/projects/<scope>/<project>/implementation.md`
+- `.oat/projects/<scope>/<project>/summary.md`

package/assets/docs/guide/workflow/hill-checkpoints.md

@@ -0,0 +1,53 @@
+---
+title: Human-in-the-Loop Lifecycle (HiLL) Checkpoints
+description: 'Checkpoint configuration and behavior for pauseable, human-in-the-loop lifecycle execution.'
+---
+
+# Human-in-the-Loop Lifecycle (HiLL) Checkpoints
+
+OAT supports two checkpoint classes:
+
+- Workflow phase checkpoints
+- Plan phase checkpoints
+
+## Workflow checkpoints (`state.md`)
+
+Frontmatter keys:
+
+- `oat_hill_checkpoints`
+- `oat_hill_completed`
+
+Example:
+
+```yaml
+oat_hill_checkpoints: ['discovery', 'spec', 'design']
+oat_hill_completed: ['discovery']
+```
+
+## Plan phase checkpoints (`plan.md`)
+
+Frontmatter key written after implementation confirmation:
+
+- `oat_plan_hill_phases`
+
+Semantics:
+
+- Field absent: valid before the first `oat-project-implement` run confirms checkpoint selection. Planning may intentionally leave the field unset until that first execution starts.
+- Empty list: checkpoint after every phase boundary, but only after implementation has confirmed the choice and written `oat_plan_hill_phases: []` into `plan.md`.
+- Explicit list: checkpoint only after completing the named phases (`p01`, `p04`, etc).
+
+On the first implementation run, `oat-project-implement` must summarize every plan phase, state the total phase count and final phase ID, and then ask an explicit three-option checkpoint question:
+
+- Stop after each phase
+- Stop after specific phases
+- Stop only after the final phase is completed
+
+It then writes the confirmed value into `plan.md`. If the field is later missing during a resumed implementation run, treat that as bookkeeping drift rather than as an implicit default.
+
+Listed phases are where you stop **after completing them**, not before. `["p03"]` means "complete p03, then pause" — not "pause before starting p03." Setting the last phase ID (e.g., `["p03"]` when p03 is final) means "stop only at the end of implementation."
+
+## Reference artifacts
+
+- `.oat/templates/plan.md`
+- `.oat/projects/<scope>/<project>/plan.md`
+- `.oat/projects/<scope>/<project>/state.md`

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

@@ -0,0 +1,34 @@
+---
+title: Workflow & Projects
+description: 'Guide to OAT lifecycle execution, project artifacts, reviews, PR flow, and repo-analysis helpers.'
+---
+
+# Workflow & Projects
+
+Use this section when you want tracked, resumable work on top of the base CLI and provider-sync layers.
+
+OAT workflow is optional. The CLI remains useful on its own, but projects add explicit artifacts, stable task IDs, review loops, and resumable implementation state for longer-running work.
+
+## Contents
+
+- [Lifecycle](lifecycle.md) - End-to-end flow from discovery through implementation and completion.
+- [HiLL Checkpoints](hill-checkpoints.md) - Human-in-the-Loop Lifecycle configuration and approval behavior.
+- [Artifacts](artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
+- [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 Analysis](repo-analysis.md) - Repo-wide PR comment collection and triage workflows.
+
+## Choose the Right Workflow Layer
+
+- Use the CLI only when you want direct commands without tracked artifacts.
+- Use quick mode when the work is bounded and requirements are already clear.
+- Use spec-driven mode when requirements or design decisions need explicit baseline artifacts.
+- Use import mode when a plan already exists outside OAT and you want tracked execution.
+
+## Core Project Concepts
+
+- `state.md` tracks the current phase, task pointer, blockers, and review readiness.
+- `plan.md` owns the stable task sequence and HiLL checkpoint configuration.
+- `implementation.md` records outcomes, verification, and resume notes as work progresses.
+- reviews and PR artifacts provide the quality gate between implementation and merge.