@open-agent-toolkit/cli 0.3.6 → 0.3.8

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.6"
+  "oatVersion": "0.3.8"
 }

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

@@ -51,7 +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 set <key> <value>` updates supported shared or repo-local keys. Writes to the shared `.oat/config.json` keep the file's existing key order, and a write that would not change any value leaves the file byte-identical.
 - `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, aggregate read views, read-only remote-policy structure, 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. A deprecated key also prints `Deprecated: prefer <successor>`, and `--json` carries the same fact as a `deprecated` object (`supersededBy`, plus `note` and `legacyValues` where they apply).
@@ -125,6 +125,20 @@ and purpose field grants intersect to narrow outbound fields. No configured
 layer bypasses hard approval floors or current caller-owned authority evidence;
 missing, stale, or mismatched evidence fails closed.
 
+The shared `pjm.remote` tree is closed. An unknown key, a non-object where an
+object is expected, or a wrong-typed leaf (for example `authority.default: 5`,
+a string `schemaVersion`, or a number, boolean, array, object, or `null` where a
+string is expected) makes every shared config read fail closed with an
+`Invalid PJM remote policy structure` error. The error names each offending
+field path: unknown keys by path alone, and wrong-typed values by path and
+structure type, never by value. This includes ordinary reads such as
+`oat config get` and `oat config unset` of an unrelated `pjm.remote` child: the
+`oat config` subcommands report the error and exit with code `1`, and `unset`
+leaves the file byte-identical. Repair the named fields by editing
+`.oat/config.json` by hand. A well-typed but unrecognized string is not
+rejected: it keeps its documented coercion to `none` for descriptions and
+`read-only` for authority.
+
 Tool-pack intent example:
 
 ```bash
@@ -387,14 +401,14 @@ preference. For the full model, see
 
 ### Config keys
 
-| Key                                                    | Values                                                | Purpose                                                                                 |
-| ------------------------------------------------------ | ----------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `workflow.dispatchPolicy.mode`                         | `managed`, `inherit`                                  | `managed` lets OAT select exact candidates; `inherit` leaves controls to the host       |
-| `workflow.dispatchPolicy.policy`                       | `economy`, `balanced`, `high`, `frontier`, `uncapped` | Default named maximum or explicit managed uncapped state                                |
-| `workflow.dispatchCeiling.providers.<provider>`        | tier map or legacy bare value                         | Reusable provider candidate column                                                      |
-| `workflow.dispatchCeiling.providers.<provider>.<tier>` | `candidates` cell, route, or legacy bare value        | One named tier in the provider ladder                                                   |
-| `workflow.dispatchCeiling.recommendationVersion`       | string                                                | Version written by `oat config adopt dispatch-matrix` for recommendation drift tracking |
-| `workflow.dispatchCeiling.preset`                      | `balanced`, `maximum`, `cost-conscious`               | Legacy policy setup alias                                                               |
+| Key                                                    | Values                                                | Purpose                                                                              |
+| ------------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `workflow.dispatchPolicy.mode`                         | `managed`, `inherit`                                  | `managed` lets OAT select exact candidates; `inherit` leaves controls to the host    |
+| `workflow.dispatchPolicy.policy`                       | `economy`, `balanced`, `high`, `frontier`, `uncapped` | Default named maximum or explicit managed uncapped state                             |
+| `workflow.dispatchCeiling.providers.<provider>`        | tier map or legacy bare value                         | Reusable provider candidate column                                                   |
+| `workflow.dispatchCeiling.providers.<provider>.<tier>` | `candidates` cell, route, or legacy bare value        | One named tier in the provider ladder                                                |
+| `workflow.dispatchCeiling.recommendationVersion`       | string                                                | Bundle version last written by adoption; does not prove the effective ladder matches |
+| `workflow.dispatchCeiling.preset`                      | `balanced`, `maximum`, `cost-conscious`               | Legacy policy setup alias                                                            |
 
 ### Adopt a complete ladder
 
@@ -406,14 +420,20 @@ oat config adopt dispatch-matrix --local
 oat config adopt dispatch-matrix --user
 ```
 
