@open-agent-toolkit/cli 0.2.63 → 0.2.65

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.63"
+  "oatVersion": "0.2.65"
 }

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

@@ -307,6 +307,57 @@ application-process restart requirement, or proof of visibility. No advice is
 emitted for current/no-op, planned-only, failed, missing, inactive, or
 unsupported materialization.
 
+Every pack lifecycle outcome (`install`, `update`, `remove`, and the aggregate
+init path) and every pack inventory surface (`oat tools list`, `oat tools
+info`, `oat status`, `oat doctor`) carries per-provider reachability evidence
+in its JSON, derived from the same config-aware registry the sync engine uses:
+activation, content capability, projection, materialization, catalog-refresh
+visibility, and recovery guidance. Human output names the provider on its own
+line and on any provider-attributed diagnostic. Reachability is never inferred
+from the presence of a provider directory on disk.
+
+The four inventory surfaces agree on managed user-scope roles. `list` and
+`info` resolve the same provider surface as `status` and `doctor`, so an
+active Codex or Cursor adapter that supplies managed roles suppresses the
+unmaterialized-user-agent report on all four rather than only two.
+
+Each provider state maps to exactly one row below. Pack evidence status and
+the lifecycle exit code derive from the **severity** column, never from the
+code name, so adding a code later cannot silently change an exit code.
+
+| Provider state (per provider, scope, content kind)                     | Diagnostic code                         | Severity  | Pack evidence status | Lifecycle outcome / exit code                    |
+| ---------------------------------------------------------------------- | --------------------------------------- | --------- | -------------------- | ------------------------------------------------ |
+| Active, supported, projection and materialization succeeded            | none                                    | --        | `ok`                 | `complete` / 0                                   |
+| Explicitly disabled in sync config for this scope                      | `provider-inactive`                     | `info`    | `ok`                 | `complete` / 0                                   |
+| Active but the content kind is unsupported by the adapter              | `provider-unsupported`                  | `info`    | `ok`                 | `complete` / 0                                   |
+| Active, supported, no projection exists (never synced or sync skipped) | `provider-materialization-missing`      | `warning` | `partial`            | `complete` / 0 (install succeeded; sync advised) |
+| Active, supported, the sync operation for this asset failed            | `provider-materialization-failed`       | `error`   | `partial`            | `partial` / 1                                    |
+| Active, projected, no sourced refresh contract for the host            | `visibility-unknown`                    | `info`    | `ok`                 | `complete` / 0                                   |
+| Active, projected, host catalog needs a refresh or a restart           | `refresh-required` / `restart-required` | `info`    | `ok`                 | `complete` / 0                                   |
+| Read-only inventory (`list`, `info`, `status`, `doctor`): no sync ran  | registry-derived codes only             | as above  | as above             | not applicable                                   |
+| Auto-sync not run (disabled or skipped) after a lifecycle operation    | none; `providerSync.status: 'not-run'`  | --        | `ok`                 | `complete` / 0                                   |
+
+Rows with `info` severity are visible in JSON and in the human provider line
+but do not turn `ok` into `partial`. A provider that was never detected and
+never configured is not reported per pack: its inactive state is still carried
+on the evidence row, but emitting a diagnostic for every registered provider on
+every pack would bury the actionable rows. `unknown` visibility is reported as
+unknown; it never claims reachability and never fails an otherwise successful
+install. A read-only inventory surface ran no sync, so it never reports
+`provider-materialization-failed`.
+
+The three visibility codes — `visibility-unknown`, `refresh-required`, and
+`restart-required` — are lifecycle-only for the same reason. They require an
+established projection, and a read-only surface never establishes one: it
+observed no sync, so it reports materialization as a non-claim rather than
+asserting the provider view exists. For an active provider that supports the
+content kind, the registered catalog state remains readable in the row's
+`visibility` field on every surface; only the diagnostics are withheld. Run
+`oat tools install`, `update`, or `remove` to see them emitted. An inactive or
+unsupported row reports `not-applicable` visibility instead, matching its
+`not-applicable` projection: catalog advice about a provider that cannot
+receive the content would read as a step to act on.
+
 Repository templates under `.oat/templates/` are **owner-owned seeds**. OAT
 compares a source-backed seed with its bundled default: a byte-equivalent copy
 is reported as current, while an edited copy is retained and reported as a
