@open-agent-toolkit/cli 0.1.74 → 0.2.0

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

@@ -16,21 +16,23 @@ For the deep file-by-file reference, see:
 - [`.oat` Directory Structure](../reference/oat-directory-structure.md)
 - [Sync Config (`.oat/sync/config.json`)](../provider-sync/config.md)
 
-## The four config surfaces
+## The five config surfaces
 
-| Surface              | File                     | Typical contents                                                                                                                                      | Primary CLI surface                            |
-| -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
-| Shared repo config   | `.oat/config.json`       | Repo-wide non-sync settings such as `projects.root`, `git.defaultBranch`, `documentation.*`, `archive.*`, `tools.*`, and shared `workflow.*` defaults | `oat config get/set/list/describe`, `oat gate` |
-| Repo-local config    | `.oat/config.local.json` | Per-developer state for this checkout, such as `activeProject`, `lastPausedProject`, repo-local `activeIdea`, and local `workflow.*` overrides        | `oat config get/set/list/describe`, `oat gate` |
-| User config          | `~/.oat/config.json`     | User-level state such as global `activeIdea` fallback, personal `workflow.*` defaults, and personal known provider strays                             | `oat config describe`, `oat gate`              |
-| Provider sync config | `.oat/sync/config.json`  | Provider enablement, sync strategy, and repo-level known stray settings                                                                               | `oat providers set`, `oat config describe`     |
+| Surface                   | File                      | Typical contents                                                                                                                                      | Primary CLI surface                            |
+| ------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| Shared repo config        | `.oat/config.json`        | Repo-wide non-sync settings such as `projects.root`, `git.defaultBranch`, `documentation.*`, `archive.*`, `tools.*`, and shared `workflow.*` defaults | `oat config get/set/list/describe`, `oat gate` |
+| Repo-local config         | `.oat/config.local.json`  | Per-developer state for this checkout, such as `activeProject`, `lastPausedProject`, repo-local `activeIdea`, and local `workflow.*` overrides        | `oat config get/set/list/describe`, `oat gate` |
+| User config               | `~/.oat/config.json`      | User-level state such as global `activeIdea` fallback and personal `workflow.*` defaults                                                              | `oat config describe`, `oat gate`              |
+| Project sync config       | `.oat/sync/config.json`   | Provider enablement, sync strategy, and repo-level known stray settings                                                                               | `oat providers set`, `oat config describe`     |
+| User provider sync config | `~/.oat/sync/config.json` | User sync strategy and personal known provider strays                                                                                                 | Provider-sync commands, `oat config describe`  |
 
 The main split is:
 
 - `.oat/config.json` for shared repo behavior
 - `.oat/config.local.json` for local developer state
-- `~/.oat/config.json` for user-scope fallback state and personal provider-sync exceptions
-- `.oat/sync/config.json` for provider sync only
+- `~/.oat/config.json` for user-scope fallback and workflow state
+- `.oat/sync/config.json` for project provider sync
+- `~/.oat/sync/config.json` for user provider sync
 
 ## The fastest way to inspect config
 
@@ -634,9 +636,13 @@ Use:
 - `oat config describe ...` to understand sync keys
 - `oat providers set ...` to mutate sync/provider settings
 
-Known provider strays are the narrow cross-surface exception: repo-wide
-`knownStrays` entries live in `.oat/sync/config.json`, while personal
-`knownStrays` entries can live in `~/.oat/config.json`.
+Known provider strays follow sync ownership: repo-wide `knownStrays` entries
+live in `.oat/sync/config.json`, while personal entries live in
+`~/.oat/sync/config.json`. Before resolving user sync settings or writing any
+general user-config change, OAT migrates legacy
+`~/.oat/config.json#knownStrays` by writing the normalized union to the user
+sync config first, then deleting only the legacy key. The migration is
+idempotent.
 
 For the provider-sync schema details, use [Sync Config (`.oat/sync/config.json`)](../provider-sync/config.md).
 

package/assets/docs/cli-utilities/tool-packs.md

