@open-agent-toolkit/cli 0.0.10 → 0.0.18

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Stang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @open-agent-toolkit/cli
 
-Open Agent Toolkit command-line interface for provider sync, workflow tooling, docs scaffolding, and project hygiene.
+Open Agent Toolkit command-line interface for provider sync, docs tooling, workflow utilities, and diagnostics.
 
 ## Install
 
@@ -8,38 +8,27 @@ Open Agent Toolkit command-line interface for provider sync, workflow tooling, d
 npm install -g @open-agent-toolkit/cli
 ```
 
-You can also run it without a global install:
+Run without a global install:
 
 ```bash
 npx @open-agent-toolkit/cli --help
 ```
 
-## Usage
+## Quick Start
 
 ```bash
 oat init --scope project
 oat status --scope all
 oat sync --scope all
 oat config describe
-oat config describe archive.s3Uri
-oat project archive sync
-oat project archive sync my-project
-oat docs init --app-name my-docs
 ```
 
-Archive lifecycle settings are managed through shared repo config:
+Additional useful entry points:
 
-- `archive.s3Uri`
-- `archive.s3SyncOnComplete`
-- `archive.summaryExportPath`
-
-Use `oat config describe` to inspect which file owns a setting and which command surface mutates it. Completion writes dated archive snapshots to S3 and exports dated summary snapshots when those archive settings are configured.
-
-## Related Packages
-
-- `@open-agent-toolkit/docs-config`
-- `@open-agent-toolkit/docs-theme`
-- `@open-agent-toolkit/docs-transforms`
+- `oat tools install`
+- `oat docs init --app-name my-docs`
+- `oat project archive sync`
+- `oat doctor`
 
 ## Requirements
 
@@ -47,4 +36,7 @@ Use `oat config describe` to inspect which file owns a setting and which command
 
 ## Docs
 
-Repository and docs: <https://github.com/voxmedia/open-agent-toolkit>
+- [Docs Home](https://voxmedia.github.io/open-agent-toolkit/)
+- [CLI Utilities](https://voxmedia.github.io/open-agent-toolkit/cli-utilities)
+- [Provider Sync](https://voxmedia.github.io/open-agent-toolkit/provider-sync)
+- [Reference](https://voxmedia.github.io/open-agent-toolkit/reference)

package/assets/docs/{guide/getting-started.md → cli-utilities/bootstrap.md}

@@ -7,6 +7,12 @@ description: 'Foundational setup via oat init for canonical directories, provide
 
 This page covers foundational CLI setup commands that prepare OAT structures and configuration before provider sync or tool-pack workflows.
 
+## Quick Look
+
+- What it does: explains the initial `oat init` setup flow and the optional guided setup path that configures packs, local paths, and provider sync.
+- When to use it: when you are first introducing OAT into a repo or need to re-run the guided setup path on an existing checkout.
+- Primary commands: `oat init`, `oat init --setup`, `oat init --scope project`
+
 ## `oat init`
 
 Purpose:
@@ -59,5 +65,5 @@ oat init --scope project
 Related commands:
 
 - `oat tools ...` (tool-pack install, update, remove, list, info): `tool-packs.md`
-- `oat local ...`, `oat doctor`, and other utility commands: `cli-reference.md`
-- `oat status` / `oat sync` (provider sync): `provider-sync/index.md`
+- `oat local ...`, `oat doctor`, and other utility commands: `config-and-local-state.md`
+- `oat status` / `oat sync` (provider sync): `../provider-sync/index.md`

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -0,0 +1,84 @@
+---
+title: Config and Local State
+description: Utility command groups for config discovery, backlog helpers, local paths, instruction integrity, and diagnostics.
+---
+
+# Config and Local State
+
+This page covers the general-purpose OAT command groups that support configuration discovery, local-only state, backlog maintenance, instruction integrity, and diagnostics.
+
+Use these commands when you need operational support around the toolkit rather than one of the deeper product lanes.
+
+## `oat backlog ...`
+
+Use the `oat backlog` group when you want direct CLI support for the file-backed backlog under `.oat/repo/reference/backlog/`.
+
+- `oat backlog init` - scaffold `.oat/repo/reference/backlog/` with starter files and directories for a fresh repo
+- `oat backlog generate-id <filename>` - generate a unique backlog ID from a filename seed
+- `oat backlog generate-id <filename> --created-at <timestamp>` - generate a reproducible ID for a known creation timestamp
+- `oat backlog regenerate-index` - rebuild the managed backlog index table from item frontmatter
+
+Run `oat backlog init` first when the local backlog scaffold does not exist yet in a fresh repo. This command group is primarily used by the `oat-pjm-*` project-management skills, but it is also available directly when you need to inspect or repair backlog metadata by hand.
+
+## `oat local ...`
+
+`oat local` manages local-only, gitignored paths that still need to follow you between the main repo and worktrees.
+
+Common examples:
+
+- `.oat/ideas/`
+- `.oat/**/reviews/archived/`
+
+Available commands:
+
+- `oat local status` - show whether configured local paths exist and are gitignored
+- `oat local apply` - write the managed `.gitignore` section for configured paths
+- `oat local sync` - copy local paths between the main repo and a worktree
+- `oat local add` / `oat local remove` - maintain the `localPaths` config entries
+
+Use this when you want archived review history or idea scratchpads to persist locally without being committed.
+
+## `oat config ...`
+
+Use `oat config` for repo runtime config inspection and supported key mutation.
+
+- `oat config get <key>` - read one resolved config value
+- `oat config set <key> <value>` - update a supported shared or repo-local key
+- `oat config list` - show the resolved command-surface values with source information
+- `oat config describe` - list supported config surfaces and keys across shared repo, repo-local, user, and sync/provider config
+- `oat config describe <key>` - show file location, scope, default, mutability, and owning command for one key
+
+Archive lifecycle settings live here as shared repo config:
+
+- `archive.s3Uri`
+- `archive.s3SyncOnComplete`
+- `archive.summaryExportPath`
+
+When archive settings are configured, completion uploads dated archive snapshots to S3 and exports dated summary snapshots into the configured summary reference directory.
+
+Use these reference pages for file ownership and schema details:
+
+- [File Locations](../reference/file-locations.md)
+- [`.oat` Directory Structure](../reference/oat-directory-structure.md)
+- [Sync Config (`.oat/sync/config.json`)](../provider-sync/config.md)
+
+## `oat instructions ...`
+
+These commands validate and repair pointer integrity between `AGENTS.md` and sibling `CLAUDE.md` files.
+
+- `oat instructions validate` - read-only integrity check
+- `oat instructions sync` - preview or apply pointer repairs
+
+Use this command group when instruction files drift after manual edits or generated updates.
+
+## Repo state helpers
+
+- `oat state refresh` - rebuild the `.oat/state.md` dashboard for the repo
+- `oat index init` - generate a lightweight `project-index.md` for orientation
+
+## Internal helpers and diagnostics
+
+- `oat internal validate-oat-skills` - validate `oat-*` skill contracts and metadata
+- `oat doctor` - run environment and setup diagnostics, including installed-vs-bundled skill version checks
+
+`oat doctor` is the quickest way to confirm that your runtime, directory structure, and installed OAT assets are healthy before deeper debugging. The `/oat-doctor` skill (installed via the core pack) provides richer diagnostics with check and summary modes, including config explanations sourced from bundled documentation.

package/assets/docs/{guide → cli-utilities}/configuration.md

@@ -14,7 +14,7 @@ For the deep file-by-file reference, see:
 
 - [File Locations](../reference/file-locations.md)
 - [`.oat` Directory Structure](../reference/oat-directory-structure.md)
-- [Sync Config (`.oat/sync/config.json`)](provider-sync/config.md)
+- [Sync Config (`.oat/sync/config.json`)](../provider-sync/config.md)
 
 ## The four config surfaces
 
@@ -117,7 +117,7 @@ Use:
 - `oat config describe ...` to understand sync keys
 - `oat providers set ...` to mutate sync/provider settings
 
-For the provider-sync schema details, use [Sync Config (`.oat/sync/config.json`)](provider-sync/config.md).
+For the provider-sync schema details, use [Sync Config (`.oat/sync/config.json`)](../provider-sync/config.md).
 
 ## Recommended workflow
 

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

@@ -0,0 +1,41 @@
+---
+title: CLI Utilities
+description: Standalone adoption lane for general OAT CLI surfaces outside provider sync, docs tooling, and tracked workflows.
+---
+
+# CLI Utilities
+
+CLI Utilities is the OAT lane for the useful command surface that does not primarily belong to Provider Sync, Docs Tooling, or tracked workflow lifecycle execution.
+
+Use this section when you want bootstrap guidance, tool-pack lifecycle details, configuration help, and general-purpose command references.
+
+## What This Section Is
+
+This section collects the command groups that help you initialize OAT, manage installed packs, inspect local or config state, and use the wider CLI without implying that you are adopting provider sync or tracked workflows.
+
+## Who It's For
+
+- Users getting OAT set up in a repo
+- Teams managing installed tool packs and local config
+- People who need a general command map without diving into workflow lifecycle docs
+
+## Start Here
+
+- Read [Overview](overview.md) to see what command groups live here and how this section relates to the other adoption lanes.
+- Use [CLI Bootstrap](bootstrap.md) when you are starting with `oat init`.
+- Go to [Tool Packs](tool-packs.md) when you are managing bundled OAT packs and installed assets.
+
+## Common Tasks
+
+- Bootstrap OAT in a repo with [CLI Bootstrap](bootstrap.md).
+- Manage installed packs in [Tool Packs](tool-packs.md).
+- Adjust settings in [Configuration](configuration.md).
+- Use [Config and Local State](config-and-local-state.md) for the utility command groups that support inspection and diagnostics.
+
+## Go Deeper
+
+- [Overview](overview.md) - What belongs in CLI Utilities and when to use this section.
+- [CLI Bootstrap](bootstrap.md) - Foundational `oat init` guidance outside provider-sync-specific onboarding.
+- [Tool Packs](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
+- [Configuration](configuration.md) - OAT configuration guidance.
+- [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.

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

@@ -0,0 +1,33 @@
+---
+title: CLI Utilities Overview
+description: Plain-language explanation of the OAT CLI surface that lives outside provider sync, docs tooling, and tracked workflows.
+---
+
+# CLI Utilities Overview
+
+Not every OAT command belongs to a single product lane. Some commands are general-purpose setup, configuration, pack-management, or diagnostic utilities that support the rest of the toolkit without being specific to provider sync, docs tooling, or tracked workflow execution.
+
+That is what this section covers.
+
+## What Lives Here
+
+- bootstrap and setup flows such as `oat init`
+- bundled pack management through `oat tools`
+- general configuration guidance
+- utility command groups for config, local state, diagnostics, and related inspection flows
+
+## When To Use This Section
+
+Use CLI Utilities when:
+
+- you are first setting up OAT in a repo
+- you need to install or update OAT packs
+- you are looking for configuration or local-state inspection help
+- you need the general CLI surface without committing to one of the deeper lanes yet
+
+## Continue Here
+
+- [CLI Bootstrap](bootstrap.md) for initial setup
+- [Tool Packs](tool-packs.md) for pack lifecycle management
+- [Configuration](configuration.md) for config semantics
+- [Config and Local State](config-and-local-state.md) for the wider utility command map

package/assets/docs/{guide → cli-utilities}/tool-packs.md

@@ -7,6 +7,12 @@ description: 'Tool-pack lifecycle commands (oat tools) for installing, updating,
 
 This page covers CLI commands that manage bundled OAT tool packs and installed OAT skill/agent assets in canonical directories.
 
+## Quick Look
+
+- What it does: explains how bundled OAT packs are installed, updated, inspected, and removed.
+- When to use it: when you need to add capabilities to a repo, update installed skills, or understand which packs own which tools.
+- Primary commands: `oat tools list`, `oat tools install`, `oat tools update`, `oat tools remove`
+
 ## Bundled packs at a glance
 
 - `core` - foundational diagnostics and docs access (`oat-doctor`, `oat-docs`)
@@ -162,6 +168,6 @@ 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`
+- Bootstrap (`oat init`): `bootstrap.md`
+- Provider sync (`oat status`, `oat sync`, `oat providers ...`): `../provider-sync/index.md`
+- Diagnostics and local-state commands: `config-and-local-state.md`

