@open-agent-toolkit/cli 0.1.43 → 0.1.46

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

@@ -1,6 +1,8 @@
 import { buildCommandContext, type CommandContext } from '../../app/command-context.js';
+import { type PromptContext } from '../shared/shared.prompts.js';
 import { type OatConfig, type OatLocalConfig, type UserConfig } from '../../config/oat-config.js';
 import { type ResolvedConfig } from '../../config/resolve.js';
+import { type MatrixCellAvailabilityResponse, type ValidateMatrixCellOptions } from '../../providers/identity/availability.js';
 import { Command } from 'commander';
 interface ConfigCommandDependencies {
     buildCommandContext: (options: Parameters<typeof buildCommandContext>[0]) => CommandContext;
@@ -13,6 +15,10 @@ interface ConfigCommandDependencies {
     writeUserConfig: (userConfigDir: string, config: UserConfig) => Promise<void>;
     resolveProjectsRoot: (repoRoot: string, env: NodeJS.ProcessEnv) => Promise<string>;
     resolveEffectiveConfig: (repoRoot: string, userConfigDir: string, env: NodeJS.ProcessEnv) => Promise<ResolvedConfig>;
+    resolveAssetsRoot: () => Promise<string>;
+    readFile: (path: string) => Promise<string>;
+    confirmAction: (message: string, ctx: PromptContext) => Promise<boolean>;
+    validateMatrixCell: (provider: string, value: string, options: ValidateMatrixCellOptions) => Promise<MatrixCellAvailabilityResponse>;
     processEnv: NodeJS.ProcessEnv;
 }
 export declare function createConfigCommand(overrides?: Partial<ConfigCommandDependencies>): Command;

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":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAIhF,OAAO,EACL,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAUhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgEpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAyzCD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CA0GT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAQzC,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAehB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAGL,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAC/B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkFpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC7C,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AA65DD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAwKT"}

package/dist/commands/config/index.js

@@ -1,13 +1,25 @@
+import { readFile as readFileDefault } from 'node:fs/promises';
 import { join } from 'node:path';
 import { buildCommandContext } from '../../app/command-context.js';
 import { resolveProjectsRoot } from '../shared/oat-paths.js';
+import { confirmAction, } from '../shared/shared.prompts.js';
 import { readGlobalOptions } from '../shared/shared.utils.js';
 import { compileDispatchCeilingPreset } from '../../config/dispatch-ceiling-preset.js';