@@ -512,8 +563,40 @@ Key behavior:
 
 - Displays name, type (skill/agent), version, bundled version, pack, scope, and status
 - Reports whether the tool is invocable (for skills) and whether an update is available
+- For a skill, adds a read-only provider-view section per active provider and scope: the expected provider path, the view class, and versions where a copy makes them comparable
+- Suggests the narrowest safe repair, one `oat sync --scope <concrete>` per affected scope and never `--scope all`
 - Returns exit code 1 if the tool is not found in any scope
 
+An unknown name keeps the existing `Tool '<name>' not found.` wording and prints
+no provider-view section, so a skill that exists but was never distributed is
+never confused with a name the repository does not have.
+
+```text
+$ oat tools info probe-skill --scope project
+probe-skill
+  Type:        skill
+  Version:     1.4.2
+  Pack:        custom
+  Scope:       project
+  Status:      not-bundled
+  Provider views (project):
+    claude:  missing-additive  .claude/skills/probe-skill
+      Canonical skill has never been projected to this view: no manifest entry and nothing at the expected path.
+    cursor:  inactive
+    Repair: oat sync --scope project
+```
+
+The section is additive in `--json` output as `providerViews`, an array of one
+entry per concrete scope where the canonical skill exists. The command reads the
+manifest, the sync config, and the filesystem; it never writes, and it never
+runs a sync. If the sync config or the manifest cannot be read, that scope's
+section reports `unavailable` with a redacted reason and the tool detail and exit
+code are unchanged; a failure reading one provider's view degrades only that row,
+to `unverified` with the same redacted reason. An absent sync config is not a
+failure: it resolves to the defaults and the scope is diagnosed normally. See
+[Manifest and Drift](../provider-sync/manifest-and-drift.md#resolution-time-skill-view-classes)
+for the view classes.
+
 ### `oat tools has <pack>`
 
 Purpose:

package/assets/docs/contributing/skills.md

@@ -179,20 +179,65 @@ direct managed-role intent still retains the canonical agent.
 
 - `name`
 - `description`
-- `version`
+- `metadata.version` (top-level `version` is the deprecated alias)
 - `disable-model-invocation`
 - `user-invocable`
 - `allowed-tools`
 - `oat_gateable`
 
-### The `version` field is gated
+### How a skill's version is resolved
+
+The Agent Skills specification carries a skill's version under `metadata`, so
+that is where a new skill declares it:
+
+```yaml
+metadata:
+  version: 1.0.0
+```
+
+OAT resolves a version from `metadata.version` first and from the top-level
+`version` field second, and it resolves it the same way everywhere it reads
+one: the installed-versus-bundled comparison behind `oat tools list`,
+`oat tools update`, and `oat doctor`; skill validation; and canonical role
+resolution. `resolveSkillVersion` in
+`packages/cli/src/commands/shared/frontmatter.ts` owns that order, so the
+runtime helper and the validators cannot disagree.
+
+The top-level `version` field remains supported as a deprecated alias. Every
+bundled skill now declares `metadata.version` and carries no top-level
+`version`, so `pnpm oat:validate-skills` reports no alias warnings on the
+bundled tree. The alias is retained for third-party skills installed from
+packs, which may still carry it; it retires on the schedule recorded in
+`DR-260908-bundled-skills-declare` — the warning becomes an error in the first
+release after 0.2.65 that changes the validator, and the resolver's top-level
+read is removed one release after that error has produced no findings on the
+bundled tree.
+
+A skill that carries both fields with different values is a conflict. The
+resolver reports the `metadata.version` value together with the conflict, and
+the callers that must not guess act on it: validation reports an error rather
+than silently picking one, and canonical role resolution treats the identity as
+invalid. The runtime version readers still return the `metadata.version` value,
+so an installed-versus-bundled comparison keeps working while the conflict is
+being fixed. Carrying both with the _same_ value resolves without a conflict and
+without an alias warning, because `metadata.version` wins. A bundled skill must
+still carry `metadata.version` alone: the corpus sweep in
+`packages/cli/src/validation/skills.test.ts` fails on any column-0 `version:`
+line under `.agents/skills`, which is the only check that catches the
+same-value case.
+
+### The version is gated
 
 Changing any canonical skill's `SKILL.md` requires bumping its frontmatter
-`version` in the same PR — one bump per changed skill in the final PR diff,
-even if the skill was edited multiple times on the branch. The rule is
-enforced by `pnpm run check:skill-bumps`, which runs locally (root `AGENTS.md`
-Definition of Done) and in CI; a changed skill whose version matches
-`origin/main` fails the gate.
+version in the same PR — one bump per changed skill in the final PR diff,
+even if the skill was edited multiple times on the branch. The gate reads the
+resolved version, so it enforces the bump whether the skill declares
+`metadata.version` or the top-level alias. The rule is enforced by
+`pnpm run check:skill-bumps`, which runs locally (root `AGENTS.md` Definition
+of Done) and in CI; a changed skill whose version matches `origin/main` fails
+the gate. The deprecation warning above is deliberately not part of that gate:
+`check:skill-bumps` fails on any finding it receives, so an alias warning
+routed through it would fail every changed skill that still carried one.
 
 ## Practical Authoring Flow
 

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

@@ -84,6 +84,111 @@ An exact alias is `in_sync`; an absent alias is `missing`; and a broken,
 replaced, foreign, or otherwise unverifiable alias is `drifted`. Provider list
 and inspect output summarize collection ownership separately from copy mode.
 
+### Resolution-time skill view classes
+
+Drift states answer "does the tracked view still match?", which presupposes a
+manifest entry. A canonical skill that was never synced has no entry at all, so
+`oat tools info <name>` adds a second, additive classification beside the
+unchanged drift state. Provider and path identity for an untracked projection
+come from the active provider set and the adapter's scope mappings, not from
+the manifest.
+
+- `missing-additive` — active, supported, no manifest entry, nothing at the expected path: the only true projection gap
+- `removed` — a manifest entry exists but the provider file is gone
+- `modified` — a manifest entry exists and the view no longer agrees with what the last sync recorded, or its version has fallen behind canonical. A `copy` view also reaches this class through the known limitation below, where the difference may be nothing but the generated banner
+- `in-sync` — a symlinked, collection-aliased, or natively read view _is_ the canonical file; a `copy` view matches the content recorded at its last sync
+- `untracked` — something exists at the expected path that no manifest entry tracks; stray detection skips provider entries whose name matches a canonical entry, so `oat status` does not report it as a stray and reports the untracked projection as `missing` instead
+- `unverified` — the view's state is unknown: either a manifest entry arrived with no drift observation, or reading that one view failed and the row carries the redacted reason
+- `inactive`, `unsupported`, `excluded` — no projection is expected in this scope, so none of them is reported as missing
+
+`unsupported` and `excluded` are defensive: no shipped adapter or config
+produces them today. Every shipped adapter maps skills in both scopes and the
+command passes no canonical-path filter. The branches exist so a future adapter
+or filter cannot be silently reported as a projection gap. `unverified` is
+reachable: an unreadable provider path makes drift detection throw, and that one
+view degrades to `unverified` with its reason.
+
+A row for `inactive`, `unsupported`, or `excluded` prints neither a projection
+qualifier nor a path, because no view is projected for it: naming an expected
+path and a sync strategy for a file that is never produced described work that
+is never going to happen.
+
+Only `missing-additive`, `removed`, and `modified` carry a repair, and it is
+always one concrete `oat sync --scope project` or `oat sync --scope user` for
+the scope where the gap was observed. Versions are compared only for `copy`
+views: a symlinked, collection-aliased, or natively read view is the canonical
+file, so it has no second version.
+
+If reading the sync config or the manifest fails — an invalid, unreadable, or
+otherwise non-loadable `.oat/sync/config.json` or `.oat/sync/manifest.json`, for
+instance — the section for that scope reports `unavailable` with the reason, and
+the rest of the command is unaffected. A failure while reading one provider's
+view, such as drift detection throwing on an unreadable provider path, is
+narrower: only that row degrades, to `unverified` with the same redacted reason,
+and the other providers keep their real rows. The
+diagnostic is additive evidence, so it never changes the exit code or removes
+the tool detail of a user whose sync state is already broken. A broken sync
+config is one of the likeliest reasons a provider view is missing, which is
+exactly what this command is run to explain, so it is reported rather than
+dropped: printing no section at all would read as "no providers configured".
+An absent `.oat/sync/config.json` is a different case and not a failure — it
+resolves to the defaults, and the scope is diagnosed normally. Reasons are
+redacted; the scope root becomes `<project>` or `~` (only at a path boundary, so
+a sibling directory that merely shares the prefix is left alone), and any
+absolute path outside it is replaced entirely with `<path>`, quoted or not and
+whatever punctuation precedes it. A manifest `providerPath` that escapes its own
+scope is redacted the same way rather than rendered in the row, and no version
+is read from it: its `SKILL.md` is a file outside the tree the command was asked
+about.
+
+A drift state and a view class can legitimately disagree. Drift compares a copy
+against the hash recorded at its last sync, so a copy that was never re-synced
+after a canonical edit still matches its own manifest entry and reads as
+`in_sync`. When the two versions differ, the view class is `modified` and the
+drift state is reported unchanged beside it.
+
+The manifest is keyed by `(canonicalPath, provider)` and never by path, so a
+manifest entry can track a view somewhere other than the adapter's expected
+projection path — reachable after a `providerDir` change or from a manifest
+written under an older layout. Drift resolves the entry's own `providerPath`, so
+in that case the row names the tracked path rather than the expected one, and
+its `--json` record carries the expected path separately as
+`expectedProviderPath`. The detail says which path the state describes and
+whether anything exists at the expected path. A drift verdict computed for one
+path is never attached to a row labelled with another: doing so reported `removed`
+with "the provider file is gone from disk" against a healthy file that was
+sitting at the expected path all along.
+
+Both sides resolve their version through the same shared reader, so
+`metadata.version` takes precedence over the deprecated top-level `version`
+alias for a projected view exactly as it does for the canonical source; the only
+extra step for a view is stripping the generated banner. When a projected
+`SKILL.md` contradicts itself — a top-level `version` and a differing
+`metadata.version` — or declares a version the reader cannot use at all, the
+comparison is withheld rather than decided: no version is reported for that
+view, and the class is left to the drift state alone. That is deliberately
+conservative and has a cost, since a copy in that state could be genuinely
+stale and would not be reported as such. The view's detail names the two
+declared values and says the comparison was skipped, so the ambiguity is
+visible rather than silently resolved. When the resolver's answer happens to
+agree with canonical, nothing is withheld and the detail says so instead.
+
+### Known limitation: copy-strategy skill views
+
+A `copy` skill view is reported `modified` immediately after a successful sync,
+and stays that way. The engine writes an OAT-managed banner into the copied
+`SKILL.md` and an `.oat-generated` sentinel beside it, and neither is accounted
+for in the manifest hash, so `oat status` reports `drifted:modified` and every
+later `oat sync --dry-run` plans another `update_copy`. Because no sync clears
+that state, `oat tools info` prints no repair line when a `modified` copy's
+version still matches canonical.
+
+That suppression is a conservative heuristic rather than a proof: equal versions
+do not establish equal bodies, so an edit to the canonical source or to the copy
+that kept the version reaches the same branch, and a sync _would_ repair that
+one. The class detail says so and names the concrete scope command to run if you
+know either side was edited. Tracked as `BL-260908-make-copy-strategy-skill`.
+
 ## Stray adoption
 
 `oat init` and `oat status` can offer adoption of unmanaged provider entries into canonical `.agents`.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.63",
-  "docs-config": "0.2.63",
-  "docs-theme": "0.2.63",
-  "docs-transforms": "0.2.63"
+  "cli": "0.2.65",
+  "docs-config": "0.2.65",
+  "docs-theme": "0.2.65",
+  "docs-transforms": "0.2.65"
 }

