@open-agent-toolkit/cli 0.2.62 → 0.2.64

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.62"
+  "oatVersion": "0.2.64"
 }

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -120,6 +120,7 @@ Use `oat config` for repo runtime config inspection and supported key mutation.
 
 - `oat config get <key>` - read one resolved config value
 - `oat config set <key> <value>` - update a supported shared or repo-local key
+- `oat config unset <key>` - remove a supported key from one surface, with the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. Pruning removes any parent object the removal empties, and the resolved value falls back to the next surface or the built-in default. A key the surface does not hold reports an already-unset outcome and exits 0; `--json` adds a `removed` boolean that distinguishes that no-op from a real removal. Five classes are refused with exit 1: unknown keys (including the uncatalogued `documentation.index`), lifecycle state (`activeProject`, `lastPausedProject`, cleared with `oat config set <key> ''`), pack intent (`tools.*`, removed with `oat tools remove --pack <pack> --scope project`), the aggregate read views `workflow.dispatchCeiling` and `workflow.dispatchCeiling.providers`, and environment-shadowed keys with nothing stored on the target surface. See [CLI Reference](../reference/cli-reference.md#oat-config-surface-flags) for the full contract
 - `oat config list` - show the resolved command-surface values with source information
 - `oat config dump --json` - emit the full merged config payload with per-key source attribution, suitable for automation and debugging
 - `oat config describe` - list supported config surfaces and keys across shared repo, repo-local, user, and sync/provider config

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

@@ -18,13 +18,13 @@ For the deep file-by-file reference, see:
 
 ## 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 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`  |
+| 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/unset/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/unset/list/describe`, `oat gate` |
+| User config               | `~/.oat/config.json`      | User-level state such as global `activeIdea` fallback and personal `workflow.*` defaults                                                              | `oat config get/set/unset/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:
 
@@ -51,6 +51,7 @@ What each command is for:
 - `oat config list` shows the currently resolved command-surface values for shared and repo-local keys.
 - `oat config get <key>` reads one supported key value.
 - `oat config set <key> <value>` updates supported shared or repo-local keys.
+- `oat config unset <key>` removes a supported key from one surface, using the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. The resolved value then falls back to the next surface down, or to the built-in default. A key the surface does not hold exits 0 as already-unset (`--json` adds a `removed` boolean to tell the two apart). Unknown keys, lifecycle state, `tools.*` pack intent, the `workflow.dispatchCeiling` aggregate read views, and environment-shadowed keys with nothing stored are refused with exit 1 — see [CLI Reference](../reference/cli-reference.md#oat-config-surface-flags).
 - `oat config describe` shows the supported config catalog across shared repo, repo-local, user, and sync/provider surfaces.
 - `oat config describe <key>` shows file, scope, default, mutability, owning command, and description for one key.
 
@@ -91,6 +92,7 @@ Common keys in `.oat/config.json`:
 - `git.defaultBranch` — base branch fallback for PR workflows
 - `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership
 - `documentation.excludes` — a JSON array of globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. `oat config set` takes the list as one comma-separated value (`"a/**,b.md"`) and stores it as an array; repeated `--exclude` flags extend it, and an empty value clears the key
+- `documentation.instructionPointerExcludes` — a JSON array of repository-relative directories that `oat instructions sync` and `oat instructions validate` must not treat as pointer sites, additive to the documentation content root they already skip by default (see [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees)). `oat config set` takes the list as one comma-separated value (`"vendor/generated,apps/oat-docs/docs"`) and stores it as an array of repository-relative POSIX paths, trimmed and de-duplicated; an empty value clears the key, and `oat config unset documentation.instructionPointerExcludes` removes it. An entry that could never exclude anything — an absolute path, or one escaping the repository with `..` — is rejected with exit code `1` rather than stored. A structurally malformed value already on disk (a non-array, or an empty or non-string entry) is rejected with exit code `2` and a repair message, and `oat config set` can still replace it. Entries that are well formed but cannot exclude anything — among them absolute paths, paths escaping the repository, paths that match no directory (matching is case-sensitive), and the unexcludable `.oat/repo` carve-in root — never abort the command; they are reported as warnings and are not counted as protection. Warnings go to stderr in human mode and to the `exclusionWarnings` field under `--json`
 - `documentation.requireForProjectCompletion` — whether docs sync is a completion gate
 - `archive.s3Uri` — base S3 archive prefix
 - `archive.s3SyncOnComplete` — upload archived projects to S3 during completion
@@ -768,7 +770,7 @@ Workflow preferences resolve through three config surfaces, with `local > shared
 
 ### Setting preferences
 
-`oat config set` supports mutually exclusive surface flags for workflow keys:
+`oat config set` and `oat config unset` support the same mutually exclusive surface flags for workflow keys:
 
 ```bash
 # User-level: applies to all repos on this machine

package/assets/docs/cli-utilities/project-log.md

@@ -71,6 +71,22 @@ oat project log append \
 Structural entries require `--structural`, `--producer`, `--ref`, and `--body`.
 Do not combine structural flags with judgment flags.
 
+### Idempotent append and commit
+
+Two optional flags let an interrupted append be replayed safely:
+
+- `--idempotency-key <key>` — skip the append when an existing entry body
+  already carries `key`, reporting `already-appended` instead of writing a
+  duplicate. The key must appear in `--body`, since that is how a replay
+  recognizes the entry it already wrote.
+- `--commit` — stage and commit the log after appending, retrying a bounded
+  three attempts when the failure is a transient `.git/index.lock`.
+
+Together they are the recovery entry point for a gate whose project-log
+finalization could not commit. See
+[Workflow Gates](./workflow-gates.md#project-log-finalization) for the receipt
+and the exact recovery command.
+
 The helper produces these heading grammars in UTC:
 
 ```text

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/cli-utilities/workflow-gates.md

@@ -375,14 +375,14 @@ once an artifact exists, its `generatedAt` (the artifact's seconds-precision
 `oat_generated_at`), so a caller can correlate the result to the exact artifact
 and disambiguate re-gate rounds:
 
-| `status`                       | Exit | Meaning                                                      |
-| ------------------------------ | ---- | ------------------------------------------------------------ |
-| `ok`                           | 0    | Review completed; gate passed at the threshold.              |
-| `blocked`                      | 1    | Review completed; findings at/above the threshold.           |
-| `review_failed`                | ≠0   | The provider target exited non-zero; no verdict.             |
-| `artifact_missing`             | 1    | The child exited cleanly without producing an artifact.      |
-| `artifact_validation_failed`   | 1    | Artifact format or configured invocation fields are invalid. |
-| `targeting_correlation_failed` | 1    | Identity did not correlate; do not run review-receive.       |
+| `status`                       | Exit | Meaning                                                         |
+| ------------------------------ | ---- | --------------------------------------------------------------- |
+| `ok`                           | 0    | Review completed; gate passed at the threshold.                 |
+| `blocked`                      | 1    | Review completed; findings at/above the threshold.              |
+| `review_failed`                | ≠0   | No validated verdict: the target or post-selection work failed. |
+| `artifact_missing`             | 1    | The child exited cleanly without producing an artifact.         |
+| `artifact_validation_failed`   | 1    | Artifact format or configured invocation fields are invalid.    |
+| `targeting_correlation_failed` | 1    | Identity did not correlate; do not run review-receive.          |
 
 Only `ok` and `blocked` are positive, receive-eligible review outcomes: both
 follow successful identity corroboration and carry a non-null `handoff`.
@@ -400,6 +400,37 @@ bookkeeping finish inline or through a synchronously awaited child, then start
 a new gate run. Do not use review-fix retries or review-receive for the failed
 run.
 
+Post-selection recovery covers work that fails _after_ the reviewer already
+committed a run-correlated artifact: corroboration, the threshold, handoff
+construction, or result writing. Recovery means re-validation, never re-review.
+The gate re-runs the same eligibility pipeline the normal path uses (project
+containment, `oat_generated_at` validity, verdict parsing, gate-invocation
+corroboration, the `oat_review_invocation: gate` marker, and the threshold)
+against the immutable content/signature snapshot selected at correlation time.
+It re-validates that snapshot rather than re-parsing whatever the path now
+holds, and it never dispatches a second reviewer. The artifact must still be
+present and unchanged for re-validation to succeed: a deleted or rewritten
+artifact fails re-validation and the run stays failed.
+When that re-validation succeeds the gate returns the ordinary `ok` or
+`blocked` envelope with an additive `postSelectionRecovery: true`. Like
+`lateCompletion`, that is recovery telemetry rather than a new status: route
+review-receive from `status`, `receiveEligible`, and `handoff` as usual.
+
+When no artifact was selected, or the selected snapshot does not re-validate,
+the run stays `review_failed` with `outcome:
+unexpected_post_selection_failure`. That envelope names the failing sub-step in
+`postSelection.step` (`target-dispatch`, `artifact-scan`,
+`artifact-correlation`, `artifact-validation`, `verdict-parse`,
+`invocation-corroboration`, or `verdict-disposition`) and a routable
+`postSelection.code`: the thrown error's own `code` or constructor name, the
+eligibility cause when a committed artifact failed re-validation, or
+`recovery_revalidation_failed` when the re-validation attempt itself threw. That
+last case also emits a `gate-recovery-failed` diagnostic, so a persistent
+non-recovery stays distinguishable from the transient failure that triggered it.
+Replacement bytes at the artifact path, a missing artifact, a non-gate
+invocation marker, and an artifact targeting another project never recover. Route deterministically on those
+fields instead of re-dispatching the reviewer.
+
 `ok` and `blocked` also include `receiveEligible: true`, `outcome`,
 `artifactPath`, `counts`, `scope`, `handoff`, `gateInvocation`, and
 `corroboration`. Invoke review-receive only when all three conditions hold:
@@ -445,6 +476,81 @@ oat --json gate review \
 Read the resulting envelope and exit code; that is the whole completion
 contract.
 
+### Project log finalization
+
+After the envelope is written, the gate appends one structural entry to the
+project's `project-log.md` and commits it, so the run does not leave a dirty
+worktree for whatever executes next. The entry body ends with
+`run=<runId>` — the same run id the envelope carries. That token is the entry's
+stable identity: a retry or a later recovery recognizes the entry it already
+wrote instead of appending a second one.
+
+Staging and committing the log retries **three attempts** separated by two
+waits (250 ms, then 500 ms) when, and only when, git itself reports index-lock
+contention: `Unable to create '…/index.lock': File exists`, or git's `Another
+git process seems to be running in this repository` advice in output that also
+names an index lock. Every other failure — a hook,
+signing, identity, or pathspec error — is reported immediately rather than
+retried, including one whose output merely mentions `index.lock`. The gate never
+deletes, moves, or forces a lock it did not take. A lock whose mtime is
+unchanged across the whole retry window is reported as `persistent-index-lock`;
+one that moves is `transient-index-lock`. If a competing writer commits the same
+entry while the gate retries, the gate reports the work as already committed
+instead of a failure — but only when the committed log still carries this run's
+entry.
+
+When the retries are exhausted the append has landed but the commit has not, so
+the gate writes a durable receipt to
+`<project>/gate-receipts/<runId>.json` and emits a
+`gate-project-log-partial-finalization` diagnostic naming the receipt and
+printing its recovery command verbatim. The gate result is unchanged: a passing
+review still exits `ok`.
+
+The receipt must not dirty the worktree, so this repository ignores
+`**/gate-receipts/` repository-wide rather than under `.oat/projects` alone:
+`projects.root` is settable, and the receipt follows the resolved project. A
+repository whose ignore rules do not cover the receipt still gets the receipt —
+losing the finalization would be worse than a tracked file — plus a
+`gate-project-log-receipt-warning` diagnostic naming the path, so the gap
+surfaces before the next repository-wide `git add`.
+
+The receipt completes the finalization from a later process, with no reviewer
+and no second gate run:
+
+```bash
+oat project log append --project <projectPath> --structural \
+  --producer 'oat gate review' --ref <ref> --body <body> \
+  --idempotency-key <runId> --commit
+```
+
+Before appending anything, that command validates the receipt against the live
+tree: the project path must resolve to the same project, `worktreeRoot` must
+match `git rev-parse --show-toplevel`, and the review artifact must still exist
+with its recorded sha256 signature. A receipt that names no artifact — the gate
+correlated none, so `artifactPath` and `artifactSignature` are both `null` — is
+bound by run id, project, worktree, and the entry fields alone; a receipt that
+names an artifact _without_ a signature is malformed and refused. The replayed
+entry must also be the entry
+the receipt describes — `--producer`, `--ref`, and `--body` are compared against
+the receipt, and the receipt's own run id must be the `--idempotency-key` that
+names its file — so a receipt can never be consumed while some other entry is
+written. Any mismatch exits non-zero with a
+`gate-project-log-receipt-mismatch` diagnostic and touches nothing. On a match
+it appends (or reports `already-appended` when the entry is already there),
+commits with the same bounded retry, and deletes the receipt. Running it twice
+is safe: the second run appends nothing and creates no commit.
+
+At the start of a run, a receipt still sitting under the project produces a
+`gate-project-log-receipt-pending` diagnostic naming the receipt and its
+recovery command. Its `state` is `stale` only when the _committed_ log
+(`HEAD:project-log.md`) already carries that run id and entry — the append
+landed and was committed, so recovery will observe `already-appended` and clear
+the receipt. Everything else is `pending`, including the ordinary case where
+the entry is in the working tree but no commit succeeded: that is precisely
+what the receipt exists to finish, so it is never reported as leftovers. A
+receipt naming another tree's log, or a committed log that cannot be read back,
+also stays `pending`. The warning is discovery only; the gate still runs.
+
 ## Exec targets
 
 `oat gate cross-provider-exec` chooses from `workflow.gates.execTargets`.
@@ -884,14 +990,16 @@ those artifacts; correct the project/run correlation and start a new gate run.
 
 ### Incident-to-regression mapping
 
-| Observed failure                                         | Regression coverage                                                                                                    |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Headless reviewer could not complete an async delegation | route unit matrix plus canonical checkout-local command, strict receipt, headless inline, and structured-refusal cases |
-| Large final review exceeded the old 15-minute budget     | scope-aware resolver tests plus scaled final-scope fake-runtime case                                                   |
-| Silent child looked idle while transcripts grew          | metadata-probe tests plus timeout-with-advancing-transcript fixture                                                    |
-| Timeout or child failure produced no artifact            | fail-closed `noOutputProduced` fixture                                                                                 |
-| Artifact carried the wrong gate run ID                   | provenance-mismatch fixture                                                                                            |
-| Passing artifact lost receive routing                    | handoff and `receiveEligible` fixture                                                                                  |
+| Observed failure                                                      | Regression coverage                                                                                                    |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Headless reviewer could not complete an async delegation              | route unit matrix plus canonical checkout-local command, strict receipt, headless inline, and structured-refusal cases |
+| Large final review exceeded the old 15-minute budget                  | scope-aware resolver tests plus scaled final-scope fake-runtime case                                                   |
+| Silent child looked idle while transcripts grew                       | metadata-probe tests plus timeout-with-advancing-transcript fixture                                                    |
+| Timeout or child failure produced no artifact                         | fail-closed `noOutputProduced` fixture                                                                                 |
+| Artifact carried the wrong gate run ID                                | provenance-mismatch fixture                                                                                            |
+| Passing artifact lost receive routing                                 | handoff and `receiveEligible` fixture                                                                                  |
+| Passing review reported as a failed gate after a post-selection error | post-selection recovery cases plus snapshot-replacement, non-gate-marker, and foreign-target controls                  |
+| Transient index lock turned a completed review into a failed gate     | index-lock retry cases plus persistent/transient classification, receipt fixture, and fresh-process recovery control   |
 
 ## Current limits
 

package/assets/docs/contributing/skills.md

@@ -179,20 +179,55 @@ 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 still uses it today, so `pnpm oat:validate-skills` reports each
+one as a non-blocking warning; the value is still read, and nothing breaks.
+Migrating the bundled skills is tracked separately.
+
+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 is accepted.
+
+### 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 until the migration lands.
 
 ## Practical Authoring Flow
 

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

@@ -210,6 +210,7 @@ Key behavior:
 - 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`](instruction-sync.md)
 
@@ -227,5 +228,7 @@ Key behavior:
 - 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`](instruction-sync.md)

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

@@ -23,8 +23,115 @@ Instruction sync is currently project-only.
 - It supports nested directories all the way down the tree.
 - It skips provider-irrelevant or local-only roots such as `.git`, `.oat`, `.worktrees`, and `node_modules`.
 - Exception: `.oat/repo/**` is scanned even though the rest of `.oat/` is skipped, so the curated `AGENTS.md` files there (repo root guidance, `pjm/`, `reference/`) get their sibling `CLAUDE.md` shims managed and validated like any other directory. The rest of `.oat/` (`templates/`, `projects/`, `sync/`) stays excluded.
+- It skips the documentation content tree by default, and any path you add to `documentation.instructionPointerExcludes`. See [Documentation trees](#documentation-trees) below.
 - It does not scan user-level provider roots such as `~/.claude` in this release.
 
+## Documentation Trees
+
+A documentation tree holds authored pages, not instructions for agents. A
+`CLAUDE.md` written into one becomes a published page, and a page legitimately
+named `CLAUDE.md` is content that must not be treated as a pointer. Both
+`oat instructions validate` and `oat instructions sync` therefore skip the
+documentation content root, so validate never reports drift that sync refuses
+to fix.
+
+The content root is derived from `documentation.root` in `.oat/config.json`:
+
+- `<documentation.root>/docs` when that path is a directory;
+- otherwise `documentation.root` itself.
+
+This is the same derivation `oat docs generate-index` uses to pick its default
+docs directory, so the excluded tree and the indexed tree agree by
+construction. (`oat docs generate-index --docs-dir` overrides the index side
+only; it does not change what instruction sync excludes.)
+
+**App-level instruction files are still synced.** `documentation.root`
+canonically names the docs _app_ root, and a file like
+`apps/oat-docs/AGENTS.md` is instructions for working on the docs app rather
+than a documentation page. When the app root has a `docs` child, only that
+child is skipped, and the app root keeps receiving its `CLAUDE.md` pointer. Opt
+the app root out explicitly if you do not want it synced.
+
+Add further paths with `documentation.instructionPointerExcludes`, a list of
+repository-relative directories. Set it with
+`oat config set documentation.instructionPointerExcludes "vendor,third_party/docs"`
+(an empty value clears it, and `oat config unset` removes it), or write it
+directly:
+
+```json
+{
+  "documentation": {
+    "root": "apps/oat-docs",
+    "instructionPointerExcludes": ["vendor", "third_party/docs"]
+  }
+}
+```
+
+Each entry excludes that directory and everything beneath it, matching the
+directory path exactly rather than by prefix — excluding `apps/docs` leaves a
+sibling `apps/docs-legacy` scanned. Entries are repository-relative and
+normalized, so `apps/./docs`, `apps//docs`, and `apps/docs/` all name the same
+tree; absolute paths and paths escaping the repository are dropped with a
+warning when they are already stored — and refused outright by
+`oat config set` — and the repository root itself cannot be excluded. A structurally malformed value
+(anything other than an array of non-empty strings) is rejected with exit code
+`2` rather than silently ignored.
+
+The list is additive to the derived content root, and it is applied after the
+`.oat/repo` carve-in, so excluding _another_ tree can never collaterally leave
+`.oat/repo/**` unscanned. `.oat/repo` itself is never excludable — listing it
+is reported as having no effect rather than silently honoured, and its
+`AGENTS.md` keeps its pointer. A deliberate opt-out naming a path _beneath_
+it, such as `.oat/repo/pjm`, is honoured: descendants are reached by ordinary
+traversal, so only the carve-in root is protected from exclusion.
+
+### When an exclusion does nothing
+
+An entry that is well formed but cannot protect anything — it names a
+directory that does not exist, differs in case from the real path on a
+case-insensitive filesystem such as APFS, is absolute, escapes the repository,
+or is the unexcludable `.oat/repo` — does not fail the command. It is reported
+as a warning naming the entry, and it is never counted as protection.
+
+The warning channel depends on the mode: in human mode warnings are written to
+stderr, and under `--json` they are carried in the `exclusionWarnings` payload
+field instead, because `--json` suppresses stderr warnings entirely.
+
+That distinction matters most on a case-insensitive filesystem: a
+`documentation.root` of `Apps/Docsapp` resolves happily while the scan compares
+the real `apps/docsapp`, so the tree would be scanned after all. Trust
+`effectiveExcludedPaths`, not `excludedPaths`, when deciding whether a tree is
+protected — and read `exclusionWarnings` for the reason, since the stderr
+warnings are silent under `--json`.
+
+Because both commands read `.oat/config.json` to resolve exclusions, they
+inherit its validation. Any value that fails a _fail-closed_ field check —
+including keys these commands do not otherwise use, such as
+`documentation.excludes` — makes `oat instructions sync` and
+`oat instructions validate` exit `2` until it is repaired. Not every key is
+fail-closed: a wrong-typed scalar such as `documentation.root` is dropped
+rather than rejected, so it never aborts the command (a dropped `root` simply
+leaves the content root underived, and no default exclusion applies).
+
+Exclusion only stops a directory from being scanned. Nothing is deleted: a
+`CLAUDE.md` that already exists inside an excluded tree is left exactly as it
+is. When any exclusion is configured, `--json` output carries three additional
+fields.
+
+- `excludedPaths` lists the configured exclusions — a statement of intent, not
+  a per-directory skip log, so `.oat` appearing there does not contradict
+  `.oat/repo` still being scanned.
+- `effectiveExcludedPaths` lists the subset that names a real, case-exact
+  directory the scan actually pruned. It is present whenever `excludedPaths`
+  is, including as an empty array when every configured entry turned out to be
+  inert.
+- `exclusionWarnings` lists one message per configured exclusion that will not
+  protect anything — the `--json` counterpart of the stderr warnings above.
+
+Each field is omitted when it would be empty. `exclusionWarnings` is
+independent of the other two: an absolute or repository-escaping entry is
+dropped before `excludedPaths` is built, so it appears only here.
+
 ## Canonical Model
 
 - `AGENTS.md` is canonical.