@open-agent-toolkit/cli 0.3.13 → 0.3.15

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

@@ -0,0 +1,174 @@
+---
+title: Quickstart
+description: 'Install the OAT CLI, get a first result in an existing repository, and choose what to add next.'
+---
+
+# Quickstart
+
+In about ten minutes you install the OAT command-line tool, try it safely in a
+repository you already have, and choose what to add.
+
+## What you need
+
+- Node.js 22.17 or newer
+- Git 2.31 or newer
+- An existing Git repository
+
+OAT does not run an up-front Git version check. Git compatibility is evaluated
+best-effort by each command, and a missing or unsupported Git operation makes
+that command fail with a system error.
+
+## Install the CLI
+
+```bash
+npm install --global @open-agent-toolkit/cli
+oat --version
+```
+
+## Your first result
+
+From the root folder of your repository, run:
+
+```bash
+oat init --scope project
+oat status --scope project
+```
+
+`--scope project` targets the current repository. OAT calls this choice a
+scope; `user` scope targets your home directory instead.
+
+In a terminal, `oat init` asks which providers to enable (saved in
+`.oat/sync/config.json`), whether to add an optional pre-commit hook that
+warns, without blocking, when provider views are out of date, and whether to
+run guided setup. For this first run, answer no to guided setup: it installs
+tool packs in your home directory. Apart from your answers,
+`oat init --scope project` writes only these files:
+
+- empty folders `.agents/skills/`, `.agents/agents/` and `.agents/rules/`,
+  which hold your canonical assets: the one copy of each skill, agent and rule
+  that you edit;
+- `.oat/sync/manifest.json`, OAT's record of the files it manages;
+- a block marked `# OAT core` at the end of `.gitignore` and `.gitattributes`,
+  creating either file if needed and leaving your existing lines unchanged.
+
+It does not touch your home directory or your Git remote, and it commits
+nothing. For every file OAT creates, what to commit, and how to remove it all, see [What OAT Writes](../reference/what-oat-writes.md).
+
+`oat status --scope project` reports provider views: the files or links that
+each provider (a coding agent tool such as Claude Code, Cursor or Codex) reads.
+A new repository has none yet, so it prints `No managed entries found.`
+
+Leaving out `--scope project` also writes under your home directory
+(`~/.oat/sync/manifest.json` and an empty `~/.agents/skills/`).
+
+## Then choose what to add
+
+Each path works on its own. Code blocks run in a terminal. Names written as
+`/name` are agent skills, typed in your coding agent's chat, not in a shell;
+Codex uses `$name`. A skill is a set of instructions your agent follows on
+request, and a tool pack is a bundle of skills and templates that installs
+together.
+
+### Provider Sync
+
+You edit each skill, agent and rule once in `.agents/`, and OAT creates the
+files each coding tool reads and reports drift. It needs no tracked projects.
+
+Add a skill first: a folder in `.agents/skills/` with a `SKILL.md` file (see
+step 4 of [Pilot Provider Sync with One Team](../provider-sync/pilot-with-a-team.md)).
+With no skills, sync reports `No changes required.`
+
+```bash
+oat providers set --scope project --enabled claude
+oat sync --scope project --dry-run
+oat sync --scope project
+```
+
+The first command saves your choice in `.oat/sync/config.json` (other
+providers are `cursor`, `codex`, `copilot` and `gemini`). The second previews.
+The third creates views, such as a link in `.claude/skills/` for each skill in
+`.agents/skills/`, and records them in `.oat/sync/manifest.json`. A provider
+folder already in the repository, such as `.claude/`, is enough for sync to
+create its views. Read next: [Provider Sync](../provider-sync/index.md).
+
+### Reusable skills
+
+You get skills for research, comparing options, code review, ideas and
+brainstorming, installed for you across all your repositories. You do not need
+`oat init` for this.
+
+```bash
+oat tools install --scope user
+oat sync --scope user
+```
+
+With no pack name, this installs all eight packs (core, ideas, docs,
+workflows, utility, research, brainstorm and project-management) under
+`~/.agents/` and `~/.oat/`, and sync links them into tools it finds in your
+home directory, such as `~/.claude/skills/`. To install one pack, name it:
+`oat tools install research --scope user`. The core pack (`oat-docs` and
+`oat-doctor`) always installs for your user, never into a repository. Read
+next: [Skills](../skills/index.md) and
+[Tool Packs and Installed Assets](tool-packs.md).
+
+### Workflows
+
+You track longer work as a resumable project with reviews, approval points and
+files such as `plan.md`, `implementation.md` and `state.md`.
+
+```bash
+oat tools install workflows --scope project
+```
+
+Claude Code reads skills only from `.claude/skills/`, while Cursor, Codex,
+Copilot and Gemini read `.agents/skills/` directly. If you use Claude Code and
+have not enabled it, run `oat providers set --scope project --enabled claude`
+and then `oat sync --scope project` after installing, or the `/oat-...` skills
+will not appear in it.
+
+Then type `/oat-project-quick-start` in your coding agent.
+
+This adds workflow skills and agents under `.agents/`, templates, scripts and
+project folders under `.oat/`, and `.oat/config.json`. New tracked projects
+default to the synced scope, which stores project files on a separate Git ref
+and pushes it to your `origin` remote; read
+[Before your first project](../workflows/projects/planning/starting-projects.md#before-your-first-project)
+first. Read next: [Choose a Workflow](../workflows/choose-workflow.md).
+
+### Docs tooling
+
+You set up plain Markdown or a docs site, then have your agent analyze it and
+apply the changes you approve.
+
+```bash
+oat tools install docs --scope project
+```
+
+As with Workflows, if you use Claude Code and have not enabled it, run
+`oat providers set --scope project --enabled claude` and
+`oat sync --scope project` after installing.
+
+Then type `/oat-docs-bootstrap` in your coding agent.
+
+This adds seven docs skills under `.agents/skills/`, templates under
+`.oat/templates/`, a script under `.oat/scripts/`, and `.oat/config.json`.
+Read next: [Docs Tooling](../docs-tooling/index.md).
+
+For setup options, configuration and every command, see
+[CLI Bootstrap](bootstrap.md),
+[Config and Local State](../reference/config-and-local-state.md) and the
+[CLI Reference](../reference/cli-reference.md).
+
+## If you are unsure
+
+Start with the path that matches what you need right now.
+
+- To sync canonical assets across tools, choose Provider Sync.
+- For help with one task, such as researching a decision, choose Reusable
+  skills.
+- To run a tracked implementation workflow, choose Workflows.
+- To work on documentation, choose Docs tooling.
+- For command-line setup or utility guidance, use the links just above.
+
+You can adopt more than one path over time; they work together or on their
+own.

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

@@ -7,6 +7,15 @@ 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.
 
+> **In short**
+>
+> - A tool pack is a bundle of OAT skills (instructions your coding agent follows), agents, templates and scripts that installs as one unit.
+> - There are eight packs: `core` (setup diagnostics and a local copy of these docs), `workflows` (tracked projects), `docs` (documentation upkeep), `utility` (reviews and maintenance helpers), `research` (evidence gathering and comparison), `ideas` and `brainstorm` (exploring ideas), and `project-management` (backlog and decisions kept in the repository).
+> - Install one pack with an explicit scope: `oat tools install research --scope project` puts it in this repository, and `oat tools install research --scope user` puts it in your home directory. Leave out the pack name, as in `oat tools install --scope project`, to install every pack; in an interactive terminal it first asks which packs to include.
+> - The `core` pack only ever installs under your home directory, whatever `--scope` you pass. [Where packs install](#where-packs-install) shows what that means for each command.
+> - Installing the `project-management` pack is not the same as adopting project management: the repository's planning files are created only when someone runs `oat pjm init`.
+> - Read next: [Choosing packs and their ownership](#choosing-packs-and-their-ownership), [Install vs. initialize](#install-vs-initialize), [Upgrading from an earlier CLI](#upgrading-from-an-earlier-cli), and [What OAT Writes](../reference/what-oat-writes.md) for every file each command creates.
+
 ## Quick Look
 
 - What it does: explains how bundled OAT packs are installed, updated, inspected, and removed.
@@ -29,8 +38,40 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 
 Every reusable pack is a complete user-scope capability. On a **fresh** install
 each pack lands at user scope by default, so capabilities follow you across
-repositories. `core` is the one pack that is user-only: passing a conflicting
-explicit `--scope project` is rejected rather than silently ignored.
+repositories. `core` is the one pack that is user-only; see
+[Where packs install](#where-packs-install) for what happens when you ask for
+project scope.
+
+### Where packs install
+
+The `--scope` option of `oat tools install` and `oat tools remove` lists `all`
+as its default in `--help`. For `oat tools install`, that default does not
+mean both scopes:
+
+- With no `--scope`, a pack that is not installed yet is installed under your
+  home directory (user scope: `~/.agents/` and `~/.oat/`). A pack that is
+  already installed keeps the scope it has. An interactive install of several
+  packs asks where each one should go and suggests the same answer.
+- With `--scope project`, the pack is installed in this repository
+  (`.agents/` and `.oat/`). With `--scope user`, it is installed under your
+  home directory.
+- With `--scope all` given explicitly for one pack, as in
+  `oat tools install docs --scope all`, that pack is installed at both scopes.
+
+The `core` pack can only live under your home directory:
+
+- `oat tools install --scope project`, with no pack name, installs the other
+  seven packs in this repository and still installs `core` under your home
+  directory.
+- `oat tools install core --scope project` exits successfully and prints
+  `Installed core tool pack.`, but it writes nothing, neither in the
+  repository nor in your home directory. Run `oat tools install core` (or add
+  `--scope user`) to install it.
+- `oat tools remove --all --scope project` fails with
+  `Pack core does not allow project scope`, and so does
+  `oat tools remove --all` with no `--scope`. Remove the project copies one
+  pack at a time with `oat tools remove --pack <pack> --scope project`, and
+  remove the home-directory copies with `oat tools remove --all --scope user`.
 
 On a **re-install**, existing placement wins. A pack already installed at
 project scope stays at project scope; the fresh-install default never migrates
@@ -184,7 +225,7 @@ oat tools update --pack utility --scope user
 ```
 
 It never falls back to a source checkout or copies core logic into the
-workflows pack. See [Explainer Kit](../workflows/skills/explainer-kit.md) for
+workflows pack. See [Explainer Kit](../skills/explainer-kit.md) for
 the usage and lifecycle contract.
 
 ## Scope, intent, and inventory
@@ -449,12 +490,17 @@ adoption**, and the two are tracked independently:
   fresh install, so `~/.agents/skills/` and `~/.oat/templates/` receive the
   managed assets and no repository file is touched.
 - **Initialize (adoption)**: `oat pjm init` instantiates the two-layer working
-  repo-reference surface under `.oat/repo/`, creates repository guidance only
-  when the root `AGENTS.md` is absent, and records explicit adoption in
-  `.oat/config.json` as `pjm.initialized: true` with a `pjm.schemaVersion`.
-  When the root file or a contained symlink already exists, adoption completes
-  independently and OAT prints a manual project-management/decision patch
-  without changing that file.
+  repo-reference surface under `.oat/repo/` and records explicit adoption in
+  `.oat/config.json` as `pjm.initialized: true` with a `pjm.schemaVersion`. It
+  also writes the `OAT project-management` and `OAT decisions` guidance
+  sections to the root `AGENTS.md`. When no root `AGENTS.md` exists, it
+  creates the file with both sections. When the file (or a contained symlink
+  to one) exists, it appends whichever of the two sections is absent and
+  leaves the rest of the file unchanged. It does not rewrite a section that is
+  already there but differs from the managed version, and it does not write to
+  a file with more than one hard link or that it cannot write. In those cases
+  adoption still completes, the existing file is left unchanged, OAT prints a
+  manual patch for you to apply, and the command exits with status 1.
 
 Having the pack installed does **not** mean this repository uses PJM. Adoption
 is a per-repository decision recorded by `oat pjm init`:
@@ -471,7 +517,7 @@ The canonical surface splits active operational state (under `pjm/`) from durabl
 - `.oat/repo/reference/decisions/` (file-per-record decisions plus a generated index)
 - AGENTS guides at `.oat/repo/AGENTS.md`, `.oat/repo/pjm/AGENTS.md`, and `.oat/repo/reference/AGENTS.md`
 
-Decisions are now file-per-record under `reference/decisions/` (created and indexed with the [`oat decision`](config-and-local-state.md#oat-decision-) command group), replacing the legacy single `decision-record.md`. Repos still on the old `reference/` layout can migrate with `oat pjm migrate`.
+Decisions are now file-per-record under `reference/decisions/` (created and indexed with the [`oat decision`](../reference/config-and-local-state.md#oat-decision-) command group), replacing the legacy single `decision-record.md`. Repos still on the old `reference/` layout can migrate with `oat pjm migrate`.
 
 Migration eligibility is independent of where the `project-management` pack is
 installed. `oat pjm migrate` resolves the repository's adoption state for
@@ -551,7 +597,7 @@ Useful options:
 - `--repo-root <path>` - scaffold a different repo-reference root instead of `.oat/repo`
 - `--json` - emit a machine-readable result with created and skipped paths
 
-Backlog scaffolding is delegated to the lower-level [`oat backlog init`](config-and-local-state.md#oat-backlog-) helper. Use `oat pjm init` for the full PJM repo-reference surface, and use `oat backlog init` directly only when you need to create or repair the backlog sub-surface by itself.
+Backlog scaffolding is delegated to the lower-level [`oat backlog init`](../reference/config-and-local-state.md#oat-backlog-) helper. Use `oat pjm init` for the full PJM repo-reference surface, and use `oat backlog init` directly only when you need to create or repair the backlog sub-surface by itself.
 
 ### `oat tools list`
 
@@ -726,7 +772,7 @@ Key behavior:
 - Interactive installs show each pack's current install location in the picker so already-installed packs are visible before you submit
 - Installing is **additive**: choosing a scope for a pack never removes it from another scope. A pack installed at user scope plus a project install ends up at `project + user`, not moved
 - For every pack that allows both scopes (`ideas`, `docs`, `workflows`, `utility`, `project-management`, `research`, `brainstorm`), the interactive flow offers a per-pack end-state selector (`project`, `user`, or `both`) defaulting to the pack's current placement; leaving the default makes no changes for that pack
-- Fresh installs default to **user scope** for every pack; existing installs keep their current placement
+- Fresh installs default to **user scope** for every pack; existing installs keep their current placement. The `--scope` default shown in `--help` is `all`, but with no `--scope` a pack that is not installed yet goes under your home directory; see [Where packs install](#where-packs-install)
 - `oat init --setup` uses this same additive scope resolver. In guided setup, choosing to customize scope reaches the per-pack selector; choosing the recommended defaults, or running non-interactively, applies additive per-pack defaults without removals
 - Every pack's fresh-install default is user scope (`defaultScope` in the release manifest); existing installs keep their current placement on re-install, so a re-install never moves a pack between scopes or creates a second copy at the other one. This applies to the per-pack subcommands too: a bare `oat tools install docs` in a repository where `docs` is already at project scope stays at project scope, and only an explicit `--scope` overrides that
 - Removing a pack from a scope happens only when you explicitly choose a narrower end-state in the interactive flow (e.g. a pack at `both` set to `project` only). All staged removals are shown in a single change summary and applied only after one batch confirmation — declining makes no changes
@@ -785,6 +831,7 @@ Purpose:
 Key behavior:
 
 - Accepts a tool name, `--pack <pack>`, or `--all` (mutually exclusive)
+- `--all` covers every pack, including `core`, so it works only with `--scope user`. `oat tools remove --all --scope project`, and `oat tools remove --all` with no `--scope`, fail with `Pack core does not allow project scope`; remove project-scope packs one at a time with `--pack <pack> --scope project`
 - Removal is planned from the release manifest, so it deletes **only** assets OAT manages for that pack and scope
 - Retained by design: project-scope repository template overrides, mutable seed files (`.oat/ideas/…`, `.oat/projects-root`, project `.gitkeep` files), and shared scripts still owned by another installed pack. Retained owner data is reported rather than silently skipped
 - Already-missing files are not an error
@@ -916,7 +963,7 @@ The `core` pack contains foundational diagnostic and documentation skills:
 
 Key behavior:
 
-- Core pack always installs at **user scope** (`~/.agents/skills/`). It is the only pack whose sole allowed scope is `user`, and passing a conflicting explicit `--scope` (e.g. `oat init tools core --scope project`) is rejected with an error rather than silently ignored; omit `--scope` or pass `--scope user`. This ensures core skills are available in any directory.
+- Core pack always installs at **user scope** (`~/.agents/skills/`). It is the only pack whose sole allowed scope is `user`. A conflicting explicit `--scope project` is not rejected: `oat tools install core --scope project` (and the legacy `oat init tools core --scope project`) exits successfully and prints `Installed core tool pack.` but writes nothing, while `oat tools install --scope project` with no pack name still installs core under your home directory. To install core, omit `--scope` or pass `--scope user`. Keeping core in your home directory makes its skills available in any directory. See [Where packs install](#where-packs-install).
 - `~/.oat/docs/` is a managed directory asset: its completeness and drift are compared as a whole tree, so a partially deleted docs tree is reported as a partial `core` install rather than passing silently.
 - 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.
@@ -1042,6 +1089,13 @@ grandfathered as `inferred-legacy`, and existing installs remain additive. One
 inert per-pack install flag was removed, and several commands you already run
 behave differently.
 
+OAT is versioned 0.x, and as this section shows, defaults and exit codes can
+change between 0.x releases. Release notes for each version, including the
+list of merged changes, are published on the repository's
+[GitHub Releases page](https://github.com/voxmedia/open-agent-toolkit/releases).
+The repository does not keep a separate `CHANGELOG` file. Read the notes for
+each version you skip before you update a team's installation.
+
 ### Install scope defaults flipped to user
 
 Every pack's fresh-install default is now **user** scope; it used to be project
@@ -1172,4 +1226,78 @@ Related docs:
 - Diagnosing pack drift (`oat status`, `oat doctor`): `../reference/troubleshooting.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`
+- Diagnostics and local-state commands: [Config and Local State](../reference/config-and-local-state.md)
+
+## Choosing packs and their ownership
+
+A tool pack is a bundle of OAT skills, agents, templates, and scripts that
+installs as one unit. You choose which packs to install and, for each one, its
+scope: user scope puts it in your home directory (`~/.agents/`, `~/.oat/`) so
+it works in every repository you open, and project scope puts it in this
+repository so every clone gets it.
+
+| Need                                                       | Choose                                          |
+| ---------------------------------------------------------- | ----------------------------------------------- |
+| Setup diagnostics and bundled documentation                | `core`                                          |
+| Tracked projects and lifecycle execution                   | `workflows`                                     |
+| Documentation and instruction maintenance                  | `docs`                                          |
+| Reviews, orchestration, explainers, repository improvement | `utility`                                       |
+| Evidence gathering and analysis                            | `research` (includes its dispatch dependencies) |
+| Exploratory capture                                        | `ideas` and/or `brainstorm`                     |
+| File-backed backlog, roadmap, decisions, tracker bindings  | `project-management`, then explicitly adopt PJM |
+
+The interactive picker selects every pack except `project-management`; a
+non-interactive install includes all eight. To install only one pack, name it:
+for example, `oat tools install research --scope user` installs just the
+`research` pack (plus the two `utility` dispatch skills it depends on). The
+`brainstorm` pack is labeled "always-on" because, at its default user scope,
+its skill is available in every repository you open. It does not start on its
+own: it enters brainstorm mode only when you run `/oat-brainstorm` or
+explicitly ask to brainstorm, and it does not activate for review, debugging,
+PR, status, or implementation questions. Installing `project-management`
+only makes its commands available. The repository's planning files are not
+created until someone runs `oat pjm init` (see [Install vs. initialize](#install-vs-initialize)).
+
+- If you are trying OAT on your own, accept the picker's selection and add packs
+  later when you need their workflows.
+- If your team will keep its backlog and decisions in the repository, also
+  select `project-management`, then run `oat pjm doctor --json` and
+  `oat pjm init` once.
+- If you mainly need evidence gathering, choose `research`; it installs the two
+  dispatch skills it needs from `utility` for you.
+
+| Scope   | Choose it when                                  | What you give up                                                           |
+| ------- | ----------------------------------------------- | -------------------------------------------------------------------------- |
+| User    | You want the skills in every repository you use | Teammates do not get them from the repository                              |
+| Project | The team needs identical tooling in every clone | Pack updates show up as repository changes                                 |
+| Both    | Rarely, and only deliberately                   | Duplicate copies, and OAT does not decide which copy your agent tool loads |
+
+A fresh install goes to user scope, which lets you reuse packs across
+repositories without update churn in each one; a pack that is already installed
+keeps its scope. **`core` is user-only**: `oat tools install --scope project`
+with no pack name still installs it in your home directory, and
+`oat tools install core --scope project` reports success but installs nothing
+(see [Where packs install](#where-packs-install)). `oat init --scope project --setup` does not choose
+project scope for packs; customize each pack's scope at the prompt, or install
+packs explicitly. Installing a pack at a second scope adds a second copy rather
+than moving it, so use `oat tools migrate` to move a pack between scopes.
+Templates that a project-scope install writes belong to the repository after
+that: later pack updates and `oat tools remove` leave them alone.
+
+- If you are trying OAT alone, or want your skills in all your repositories,
+  use user scope.
+- If you are rolling OAT out to a team, install with `--scope project` and
+  commit the result. If you already have user-scope copies, move them with
+  `oat tools migrate --pack <pack> --from user --to project` instead of
+  installing a second time.
+- If you do end up with both copies, check which one your agent tool actually
+  loads; OAT does not resolve that for you.
+
+Installing any pack never gives OAT permission to publish to an issue tracker.
+
+> [!WARNING]
+> Rerunning `oat pjm init` or `oat pjm migrate --apply` deletes the `pjm.remote`
+> settings from `.oat/config.json`, so every remote setting silently returns to
+> its default. Afterwards, check `git diff .oat/config.json` and restore the
+> settings you need with `oat config set` (shared remote storage is restored
+> with `oat pjm remote storage shared`) before doing more remote work.

package/assets/docs/index.md

@@ -1,30 +1,45 @@
 ---
-title: OAT Documentation
+title: Home
 description: 'An open-source toolkit for portable, provider-agnostic agent tooling and workflows.'
 ---
 
 # OAT Documentation
 
-Open Agent Toolkit (OAT) is an open-source toolkit for portable, provider-agnostic agent tooling and workflows. It lets teams define canonical agent capabilities once, sync them across providers, and optionally run tracked human-in-the-loop workflows on top.
-
-OAT is organized as three distinct capabilities that can be used together or independently:
-
-1. Provider interoperability CLI (canonical skills/agents + provider sync/drift tooling)
-2. Reusable skills, CLI commands, and tooling for provider-agnostic development workflows
-3. Optional workflow system (discovery/spec/design/plan/implement/review/PR lifecycle)
-
-## Contents
-
-- [Quickstart](quickstart.md) - Canonical Start Here page for choosing the right OAT adoption path.
-- [User Guide](guide/index.md) - Legacy compatibility router for old guide links while content continues moving into the canonical sections below.
-- [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.
-
-## Why OAT Exists
+Open Agent Toolkit (OAT) is an open-source command-line tool and skill library
+for teams that work with AI coding agents such as Claude Code, Cursor, Codex,
+GitHub Copilot and Gemini CLI. You define skills, agents and rules once in your
+repository and OAT keeps every tool's copy in step, and when you want more
+structure it adds optional tracked workflows with plans, reviews and human
+approval points.
+
+## What you can do with it
+
+- **Keep your coding tools aligned.** Edit each skill, agent and rule once in
+  `.agents/`, let `oat sync` create the files each tool reads, and check them
+  for drift with `oat status`. Start with
+  [Provider Sync](provider-sync/index.md).
+- **Get help with a single task.** Use ready-made skills, instructions your
+  agent follows on request, to research a decision, compare options or review
+  a change, without setting up a tracked project. Start with
+  [Skills](skills/index.md).
+- **Make longer work resumable.** Track work as a project that moves through
+  discovery, specification, design, planning, implementation, review and pull
+  request, with points where a person approves before the agent continues.
+  Start with [Choose a Workflow](workflows/choose-workflow.md).
+- **Keep documentation maintained.** Set up plain Markdown or a docs site,
+  then have your agent analyze it and apply the improvements you approve.
+  Start with [Docs Tooling](docs-tooling/index.md).
+
+Each of these works on its own, so you can start with one and add others
+later.
+
+## Start here
+
+New to OAT? [Quickstart](getting-started/quickstart.md) installs the CLI, gives
+you a first result in an existing repository that changes files only inside
+that repository, and helps you choose what to add next.
+
+## Why OAT exists
 
 Teams often need some combination of:
 
@@ -32,32 +47,16 @@ Teams often need some combination of:
 - 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
+OAT exists to make those layers work together without forcing teams to adopt
+all of them at once. It is not another agent runtime: it works through the
+coding agents you already use.
 
-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
-
-1. Runtime behavior: `packages/cli/src/**`
-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
+## Contents
 
-- New to OAT: [Quickstart](quickstart.md)
-- Following an older guide link: [User Guide](guide/index.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)
+- [Getting Started](getting-started/index.md) - How to install OAT, get a first result, and learn the core ideas, plus project status and known limits.
+- [Skills](skills/index.md) - Which skill to use for a task, and how to run it.
+- [Workflows](workflows/index.md) - Tracked projects from plan to pull request, plus ideas, backlog planning and running a batch of existing plans as a wave.
+- [Provider Sync](provider-sync/index.md) - How to keep one set of skills, agents and rules in step across coding tools.
+- [Docs Tooling](docs-tooling/index.md) - How to set up and maintain Markdown docs or a docs site.
+- [Reference](reference/index.md) - Configuration, commands, file locations and troubleshooting.
+- [Contributing](contributing/index.md) - How to change OAT itself: code, docs and skills.

package/assets/docs/meta.json

@@ -1,14 +1,13 @@
 {
-  "title": "OAT Documentation",
+  "title": "Home",
   "pages": [
     "index",
-    "quickstart",
-    "guide",
-    "provider-sync",
+    "getting-started",
+    "skills",
     "workflows",
+    "provider-sync",
     "docs-tooling",
-    "cli-utilities",
-    "contributing",
-    "reference"
+    "reference",
+    "contributing"
   ]
 }

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

@@ -13,8 +13,8 @@ These command definitions inherit the cross-cutting CLI conventions in:
 
 ## Adjacent command docs (outside provider interop scope)
 
-- `oat init` (bootstrap): `../cli-utilities/bootstrap.md`
-- `oat tools ...` (tool-pack lifecycle — install, update, remove, list, info): `../cli-utilities/tool-packs.md`
+- `oat init` (bootstrap): [CLI Bootstrap](../getting-started/bootstrap.md)
+- `oat tools ...` (tool-pack lifecycle — install, update, remove, list, info): [Tool Packs and Installed Assets](../getting-started/tool-packs.md)
 - `oat doctor` (cross-cutting diagnostics): `../reference/cli-reference.md`
 
 ## Quick Look
@@ -241,3 +241,26 @@ Key behavior:
 - Under `none`, warns about every `CLAUDE.md` that remains after sync, including inside excluded trees, because any one of them makes Claude Code ignore every `AGENTS.md`
 - Uses pointer content `@AGENTS.md\n`, file symlinks, or hard copies depending on the selected strategy
 - Detailed behavior and examples: [`Instruction Sync`](instruction-sync.md)
+
+## Safe scope for routine refresh
+
+`oat sync` copies or links your canonical assets (the skills, agents, and rules
+you edit under `.agents/`) into provider views, the per-tool files such as
+`.claude/skills/<name>` that each agent tool reads. The scope decides which
+trees it touches: `project` is this repository, `user` is your home directory,
+and `all` is both.
+
+> [!WARNING]
+> A bare `oat sync` uses scope `all`, so it also writes under your home
+> directory. Every sync also overwrites edits made directly in provider folders,
+> replaces an untracked file sitting at a view path, and removes a view whose
+> canonical source was deleted. Edit files under `.agents/` rather than in
+> provider folders, and pass `--scope` explicitly.
+
+- For a repository-only refresh, run `oat sync --scope project --dry-run` to
+  preview, then run it again without `--dry-run`.
+- In CI or scripts, always pass `--scope project` so the run cannot touch
+  anything in a home directory.
+- To refresh your personal skills across repositories, run
+  `oat sync --scope user`.
+- If you do mean to refresh both, preview `oat sync --scope all --dry-run` first.