@open-agent-toolkit/cli 0.3.12 → 0.3.14

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

@@ -19,7 +19,9 @@ This document defines the project and user sync config used by provider-interop
 Discovery note:
 
 - `oat config describe` includes both sync config scopes in its catalog so you can inspect sync/provider keys from the main config help surface.
-- Mutation ownership still lives with provider-sync commands such as `oat providers set`, not `oat config set`.
+- Enablement mutation lives with `oat providers set`, not `oat config set`.
+  Strategy fields are edited directly in sync config; the provider command does
+  not set them.
 
 It is read by:
 
@@ -143,3 +145,60 @@ safe, including after interruption.
 - [`commands.md`](commands.md)
 - [`manifest-and-drift.md`](manifest-and-drift.md)
 - [`../reference/oat-directory-structure.md`](../reference/oat-directory-structure.md)
+
+## Choosing providers and strategy
+
+### Which providers to enable
+
+Enabling a provider tells OAT to maintain that agent tool's provider views (the
+per-tool files it generates from your `.agents/` canonical assets). Set it with
+`oat providers set --enabled <list> --disabled <list>`.
+
+| `enabled`       | Choose it when                     | What you give up                                                                  |
+| --------------- | ---------------------------------- | --------------------------------------------------------------------------------- |
+| `true`          | Someone on the team uses that tool | Generated files appear in your diffs, even in checkouts without the tool's folder |
+| `false`         | Nobody uses that tool              | OAT stops creating, updating, or removing its files; existing views stay on disk  |
+| Unset (default) | You have not chosen yet            | Predictability: the provider is active only if its folder already exists          |
+
+Interactive `oat init` writes an explicit choice for each provider. While a
+disabled provider's folder still exists, a non-interactive `oat sync` warns
+about it on every run, and an interactive `oat sync --scope project` offers to
+re-enable it with that option already ticked. Untick it, or delete the folder.
+
+- If your team uses only Claude Code, enable `claude` and disable the others.
+- If your team mixes Claude Code, Cursor, and Codex, enable those three and
+  disable `copilot` and `gemini`, so fresh checkouts and worktrees get the same
+  views without depending on which folders happen to exist.
+- If you stop using a tool, disable it, then delete its old views yourself.
+
+### Links or copies
+
+The strategy decides whether provider views are links to the canonical files or
+copies of them. No command sets it: edit `defaultStrategy` or
+`providers.<name>.strategy` in this file by hand, and keep `"version": 1` and
+`"defaultStrategy"`, or sync and status stop with a validation error. The
+"default strategy" that `oat providers inspect` prints for an adapter is not
+used by sync; this file's setting always wins.
+
+| Strategy         | Choose it when                       | What you give up                                                                                          |
+| ---------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `auto` (default) | Almost always                        | Once `auto` has adopted a whole-folder link, switching strategy needs the manual recovery described above |
+| `symlink`        | You want one link per skill or agent | It refuses to sync through an existing whole-folder link                                                  |
+| `copy`           | Links really cannot work for you     | Canonical edits reach the tools only after you run `oat sync` again                                       |
+
+Rules are always copied, whatever the strategy. If the operating system refuses
+to create a link, `auto` and `symlink` quietly copy that entry instead, so check
+the views sync actually produced. With `copy`, `oat status` can still report a
+stale copy as in sync, because it compares the copy with what OAT last wrote.
+
+> [!WARNING]
+> The `copy` strategy stamps the absolute path of the checkout that ran sync
+> into each copied skill. Committed copies therefore show as drifted in every
+> other checkout (teammates, worktrees, CI), and each `oat sync` there rewrites
+> them, so expect constant churn in Git if you commit copied views.
+
+- If you are unsure, keep `auto`.
+- If you want one link per entry, choose `symlink`, but remove any whole-folder
+  link first.
+- If links truly cannot work, choose `copy`, rerun `oat sync` after every
+  canonical edit, and expect the churn described above.

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

@@ -11,15 +11,27 @@ 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.
 