package/assets/docs/contributing/code.md

@@ -69,8 +69,10 @@ not the steady-state path.
 - Publish the four public packages manually the first time under the new npm
   org scope.
 - After those packages exist in npm, configure npm trusted publishing for this
-  repository so `.github/workflows/release.yml` can become the steady-state
-  release path without an npm token.
+  repository so `.github/workflows/release.yml` can stay the steady-state
+  top-level release path without an npm token.
+- In steady state, `release.yml` owns automatic releases from `main` and manual
+  reruns for an existing release tag; `ci.yml` remains validation-only.
 - Use `.github/workflows/release-dry-run.yml` to validate the GitHub path after
   the npm trust relationship is configured.
 

package/assets/docs/contributing/design-principles.md

@@ -119,6 +119,6 @@ For CLI behavior changes:
 
 ## Related Docs
 
-- CLI Reference: [`../guide/cli-reference.md`](../guide/cli-reference.md)
-- Provider sync commands: [`../guide/provider-sync/commands.md`](../guide/provider-sync/commands.md)
-- Provider sync manifest and drift: [`../guide/provider-sync/manifest-and-drift.md`](../guide/provider-sync/manifest-and-drift.md)
+- CLI Reference: [`../reference/cli-reference.md`](../reference/cli-reference.md)
+- Provider sync commands: [`../provider-sync/commands.md`](../provider-sync/commands.md)
+- Provider sync manifest and drift: [`../provider-sync/manifest-and-drift.md`](../provider-sync/manifest-and-drift.md)

