akm-cli 0.8.0-rc2 → 0.8.1

package/dist/core/config.js

@@ -1,11 +1,60 @@
-import { createHash } from "node:crypto";
+// 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/.
 import fs from "node:fs";
 import path from "node:path";
-import { parseAgentConfig } from "../integrations/agent/config";
-import { asNonEmptyString, filterNonEmptyStrings, writeFileAtomic } from "./common";
+import { backupExistingConfig, parseConfigText, withConfigLock, writeConfigAtomic } from "./config-io";
+import { CURRENT_CONFIG_VERSION, compareConfigVersion, migrateConfigShape } from "./config-migration";
+import { AkmConfigSchema } from "./config-schema";
 import { ConfigError } from "./errors";
+export { stripJsonComments } from "./config-io";
 import { getCacheDir, getConfigPath } from "./paths";
 import { warn } from "./warn";
+// ── Feedback failure-mode constants (F-3 / #384) ────────────────────────────
+/**
+ * Curated taxonomy of failure modes for negative feedback.
+ *
+ * Structured failure modes enable aggregation across feedback events so the
+ * distill pipeline can detect that "5 assets failed for the same reason" and
+ * act on it — free-text strings about the same issue are not aggregatable.
+ */
+export const FEEDBACK_FAILURE_MODES = [
+    "incorrect", // Factually wrong or logically flawed content
+    "outdated", // Correct at some point but now stale
+    "dangerous", // Could cause harm if followed (security, safety)
+    "incomplete", // Missing key steps, context, or caveats
+    "redundant", // Duplicates another asset without adding value
+];
+/**
+ * Default value for {@link IndexPassConfig.graphExtractionBatchSize}. Chosen
+ * empirically: 4 amortises the per-call HTTP overhead 4× while keeping the
+ * combined prompt size well under common 8K/16K context windows (each body is
+ * sliced to ~500 chars in the graph-extract prompt builder).
+ */
+export const DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE = 4;
+/**
+ * Approximate character budget per asset body inside a batched
+ * graph-extraction prompt — used by {@link resolveBatchSize} to derive a
+ * context-window ceiling when `llm.contextLength` is configured. This accounts
+ * for the actual `MAX_BODY_CHARS` (500) in graph-extract.ts plus the system
+ * prompt, user prompt wrapper, and expected JSON response overhead.
+ */
+const GRAPH_EXTRACTION_CHARS_PER_BODY = 1500;
+/**
+ * Clamp a configured batch size against the model's known context window.
+ *
+ * `configured` defaults to {@link DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE} when
+ * `undefined`. When `contextLength` is provided, the result is the smaller of
+ * `configured` and `floor(contextLength / GRAPH_EXTRACTION_CHARS_PER_BODY)`,
+ * with a floor of 1 so the batched path always processes at least one body.
+ */
+export function resolveBatchSize(configured, contextLength) {
+    const base = configured && configured > 0 ? configured : DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE;
+    if (!contextLength || contextLength <= 0)
+        return base;
+    const ceiling = Math.max(1, Math.floor(contextLength / GRAPH_EXTRACTION_CHARS_PER_BODY));
+    return Math.max(1, Math.min(base, ceiling));
+}
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
     semanticSearchMode: "auto",
@@ -18,65 +67,11 @@ export const DEFAULT_CONFIG = {
         detail: "brief",
     },
 };
-// ── Paths ───────────────────────────────────────────────────────────────────
-// ── Private helpers ─────────────────────────────────────────────────────────
-/**
- * Returns `value` if it is a finite positive integer; otherwise `undefined`.
- * Used to validate numeric config fields like `dimension`, `contextLength`,
- * `timeoutMs`, `maxTokens`, and `ollamaOptions.num_ctx`.
- */
-function parsePositiveInteger(_fieldPath, value) {
-    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
-        return undefined;
-    }
-    return value;
-}
-function parseNonNegativeNumber(value) {
-    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
-        return undefined;
-    return value;
-}
-/**
- * Returns `value` if it is a string present in `allowed`; otherwise `undefined`.
- */
-function isOneOf(value, allowed) {
-    return typeof value === "string" && allowed.includes(value);
-}
-/**
- * Validates that `url` starts with `http://` or `https://`. Returns `url` on
- * success and warns+returns `undefined` on failure. `fieldName` is used only
- * in the warning message.
- */
-function isValidHttpUrl(url, fieldName) {
-    if (typeof url !== "string" || !url)
-        return undefined;
-    if (!url.startsWith("http://") && !url.startsWith("https://")) {
-        warn(`[akm] Ignoring ${fieldName}: endpoint must start with http:// or https://, got "${url}"`);
-        return undefined;
-    }
-    return url;
-}
-function clearAllCaches() {
-    cachedConfig = undefined;
-    cachedUserConfig = undefined;
-}
 // ── Load / Save / Update ────────────────────────────────────────────────────
 const PROJECT_CONFIG_RELATIVE_PATH = path.join(".akm", "config.json");
 let cachedConfig;