-In practice, you edit the canonical layout in `.agents/` and `.oat/`. OAT
-generates provider-specific views where required, leaves native-read assets in
-their canonical directories, and keeps intentional provider-local adoption
-surfaces visible.
+In practice, you edit the canonical layout in `.agents/`, and choose providers
+in `.oat/sync/config.json`; the rest of `.oat/sync/`, such as the manifest, is
+written by OAT. OAT generates provider-specific views where required, leaves
+native-read assets in their canonical directories, and keeps intentional
+provider-local adoption surfaces visible.
+
+> [!WARNING]
+> `oat sync` and `oat init` default to scope `all`, so they also write under
+> your home directory. Pass `--scope project` when you mean to change only this
+> repository. Re-running `oat sync` also rewrites the files it generates in
+> provider folders such as `.claude/` and `.codex/`, so an edit made to a
+> generated copy there is lost. Make changes in `.agents/` instead.
+
+Piloting with a team? Start with
+[Pilot Provider Sync with One Team](pilot-with-a-team.md).
 
 ## Contents
 
+- [Pilot Provider Sync with One Team](pilot-with-a-team.md) - A week-one plan for trying Provider Sync on one repository.
 - [Provider Interop Commands](commands.md) - `oat status`, `oat sync`, and `oat providers ...` behavior.
-- [Sync Config](config.md) - Provider config model, enablement, and scope semantics.
+- [Sync Config (`.oat/sync/config.json`)](config.md) - Provider config model, enablement, and scope semantics.
 - [Instruction Sync](instruction-sync.md) - Project-scoped `AGENTS.md` / `CLAUDE.md` validation, repair, and Claude-only adoption.
 - [Manifest and Drift](manifest-and-drift.md) - How OAT tracks synced state, stray files, and adoption decisions.
 - [Providers](providers.md) - Provider-specific mappings, capabilities, and path conventions.
@@ -27,15 +39,17 @@ surfaces visible.
 
 ## What This Section Is
 
-This section explains how OAT treats `.agents/` and `.oat/` as the source of
-truth, when provider views are derived from those canonical assets, how
+This section explains how OAT treats `.agents/` as the source of truth, with
+provider settings in `.oat/sync/config.json`, when provider views are derived
+from those canonical assets, how
 native-read mappings avoid redundant output, and how provider-local adoption
 surfaces remain discoverable.
 
 ## What OAT Treats As Canonical
 
 - canonical skills, agents, and rules under `.agents/`
-- sync state and related metadata under `.oat/`
+- provider settings in `.oat/sync/config.json`, and sync state that OAT writes
+  to `.oat/sync/manifest.json`
 - provider-specific files as derived views when a mapping requires output
 - native-read assets in canonical directories without mirrored provider files
 - provider-local extension files as adoption candidates until explicitly
@@ -49,16 +63,18 @@ surfaces remain discoverable.
 
 ## Typical Flow
 
-1. Run `oat init` to create the base OAT layout and setup state.
-2. Inspect current sync state with `oat status`.
+1. Run `oat init --scope project` to create the base OAT layout and setup state.
+2. Inspect current sync state with `oat status --scope project`.
 3. Adjust provider enablement with `oat providers ...` if needed.
-4. Run `oat sync` to materialize required provider views and reconcile managed
-   state. Native-read assets do not produce provider-view operations.
-5. Re-run `oat status` after edits to confirm whether anything drifted or needs adoption.
+4. Run `oat sync --scope project` to materialize required provider views and
+   reconcile managed state. Native-read assets do not produce provider-view
+   operations.
+5. Re-run `oat status --scope project` after edits to confirm whether anything
+   drifted or needs adoption.
 
 ## Start Here
 