-Adoption fills missing provider/tier cells and preserves explicit existing
-values. Planning shows the complete bundled recommendation before asking for
-this scope, then rechecks the effective ladder. If explicit cells still leave
-the ladder incomplete, readiness blocks; OAT does not overwrite them.
-`workflow.dispatchCeiling.recommendationVersion` describes only the bundled
-recommendation that was adopted. Dispatch targets, structured notices, and
-runtime disclosure come from the effective ladder after explicit cells have
-been preserved.
+Adoption replaces populated cells from the bundled recommendation in the
+chosen scope, fills missing cells, and keeps extra custom tier cells when
+the bundled provider remains a tier map. A bundled provider-level scalar
+replaces the whole provider, including its custom tiers. It warns about
+replaced and removed cells and reports their paths in human and JSON output. Preview with
+`oat config adopt dispatch-matrix --user --dry-run` before writing user defaults.
+Add `--keep-existing` when you want only missing cells filled; a fill-only run
+with no missing cells leaves the config and version unchanged. If it fills
+missing cells while preserving differences, it leaves the version unchanged. Planning uses
+`--keep-existing` after showing the complete bundle and asking for the owning
+scope. If the resulting effective ladder remains incomplete, readiness blocks.
+The version records the bundle last written by adoption, not whether the
+effective ladder matches it. Dispatch targets, structured notices, and runtime
+disclosure come from the effective ladder.
 
 A recommended Fable target may require model access from the executing
 provider. The adopting organization is responsible for confirming its
@@ -700,7 +720,7 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.dispatchCeiling.preset` — legacy compatibility alias (`balanced`, `maximum`, or `cost-conscious`) for capped managed policy setup.
 - `workflow.dispatchCeiling.providers.<provider>` — dispatch matrix provider column or legacy bare provider target.
 - `workflow.dispatchCeiling.providers.<provider>.<tier>` — one matrix cell for `economy`, `balanced`, `high`, or `frontier`.
-- `workflow.dispatchCeiling.recommendationVersion` — version of the adopted recommended matrix.
+- `workflow.dispatchCeiling.recommendationVersion` — bundle version last written by adoption; not an effective-ladder parity indicator.
 - `workflow.gates.skills` / `workflow.gates.execTargets` — structured per-skill final gate commands and exec-target registry. Use `oat gate set`, `oat gate target set`, `oat gate review`, and `oat gate cross-provider-exec`; do not use `oat config set` for these objects.
 - `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` — validated default gate-review budgets in milliseconds. Both resolve through `local > shared > user`.
 

package/assets/docs/cli-utilities/workflow-gates.md

@@ -236,6 +236,35 @@ model that ran, and the reviewer must not replace them with self-identification.
 The CLI compares the copied values with its gate-owned record before it applies
 the severity threshold.
 
+The gate frontmatter is also the authority for the artifact's dispatch audit
+line. The reviewer's resolver stamp describes the project reviewer policy, so
+gate-originated artifacts label it as the policy view:
+
+```markdown
+**Dispatch audit (policy view):** `Dispatch: scope=p01 action=review role=reviewer ... target=oat-reviewer-gpt-6-sol-high`
+```
+
+The gate reads reviewer stamps (`action=review role=reviewer`) from audit lines
+anywhere in the artifact body except finding sections: `## Findings` with its
+subsections, and any `### Critical`, `### High`, `### Medium`, or `### Low`
+section. Reviewers place these lines in the metadata block before the first
+level-two (`##`) heading and in sections such as `## Dispatch Audit`,
+`## Dispatch Metadata`, `## Review Dispatch Audit`, `## Review Scope`, and
+`## Dispatch Evidence`. An audit line is an optional list marker, an optional
+label ending in `:`, and a `Dispatch:` stamp that is either bare or wrapped in
+one backtick pair, which may be followed only by punctuation or one
+parenthetical such as `(resolver)`. Fenced code blocks, table rows, and prose
+that quotes a stamp are ignored, including a labeled line where other prose
+follows the closing backtick. To cite a stamp as evidence, put it in a fenced
+block, a table, or a finding. A stamp whose label contains
+`policy view` is not checked. Every other audit stamp must agree with the
+frontmatter: its `target` equals `oat_gate_target`, and, when
+`oat_invocation_reasoning_effort` is a concrete effort (not `unknown`,
+`provider-default`, or `not-applicable`), its `effort_axis` equals
+`selected:<effort>`. A disagreeing stamp fails with
+`status: artifact_validation_failed` and cause `gate_dispatch_audit_mismatched`.
+Artifacts without an audit stamp are unaffected.
+
 ### Review producer identity
 
 Dynamic planning workflows can declare their current parent model to a review