-let cachedUserConfig;
 export function resetConfigCache() {
-    clearAllCaches();
-}
-function hashString(text) {
-    // Simple, fast non-cryptographic hash (FNV-1a 32-bit) — sufficient to detect
-    // content changes between config writes when filesystem mtime resolution is
-    // too coarse to reflect rapid back-to-back writes (common in tests).
-    let hash = 0x811c9dc5;
-    for (let i = 0; i < text.length; i++) {
-        hash ^= text.charCodeAt(i);
-        hash = Math.imul(hash, 0x01000193);
-    }
-    return (hash >>> 0).toString(16);
+    cachedConfig = undefined;
 }
 export function loadUserConfig() {
     const configPath = getConfigPath();
@@ -85,1048 +80,362 @@ export function loadUserConfig() {
         stat = fs.statSync(configPath);
     }
     catch {
-        cachedUserConfig = undefined;
+        cachedConfig = undefined;
         return applyRuntimeEnvApiKeys({ ...DEFAULT_CONFIG });
     }
-    // Cache key combines mtimeMs + size + content hash. mtimeMs alone is unreliable
-    // when tests write multiple times within the filesystem mtime resolution
-    // window (often 1ms+). Reading + hashing on cache miss is cheap and ensures
-    // we never serve stale config.
+    // Cache key: mtimeMs + size. Tests that write rapidly back-to-back inside
+    // the mtime resolution window MUST call resetConfigCache() between writes —
+    // every public test helper already does.
+    if (cachedConfig &&
+        cachedConfig.path === configPath &&
+        cachedConfig.mtime === stat.mtimeMs &&
+        cachedConfig.size === stat.size) {
+        return cachedConfig.config;
+    }
     let text;
     try {
         text = fs.readFileSync(configPath, "utf8");
     }
     catch {
-        cachedUserConfig = undefined;
+        cachedConfig = undefined;
         return applyRuntimeEnvApiKeys({ ...DEFAULT_CONFIG });
     }
-    const contentHash = hashString(text);
-    if (cachedUserConfig &&
-        cachedUserConfig.path === configPath &&
-        cachedUserConfig.mtime === stat.mtimeMs &&
-        cachedUserConfig.size === stat.size &&
-        cachedUserConfig.contentHash === contentHash) {
-        return cachedUserConfig.config;
+    // Auto-migration: rewrite legacy shapes to disk on cache miss so the schema
+    // sees canonical input. AKM_NO_AUTO_MIGRATE=1 skips the disk rewrite (still
+    // applies in-memory).
+    text = maybeAutoMigrateConfigFile(configPath, text);
+    const finalConfig = applyRuntimeEnvApiKeys(parseAndValidate(text, configPath));
+    // Re-stat after potential write-back so the cache key reflects the new mtime.
+    let finalStat = stat;
+    try {
+        finalStat = fs.statSync(configPath);
+    }
+    catch {
+        // Stat failed — use original stat for cache; no harm done.
     }
-    const config = mergeLoadedConfig(DEFAULT_CONFIG, readNormalizedConfigFromText(text));
-    const finalConfig = applyRuntimeEnvApiKeys(config);
-    cachedUserConfig = {
+    cachedConfig = {
         config: finalConfig,
         path: configPath,
-        mtime: stat.mtimeMs,
-        size: stat.size,
-        contentHash,
+        mtime: finalStat.mtimeMs,
+        size: finalStat.size,
     };
     return finalConfig;
 }
+/**
+ * Parse raw config text, run the legacy-shape migration
+ * ({@link migrateConfigShape}), then validate via Zod
+ * ({@link AkmConfigSchema}). Returns the merged-with-defaults AkmConfig.
+ *
+ * The migration handles all one-time 0.7→0.8 transforms (legacy keys,
+ * boolean→string coercions, openviking rename); the schema then validates
+ * the canonical shape and throws on anything it doesn't recognise.
+ */
+function parseAndValidate(text, sourcePath) {
+    // Migration absorbs 0.7→0.8 input transforms (semanticSearchMode bool→string,
+    // stashes[] → sources[], openviking removal); the schema then sees a
+    // canonical shape. Migration is idempotent on already-migrated input.
+    const migrated = migrateConfigShape(parseConfigText(text, sourcePath)).result;
+    const parsed = AkmConfigSchema.safeParse(migrated);
+    if (!parsed.success) {
+        const lines = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+        const where = sourcePath ? ` at ${sourcePath}` : "";
+        throw new ConfigError(`Invalid config${where}:\n${lines}`, "INVALID_CONFIG_FILE");
+    }
+    return mergeLoadedConfig(DEFAULT_CONFIG, parsed.data);
+}
 export function getSources(config) {
     return config.sources ?? [];
 }
 export function getEffectiveRegistries(config) {
     return config.registries ?? DEFAULT_CONFIG.registries ?? [];
 }
-export function requireLlmConfig(config) {
-    if (!config.llm)
-        throw new ConfigError("LLM is not configured. Run `akm config set llm` to configure one.", "LLM_NOT_CONFIGURED");
-    return config.llm;
-}
-export function loadConfig() {
-    const configPaths = getEffectiveConfigPaths();
-    const signature = getConfigSignature(configPaths);
-    if (cachedConfig && cachedConfig.signature === signature) {
-        return cachedConfig.config;
-    }
-    let config = loadUserConfig();
-    const userConfigPath = getConfigPath();
-    for (const configPath of configPaths) {
-        if (configPath === userConfigPath)
-            continue;
-        config = mergeLoadedConfig(config, readNormalizedConfig(configPath));
-    }
-    const finalConfig = applyRuntimeEnvApiKeys(config);
-    cachedConfig = { config: finalConfig, signature };
-    return finalConfig;
-}
-export function saveConfig(config) {
-    clearAllCaches();
-    const configPath = getConfigPath();
-    const dir = path.dirname(configPath);
-    fs.mkdirSync(dir, { recursive: true });
-    backupExistingConfig(configPath);
-    const sanitized = sanitizeConfigForWrite(config);
-    writeConfigObject(configPath, sanitized);
-}
-function backupExistingConfig(configPath) {
-    if (!fs.existsSync(configPath))
-        return;
-    const backupDir = path.join(getCacheDir(), "config-backups");
-    fs.mkdirSync(backupDir, { recursive: true });
-    const timestamp = new Date().toISOString().replace(/[.:]/g, "-");
-    const backupPath = path.join(backupDir, `config-${timestamp}.json`);
-    fs.copyFileSync(configPath, backupPath);
-    const latestPath = path.join(backupDir, "config.latest.json");
-    fs.copyFileSync(configPath, latestPath);
-}
 /**
- * Strip apiKey fields before writing config to disk.
- * API keys should be provided via environment variables
- * AKM_EMBED_API_KEY and AKM_LLM_API_KEY.
+ * Resolve the name of the default LLM profile.
+ *
+ * Resolution order:
+ *   1. `defaults.llm` — explicit pointer set by the user.
+ *   2. A profile literally named `default` under `profiles.llm` — implicit
+ *      fallback. The convention "name your default profile `default`" is
+ *      what `akm setup` produces, so an unset `defaults.llm` next to a
+ *      `profiles.llm.default` block is overwhelmingly a config-rewrite
+ *      casualty (see [[project_akm_config_clobber_trap]]) rather than
+ *      intent. Treating that shape as configured avoids the silent
+ *      `getDefaultLlmConfig → undefined → pass-returns-zero` failure mode
+ *      that produced 18h of no-op memory-inference runs on 2026-05-23.
+ *
+ * Returns `undefined` when neither path resolves to a profile name.
  */
-function sanitizeConfigForWrite(config) {
-    const sanitized = { ...config };
-    if (config.embedding) {
-        const { apiKey, ...rest } = config.embedding;
-        sanitized.embedding = rest;
-    }
-    if (config.llm) {
-        const { apiKey, ...rest } = config.llm;
-        sanitized.llm = rest;
-    }
-    // Drop empty keys to keep config clean
-    return sanitized;
-}
-export function updateConfig(partial) {
-    const current = loadUserConfig();
-    const merged = mergeLoadedConfig(current, partial);
-    saveConfig(merged);
-    return merged;
+function resolveDefaultLlmProfileName(config) {
+    const explicit = config.defaults?.llm;
+    if (explicit)
+        return explicit;
+    if (config.profiles?.llm?.default)
+        return "default";
+    return undefined;
 }
-// ── Helpers ─────────────────────────────────────────────────────────────────
 /**
- * Normalize a raw config object into a sparse config layer containing only
- * recognized keys that were valid in the source object. This function does not
- * merge with DEFAULT_CONFIG; callers are responsible for layering defaults and
- * combining multiple config sources so project config files only override what
- * they set.
+ * Resolve the default LLM connection from `profiles.llm[defaults.llm]`.
+ *
+ * Throws {@link ConfigError} when no default profile can be resolved (neither
+ * `defaults.llm` nor an implicit `profiles.llm.default`) or when the named
+ * profile does not exist under `profiles.llm`. Use this in code paths that
+ * must have an LLM configured (per-pass index calls, distill, consolidate,
+ * etc).
  */
-function parseConfigLayer(raw) {
-    const config = {};
-    if (typeof raw.stashDir === "string" && raw.stashDir.trim()) {
-        config.stashDir = raw.stashDir.trim();
-    }
-    // Backward compatibility: coerce legacy boolean values to string
-    if (typeof raw.semanticSearchMode === "boolean") {
-        config.semanticSearchMode = raw.semanticSearchMode ? "auto" : "off";
-    }
-    else if (isOneOf(raw.semanticSearchMode, ["off", "auto"])) {
-        config.semanticSearchMode = raw.semanticSearchMode;
-    }
-    const embedding = parseEmbeddingConfig(raw.embedding);
-    if (embedding)
-        config.embedding = embedding;
-    const llm = parseLlmConfig(raw.llm);
-    if (llm)
-        config.llm = llm;
-    const index = parseIndexConfig(raw.index);
-    if (index)
-        config.index = index;
-    const installed = parseInstalledEntries(raw.installed);
-    if (installed)
-        config.installed = installed;
-    const registries = parseRegistriesConfig(raw.registries);
-    if (registries)
-        config.registries = registries;
-    if (isOneOf(raw.stashInheritance, ["replace", "merge"])) {
-        config.stashInheritance = raw.stashInheritance;
-    }
-    if (Array.isArray(raw.stashes)) {
-        throw new ConfigError("The legacy `stashes[]` config key is no longer supported. Rename it to `sources`.", "INVALID_CONFIG_FILE");
-    }
-    const sources = parseSourcesConfig(raw.sources);
-    if (sources) {
-        config.sources = sources;
-    }
-    const security = parseSecurityConfig(raw.security);
-    if (security)
-        config.security = security;
-    const output = parseOutputConfig(raw.output);
-    if (output)
-        config.output = output;
-    if (typeof raw.writable === "boolean") {
-        config.writable = raw.writable;
-    }
-    if (typeof raw.defaultWriteTarget === "string" && raw.defaultWriteTarget.trim()) {
-        config.defaultWriteTarget = raw.defaultWriteTarget.trim();
-    }
-    if ("agent" in raw) {
-        const agent = parseAgentConfig(raw.agent);
-        if (agent)
-            config.agent = agent;
-    }
-    if (typeof raw.search === "object" && raw.search !== null && !Array.isArray(raw.search)) {
-        const searchRaw = raw.search;
-        const searchConfig = {};
-        for (const key of Object.keys(searchRaw)) {
-            if (key !== "minScore" && key !== "graphBoost") {
-                warn(`[akm] Ignoring unknown search key "${key}".`);
-            }
-        }
-        if (typeof searchRaw.minScore === "number" && Number.isFinite(searchRaw.minScore) && searchRaw.minScore >= 0) {
-            searchConfig.minScore = searchRaw.minScore;
-        }
-        if (typeof searchRaw.graphBoost === "object" &&
-            searchRaw.graphBoost !== null &&
-            !Array.isArray(searchRaw.graphBoost)) {
-            const graphBoostRaw = searchRaw.graphBoost;
-            const graphBoostConfig = {};
-            for (const key of Object.keys(graphBoostRaw)) {
-                if (key !== "directBoostPerEntity" &&
-                    key !== "directBoostCap" &&
-                    key !== "hopBoostPerEntity" &&
-                    key !== "hopBoostCap" &&
-                    key !== "maxHops" &&
-                    key !== "confidenceMode" &&
-                    key !== "confidenceWeight") {
-                    warn(`[akm] Ignoring unknown search.graphBoost key "${key}".`);
-                }
-            }
-            const directBoostPerEntity = parseNonNegativeNumber(graphBoostRaw.directBoostPerEntity);
-            if (directBoostPerEntity !== undefined)
-                graphBoostConfig.directBoostPerEntity = directBoostPerEntity;
-            const directBoostCap = parseNonNegativeNumber(graphBoostRaw.directBoostCap);
-            if (directBoostCap !== undefined)
-                graphBoostConfig.directBoostCap = directBoostCap;
-            const hopBoostPerEntity = parseNonNegativeNumber(graphBoostRaw.hopBoostPerEntity);
-            if (hopBoostPerEntity !== undefined)
-                graphBoostConfig.hopBoostPerEntity = hopBoostPerEntity;
-            const hopBoostCap = parseNonNegativeNumber(graphBoostRaw.hopBoostCap);
-            if (hopBoostCap !== undefined)
-                graphBoostConfig.hopBoostCap = hopBoostCap;
-            const maxHops = parsePositiveInteger("search.graphBoost.maxHops", graphBoostRaw.maxHops);
-            if (maxHops !== undefined)
-                graphBoostConfig.maxHops = Math.min(maxHops, 3);
-            if (isOneOf(graphBoostRaw.confidenceMode, ["off", "blend", "multiply"])) {
-                graphBoostConfig.confidenceMode = graphBoostRaw.confidenceMode;
-            }
-            const confidenceWeight = parseNonNegativeNumber(graphBoostRaw.confidenceWeight);
-            if (confidenceWeight !== undefined)
-                graphBoostConfig.confidenceWeight = Math.min(confidenceWeight, 1);
-            if (Object.keys(graphBoostConfig).length > 0)
-                searchConfig.graphBoost = graphBoostConfig;
-        }
-        if (Object.keys(searchConfig).length > 0)
-            config.search = searchConfig;
-    }
-    if (typeof raw.feedback === "object" && raw.feedback !== null && !Array.isArray(raw.feedback)) {
-        const feedbackRaw = raw.feedback;
-        const feedbackConfig = {};
-        if (typeof feedbackRaw.requireReason === "boolean") {
-            feedbackConfig.requireReason = feedbackRaw.requireReason;
-        }
-        if (Object.keys(feedbackConfig).length > 0)
-            config.feedback = feedbackConfig;
-    }
-    if (typeof raw.archiveRetentionDays === "number" &&
-        Number.isFinite(raw.archiveRetentionDays) &&
-        raw.archiveRetentionDays >= 0) {
-        config.archiveRetentionDays = raw.archiveRetentionDays;
-    }
-    return config;
-}
-function parseConfigText(text) {
-    const raw = parseConfigObjectFromText(text);
-    if (!raw)
-        return undefined;
-    const expanded = expandEnvVars(raw);
-    return parseConfigLayer(expanded);
-}
-function readNormalizedConfig(configPath) {
-    let text;
-    try {
-        text = fs.readFileSync(configPath, "utf8");
-    }
-    catch {
-        return undefined;
-    }
-    return parseConfigText(text);
-}
-function readNormalizedConfigFromText(text) {
-    return parseConfigText(text);
-}
-function parseOutputConfig(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return undefined;
-    const obj = value;
-    const output = {};
-    if (isOneOf(obj.format, ["json", "yaml", "text"])) {
-        output.format = obj.format;
+export function requireLlmConfig(config) {
+    const defaultName = resolveDefaultLlmProfileName(config);
+    if (!defaultName) {
+        throw new ConfigError("LLM is not configured. Run `akm setup` or set `defaults.llm` to a profile defined in `profiles.llm`.", "LLM_NOT_CONFIGURED");
     }
-    if (isOneOf(obj.detail, ["brief", "normal", "full"])) {
-        output.detail = obj.detail;
+    const profile = config.profiles?.llm?.[defaultName];
+    if (!profile) {
+        throw new ConfigError(`LLM default profile "${defaultName}" not found in profiles.llm.`, "LLM_NOT_CONFIGURED", `Available profiles: ${Object.keys(config.profiles?.llm ?? {}).join(", ") || "none"}. Run \`akm setup\` to configure.`);
     }
-    return Object.keys(output).length > 0 ? output : undefined;
+    return profile;
 }
 /**
- * Field names that hold URLs and must NOT have env var substitution applied.
- * Expanding ${VAR} inside a URL could leak secrets by redirecting requests to
- * an attacker-controlled server if the config file is world-readable.
+ * Like {@link requireLlmConfig} but returns `undefined` instead of throwing
+ * when no LLM is configured. Use in code paths where the LLM is optional.
  */
-const URL_FIELD_NAMES = new Set(["url", "endpoint", "artifactUrl"]);
+export function getDefaultLlmConfig(config) {
+    const defaultName = resolveDefaultLlmProfileName(config);
+    if (!defaultName)
+        return undefined;
+    return config.profiles?.llm?.[defaultName];
+}
 /**
- * Recursively expand `${VAR}` references in all string values.
- * Supports `${VAR}`, `${VAR:-default}`, and bare `$VAR` at the start of a value.
- * Non-string values pass through unchanged.
+ * Run `migrateConfigShape` on the raw text and — unless `AKM_NO_AUTO_MIGRATE=1`
+ * is set — persist the migrated result. Returns the (possibly migrated) text
+ * for the caller to feed into `parseAndValidate`.
  *
- * URL-type fields (named `url`, `endpoint`, `artifactUrl`, or whose value starts
- * with `http://` / `https://`) are skipped to prevent secret injection into URLs.
+ * If the on-disk config is newer than this binary's known version, the bytes
+ * are left untouched (we won't silently strip fields on downgrade).
  */
-function expandEnvVars(value, fieldName) {
-    if (typeof value === "string") {
-        // Skip URL-type fields by name or by value prefix, unless they contain ${VAR} syntax
-        if (!value.includes("${") &&
-            ((fieldName !== undefined && URL_FIELD_NAMES.has(fieldName)) ||
-                value.startsWith("http://") ||
-                value.startsWith("https://"))) {
-            return value;
-        }
-        return value.replace(/\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => {
-            if (braced) {
-                const [name, ...rest] = braced.split(":-");
-                const fallback = rest.join(":-");
-                return process.env[name] ?? fallback ?? "";
-            }
-            return process.env[bare] ?? "";
-        });
-    }
-    if (Array.isArray(value)) {
-        return value.map((item) => expandEnvVars(item));
-    }
-    if (value !== null && typeof value === "object") {
-        const out = {};
-        for (const [k, v] of Object.entries(value)) {
-            out[k] = expandEnvVars(v, k);
-        }
-        return out;
-    }
-    return value;
-}
-function parseConfigObjectFromText(text) {
+function maybeAutoMigrateConfigFile(configPath, text) {
+    let obj;
     try {
-        const raw = JSON.parse(stripJsonComments(text));
-        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
-            return undefined;
-        return raw;
+        obj = parseConfigText(text);
     }
     catch {
-        return undefined;
+        return text; // Malformed JSON — let parseAndValidate surface the error.
     }
-}
-function writeConfigObject(configPath, config) {
-    writeFileAtomic(configPath, `${JSON.stringify(config, null, 2)}\n`);
-}
-/**
- * Strip JavaScript-style comments from a JSON string (JSONC support).
- * Handles // line comments and /* block comments while preserving
- * comment-like sequences inside quoted strings.
- */
-export function stripJsonComments(text) {
-    let result = "";
-    let i = 0;
-    let inString = false;
-    while (i < text.length) {
-        if (inString) {
-            if (text[i] === "\\") {
-                result += text[i] + (text[i + 1] ?? "");
-                i += 2;
-                continue;
-            }
-            if (text[i] === '"') {
-                inString = false;
-            }
-            result += text[i];
-            i++;
-            continue;
-        }
-        // JSON only uses double-quoted strings; single quotes are not valid JSON
-        if (text[i] === '"') {
-            inString = true;
-            result += text[i];
-            i++;
-            continue;
-        }
-        if (text[i] === "/" && text[i + 1] === "/") {
-            while (i < text.length && text[i] !== "\n")
-                i++;
-            continue;
-        }
-        if (text[i] === "/" && text[i + 1] === "*") {
-            i += 2;
-            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
-                i++;
-            i += 2;
-            continue;
-        }
-        result += text[i];
-        i++;
+    if (compareConfigVersion(obj.configVersion, CURRENT_CONFIG_VERSION) === 1) {
+        return text;
     }
-    return result;
+    const { changed, result } = migrateConfigShape(obj);
+    if (!changed)
+        return text;
+    const migratedText = `${JSON.stringify(result, null, 2)}\n`;
+    if (process.env.AKM_NO_AUTO_MIGRATE === "1")
+        return migratedText;
+    try {
+        withConfigLock(() => {
+            backupExistingConfig(configPath);
+            writeConfigAtomic(configPath, result);
+        });
+        const newVersion = typeof result.configVersion === "string" ? result.configVersion : "0.8.0";
+        const backupDir = `${getCacheDir()}/config-backups`;
+        // WS-2: emit a loud banner to BOTH stderr and stdout so pipelines and
+        // interactive terminals both see it. Include the backup path (resolved,
+        // not ~/...), opt-out env var, and preview diff command.
+        const banner = [
+            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+            `  akm: auto-migrated config → ${newVersion} format`,
+            `  file:   ${configPath}`,
+            `  backup: ${backupDir}/config-<timestamp>.json`,
+            "  to opt out of future auto-migration: AKM_NO_AUTO_MIGRATE=1",
+            "  to preview a dry-run diff:            akm config migrate --dry-run --print-diff",
+            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        ].join("\n");
+        process.stderr.write(`${banner}\n`);
+        process.stdout.write(`${banner}\n`);
+    }
+    catch (err) {
+        // #461: never return migrated bytes when disk write fails — that triggers
+        // an infinite re-migrate loop on every load. Hard-error so the user
+        // notices and either fixes the disk issue or sets AKM_NO_AUTO_MIGRATE=1.
+        throw new ConfigError(`Failed to write migrated config to ${configPath}: ${err instanceof Error ? err.message : String(err)}`, "INVALID_CONFIG_FILE", "Check filesystem permissions, free space, and disk health. To skip auto-migration, set AKM_NO_AUTO_MIGRATE=1.");
+    }
+    return migratedText;
 }
-function parseEmbeddingConfig(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return undefined;
-    const obj = value;
-    // Extract localModel early — it's valid even without a remote endpoint
-    const localModel = typeof obj.localModel === "string" && obj.localModel ? obj.localModel : undefined;
-    // If no endpoint is provided, the config is only valid when localModel is set
-    // (local-only embedding configuration).
-    // Sentinel: { endpoint: "", model: "" } means "local-only" — use hasRemoteEndpoint()
-    // (in embedder.ts) to distinguish from a real remote config. Do NOT check
-    // endpoint/model directly in consuming code.
-    if (typeof obj.endpoint !== "string" || !obj.endpoint) {
-        if (localModel) {
-            return { endpoint: "", model: "", localModel };
-        }
-        return undefined;
-    }
-    if (!isValidHttpUrl(obj.endpoint, "embedding config")) {
-        // Still return localModel-only config if localModel was set
-        if (localModel) {
-            return { endpoint: "", model: "", localModel };
-        }
-        return undefined;
-    }
-    if (typeof obj.model !== "string" || !obj.model) {
-        // No remote model, but localModel may still be valid
-        if (localModel) {
-            warn(`[akm] Embedding endpoint "${obj.endpoint}" ignored: model is required for remote embeddings. Using local model only.`);
-            return { endpoint: "", model: "", localModel };
-        }
-        return undefined;
-    }
-    const result = {
-        endpoint: obj.endpoint,
-        model: obj.model,
-    };
-    if (typeof obj.provider === "string" && obj.provider) {
-        result.provider = obj.provider;
-    }
-    if ("dimension" in obj) {
-        const dim = parsePositiveInteger("embedding.dimension", obj.dimension);
-        if (dim === undefined)
-            return undefined;
-        result.dimension = dim;
-    }
-    if (typeof obj.apiKey === "string" && obj.apiKey) {
-        result.apiKey = obj.apiKey;
-    }
-    if (localModel) {
-        result.localModel = localModel;
-    }
-    if ("contextLength" in obj) {
-        const ctx = parsePositiveInteger("embedding.contextLength", obj.contextLength);
-        if (ctx === undefined)
-            return undefined;
-        result.contextLength = ctx;
-    }
-    if (typeof obj.ollamaOptions === "object" && obj.ollamaOptions !== null && !Array.isArray(obj.ollamaOptions)) {
-        const opts = obj.ollamaOptions;
-        const parsed = {};
-        const numCtx = parsePositiveInteger("embedding.ollamaOptions.num_ctx", opts.num_ctx);
-        if (numCtx !== undefined) {
-            parsed.num_ctx = numCtx;
-        }
-        if (Object.keys(parsed).length > 0) {
-            result.ollamaOptions = parsed;
-        }
-    }
-    return result;
+export function loadConfig() {
+    // Single-layer load: only the user-level config file is read. Project-level
+    // .akm/config.json files discovered under cwd-ancestors emit a one-time
+    // deprecation warning (#457) but are NOT merged.
+    warnIfProjectConfigPresent(process.cwd());
+    return loadUserConfig();
 }
-function parseLlmConfig(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return undefined;
-    const obj = value;
-    if (typeof obj.endpoint !== "string" || !obj.endpoint)
-        return undefined;
-    if (!isValidHttpUrl(obj.endpoint, "llm config")) {
-        return undefined;
-    }
-    if (!obj.endpoint.endsWith("/chat/completions")) {
-        warn(`[akm] llm.endpoint "${obj.endpoint}" does not end in /chat/completions. ` +
-            `Did you mean "${obj.endpoint.replace(/\/+$/, "")}/chat/completions"?`);
-    }
-    const model = typeof obj.model === "string" ? obj.model : "";
-    const result = {
-        endpoint: obj.endpoint,
-        model,
-    };
-    if (typeof obj.provider === "string" && obj.provider) {
-        result.provider = obj.provider;
-    }
-    if (typeof obj.temperature === "number" && Number.isFinite(obj.temperature)) {
-        result.temperature = obj.temperature;
-    }
-    if ("timeoutMs" in obj) {
-        const t = parsePositiveInteger("llm.timeoutMs", obj.timeoutMs);
-        if (t === undefined)
-            return undefined;
-        result.timeoutMs = t;
-    }
-    if ("concurrency" in obj) {
-        const c = parsePositiveInteger("llm.concurrency", obj.concurrency);
-        if (c === undefined)
-            return undefined;
-        result.concurrency = c;
-    }
-    if ("maxTokens" in obj) {
-        const m = parsePositiveInteger("llm.maxTokens", obj.maxTokens);
-        if (m === undefined)
-            return undefined;
-        result.maxTokens = m;
-    }
-    if ("contextLength" in obj) {
-        const ctx = parsePositiveInteger("llm.contextLength", obj.contextLength);
-        if (ctx !== undefined)
-            result.contextLength = ctx;
-    }
-    if (typeof obj.apiKey === "string" && obj.apiKey) {
-        result.apiKey = obj.apiKey;
-    }
-    if (typeof obj.capabilities === "object" && obj.capabilities !== null && !Array.isArray(obj.capabilities)) {
-        const capsRaw = obj.capabilities;
-        const caps = {};
-        if (typeof capsRaw.structuredOutput === "boolean")
-            caps.structuredOutput = capsRaw.structuredOutput;
-        if (Object.keys(caps).length > 0)
-            result.capabilities = caps;
-    }
-    if (typeof obj.features === "object" && obj.features !== null && !Array.isArray(obj.features)) {
-        const features = parseLlmFeatures(obj.features);
-        if (Object.keys(features).length > 0)
-            result.features = features;
-    }
-    if (typeof obj.judgeModel === "string" && obj.judgeModel.trim()) {
-        result.judgeModel = obj.judgeModel.trim();
-    }
-    if (typeof obj.extraParams === "object" && obj.extraParams !== null && !Array.isArray(obj.extraParams)) {
-        result.extraParams = obj.extraParams;
-    }
-    return result;
+export function saveConfig(config) {
+    cachedConfig = undefined;
+    const configPath = getConfigPath();
+    const dir = path.dirname(configPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const sanitized = sanitizeConfigForWrite(config);
+    // Final validation gate before bytes hit disk. Catches schema violations
+    // (unknown keys in registries[] / sources[] / profiles.*; out-of-range
+    // numbers; etc. — closes #462) before we corrupt the user's config.
+    const parseResult = AkmConfigSchema.safeParse(sanitized);
+    if (!parseResult.success) {
+        const lines = parseResult.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+        throw new ConfigError(`Refusing to save invalid config:\n${lines}`, "INVALID_CONFIG_FILE", "Fix the listed fields, or undo the offending `akm config set`. " +
+            "If this looks like an akm bug, re-run with --debug to attach the traceback.");
+    }
+    // WS-3: acquire the config write lock so concurrent `akm config set`
+    // invocations do not interleave their backup+atomic-write cycles.
+    withConfigLock(() => {
+        backupExistingConfig(configPath);
+        writeConfigAtomic(configPath, sanitized);
+    });
 }
 /**
- * v1 spec §14 — locked feature keys. Defined here so unknown keys can
- * be warn-and-ignored at load time (per spec §14.3 / §9.2). The set is
- * deliberately the *full* locked table even though only a subset has
- * runtime parsing today; this lets users author future-flagged configs
- * without spurious warnings.
+ * Strip literal apiKey fields before writing config to disk.
+ * API keys are expected to come from environment variables
+ * (AKM_EMBED_API_KEY, AKM_LLM_API_KEY, AKM_PROFILE_<NAME>_API_KEY).
+ *
+ * `${VAR}` / `$VAR` references are preserved — they are not secrets, they
+ * are deferred lookups resolved at consumption by `resolveSecret`. Dropping
+ * them would break the documented config-on-disk pattern.
+ *
+ * When a non-reference literal value is stripped, emit a `warn()` so the
+ * user knows their key was dropped and how to provide it at runtime (#474).
+ * Previously the strip was silent — a user invoking `akm setup --from <file>
+ * --yes` with an `apiKey` field expected persistence and got a wiped config
+ * with no feedback.
  */
-const LOCKED_LLM_FEATURE_KEYS = new Set([
-    "curate_rerank",
-    "feedback_distillation",
-    "memory_inference",
-    "graph_extraction",
-    "memory_consolidation",
-    "lesson_quality_gate",
-    "metadata_enhance",
-]);
-function parseLlmFeatures(raw) {
-    const out = {};
-    for (const [key, value] of Object.entries(raw)) {
-        if (!LOCKED_LLM_FEATURE_KEYS.has(key)) {
-            warn(`[akm] Ignoring unknown llm.features key "${key}".`);
-            continue;
-        }
-        if (typeof value !== "boolean") {
-            warn(`[akm] Ignoring llm.features.${key}: expected boolean, got ${typeof value}.`);
-            continue;
+function sanitizeConfigForWrite(config) {
+    const sanitized = { ...config };
+    const stripped = [];
+    if (config.embedding?.apiKey !== undefined) {
+        const apiKey = config.embedding.apiKey;
+        if (isEnvReference(apiKey)) {
+            // Preserve reference verbatim — not a secret.
+            sanitized.embedding = { ...config.embedding };
         }
-        if (LOCKED_LLM_FEATURE_KEYS.has(key)) {
-            out[key] = value;
+        else {
+            const { apiKey: _drop, ...rest } = config.embedding;
+            sanitized.embedding = rest;
+            if (apiKey)
+                stripped.push("embedding.apiKey (set AKM_EMBED_API_KEY to provide at runtime)");
         }
     }
-    return out;
-}
-/**
- * Keys that, if present anywhere under `index.<pass>`, indicate the user is
- * trying to supply a parallel LLM provider configuration. Per #208 this is
- * deliberately rejected at load time so there is exactly one place to
- * configure the LLM (`akm.llm`).
- */
-const PROVIDER_CONFIG_KEYS = new Set([
-    "endpoint",
-    "model",
-    "provider",
-    "apiKey",
-    "baseUrl",
-    "temperature",
-    "maxTokens",
-    "capabilities",
-]);
-const GRAPH_EXTRACTION_INCLUDE_TYPES_ALLOWED = new Set([
-    "memory",
-    "knowledge",
-    "skill",
-    "command",
-    "agent",
-    "workflow",
-    "lesson",
-    "task",
-    "wiki",
-]);
-/**
- * Parse the `index` config block. Each entry is a pass name → small object
- * `{ llm?: boolean }`. Anything richer (a parallel provider config, unknown
- * keys, non-boolean `llm`) throws `ConfigError("INVALID_CONFIG_FILE")` at
- * load time so the failure is visible at startup, not on the next index run.
- */
-function parseIndexConfig(value) {
-    if (value === undefined || value === null)
-        return undefined;
-    if (typeof value !== "object" || Array.isArray(value)) {
-        throw new ConfigError('Invalid `index` config: expected an object keyed by pass name (e.g. `{ "enrichment": { "llm": false } }`).', "INVALID_CONFIG_FILE");
+    else if (config.embedding) {
+        sanitized.embedding = { ...config.embedding };
     }
-    const out = {};
-    for (const [passName, raw] of Object.entries(value)) {
-        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-            throw new ConfigError(`Invalid \`index.${passName}\` config: expected an object like \`{ "llm": false }\`.`, "INVALID_CONFIG_FILE");
-        }
-        const passRaw = raw;
-        // Reject any provider-shaped key — there must be exactly one place to
-        // configure the LLM (#208). This is the duplicate-provider guard.
-        for (const key of Object.keys(passRaw)) {
-            if (PROVIDER_CONFIG_KEYS.has(key)) {
-                throw new ConfigError(`Duplicate LLM provider configuration: \`index.${passName}.${key}\` is not allowed. ` +
-                    "Configure provider/model/endpoint under top-level `llm` only; per-pass entries support `{ llm: false }` opt-out.", "INVALID_CONFIG_FILE", 'Move provider settings to the top-level "llm" block, then set `index.<pass>.llm = false` to opt a single pass out.');
-            }
-            if (key !== "llm" &&
-                key !== "graphExtractionBatchSize" &&
-                key !== "graphExtractionIncludeTypes" &&
-                key !== "memoryInferenceBatchSize") {
-                throw new ConfigError(`Unknown key \`index.${passName}.${key}\`. Per-pass entries support \`llm\` (boolean opt-out), \`graphExtractionBatchSize\`, \`graphExtractionIncludeTypes\`, and \`memoryInferenceBatchSize\`.`, "INVALID_CONFIG_FILE");
-            }
-        }
-        const passConfig = {};
-        if ("llm" in passRaw) {
-            const llmFlag = passRaw.llm;
-            if (typeof llmFlag !== "boolean") {
-                throw new ConfigError(`Invalid \`index.${passName}.llm\`: expected a boolean (true to use \`akm.llm\`, false to opt out). Got ${typeof llmFlag}.`, "INVALID_CONFIG_FILE", "Per-pass alternative provider config is intentionally unsupported in v1 (#208). Use `false` to disable LLM for this pass.");
-            }
-            passConfig.llm = llmFlag;
-        }
-        if ("graphExtractionBatchSize" in passRaw) {
-            const n = parsePositiveInteger(`index.${passName}.graphExtractionBatchSize`, passRaw.graphExtractionBatchSize);
-            if (n !== undefined)
-                passConfig.graphExtractionBatchSize = n;
-        }
-        if ("graphExtractionIncludeTypes" in passRaw) {
-            const rawTypes = passRaw.graphExtractionIncludeTypes;
-            if (!Array.isArray(rawTypes) || !rawTypes.every((t) => typeof t === "string" && t.trim().length > 0)) {
-                throw new ConfigError(`Invalid \`index.${passName}.graphExtractionIncludeTypes\`: expected a non-empty string array of asset types.`, "INVALID_CONFIG_FILE");
+    if (config.profiles?.llm) {
+        const llmProfiles = {};
+        for (const [name, profile] of Object.entries(config.profiles.llm)) {
+            if (profile.apiKey !== undefined) {
+                if (isEnvReference(profile.apiKey)) {
+                    llmProfiles[name] = { ...profile };
+                }
+                else {
+                    const { apiKey: _drop, ...rest } = profile;
+                    llmProfiles[name] = rest;
+                    if (profile.apiKey) {
+                        const envVar = `AKM_PROFILE_${name.toUpperCase().replace(/-/g, "_")}_API_KEY`;
+                        stripped.push(`profiles.llm.${name}.apiKey (set ${envVar} to provide at runtime)`);
+                    }
+                }
             }
-            const normalized = rawTypes.map((t) => t.trim().toLowerCase());
-            const invalid = normalized.filter((t) => !GRAPH_EXTRACTION_INCLUDE_TYPES_ALLOWED.has(t));
-            if (invalid.length > 0) {
-                throw new ConfigError(`Invalid \`index.${passName}.graphExtractionIncludeTypes\`: unsupported type(s): ${invalid.join(", ")}.`, "INVALID_CONFIG_FILE");
+            else {
+                llmProfiles[name] = { ...profile };
             }
-            passConfig.graphExtractionIncludeTypes = normalized;
-        }
-        if ("memoryInferenceBatchSize" in passRaw) {
-            const n = parsePositiveInteger(`index.${passName}.memoryInferenceBatchSize`, passRaw.memoryInferenceBatchSize);
-            if (n !== undefined)
-                passConfig.memoryInferenceBatchSize = n;
         }
-        out[passName] = passConfig;
+        sanitized.profiles = {
+            ...(sanitized.profiles ?? {}),
+            llm: llmProfiles,
+        };
     }
-    return out;
+    if (stripped.length > 0) {
+        warn(`Config sanitizer dropped API key(s) before writing to disk:\n  - ${stripped.join("\n  - ")}\n\nakm does not persist API keys to config.json. Set the listed environment variables to provide them at runtime, or use \`\${VAR}\` references in your config to defer lookup. See docs/data-and-telemetry.md.`);
+    }
+    return sanitized;
 }
-function parseInstalledEntries(value) {
-    if (!Array.isArray(value))
-        return undefined;
-    const entries = value
-        .map((entry) => parseInstalledStashEntry(entry))
-        .filter((entry) => entry !== undefined);
-    return entries.length > 0 ? entries : undefined;
+/** Matches `${VAR}`, `${VAR:-default}`, or `$VAR`. */
+function isEnvReference(value) {
+    return /^\$\{[^}]+\}$|^\$[A-Za-z_][A-Za-z0-9_]*$/.test(value);
 }
-function parseInstalledStashEntry(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return undefined;
-    const obj = value;
-    const id = asNonEmptyString(obj.id);
-    const source = asKitSource(obj.source);
-    const ref = asNonEmptyString(obj.ref);
-    const artifactUrl = asNonEmptyString(obj.artifactUrl);
-    const stashRoot = asNonEmptyString(obj.stashRoot);
-    const cacheDir = asNonEmptyString(obj.cacheDir);
-    const installedAt = asNonEmptyString(obj.installedAt);
-    if (!id || !source || !ref || !artifactUrl || !stashRoot || !cacheDir || !installedAt)
-        return undefined;
-    const entry = {
-        id,
-        source,
-        ref,
-        artifactUrl,
-        stashRoot,
-        cacheDir,
-        installedAt,
-    };
-    if (typeof obj.writable === "boolean")
-        entry.writable = obj.writable;
-    if (entry.writable === true && entry.source !== "git") {
-        throw new ConfigError(`writable: true is only supported on filesystem and git sources (got "${entry.source}" on installed entry "${entry.id}").`, "INVALID_CONFIG_FILE", "Remove `writable: true` from the installed entry or re-add it as a git source instead.");
-    }
-    const resolvedVersion = asNonEmptyString(obj.resolvedVersion);
-    if (resolvedVersion)
-        entry.resolvedVersion = resolvedVersion;
-    const resolvedRevision = asNonEmptyString(obj.resolvedRevision);
-    if (resolvedRevision)
-        entry.resolvedRevision = resolvedRevision;
-    const wikiName = asNonEmptyString(obj.wikiName);
-    if (wikiName)
-        entry.wikiName = wikiName;
-    return entry;
+export function updateConfig(partial) {
+    const current = loadUserConfig();
+    const merged = mergeLoadedConfig(current, partial);
+    saveConfig(merged);
+    return merged;
 }
+// ── Helpers ─────────────────────────────────────────────────────────────────
 /**
- * Validate a legacy lockfile/installed-entry source string.
+ * Resolve a single secret value by expanding `${VAR}` / `$VAR` /
+ * `${VAR:-default}` references against `process.env`. Use this at apiKey /
+ * authorization-header consumption sites (LLM client, embedder, agent SDK
+ * runner) — NOT on the load path. Non-string inputs pass through unchanged.
  *
- * Restricted to the four kinds that the install pipeline produces
- * (`"npm" | "github" | "git" | "local"`). The full {@link KitSource} union is
- * wider, but persisted `installed[]` entries should never carry the runtime
- * provider kinds (`"filesystem" | "website"`).
+ * Returns the input unchanged when no substitution markers are present, so
+ * literal API key strings (already-resolved secrets) are zero-cost.
+ *
+ * Other config string values (URLs, endpoints, model names, prompts) are
+ * preserved verbatim on read — only fields explicitly routed through this
+ * helper are expanded.
  */
-function asKitSource(value) {
-    if (value === "npm" || value === "github" || value === "git" || value === "local")
-        return value;
-    return undefined;
-}
-function parseRegistriesConfig(value) {
-    if (!Array.isArray(value))
-        return undefined;
-    const entries = value
-        .map((entry) => parseRegistryConfigEntry(entry))
-        .filter((entry) => entry !== undefined);
-    // Return the array even if empty — an explicit empty array means "no registries"
-    // which overrides the default. Only return undefined if the field was not an array.
-    return entries;
-}
-function parseSourcesConfig(value) {
-    if (!Array.isArray(value))
+export function resolveSecret(value) {
+    if (value === undefined)
         return undefined;
-    const entries = value
-        .map((entry) => parseSourceConfigEntry(entry))
-        .filter((entry) => entry !== undefined);
-    return entries;
-}
-function parseSecurityConfig(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return undefined;
-    const obj = value;
-    const installAudit = parseInstallAuditConfig(obj.installAudit);
-    if (!installAudit)
-        return undefined;
-    return { installAudit };
-}
-function parseInstallAuditConfig(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return undefined;
-    const obj = value;
-    const config = {};
-    if (typeof obj.enabled === "boolean")
-        config.enabled = obj.enabled;
-    if (typeof obj.blockOnCritical === "boolean")
-        config.blockOnCritical = obj.blockOnCritical;
-    if (typeof obj.blockUnlistedRegistries === "boolean")
-        config.blockUnlistedRegistries = obj.blockUnlistedRegistries;
-    const rawAllowlist = filterNonEmptyStrings(obj.registryAllowlist) ?? filterNonEmptyStrings(obj.registryWhitelist);
-    if (!obj.registryAllowlist && obj.registryWhitelist) {
-        warn("[akm] config: `registryWhitelist` is deprecated; rename it to `registryAllowlist`");
-    }
-    if (rawAllowlist) {
-        config.registryAllowlist = rawAllowlist;
-    }
-    const allowedFindings = parseInstallAuditAllowedFindings(obj.allowedFindings);
-    if (allowedFindings) {
-        config.allowedFindings = allowedFindings;
-    }
-    return Object.keys(config).length > 0 ? config : undefined;
-}
-function parseInstallAuditAllowedFindings(value) {
-    if (!Array.isArray(value))
-        return undefined;
-    const findings = value
-        .map((entry) => parseInstallAuditAllowedFinding(entry))
-        .filter((entry) => entry !== undefined);
-    return findings.length > 0 ? findings : undefined;
-}
-function parseInstallAuditAllowedFinding(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return undefined;
-    const obj = value;
-    const id = asNonEmptyString(obj.id);
-    if (!id)
-        return undefined;
-    const finding = { id };
-    const ref = asNonEmptyString(obj.ref);
-    if (ref)
-        finding.ref = ref;
-    const entryPath = asNonEmptyString(obj.path);
-    if (entryPath)
-        finding.path = entryPath;
-    const reason = asNonEmptyString(obj.reason);
-    if (reason)
-        finding.reason = reason;
-    return finding;
-}
-function parseSourceConfigEntry(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return undefined;
-    const obj = value;
-    const type = asNonEmptyString(obj.type);
-    if (!type)
-        return undefined;
-    if (type === "openviking") {
-        const name = asNonEmptyString(obj.name) ?? "unnamed";
-        throw new ConfigError(`openviking is not supported in akm v1. API-backed sources will return as a\nseparate QuerySource tier post-v1. Remove the source named "${name}" from your config file\nor downgrade to 0.6.x. See docs/migration/v1.md.`, "INVALID_CONFIG_FILE", `Run \`akm remove ${name}\` then re-run, or edit your config file directly at ${getConfigPath()} to remove the openviking entry.`);
-    }
-    const entry = { type };
-    const entryPath = asNonEmptyString(obj.path);
-    if (entryPath)
-        entry.path = entryPath;
-    const url = asNonEmptyString(obj.url);
-    if (url)
-        entry.url = url;
-    const name = asNonEmptyString(obj.name);
-    if (name)
-        entry.name = name;
-    if (typeof obj.enabled === "boolean")
-        entry.enabled = obj.enabled;
-    if (typeof obj.writable === "boolean")
-        entry.writable = obj.writable;
-    if (typeof obj.primary === "boolean")
-        entry.primary = obj.primary;
-    // Locked decision 4 (§6 v1 implementation plan): reject writable: true on
-    // website / npm sources at config load. The next sync() would clobber
-    // writes — allowing this is a footgun, not a feature. Throw early so the
-    // user sees the problem at `akm` startup, not when they try to write.
-    if (entry.writable === true && (type === "website" || type === "npm")) {
-        const label = entry.name ? ` "${entry.name}"` : "";
-        throw new ConfigError(`writable: true is only supported on filesystem and git sources (got "${type}" on source${label}).`, "INVALID_CONFIG_FILE", "To author into a checked-out package, add the same path as a separate filesystem source.");
-    }
-    if (typeof obj.options === "object" && obj.options !== null && !Array.isArray(obj.options)) {
-        entry.options = obj.options;
-    }
-    const wikiName = asNonEmptyString(obj.wikiName);
-    if (wikiName)
-        entry.wikiName = wikiName;
-    return entry;
-}
-// ── ConfiguredSource runtime construction ─────────────────────────────────────────
-/**
- * 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) {
-    if (entry.name)
-        return entry.name;
-    const seed = JSON.stringify({
-        type: entry.type,
-        path: entry.path ?? null,
-        url: entry.url ?? null,
+    if (typeof value !== "string")
+        return value;
+    if (!value.includes("$"))
+        return value;
+    return value.replace(/\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => {
+        if (braced) {
+            const [name, ...rest] = braced.split(":-");
+            const fallback = rest.join(":-");
+            return process.env[name] ?? fallback ?? "";
+        }
+        return process.env[bare] ?? "";
     });
-    const hash = createHash("sha256").update(seed).digest("hex").slice(0, 8);
-    return `${entry.type}-${hash}`;
 }
 /**
- * Convert a persisted {@link SourceConfigEntry} into the runtime
- * {@link SourceSpec} discriminated union. Returns `undefined` when the
- * entry is missing the fields its provider type requires (e.g. a
- * `filesystem` entry with no `path`); callers should drop or warn for those.
- *
- * Unknown provider types fall back to `{ type: "filesystem", path: ... }` when
- * a `path` is supplied, so future provider types still produce a usable
- * runtime value.
+ * Read a per-pass {@link IndexPassConfig} entry from {@link IndexConfig},
+ * filtering out the reserved feature-section keys so callers don't mistake
+ * `metadataEnhance` / `stalenessDetection` for a pass.
  */
-export function parseSourceSpec(entry) {
-    switch (entry.type) {
-        case "filesystem":
-            return entry.path ? { type: "filesystem", path: entry.path } : undefined;
-        case "git":
-            return entry.url ? { type: "git", url: entry.url } : undefined;
-        case "website":
-            return entry.url
-                ? {
-                    type: "website",
-                    url: entry.url,
-                    ...(typeof entry.options?.maxPages === "number" ? { maxPages: entry.options.maxPages } : {}),
-                }
-                : undefined;
-        case "npm":
-            // Persisted `npm` stash entries are unusual but supported for symmetry.
-            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;
-    }
-}
-/**
- * Build the full ordered list of runtime {@link ConfiguredSource} values from a
- * loaded {@link AkmConfig}. Order is the canonical iteration order:
- *
- *   1. The entry marked `primary: true` (or, as a backwards-compat shim,
- *      a synthetic filesystem entry built from the top-level `stashDir`).
- *   2. Remaining `sources[]` entries in declared order.
- *   3. Legacy `installed[]` entries, mapped into runtime entries.
- *
- * Entries with `enabled: false` are still emitted — callers decide whether
- * to honour the flag (mirrors how `installed[]` entries have always been
- * unconditional). Entries that fail {@link parseSourceSpec} are
- * dropped silently.
- */
-export function resolveConfiguredSources(config) {
-    const entries = [];
-    const sources = config.sources ?? [];
-    // (1) Primary entry: explicit `primary: true` wins; fall back to top-level stashDir.
-    let primary = sources.find((entry) => entry.primary === true);
-    if (!primary && config.stashDir) {
-        primary = { type: "filesystem", path: config.stashDir, primary: true };
-    }
-    if (primary) {
-        const runtime = toConfiguredSource(primary, true);
-        if (runtime)
-            entries.push(runtime);
-    }
-    // (2) Declared sources (skip the primary entry — already added).
-    for (const entry of sources) {
-        if (entry === primary)
-            continue;
-        const runtime = toConfiguredSource(entry, false);
-        if (runtime)
-            entries.push(runtime);
-    }
-    // (3) Legacy installed[] entries.
-    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;
-}
-function toConfiguredSource(persisted, isPrimary) {
-    const source = parseSourceSpec(persisted);
-    if (!source)
+/** Reserved well-known keys on IndexConfig that are NOT per-pass entries. */
+const INDEX_RESERVED_KEYS = new Set(["metadataEnhance", "stalenessDetection"]);
+export function getIndexPassConfig(config, passName) {
+    if (!config)
         return undefined;
-    return {
-        name: deriveStashEntryName(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 } : {}),
-    };
-}
-function parseRegistryConfigEntry(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
+    if (INDEX_RESERVED_KEYS.has(passName))
         return undefined;
-    const obj = value;
-    const url = asNonEmptyString(obj.url);
-    if (!url?.startsWith("http"))
+    const entry = config[passName];
+    if (!entry || typeof entry !== "object")
         return undefined;
-    const entry = { url };
-    const name = asNonEmptyString(obj.name);
-    if (name)
-        entry.name = name;
-    if (typeof obj.enabled === "boolean")
-        entry.enabled = obj.enabled;
-    const provider = asNonEmptyString(obj.provider);
-    if (provider)
-        entry.provider = provider;
-    if (typeof obj.options === "object" && obj.options !== null && !Array.isArray(obj.options)) {
-        entry.options = obj.options;
-    }
     return entry;
 }
-function mergeAgentConfig(base, override) {
-    const merged = { ...base, ...override };
-    const baseProfiles = base.profiles;
-    const overrideProfiles = override.profiles;
-    if (baseProfiles && overrideProfiles) {
-        const profiles = { ...baseProfiles };
-        for (const [name, entry] of Object.entries(overrideProfiles)) {
-            const existing = baseProfiles[name];
-            profiles[name] = existing ? { ...existing, ...entry } : entry;
-        }
-        merged.profiles = profiles;
-    }
-    // Shallow merge per-key: later layer wins per process name (same as profiles).
-    const baseProcesses = base.processes;
-    const overrideProcesses = override.processes;
-    if (baseProcesses || overrideProcesses) {
-        merged.processes = { ...(baseProcesses ?? {}), ...(overrideProcesses ?? {}) };
-    }
-    return merged;
-}
-function mergeSecurityConfig(base, override) {
-    if (!base && !override)
-        return undefined;
-    const installAudit = mergeInstallAuditConfig(base?.installAudit, override?.installAudit);
-    return installAudit ? { installAudit } : undefined;
-}
-function mergeInstallAuditConfig(base, override) {
-    if (!base && !override)
-        return undefined;
-    const merged = {
-        ...(base ?? {}),
-        ...(override ?? {}),
-    };
-    return Object.values(merged).some((value) => value !== undefined) ? merged : undefined;
-}
+// Re-export source runtime helpers — implementation lives in config-sources.ts.
+export { parseSourceSpec, resolveConfiguredSources } from "./config-sources";
 /**
- * Merge a normalized config layer into an accumulated config.
- *
- * Scalar fields follow normal override semantics. Known nested objects are
- * deep-merged so project config files can override individual fields without
- * clobbering sibling settings. `sources` are additive by default, but a later
- * layer can set `stashInheritance: "replace"` to drop inherited sources first.
+ * Merge a partial user-config override onto a base config. Used by
+ * {@link loadUserConfig} (DEFAULT_CONFIG + on-disk) and {@link updateConfig}
+ * (current config + partial patch). Sub-objects with named records (profiles,
+ * defaults, etc.) shallow-merge; arrays override wholesale.
  */
 function mergeLoadedConfig(base, override) {
     if (!override)
         return { ...base };
-    const merged = {
-        ...base,
-        ...override,
-    };
-    if (base.output && override.output) {
-        merged.output = { ...base.output, ...override.output };
-    }
-    if (base.embedding && override.embedding) {
-        merged.embedding = { ...base.embedding, ...override.embedding };
-    }
-    if (base.llm && override.llm) {
-        merged.llm = { ...base.llm, ...override.llm };
-    }
-    if (base.index || override.index) {
-        // Deep-merge per-pass entries so a project layer can opt one pass out
-        // without dropping siblings configured in user config.
-        const mergedIndex = { ...(base.index ?? {}) };
-        for (const [passName, passOverride] of Object.entries(override.index ?? {})) {
-            mergedIndex[passName] = { ...(mergedIndex[passName] ?? {}), ...passOverride };
+    const merged = { ...base, ...override };
+    // Shallow-merge sub-objects so a partial update to e.g. `output.format`
+    // doesn't drop the existing `output.detail`.
+    for (const key of ["output", "embedding", "index", "defaults"]) {
+        if (base[key] && override[key]) {
+            // biome-ignore lint/suspicious/noExplicitAny: heterogeneous structural merge
+            merged[key] = { ...base[key], ...override[key] };
         }
-        if (Object.keys(mergedIndex).length > 0)
-            merged.index = mergedIndex;
-    }
-    if (base.security && override.security) {
-        merged.security = mergeSecurityConfig(base.security, override.security);
     }
-    if (base.agent && override.agent) {
-        merged.agent = mergeAgentConfig(base.agent, override.agent);
-    }
-    const replaceSources = override.stashInheritance === "replace";
-    const overrideSources = override.sources ?? [];
-    const baseSources = base.sources ?? [];
-    if (replaceSources) {
-        merged.sources = [...overrideSources];
-    }
-    else if (overrideSources.length > 0) {
-        merged.sources = [...baseSources, ...overrideSources];
-    }
-    else if (baseSources.length > 0) {
-        merged.sources = [...baseSources];
+    if (base.profiles && override.profiles) {
+        const next = { ...base.profiles };
+        for (const k of ["llm", "agent", "improve"]) {
+            const ovr = override.profiles[k];
+            if (ovr)
+                next[k] = { ...(next[k] ?? {}), ...ovr };
+        }
+        merged.profiles = next;
     }
     return merged;
 }
@@ -1137,51 +446,51 @@ function applyRuntimeEnvApiKeys(config) {
         if (envKey)
             next.embedding = { ...next.embedding, apiKey: envKey };
     }
-    if (next.llm && !next.llm.apiKey) {
-        const envKey = process.env.AKM_LLM_API_KEY?.trim();
-        if (envKey)
-            next.llm = { ...next.llm, apiKey: envKey };
+    // LLM profile keys: AKM_LLM_API_KEY for the default profile, then
+    // AKM_PROFILE_<UPPER>_API_KEY for any profile (per-profile wins).
+    const defaultProfile = next.defaults?.llm;
+    if (next.profiles?.llm) {
+        const updated = { ...next.profiles.llm };
+        let changed = false;
+        for (const [name, profile] of Object.entries(updated)) {
+            if (profile.apiKey)
+                continue;
+            const perProfile = process.env[`AKM_PROFILE_${name.toUpperCase().replace(/-/g, "_")}_API_KEY`]?.trim();
+            const fallback = name === defaultProfile ? process.env.AKM_LLM_API_KEY?.trim() : undefined;
+            const envKey = perProfile || fallback;
+            if (envKey) {
+                updated[name] = { ...profile, apiKey: envKey };
+                changed = true;
+            }
+        }
+        if (changed)
+            next.profiles = { ...next.profiles, llm: updated };
     }
     return next;
 }
 /**
- * Return config file paths in merge order: user config first, then project
- * config files from the outermost parent directory down to the current working
- * directory. Later entries have higher precedence when merged.
- */
-function getEffectiveConfigPaths() {
-    const configPath = getConfigPath();
-    const paths = [];
-    if (isFile(configPath)) {
-        paths.push(configPath);
-    }
-    return [...paths, ...discoverProjectConfigPaths(process.cwd())];
-}
-/**
- * Walk from `startDir` up to the filesystem root and collect `.akm/config.json`
- * files. Paths are returned from outermost parent to innermost directory so
- * nearer project directories override broader project settings.
+ * Walk cwd-ancestors looking for `.akm/config.json`. If one is found, emit a
+ * one-time deprecation warning per path. The file's contents are NOT read —
+ * multi-layer project config was removed in this release; the warning stays
+ * for one cycle so users notice they have a now-dead file on disk and can
+ * migrate its settings to the user-level config.
  */
-function discoverProjectConfigPaths(startDir) {
-    const paths = [];
+const PROJECT_CONFIG_DEPRECATION_WARNED = new Set();
+function warnIfProjectConfigPresent(startDir) {
     let currentDir = path.resolve(startDir);
     while (true) {
         const configPath = path.join(currentDir, PROJECT_CONFIG_RELATIVE_PATH);
-        if (isFile(configPath)) {
-            paths.unshift(configPath);
+        if (isFile(configPath) && !PROJECT_CONFIG_DEPRECATION_WARNED.has(configPath)) {
+            PROJECT_CONFIG_DEPRECATION_WARNED.add(configPath);
+            warn(`[akm] DEPRECATED: project-level config file found at ${configPath}. ` +
+                "Project-level config files are no longer merged (removed after 0.8.x deprecation). " +
+                "Move any needed settings to ~/.config/akm/config.json; this file is ignored.");
         }
         const parentDir = path.dirname(currentDir);
-        if (parentDir === currentDir) {
+        if (parentDir === currentDir)
             break;
-        }
         currentDir = parentDir;
     }
-    return paths;
-}
-function getConfigSignature(configPaths) {
-    if (configPaths.length === 0)
-        return "defaults";
-    return configPaths.map((configPath) => `${configPath}:${getFileSignatureToken(configPath)}`).join("|");
 }
 function isFile(filePath) {
     try {
@@ -1191,23 +500,3 @@ function isFile(filePath) {
         return false;
     }
 }
-function getFileSignatureToken(filePath) {
-    try {
-        const stat = fs.statSync(filePath);
-        // mtimeMs alone is unreliable on filesystems with low-resolution mtime
-        // (HFS+, some network FS, or very fast back-to-back writes in tests).
-        // Combine mtime + size + content hash so the signature actually changes
-        // when content does.
-        let contentHash = "";
-        try {
-            contentHash = hashString(fs.readFileSync(filePath, "utf8"));
-        }
-        catch {
-            // ignore — fall back to stat-only signature
-        }
-        return `${stat.mtimeMs}:${stat.size}:${contentHash}`;
-    }
-    catch {
-        return "missing";
-    }
-}