package/assets/docs/contributing/documentation.md

@@ -27,13 +27,21 @@ Documentation should ship with the code it explains. This page covers the core d
    pnpm build:docs
    ```
 
-3. Run Markdown linting:
+3. Check rendered links against a local or deployed docs host:
+
+   ```bash
+   pnpm docs:check-links
+   # or target a local docs server explicitly
+   pnpm docs:check-links --url http://127.0.0.1:3000/open-agent-toolkit/
+   ```
+
+4. Run Markdown linting:
 
    ```bash
    pnpm --filter oat-docs docs:lint
    ```
 
-4. Run Markdown formatting:
+5. Run Markdown formatting:
 
    ```bash
    pnpm --filter oat-docs docs:format
@@ -60,10 +68,10 @@ Documentation should ship with the code it explains. This page covers the core d
 ## Related Guides
 
 - [Markdown Features](markdown-features.md)
-- [Documentation User Guide](../guide/documentation/index.md)
+- [Docs Tooling](../docs-tooling/index.md)
 
 ## If You Are Trying To...
 
-- use docs commands or bootstrap a docs app, start with [Documentation User Guide](../guide/documentation/index.md)
+- use docs commands or bootstrap a docs app, start with [Docs Tooling](../docs-tooling/index.md)
 - follow the authoring contract for `index.md` and navigation, stay on this page and then read [Docs Index Contract](../reference/docs-index-contract.md)
 - understand supported markdown patterns, use [Markdown Features](markdown-features.md)

