@open-agent-toolkit/cli 0.3.6 → 0.3.7

package/assets/bundle-metadata.json

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

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

@@ -387,14 +387,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 +406,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 +706,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/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/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

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

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 2.0.0
+  version: 2.0.1
 ---
 
 # OAT Doctor
@@ -111,7 +111,7 @@ Each finding is one line with an **area**, a **severity**, a one-line **summary*
 - `activeProject` or `lastPausedProject` set to a path that does not exist → `error`; fix `oat config set activeProject ''` / `oat config set lastPausedProject ''` (the CLI refuses `unset` for these two lifecycle keys). `activeIdea` set to a missing path → `error`; fix `oat config unset activeIdea --local` (or `--user` for a user-level value).
 - A set key whose `describe` entry carries `deprecated` → `warning`; summary names the key and its `deprecated.supersededBy`; when `deprecated.legacyValues` is present the finding fires only when the set value is one of those values; fix = the entry's `owningCommand` for the successor.
 - A key set on a surface that is not one of the surfaces its `describe` entry's `file` names → `warning`; fix `oat config unset <key> --<surface>` then `oat config set <key> <value> --<right surface>`.
-- The `dispatch-matrix` recommendation is reported only through the `project:dispatch_matrix` check (command 1, config area); there is no separate rule for it, so one gap is one finding. Its fix is `oat config adopt dispatch-matrix --shared`, and the config dive explains it from `workflow.dispatchCeiling.recommendationVersion` in the dump.
+- The `project:dispatch_matrix` check (command 1, config area) reports target availability, not parity with the bundled recommendation. Do not infer parity from `workflow.dispatchCeiling.recommendationVersion`: it identifies the bundle last written by adoption. In the config dive, `oat config adopt dispatch-matrix --shared --keep-existing` fills missing cells and reports preserved differences; a direct adoption without `--keep-existing` replaces bundled cells in the chosen scope, so preview it with `--dry-run`.
 - A documented key group with nothing set on any surface → one `info` per group, expanded only in the dive.
 - Synced project health: `project:synced_tracked_artifacts`, `project:synced_gitignore`, `project:synced_projects`, `project:synced_editor_hint`, and per-project `project:synced_<slug>_<kind>` checks from command 1 → severity from status, summary from the message; report them without treating an absent checkout as proof that no synced project exists (an absent checkout is materialized by `oat project pull`, which the check's message names).
 

package/assets/skills/oat-project-autonomous/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.0.16
+  version: 1.0.17
 ---
 
 # Autonomous OAT Project
@@ -375,7 +375,7 @@ provider scalar or is shadowed by one at higher precedence, and block without
 mutation only when no authorized adoption-compatible scope remains. Existing
 explicit matrix cells are preserved by adoption; their provenance does not
 choose the persistence scope. Run exactly one matching
-`oat config adopt dispatch-matrix` command and re-run the reviewer preflight.
+`oat config adopt dispatch-matrix --keep-existing` command and re-run the reviewer preflight.
 Block when the ladder remains incomplete after adoption.
 
 At every required artifact or code review:

package/assets/skills/oat-project-import-plan/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.4.17
+  version: 1.4.18
 ---
 
 # Import External Plan
@@ -291,9 +291,9 @@ show the complete bundled recommendation and ask for its owning scope before
 running exactly one of:
 
 ```bash
-oat config adopt dispatch-matrix --shared
-oat config adopt dispatch-matrix --local
-oat config adopt dispatch-matrix --user
+oat config adopt dispatch-matrix --shared --keep-existing
+oat config adopt dispatch-matrix --local --keep-existing
+oat config adopt dispatch-matrix --user --keep-existing
 ```
 
 Adoption preserves explicit cells. Re-run the resolver and completeness check.

package/assets/skills/oat-project-plan/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.4.14
+  version: 1.4.15
 ---
 
 # Planning Phase
@@ -408,9 +408,9 @@ recommendation and ask the user to choose the owning scope before running
 exactly one of:
 
 ```bash
-oat config adopt dispatch-matrix --shared
-oat config adopt dispatch-matrix --local
-oat config adopt dispatch-matrix --user
+oat config adopt dispatch-matrix --shared --keep-existing
+oat config adopt dispatch-matrix --local --keep-existing
+oat config adopt dispatch-matrix --user --keep-existing
 ```
 
 Adoption fills missing cells but preserves explicit values. Re-run the resolver

package/assets/skills/oat-project-plan-writing/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read, Write, Glob, Grep
 metadata:
-  version: 1.2.32
+  version: 1.2.33
 ---
 
 # Plan Writing Contract
@@ -129,11 +129,11 @@ In an interactive run, ask the user to select the owning scope explicitly
 before any adoption write:
 
 1. **Shared repository** - team-owned `.oat/config.json`; run
-   `oat config adopt dispatch-matrix --shared`.
+   `oat config adopt dispatch-matrix --shared --keep-existing`.
 2. **Repo-local checkout** - personal `.oat/config.local.json`; run
-   `oat config adopt dispatch-matrix --local`.
+   `oat config adopt dispatch-matrix --local --keep-existing`.
 3. **User** - cross-repository `~/.oat/config.json`; run
-   `oat config adopt dispatch-matrix --user`.
+   `oat config adopt dispatch-matrix --user --keep-existing`.
 4. **Do not adopt** - leave setup unresolved and block implementation
    readiness.
 

package/assets/skills/oat-project-quick-start/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 2.3.15
+  version: 2.3.16
 ---
 
 # Quick Start Project
@@ -659,9 +659,9 @@ show the full bundled recommendation and ask the user to select its owning
 scope before running exactly one command:
 
 ```bash
-oat config adopt dispatch-matrix --shared
-oat config adopt dispatch-matrix --local
-oat config adopt dispatch-matrix --user
+oat config adopt dispatch-matrix --shared --keep-existing
+oat config adopt dispatch-matrix --local --keep-existing
+oat config adopt dispatch-matrix --user --keep-existing
 ```
 
 The selected scope owns only the reusable ladders. A project-specific active

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/config/index.js

@@ -1,5 +1,6 @@
 import { readFile as readFileDefault } from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { buildCommandContext } from '../../app/command-context.js';
 import { normalizeExcludedPaths } from '../instructions/instructions.utils.js';
 import { resolveProjectsRoot } from '../shared/oat-paths.js';
@@ -2353,6 +2354,14 @@ async function removeConfigPathOnDisk(configPath, path) {
     const { next, removed } = removeConfigPath(parsed, path);
     return removed ? next : null;
 }
+function warnBeforeReplacingCells(application, options, context) {
+    if (options.dryRun ||
+        context.json ||
+        application.replacedCells.length === 0) {
+        return;
+    }
+    context.logger.warn(`Replacing ${application.replacedCells.length} populated dispatch matrix cells from the bundled recommendation: ${application.replacedCells.join(', ')}.${application.droppedCells.length > 0 ? ` Whole-provider replacements remove: ${application.droppedCells.join(', ')}.` : ''} Use --keep-existing to preserve them or --dry-run to preview.`);
+}
 async function loadDispatchMatrixRecommendation(dependencies) {
     const assetsRoot = await dependencies.resolveAssetsRoot();
     const assetPath = join(assetsRoot, DISPATCH_MATRIX_RECOMMENDATION_ASSET);
@@ -2392,18 +2401,90 @@ async function validateRecommendationCells(repoRoot, recommendation, dependencie
         }
     }
 }
