@open-agent-toolkit/cli 0.1.74 → 0.1.76

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/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/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.1.76",
+  "docs-config": "0.1.76",
+  "docs-theme": "0.1.76",
+  "docs-transforms": "0.1.76"
 }

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

package/assets/skills/create-agnostic-skill/references/docs/skills-guide.md

@@ -2,7 +2,7 @@
 
 Agent Skills ecosystem research and notes across providers.
 
-_Last updated: February 2026_
+_Last updated: July 2026_
 
 ---
 
@@ -194,15 +194,20 @@ Legend: ✅ documented support | ⚠️ provider-specific semantics | 💤 ignor
 **Skill locations:**
 
 - Project:
+  - `.agents/skills/<skill-name>/SKILL.md` (**portable canonical path**)
   - `.cursor/skills/<skill-name>/SKILL.md`
   - `.claude/skills/<skill-name>/SKILL.md` (**Claude compatibility**)
   - `.codex/skills/<skill-name>/SKILL.md` (**Codex compatibility**)
 - Personal:
+  - `~/.agents/skills/<skill-name>/SKILL.md` (**portable canonical path**)
   - `~/.cursor/skills/<skill-name>/SKILL.md`
   - `~/.claude/skills/<skill-name>/SKILL.md` (**Claude compatibility**)
   - `~/.codex/skills/<skill-name>/SKILL.md` (**Codex compatibility**)
 
-**Notable:** Cursor explicitly reads from `.claude/skills/` and `.codex/skills/` for cross-tool compatibility. This means skills authored in `.claude/skills/` are automatically available in Cursor without symlinking.
+**Notable:** Cursor reads `.agents/skills/` natively at project and user scope, so
+portable canonical skills need no Cursor mirror. `.cursor/skills/` remains a
+supported home for Cursor-only skills. Cursor also reads `.claude/skills/` and
+`.codex/skills/` for compatibility.
 
 **Documented frontmatter fields:**
 
@@ -341,13 +346,13 @@ Installs skills from GitHub repos, local paths, or GitLab URLs to any supported
 Author skills in `.agents/skills/` (canonical) and distribute to provider-specific directories:
 
 ```bash
-# Claude Code + Cursor (Cursor reads .claude/skills/ natively)
+# Claude Code
 ln -s ../../.agents/skills/my-skill .claude/skills/my-skill
 
 # GitHub Copilot
 ln -s ../../.agents/skills/my-skill .github/skills/my-skill
 
-# Codex reads .agents/skills/ natively at project level — no symlink needed
+# Cursor, Codex, and Gemini read .agents/skills/ natively — no symlink needed
 ```
 
 For automated distribution, use **OAT sync** (for local/internal skills) or **`npx skills add`** (for remote/community skills):
@@ -360,9 +365,11 @@ oat sync --scope all
 npx skills add github-user/skill-repo -a claude-code -a github-copilot
 ```
 
-**Result: one canonical source, two symlinks, four tools.**
+**Result: one canonical source, two symlinks, five tools.**
 
-**Note:** Cursor already reads `.claude/skills/` natively, so the Claude Code symlink covers both. Codex reads `.agents/skills/` at project level (per Vercel skills docs), eliminating its symlink entirely.
+**Note:** Cursor, Codex, and Gemini read `.agents/skills/` directly at project
+and user scope. Keep `.cursor/skills/` for intentionally Cursor-only skills,
+not as a generated mirror of canonical content.
 
 ---
 
@@ -516,31 +523,33 @@ The proposal has community interest but no official timeline or maintainer respo
 
 **Source:** https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices, https://github.com/agentskills/agentskills/tree/main/skills-ref
 
-### Q: Cursor reads `.claude/skills/` natively — does this make `.agents/skills/` + symlinks unnecessary?
+### Q: Does Cursor's native `.agents/skills/` support eliminate all provider views?
 
-**Answer:** No. While Cursor reading `.claude/skills/` is convenient, it only covers two of four required tools:
+**Answer:** No. Cursor, Codex, and Gemini need no skill mirror, but Claude Code
+and GitHub Copilot still use provider-specific paths:
 
 | Tool           | Native Path       | Reads `.claude/skills/`? | Reads `.agents/skills/`? |
 | -------------- | ----------------- | ------------------------ | ------------------------ |
 | Claude Code    | `.claude/skills/` | ✅ (native)              | ❌                       |
-| Cursor         | `.cursor/skills/` | ✅ (cross-compat)        | ❌                       |
+| Cursor         | `.agents/skills/` | ✅ (compatibility)       | ✅ (native)              |
 | Codex CLI      | `.agents/skills/` | ❌                       | ✅ (native)              |
-| GitHub Copilot | `.github/skills/` | ✅ (cross-compat)        | ❌                       |
-| Gemini CLI     | `.gemini/skills/` | ❌                       | ✅ (native alias)        |
+| GitHub Copilot | `.github/skills/` | ✅ (compatibility)       | ❌                       |
+| Gemini CLI     | `.agents/skills/` | ❌                       | ✅ (native alias)        |
 
 **Recommended approach:** Author skills in `.agents/skills/` (tool-agnostic canonical source), then symlink only where needed:
 
 ```bash
 # Two symlinks needed:
