Provider Interop Commands

Shared conventions

These command definitions inherit the cross-cutting CLI conventions in:

• ../contributing/design-principles

Adjacent command docs (outside provider interop scope)

• oat init (bootstrap): ../cli-utilities/bootstrap.md
• oat tools ... (tool-pack lifecycle — install, update, remove, list, info): ../cli-utilities/tool-packs.md
• oat doctor (cross-cutting diagnostics): ../reference/cli-reference.md

Quick Look

• What it does: defines the day-to-day provider-sync command surface for inspecting state, reconciling provider views, and changing provider enablement.
• When to use it: after you have canonical assets in place and need to check sync state, write provider views, or change provider config.
• Primary commands: oat status, oat sync, oat providers list, oat providers inspect, oat providers set, oat providers codex materialize

oat status

Purpose:

• Report in_sync, drifted, missing, and stray states

Key behavior:

• Scope support (project, user, all)
• Optional interactive stray adoption
• Cursor-local and Copilot-local skills are handled individually: Adopt moves the skill into the matching canonical .agents/skills directory, while Keep provider-only preserves it and records its exact path in the applicable sync config
• Aborting a native-read skill migration preserves completed choices and leaves the current and remaining skills unresolved
• Keep provider-only is blocked when a canonical skill has the same name; rename one skill before retrying
• Non-interactive and JSON modes report unresolved native-read skill actions without choosing or mutating a disposition
• JSON output for automation

oat sync

Purpose:

• Reconcile provider views from canonical sources

Key behavior:

• Mutates by default; use --dry-run to preview
• Strategy-aware operations (symlink, copy, auto)
• Configured auto may adopt an existing exact collection-directory alias. When the destination is absent, the current runtime falls back per entry; OAT does not create or unlink a collection alias without identity-bound guarded primitives. Configuring an explicit per-entry strategy does not release an owned collection: the current runtime fails closed for deferred collection-directory copies and symlinks because it cannot keep every destination ancestor identity-bound. To leave the provider directory externally owned, run oat providers set --scope <scope> --disabled <provider> and then oat sync --scope <scope> to detach OAT ownership. Then verify and remove the preserved alias before managing that directory manually. Automatic transition requires an identity-bound, non-following publication primitive. Deferred file operations and ordinary non-transition per-entry symlinks retain their existing behavior. Explicit symlink and copy remain per-entry modes; oat sync does not add a --strategy option.
• Provider enable/disable honored via sync config
• Cursor skills are native-read from canonical .agents/skills; sync does not create .cursor/skills mirrors
• Copilot skills are native-read from canonical .agents/skills; sync does not create .github/skills or ~/.copilot/skills mirrors. Copilot agents and project rules still sync to .github/agents, ~/.copilot/agents, and .github/instructions.
• Upgrade cleanup removes only verified clean legacy Cursor or Copilot skill views. Changed or unverified views are preserved and detached from obsolete manifest ownership.
• Before the dry-run/apply branch, each scope's sync manifest oatVersion is compared with the invoking CLI version. Any difference (older or newer) logs an advisory warning naming the scope and both versions; the run continues and the apply path restamps the manifest with the invoking version. JSON output suppresses the warning and reports the same data under a top-level versionSkew array ({ scope, producingVersion, invokingVersion }) in both --dry-run and apply envelopes; a scope without skew is omitted from the array.
• When a run's only effect is that restamp — no planned operations and no failures, but skew present — apply reports Manifest version refreshed; no content changes required. instead of No changes required., so a manifest write is never described as a no-op.

oat sync is not the only command that replaces a manifest's producer version. oat init, oat remove skill, and oat status each capture the manifest's pre-mutation oatVersion while loading and planning, compare it with the invoking CLI version, and log the same advisory immediately before a qualifying save when the two differ:

Manifest version restamp [init user]: manifest produced by oat "0.2.58" will be restamped to oat "0.2.59".

