@open-agent-toolkit/cli 0.1.73 → 0.1.76

package/assets/config/dispatch-matrix-recommendation.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026-07-10.2",
+  "version": "2026-07-11.1",
   "providers": {
     "codex": {
       "economy": {
@@ -101,29 +101,25 @@
     "cursor": {
       "economy": {
         "candidates": [
-          "gpt-5.6-luna-low",
-          "gpt-5.6-luna-medium",
-          "gpt-5.6-luna-high"
+          "composer-2.5",
+          "claude-sonnet-5-high",
+          "gpt-5.6-luna-high",
+          "gpt-5.6-luna-xhigh"
         ]
       },
       "balanced": {
-        "candidates": [
-          "gpt-5.6-luna-xhigh",
-          "gpt-5.6-terra-low",
-          "gpt-5.6-terra-medium",
-          "gpt-5.6-terra-high",
-          "gpt-5.6-terra-xhigh"
-        ]
+        "candidates": ["cursor-grok-4.5-high", "gpt-5.6-terra-high"]
       },
       "high": {
-        "candidates": [
-          "gpt-5.6-sol-low",
-          "gpt-5.6-sol-medium",
-          "gpt-5.6-sol-high"
-        ]
+        "candidates": ["gpt-5.6-sol-medium", "gpt-5.6-sol-high"]
       },
       "frontier": {
-        "candidates": ["gpt-5.6-sol-xhigh", "gpt-5.6-sol-max"]
+        "candidates": [
+          "claude-fable-5-thinking-high",
+          "claude-fable-5-thinking-xhigh",
+          "gpt-5.6-sol-xhigh",
+          "gpt-5.6-sol-max"
+        ]
       }
     }
   }

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
 
@@ -232,14 +234,15 @@ values. Planning shows the complete bundled recommendation before asking for
 this scope, then rechecks the effective ladder. If explicit cells still leave
 the ladder incomplete, readiness blocks; OAT does not overwrite them.
 
-Scope determines ownership and Codex materialization:
+Scope determines ownership and Codex/Cursor materialization:
 
 - `--shared` and `--local` are project configuration sources. Their configured
-  Codex candidates materialize into the tracked project `.codex` view.
+  Codex and Cursor candidates materialize into the tracked project `.codex`
+  and `.cursor` views.
 - `--user` writes reusable personal defaults to `~/.oat/config.json`; those
-  Codex candidates materialize under `~/.codex`.
-- Active-project sparse candidates also materialize into the tracked project
-  view.
+  candidates materialize under `~/.codex` and `~/.cursor`.
+- Active-project sparse candidates also materialize into the applicable tracked
+  project view.
 
 Project-generated provider views remain visible to version control. OAT does
 not auto-ignore them. A project-specific active policy or ceiling must not be
@@ -274,7 +277,7 @@ even when the reusable ladder is user-owned.
         },
         "cursor": {
           "balanced": {
-            "candidates": ["opaque:model/lower [v1]", "opaque:model/high [v2]"]
+            "candidates": ["cursor-grok-4.5-high", "gpt-5.6-terra-high"]
           }
         }
       }
@@ -285,9 +288,11 @@ even when the reusable ladder is user-owned.
 
 The bundled recommendation covers 13 Codex model/effort combinations: Luna and
 Terra at `low`, `medium`, `high`, and `xhigh`, plus Sol at those efforts and
-`max`. Claude covers `haiku`, `sonnet`, `opus`, and `fable`. Cursor covers 13
-opaque configured strings. Cursor spelling never supplies capability metadata;
-the configured candidate position owns the tier meaning.
+`max`. Claude covers `haiku`, `sonnet`, `opus`, and `fable`. Cursor covers 12
+verified multi-family flat IDs across Composer, Claude, GPT, and Grok. An
+explicit mapping connects each flat ladder ID to a separate bracket-form
+frontmatter model; configuration and skills never derive or normalize either
+form.
 
 The corresponding pinned Codex variant catalogue includes
 `gpt-5.6-luna-high`, `gpt-5.6-terra-xhigh`, `gpt-5.6-sol-high`, and
@@ -360,7 +365,7 @@ oat project dispatch-ceiling resolve \
   --provider cursor \
   --role implementer \
   --ceiling-tier high \