@@ -329,6 +358,14 @@ self-report are not interchangeable. The human report is rendered from the
 versioned object, and any parseable `Dispatch:` compatibility line is derived
 from that same report rather than rebuilt from target IDs or model names.
 
+Because the resolver stamp and the gate invocation can name different targets
+and efforts, a gate artifact writes the resolver stamp under the
+`**Dispatch audit (policy view):**` label (see
+[Review gates](#review-gates) above for the agreement rule). An unlabeled stamp that disagrees with the frontmatter fails with
+`gate_dispatch_audit_mismatched`. When an older installed
+`oat-project-review-provide` wrote the unlabeled line, refresh installed skills
+with `oat tools update` and rerun the gate instead of editing findings.
+
 ### Review project resolution and corroboration
 
 `--project <path-or-name>` is a declaration. OAT normalizes the declared path

package/assets/docs/contributing/updating-model-guidance.md

@@ -108,11 +108,11 @@ Follow [Contributing Code](code.md) for the current validation and PR workflow.
 
 ## Adoption Is Separate
 
-The bundled ladder is a default for missing provider/tier cells. `oat config
-adopt dispatch-matrix --shared`, `--local`, or `--user` fills missing cells but
-does not replace populated explicit cells, even when its recommendation version
-changes. A user who wants the new model ordering must edit those cells or
-clear and re-adopt them deliberately. The active project's named ceiling is a
-separate policy in its `state.md`; a model update must not silently change it.
+A bundled ladder update does not mutate adopted user or repository config.
+`oat config adopt dispatch-matrix --shared`, `--local`, or `--user` replaces
+bundled cells in the chosen scope, with a warning and a `--dry-run` preview;
+extra custom cells remain. Add `--keep-existing` to fill only missing cells.
+The active project's named ceiling is a separate policy in its `state.md`;
+a model update must not silently change it.
 See [Dispatch Policy](../workflows/projects/dispatch-ceiling.md#ownership-and-adoption)
 for config precedence and examples.

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

@@ -71,6 +71,12 @@ Key behavior:
   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
+- Invalid canonical rules stop the run before anything is applied. Sync
+  checks every rule first and fails once with a message that names each
+  invalid rule file exactly once, even though several provider transforms
+  read the same rule, so one run surfaces every file to fix. See
+  [Canonical rule frontmatter](providers.md#canonical-rule-frontmatter) for
+  the accepted `alwaysApply: true` alias.
 - 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

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

@@ -89,6 +89,10 @@ oat config adopt dispatch-matrix --local
 oat config adopt dispatch-matrix --user
 ```
 
+These commands replace bundled cells in the chosen scope and warn about
+replacements. Add `--dry-run` to preview or `--keep-existing` to fill only
+missing cells.
+
 Project-config candidates materialize into the tracked, version-controlled
 project `.codex` and `.cursor` views. User-config candidates materialize under
 `~/.codex` and `~/.cursor`. OAT does not auto-ignore project output or create
@@ -182,6 +186,26 @@ current-session catalog probe is still not proof of provider visibility.
 - Codex user-scope sync materializes user-config custom roles under `~/.codex`; project-config and supported-catalogue output remains project-scoped and version controlled
 - Cursor user-scope sync materializes user-config variants under `~/.cursor/agents`; project-config and supported-catalogue output remains project-scoped and version controlled
 
+## Canonical rule frontmatter
+
+Canonical rules in `.agents/rules/*.md` declare `activation` as one of
+`always`, `glob`, `agent-requested`, or `manual`; `globs` is valid only with
+`activation: glob`.
+
+Third-party installers sometimes write Cursor-style rules straight into
+`.agents/rules/` (for example `argent init`, reported in GitHub issue #316).
+OAT accepts that shape through one narrow alias:
+
+- `alwaysApply: true` with no `activation` is read as `activation: always`.
+- Under that alias a null or empty `globs` value is ignored, and a non-empty
+  `globs` value is an error naming the file, because canonical rules keep globs
+  only for `activation: glob`.
+- An explicit `activation` always wins over `alwaysApply`.
+- `alwaysApply: false`, or any value other than `true`, without `activation`
+  stays an activation error that names the file.
+
+Every canonical rule parse error names the repository-relative rule file.
+
 ## Adoption model
 
 - Stray adoption is available in `oat init` and `oat status`.

package/assets/docs/provider-sync/scope-and-surface.md

@@ -45,6 +45,8 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - `oat providers codex materialize`
 - `oat project dispatch record` (project-aware dispatch evidence only; never a
   provider launcher)
+- `oat project dispatch canonical-role` (read-only; prints the
+  canonical-role-resolution event that `oat project dispatch record` accepts)
 
 ## Adjacent CLI commands (commonly used with provider interop)
 

package/assets/docs/reference/cli-reference.md

@@ -153,7 +153,8 @@ Notable commands introduced in the current CLI surface:
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
 - `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit]` - archive a tracked project through the same local move, summary export, and configured S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete inventory coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. For synced projects, a configured S3 upload must succeed before terminal cleanup. Successful closeout makes `refs/oat/completed/<project>` authoritative, deletes the tracked JSON record and nested checkout, and leaves archive metadata sufficient for an idempotent recordless retry. With `--json`, the terminal receipt reports `completedRef`, `verifiedSourceSha`, whether `activeAliasDisposition` was `retained` or `removed`, whether `recordRetired` completed, and the parent `lifecycleCommit`. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately leaves `lifecycleCommit` null. Never pass it through `oat-project-complete`, which requires that receipt.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
-- `oat project dispatch record --event-file <json-file-or-dash> [--project <project-path>]` - validate one generic dispatch record plus its namespaced OAT evidence event, and persist it into the project's append-only `dispatch/` journal (optional; no lifecycle skill requires persistence). Omit `--project` to validate without persisting. Managed, effort-pinned Claude launches use the validation-only form before launch: the input carries `claudeLaunch` with the real resolver result, generated definition, and proposed payload, plus `recordBase` and `event`. The command validates their agreement and derives the configured invocation fields; callers cannot copy those fields into `recordBase`. Revision 1 is `dispatch/<request-id>.json` and every later revision is `dispatch/<request-id>@<NNNN>.json`; superseded revisions are never replaced or removed. The command validates and records evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never persisted, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/projects/evidence-layers.md).
+- `oat project dispatch record --event-file <json-file-or-dash> [--project <project-path>]` - validate one generic dispatch record plus its namespaced OAT evidence event, and persist it into the project's append-only `dispatch/` journal (optional; no lifecycle skill requires persistence). Omit `--project` to validate without persisting. Managed, effort-pinned Claude launches use the validation-only form before launch: the input carries `claudeLaunch` with the real resolver result, generated definition, and proposed payload, plus `recordBase` and `event`. The command validates their agreement and derives the configured invocation fields; callers cannot copy those fields into `recordBase`. One validation run reports every violation across `claudeLaunch`, `recordBase`, and `event` in a single error message, one `stage path: message` line each; the `recordBase` cross-field rules run even when a required field is missing, checks that need a value that failed to parse are skipped and named on a final line, secret-shaped values and absolute paths are scrubbed from the message, and the exit code stays 1. A validated input per role is published at `.agents/skills/oat-dispatch-subagents/references/managed-claude-example.json`. Revision 1 is `dispatch/<request-id>.json` and every later revision is `dispatch/<request-id>@<NNNN>.json`; superseded revisions are never replaced or removed. The command validates and records evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never persisted, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/projects/evidence-layers.md).
+- `oat project dispatch canonical-role --role <name> --request-id <id> --skill-dir <dir> [--json]` - resolve a canonical role through the loaded, user (`$HOME/.agents`), and project (`<repo>/.agents`) tiers and print the `canonical-role-resolution` event that `oat project dispatch record` accepts unchanged: redacted `canonicalPath` and `selectedPath` in the form `<loaded|user|project>/agents/<name>.md`, the role's `contentDigest`, and `candidateMisses`. `--skill-dir` is required because the loaded tier is derived from the loaded skill's directory; a missing or invalid directory exits 1 with a redacted error. An unknown role prints `missing` evidence with its recovery commands. Read-only; the dependency is the `workflows` pack.
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a `manual:` instruction. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.

package/assets/docs/workflows/projects/autonomy.md

@@ -83,7 +83,7 @@ provider-level scalar in that scope or remain shadowed by one at higher
 precedence. It always tries the next authorized compatible candidate and stops
 without mutation only when none remains.
 
-The planner runs exactly one matching `oat config adopt dispatch-matrix`
+The planner runs exactly one matching `oat config adopt dispatch-matrix --keep-existing`
 command, records file-existence and compatibility evidence plus the selected
 scope, and re-runs dispatch preflight. Existing explicit cells remain unchanged;
 their provenance does not select the persistence scope. No authorized

package/assets/docs/workflows/projects/dispatch-ceiling.md

@@ -58,27 +58,32 @@ oat config adopt dispatch-matrix --local
 oat config adopt dispatch-matrix --user
 ```
 
-Adoption fills missing provider/tier cells and records
-`workflow.dispatchCeiling.recommendationVersion`; it does not replace explicit
-existing cells. Planning shows the complete recommendation before asking which
-scope should own it. If the resulting ladder is still missing or incomplete,
-planning remains blocked rather than replacing the user's explicit values.
-The recommendation version describes only the bundled recommendation. After
-preserving existing cells, OAT resolves the effective ladder and uses that
-effective result—not the recommendation version—for dispatch targets and
-runtime disclosure.
+Adoption replaces populated cells from the bundled recommendation in the
+chosen scope, fills missing cells, and retains extra custom tiers when the
+bundled provider remains a tier map. A bundled provider-level scalar replaces
+the whole provider, including custom tiers. It warns about replaced or
+removed cells and reports their paths. Use `--dry-run` to preview. For
+fill-only setup, `--keep-existing` preserves populated cells; if it fills
+nothing, both config and version remain unchanged. When it fills missing
+cells but preserves divergent cells, the version also stays unchanged. Planning always uses
+`--keep-existing` after showing the complete recommendation and asking which
+scope should own it. If the resulting effective ladder remains incomplete,
+planning blocks. The version identifies the bundle last written by adoption;
+it does not prove the effective ladder matches it. OAT resolves the effective
+ladder for dispatch targets and runtime disclosure.
 
 ### Upgrading to a newer recommendation version
 
-Preservation applies to whole cells, which has a consequence worth stating
-plainly: when a new recommendation version adds candidates to a tier you have
-already populated, re-running adoption will not give them to you. The existing
-cell is kept intact rather than merged candidate by candidate. Removals are not
-propagated either.
+A new bundled recommendation does not change an adopted config by itself.
+To update the chosen scope, first preview its affected cells:
 
-To pick up a new version, compare your
-`workflow.dispatchCeiling.recommendationVersion` against the bundled version,
-then either edit the affected cells by hand or clear them and re-adopt.
+```bash
+oat config adopt dispatch-matrix --user --dry-run
+```
+
+Run the same command without `--dry-run` to replace bundled cells. Use
+`--shared` or `--local` instead when that scope owns the ladder. Add
+`--keep-existing` to fill only missing cells and preserve existing choices.
 
 Version `2026-09-25.1` is the current bundled recommendation. It prefers
 GPT-6 Luna and Sol in Codex, then Sol xhigh, Astra high, and Astra xhigh in
@@ -96,9 +101,10 @@ Balanced, and Fable 5.1 thinking high replaces Fable 5 as Frontier's terminal
 target. The ordering is an explicit user-directed preference informed by
 vendor benchmarks and the model-selection matrix, not a local workload
 comparison. Grok 4.5 and Fable 5 stay supported for explicit configurations.
-Rerunning adoption preserves any
-explicit older cell unchanged. For the complete maintenance
-procedure, see [Updating Model Guidance](../../contributing/updating-model-guidance.md).
+Rerunning adoption replaces the bundled cells in the chosen scope; use
+`--keep-existing` to preserve explicit older cells. For the complete
+maintenance procedure, see
+[Updating Model Guidance](../../contributing/updating-model-guidance.md).
 
 The terminal Fable target may require model access from the executing provider.
 The adopting organization is responsible for confirming its applicable

package/assets/docs/workflows/projects/evidence-layers.md

@@ -86,7 +86,11 @@ before launch. That validation-only call derives the configured invocation and
 does not persist a journal file. When a host opts in, the generic snake-case
 fields remain authoritative. A namespaced `oat` block adds
 only canonical-role identity, proven pre-start rejection, fallback linkage,
-and optional runtime observation. `DispatchReportV1` and the parseable
+and optional runtime observation. `oat project dispatch canonical-role`
+prints the canonical-role-resolution event read-only, so callers do not
+hand-author it; a validated managed Claude input per role is published at
+`.agents/skills/oat-dispatch-subagents/references/managed-claude-example.json`.
+`DispatchReportV1` and the parseable
 `Dispatch:` compatibility stamp keep their existing byte shape.
 
 The launcher constructs and redacts the complete payload before calling the

package/assets/docs/workflows/projects/retro.md

@@ -84,6 +84,13 @@ Per-item statuses and frontmatter rollups make interrupted and repeated runs
 resumable. The promotions rollup covers RP apply-items; the filing rollup covers
 UP items plus RP file-items.
 
+Every run ends with a final report walkthrough that links the artifact and
+explains each `RP-*` and `UP-*` item (ID, title, summary, why it matters,
+current disposition and destination, and next action), grouped into apply,
+repository filing, and upstream filing items, or states that no items were
+proposed. It appears in interactive and non-interactive runs, whatever happened
+to apply and filing.
+
 ### Project-log receipt
 
 When a project log exists, generate mode appends this one-line structural

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.6",
-  "docs-config": "0.3.6",
-  "docs-theme": "0.3.6",
-  "docs-transforms": "0.3.6"
+  "cli": "0.3.8",
+  "docs-config": "0.3.8",
+  "docs-theme": "0.3.8",
+  "docs-transforms": "0.3.8"
 }

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.12.2
+  version: 1.12.3
 ---
 
 # Agent Instructions Analysis

package/assets/skills/oat-agent-instructions-analyze/scripts/resolve-providers.sh

@@ -78,11 +78,21 @@ resolve_from_sync_config() {
 }
 
 resolve_from_auto_detect() {
-  # Scan for provider directories
-  [[ -d "${REPO_ROOT}/.claude" || -f "${REPO_ROOT}/CLAUDE.md" ]] && providers+=("claude")
-  [[ -d "${REPO_ROOT}/.cursor" ]] && providers+=("cursor")
-  [[ -d "${REPO_ROOT}/.github/instructions" || -f "${REPO_ROOT}/.github/copilot-instructions.md" ]] && providers+=("copilot")
-  [[ -d "${REPO_ROOT}/.cline" ]] && providers+=("cline")
+  # Scan for provider directories. Each test is an `if` block so a false test
+  # never becomes the function's exit status under `set -e`.
+  if [[ -d "${REPO_ROOT}/.claude" || -f "${REPO_ROOT}/CLAUDE.md" ]]; then
+    providers+=("claude")
+  fi
+  if [[ -d "${REPO_ROOT}/.cursor" ]]; then
+    providers+=("cursor")
+  fi
+  if [[ -d "${REPO_ROOT}/.github/instructions" || -f "${REPO_ROOT}/.github/copilot-instructions.md" ]]; then
+    providers+=("copilot")
+  fi
+  if [[ -d "${REPO_ROOT}/.cline" ]]; then
+    providers+=("cline")
+  fi
+  return 0
 }
 
 interactive_confirm() {
@@ -103,7 +113,8 @@ interactive_confirm() {
   echo "" >&2
   echo "Available providers: claude, cursor, copilot, cline, codex" >&2
   echo -n "Add any additional providers? (comma-separated, or Enter to skip): " >&2
-  read -r additional
+  # EOF (for example Ctrl-D) means no additional providers, not failure.
+  read -r additional || additional=""
 
   if [[ -n "$additional" ]]; then
     IFS=',' read -ra items <<< "$additional"

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read
 metadata:
-  version: 1.2.9
+  version: 1.2.10
 ---
 
 # Dispatching OAT Subagents