akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/core/config/config-sources.js

@@ -3,16 +3,152 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Runtime helpers that derive {@link ConfiguredSource} values from the
- * persisted {@link SourceConfigEntry} / {@link InstalledStashEntry} shapes
+ * persisted {@link SourceConfigEntry} / {@link InstalledBundle} shapes
  * in an {@link AkmConfig}.
  */
 import { createHash } from "node:crypto";
+import path from "node:path";
+import { ConfigError } from "../errors.js";
+/** The current one-component-per-bundle configuration entry, if present. */
+export function bundleComponentConfig(bundle) {
+    if (!bundle?.components)
+        return undefined;
+    const components = Object.values(bundle.components);
+    if (components.length !== 1) {
+        throw new ConfigError("A bundle components map must contain exactly one component.", "INVALID_CONFIG_FILE");
+    }
+    return components[0];
+}
+/**
+ * Convert a `bundles` map (0.9.0 config-shape cutover, spec §10.1 / D-R5) into
+ * the ordered {@link SourceConfigEntry} list the transitional runtime source
+ * resolvers already consume — `defaultBundle` first (primary), then map
+ * insertion order (preserving today's installation-priority semantics, on which
+ * D-R4 short-ref resolution depends). Each entry's `name` IS its bundle key, so
+ * `deriveInstallations` re-derives the exact same installation id (D-R5 rule 1).
+ *
+ * Returns `undefined` for an old-shape config (no `bundles`), so callers fall
+ * back to the pre-cutover `stashDir`/`sources[]`/`installed[]` resolution.
+ */
+/**
+ * The resolved primary stash path — the `defaultBundle`'s filesystem `path`
+ * (spec §10.1) — or `undefined` when no filesystem primary is configured.
+ */
+export function primaryBundlePath(config) {
+    const bundles = config.bundles;
+    const key = config.defaultBundle;
+    if (!bundles || !key)
+        return undefined;
+    const entry = bundles[key];
+    if (!entry || typeof entry.path !== "string" || entry.path.length === 0)
+        return undefined;
+    const componentRoot = bundleComponentConfig(entry)?.root;
+    if (!componentRoot || componentRoot === ".")
+        return entry.path;
+    const bundleRoot = path.resolve(entry.path);
+    const resolved = path.resolve(bundleRoot, componentRoot);
+    const relative = path.relative(bundleRoot, resolved);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new ConfigError(`Component root "${componentRoot}" escapes bundle "${key}".`, "INVALID_CONFIG_FILE");
+    }
+    return resolved;
+}
+export function bundlesToSourceEntries(config) {
+    const bundles = config.bundles;
+    if (!bundles)
+        return undefined;
+    const keys = Object.keys(bundles);
+    const defaultKey = config.defaultBundle && config.defaultBundle in bundles ? config.defaultBundle : undefined;
+    const ordered = defaultKey ? [defaultKey, ...keys.filter((k) => k !== defaultKey)] : keys;
+    const entries = [];
+    for (const key of ordered) {
+        const entry = bundleEntryToSourceEntry(key, bundles[key], key === defaultKey);
+        if (entry)
+            entries.push(entry);
+    }
+    return entries;
+}
+/** Map one `bundles.<key>` entry to a runtime {@link SourceConfigEntry}. */
+export function bundleEntryToSourceEntry(key, bundle, isPrimary = false) {
+    const base = {
+        name: key,
+        ...(bundle.writable !== undefined ? { writable: bundle.writable } : {}),
+        ...(bundle.enabled !== undefined ? { enabled: bundle.enabled } : {}),
+        ...(isPrimary ? { primary: true } : {}),
+    };
+    if (typeof bundle.path === "string" && bundle.path.length > 0) {
+        return { type: "filesystem", path: bundle.path, ...base };
+    }
+    if (typeof bundle.git === "string" && bundle.git.length > 0) {
+        return { type: "git", url: normalizeInstalledGitRef("", bundle.git), ...base };
+    }
+    if (bundle.website && typeof bundle.website.url === "string") {
+        // All non-`url` website-descriptor keys (maxPages/refresh/maxDepth + any
+        // passthrough provider options) round-trip back to the runtime entry's
+        // `options` bag, mirroring the pre-cutover `sources[].options` shape.
+        const { url, ...rest } = bundle.website;
+        return {
+            type: "website",
+            url,
+            ...(Object.keys(rest).length > 0 ? { options: rest } : {}),
+            ...base,
+        };
+    }
+    if (typeof bundle.npm === "string" && bundle.npm.length > 0) {
+        // Today's npm source carries the package spec in `path` (see parseSourceSpec).
+        return { type: "npm", path: bundle.npm, ...base };
+    }
+    return undefined;
+}
+/**
+ * Desired 0.9.0 bundle descriptor for a registry-installed source (spec §10.1).
+ * Maps the install source kind onto the ONE source descriptor a bundle entry
+ * carries: git/github → a provider-ready clone URL, npm → `{ npm: ref }`,
+ * everything else (local/filesystem) → `{ path: stashRoot }`.
+ *
+ * CRITICAL (spec §10.2:453): the materialized cache root NEVER appears in the
+ * descriptor for a git/npm bundle — the desired config carries only the source
+ * descriptor; the install locator stays in `registryId` and the resolved root
+ * belongs exclusively in the lock's `localRoot`. Callers layer
+ * `registryId`/`writable` onto the result.
+ */
+export function installedSourceDescriptor(source, ref, stashRoot) {
+    switch (source) {
+        case "git":
+        case "github":
+            if (ref)
+                return { git: normalizeInstalledGitRef(source, ref) };
+            break;
+        case "npm":
+            if (ref)
+                return { npm: ref };
+            break;
+        default:
+            break;
+    }
+    // local/filesystem installs reference a real on-disk path (no package-manager
+    // cache to re-materialize), so the resolved root IS the desired path.
+    return { path: stashRoot };
+}
+function normalizeInstalledGitRef(source, ref) {
+    if (ref.startsWith("git+"))
+        return ref.slice(4);
+    const isGithubShorthand = ref.startsWith("github:") || (source === "github" && /^[^/:#]+\/[^/#]+(?:#.+)?$/.test(ref));
+    if (!isGithubShorthand)
+        return ref;
+    const body = ref.startsWith("github:") ? ref.slice("github:".length) : ref;
+    const fragmentAt = body.indexOf("#");
+    const repository = fragmentAt >= 0 ? body.slice(0, fragmentAt) : body;
+    const requestedRef = fragmentAt >= 0 ? body.slice(fragmentAt + 1) : "";
+    const cloneUrl = `https://github.com/${repository.replace(/\.git$/i, "")}`;
+    return requestedRef ? `${cloneUrl}/tree/${requestedRef}` : cloneUrl;
+}
 /**
  * Synthesize a stable identifier when a {@link SourceConfigEntry} omits its
  * `name`. Uses a short hash of the discriminating fields so two equivalent
  * entries collapse to the same generated name.
  */
-function deriveStashEntryName(entry) {
+function deriveBundleName(entry) {
     if (entry.name)
         return entry.name;
     const seed = JSON.stringify({
@@ -46,63 +182,50 @@ export function parseSourceSpec(entry) {
         case "npm":
             return entry.path ? { type: "npm", package: entry.path } : undefined;
         default:
-            // Unknown provider — best-effort fallback so callers still get something.
-            return entry.path ? { type: "filesystem", path: entry.path } : undefined;
+            return undefined;
     }
 }
 /**
- * Build the full ordered list of runtime {@link ConfiguredSource} values from
- * a loaded {@link AkmConfig}:
- *   1. The entry marked `primary: true` (or a synthetic entry from `stashDir`).
- *   2. Remaining `sources[]` entries in declared order.
- *   3. Legacy `installed[]` entries, mapped into runtime entries.
+ * Build the full ordered list of runtime {@link ConfiguredSource} values from a
+ * loaded {@link AkmConfig}, resolved from `bundles` + `defaultBundle` (spec
+ * §10.1): the `defaultBundle` (primary) first, then map insertion order. The
+ * retired `stashDir`/`sources[]`/`installed[]` trio is no longer read here — a
+ * pre-cutover config is normalized to bundles by the migrator before it loads.
  *
  * Entries with `enabled: false` are still emitted — callers decide whether to
  * honour the flag. Entries that fail {@link parseSourceSpec} drop silently.
+ * Returns `[]` when no bundles are configured.
  */
 export function resolveConfiguredSources(config) {
-    const entries = [];
-    const sources = config.sources ?? [];
-    let primary = sources.find((entry) => entry.primary === true);
-    if (!primary && config.stashDir) {
-        primary = { type: "filesystem", path: config.stashDir, primary: true };
+    const bundleEntries = bundlesToSourceEntries(config);
+    if (!bundleEntries)
+        return [];
+    const out = [];
+    for (const persisted of bundleEntries) {
+        const runtime = toConfiguredSource(persisted, persisted.primary === true);
+        if (runtime) {
+            const component = bundleComponentConfig(config.bundles?.[persisted.name ?? ""]);
+            out.push({
+                ...runtime,
+                ...(component?.adapter ? { adapterId: component.adapter } : {}),
+                ...(component?.root ? { componentRoot: component.root } : {}),
+                ...(component?.writable !== undefined ? { writable: component.writable } : {}),
+            });
+        }
     }
-    if (primary) {
-        const runtime = toConfiguredSource(primary, true);
-        if (runtime)
-            entries.push(runtime);
-    }
-    for (const entry of sources) {
-        if (entry === primary)
-            continue;
-        const runtime = toConfiguredSource(entry, false);
-        if (runtime)
-            entries.push(runtime);
-    }
-    for (const installed of config.installed ?? []) {
-        entries.push({
-            name: installed.id,
-            type: "filesystem",
-            source: { type: "filesystem", path: installed.stashRoot },
-            enabled: true,
-            writable: installed.writable,
-            ...(installed.wikiName ? { wikiName: installed.wikiName } : {}),
-        });
-    }
-    return entries;
+    return out;
 }
 function toConfiguredSource(persisted, isPrimary) {
     const source = parseSourceSpec(persisted);
     if (!source)
         return undefined;
     return {
-        name: deriveStashEntryName(persisted),
+        name: deriveBundleName(persisted),
         type: persisted.type,
         source,
         ...(persisted.enabled !== undefined ? { enabled: persisted.enabled } : {}),
         ...(persisted.writable !== undefined ? { writable: persisted.writable } : {}),
         ...(isPrimary || persisted.primary ? { primary: true } : {}),
         ...(persisted.options ? { options: persisted.options } : {}),
-        ...(persisted.wikiName ? { wikiName: persisted.wikiName } : {}),
     };
 }

package/dist/core/config/config-types.js

@@ -1,16 +1,21 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-// VALID_HARNESS_IDS now derives from the unified HARNESS_REGISTRY (#562), which
-// is the single source of truth replacing the previously-disconnected
-// registries. config ← harnesses is the only import direction (harnesses/ is a
-// dependency-graph leaf), so there is no cycle.
-import { VALID_HARNESS_IDS } from "../../integrations/harnesses/index.js";
+// VALID_HARNESS_IDS / HARNESS_AGENT_DISPATCH_IDS derive from the dependency-free
+// harnesses/ids.ts leaf (WI-9.8 KILL 3), NOT the full HARNESS_REGISTRY barrel
+// (`../../integrations/harnesses`) — that barrel transitively pulls in every
+// harness's agent-builder and the agent runtime, which is what fused config
+// into the same import-cycle SCC as `integrations/agent/*`. `harnesses/index.ts`
+// asserts at construction time that its registry matches this leaf, so the two
+// cannot silently drift (see `tests/harnesses-registry.test.ts` for the
+// value-level pin). config ← harnesses/ids is the only import direction (the
+// leaf imports nothing), so there is no cycle.
+import { HARNESS_AGENT_DISPATCH_IDS, VALID_HARNESS_IDS } from "../../integrations/harnesses/ids.js";
 /**
- * Canonical list of valid agent harness / platform ids. Re-exported from the
- * unified harness registry (#562) so the Zod `AgentPlatformSchema` enum, the
- * `AgentProfileConfig` platform union, and setup's `DetectedHarness` union all
- * derive from one place and cannot drift. Add a harness in
- * `src/integrations/harnesses/index.ts`.
+ * Canonical list of valid agent harness / platform ids. Derived from the
+ * dependency-free harness-id leaf (#562/WI-9.8) so the Zod `AgentPlatformSchema`
+ * enum, the agent-engine platform union, and setup's `DetectedHarness` union
+ * all derive from one place and cannot drift. Add a harness in
+ * `src/integrations/harnesses/index.ts` (and its `ids.ts` mirror entry).
  */
-export { VALID_HARNESS_IDS };
+export { HARNESS_AGENT_DISPATCH_IDS, VALID_HARNESS_IDS };

package/dist/core/config/config-version.js

@@ -0,0 +1,29 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/** Compare legacy numeric or semver-like config versions for diagnostics only. */
+export function compareConfigVersion(a, b) {
+    const left = normalize(a);
+    const right = normalize(b);
+    if (!left || !right)
+        return undefined;
+    for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+        const l = left[index] ?? 0;
+        const r = right[index] ?? 0;
+        if (l < r)
+            return -1;
+        if (l > r)
+            return 1;
+    }
+    return 0;
+}
+function normalize(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return [0, Math.trunc(value), 0];
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    const parts = value.trim().replace(/^v/i, "").split(/[-+]/, 1)[0].split(".");
+    if (parts.some((part) => !/^\d+$/.test(part)))
+        return undefined;
+    return parts.map(Number);
+}

package/dist/core/config/config-walker.js

@@ -22,7 +22,8 @@
  */
 import { z } from "zod";
 import { UsageError } from "../errors.js";
-import { AkmConfigBaseSchema, listTopLevelConfigKeys } from "./config-schema.js";
+import { AkmConfigBaseSchema, EngineConfigSchema, listTopLevelConfigKeys } from "./config-schema.js";
+import { deepMergeConfig } from "./deep-merge.js";
 /**
  * Parse a dotted path into segments. Empty segments are rejected. Bracket
  * notation (e.g. `sources[0]`) is NOT supported — arrays are set as JSON.
@@ -73,9 +74,10 @@ function unwrap(schema) {
  * AkmConfig schema. Returns `undefined` if any path segment doesn't match a
  * known schema field.
  */
-function resolveSchemaAt(path) {
+function resolveSchemaAt(path, config, raw) {
     let schema = AkmConfigBaseSchema;
-    for (const segment of path) {
+    let existing = config;
+    for (const [index, segment] of path.entries()) {
         schema = unwrap(schema);
         if (schema instanceof z.ZodObject) {
             const next = schema.shape[segment];
@@ -84,23 +86,56 @@ function resolveSchemaAt(path) {
                 const catchall = schema._def.catchall;
                 if (catchall && !(catchall instanceof z.ZodNever)) {
                     schema = catchall;
-                    continue;
                 }
-                return undefined;
+                else {
+                    return undefined;
+                }
+            }
+            else {
+                schema = next;
             }
-            schema = next;
         }
         else if (schema instanceof z.ZodRecord) {
-            // Records (profiles.llm, profiles.agent, profiles.improve, sources, etc.)
+            // Named records (engines, improve.strategies, sources, etc.)
             // accept any string key — descend into the value schema.
             schema = schema._def.valueType;
         }
+        else if (schema instanceof z.ZodUnion) {
+            const option = selectUnionObjectOption(schema._def.options, segment, existing, index === path.length - 1 ? raw : undefined);
+            if (!option)
+                return undefined;
+            schema = option.shape[segment];
+        }
         else {
             // Cannot descend into a non-object schema.
             return undefined;
         }
+        existing = isPlainObject(existing) ? existing[segment] : undefined;
     }
-    return unwrap(schema);
+    // Preserve leaf refinements/transforms for validation. Traversal unwraps at
+    // the start of each loop iteration, while coercion unwraps independently.
+    return schema;
+}
+function selectUnionObjectOption(candidates, segment, existing, raw) {
+    const options = candidates
+        .map((candidate) => unwrap(candidate))
+        .filter((candidate) => candidate instanceof z.ZodObject);
+    if (raw !== undefined) {
+        const requested = options.find((option) => {
+            const leaf = option.shape[segment];
+            if (!leaf || !(unwrap(leaf) instanceof z.ZodLiteral))
+                return false;
+            return leaf.safeParse(coerceForSchema(leaf, raw, segment)).success;
+        });
+        if (requested)
+            return requested;
+    }
+    if (isPlainObject(existing)) {
+        const selected = options.find((option) => Object.entries(option.shape).some(([key, field]) => key in existing && unwrap(field) instanceof z.ZodLiteral && field.safeParse(existing[key]).success));
+        if (selected)
+            return segment in selected.shape ? selected : undefined;
+    }
+    return options.find((option) => segment in option.shape);
 }
 /**
  * Get the value at the dotted path from a config-shaped object. Returns
@@ -109,7 +144,7 @@ function resolveSchemaAt(path) {
  */
 export function configGet(config, dotted) {
     const path = parsePath(dotted);
-    const schema = resolveSchemaAt(path);
+    const schema = resolveSchemaAt(path, config);
     if (!schema) {
         throw new UsageError(`Unknown config key: ${dotted}`, "INVALID_FLAG_VALUE", unknownKeyHint(dotted));
     }
@@ -129,23 +164,38 @@ export function configGet(config, dotted) {
  *
  * Throws {@link UsageError} on:
  *   - unknown path
- *   - apiKey paths (#454)
+ *   - invalid apiKey paths
  *   - coercion failure
  */
 export function configSet(config, dotted, raw) {
     const path = parsePath(dotted);
+    if (path.length === 1 && path[0] === "configVersion") {
+        throw new UsageError("configVersion cannot be changed through config set.", "INVALID_FLAG_VALUE");
+    }
     // #454: apiKey paths are not persistable. Throw at set time.
     rejectApiKeyPath(path, dotted);
-    const schema = resolveSchemaAt(path);
-    if (!schema) {
+    const schema = resolveSchemaAt(path, config, raw);
+    const symbolicApiKey = (path[0] === "engines" && path[2] === "apiKey") ||
+        (path[0] === "embedding" && path.length === 2 && path[1] === "apiKey");
+    if (!schema && !symbolicApiKey) {
         throw new UsageError(`Unknown config key: ${dotted}`, "INVALID_FLAG_VALUE", unknownKeyHint(dotted));
     }
-    const value = coerceForSchema(schema, raw, dotted);
+    const value = path[0] === "engines" && path.length === 2
+        ? parseObjectPatch(raw, dotted)
+        : symbolicApiKey
+            ? raw
+            : coerceForSchema(schema, raw, dotted);
     // Validate the coerced value against the leaf schema. This catches enum
     // mismatches, out-of-range numbers, schema-level shape errors (writable
     // npm/website sources via .superRefine, strict-mode unknown keys in nested
     // objects, etc.) BEFORE we apply the patch.
-    const parsed = schema.safeParse(value);
+    const parsed = path[0] === "engines" && path.length === 2
+        ? EngineConfigSchema.safeParse(value)
+        : symbolicApiKey
+            ? /^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(raw)
+                ? { success: true, data: value }
+                : { success: false, error: { issues: [{ path: [], message: `apiKey must be $VAR or \${VAR}` }] } }
+            : schema.safeParse(value);
     if (!parsed.success) {
         const lines = parsed.error.issues
             .map((i) => {
@@ -155,16 +205,20 @@ export function configSet(config, dotted, raw) {
             .join("\n");
         throw new UsageError(`Invalid value for ${dotted}:\n${lines}`, "INVALID_FLAG_VALUE");
     }
-    const next = setPath(config, path, parsed.data);
-    // Targeted invariant: defaultWriteTarget must point at a configured source
+    const existing = path.reduce((value, key) => {
+        if (value && typeof value === "object")
+            return value[key];
+        return undefined;
+    }, config);
+    const next = setPath(config, path, isPlainObject(existing) && isPlainObject(parsed.data) ? deepMergeConfig(existing, parsed.data) : parsed.data);
+    // Targeted invariant: defaultWriteTarget must point at a configured bundle
     // (#464.a). Whole-config validation happens at save time; this check fires
-    // at set time so the user sees the typo immediately. Empty-sources case is
-    // accepted here (legacy behaviour) — saveConfig will reject if it persists.
+    // at set time so the user sees the typo immediately.
     if (dotted === "defaultWriteTarget" && typeof value === "string") {
-        const sources = next.sources ?? [];
-        const knownNames = sources.map((s) => s.name).filter((n) => typeof n === "string" && n.length > 0);
-        if (knownNames.length > 0 && !knownNames.includes(value)) {
-            throw new UsageError(`Unknown source name "${value}" for defaultWriteTarget; configured source names: ${knownNames.map((n) => `"${n}"`).join(", ")}.`, "INVALID_FLAG_VALUE");
+        const bundles = next.bundles && typeof next.bundles === "object" ? next.bundles : {};
+        const knownNames = Object.keys(bundles);
+        if (!knownNames.includes(value)) {
+            throw new UsageError(`Unknown bundle "${value}" for defaultWriteTarget; configured bundles: ${knownNames.map((n) => `"${n}"`).join(", ") || "none"}.`, "INVALID_FLAG_VALUE");
         }
     }
     return next;
@@ -175,8 +229,11 @@ export function configSet(config, dotted, raw) {
  */
 export function configUnset(config, dotted) {
     const path = parsePath(dotted);
+    if (path.length === 1 && path[0] === "configVersion") {
+        throw new UsageError("configVersion cannot be removed through config unset.", "INVALID_FLAG_VALUE");
+    }
     // Validate the path resolves to a real schema field (so typos don't no-op).
-    const schema = resolveSchemaAt(path);
+    const schema = resolveSchemaAt(path, config);
     if (!schema) {
         throw new UsageError(`Unknown config key: ${dotted}`, "INVALID_FLAG_VALUE", unknownKeyHint(dotted));
     }
@@ -184,12 +241,14 @@ export function configUnset(config, dotted) {
 }
 // ── apiKey rejection (#454) ─────────────────────────────────────────────────
 /**
- * Reject any attempt to persist an apiKey via `akm config set`. Matches:
- *   - `llm.apiKey` (legacy alias mapped to default LLM profile)
- *   - `embedding.apiKey`
- *   - `profiles.llm.<name>.apiKey`
+ * Embedding credentials are never persisted. Engine credentials are symbolic
+ * configuration and are validated by the engine schema below.
  */
 function rejectApiKeyPath(path, dotted) {
+    if (path[0] === "engines" && path[2] === "apiKey")
+        return;
+    if (path[0] === "embedding" && path.length === 2 && path[1] === "apiKey")
+        return;
     const last = path[path.length - 1];
     if (last !== "apiKey")
         return;
@@ -197,14 +256,25 @@ function rejectApiKeyPath(path, dotted) {
     throw new UsageError(`apiKey cannot be persisted in config; export ${recipe} instead. (key: ${dotted})`, "INVALID_FLAG_VALUE", "Storing API keys in config.json leaks them through backups, logs, and version control. " +
         "Use the corresponding environment variable. AKM reads it at request time.");
 }
+function parseObjectPatch(raw, key) {
+    try {
+        const value = JSON.parse(raw);
+        if (!isPlainObject(value))
+            throw new Error("expected an object");
+        return value;
+    }
+    catch (err) {
+        throw new UsageError(`Invalid JSON object for ${key}: ${err instanceof Error ? err.message : String(err)}`, "INVALID_JSON_CONFIG_VALUE");
+    }
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function recipeForApiKey(path, _dotted) {
     if (path[0] === "embedding")
         return "AKM_EMBED_API_KEY";
-    if (path[0] === "llm")
-        return "AKM_LLM_API_KEY";
-    if (path[0] === "profiles" && path[1] === "llm" && typeof path[2] === "string") {
-        const upper = path[2].toUpperCase().replace(/-/g, "_");
-        return `AKM_PROFILE_${upper}_API_KEY (or AKM_LLM_API_KEY for the default profile)`;
+    if (path[0] === "engines" && typeof path[1] === "string") {
+        return `AKM_ENGINE_${path[1].toUpperCase().replaceAll("-", "_")}_API_KEY`;
     }
     return "AKM_LLM_API_KEY / AKM_EMBED_API_KEY";
 }
@@ -237,7 +307,7 @@ function coerceForSchema(schema, raw, key) {
         return raw;
     }
     if (target instanceof z.ZodLiteral) {
-        return target._def.value;
+        return typeof target._def.value === "string" ? raw : target._def.value;
     }
     if (target instanceof z.ZodArray || target instanceof z.ZodObject || target instanceof z.ZodRecord) {
         if (raw === "" || raw === "null")
@@ -290,7 +360,8 @@ function coerceForSchema(schema, raw, key) {
 function setPath(config, path, value) {
     if (path.length === 0)
         return config;
-    const [head, ...rest] = path;
+    const head = path[0]; // non-empty: guarded by the `path.length === 0` check above
+    const rest = path.slice(1);
     const next = { ...config };
     if (rest.length === 0) {
         if (value === undefined) {
@@ -311,7 +382,8 @@ function setPath(config, path, value) {
 function unsetPath(config, path) {
     if (path.length === 0)
         return config;
-    const [head, ...rest] = path;
+    const head = path[0]; // non-empty: guarded by the `path.length === 0` check above
+    const rest = path.slice(1);
     const next = { ...config };
     if (rest.length === 0) {
         delete next[head];
@@ -331,7 +403,24 @@ function unsetPath(config, path) {
     return next;
 }
 // ── Hint generation (#460) ──────────────────────────────────────────────────
-export function unknownKeyHint(_attempted) {
+/**
+ * Per-key "use X instead" guidance for config keys retired before the 0.9
+ * cutover, keyed on the first dotted-path segment. Mitigation item 3: the
+ * generic "valid top-level keys" hint doesn't tell a pre-0.9 user what
+ * replaced the key they typed — this does.
+ */
+const RETIRED_KEY_HINTS = {
+    stashDir: "stashDir was removed in 0.9; get the stash path from `akm config path --all` or `akm info`.",
+    sources: "sources was replaced by bundles in 0.9; run `akm-migrate apply` on a pre-0.9 config to convert it.",
+    installed: "installed was replaced by bundles in 0.9; run `akm-migrate apply` on a pre-0.9 config to convert it.",
+    wikiName: "the wiki subsystem was removed in 0.9; wikis are ordinary knowledge assets now — see `akm import`.",
+    wiki: "the wiki subsystem was removed in 0.9; wikis are ordinary knowledge assets now — see `akm import`.",
+    llm: "llm was replaced by named engines configuration in 0.9; configure `engines` instead.",
+};
+export function unknownKeyHint(attempted) {
     const keys = listTopLevelConfigKeys();
-    return `Valid top-level keys: ${keys.join(", ")}. Use dotted paths for nested values (e.g. embedding.endpoint, profiles.llm.<name>.model).`;
+    const generic = `Valid top-level keys: ${keys.join(", ")}. Use dotted paths for nested values (e.g. embedding.endpoint, engines.<name>.model).`;
+    const firstSegment = attempted.split(".")[0] ?? "";
+    const retiredHint = RETIRED_KEY_HINTS[firstSegment];
+    return retiredHint ? `${retiredHint} ${generic}` : generic;
 }