The advisory sits immediately before the save, so a run that aborts earlier never announces a restamp it did not perform; a save that fails after the advisory still leaves the manifest unrestamped. An equal or absent version stays quiet. JSON mode suppresses the human warning; oat init and oat remove skill report the applied restamps under a top-level manifestVersionRestamps array of { scope, producingVersion, invokingVersion } entries. The oat remove skill dry-run payload omits the field rather than naming a restamp no save will perform.

Preview project and user cleanup before applying it:

oat sync --scope all --dry-run

Review every planned remove and detach operation before running the same command without --dry-run.

Dry-run and apply output include a Collection aliases section with scope, provider, content kind, action, ownership, scope-relative canonical/provider directories, reason, and planned or applied result. JSON reports the same redacted fields under collectionOperations; collection proofs are reduced to status and a safe reason rather than filesystem identities or absolute scope roots. Real-directory fallback is reported as fallback-per-entry.

oat providers list

Purpose:

• Summarize adapters, detection, and mapping-level health summary
• Summarize managed collection aliases by oat-created and adopted-exact ownership in both human and JSON output

oat providers inspect <provider>

Purpose:

• Show adapter mappings and per-scope mapping state details
• Show each owned collection alias with scope-relative paths, ownership, and last-verification time

oat providers set

Purpose:

• Enable or disable providers in the selected scope's sync config; project is the default scope

Key behavior:

• Updates the selected scope's sync config to toggle provider enablement
• Scope: --scope project|user (defaults to project)
• Options: --enabled <providers>, --disabled <providers> (comma-separated)
• Changes take effect on next oat sync

oat providers codex materialize

Purpose:

• Materialize one canonical Markdown agent as a Codex TOML role and register it in Codex configuration

Required operands:

oat providers codex materialize <agent-name> \
  --model <model-id> \
  --effort <reasoning-effort>

Key behavior:

• Project scope is the default and writes only .codex/config.toml plus the project role file; --scope user writes only under ~/.codex
• --agent-path selects a specific canonical agent and --role-name overrides the generated role name
• Managed role registration enables multi-agent support and merges an agents.max_depth floor of 2
• Project writes preserve a higher existing project depth or inherited user depth without mutating user configuration; user writes do not inspect or mutate project configuration
• Existing unrelated Codex configuration and custom roles are preserved

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

These commands are documented here because they are commonly used during interop-only repo maintenance, but they are not provider sync/drift commands.

oat instructions validate

Purpose:

• Validate project-scoped AGENTS.md to CLAUDE.md integrity

Key behavior:

• Read-only validation of nested project-scoped instruction directories
• Supports --strategy pointer|symlink|copy to validate the expected file shape
• Reports ok, missing, content_mismatch, and stray states
• Detects Claude-only adoptable directories and unreadable/broken instruction paths as drift
• Skips the derived documentation content root and any documentation.instructionPointerExcludes paths, using the same exclusions as oat instructions sync
• Exit code 0 when all entries are valid, 1 when drift is detected
• Detailed behavior: Instruction Sync

oat instructions sync

Purpose:

• Repair project-scoped AGENTS.md to CLAUDE.md drift

Key behavior:

• Mutates by default; use --dry-run to preview changes
• Supports --strategy pointer|symlink|copy
• Creates missing CLAUDE.md files using the selected strategy
• Adopts Claude-only stray files by writing canonical AGENTS.md content first, then regenerating CLAUDE.md
• Skips mismatched files unless --force is provided
• Skips unreadable canonical or Claude-only sources and reports manual-repair guidance instead of forcing recovery
• Skips the documentation content tree (<documentation.root>/docs when that is a directory, otherwise documentation.root) plus any documentation.instructionPointerExcludes paths, so authored pages never receive pointers; app-level instruction files such as apps/oat-docs/AGENTS.md are still synced
• Never deletes an existing CLAUDE.md inside an excluded tree
• Uses pointer content @AGENTS.md\n, file symlinks, or hard copies depending on the selected strategy
• Detailed behavior and examples: Instruction Sync