@@ -17,7 +17,7 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 
 - `core` - foundational diagnostics and docs access (`oat-doctor`, `oat-docs`)
 - `docs` - docs and agent-instructions governance workflows
-- `workflows` - project lifecycle skills, the project subagent-dispatch adapter, wrap-up reporting, reviewer agents, and core project templates
+- `workflows` - project lifecycle skills, wave-program orchestration (`oat-wave-program`, `oat-wave-execute`), the project subagent-dispatch adapter, wrap-up reporting, reviewer agents, and core project templates
 - `ideas` - lightweight ideation and promotion flows
 - `utility` - review and repo-maintenance helpers plus the provider-neutral subagent-dispatch engine
 - `project-management` - file-backed backlog/reference skills plus backlog, roadmap, current-state, file-per-record decision, and AGENTS-guide templates

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

@@ -33,6 +33,15 @@ Key behavior:
 
 - Scope support (`project`, `user`, `all`)
 - Optional interactive stray adoption
+- Cursor-local skills are handled individually: Adopt moves the skill into the
+  matching canonical `.agents/skills` directory, while Keep Cursor-only
+  preserves it and records its exact path in the applicable sync config
+- Aborting a Cursor migration preserves completed choices and leaves the
+  current and remaining skills unresolved
+- Keep Cursor-only is blocked when a canonical skill has the same name; rename
+  one skill before retrying
+- Non-interactive and JSON modes report unresolved Cursor skill actions without
+  choosing or mutating a disposition
 - JSON output for automation
 
 ## `oat sync`
@@ -46,6 +55,20 @@ Key behavior:
 - Mutates by default; use `--dry-run` to preview
 - Strategy-aware operations (`symlink`, `copy`, `auto`)
 - Provider enable/disable honored via sync config
+- Cursor skills are native-read from canonical `.agents/skills`; sync does not
+  create `.cursor/skills` mirrors
+- Upgrade cleanup removes only verified clean legacy Cursor skill views.
+  Changed or unverified views are preserved and detached from obsolete manifest
+  ownership.
+
+Preview project and user cleanup before applying it:
+
+```bash
+oat sync --scope all --dry-run
+```
+
+Review every planned `remove` and `detach` operation before running the same
+command without `--dry-run`.
 
 ## `oat providers list`
 
@@ -102,6 +125,9 @@ Key behavior:
 ## Notes
 
 - `oat init --scope project` is commonly used before provider-interop commands because it initializes `.oat/sync/config.json`.
+- User-scope known-stray choices are stored in `~/.oat/sync/config.json`.
+  Legacy `~/.oat/config.json#knownStrays` entries migrate automatically before
+  user-scope stray filtering.
 - `oat doctor` complements interop workflows by surfacing environment and bundled-skill version issues before or after sync operations.
 
 ## Adjacent Instruction Integrity Commands

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

@@ -5,11 +5,12 @@ description: 'Configuration schema and behavior for provider sync in .oat/sync/c
 
 # Sync Config (`.oat/sync/config.json`)
 
-This document defines the project sync config used by provider-interop commands.
+This document defines the project and user sync config used by provider-interop commands.
 
 ## Location
 
 - Project scope: `.oat/sync/config.json`
+- User scope: `~/.oat/sync/config.json`
 
 ## Purpose
 
@@ -17,7 +18,7 @@ This document defines the project sync config used by provider-interop commands.
 
 Discovery note:
 
-- `oat config describe` includes `.oat/sync/config.json` in its catalog so you can inspect the sync/provider keys from the main config help surface.
+- `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`.
 
 It is read by:
@@ -64,7 +65,7 @@ Entries are exact provider-path matches after path normalization; they are not
 globs and do not suppress sibling paths.
 
 Project-level config in `.oat/sync/config.json` applies to everyone using the
-repository:
+repository. A Keep Cursor-only choice for a project skill writes here:
 
 ```json
 {
@@ -74,11 +75,13 @@ repository:
 }
 ```
 
-User-level config in `~/.oat/config.json` is useful for personal provider-local
-files that should not be committed to the repository:
+User-level config in `~/.oat/sync/config.json` owns personal provider-local
+files and user-scope Keep Cursor-only choices:
 
 ```json
 {
+  "version": 1,
+  "defaultStrategy": "auto",
   "knownStrays": [".cursor/skills/cloud-environment-setup"]
 }
 ```