package/assets/docs/{guide/documentation/quickstart.md → docs-tooling/add-docs-to-a-repo.md}

@@ -161,4 +161,4 @@ Important:
 
 - [`commands.md`](commands.md)
 - [`workflows.md`](workflows.md)
-- [`../../reference/docs-index-contract.md`](../../reference/docs-index-contract.md)
+- [`../reference/docs-index-contract.md`](../reference/docs-index-contract.md)

package/assets/docs/{guide/documentation → docs-tooling}/commands.md

@@ -9,6 +9,12 @@ OAT includes a dedicated docs command family for bootstrapping and maintaining
 documentation apps. Two frameworks are supported: **Fumadocs** (Next.js-based)
 and **MkDocs Material**.
 
+## Quick Look
+
+- What it does: documents the docs-specific CLI surface for scaffolding apps, migrating markdown, generating indexes, and syncing navigation.
+- When to use it: when you already know you are working on a docs surface and need the exact command-level behavior.
+- Primary commands: `oat docs init`, `oat docs migrate`, `oat docs generate-index`, `oat docs nav sync`
+
 ## Command surface
 
 | Command                   | Purpose                                                                              |
@@ -50,6 +56,7 @@ Supported flags:
 - `--target-dir <path>`
 - `--framework <fumadocs|mkdocs>` (default: `fumadocs` in non-interactive mode)
 - `--description <text>` (site description, optional)