-import { readOatConfig, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
+import { dispatchPolicyModeDescription, dispatchPolicyPolicyDescription, managedDispatchPolicyValueList, } from '../../config/dispatch-policy-options.js';
+import { VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, isCodexMaterializedRouteTarget, readOatConfig, readOatLocalConfig, readUserConfig, validateDispatchRouteTarget, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
 import { resolveEffectiveConfig, } from '../../config/resolve.js';
+import { resolveAssetsRoot } from '../../fs/assets.js';
 import { resolveProjectRoot } from '../../fs/paths.js';
+import { normalizeMatrixCellAvailability, validateMatrixCell, } from '../../providers/identity/availability.js';
 import { Command } from 'commander';
 import { createConfigDumpCommand } from './dump.js';
+const DISPATCH_CEILING_PROVIDER_KEY_PREFIX = 'workflow.dispatchCeiling.providers.';
+const DISPATCH_MATRIX_TIERS = [
+    'economy',
+    'balanced',
+    'high',
+    'frontier',
+];
 const KEY_ORDER = [
     'activeIdea',
     'activeProject',
@@ -467,7 +479,7 @@ const CONFIG_CATALOG = [
         defaultValue: 'unset',
         mutability: 'read/write',
         owningCommand: 'oat config set workflow.dispatchPolicy.mode <value>',
-        description: 'Dispatch policy mode. "managed" means OAT selects model/effort from workflow.dispatchPolicy.policy; "inherit" means OAT leaves dispatch controls to the host/provider defaults. Set workflow.dispatchPolicy.policy to choose a managed policy. Resolution: local > shared > user > default.',
+        description: dispatchPolicyModeDescription(),
     },
     {
         key: 'workflow.dispatchPolicy.policy',
@@ -478,7 +490,7 @@ const CONFIG_CATALOG = [
         defaultValue: 'unset',
         mutability: 'read/write',
         owningCommand: 'oat config set workflow.dispatchPolicy.policy <value>',
-        description: 'Managed dispatch policy. economy, balanced, high, and frontier are capped managed policies; uncapped keeps OAT-managed preferred selection without provider caps. Setting this key writes workflow.dispatchPolicy.mode=managed. Resolution: local > shared > user > default.',
+        description: dispatchPolicyPolicyDescription(),
     },
     {
         key: 'workflow.dispatchCeiling.providers.codex',
@@ -547,10 +559,49 @@ const DEFAULT_DEPENDENCIES = {
     writeUserConfig,
     resolveProjectsRoot,
     resolveEffectiveConfig,
+    resolveAssetsRoot,
+    readFile: (path) => readFileDefault(path, 'utf8'),
+    confirmAction,
+    validateMatrixCell,
     processEnv: process.env,
 };
 function isConfigKey(value) {
-    return KEY_ORDER.includes(value);
+    return (KEY_ORDER.includes(value) ||
+        isDispatchCeilingProviderKey(value));
+}
+function isDispatchCeilingProviderKey(value) {
+    return (value.startsWith(DISPATCH_CEILING_PROVIDER_KEY_PREFIX) &&
+        value.slice(DISPATCH_CEILING_PROVIDER_KEY_PREFIX.length).trim().length > 0);
+}
+function isDispatchMatrixTier(value) {
+    return DISPATCH_MATRIX_TIERS.includes(value);
+}
+function parseDispatchCeilingProviderConfigKey(key) {
+    const suffix = key.slice(DISPATCH_CEILING_PROVIDER_KEY_PREFIX.length).trim();
+    const parts = suffix.split('.').map((part) => part.trim());
+    const invalidMessage = `Invalid config key ${key}: expected workflow.dispatchCeiling.providers.<provider> or workflow.dispatchCeiling.providers.<provider>.<tier> with tier one of ${DISPATCH_MATRIX_TIERS.join(' | ')}.`;
+    if (parts.some((part) => part.length === 0)) {
+        throw new Error(invalidMessage);
+    }
+    if (parts.length === 1) {
+        const provider = parts[0];
+        if (!provider) {
+            throw new Error(invalidMessage);
+        }
+        return { provider };
+    }
+    const tier = parts[parts.length - 1];
+    if (!tier || !isDispatchMatrixTier(tier)) {
+        throw new Error(invalidMessage);
+    }
+    const provider = parts.slice(0, -1).join('.').trim();
+    if (!provider) {
+        throw new Error(invalidMessage);
+    }
+    return { provider, tier };
+}
+function providerNameFromConfigKey(key) {
+    return parseDispatchCeilingProviderConfigKey(key).provider;
 }
 function normalizeSharedRoot(value) {
     const trimmed = value.trim();
@@ -564,14 +615,8 @@ const WORKFLOW_ENUM_VALUES = {
     'workflow.postImplementSequence': ['wait', 'summary', 'pr', 'docs-pr'],
     'workflow.reviewExecutionModel': ['subagent', 'inline', 'fresh-session'],
     'workflow.designMode': ['collaborative', 'selective', 'draft'],
-    'workflow.dispatchPolicy.mode': ['managed', 'inherit'],
-    'workflow.dispatchPolicy.policy': [
-        'economy',
-        'balanced',
-        'high',
-        'frontier',
-        'uncapped',
-    ],
+    'workflow.dispatchPolicy.mode': [...VALID_DISPATCH_POLICY_MODES],
+    'workflow.dispatchPolicy.policy': [...VALID_MANAGED_DISPATCH_POLICIES],
     'workflow.dispatchCeiling.preset': ['balanced', 'maximum', 'cost-conscious'],
     'workflow.dispatchCeiling.providers.codex': [
         'low',
@@ -586,6 +631,15 @@ const WORKFLOW_ENUM_VALUES = {
         'fable',
     ],
 };
+function closedDispatchProviderValues(provider) {
+    if (provider === 'codex') {
+        return WORKFLOW_ENUM_VALUES['workflow.dispatchCeiling.providers.codex'];
+    }
+    if (provider === 'claude') {
+        return WORKFLOW_ENUM_VALUES['workflow.dispatchCeiling.providers.claude'];
+    }
+    return undefined;
+}
 const WORKFLOW_BOOLEAN_KEYS = new Set([
     'workflow.archiveOnComplete',
     'workflow.createPrOnComplete',
@@ -666,8 +720,144 @@ function parseWorkflowValue(key, rawValue) {
         }
         return normalized;
     }
+    if (isDispatchCeilingProviderKey(key)) {
+        const { provider } = parseDispatchCeilingProviderConfigKey(key);
+        const normalized = rawValue.trim();
+        if (normalized.length === 0) {
+            throw new Error(`Invalid value for ${key}: provider values cannot be empty`);
+        }
+        const closedValues = closedDispatchProviderValues(provider);
+        if (closedValues && !closedValues.includes(normalized)) {
+            throw new Error(`Invalid value for ${key}: expected one of ${closedValues.join(' | ')}, got '${rawValue}'`);
+        }
+        return normalized;
+    }
     throw new Error(`Unknown workflow key: ${key}`);
 }
+function dispatchProviderAvailabilityWarning(key, value, availability) {
+    return matrixCellAvailabilityWarning(key, value, availability);
+}
+const DISPATCH_MATRIX_RECOMMENDATION_ASSET = join('config', 'dispatch-matrix-recommendation.json');
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function matrixCellAvailabilityWarning(path, value, availability) {
+    const result = normalizeMatrixCellAvailability(availability);
+    if (result.availability === 'valid') {
+        return null;
+    }
+    const details = result.message ? ` ${result.message}` : '';
+    if (result.availability === 'unknown-value') {
+        return `${path} value '${value}' was not recognized by the provider availability oracle; saving anyway.${details}`;
+    }
+    return `${path} value '${value}' could not be validated because the provider availability oracle is unavailable; saving anyway.${details}`;
+}
+function parseDispatchMatrixRecommendation(raw) {
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed)) {
+        throw new Error('Dispatch matrix recommendation asset must be an object.');
+    }
+    const version = typeof parsed.version === 'string' ? parsed.version.trim() : '';
+    if (!version) {
+        throw new Error('Dispatch matrix recommendation asset is missing a version.');
+    }
+    if (!isRecord(parsed.providers)) {
+        throw new Error('Dispatch matrix recommendation asset is missing providers.');
+    }
+    return {
+        version,
+        providers: parsed.providers,
+    };
+}
+function isRouteTarget(entry) {
+    return isRecord(entry);
+}
+function formatRouteTargetValue(entry) {
+    return [entry.model, entry.effort].filter(Boolean).join('/');
+}
+function addDispatchMatrixCellRefs(refs, provider, path, cell) {
+    if (typeof cell === 'string') {
+        refs.push({ provider, value: cell, path });
+        return;
+    }
+    for (const [index, entry] of cell.entries()) {
+        const entryPath = `${path}[${index}]`;
+        if (typeof entry === 'string') {
+            refs.push({ provider, value: entry, path: entryPath });
+            continue;
+        }
+        if (!isRouteTarget(entry)) {
+            continue;
+        }
+        const targetProvider = entry.harness ?? provider;
+        if (isCodexMaterializedRouteTarget(provider, entry)) {
+            if (entry.model && entry.effort) {
+                refs.push({
+                    provider: targetProvider,
+                    value: formatRouteTargetValue(entry),
+                    path: entryPath,
+                    target: entry,
+                });
+                continue;
+            }
+        }
+        if (entry.model) {
+            refs.push({
+                provider: targetProvider,
+                value: entry.model,
+                path: `${entryPath}.model`,
+            });
+        }
+        if (entry.effort) {
+            refs.push({
+                provider: targetProvider,
+                value: entry.effort,
+                path: `${entryPath}.effort`,
+            });
+        }
+    }
+}
+function collectDispatchMatrixCellRefs(providers) {
+    const refs = [];
+    for (const [provider, providerValue] of Object.entries(providers)) {
+        const providerPath = `workflow.dispatchCeiling.providers.${provider}`;
+        if (typeof providerValue === 'string') {
+            refs.push({ provider, value: providerValue, path: providerPath });
+            continue;
+        }
+        for (const [tier, cell] of Object.entries(providerValue)) {
+            if (cell === undefined) {
+                continue;
+            }
+            addDispatchMatrixCellRefs(refs, provider, `${providerPath}.${tier}`, cell);
+        }
+    }
+    return refs;
+}
+function collectDispatchMatrixTargetValidationErrors(providers) {
+    const errors = [];
+    for (const [provider, providerValue] of Object.entries(providers)) {
+        if (typeof providerValue === 'string') {
+            continue;
+        }
+        const providerPath = `workflow.dispatchCeiling.providers.${provider}`;
+        for (const [tier, cell] of Object.entries(providerValue)) {
+            if (!Array.isArray(cell)) {
+                continue;
+            }
+            for (const [index, entry] of cell.entries()) {
+                if (!isRouteTarget(entry)) {
+                    continue;
+                }
+                const validation = validateDispatchRouteTarget(provider, entry);
+                if (!validation.valid) {
+                    errors.push(`${providerPath}.${tier}[${index}]: ${validation.reason}`);
+                }
+            }
+        }
+    }
+    return errors;
+}
 function applyWorkflowValue(workflow, key, value) {
     const subKey = key.slice('workflow.'.length);
     if (subKey === 'dispatchPolicy.mode') {
@@ -680,7 +870,7 @@ function applyWorkflowValue(workflow, key, value) {
         }
         const policy = workflow.dispatchPolicy?.policy;
         if (!policy) {
-            throw new Error('Cannot set workflow.dispatchPolicy.mode to managed without an existing workflow.dispatchPolicy.policy. Set workflow.dispatchPolicy.policy <economy|balanced|high|frontier|uncapped> instead.');
+            throw new Error(`Cannot set workflow.dispatchPolicy.mode to managed without an existing workflow.dispatchPolicy.policy. Set workflow.dispatchPolicy.policy <${managedDispatchPolicyValueList('|')}> instead.`);
         }
         return {
             ...workflow,
@@ -714,15 +904,37 @@ function applyWorkflowValue(workflow, key, value) {
             },
         };
     }
-    if (subKey.startsWith('dispatchCeiling.providers.')) {
-        const providerKey = subKey.slice('dispatchCeiling.providers.'.length);
+    if (isDispatchCeilingProviderKey(key)) {
+        const { provider, tier } = parseDispatchCeilingProviderConfigKey(key);
+        const providers = workflow.dispatchCeiling?.providers ?? {};
+        if (tier) {
+            const existingProviderValue = providers[provider];
+            const existingTierMap = existingProviderValue &&
+                typeof existingProviderValue === 'object' &&
+                !Array.isArray(existingProviderValue)
+                ? existingProviderValue
+                : {};
+            return {
+                ...workflow,
+                dispatchCeiling: {
+                    ...workflow.dispatchCeiling,
+                    providers: {
+                        ...providers,
+                        [provider]: {
+                            ...existingTierMap,
+                            [tier]: value,
+                        },
+                    },
+                },
+            };
+        }
         return {
             ...workflow,
             dispatchCeiling: {
                 ...workflow.dispatchCeiling,
                 providers: {
-                    ...workflow.dispatchCeiling?.providers,
-                    [providerKey]: value,
+                    ...providers,
+                    [provider]: value,
                 },
             },
         };
@@ -769,12 +981,32 @@ async function getConfigValue(repoRoot, userConfigDir, key, dependencies) {
         source: entry.source,
     };
 }
-async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, dependencies) {
+async function listConfigKeys(repoRoot, userConfigDir, dependencies) {
+    const resolved = await dependencies.resolveEffectiveConfig(repoRoot, userConfigDir, dependencies.processEnv);
+    const staticKeys = new Set(KEY_ORDER);
+    const dynamicProviderKeys = Object.keys(resolved.resolved)
+        .filter(isDispatchCeilingProviderKey)
+        .filter((key) => !staticKeys.has(key))
+        .sort();
+    return [...KEY_ORDER, ...dynamicProviderKeys];
+}
+async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, dependencies, warn) {
     validateSurfaceForKey(key, surface);
     const effectiveSurface = surface === 'auto' ? defaultSurfaceForKey(key) : surface;
     if (isWorkflowKey(key)) {
         const parsedValue = parseWorkflowValue(key, rawValue);
         const displayValue = typeof parsedValue === 'boolean' ? String(parsedValue) : parsedValue;
+        if (typeof parsedValue === 'string' && isDispatchCeilingProviderKey(key)) {
+            const availability = await dependencies.validateMatrixCell(providerNameFromConfigKey(key), parsedValue, {
+                cwd: repoRoot,
+                env: dependencies.processEnv,
+                detailed: true,
+            });
+            const warning = dispatchProviderAvailabilityWarning(key, parsedValue, availability);
+            if (warning) {
+                warn(warning);
+            }
+        }
         if (effectiveSurface === 'user') {
             const userConfig = await dependencies.readUserConfig(userConfigDir);
             await dependencies.writeUserConfig(userConfigDir, {
@@ -952,6 +1184,115 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
         source: 'shared',
     };
 }
+function hasExistingDispatchMatrix(config) {
+    const providers = config.workflow?.dispatchCeiling?.providers;
+    return providers !== undefined && Object.keys(providers).length > 0;
+}
+async function loadDispatchMatrixRecommendation(dependencies) {
+    const assetsRoot = await dependencies.resolveAssetsRoot();
+    const assetPath = join(assetsRoot, DISPATCH_MATRIX_RECOMMENDATION_ASSET);
+    return parseDispatchMatrixRecommendation(await dependencies.readFile(assetPath));
+}
+async function validateRecommendationCells(repoRoot, recommendation, dependencies, warn) {
+    const targetErrors = collectDispatchMatrixTargetValidationErrors(recommendation.providers);
+    if (targetErrors.length > 0) {
+        throw new Error(targetErrors.join('\n'));
+    }
+    for (const ref of collectDispatchMatrixCellRefs(recommendation.providers)) {
+        const closedValues = closedDispatchProviderValues(ref.provider);
+        if (!ref.target && closedValues && !closedValues.includes(ref.value)) {
+            throw new Error(`Invalid value for ${ref.path}: expected one of ${closedValues.join(' | ')}, got '${ref.value}'`);
+        }
+        let availability;
+        try {
+            availability = await dependencies.validateMatrixCell(ref.provider, ref.value, {
+                cwd: repoRoot,
+                env: dependencies.processEnv,
+                detailed: true,
+                ...(ref.target ? { target: ref.target } : {}),
+            });
+        }
+        catch {
+            availability = 'unvalidated';
+        }
+        const warning = matrixCellAvailabilityWarning(ref.path, ref.value, availability);
+        if (warning) {
+            warn(warning);
+        }
+    }
+}
+function applyDispatchMatrixRecommendation(workflow, recommendation) {
+    return {
+        ...(workflow ?? {}),
+        dispatchCeiling: {
+            ...workflow?.dispatchCeiling,
+            recommendationVersion: recommendation.version,
+            providers: recommendation.providers,
+        },
+    };
+}
+async function confirmDispatchMatrixOverwrite(context, dependencies, source, yes) {
+    if (yes) {
+        return;
+    }
+    if (!context.interactive) {
+        throw new Error('Dispatch matrix already exists; rerun interactively or pass --yes to replace it.');
+    }
+    const shouldReplace = await dependencies.confirmAction(`Replace existing dispatch matrix in ${source} config?`, { interactive: context.interactive });
+    if (!shouldReplace) {
+        throw new Error('Dispatch matrix adoption cancelled; existing matrix unchanged.');
+    }
+}
+async function adoptDispatchMatrixRecommendation(repoRoot, userConfigDir, options, context, dependencies) {
+    const source = options.surface === 'auto' ? 'local' : options.surface;
+    const recommendation = await loadDispatchMatrixRecommendation(dependencies);
+    if (source === 'user') {
+        const userConfig = await dependencies.readUserConfig(userConfigDir);
+        if (hasExistingDispatchMatrix(userConfig)) {
+            await confirmDispatchMatrixOverwrite(context, dependencies, source, options.yes);
+        }
+        await validateRecommendationCells(repoRoot, recommendation, dependencies, context.logger.warn);
+        await dependencies.writeUserConfig(userConfigDir, {
+            ...userConfig,
+            workflow: applyDispatchMatrixRecommendation(userConfig.workflow, recommendation),
+        });
+        return {
+            key: 'workflow.dispatchCeiling.providers',
+            value: recommendation.version,
+            source,
+        };
+    }
+    if (source === 'local') {
+        const localConfig = await dependencies.readOatLocalConfig(repoRoot);
+        if (hasExistingDispatchMatrix(localConfig)) {
+            await confirmDispatchMatrixOverwrite(context, dependencies, source, options.yes);
+        }
+        await validateRecommendationCells(repoRoot, recommendation, dependencies, context.logger.warn);
+        await dependencies.writeOatLocalConfig(repoRoot, {
+            ...localConfig,
+            workflow: applyDispatchMatrixRecommendation(localConfig.workflow, recommendation),
+        });
+        return {
+            key: 'workflow.dispatchCeiling.providers',
+            value: recommendation.version,
+            source,
+        };
+    }
+    const sharedConfig = await dependencies.readOatConfig(repoRoot);
+    if (hasExistingDispatchMatrix(sharedConfig)) {
+        await confirmDispatchMatrixOverwrite(context, dependencies, source, options.yes);
+    }
+    await validateRecommendationCells(repoRoot, recommendation, dependencies, context.logger.warn);
+    await dependencies.writeOatConfig(repoRoot, {
+        ...sharedConfig,
+        workflow: applyDispatchMatrixRecommendation(sharedConfig.workflow, recommendation),
+    });
+    return {
+        key: 'workflow.dispatchCeiling.providers',
+        value: recommendation.version,
+        source,
+    };
+}
 function formatList(values) {
     const keyWidth = Math.max('Key'.length, ...values.map((item) => item.key.length));
     const sourceWidth = Math.max('Source'.length, ...values.map((item) => item.source.length));
@@ -1044,7 +1385,7 @@ async function runSet(keyArg, rawValue, surface, context, dependencies) {
         }
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
         const userConfigDir = join(context.home, '.oat');
-        const result = await setConfigValue(repoRoot, userConfigDir, keyArg, rawValue, surface, dependencies);
+        const result = await setConfigValue(repoRoot, userConfigDir, keyArg, rawValue, surface, dependencies, context.logger.warn);
         if (context.json) {
             context.logger.json({
                 status: 'ok',
@@ -1067,12 +1408,42 @@ async function runSet(keyArg, rawValue, surface, context, dependencies) {
         process.exitCode = 1;
     }
 }
+async function runAdopt(templateArg, options, context, dependencies) {
+    try {
+        if (templateArg !== 'dispatch-matrix') {
+            throw new Error(`Unknown config adoption template: ${templateArg}`);
+        }
+        const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
+        const userConfigDir = join(context.home, '.oat');
+        const result = await adoptDispatchMatrixRecommendation(repoRoot, userConfigDir, options, context, dependencies);
+        if (context.json) {
+            context.logger.json({
+                status: 'ok',
+                ...result,
+            });
+        }
+        else {
+            context.logger.info(`Adopted dispatch matrix recommendation ${result.value} to ${result.source} config.`);
+        }
+        process.exitCode = 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (context.json) {
+            context.logger.json({ status: 'error', message });
+        }
+        else {
+            context.logger.error(message);
+        }
+        process.exitCode = 1;
+    }
+}
 async function runList(context, dependencies) {
     try {
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
         const userConfigDir = join(context.home, '.oat');
         const values = [];
-        for (const key of KEY_ORDER) {
+        for (const key of await listConfigKeys(repoRoot, userConfigDir, dependencies)) {
             values.push(await getConfigValue(repoRoot, userConfigDir, key, dependencies));
         }
         if (context.json) {
@@ -1182,6 +1553,44 @@ export function createConfigCommand(overrides = {}) {
             }
             process.exitCode = 1;
         }
+    }))
+        .addCommand(new Command('adopt')
+        .description('Adopt a bundled OAT config recommendation')
+        .argument('<template>', 'Recommendation template to adopt')
+        .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', 'Replace an existing adopted matrix without prompting')
+        .action(async (template, options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        try {
+            const flagsPresent = [
+                options.shared,
+                options.local,
+                options.user,
+            ].filter(Boolean).length;
+            if (flagsPresent > 1) {
+                throw new Error('--shared, --local, and --user flags are mutually exclusive; pass at most one.');
+            }
+            let surface = 'auto';
+            if (options.shared)
+                surface = 'shared';
+            else if (options.local)
+                surface = 'local';
+            else if (options.user)
+                surface = 'user';
+            await runAdopt(template, { surface, yes: options.yes === true }, context, dependencies);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (context.json) {
+                context.logger.json({ status: 'error', message });
+            }
+            else {
+                context.logger.error(message);
+            }
+            process.exitCode = 1;
+        }
     }))
         .addCommand(new Command('list')
         .description('List resolved OAT config values with sources')

package/dist/commands/doctor/index.d.ts

@@ -1,7 +1,8 @@
 import { type CommandContext, type GlobalOptions } from '../../app/command-context.js';
 import { type PjmDoctorOptions } from '../pjm/doctor.js';
-import { type OatConfig } from '../../config/oat-config.js';
+import { type OatConfig, type OatLocalConfig, type UserConfig } from '../../config/oat-config.js';
 import { type Manifest } from '../../manifest/index.js';
+import { type MatrixCellAvailabilityResponse, type ValidateMatrixCellOptions } from '../../providers/identity/availability.js';
 import type { ConcreteScope } from '../../shared/types.js';
 import { type DoctorCheck } from '../../ui/output.js';
 import { Command } from 'commander';
@@ -19,6 +20,10 @@ interface DoctorDependencies {
     readFile: (path: string) => Promise<string>;
     resolveAssetsRoot: () => Promise<string>;
     readOatConfig: (repoRoot: string) => Promise<OatConfig>;
+    readOatLocalConfig: (repoRoot: string) => Promise<OatLocalConfig>;
+    readUserConfig: (userConfigDir: string) => Promise<UserConfig>;
+    validateMatrixCell: (provider: string, value: string, options: ValidateMatrixCellOptions) => Promise<MatrixCellAvailabilityResponse>;
+    processEnv: NodeJS.ProcessEnv;
     runPjmDoctorChecks: (repoRoot: string, options?: PjmDoctorOptions) => Promise<DoctorCheck[]>;
     checkSkillVersions: (scopeRoot: string, assetsRoot: string, pathExists: (path: string) => Promise<boolean>) => Promise<SkillVersionReport>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAInE,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAM9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,KAAK,WAAW,EAAuB,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,UAAU,kBAAkB;IAC1B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,gBAAgB,EAAE,CAChB,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,cAAc,KACpB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1D,mBAAmB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,cAAc,EAAE,CACd,SAAS,EAAE,MAAM,KACd,OAAO,CACV,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CACnE,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,gBAAgB,KACvB,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5B,kBAAkB,EAAE,CAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,KAC3C,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAClC;AAED,UAAU,oBAAoB;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,UAAU,kBAAkB;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,0BAA0B,EAAE,MAAM,CAAC;IACnC,cAAc,EAAE,oBAAoB,EAAE,CAAC;CACxC;AAsbD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,kBAAkB,CAAM,GAC1C,OAAO,CAcT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/index.ts"],"names":[],"mappings":"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"}