@@ -87,6 +90,12 @@ The common Cursor-only skill case is a good fit: the skill may intentionally
 exist in `.cursor/skills/cloud-environment-setup` while remaining outside the
 canonical `.agents/skills` inventory.
 
+Earlier releases stored user `knownStrays` in `~/.oat/config.json`. Before OAT
+resolves user sync config or writes any general user-config change, it
+normalizes and unions those entries into `~/.oat/sync/config.json`, writes the
+sync config first, then removes only the legacy key. Repeating the migration is
+safe, including after interruption.
+
 ## Behavior notes
 
 - If `providers.<name>.enabled` is:
@@ -95,6 +104,8 @@ canonical `.agents/skills` inventory.
   - unset: provider falls back to directory detection.
 - `defaultStrategy` is used when no provider-specific `strategy` is set.
 - At runtime, config is normalized so `providers` is always present in memory.
+- Project scans combine project and user known-stray paths. User scans use the
+  user sync config.
 - Codex project sync also manages generated materialized roles derived from
   canonical agents and explicit model+effort targets. Dispatch-aware roles such
   as `oat-phase-implementer-gpt-5-6-terra-xhigh` and
@@ -106,7 +117,7 @@ canonical `.agents/skills` inventory.
 - Initial setup (interactive): `oat init --scope project`
 - Explicit updates: `oat providers set --scope project --enabled <providers> --disabled <providers>`
 - Apply sync changes: `oat sync --scope project`
-- Inspect the sync config contract: `oat config describe sync.defaultStrategy` or `oat config describe sync.providers.<name>.enabled`
+- Inspect the sync config contract: `oat config describe sync.defaultStrategy`, `oat config describe sync.knownStrays`, or `oat config describe sync.providers.<name>.enabled`
 
 ## Related references
 

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

@@ -5,11 +5,16 @@ description: Standalone adoption lane for canonical assets, provider views, sync
 
 # Provider Sync
 
-Provider Sync is the OAT lane for keeping a canonical rules-and-skills layout in sync with provider-specific surfaces such as Claude, Cursor, Copilot, Gemini, or Codex.
+Provider Sync is the OAT lane for reconciling a canonical rules-and-skills
+layout with provider-specific surfaces such as Claude, Cursor, Copilot, Gemini,
+or Codex.
 
 You can adopt this layer on its own. It does not require tracked OAT projects, and it is the right starting point when you mainly want interoperability and drift control.
 
-In practice, you edit the canonical layout in `.agents/` and `.oat/`, then let OAT generate or reconcile provider-specific views for Claude Code, Cursor, Copilot, Gemini, Codex, and other supported providers.
+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.
 
 ## Contents
 
@@ -22,13 +27,19 @@ In practice, you edit the canonical layout in `.agents/` and `.oat/`, then let O
 
 ## What This Section Is
 
-This section explains how OAT treats `.agents/` and `.oat/` as the source of truth, how provider views are derived from those canonical assets, and how sync/adoption workflows keep everything aligned.
+This section explains how OAT treats `.agents/` and `.oat/` as the source of
+truth, 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-specific files as derived views unless they are explicitly adopted back into canonical form
+- 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
+  adopted or remembered as intentional strays
 
 ## Who It's For
 
@@ -41,7 +52,8 @@ This section explains how OAT treats `.agents/` and `.oat/` as the source of tru
 1. Run `oat init` to create the base OAT layout and setup state.
 2. Inspect current sync state with `oat status`.
 3. Adjust provider enablement with `oat providers ...` if needed.
-4. Run `oat sync` to materialize provider views from canonical assets.
+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.
 
 ## Start Here

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

@@ -55,10 +55,48 @@ Provider files ignored by Git are treated as intentionally local runtime files a
 
 Provider files listed in sync config `knownStrays` are also omitted from stray
 summaries and adoption prompts. Known strays can be configured at project scope