package/assets/skills/analyze/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: analyze
-version: 0.2.0
 description: Multi-angle analysis of existing artifacts, codebases, documents, or systems. Examines what you have from six analysis angles and produces structured findings with prioritized recommendations.
 argument-hint: 'target [--context path]'
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, WebSearch, WebFetch, AskUserQuestion, Agent, mcp__*
+metadata:
+  version: 0.2.1
 ---
 
 # /analyze

package/assets/skills/authoring-docs/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: authoring-docs
-version: 1.0.0
 description: Use when creating, restructuring, migrating, auditing, or reviewing technical documentation for software projects. Provides evidence-first, provider-portable Markdown authoring standards.
 argument-hint: '[docs task or target path]'
 disable-model-invocation: false
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
+metadata:
+  version: 1.0.1
 ---
 
 # Authoring Docs

package/assets/skills/compare/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: compare
-version: 0.1.1
 description: Domain-aware comparative analysis with clear recommendations. Compares options across auto-detected or user-specified dimensions and produces a qualitative assessment with a clear winner.
 argument-hint: 'item1 item2 [item3...] [--save] [--context path] [--dimensions "dim1, dim2, ..."]'
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, WebSearch, WebFetch, AskUserQuestion, Agent, mcp__*
+metadata:
+  version: 0.1.2
 ---
 
 # /compare

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