+- `--lint <none|markdownlint-cli2>`
 - `--format <oxfmt|none>`
 - `--yes`
 
@@ -139,7 +146,7 @@ oat docs nav sync --target-dir apps/oat-docs
 
 Related reference:
 
-- [`../../reference/docs-index-contract.md`](../../reference/docs-index-contract.md)
+- [`../reference/docs-index-contract.md`](../reference/docs-index-contract.md)
 
 ## `oat docs analyze` and `oat docs apply`
 

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

@@ -0,0 +1,40 @@
+---
+title: Docs Tooling
+description: Standalone adoption lane for docs app setup, docs commands, and docs maintenance workflows.
+---
+
+# Docs Tooling
+
+Docs Tooling is the OAT lane for setting up, maintaining, and restructuring a documentation surface with OAT.
+
+Use this section when you are adopting the docs app workflow in a repo, maintaining generated navigation, or using the analyze/apply docs workflows.
+
+## What This Section Is
+
+This section explains how OAT supports docs surfaces, how the index contract works in practice, and which commands or workflows to use for bootstrapping, maintenance, and restructure work.
+
+## Who It's For
+
+- Repos adding a docs app for the first time
+- Teams maintaining directory indexes and generated navigation
+- Users who want a controlled analyze/apply flow for docs changes
+
+## Start Here
+
+- Read [Overview](overview.md) for the docs-tooling model and where Fumadocs versus MkDocs matters.
+- Use [Add Docs to a Repo](add-docs-to-a-repo.md) when you are bootstrapping a docs surface.
+- Go to [Commands](commands.md) when you already have a docs app and need the CLI surface.
+
+## Common Tasks
+
+- Bootstrap docs app support with [Add Docs to a Repo](add-docs-to-a-repo.md).
+- Maintain docs structure with [Commands](commands.md).
+- Use the governed workflow in [Workflows](workflows.md).
+- Check the underlying docs contract in [Docs Index Contract](../reference/docs-index-contract.md).
+
+## Go Deeper
+
+- [Overview](overview.md) - What docs tooling is for and how the docs contract fits together.
+- [Add Docs to a Repo](add-docs-to-a-repo.md) - Bootstrap a docs app and adopt the docs workflow in a repo.
+- [Commands](commands.md) - Docs CLI surface for init, migration, index generation, and nav sync.
+- [Workflows](workflows.md) - How the docs CLI helpers pair with analyze/apply workflows.

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

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

package/assets/docs/{guide/documentation → docs-tooling}/workflows.md

@@ -62,6 +62,6 @@ to open every page.
 ## Related docs
 
 - [`commands.md`](commands.md)
-- [`quickstart.md`](quickstart.md)
-- [`../../reference/docs-index-contract.md`](../../reference/docs-index-contract.md)
-- [`../../contributing/skills.md`](../../contributing/skills.md)
+- [`add-docs-to-a-repo.md`](add-docs-to-a-repo.md)
+- [`../reference/docs-index-contract.md`](../reference/docs-index-contract.md)
+- [`../contributing/skills.md`](../contributing/skills.md)

package/assets/docs/guide/concepts.md

@@ -33,7 +33,7 @@ flowchart LR
 
 Use these docs next:
 