-in `.oat/sync/config.json` or user scope in `~/.oat/config.json`; entries use
+in `.oat/sync/config.json` or user scope in `~/.oat/sync/config.json`; entries use
 exact provider-path matching, so `.cursor/skills/cloud-environment-setup` does
 not suppress `.cursor/skills/cloud-environment-setup-extra`.
 
+### Cursor skill migration
+
+Cursor reads canonical project and user skills directly from `.agents/skills`
+and `~/.agents/skills`. OAT therefore treats `.cursor/skills` as a Cursor-only
+extension and adoption surface rather than generated output.
+
+Interactive `oat init` and `oat status` ask about every unresolved Cursor-local
+skill separately:
+
+- **Adopt:** move the skill to the matching canonical `.agents/skills`
+  directory without creating a Cursor skill view or manifest row. If identical
+  canonical content already exists, OAT removes the redundant Cursor-local
+  copy.
+- **Keep Cursor-only:** leave the skill in place and immediately add its exact
+  normalized path to the applicable project or user sync config.
+- **Abort:** keep the current and remaining skills unresolved. Choices already
+  completed in the same run remain saved.
+
+Keep Cursor-only is unavailable when a canonical skill has the same name.
+Rename one skill before retrying; Cursor does not document a safe precedence
+rule for duplicates discovered from both roots. Non-interactive and JSON modes
+report pending migration actions without choosing or mutating a disposition.
+
+### Retiring legacy Cursor skill views
+
+When upgrading from generated Cursor skill views, sync classifies each obsolete
+manifest-owned path before acting:
+
+- Verified clean symlinks and managed copies are removed with their manifest
+  entries.
+- Missing paths lose only their stale manifest entries.
+- Modified, replaced, broken, unreadable, or otherwise unverified paths are
+  preserved while OAT detaches their obsolete manifest ownership.
+- Unmanaged Cursor-only content is never removed.
+
+Use `oat sync --scope <project|user|all> --dry-run` to distinguish planned
+removal from preserve-and-detach operations before running a mutating sync.
+
 For rules, adoption maps provider-native files back into `.agents/rules/*.md`:
 
 - Claude: `.claude/rules/*.md`

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

@@ -16,8 +16,12 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
 
 === "Cursor"
 
-    - Project: `.agents/skills` -> `.cursor/skills`, `.agents/agents` -> `.cursor/agents`, `.agents/rules` -> `.cursor/rules`
-    - User: `~/.agents/skills` -> `~/.cursor/skills`, `~/.agents/agents` -> `~/.cursor/agents`
+    - Project skills are native-read from `.agents/skills`; agents and rules still sync to `.cursor/agents` and `.cursor/rules`
+    - User skills are native-read from `~/.agents/skills`; agents still sync to `~/.cursor/agents`
+    - `.cursor/skills` and `~/.cursor/skills` remain supported Cursor-only extension and adoption surfaces. OAT does not generate skill views there.
+    - Interactive `oat init` and `oat status` ask for an individual disposition for each unresolved Cursor-local skill: adopt it into `.agents/skills` or keep it Cursor-only and remember the exact path in sync config
+    - Keep-local is blocked when a canonical skill has the same name because Cursor does not document a safe duplicate-resolution order
+    - During upgrades, OAT removes only verified clean legacy managed skill views. Changed or replaced views are preserved, detached from manifest ownership, and offered for migration.
     - Sync materializes pinned Markdown definitions for both `oat-phase-implementer` and `oat-reviewer`. Each generated name keeps the configured flat ladder ID, while an explicit verified mapping writes the separate bracket-form frontmatter model. OAT never derives one form from the other.
     - Generated definitions carry `supported-catalogue`, `project-config`, or `user-config` ownership. Project and supported output lives in the tracked `.cursor/agents` view; user-owned output lives under `~/.cursor/agents`. Cleanup reconciles only the applicable owner.
     - Managed dispatch requires `providers.cursor.dispatchArgs.variant` and launches that exact resolver-selected native agent type first. Skills do not pass a Task-level model argument or normalize Cursor model strings.
