@open-agent-toolkit/cli 0.0.10 → 0.0.18

package/assets/docs/{guide/provider-sync → provider-sync}/commands.md

@@ -9,13 +9,19 @@ description: 'CLI commands for provider status, sync, and drift management.'
 
 These command definitions inherit the cross-cutting CLI conventions in:
 
-- [`../../contributing/design-principles.md`](../../contributing/design-principles.md)
+- [`../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 init` (bootstrap): `../cli-utilities/bootstrap.md`
+- `oat tools ...` (tool-pack lifecycle — install, update, remove, list, info): `../cli-utilities/tool-packs.md`
+- `oat doctor` (cross-cutting diagnostics): `../reference/cli-reference.md`
+
+## Quick Look
+
+- What it does: defines the day-to-day provider-sync command surface for inspecting state, reconciling provider views, and changing provider enablement.
+- When to use it: after you have canonical assets in place and need to check sync state, write provider views, or change provider config.
+- Primary commands: `oat status`, `oat sync`, `oat providers list`, `oat providers inspect`, `oat providers set`
 
 ## `oat status`
 

package/assets/docs/{guide/provider-sync → provider-sync}/config.md

@@ -74,4 +74,4 @@ It is read by:
 
 - [`commands.md`](commands.md)
 - [`manifest-and-drift.md`](manifest-and-drift.md)
-- [`../../reference/oat-directory-structure.md`](../../reference/oat-directory-structure.md)
+- [`../reference/oat-directory-structure.md`](../reference/oat-directory-structure.md)

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

@@ -0,0 +1,43 @@
+---
+title: Provider Sync
+description: Standalone adoption lane for canonical assets, provider views, sync commands, and drift management.
+---
+
+# Provider Sync
+
+Provider Sync is the OAT lane for keeping a canonical rules-and-skills layout in sync with provider-specific surfaces such as Claude, Cursor, Copilot, Gemini, or Codex.
+
+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.
+
+## 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.
+
+## 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
+
+## 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`.
+
+## Common Tasks
+
+- Understand the canonical/provider-view model in [Scope and Surface](scope-and-surface.md).
+- Learn provider-specific mappings in [Providers](providers.md).
+- Diagnose drift and adoption behavior in [Manifest and Drift](manifest-and-drift.md).
+- Adjust provider enablement and scope behavior in [Sync Config](config.md).
+
+## 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.
+- [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.
+- [Sync Config](config.md) - Provider config model, enablement, and scope semantics.

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

@@ -5,6 +5,14 @@ description: 'Manifest tracking, drift states, and stray adoption for canonical-
 
 # Manifest and Drift
 
+This page explains how OAT remembers what it manages and how it distinguishes clean sync state from drift, missing files, or unmanaged strays.
+
+## Quick Look
+
+- What it does: describes the manifest contract behind provider sync and the drift/adoption model built on top of it.
+- When to use it: when `oat status` shows drift or strays and you need to understand why OAT thinks a file is managed, missing, or adoptable.
+- Primary commands: `oat status`, `oat init`, `oat sync`
+
 ## Manifest locations
 
 - Project: `.oat/sync/manifest.json`

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

@@ -0,0 +1,38 @@
+---
+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/{guide/provider-sync → provider-sync}/scope-and-surface.md

@@ -37,9 +37,9 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 
 ## 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`
+- `oat init` (bootstrap canonical structure and sync config) — see `../cli-utilities/bootstrap.md`
+- `oat tools ...` (install/update/remove/list/inspect tools) — see `../cli-utilities/tool-packs.md`
+- `oat doctor` (environment + skill-version diagnostics) — see `../reference/cli-reference.md`
 
 ## Provider enablement model
 

package/assets/docs/quickstart.md

@@ -1,162 +1,79 @@
 ---
 title: Quickstart
-description: 'Quick-start guides for interop-only, provider-agnostic tooling, and optional workflow adoption.'
+description: 'Start-here guide for choosing the right OAT adoption path.'
 ---
 
 # Quickstart
 
-## Prerequisites
+Use this page to choose the OAT path that matches what you are actually trying to do.
 
-- Node.js `22.17.0+`
-- pnpm `10.13.1+`
+This page is intentionally lightweight. It is not the full command manual. Once you choose a path, continue into the owning section for the deeper operational detail.
 
-## Path A: Interop-only (CLI)
+## Choose a Path
 
-```bash
-pnpm install
-pnpm run cli -- --help
-```
+### Provider Sync
 
-### Initialize canonical structure
+Use this path when you want canonical skills, agents, and rules to stay aligned across provider surfaces such as Claude, Cursor, Copilot, Gemini, or Codex.
 
-```bash
-pnpm run cli -- init --scope project
-```
+Best fit:
 
-Creates canonical directories and can offer stray adoption/hook installation.
+- you want cross-provider sync and drift checks
+- you care about canonical-to-provider asset management
+- you do not necessarily need tracked project workflows
 
-### Check status and sync
+Continue here:
 
-```bash
-pnpm run cli -- status --scope all
-pnpm run cli -- sync --scope all
-```
+- [Provider Sync](provider-sync/index.md)
 
-Notes:
+### Agentic Workflows
 
-- `sync` mutates by default; use `--dry-run` to preview changes without writing.
+Use this path when you want tracked, resumable implementation work with explicit lifecycle artifacts, reviews, and handoff-friendly state.
 
-### Install or update OAT tool packs (optional)
+Best fit:
 
-```bash
-pnpm run cli -- tools install
-# or install just the project-management pack
-pnpm run cli -- tools install project-management
-```
+- you want structured project execution
+- you want lifecycle artifacts like `state.md`, `plan.md`, and `implementation.md`
+- you want a workflow layer on top of the base CLI/tooling
 
-Notes:
+Continue here:
 
-- 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.
+- [Agentic Workflows](workflows/index.md)
 
-### Remove installed skills or packs (optional)
+### Docs Tooling
 
-```bash
-pnpm run cli -- remove skill oat-idea-scratchpad
-pnpm run cli -- remove skills --pack utility
-```
+Use this path when you are bootstrapping or maintaining a documentation surface with OAT.
 
-Notes:
+Best fit:
 
-- `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.
+- you need docs app setup or maintenance workflows
+- you care about docs navigation, docs commands, and docs-specific analysis/apply flows
+- you want the docs-system contract rather than the broader workflow layer
 
-### Validate instruction pointers
+Continue here:
 
-```bash
-pnpm run cli -- instructions validate
-pnpm run cli -- instructions sync
-```
+- [Docs Tooling](docs-tooling/index.md)
 
-Notes:
+### CLI Utilities
 
-- `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.
+Use this path when you want general OAT CLI help outside the dedicated provider-sync, workflows, and docs-tooling lanes.
 
-### Additional CLI commands
+Best fit:
 
-```bash
-# Mode-aware project scaffold
-pnpm run cli -- project new my-project --mode quick
+- you want bootstrap/setup guidance
+- you want tool-pack, configuration, local-state, or utility command guidance
+- you want a general CLI surface map rather than one specific product lane
 
-# 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
+Continue here:
 
-# 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
+- [CLI Utilities](cli-utilities/index.md)
 
-# Internal oat-* skill validation (primary path)
-pnpm oat:validate-skills
-```
+## If You Are Unsure
 
-### Worktree setup
+Start with the path that best matches the primary thing you need right now.
 
-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.
+- If you are trying to sync canonical assets across tools, choose Provider Sync.
+- If you are trying to run a tracked implementation workflow, choose Agentic Workflows.
+- If you are working on the docs system itself, choose Docs Tooling.
+- If you mainly need command-line setup or utility guidance, choose CLI Utilities.
 
-### 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`.
+You can adopt more than one lane over time. OAT is designed so these sections can be used together or independently.

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

@@ -0,0 +1,35 @@
+---
+title: CLI Reference
+description: Scannable reference for the current OAT CLI surface, with links to the deeper owning sections for each command family.
+---
+
+# CLI Reference
+
+Use this page when you need a quick map of the OAT CLI rather than the full command-by-command docs. It is intentionally shallow: each section points to the owning page that documents the detailed behavior.
+
+The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oat tools`, docs commands, and repo-analysis commands without adopting the full project workflow.
+
+## Contents
+
+- [CLI Bootstrap](../cli-utilities/bootstrap.md) - Bootstrap a repo with `oat init`, guided setup, and initial provider adoption.
+- [Tool Packs](../cli-utilities/tool-packs.md) - Install, update, inspect, and remove bundled OAT skills and agents.
+- [Config and Local State](../cli-utilities/config-and-local-state.md) - Config, backlog, local paths, diagnostics, and related utility commands.
+- [Docs Tooling Commands](../docs-tooling/commands.md) - Docs app scaffolding, migration, index generation, and nav sync.
+- [Provider Sync](../provider-sync/index.md) - Sync behavior, provider capabilities, config, and drift management.
+- [Agentic Workflows](../workflows/index.md) - Tracked project execution, skills, ideas, and workflow routing.
+- [Workflow & Projects](../workflows/projects/index.md) - Project lifecycle, artifacts, reviews, PR flow, and state-machine docs.
+- [Repository Analysis](../workflows/projects/repo-analysis.md) - Detailed `oat repo pr-comments ...` behavior.
+
+## Command Groups
+
+| Command group                                   | What it covers                                                                            | Go deeper                                                            |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `oat init`                                      | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.       | [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 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, 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, execution mode, and project/artifact cleanup commands.               | [Workflow & Projects](../workflows/projects/index.md)                |
+| `oat repo ...`                                  | Repository-level analysis workflows, currently centered on PR comments.                   | [Repository Analysis](../workflows/projects/repo-analysis.md)        |

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

@@ -12,7 +12,6 @@ OAT docs navigation is generated from each directory `index.md`, not from hand-m
 - 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
 
@@ -49,5 +48,5 @@ Generated behavior:
 
 ## If You Are Trying To...
 
-- learn the docs workflow or docs commands as a user, start with [Documentation](../guide/documentation/index.md)
+- learn the docs workflow or docs commands as a user, start with [Docs Tooling](../docs-tooling/index.md)
 - contribute or restructure docs in this repo, pair this contract with [Contributing to OAT Docs](../contributing/documentation.md)

package/assets/docs/reference/index.md

@@ -5,12 +5,13 @@ description: 'Durable reference material for OAT file locations, docs contracts,
 
 # Reference
 
-Use this section for durable facts and contracts that should stay stable even as the guide and contributing flows evolve.
+Use this section for durable facts and contracts that should stay stable even as the user-facing adoption lanes and contributor flows evolve.
 
-Contributor how-to material now lives under `contributing/`, and audience-routing guidance lives under `guide/`.
+Contributor how-to material now lives under `contributing/`, and user-facing routing now lives in the top-level adoption lanes.
 
 ## Contents
 
+- [CLI Reference](cli-reference.md) - Shallow map of the OAT command surface with links to owning sections.
 - [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.
@@ -24,6 +25,6 @@ Contributor how-to material now lives under `contributing/`, and audience-routin
 
 ## 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
+- [CLI Reference](cli-reference.md) for the command-surface map
+- [Docs Tooling](../docs-tooling/index.md) for docs app setup and workflow guidance
 - [Contributing](../contributing/index.md) for code, docs, and skill-authoring practices

package/assets/docs/workflows/index.md

@@ -0,0 +1,40 @@
+---
+title: Agentic Workflows
+description: Standalone adoption lane for tracked OAT projects, workflow lifecycle execution, ideas, and workflow-oriented skills.
+---
+
+# Agentic Workflows
+
+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.
+
+## What This Section Is
+
+This section explains when workflow mode is worth the overhead, how OAT projects move through lifecycle phases, and how ideas, skills, reviews, and PR flow fit into that model.
+
+## Who It's For
+
+- Teams doing multi-session or multi-phase work that benefits from tracked artifacts
+- Users who want explicit discovery, planning, implementation, and review state
+- Repos that need a repeatable human-in-the-loop execution model
+
+## 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.
+
+## Common Tasks
+
+- Capture or refine early work in [Ideas](ideas/index.md).
+- Understand how tracked projects progress in [Workflow & Projects](projects/index.md).
+- Learn the artifact contract in [Artifacts](projects/artifacts.md).
+- Understand review and PR expectations in [Reviews](projects/reviews.md) and [PR Flow](projects/pr-flow.md).
+
+## 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/overview.md

@@ -0,0 +1,38 @@
+---
+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

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

@@ -0,0 +1,37 @@
+---
+title: Workflow & Projects
+description: 'Lifecycle, project artifacts, reviews, PR flow, and repository analysis for tracked OAT projects.'
+---
+
+# Workflow & Projects
+
+Use this section when you want the detailed lifecycle and artifact model behind tracked OAT projects.
+
+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.
+
+## 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.
+
+## Start Here
+
+- Start with [Lifecycle](lifecycle.md) for the end-to-end flow.
+- Read [Artifacts](artifacts.md) once you need the file contract behind project execution.
+- Use [HiLL Checkpoints](hill-checkpoints.md) when you want to understand pause/approval behavior.
+
+## Common Tasks
+
+- Understand lifecycle order and alternate lanes in [Lifecycle](lifecycle.md).
+- Learn the artifact system of record in [Artifacts](artifacts.md).
+- Understand lifecycle and review transitions in [State Machine](state-machine.md).
+- Learn review and PR expectations in [Reviews](reviews.md) and [PR Flow](pr-flow.md).
+
+## Go Deeper
+
+- [Lifecycle](lifecycle.md) - End-to-end flow from discovery through 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.

package/assets/docs/{guide/workflow → workflows/projects}/lifecycle.md

@@ -23,6 +23,12 @@ OAT lifecycle order:
 
 **Shortcut:** `oat-project-next` reads project state and invokes the correct next skill automatically — use it instead of remembering which skill comes next. Complements `oat-project-progress` (which is read-only diagnostic).
 
+## Quick Look
+
+- What it does: explains the end-to-end lifecycle for tracked OAT projects, including alternate quick and import lanes.
+- When to use it: when you need the actual project execution model, not just a high-level overview of workflow mode.
+- Primary entry points: `oat-project-new`, `oat-project-quick-start`, `oat-project-import-plan`, `oat-project-implement`
+
 ## Lifecycle Map
 
 ```mermaid

package/assets/docs/{guide/workflow → workflows/projects}/repo-analysis.md

@@ -7,6 +7,12 @@ description: 'Repository-level analysis commands for collecting and triaging PR
 
 The `oat repo` command group provides repository-level analysis and insight tools. These commands operate across merged pull requests rather than on individual PRs.
 
+## Quick Look
+
+- What it does: collects and triages review-comment data across merged pull requests so you can mine recurring feedback patterns.
+- When to use it: when you want repo-wide review insight rather than project-by-project execution guidance.
+- Primary commands: `oat repo pr-comments collect`, `oat repo pr-comments triage-collection`
+
 ## Commands
 
 | Command                                  | Purpose                                                              |

package/assets/docs/{guide/workflow → workflows/projects}/state-machine.md

@@ -5,6 +5,14 @@ description: 'Workflow and review state transitions across lifecycle phases and
 
 # State Machine
 
+This page is the compact contract for how project lifecycle state and review state advance across a tracked OAT project.
+
+## Quick Look
+
+- What it does: defines the allowed lifecycle and review-state transitions recorded in `state.md` and `plan.md`.
+- When to use it: when you need to debug lifecycle routing, review posture, or why a project is not advancing to the next phase.
+- Primary artifacts: `state.md`, `plan.md`, `implementation.md`
+
 ## State Transition Map
 
 ```mermaid

package/assets/docs/{guide → workflows}/skills/index.md

@@ -10,7 +10,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 ## 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.
+- [Docs Workflows](../../docs-tooling/workflows.md) - How docs CLI helpers and docs skills work together.
 
 ## Key Skills by Use Case
 
@@ -33,7 +33,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
 - 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)
+- understand how docs-specific skills fit with docs commands, use [Docs Workflows](../../docs-tooling/workflows.md)
 
 ## Full Catalog
 

package/assets/public-package-versions.json

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