-- [Provider Sync](provider-sync/index.md)
+- [Provider Sync](../provider-sync/index.md)
 - [Reference](../reference/index.md)
 
 ## Sync, Drift, and Adoption
@@ -42,8 +42,8 @@ Use these docs next:
 
 Use these docs next:
 
-- [Provider Sync Commands](provider-sync/commands.md)
-- [Manifest and Drift](provider-sync/manifest-and-drift.md)
+- [Provider Sync Commands](../provider-sync/commands.md)
+- [Manifest and Drift](../provider-sync/manifest-and-drift.md)
 
 ## Scopes
 
@@ -51,8 +51,8 @@ Most OAT operations run in one of three scopes: `project`, `user`, or `all`. Pro
 
 Use these docs next:
 
-- [Scope and Surface](provider-sync/scope-and-surface.md)
-- [CLI Reference](cli-reference.md)
+- [Scope and Surface](../provider-sync/scope-and-surface.md)
+- [CLI Reference](../reference/cli-reference.md)
 
 ## Skills and CLI Commands
 
@@ -60,7 +60,7 @@ Skills are structured workflow instructions stored in `.agents/skills`, while CL
 
 Use these docs next:
 
-- [Skills](skills/index.md)
+- [Skills](../workflows/skills/index.md)
 - [Contributing Skills](../contributing/skills.md)
 
 ## The Three Usage Modes
@@ -76,7 +76,7 @@ These layers stack. You can stay at the interop layer, use only the tooling laye
 Use these docs next:
 
 - [Quickstart](../quickstart.md)
-- [Workflow & Projects](workflow/index.md)
+- [Workflow & Projects](../workflows/projects/index.md)
 
 ## Human-in-the-Loop Lifecycle
 
@@ -84,5 +84,5 @@ The workflow system supports explicit checkpoints so a project can pause at sele
 
 Use these docs next:
 
-- [Workflow & Projects](workflow/index.md)
-- [Hill Checkpoints](workflow/hill-checkpoints.md)
+- [Workflow & Projects](../workflows/projects/index.md)
+- [Hill Checkpoints](../workflows/projects/hill-checkpoints.md)

package/assets/docs/guide/index.md

@@ -5,16 +5,19 @@ description: User-facing guide for operating OAT across provider sync, docs tool
 
 # User Guide
 
-Use this section when you want to operate OAT as a user of the toolkit rather than contribute to the codebase itself.
+This page is now a compatibility router.
 
-## Contents
+The old catch-all User Guide is being split into clearer adoption lanes so new users can choose the part of OAT that matches what they actually need.
 
-- [Core Concepts](concepts.md) - Mental model for canonical assets, provider views, scopes, skills, and workflow layers.
-- [Getting Started](getting-started.md) - Foundational CLI setup and guided `oat init` usage.
-- [Provider Sync](provider-sync/index.md) - Provider interoperability, drift, sync, and config behavior.
-- [Tool Packs](tool-packs.md) - Install, update, and remove bundled OAT tool packs.
-- [Documentation](documentation/index.md) - Docs app setup, docs commands, and docs workflow entry points.
-- [Workflow & Projects](workflow/index.md) - Lifecycle, project artifacts, reviews, PR flow, and repo analysis docs.
-- [Skills](skills/index.md) - Skill families and recommended entry points by use case.
-- [Ideas](ideas/index.md) - Lightweight brainstorming and idea capture flow.
-- [CLI Reference](cli-reference.md) - Scannable command-group reference for the current OAT CLI surface.
+## Canonical Sections
+
+- [Provider Sync](../provider-sync/index.md) - Provider interoperability, drift, sync, and config behavior.
+- [Agentic Workflows](../workflows/index.md) - Tracked projects, ideas, workflow skills, and lifecycle execution.
+- [Docs Tooling](../docs-tooling/index.md) - Docs app setup, docs commands, and docs workflow entry points.
+- [CLI Utilities](../cli-utilities/index.md) - Bootstrap, tool packs, configuration, and general CLI surfaces.
+- [Reference](../reference/index.md) - Durable contracts and reference material.
+
+## Legacy Pages Still Under Guide
+
+- [Core Concepts](concepts.md) - High-level mental model while concept material is being redistributed.
+- This guide bucket is being retired. Use the canonical top-level sections above for active documentation.