@@ -107,6 +111,8 @@ than falling back to the root target or a base role.
 
 - Stray adoption is available in `oat init` and `oat status`.
 - Adoption reconciles canonical plus the adopted provider first.
+- Native-read Cursor skill adoption moves the provider-local skill into `.agents/skills` without recreating a `.cursor/skills` view or manifest entry.
+- Choosing Keep Cursor-only leaves the skill in place and records its exact normalized path in the project or user sync config.
 - Rule adoption normalizes provider filenames back to canonical `.agents/rules/*.md` entries before cross-provider fanout.
 - Cross-provider fanout is explicit via `oat sync --scope all`.
 

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

@@ -13,7 +13,8 @@ This capability is intentionally independent from OAT workflow artifacts. Teams
 
 - Canonical directories: `.agents/skills`, `.agents/agents`, `.agents/rules`
 - Managed provider views: `.claude/*`, `.cursor/*`, `.github/*`, `.copilot/*`, `.codex/*` (where applicable)
-- Native-read providers may use canonical `.agents/*` directly without mirrored provider directories (for example, Gemini and Codex canonical mappings)
+- Native-read mappings use canonical `.agents/*` directly without mirrored provider directories. Cursor skills, Gemini skills and agents, and Codex canonical mappings use this model.
+- Cursor's `.cursor/skills` and `~/.cursor/skills` directories are provider-local extension and adoption surfaces, not managed output directories.
 - Manifest tracking: `.oat/sync/manifest.json` (project) and `~/.oat/sync/manifest.json` (user)
 
 Rules are currently project-scoped canonical content. Unlike skills and agents, synced rule files for Claude, Cursor, and Copilot are rendered copies with provider-specific frontmatter and filename extensions.
@@ -24,6 +25,8 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - Explicit `--dry-run` for safe preview of mutations
 - Scoped destructive actions only for manifest-tracked entries
 - 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
 - Canonical `.agents/agents` is source of truth for subagents; provider views are derived
 - Canonical `.agents/rules` is source of truth for rules; provider rule files are derived rendered copies
 
@@ -47,6 +50,7 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - Project provider enablement is stored in `.oat/sync/config.json` (`providers.<name>.enabled`).
 - `oat init --scope project` (interactive) prompts for supported providers and persists explicit true/false values.
 - `oat sync --scope project` uses config-aware provider activation and can prompt to remediate detected mismatches.
+- Cursor provider enablement still controls agents, rules, migration discovery, and legacy cleanup even though Cursor reads canonical skills without a generated skill view.
 - Codex project-scope subagent sync writes `.codex/config.toml` and `.codex/agents/*.toml` at command layer after path-mapping sync. Every generated project Codex variant and registration is repository-owned, version-controlled provider output. OAT provides no automatic ignore mechanism for this project output; collaborators review and commit it like other project configuration.
 - Default Codex execution requires `root (0) → phase implementer (1)`. Sync and direct materialization continue to apply an `agents.max_depth` floor of `2` as optional nested-work capability without lowering a higher target value. A project write may read a higher lower-precedence user value and preserves it in project configuration; it writes only project `.codex/config.toml`. User scope writes only `~/.codex/config.toml` and does not read or change project configuration.
 - Missing depth or depth `1` does not block default phase execution. Invalid values or explicit values below `1` fail managed implementation preflight. `oat doctor` reports whether optional depth-two nesting is available and gives a scope-specific repair when the configured value is unusable.

package/assets/docs/reference/file-locations.md

@@ -14,6 +14,9 @@ For detailed `.oat/` tree semantics, see:
 - Skills: `.agents/skills/`
 - Agents/subagents: `.agents/agents/`
 - Rules: `.agents/rules/`
+- Cursor reads project skills directly from `.agents/skills/` and user skills
+  directly from `~/.agents/skills/`. `.cursor/skills/` remains a Cursor-only
+  extension and adoption surface, not generated output.
 
 ## OAT runtime/state
 