-function applyDispatchMatrixRecommendation(workflow, recommendation) {
+function applyDispatchMatrixRecommendation(workflow, recommendation, replace) {
     const existingProviders = workflow?.dispatchCeiling?.providers ?? {};
     const providers = {
         ...recommendation.providers,
     };
+    const filledCells = [];
+    const preservedCells = [];
+    const differingCells = [];
+    const replacedCells = [];
+    const droppedCells = [];
+    for (const [provider, recommendedValue] of Object.entries(recommendation.providers)) {
+        const path = `${DISPATCH_CEILING_PROVIDER_KEY_PREFIX}${provider}`;
+        const existingValue = getOwnKey(existingProviders, provider);
+        if (existingValue === undefined) {
+            if (typeof recommendedValue === 'string') {
+                filledCells.push(path);
+            }
+            else {
+                filledCells.push(...Object.keys(recommendedValue).map((tier) => `${path}.${tier}`));
+            }
+            continue;
+        }
+        if (typeof recommendedValue === 'string' ||
+            typeof existingValue === 'string') {
+            if (!isDeepStrictEqual(existingValue, recommendedValue)) {
+                differingCells.push(path);
+                if (replace) {
+                    replacedCells.push(path);
+                    if (typeof recommendedValue === 'string' &&
+                        typeof existingValue !== 'string') {
+                        droppedCells.push(...Object.keys(existingValue).map((tier) => `${path}.${tier}`));
+                    }
+                }
+                else {
+                    preservedCells.push(path);
+                }
+            }
+            else {
+                preservedCells.push(path);
+            }
+            continue;
+        }
+        for (const [tier, recommendedCell] of Object.entries(recommendedValue)) {
+            const cellPath = `${path}.${tier}`;
+            const existingCell = getOwnKey(existingValue, tier);
+            if (existingCell === undefined) {
+                filledCells.push(cellPath);
+            }
+            else {
+                if (!isDeepStrictEqual(existingCell, recommendedCell)) {
+                    differingCells.push(cellPath);
+                    if (replace) {
+                        replacedCells.push(cellPath);
+                    }
+                    else {
+                        preservedCells.push(cellPath);
+                    }
+                }
+                else {
+                    preservedCells.push(cellPath);
+                }
+            }
+        }
+    }
     // `existingProviders` is a `normalizeDispatchMatrix` product, which now
     // keeps a provider literally named `__proto__` as an own key, so
     // `Object.entries` yields it here and every access is own-key guarded. The
     // `{ ...recommendation.providers }` spread above is already safe.
     for (const [provider, existingValue] of Object.entries(existingProviders)) {
         const recommendedValue = getOwnKey(recommendation.providers, provider);
-        if (recommendedValue &&
+        if (replace &&
+            recommendedValue &&
+            typeof recommendedValue !== 'string' &&
+            typeof existingValue !== 'string') {
+            setOwnKey(providers, provider, {
+                ...existingValue,
+                ...recommendedValue,
+            });
+        }
+        else if (replace && recommendedValue !== undefined) {
+            // A bare provider override is replaced as one configured cell.
+            setOwnKey(providers, provider, recommendedValue);
+        }
+        else if (recommendedValue &&
             typeof recommendedValue !== 'string' &&
             typeof existingValue !== 'string') {
             setOwnKey(providers, provider, {
@@ -2415,13 +2496,31 @@ function applyDispatchMatrixRecommendation(workflow, recommendation) {
             setOwnKey(providers, provider, existingValue);
         }
     }
+    const versionWritten = replace
+        ? filledCells.length > 0 ||
+            replacedCells.length > 0 ||
+            workflow?.dispatchCeiling?.recommendationVersion !==
+                recommendation.version
+        : filledCells.length > 0 && differingCells.length === 0;
+    const writeRequired = filledCells.length > 0 || replacedCells.length > 0 || versionWritten;
     return {
-        ...(workflow ?? {}),
-        dispatchCeiling: {
-            ...workflow?.dispatchCeiling,
-            recommendationVersion: recommendation.version,
-            providers,
+        workflow: {
+            ...(workflow ?? {}),
+            dispatchCeiling: {
+                ...workflow?.dispatchCeiling,
+                ...(versionWritten
+                    ? { recommendationVersion: recommendation.version }
+                    : {}),
+                providers,
+            },
         },
+        filledCells,
+        preservedCells,
+        differingCells,
+        replacedCells,
+        droppedCells,
+        versionWritten,
+        writeRequired,
     };
 }
 async function effectiveTerminalReviewerNotices(repoRoot, userConfigDir, dependencies) {
@@ -2443,45 +2542,92 @@ async function adoptDispatchMatrixRecommendation(repoRoot, userConfigDir, option
     if (source === 'user') {
         const userConfig = await dependencies.readUserConfig(userConfigDir);
         await validateRecommendationCells(repoRoot, recommendation, dependencies, context.logger.warn);
-        const workflow = applyDispatchMatrixRecommendation(userConfig.workflow, recommendation);
-        await dependencies.writeUserConfig(userConfigDir, {
-            ...userConfig,
-            workflow,
-        });
+        const application = applyDispatchMatrixRecommendation(userConfig.workflow, recommendation, options.replace);
+        warnBeforeReplacingCells(application, options, context);
+        if (application.writeRequired && !options.dryRun) {
+            await dependencies.writeUserConfig(userConfigDir, {
+                ...userConfig,
+                workflow: application.workflow,
+            });
+        }
         return {
             key: 'workflow.dispatchCeiling.providers',
             value: recommendation.version,
             source,
-            notices: await effectiveTerminalReviewerNotices(repoRoot, userConfigDir, dependencies),
+            versionWritten: application.versionWritten && !options.dryRun,
+            dryRun: options.dryRun,
+            currentVersion: (options.dryRun
+                ? userConfig.workflow?.dispatchCeiling?.recommendationVersion
+                : application.workflow.dispatchCeiling?.recommendationVersion) ??
+                null,
+            filledCells: application.filledCells,
+            preservedCells: application.preservedCells,
+            differingCells: application.differingCells,
+            replacedCells: application.replacedCells,
+            droppedCells: application.droppedCells,
+            notices: options.dryRun
+                ? []
+                : await effectiveTerminalReviewerNotices(repoRoot, userConfigDir, dependencies),
         };
     }
     if (source === 'local') {
         const localConfig = await dependencies.readOatLocalConfig(repoRoot);
         await validateRecommendationCells(repoRoot, recommendation, dependencies, context.logger.warn);
-        const workflow = applyDispatchMatrixRecommendation(localConfig.workflow, recommendation);
-        await dependencies.writeOatLocalConfig(repoRoot, {
-            ...localConfig,
-            workflow,
-        });
+        const application = applyDispatchMatrixRecommendation(localConfig.workflow, recommendation, options.replace);
+        warnBeforeReplacingCells(application, options, context);
+        if (application.writeRequired && !options.dryRun) {
+            await dependencies.writeOatLocalConfig(repoRoot, {
+                ...localConfig,
+                workflow: application.workflow,
+            });
+        }
         return {
             key: 'workflow.dispatchCeiling.providers',
             value: recommendation.version,
             source,
-            notices: await effectiveTerminalReviewerNotices(repoRoot, userConfigDir, dependencies),
+            versionWritten: application.versionWritten && !options.dryRun,
+            dryRun: options.dryRun,
+            currentVersion: (options.dryRun
+                ? localConfig.workflow?.dispatchCeiling?.recommendationVersion
+                : application.workflow.dispatchCeiling?.recommendationVersion) ??
+                null,
+            filledCells: application.filledCells,
+            preservedCells: application.preservedCells,
+            differingCells: application.differingCells,
+            replacedCells: application.replacedCells,
+            droppedCells: application.droppedCells,
+            notices: options.dryRun
+                ? []
+                : await effectiveTerminalReviewerNotices(repoRoot, userConfigDir, dependencies),
         };
     }
     const sharedConfig = await dependencies.readOatConfig(repoRoot);
     await validateRecommendationCells(repoRoot, recommendation, dependencies, context.logger.warn);
-    const workflow = applyDispatchMatrixRecommendation(sharedConfig.workflow, recommendation);
-    await dependencies.writeOatConfig(repoRoot, {
-        ...sharedConfig,
-        workflow,
-    });
+    const application = applyDispatchMatrixRecommendation(sharedConfig.workflow, recommendation, options.replace);
+    warnBeforeReplacingCells(application, options, context);
+    if (application.writeRequired && !options.dryRun) {
+        await dependencies.writeOatConfig(repoRoot, {
+            ...sharedConfig,
+            workflow: application.workflow,
+        });
+    }
     return {
         key: 'workflow.dispatchCeiling.providers',
         value: recommendation.version,
         source,
-        notices: await effectiveTerminalReviewerNotices(repoRoot, userConfigDir, dependencies),
+        versionWritten: application.versionWritten && !options.dryRun,
+        dryRun: options.dryRun,
+        currentVersion: (options.dryRun
+            ? sharedConfig.workflow?.dispatchCeiling?.recommendationVersion
+            : application.workflow.dispatchCeiling?.recommendationVersion) ?? null,
+        filledCells: application.filledCells,
+        preservedCells: application.preservedCells,
+        differingCells: application.differingCells,
+        replacedCells: application.replacedCells,
+        droppedCells: application.droppedCells,
+        notices: options.dryRun
+            ? []
+            : await effectiveTerminalReviewerNotices(repoRoot, userConfigDir, dependencies),
     };
 }
 function formatList(values) {
@@ -2686,10 +2832,40 @@ async function runAdopt(templateArg, options, context, dependencies) {
             context.logger.json({
                 status: 'ok',
                 ...result,
+                ...jsonWarnings(result.replacedCells.length > 0 && !result.dryRun
+                    ? [
+                        `Replaced ${result.replacedCells.length} populated dispatch matrix cells from the bundled recommendation.${result.droppedCells.length > 0 ? ` Removed whole-provider tier cells: ${result.droppedCells.join(', ')}.` : ''} Use --keep-existing to preserve them.`,
+                    ]
+                    : []),
             });
         }
         else {
-            context.logger.info(`Adopted dispatch matrix recommendation ${result.value} to ${result.source} config.`);
+            if (result.dryRun) {
+                context.logger.info(`Dry run for ${result.source} config using recommendation ${result.value}: would fill ${result.filledCells.length} cells and replace ${result.replacedCells.length} cells; no config changed.`);
+            }
+            else if (result.versionWritten ||
+                result.filledCells.length > 0 ||
+                result.replacedCells.length > 0) {
+                context.logger.info(`Applied dispatch matrix recommendation ${result.value} to ${result.source} config: filled ${result.filledCells.length} cells and replaced ${result.replacedCells.length} cells.`);
+            }
+            else {
+                context.logger.info(`No missing dispatch matrix cells in ${result.source} config; recommendation version remains ${result.currentVersion ?? 'unset'}.`);
+            }
+            if (result.replacedCells.length > 0) {
+                context.logger.info(`${result.dryRun ? 'Would replace' : 'Replaced'}: ${result.replacedCells.join(', ')}.`);
+                if (result.droppedCells.length > 0) {
+                    context.logger.warn(`${result.dryRun ? 'Would remove' : 'Removed'} whole-provider tier cells: ${result.droppedCells.join(', ')}.`);
+                }
+            }
+            else if (result.differingCells.length > 0) {
+                context.logger.warn(`Preserved cells differ from recommendation ${result.value}: ${result.differingCells.join(', ')}. Review and update those cells explicitly if you want the new ladder.`);
+            }
+            if (!result.dryRun &&
+                !result.versionWritten &&
+                result.filledCells.length > 0 &&
+                result.differingCells.length > 0) {
+                context.logger.warn(`Recommendation version remains ${result.currentVersion ?? 'unset'} because preserved cells differ from ${result.value}.`);
+            }
             if (result.notices.length > 0) {
                 context.logger.info(formatDispatchNotices(result.notices));
             }
@@ -2843,12 +3019,18 @@ export function createConfigCommand(overrides = {}) {
         .option('--shared', 'Write to the shared repo config (.oat/config.json)')
         .option('--local', 'Write to the repo-local config (.oat/config.local.json)')
         .option('--user', 'Write to the user-level config (~/.oat/config.json)')
-        .option('--yes', 'Compatibility flag; adoption always preserves explicit existing cells')
+        .option('--yes', 'Compatibility flag; adoption does not require confirmation')
+        .option('--keep-existing', 'Fill missing cells without replacing populated cells')
+        .option('--dry-run', 'Preview cell changes without writing config')
         .action(async (template, options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         try {
             const surface = resolveSurfaceFlags(options);
-            await runAdopt(template, { surface }, context, dependencies);
+            await runAdopt(template, {
+                surface,
+                replace: !(options.keepExisting ?? false),
+                dryRun: options.dryRun ?? false,
+            }, context, dependencies);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.3.6"
+    "@open-agent-toolkit/control-plane": "0.3.7"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",