-ln -s ../../.agents/skills/my-skill .claude/skills/my-skill    # Claude Code + Cursor + Copilot
+ln -s ../../.agents/skills/my-skill .claude/skills/my-skill    # Claude Code + Copilot compatibility
 ln -s ../../.agents/skills/my-skill .github/skills/my-skill    # GitHub Copilot (native path)
-# Codex reads .agents/skills/ natively — no symlink needed
-# Gemini reads .agents/skills/ natively — no symlink needed
+# Cursor, Codex, and Gemini read .agents/skills/ natively — no symlink needed
 ```
 
 **One canonical source, two symlinks, five tools.** (Copilot reads `.claude/skills/` cross-compat, so the `.github/skills` symlink is optional but recommended for explicitness.)
 
-**Note (updated Feb 2026):** Codex now reads `.agents/skills/` natively at both project level (`$CWD/.agents/skills` up to `$REPO_ROOT/.agents/skills`) and user level (`$HOME/.agents/skills`). Gemini CLI also reads `.agents/skills/` natively at both workspace and user scopes. No symlinks needed for Codex or Gemini at any scope.
+**Note (updated July 2026):** Cursor, Codex, and Gemini read
+`.agents/skills/` natively at project and user scope. No skill symlinks are
+needed for those providers.
 
 **Source:** https://cursor.com/docs/context/skills, https://code.visualstudio.com/docs/copilot/customization/agent-skills, https://developers.openai.com/codex/skills, https://github.com/vercel-labs/skills
 

package/assets/skills/oat-agent-instructions-analyze/references/docs/provider-reference.md

@@ -2,7 +2,7 @@
 
 Quick reference for skills, subagents, hooks, and agent instructions across all major AI coding tools.
 
-_Last updated: February 2026_
+_Last updated: July 2026_
 
 ---
 
@@ -144,11 +144,17 @@ The package manager for the agent skills ecosystem. Installs skills across 27+ a
 
 **Skill locations:**
 
-- Project: `.cursor/skills/<skill-name>/SKILL.md`
-- Personal: `~/.cursor/skills/<skill-name>/SKILL.md`
+- **Portable project skills:** `.agents/skills/<skill-name>/SKILL.md`
+- **Portable personal skills:** `~/.agents/skills/<skill-name>/SKILL.md`
+- **Cursor-only project skills:** `.cursor/skills/<skill-name>/SKILL.md`
+- **Cursor-only personal skills:** `~/.cursor/skills/<skill-name>/SKILL.md`
 - **Claude compatibility:** `.claude/skills/` (project) and `~/.claude/skills/` (personal)
 - **Codex compatibility:** `.codex/skills/` (project) and `~/.codex/skills/` (personal)
 
+OAT keeps portable skills canonical under `.agents/skills`; it does not
+generate `.cursor/skills` mirrors. Cursor-specific skill directories remain
+supported as intentional local extensions and migration sources.
+
 ### Subagents
 
 | Resource                    | URL                                       |

package/assets/skills/oat-agent-instructions-apply/references/docs/provider-reference.md

@@ -2,7 +2,7 @@
 
 Quick reference for skills, subagents, hooks, and agent instructions across all major AI coding tools.
 
-_Last updated: February 2026_
+_Last updated: July 2026_
 
 ---
 
@@ -144,11 +144,17 @@ The package manager for the agent skills ecosystem. Installs skills across 27+ a
 
 **Skill locations:**
 
-- Project: `.cursor/skills/<skill-name>/SKILL.md`
-- Personal: `~/.cursor/skills/<skill-name>/SKILL.md`
+- **Portable project skills:** `.agents/skills/<skill-name>/SKILL.md`
+- **Portable personal skills:** `~/.agents/skills/<skill-name>/SKILL.md`
+- **Cursor-only project skills:** `.cursor/skills/<skill-name>/SKILL.md`
+- **Cursor-only personal skills:** `~/.cursor/skills/<skill-name>/SKILL.md`
 - **Claude compatibility:** `.claude/skills/` (project) and `~/.claude/skills/` (personal)
 - **Codex compatibility:** `.codex/skills/` (project) and `~/.codex/skills/` (personal)
 
+OAT keeps portable skills canonical under `.agents/skills`; it does not
+generate `.cursor/skills` mirrors. Cursor-specific skill directories remain
+supported as intentional local extensions and migration sources.
+
 ### Subagents
 
 | Resource                    | URL                                       |

package/dist/commands/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAezC,OAAO,EAML,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAehB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAGL,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAC/B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,mCAAmC,EACnC,0BAA0B,EAC3B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyFpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC7C,mCAAmC,EAAE,OAAO,mCAAmC,CAAC;IAChF,0BAA0B,EAAE,OAAO,0BAA0B,CAAC;IAC9D,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAkhED,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsKT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAezC,OAAO,EAML,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAehB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAGL,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAC/B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,mCAAmC,EACnC,0BAA0B,EAC3B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyFpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC7C,mCAAmC,EAAE,OAAO,mCAAmC,CAAC;IAChF,0BAA0B,EAAE,OAAO,0BAA0B,CAAC;IAC9D,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AA6kED,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsKT"}