@@ -23,11 +26,12 @@ For detailed `.oat/` tree semantics, see:
 - Projects root config: `projects.root` in `.oat/config.json` (read via `oat config get projects.root`)
 - Archive config: `archive.s3Uri`, `archive.s3SyncOnComplete`, `archive.summaryExportPath`, `archive.wrapUpExportPath`, `archive.awsProfile`, and `archive.awsRegion` in `.oat/config.json`
 - Workflow gate config: `workflow.gates.skills` and `workflow.gates.execTargets` in `.oat/config.json`, `.oat/config.local.json`, or `~/.oat/config.json` (manage via `oat gate`)
-- Project manifests/config: `.oat/sync/`
+- Project sync manifest/config: `.oat/sync/`
+- User sync manifest/config: `~/.oat/sync/`
 
 Config discovery via CLI:
 
-- `oat config describe` lists the supported config surfaces and keys across `.oat/config.json`, `.oat/config.local.json`, `~/.oat/config.json`, and `.oat/sync/config.json`.
+- `oat config describe` lists the supported config surfaces and keys across `.oat/config.json`, `.oat/config.local.json`, `~/.oat/config.json`, `.oat/sync/config.json`, and `~/.oat/sync/config.json`.
 - `oat config describe <key>` shows file location, scope, default, mutability, and the owning command for one key.
 - `oat config list` shows the currently resolved values for the repo-local/shared command surface.
 
@@ -36,7 +40,9 @@ Config ownership note:
 - `.oat/config.json` is the canonical home for shared non-sync settings (for example, `worktrees.root`, `projects.root`).
 - `.oat/config.local.json` is the canonical home for per-developer lifecycle state (for example, `activeProject`, `lastPausedProject`, `activeIdea`).
 - `~/.oat/config.json` is the canonical home for user-level state (for example, `activeIdea` at global scope).
-- `.oat/sync/config.json` remains the sync/provider config contract.
+- `.oat/sync/config.json` owns project sync/provider settings and known strays.
+- `~/.oat/sync/config.json` owns user sync/provider settings and personal known
+  strays. OAT migrates the legacy `~/.oat/config.json#knownStrays` key here.
 - Legacy `.oat/active-project` / `.oat/projects-root` / `.oat/active-idea` files may still exist as inert compatibility artifacts in some repos/worktrees.
 
 ## OAT workflow

package/assets/docs/reference/oat-directory-structure.md

@@ -58,12 +58,16 @@ Project scope is used for project workflows and repo-local sync state. User scop
 | Path                      | Purpose                                                           |
 | ------------------------- | ----------------------------------------------------------------- |
 | `.oat/sync/manifest.json` | Records sync-managed provider entries and drift contract state    |
-| `.oat/sync/config.json`   | Sync behavior config (default strategy + provider-level settings) |
+| `.oat/sync/config.json`   | Project sync behavior, provider settings, and known-stray choices |
+
+The equivalent user files are `~/.oat/sync/manifest.json` and
+`~/.oat/sync/config.json`.
 
 `config.json` currently includes:
 
 - `version`
 - `defaultStrategy`
+- `knownStrays` (optional exact provider-local paths)
 - `providers.<provider>.enabled`
 - `providers.<provider>.strategy` (optional override)
 
@@ -79,7 +83,10 @@ Current config ownership:
 - `.oat/config.json` owns shared non-sync repo settings (including `worktrees.root`, `projects.root`, and `documentation.*`).
 - `.oat/config.local.json` owns per-developer project lifecycle state (`activeProject`, `lastPausedProject`, `activeIdea`).
 - `~/.oat/config.json` owns user-level state (`activeIdea` at global scope).
-- `.oat/sync/config.json` continues to own sync/provider behavior.
+- `.oat/sync/config.json` owns project sync/provider behavior and project known strays.
+- `~/.oat/sync/config.json` owns user sync/provider behavior and personal known
+  strays. OAT migrates legacy `~/.oat/config.json#knownStrays` entries here
+  without removing unrelated user config.
 
 CLI discovery surfaces:
 
@@ -255,13 +262,14 @@ Common user-scope entries:
   config.json
   ideas/
   sync/