-- Use [CLI Bootstrap](../cli-utilities/bootstrap.md) when you are bootstrapping OAT and want the sync-relevant setup path.
+- Use [CLI Bootstrap](../getting-started/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`.
 - Read [Scope and Surface](scope-and-surface.md) when you need the canonical/provider-view mental model.
 
@@ -72,7 +88,7 @@ surfaces remain discoverable.
 
 ## Go Deeper
 
-- [CLI Bootstrap](../cli-utilities/bootstrap.md) - Foundational setup before first sync.
+- [CLI Bootstrap](../getting-started/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.
 - [Instruction Sync](instruction-sync.md) - Project-scoped `AGENTS.md` / `CLAUDE.md` validation, repair, and Claude-only adoption.

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

@@ -41,22 +41,29 @@ to fix.
 
 The content root is derived from `documentation.root` in `.oat/config.json`:
 
-- `<documentation.root>/docs` when that path is a directory;
-- otherwise `documentation.root` itself.
+- for tooling `markdown`, the literal configured `documentation.root`, even
+  when it contains a child directory named `docs`;
+- for other or undeclared tooling, `<documentation.root>/docs` when that path is
+  a directory, otherwise `documentation.root` itself.
 
 This is the same derivation `oat docs generate-index` uses to pick its default
 docs directory, so the excluded tree and the indexed tree agree by
 construction. (`oat docs generate-index --docs-dir` overrides the index side
 only; it does not change what instruction sync excludes.)
 
-**App-level instruction files are still synced.** `documentation.root`
-canonically names the docs _app_ root, and a file like
+**Framework app-level instruction files are still synced.** For framework tooling, `documentation.root`
+names the docs _app_ root, and a file like
 `apps/oat-docs/AGENTS.md` is instructions for working on the docs app rather
 than a documentation page. When the app root has a `docs` child, only that
 child is skipped, and the app root is still synced (under a shim strategy it
 keeps receiving its `CLAUDE.md` pointer). Opt the app root out explicitly if
 you do not want it synced.
 
+For configured Markdown, the entire content root remains excluded, including
+existing local AGENTS files and parent pages outside a nested `docs` subsection.
+Bootstrap preserves local guidance and creates no docs-root AGENTS. Pointer sync
+never replaces authored content or those local instruction files.
+
 Add further paths with `instructions.claude.excludes`, a list of
 repository-relative directories. Set it with
 `oat config set instructions.claude.excludes "vendor,third_party/docs"`
@@ -460,5 +467,36 @@ oat instructions sync --force --strategy copy
 
 - [Provider Interop Commands](commands.md)
 - [Provider Interop CLI Scope and Surface](scope-and-surface.md)
-- [Config and Local State](../cli-utilities/config-and-local-state.md)
+- [Config and Local State](../reference/config-and-local-state.md)
 - [Troubleshooting](../reference/troubleshooting.md)
+
+## Which instruction strategy should I choose?
+
+A shim is a `CLAUDE.md` that OAT keeps next to an `AGENTS.md` so that Claude
+Code setups which read only `CLAUDE.md` still see the instructions. The
+strategy decides whether OAT keeps shims and what form they take.
+
+| Strategy         | Choose it when                                                                | What you give up                                                                         |
+| ---------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `none` (default) | Every contributor's Claude Code reads `AGENTS.md` itself, at default settings | Older releases, or a setting that loads only `CLAUDE.md`, see no instructions            |
+| `pointer`        | Some contributors need a `CLAUDE.md`                                          | One small file per directory, containing only `@AGENTS.md`; it never goes stale          |
+| `symlink`        | Contributors need a `CLAUDE.md` and links work on every machine               | Portability on machines where links are a problem                                        |
+| `copy`           | A tool needs the full instruction text in `CLAUDE.md`                         | After each `AGENTS.md` edit, sync skips the changed copy until you run it with `--force` |
+
+The default is `none` because Claude Code stops reading every `AGENTS.md` in the
+project as soon as any `CLAUDE.md` exists (see
+[Claude Code and AGENTS.md](#claude-code-and-agentsmd)), so shims in some
+directories but not others hide the instructions in the rest. Shims are
+maintained only by `oat instructions sync`; `oat sync` never touches them. If a
+`CLAUDE.md` holds text that is not in its `AGENTS.md`, move that text into
+`AGENTS.md` before removing the shim.
+
+- If you can confirm that everyone uses a current Claude Code at default
+  settings, keep `none`.
+- If you cannot confirm every contributor's setup, for example on a mixed team
+  or an open-source project, choose `pointer`. It works everywhere and never
+  duplicates the instruction text.
+- If you are sure links work on every contributor's machine, `symlink` is an
+  alternative to `pointer`.
+- Choose `copy` only when a consumer needs the full text, and plan to run
+  `oat instructions sync --force` after editing `AGENTS.md`.

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

@@ -13,6 +13,67 @@ This page explains how OAT remembers what it manages and how it distinguishes cl
 - 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`
 
+Diagram: canonical assets produce provider views and a manifest; status reports what changed and how to resolve it.
+
+```mermaid
+flowchart TD
+  CANON["Canonical assets\nEdit .agents/"]
+  SYNC["oat sync\nGenerate views"]
+  VIEWS["Provider views"]
+  MANIFEST["Sync manifest"]
+  STATUS["oat status\nInspect before resolving"]
+  TRACKED["Tracked views\nin_sync / drifted / missing"]
+  STRAY["Unmanaged files\nstray"]
+  CANON --> SYNC
+  SYNC --> VIEWS
+  SYNC --> MANIFEST
+  MANIFEST --> STATUS
+  VIEWS --> STATUS
+  STATUS --> TRACKED
+  STATUS --> STRAY
+```
+
+- **What you edit.** Only the canonical files under `.agents/` (skills, agents,
+  rules). `oat sync` reads them and writes provider views as symlinks or copies
+  under `.claude/`, `.cursor/`, `.github/` and `.codex/`. It records each
+  per-entry view in `.oat/sync/manifest.json`, one entry per canonical path and
+  provider. Codex roles and config are generated too, but are tracked by the
+  Codex extension, not as manifest entries.
+- **What `oat status` reports.** A view is `in_sync` when it still matches what
+  the last sync recorded, `drifted` (`modified`, `broken` or `replaced`) when
+  its content or link changed or its target is gone, and `missing` when no view
+  exists or it was never tracked. A provider file OAT does not manage is a
+  `stray`.
+- **What re-running `oat sync` does.** It writes unless you pass `--dry-run`.
+  It recreates missing views and rewrites drifted ones from canonical, so an
+  edit made in a provider copy is lost, not merged. A file you placed at a
+  view's path without OAT is replaced too. When a skill or rule is deleted
+  from `.agents/`, sync removes its views. When an agent is deleted or
+  renamed, it does not; see the warning below.
+- **What to do with a stray.** In an interactive `oat status` or `oat init` you
+  can adopt it, which moves or converts it into `.agents/`. For a Cursor or
+  Copilot skill you can keep it in place; OAT records the path under
+  `knownStrays` in `.oat/sync/config.json` and leaves it out of later reports.
+  You can also list a path there by hand.
+
+> [!WARNING]
+> Sync does not clean up after a deleted or renamed agent. With Cursor enabled,
+> once `.agents/agents/<name>.md` is gone, `oat sync`, `oat sync --dry-run` and
+> `oat status` exit 1 with
+> `Cursor agent definition is a symbolic link at .cursor/agents/<name>.md whose target escapes the sync scope.`
+> With Codex enabled, the agent's generated files stay behind. After deleting
+> or renaming an agent, clean up by hand:
+>
+> 1. Delete the link `.cursor/agents/<name>.md`.
+> 2. Delete the link `.claude/agents/<name>.md`; until it is gone, the same
+>    error names that path instead.
+> 3. Delete `.codex/agents/<name>.toml`.
+> 4. In `.codex/config.toml`, delete the `[agents.<name>]` table.
+> 5. Run `oat sync --scope project`; it should now succeed.
+>
+> Skills and rules are not affected: sync removes their views when the
+> canonical file is deleted.
+
 ## Manifest locations
 
 - Project: `.oat/sync/manifest.json`
@@ -271,3 +332,27 @@ reasoning effort, and OAT writes a role such as
 - `.oat/projects/<scope>/<project>/design.md`
 - `packages/cli/src/manifest/**`
 - `packages/cli/src/drift/**`
+
+## Choosing a stray disposition
+
+A stray is a file in a provider folder (such as `.cursor/skills/`) that OAT
+does not manage. Interactive `oat init` and `oat status` ask what to do with
+each one.
+
+| Choice                 | Choose it when                                        | What you give up                                                                                                                                                                                                                      |
+| ---------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Adopt                  | Every agent tool should get it                        | Keeping it in one tool only: OAT moves it into `.agents/`. Generated provider views receive a link; Cursor and Copilot skills are read canonically, without recreating the provider-local path or adding a managed-view manifest row. |
+| Keep tool-only         | A Cursor or Copilot skill is meant for that tool only | Other tools never see it. Its exact path is saved in `knownStrays` and no longer reported                                                                                                                                             |
+| Decide later (default) | You are not sure who should own it yet                | It is reported again on every run                                                                                                                                                                                                     |
+
+Keep is offered only for Cursor and Copilot skills, and OAT refuses it when a
+canonical skill with the same name exists; resolve that clash instead. Keeping a
+skill only stops OAT from reporting that path. It does not check that the
+skill is correct or up to date with anything else.
+
+- If a skill should work in every agent tool, adopt it.
+- If a Cursor- or Copilot-only skill is personal, keep it at user scope; if the
+  team needs it, keep it at project scope.
+- For any other stray you want to keep, add its exact path to `knownStrays` by
+  hand, or gitignore it.
+- If you are not sure yet, choose Decide later so it stays visible.

package/assets/docs/provider-sync/meta.json

@@ -1,6 +1,7 @@
 {
   "title": "Provider Sync",
   "pages": [
+    "pilot-with-a-team",
     "commands",
     "config",
     "instruction-sync",

package/assets/docs/provider-sync/pilot-with-a-team.md

@@ -0,0 +1,236 @@
+---
+title: Pilot Provider Sync with One Team
+description: 'A week-one plan for trying Provider Sync on one repository with a team that mixes Claude Code, Cursor, and Codex: setup, teammate onboarding, what to watch, and how to decide.'
+---
+
+# Pilot Provider Sync with One Team
+
+Provider Sync gives a team one set of skills, agents, and rules, kept in the
+repository as canonical assets (the files you edit, under `.agents/`), and
+shows them to each coding tool, or provider, in that tool's own format. When a
+provider view (the per-tool file OAT generates, such as
+`.claude/skills/<name>`) no longer matches what OAT wrote, OAT reports it as
+drift.
+
+This pilot needs no tracked workflows and no project management setup. OAT
+does not commit or push anything during it: you review the changes, commit
+them, and open the pull request yourself.
+
+## Before you start
+
+The team needs Node.js 22.17 or newer and Git 2.31 or newer. Each person
+installs the CLI with:
+
+```bash
+npm install --global @open-agent-toolkit/cli
+```
+
+Agree on one CLI version for the pilot. Each sync stamps its CLI version into
+the sync manifest, so if you commit that file, mixed versions show up as small,
+noisy changes to it. To install a specific version, add it to the package name:
+`npm install --global @open-agent-toolkit/cli@<version>`.
+
+One person does the setup, on a branch. The pilot adds these to the
+repository:
+
+- `.agents/` with your skills, agents, and rules
+- `.oat/sync/config.json` (which providers are on) and
+  `.oat/sync/manifest.json` (what OAT last wrote)
+- a marked OAT block in `.gitignore`, and a `.gitattributes` file or block
+- provider views such as `.claude/skills/`, `.cursor/agents/`, and `.codex/`
+
+[What OAT Writes](../reference/what-oat-writes.md) lists every path, what
+creates it, and whether it is meant to be committed.
+
+## Week one
+
+Scope decides which tree a command works on: `project` is this repository and
+`user` is your home directory. Every command below passes `--scope project`, so
+nothing is written outside the repository.
+
+1. Install the CLI (see above), then check it runs:
+
+   ```bash
+   oat --version
+   ```
+
+2. Create a branch and initialize the repository:
+
+   ```bash
+   git switch -c try-provider-sync
+   oat init --scope project
+   ```
+
+   If `oat init` asks whether to run guided setup, answer no: guided setup
+   installs every tool pack into your home directory, which this pilot does not
+   need. Then look at `git status`: you should see `.gitignore`,
+   `.gitattributes`, and `.oat/` (which holds `.oat/sync/manifest.json`). The
+   empty `.agents/skills`,
+   `.agents/agents`, and `.agents/rules` folders are also created, but Git
+   shows them only once they contain files. Nothing is written in your home
+   directory.
+
+3. Choose providers explicitly. For a team that mixes Claude Code, Cursor, and
+   Codex:
+
+   ```bash
+   oat providers set --scope project --enabled claude,cursor,codex --disabled copilot,gemini
+   ```
+
+   Look at the new `.oat/sync/config.json`. Set every provider explicitly,
+   because a provider you leave unset is still synced whenever its folder (for
+   example `.claude/`) exists, which differs from one checkout to the next.
+   [Sync Config](config.md#which-providers-to-enable) explains each choice.
+
+4. Add one real skill your team already repeats. A skill is a folder with a
+   `SKILL.md` file:
+
+   ```markdown title=".agents/skills/review-migration/SKILL.md"
+   ---
+   name: review-migration
+   description: Use when reviewing a database migration for rollback safety.
+   ---
+
+   # Review a migration
+
+   Check that the migration can be rolled back and that the previous release
+   still works against the new schema. Report problems; do not run the
+   migration.
+   ```
+
+   [Writing Skills](../contributing/skills.md#frontmatter-fields-in-active-use)
+   lists the frontmatter fields. A rule is a Markdown file in `.agents/rules/`
+   instead; see
+   [Canonical rule frontmatter](providers.md#canonical-rule-frontmatter).
+
+5. Preview the sync, then apply it:
+
+   ```bash
+   oat sync --scope project --dry-run
+   oat sync --scope project
+   ```
+
+   The preview lists each planned operation and changes nothing. After the real
+   run, `.claude/skills/review-migration` should be a link to
+   `../../.agents/skills/review-migration`. Start a new session in each tool so
+   it picks up the change.
+
+6. Check the result:
+
+   ```bash
+   oat status --scope project
+   ```
+
+   Every row should read `in_sync`. A `missing` row means that entry has not
+   been synced yet.
+
+7. Review the diff and commit it. Use
+   [What to commit](../reference/what-oat-writes.md#what-to-commit) to check
+   each path.
+
+8. Push the branch and open a pull request. The team reviews it like any other
+   change.
+
+## What each teammate does
+
+After the pilot branch merges, each teammate installs the same CLI version. If
+the pilot committed its provider views, nothing else is needed to start: the
+views are relative links into `.agents/` and generated files that contain no
+machine-specific paths, and Cursor and Codex read skills from `.agents/skills`
+directly. To confirm, run `oat status --scope project`; a `missing` row means a
+view was not committed, and `oat sync --scope project` creates it. The links and
+generated files were checked on macOS, including in a fresh clone; how Windows
+checkouts handle committed links was not tested.
+
+Run `oat sync --scope project`, and commit its output in the same change, when
+you add, rename, or delete a skill, agent, or rule, or change an agent or rule.
+Deleting or renaming an agent also needs the manual cleanup described below.
+Rules, Codex agent files and Cursor's per-model agent variants are generated
+copies, so they only change when sync runs. An edit inside an existing linked
+skill reaches Claude Code at once, because the view is a link.
+
+Make every change in `.agents/`, never in the provider folders. Re-running sync
+overwrites edits made to generated copies, replaces an untracked file sitting
+at a view path, and removes the view of a deleted skill or rule. Editing
+through a link changes the canonical file itself, which is easy to miss in
+review.
+
+Agents are the exception. After you delete or rename an agent, delete its old
+links in `.cursor/agents/` and `.claude/agents/` yourself: with Cursor enabled,
+`oat sync` and `oat status` stop with an error saying the link's target
+`escapes the sync scope` until both links are gone. Also delete its
+`.codex/agents/<name>.toml` file and the `[agents.<name>]` table in
+`.codex/config.toml`, which sync leaves behind.
+
+Before committing, run `oat status --scope project`. It exits 1 when any view
+is missing or drifted, or when a stray file sits in a provider folder. For a
+check that ignores strays, such as a CI step, run
+`oat status --scope project --hook`: it prints one warning line and exits 1
+only when a view is missing or drifted.
+
+For an automatic reminder, a teammate can add OAT's optional pre-commit hook
+with `oat init --scope project --hook`. Git does not copy hooks when you clone,
+so each person adds it in their own clone. The hook only warns; it never blocks
+a commit, and it does nothing if `oat` is not installed. If the repository sets
+Git's `core.hooksPath`, the hook goes in that folder instead, which may be
+inside the working tree. Remove it with `oat init --scope project --no-hook`.
+
+## Mixed tools
+
+| Provider    | What OAT generates in the repository                                                                                             | What the team should know                                                                                                                                           |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude Code | A relative link per skill in `.claude/skills/` and per agent in `.claude/agents/`; rules as generated copies in `.claude/rules/` | The only provider with skill views, so a new skill reaches Claude Code only after sync                                                                              |
+| Cursor      | No skill files: it reads `.agents/skills`. A link per agent in `.cursor/agents/`; rules as `.cursor/rules/*.mdc` files           | Its `.cursor/skills/` folder is not managed; skills found there are reported as strays                                                                              |
+| Codex       | No skill files: it reads `.agents/skills`. A generated `.codex/agents/<name>.toml` per agent, registered in `.codex/config.toml` | Sync merges into an existing `.codex/config.toml`: it adds OAT's tables, turns on `multi_agent` and raises `max_depth` to at least 2, and keeps your other settings |
+| Gemini      | Nothing; it reads skills and agents from `.agents/` directly                                                                     | Nothing to commit                                                                                                                                                   |
+
+If OAT's own implementer and reviewer agents are installed in the repository,
+sync also generates one file per supported model for each of them, in
+`.cursor/agents/` and `.codex/agents/`, which can add dozens of files to the
+first diff. The skill links, agent links, rule copies, generated agent files
+and `.codex/config.toml` merge were observed by running the CLI in a test
+repository. [Providers](providers.md) also covers Copilot and the user scope.
+
+## What to watch for in week one
+
+- **A bare `oat sync` or `oat init` can also write in your home directory.**
+  Both default to scope `all`. Use `--scope project` in shared instructions,
+  scripts, and CI.
+- **Edits in provider folders are not safe.** Sync overwrites edits to
+  generated copies from `.agents/`, and an edit made through a link silently
+  changes the canonical file.
+- **Disabling a provider leaves its views in place.** Delete them yourself.
+  While a disabled provider's folder exists, sync warns on every run, and an
+  interactive sync offers to re-enable it with the box already ticked; untick
+  it.
+- **Keep the default `auto` strategy unless links cannot work.** The `copy`
+  strategy records the absolute path of the checkout that ran sync, so copies
+  show as drifted in every other checkout and churn in Git.
+- **Strays are reported, not deleted.** A stray is a file in a provider folder
+  that OAT does not manage. See
+  [Choosing a stray disposition](manifest-and-drift.md#choosing-a-stray-disposition).
+
+## Deciding after the pilot
+
+The pilot is working when:
+
+- one change in `.agents/` shows up in Claude Code, Cursor, and Codex after one
+  sync and one commit
+- teammates on different tools use the same skill without copying it by hand
+- `oat status --scope project` shows every row `in_sync` before commits, or in
+  CI with `--hook`
+- nobody has had to edit a provider folder by hand
+
+**If you stop**, follow [Backing out](../reference/what-oat-writes.md#backing-out).
+There is no uninstall command: stopping means one commit that deletes the files
+the pilot added and OAT's blocks in `.gitignore` and `.gitattributes`, plus
+`oat init --scope project --no-hook` in each clone that added the hook. Your
+skills are plain files, so you can keep them.
+
+## Next
+
+- [Provider Sync](index.md) and [Commands](commands.md)
+- [Sync Config](config.md) and [Scope and Surface](scope-and-surface.md)
+- [Manifest and Drift](manifest-and-drift.md) and [Providers](providers.md)
+- [Quickstart](../getting-started/quickstart.md)
+- [What OAT Writes](../reference/what-oat-writes.md)

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

@@ -25,7 +25,7 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 
 - Mutate by default; `--dry-run` to preview
 - Explicit `--dry-run` for safe preview of mutations
-- Scoped destructive actions only for manifest-tracked entries
+- Deletions are limited to manifest-tracked entries: sync removes a skill or rule view only when the manifest records it and its canonical source is gone. Deleted agents are not cleaned up this way: with Cursor enabled, sync and status stop with an `escapes the sync scope` error until you delete the agent's dangling links in `.cursor/agents/` and `.claude/agents/`, and Codex's `.codex/agents/<name>.toml` and `[agents.<name>]` table are never removed (see [Manifest and Drift](manifest-and-drift.md#quick-look)). A provider file with no canonical source and no manifest entry is reported as a stray by `oat status`, not deleted. Writing a view is not limited this way: sync replaces whatever sits at a view's expected path, including an untracked file (see the warning under [Choosing sync scope](#choosing-sync-scope))
 - Cross-provider compatibility via adapters
 - Native-read assets stay canonical while provider-local adoption sources remain discoverable independently
 - Obsolete managed mappings are deleted only when their provider paths are verified clean; changed or unverified paths are preserved and detached from manifest ownership
@@ -50,8 +50,8 @@ 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 `../cli-utilities/bootstrap.md`
-- `oat tools ...` (install/update/remove/migrate/list/inspect tools) — see `../cli-utilities/tool-packs.md`
+- `oat init` (bootstrap canonical structure and sync config) — see [CLI Bootstrap](../getting-started/bootstrap.md)
+- `oat tools ...` (install/update/remove/migrate/list/inspect tools) — see [Tool Packs and Installed Assets](../getting-started/tool-packs.md)
 - `oat doctor` (environment + skill-version diagnostics) — see `../reference/cli-reference.md`
 
 ## Provider enablement model
@@ -131,3 +131,37 @@ runtime mismatch, malformed output, and missing telemetry never authorize it.
 - `.oat/projects/<scope>/<project>/design.md`
 - `.oat/projects/<scope>/<project>/plan.md`
 - `.oat/projects/<scope>/<project>/implementation.md`
+
+## Choosing sync scope
+
+`oat sync` and `oat status` take `--scope project`, `--scope user`, or
+`--scope all`. Project scope works on this repository's canonical assets (the
+files under `.agents/`) and its provider views (the per-tool copies or links
+such as `.claude/skills/<name>`). User scope does the same for `~/.agents/` and
+the tool folders in your home directory. All runs project scope, then user scope.
+
+| Scope           | Choose it when                                      | What you give up                                  |
+| --------------- | --------------------------------------------------- | ------------------------------------------------- |
+| `project`       | CI, scripts, or a team checkout                     | Your personal skills are not refreshed            |
+| `user`          | You keep personal skills that you use in every repo | Rules are not synced; they exist only per project |
+| `all` (default) | You maintain both trees on your own machine         | Every run also writes into your home directory    |
+
+User scope never syncs rules: only project scope distributes the rules in
+`.agents/rules` to provider folders. Edit the files under `.agents/` rather than
+the provider views, because sync overwrites changes made in the views.
+
+> [!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 the view of a
+> deleted skill or rule. It does not clean up after a deleted or renamed agent;
+> see [Manifest and Drift](manifest-and-drift.md#quick-look) for the manual
+> steps. Pass `--scope` explicitly, and preview with `--dry-run` when you are
+> unsure.
+
+- If the run is in CI or a script, always pass `--scope project`, and preview
+  with `--dry-run` when you change what is synced.
+- If you want personal skills in every repository, put them in
+  `~/.agents/skills` and run `oat sync --scope user`.
+- If you deliberately maintain both trees on your own machine, `--scope all` (or
+  a bare `oat sync`) is fine.