package/assets/docs/index.md

@@ -15,27 +15,34 @@ OAT is organized as three distinct capabilities that can be used together or ind
 
 ## Contents
 
-- [Quickstart](quickstart.md) - Shared entry point for interop-only, tooling, and workflow adoption.
-- [User Guide](guide/index.md) - User-facing guide for provider sync, docs tooling, workflow execution, skills, and ideas.
+- [Quickstart](quickstart.md) - Canonical Start Here page for choosing the right OAT adoption path.
+- [Provider Sync](provider-sync/index.md) - Canonical section for provider interoperability, drift management, and canonical-to-provider sync.
+- [Agentic Workflows](workflows/index.md) - Canonical section for tracked project workflows, ideas, lifecycle execution, and workflow-oriented skills.
+- [Docs Tooling](docs-tooling/index.md) - Canonical section for docs app setup, docs commands, and docs maintenance workflows.
+- [CLI Utilities](cli-utilities/index.md) - Canonical section for general OAT CLI surfaces outside provider sync, docs tooling, and tracked workflows.
 - [Contributing](contributing/index.md) - Contributor-facing guide for code, docs, markdown features, and skill authoring.
 - [Reference](reference/index.md) - Durable reference material for operating and maintaining OAT.
 
-## Choose a usage path
-
-- Provider sync and CLI users:
-  - Start with [`quickstart.md`](quickstart.md)
-  - Then [`guide/provider-sync/index.md`](guide/provider-sync/index.md) and [`guide/cli-reference.md`](guide/cli-reference.md)
-- Docs-tooling users:
-  - Start with [`guide/documentation/index.md`](guide/documentation/index.md)
-  - Then [`guide/documentation/commands.md`](guide/documentation/commands.md)
-- Workflow users:
-  - Start with [`quickstart.md`](quickstart.md)
-  - Then [`guide/workflow/index.md`](guide/workflow/index.md), [`guide/skills/index.md`](guide/skills/index.md), and [`reference/index.md`](reference/index.md)
-- Contributors:
-  - Start with [`contributing/index.md`](contributing/index.md)
-  - Then route into code, docs, markdown features, or skill authoring guidance
-- Idea and backlog users:
-  - Start with [`guide/ideas/index.md`](guide/ideas/index.md)
+## Why OAT Exists
+
+Teams often need some combination of:
+
+- provider-specific agent instructions that stay aligned from one tool to another
+- reusable skills and helper tooling that do not depend on one provider
+- a more structured workflow for longer-running implementation work
+
+OAT exists to make those layers work together without forcing teams to adopt all of them at once.
+
+## Start Here
+
+If you are new to OAT, start with [Quickstart](quickstart.md).
+
+That page is the canonical path-selection guide. Use it to choose whether you need:
+
+- provider sync
+- agentic workflows
+- docs tooling
+- general CLI utilities
 
 ## Source-of-truth hierarchy
 
@@ -43,3 +50,12 @@ OAT is organized as three distinct capabilities that can be used together or ind
 2. Skill behavior contracts: `.agents/skills/*/SKILL.md`
 3. OAT templates and runtime state: `.oat/templates/**`, `.oat/sync/**`, `.oat/config.json`, `.oat/config.local.json`
 4. Repo reference records: `.oat/repo/**`
+
+## Where To Go Next
+
+- New to OAT: [Quickstart](quickstart.md)
+- Need canonical-to-provider sync: [Provider Sync](provider-sync/index.md)
+- Need tracked project execution: [Agentic Workflows](workflows/index.md)
+- Need docs app or docs maintenance tooling: [Docs Tooling](docs-tooling/index.md)
+- Need general command-line help: [CLI Utilities](cli-utilities/index.md)
+- Need stable contracts and reference material: [Reference](reference/index.md)