+    config.json
     manifest.json
 ```
 
 User scope is primarily for:
 
 - User-level ideas
-- User-level provider sync state where applicable
+- User-level provider sync state and personal known-stray choices
 
 ## Practical guidance
 

package/assets/docs/reference/troubleshooting.md

@@ -20,6 +20,17 @@ description: 'Common issues and fixes for skills visibility, worktrees, sync, an
 
 Expected for native-read skill mappings. Codex can read canonical skills without mirrored provider writes.
 
+## Cursor appears detected but no skill sync actions are listed
+
+Expected for native-read skill mappings. Verify project skills under
+`.agents/skills` and personal skills under `~/.agents/skills`; Cursor reads
+those canonical directories directly. Sync will not create `.cursor/skills`
+mirrors.
+
+Use `.cursor/skills` only for intentionally Cursor-specific packages. Interactive
+`oat init` and `oat status` offer each unresolved Cursor-local skill for
+canonical adoption or a remembered Keep Cursor-only choice.
+
 ## `sync` reports provider config mismatch
 
 - For interactive runs, select detected providers to enable when prompted.

package/assets/docs/workflows/index.md

@@ -13,6 +13,7 @@ Use this section when you want explicit project artifacts, stable task IDs, revi
 
 - [Ideas Workflow](ideas/index.md) - Lightweight idea capture, brainstorming, and promotion into tracked projects when the work becomes concrete.
 - [Workflow & Projects](projects/index.md) - Lifecycle, artifacts, reviews, PR flow, and repository analysis.
+- [Wave Workflows](wave-workflows.md) - Program-level coordination for executing a corpus of external plans as ordered wrapper projects.
 - [Skills](skills/index.md) - Workflow-oriented skill discovery and use-case routing.
 
 ## What This Section Is

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

@@ -27,6 +27,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Turn a repo audit, maintainability review, backlog review, backlog directory, or backlog item into standalone external implementation plans: `oat-repo-improve`. Plans land under `.oat/repo/reference/external-plans/`; execute them directly or optionally pass one to `oat-project-import-plan` for tracked OAT execution.
 - Work on docs surfaces: `authoring-docs` (general documentation baseline), `oat-docs-authoring` (targeted OAT/Fumadocs authoring), `oat-docs-bootstrap` (guided bootstrap of a new docs app), `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
 - Generate a shipping digest or scheduled recap: `oat-wrap-up`
+- Run a wave program over a corpus of external plans: `oat-wave-program` (durable program artifact: new/refresh/wave-close) and `oat-wave-execute` (one wave as a wrapper project) — see [Wave Workflows](../wave-workflows.md)
 - Research a topic in depth: `deep-research`
 - Analyze an artifact, codebase, or document: `analyze`
 - Compare options with domain-aware dimensions: `compare`
@@ -71,6 +72,8 @@ Use this section when you want to choose the right OAT skill for a task. If you
     - `oat-project-document`
     - `oat-wrap-up`
     - `oat-project-complete`
+    - `oat-wave-program`
+    - `oat-wave-execute`
 
 === "Ideas"
 

package/assets/docs/workflows/wave-workflows.md