@@ -1,11 +1,12 @@
 ---
 name: create-agnostic-skill
-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
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
+metadata:
+  version: 1.4.3
 ---
 
 # Create Skill
@@ -98,12 +99,13 @@ For detailed guidance, see `references/skill-template.md`.
 ```markdown
 ---
 name: skill-name
-version: 1.0.0
 description: Use when [trigger condition]. [What it does for disambiguation].
 argument-hint: '[arg1] [--flag]'
 disable-model-invocation: true
 allowed-tools: Read, Write, Glob, Grep
 user-invocable: true
+metadata:
+  version: 1.0.0
 ---
 
 # Skill Title
@@ -172,9 +174,10 @@ Natural language request that triggers this skill
 - `argument-hint`, `allowed-tools`, `user-invocable`, `context`, `hooks` are Claude Code specific
 - Other agents ignore unknown frontmatter fields, so it's safe to include Claude-specific fields everywhere
 - `name`: max 64 chars for cross-provider portability (Codex allows 100, but 64 is the spec limit)
-- `version`: include valid semver and start new skills at `1.0.0`
+- `metadata.version`: include valid semver and start new skills at `1.0.0`. The Agent Skills specification puts the version under `metadata`, and OAT resolves `metadata.version` first and the top-level `version` second — `resolveSkillVersion` in `packages/cli/src/commands/shared/frontmatter.ts` owns that order, backstopped by `packages/cli/src/commands/shared/frontmatter.test.ts`
+- `version` (top-level): the deprecated alias, still read when `metadata.version` is absent. Do not set both to different values: OAT reports the conflict, skill validation fails on it, and canonical role identity rejects it
 - `description`: **single line, ≤ 500 chars** (Codex enforces single-line ≤ 500 chars; spec allows 1024)
-- Bump `version` on future edits: patch for fixes/clarifications, minor for backward-compatible behavior additions, major for breaking workflow/interface changes
+- Bump `metadata.version` on future edits: patch for fixes/clarifications, minor for backward-compatible behavior additions, major for breaking workflow/interface changes
 
 **Writing the `description` field:**
 
@@ -200,7 +203,7 @@ Create the skill at `.agents/skills/{skill-name}/SKILL.md`
 **Key requirements:**
 
 - Skill name matches directory name
-- New skills include `version: 1.0.0` in frontmatter
+- New skills include `metadata.version: 1.0.0` in frontmatter
 - Workflow steps use "Step 1, 2, 3..." naming
 - Include both "Basic Usage" and "Conversational" example styles
 - Use imperative form for instructions
@@ -238,7 +241,7 @@ Verify:
 
 - File created at `.agents/skills/{skill-name}/SKILL.md`
 - Frontmatter syntax is valid
-- Frontmatter includes valid semver `version:` (new skills start at `1.0.0`)
+- Frontmatter includes valid semver `metadata.version:` (new skills start at `1.0.0`)
 - Skill appears in `AGENTS.md`
 - Examples include both invocation styles
 - If the skill name starts with `oat-`, run `pnpm oat:validate-skills` and fix any findings
@@ -264,7 +267,7 @@ Provide:
 
 - **Context window is a public good**—keep skills lean, challenge every paragraph
 - Description is the trigger—include "when to use" in frontmatter, not just body
-- Bump `version` for edits: patch = fixes/clarifications, minor = backward-compatible additions, major = breaking changes
+- Bump `metadata.version` for edits: patch = fixes/clarifications, minor = backward-compatible additions, major = breaking changes
 - Keep SKILL.md **under 500 lines / ~5,000 tokens** (spec constraint)
 - Use clear, task-based headings
 - Include working examples for both invocation styles

package/assets/skills/create-agnostic-skill/references/skill-template.md

@@ -28,9 +28,6 @@ Adjust based on complexity—not all sections are required:
 name: skill-name
 # Required: kebab-case, max 64 chars, must match directory name
 
-version: 1.0.0
-# Required: semver. Start new skills at 1.0.0.
-
 description: Use when [trigger condition]. [What it does as disambiguation keywords].
 # Required: Single line, ≤ 500 chars. Lead with "when to use" — this is the routing trigger.
 # Agents load ONLY name+description at startup to decide relevance.
@@ -38,9 +35,13 @@ description: Use when [trigger condition]. [What it does as disambiguation keywo
 # === Spec-optional fields (recognized by some providers) ===
 # license: Apache-2.0
 # compatibility: Requires Node.js 18+
-# metadata:
-#   author: my-org
-#   version: "1.0"
+
+metadata:
+  version: 1.0.0
+  # Required: semver. Start new skills at 1.0.0. The spec carries the version
+  # under `metadata`; a top-level `version:` is a deprecated alias that is read
+  # only when `metadata.version` is absent.
+  # author: my-org
 
 # === Claude Code / Cursor extension fields (ignored by Codex, safe to include) ===
 argument-hint: '[required-arg] [--optional-flag]'
@@ -187,9 +188,10 @@ Successful completion means:
 
 ## Versioning Guidance
 
-- Include `version:` in frontmatter for every skill and use semver (`MAJOR.MINOR.PATCH`).
+- Include `metadata.version` in frontmatter for every skill and use semver (`MAJOR.MINOR.PATCH`).
 - Start new skills at `1.0.0`.
 - Bump patch for fixes/clarifications, minor for backward-compatible behavior additions, major for breaking workflow/interface changes.
+- A top-level `version:` is the deprecated alias for the same value: it is read only when `metadata.version` is absent, and a skill that carries both with different values is reported as a conflict that validation rejects. `resolveSkillVersion` in `packages/cli/src/commands/shared/frontmatter.ts` owns that order.
 
 ## Cross-Provider Portability Notes
 

package/assets/skills/deep-research/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: deep-research
-version: 0.2.0
 description: Comprehensive research orchestrator that classifies topics, dispatches parallel research-angle workers, and produces structured artifacts using domain-specific schemas.
 argument-hint: 'topic [--depth surface|standard|exhaustive] [--focus angle] [--context path] [output-path]'
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, WebSearch, WebFetch, AskUserQuestion, Agent, mcp__*
+metadata:
+  version: 0.2.1
 ---
 
 # /deep-research

package/assets/skills/explainer-kit/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: explainer-kit
-version: 2.1.0
 description: Use when building destination-neutral visual explainer artifacts from explicit, versioned inputs.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent, mcp__*
+metadata:
+  version: 2.1.1
 ---
 
 # Explainer Kit

package/assets/skills/oat-agent-instructions-analyze/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: oat-agent-instructions-analyze
-version: 1.12.0
 description: Run when you need to evaluate agent instruction file coverage, quality, and drift. Produces a severity-rated analysis artifact. Run before oat-agent-instructions-apply to identify what needs improvement.
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
+metadata:
+  version: 1.12.1
 ---
 
 # Agent Instructions Analysis

package/assets/skills/oat-agent-instructions-apply/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: oat-agent-instructions-apply
-version: 1.7.0
 description: Run when you have an agent instructions analysis artifact and want to generate or update instruction files. Creates a branch, generates files from templates, and optionally opens a PR.
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
+metadata:
+  version: 1.7.1
 ---
 
 # Agent Instructions Apply

package/assets/skills/oat-brainstorm/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: oat-brainstorm
-version: 1.3.6
 description: Use when the user explicitly invokes the `brainstorm` verb, including `/oat-brainstorm`, "let's brainstorm", "brainstorm this", "can we brainstorm X", or "help me brainstorm X". For ambiguous exploratory phrasing ("I've been thinking", "what if", "help me think through"), do NOT auto-enter; respond conversationally and offer mode only after ≥2 sustained exploratory turns. Do NOT use for review, debug, PR, status, implementation, or active-workflow questions.
 disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+metadata:
+  version: 1.3.7
 ---
 
 # Brainstorm

package/assets/skills/oat-cursor-cloud-projects/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: oat-cursor-cloud-projects
-version: 1.1.1
 description: Use when OAT work is mentioned in a Cursor Cloud environment. Orients agents to cloud detection, repo-rooted project homes, user-first assets, CLI availability, and Cursor dispatch context without owning lifecycle execution.
 disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep
+metadata:
+  version: 1.1.2
 ---
 
 # OAT in Cursor Cloud

package/assets/skills/oat-dispatch-subagents/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: oat-dispatch-subagents
-version: 1.2.6
 description: Use when an OAT skill or workflow needs provider-neutral selection, launch, recovery, or evidence for bounded subagent work without project lifecycle policy.
 disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read
+metadata:
+  version: 1.2.7
 ---
 
 # Dispatching OAT Subagents

package/assets/skills/oat-docs/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: oat-docs
-version: 1.0.2
 description: Use when a user asks questions about OAT workflows, CLI commands, skill authoring, configuration, or project lifecycle. Answers questions by reading locally-bundled OAT documentation.
 argument-hint: '[question]'
 disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, AskUserQuestion
+metadata:
+  version: 1.0.3
 ---
 
 # OAT Docs

package/assets/skills/oat-docs-analyze/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: oat-docs-analyze
-version: 1.5.0
 description: Run when you need to evaluate documentation structure, navigation, and coverage against the OAT docs app contract. Produces a severity-rated analysis artifact for oat-docs-apply.
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
+metadata:
+  version: 1.5.1
 ---
 
 # Docs Analysis

package/assets/skills/oat-docs-apply/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: oat-docs-apply
-version: 1.3.0
 description: Run when you have a docs analysis artifact and want to generate or update documentation structure and content. Creates a branch, applies approved changes, and optionally opens a PR.
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
+metadata:
+  version: 1.3.1
 ---
 
 # Docs Apply

package/assets/skills/oat-docs-authoring/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: oat-docs-authoring
-version: 1.0.0
 description: Use when authoring or restructuring targeted content inside an existing OAT/Fumadocs docs app. Preserves OAT docs navigation, generated indexes, and validation boundaries.
 argument-hint: '[docs task or target path]'
 disable-model-invocation: false
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
+metadata:
+  version: 1.0.1
 ---
 
 # OAT Docs Authoring

package/assets/skills/oat-docs-bootstrap/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: oat-docs-bootstrap
-version: 1.2.0
 description: Use when bootstrapping a new OAT docs app in a repo. Guides the user through preflight detection, richer input gathering than the raw CLI, `oat docs init` invocation with gated post-patches for open CLI gaps, build verification, post-scaffold config inspection, and an educational walkthrough. Supports Fumadocs (full path) and MkDocs (lean path with defined minimum contract).
 argument-hint: '<optional-target-dir>'
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+metadata:
+  version: 1.2.1
 ---
 
 # Docs Bootstrap

package/assets/skills/oat-doctor/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: oat-doctor
-version: 1.2.1
 description: Use when you need to diagnose your OAT setup, check for outdated skills, identify misconfigurations, or get a summary of installed tools and config. Runs health checks and recommends corrective actions.
 argument-hint: '[--summary]'
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
+metadata:
+  version: 1.2.2
 ---
 
 # OAT Doctor