-  --candidate-model 'opaque:model/lower [v1]' \
+  --candidate-model gpt-5.6-sol-high \
   --json
 ```
 
@@ -381,11 +386,12 @@ remains compatibility behavior for legacy scalar ceilings and managed
 | -------- | ---------------------------------------------------------------------------------------------------- |
 | Codex    | `providers.codex.dispatchArgs.variant` as `agent_type`, or a fresh child pinned to model plus effort |
 | Claude   | `providers.claude.dispatchArgs.model` as the actual Agent `model`                                    |
-| Cursor   | `providers.cursor.dispatchArgs.model` byte-for-byte as the actual opaque invocation model            |
+| Cursor   | `providers.cursor.dispatchArgs.variant` as the exact native agent type first                         |
 
-Project sync materializes the supported Codex catalogue and every configured
-project-owned candidate for both `oat-phase-implementer` and `oat-reviewer`.
-User sync materializes user-owned candidates under `~/.codex`:
+Project sync materializes the supported Codex and Cursor catalogues and every
+configured project-owned candidate for both `oat-phase-implementer` and
+`oat-reviewer`. User sync materializes user-owned candidates under `~/.codex`
+and `~/.cursor/agents`:
 
 ```bash
 oat sync --scope project
@@ -394,60 +400,31 @@ oat sync --scope all
 ```
 
 Generated roles carry `supported-catalogue`, `project-config`, or `user-config`
-ownership. Cleanup reconciles only the current owner. Materialization is best
-effort at sync boundaries; the exact fresh-child route means workflow
-correctness does not require provider restart or hot reload.
+ownership. Cleanup reconciles only the current owner. Cursor's mapping registry
+rejects unknown flat IDs instead of writing unverified frontmatter.
 
 Reviewer resolution uses the final candidate at the configured review ceiling.
-Codex selects the exact reviewer variant; Claude and Cursor pass the resolver's
-exact model argument. Timeout retries preserve the same complete payload. A
-lower reviewer candidate requires a separate reviewed contract.
+Codex and Cursor select exact native reviewer variants; Claude passes the
+resolver's exact model argument. Timeout retries preserve the same complete
+payload. A lower reviewer candidate requires a separate reviewed contract.
 
 Tier 2 remains target-preserving. Inline review is permitted only when the host
 has verified equivalent current-host controls for explicit inherit,
 managed-uncapped, or base-role behavior. Capped managed reviews still require
 the exact registered role, pinned child, or resolver-returned model argument.
 
-### Cursor validation pass and live evidence
-
-Config adoption and doctor validate Cursor candidates with one command-scoped
-pass context. Duplicate references to the same byte-for-byte candidate share
-one Task/subagent probe. If a decisive probe is unavailable, the pass resolves
-the broad catalog once, with at most one `--list-models` fallback. The cache
-ends with that adopt or doctor command; it is not process-global and has no
-TTL.
-
-A correlated Task start/completion pair that preserves the exact model argument
-and returns the sentinel establishes that the argument is eligible for that
-account and client. A structured rejection or exact allow-list exclusion can
-establish `unknown-value`. Neither result identifies the backend runtime model:
-`runtimeIdentity` remains `not-reported` unless trusted Cursor telemetry or
-Cursor support confirms it. Parent prose and broad catalog presence are
-diagnostic-only, so OAT preserves `unvalidated` when launcher evidence is
-absent instead of inferring capability from candidate spelling.
-
-The [dated GPT-5.6 Cursor verification evidence](https://github.com/voxmedia/open-agent-toolkit/blob/main/.oat/repo/reference/project-summaries/20260711-cursor-gpt-5-6-subagent-verification.md)
-preserves the original text-mode pass and a versioned stream-JSON second pass.
-The second pass ran a dynamic positive control and deliberate invalid control
-before candidates. Both parent runs completed without a Task event, making the
-controls inconclusive; the stop rule therefore executed zero of the 13
-recommended candidates and did not execute exploratory
-`gpt-5.6-sol-high-fast`. The recommendation remains unchanged and candidate
-eligibility remains unresolved.
-
-The tracked artifact's structured second-pass block contains only allowlisted
-event structure, derived outcomes, sanitized auth-presence context, and
-non-reversible identifier hashes. Exact request/session/tool-call IDs and
-credential-redacted unprojected streams from that pass stay under gitignored
-`.oat/projects/local/` storage for possible Cursor support diagnosis.
-
-The same public artifact intentionally retains the sanitized historical v1
-text-mode record for provenance. That older section includes command arguments
-and prompts, stdout and stderr, exit and duration data, and capture-environment
-details such as user-specific binary paths; it is not limited to the structured
-second-pass allowlist. Re-run after a Cursor client rollout exposes Task in
-headless mode or Cursor support confirms the private requests; review the open
-verification item by 2026-08-08.
+### Cursor availability and evidence
+
+`oat doctor` compares configured Cursor flat IDs with the current Cursor
+catalogue and reports availability drift. This check is diagnostic: catalogue
+presence does not prove that a bracket-form definition pin was honored.
+
+Each shipped mapping has mapping-specific native-launch evidence, but Cursor
+can silently fallback when account, plan, or administration constraints prevent
+the requested pin. OAT therefore records the selected variant and mapped model
+with launcher-owned `configured` provenance. Runtime identity remains
+`not-reported` unless independently observed; self-report and catalogue
+availability do not upgrade that evidence.
 
 ### Legacy compatibility
 
@@ -659,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/workflow-gates.md

@@ -94,6 +94,37 @@ model that ran, and the reviewer must not replace them with self-identification.
 The CLI compares the copied values with its gate-owned record before it applies
 the severity threshold.
 
+### Review producer identity
+
+Dynamic planning workflows can declare their current parent model to a review
+gate without writing a provider or model into shared/user config:
+
+```bash
+OAT_GATE_PRODUCER_IDENTITY='<model>:declared' oat gate review ...
+```
+
+This is a review-command-only bridge. `oat gate review` accepts it only when
+the value is non-empty and its provenance suffix is exactly `declared`. The
+gate removes the variable from the child reviewer's environment, and non-review
+commands such as `oat gate cross-provider-exec` ignore it.
+
+Producer evidence precedence is explicit `--producer-identity`, then a
+qualifying implementation dispatch stamp, then the review-only environment
+declaration, and finally unknown producer behavior. The environment bridge does
+not replace stronger explicit or stamped evidence and does not establish
+observed runtime identity.
+
+For final and contiguous-range reviews, each in-scope implementer/fix stamp
+contributes its claimable producer family. If that producer is not claimable or
+has an unknown family, the gate may infer only a family exclusion from the
+stamp's launcher-owned configured target. The target does not become producer
+runtime identity, and generic or unclassifiable targets contribute no family.
+
+Keep reusable gate commands producer-neutral in shared and user config.
+Planning skills attach the ephemeral declaration only while executing a
+resolved configured command that invokes `oat gate review`; they leave it
+absent for every other gate command.
+
 ### Headless completion safety
 
 Every `oat gate review` child receives the same headless contract through two
@@ -492,7 +523,9 @@ By default the dispatcher:
 4. Resolves producer identity from `--producer-identity` or dispatch stamps when
    available. Exact phase/task scopes use the matching stamp. `final` and
    contiguous ranges such as `p02-p03` aggregate every in-range implementer/fix
-   stamp.
+   stamp. A stamp whose producer is not claimable or has an unknown family may
+   contribute its classifiable configured target family to aggregate avoidance
+   at lower confidence.
 5. Applies `--avoid same-family`.
 6. Checks candidate availability in descending priority order, with target id as
    the tie-breaker.
@@ -537,7 +570,10 @@ single stamp or when no stamp has a claimable family. Their producer record uses
 an unknown representative instead of presenting the latest stamp as aggregate
 truth:
 
-- `avoidFamilies` is the stable deduplicated union of claimable known families.
+- `avoidFamilies` is the stable deduplicated union of claimable known producer
+  families plus classifiable configured target families from stamps whose
+  producer is not claimable or has an unknown family. A known, claimable
+  producer remains authoritative over a conflicting target.
 - `contributingScopes` is the stable document-order list of distinct scopes from
   every relevant stamp.
 - `contributingStampCount` counts every relevant stamp, including unknown or

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,16 +16,17 @@ 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`
-    - Subagent invocation in Cursor is prompt-driven (`/name` or natural mention), not `subagent_type`
-    - OAT-controlled Cursor dispatch uses the generic `.cursor/agents/<name>.md` file plus the exact `providers.cursor.dispatchArgs.model` value selected from the candidate ladder. OAT passes it byte-for-byte as the actual Task-level `model`; a `model` frontmatter value is only a default/fallback mechanism.
-    - Cursor model strings are opaque. OAT does not infer family, effort, cost, or capability from their spelling; the configured candidate position owns the named tier meaning.
-    - Cursor model validation checks whether the selected model is eligible for subagent Task dispatch. Each adopt/doctor command probes each distinct exact candidate once and shares one lazy broad-catalog lookup across that pass; the cache ends with the command.
-    - A correlated accepted Task carrying the exact model argument plus the child sentinel proves argument eligibility for that account/client. It does not prove backend runtime identity; that remains `not-reported` without trusted Cursor telemetry or support confirmation. Structured rejection can establish `unknown-value`, while parent prose and broad `cursor-agent models` catalog presence remain diagnostic-only.
-    - The [dated GPT-5.6 verification artifact](https://github.com/voxmedia/open-agent-toolkit/blob/main/.oat/repo/reference/project-summaries/20260711-cursor-gpt-5-6-subagent-verification.md) preserves the original probe and a stream-JSON control pass. The controls observed no Task events, so the stop rule ran zero recommendation or exploratory candidates and retained the recommendation unchanged.
-    - The artifact's structured second-pass block contains only allowlisted event fields, derived outcomes, sanitized auth presence, and identifier hashes. Exact request/session/tool-call IDs and credential-redacted unprojected streams from that pass remain in gitignored local project storage for support escalation.
-    - The same public artifact retains the sanitized historical v1 text-mode record for provenance. That older section includes command arguments and prompts, stdout and stderr, exit and duration data, and capture-environment details such as user-specific binary paths; it is not limited to the structured second-pass allowlist.
+    - 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.
+    - Cursor may silently fallback when a definition pin cannot be honored. Variant acceptance therefore establishes launcher-owned `configured` provenance only; runtime identity remains `not-reported` unless independently observed.
+    - `oat doctor` checks whether each flat ID is still present in the current Cursor catalogue and reports availability drift. Catalogue availability is diagnostic and does not prove that a definition-level bracket pin ran as configured.
     - Rule files render as `.cursor/rules/*.mdc`
 
 === "Copilot"
@@ -81,9 +82,9 @@ oat config adopt dispatch-matrix --user
 ```
 
 Project-config candidates materialize into the tracked, version-controlled
-project `.codex` view. User-config candidates materialize under `~/.codex`.
-OAT does not auto-ignore project output or create its Git commit; the team owns
-that repository change.
+project `.codex` and `.cursor` views. User-config candidates materialize under
+`~/.codex` and `~/.cursor`. OAT does not auto-ignore project output or create
+its Git commit; the team owns that repository change.
 
 At implementation time, the root passes the recorded named maximum through
 invocation-only `--ceiling-tier`, resolves one exact candidate per phase, and
@@ -91,24 +92,27 @@ dispatches one phase implementer. Codex first attempts the resolver-returned
 materialized role as the native `agent_type`. The launcher records the target,
 model axis, and effort axis from that resolved payload; child self-report is not
 provenance and cannot replace those values.
-Only an explicit pre-start native role-selection rejection permits a fresh
-pinned-child fallback. An accepted child, including one that later returns
+Only an explicit pre-start native role-selection rejection permits another
+target-preserving route. An accepted child, including one that later returns
 `BLOCKED` or lacks telemetry, is a task outcome rather than a fallback signal.
-Claude and Cursor bind the exact model arguments described above. A missing or
-unselectable managed target blocks rather than falling back to the root target
-or a base role.
+Claude binds the exact model argument described above. Cursor launches the
+exact native variant. A missing or unselectable managed target blocks rather
+than falling back to the root target or a base role.
 
 ## Scope rules
 
 - Project scope: skills + agents + rules
-- User scope: skills, plus the two bundled managed Codex role definitions used only for user-owned target expansion (provider mappings vary by adapter)
+- User scope: skills, plus the two bundled managed Codex and Cursor role definitions used only for user-owned target expansion (provider mappings vary by adapter)
 - Rules are project-scoped only in this release
 - Codex user-scope sync materializes user-config custom roles under `~/.codex`; project-config and supported-catalogue output remains project-scoped and version controlled
+- Cursor user-scope sync materializes user-config variants under `~/.cursor/agents`; project-config and supported-catalogue output remains project-scoped and version controlled
 
 ## Adoption model
 
 - 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`.