@@ -0,0 +1,77 @@
+---
+title: Wave Workflows
+description: How OAT coordinates a corpus of external plans into waves while preserving project-lifecycle ownership and human judgment.
+---
+
+# Wave Workflows
+
+A wave is a program layer above the per-project OAT lifecycle. It groups external implementation plans into an ordered delivery unit, then runs that unit as a wrapper OAT project. The wrapper uses the normal project lifecycle rather than replacing it.
+
+Use wave workflows when a plan corpus is too large to execute as one project and needs durable sequencing across multiple projects, worktree groups, and merges.
+
+## The Two Wave Skills
+
+The workflow pack provides two complementary skills:
+
+- `oat-wave-program` 1.1.0 maintains the durable execution-program artifact over the full plan corpus. Its `new` mode inventories the corpus, verifies the coverage invariant, and records the orchestrator-composed, operator-approved first program; `refresh` adds newly landed plans to the artifact and records the orchestrator's re-composition of waves not yet started; and `wave-close` records a completed wave. Composing waves is the orchestrating agent's judgment; the skill records the result.
+- `oat-wave-execute` 1.5.0 runs one wave. It owns the repeatable mechanical layer: wrapper-project scaffolding, branch conventions, worktree bootstrap, briefs, gates, merge choreography, bookkeeping cadence, and closeout order.
+
+`oat-wave-program` records which plans belong to each wave. `oat-wave-execute` consumes that mapping and executes one wave through the project lifecycle.
+
+## Mechanical Work and Judgment
+
+The ownership split is load-bearing. The skills automate mechanics, but the orchestrator retains judgment.
+
+The skills own:
+
+- integration and phase branch naming
+- wrapper-project scaffolding
+- worktree bootstrap
+- merge choreography
+- artifact and ledger bookkeeping
+- repeatable verification and closeout sequencing
+
+The orchestrator owns:
+
+- wave and parallel-group composition
+- review-finding dispositions
+- verification of load-bearing worker claims
+- merge-order decisions under live drift
+- cross-lane and end-of-run synthesis
+- all user checkpoints
+
+Do not treat a generated grouping or a mechanically successful lane as a substitute for these decisions.
+
+## Composition With Project Implementation
+
+Each wave is scaffolded as a quick-mode wrapper project. Its plan points to the source plans while preserving their requirements, and `oat-project-implement` remains the lifecycle owner for phase execution, independent review, bounded fixes, checkpoints, and project state.
+
+For plan-declared parallel groups, `oat-wave-execute` invokes its bundled `scripts/bootstrap-group.sh` helper. The helper wraps the standard worktree bootstrap flow, creates phase worktrees at an explicit base, initializes each worktree, checks provider-view parity, and reports structured status. `oat-project-implement` then dispatches and verifies each phase in its assigned worktree. The wave layer owns the serialized fan-in and integration gates after those phases pass.
+
+This composition keeps the responsibilities separate:
+
+1. `oat-wave-program` records the program and wave membership.
+2. `oat-wave-execute` scaffolds and coordinates one wrapper project.
+3. `oat-project-implement` executes that project's phases.
+4. `oat-wave-program wave-close` updates the durable program after the wave merges.
+
+## Execution-Program Artifact Format
+
+The execution-program artifact is durable reference material under `.oat/repo/reference/external-plans/`. It is not an executable plan or an `oat-project-import-plan` target.
+
+The current format contains:
+
+- **Wave table:** one row per source plan, including its link, source index, assigned wave, ordering or dependency notes, and status (`pending`, `in-wave`, `done`, `deferred`, or `dropped`).
+- **Coverage invariant:** every plan in every source plan index appears in exactly one row. A deferred or dropped plan includes a reason and re-entry trigger; an omitted plan is an error.
+- **Wave sections:** the theme, lane list, intra-wave ordering, and cross-wave prerequisites for each wave.
+- **Status ledger:** each wave advances from composed to in-progress to merged, with the wrapper-project link, PR, merge SHA, and completion-record link recorded as they become available.
+
+> **Important:** This format is documented as a description, not a stable contract. Contract work is deferred in **BL-260718-document-execution-program — Document execution-program artifact as stable OAT contract**, grouped with **BL-260718-add-oat-wave-lifecycle-cli — Add oat wave lifecycle CLI command family**.
+
+Until that grouped work ships, consumers should follow the bundled skill and template rather than depending on an independently versioned schema.
+
+## Related
+
+- [Project lifecycle](projects/lifecycle.md)
+- [Implementation execution](projects/implementation-execution.md)
+- [Project artifacts](projects/artifacts.md)

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.74",
-  "docs-config": "0.1.74",
-  "docs-theme": "0.1.74",
-  "docs-transforms": "0.1.74"
+  "cli": "0.2.0",
+  "docs-config": "0.2.0",
+  "docs-theme": "0.2.0",
+  "docs-transforms": "0.2.0"
 }

package/assets/skills/create-agnostic-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-agnostic-skill
-version: 1.4.0
+version: 1.4.1
 description: Use when adding a reusable workflow skill for AI coding agents. Scaffolds a new .agents/skills skill using the Agent Skills open standard.
 argument-hint: '[skill-name]'
 disable-model-invocation: true