akm-cli 0.8.0-rc1 → 0.8.0

package/dist/setup/setup.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Interactive configuration wizard for akm.
  *
@@ -5,23 +8,147 @@
  * registry selection, stash sources, and agent platform discovery.
  * Collects all choices and writes config once at the end.
  */
+import { promises as dnsPromises } from "node:dns";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import * as p from "@clack/prompts";
 import { akmInit } from "../commands/init";
 import { isHttpUrl } from "../core/common";
-import { DEFAULT_CONFIG, loadUserConfig, saveConfig } from "../core/config";
-import { getConfigPath, getDefaultStashDir } from "../core/paths";
+import { DEFAULT_CONFIG, getDefaultLlmConfig, loadUserConfig, saveConfig } from "../core/config";
+import { ConfigError } from "../core/errors";
+import { assertSafeStashDir, getConfigPath, getDefaultStashDir, isTransientStashPath } from "../core/paths";
 import { warn } from "../core/warn";
 import { closeDatabase, isVecAvailable, openDatabase } from "../indexer/db";
 import { akmIndex } from "../indexer/indexer";
 import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "../indexer/semantic-status";
-import { detectAgentCliProfiles, pickDefaultAgentProfile, } from "../integrations/agent";
+import { detectAgentCliProfiles, pickDefaultAgentProfile } from "../integrations/agent";
 import { probeLlmCapabilities } from "../llm/client";
 import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "../llm/embedder";
 import { detectAgentPlatforms, detectOllama } from "./detect";
 import { createSetupContext, runSetupSteps } from "./steps";
+// ── Setup sandbox guard ─────────────────────────────────────────────────────
+/**
+ * Refuse to persist an explicit `--dir /tmp/...` stashDir to the user's
+ * config. The OS may reap the directory at any time, and the next run will
+ * see a `stashDir` that points at a deleted path (falling back to ~/akm
+ * silently). Mirrors the `assertInitSandbox` check in commands/init.ts, but
+ * fires under all runtimes (not just `bun test`) because `akm setup --dir
+ * /tmp/X` is a documented isolation pattern that has been observed to
+ * silently clobber the host config — see
+ * `docs/technical/incidents/2026-05-23-setup-clobbers-user-config.md`.
+ *
+ * Escape hatch: set `AKM_FORCE_SETUP_TMP_STASH=1` to override. When the
+ * escape hatch is on, `applyStashIsolationToEnv` below also pre-sets
+ * `AKM_STASH_DIR` so that the `getConfigDir` / `getCacheDir` isolation
+ * rules fire and config + cache writes route into `$stashDir/.akm/`
+ * instead of the user's host `~/.config/akm`.
+ */
+function assertSetupSandbox(stashDir, dirExplicitlyProvided) {
+    if (!dirExplicitlyProvided)
+        return;
+    if (process.env.AKM_FORCE_SETUP_TMP_STASH === "1")
+        return;
+    if (!isTransientStashPath(stashDir))
+        return;
+    throw new ConfigError(`refusing to run \`akm setup --dir ${stashDir}\`: the path is in a transient/sandbox directory family the OS may reap. ` +
+        "Persisting it as the user's stashDir would leave the next run pointing at a deleted path (silently falling back to ~/akm). " +
+        "Use a persistent directory, OR set AKM_FORCE_SETUP_TMP_STASH=1 if you intentionally want a sandbox setup " +
+        "(setup will also auto-isolate config + cache writes into $stashDir/.akm/ so the host config is preserved).", "SETUP_TMP_STASH_REFUSED");
+}
+/**
+ * Propagate the explicit `--dir <stashDir>` choice to the env so that the
+ * `getConfigDir` / `getCacheDir` isolation rules in `src/core/paths.ts`
+ * actually fire for the duration of this setup run. Without this, a CLI
+ * caller who passes `--dir /tmp/X` but doesn't pre-export `AKM_STASH_DIR`
+ * would still write config to the host `~/.config/akm/config.json`. We
+ * only set the env var when:
+ *   - `--dir` was explicitly provided (we have an operator-stated stash), AND
+ *   - `AKM_STASH_DIR` is not already set (caller's explicit env wins).
+ * The set is process-wide; for the CLI that's the right scope (the process
+ * is about to do all its work against this stash). For tests, each test
+ * already isolates env via beforeEach/afterEach so there is no leak.
+ */
+function applyStashIsolationToEnv(stashDir, dirExplicitlyProvided) {
+    if (!dirExplicitlyProvided)
+        return;
+    if (process.env.AKM_STASH_DIR?.trim())
+        return;
+    process.env.AKM_STASH_DIR = stashDir;
+}
+/** Read the currently-configured LLM connection from a loaded config. */
+function getCurrentLlm(config) {
+    return getDefaultLlmConfig(config);
+}
+/** Read a synthesised legacy-shape agent block from the new-shape AkmConfig. */
+function getCurrentAgentBlock(config) {
+    if (!config.profiles?.agent && !config.defaults?.agent)
+        return undefined;
+    const block = {};
+    if (config.defaults?.agent)
+        block.default = config.defaults.agent;
+    if (config.profiles?.agent) {
+        const profiles = {};
+        for (const [name, raw] of Object.entries(config.profiles.agent)) {
+            profiles[name] = {
+                ...(raw.platform === "opencode-sdk" ? { sdkMode: true } : {}),
+                ...(raw.model ? { model: raw.model } : {}),
+                ...(raw.bin ? { bin: raw.bin } : {}),
+                ...(raw.args ? { args: raw.args } : {}),
+            };
+        }
+        block.profiles = profiles;
+    }
+    return block;
+}
+/** Apply an LLM connection patch onto the new-shape config. */
+function applyLegacyLlm(config, llm) {
+    if (!llm) {
+        // Clear the default LLM profile.
+        const name = config.defaults?.llm ?? "default";
+        const remaining = { ...(config.profiles?.llm ?? {}) };
+        delete remaining[name];
+        return {
+            profiles: { ...(config.profiles ?? {}), llm: remaining },
+            defaults: { ...(config.defaults ?? {}), llm: undefined },
+        };
+    }
+    const name = config.defaults?.llm ?? "default";
+    return {
+        profiles: {
+            ...(config.profiles ?? {}),
+            llm: { ...(config.profiles?.llm ?? {}), [name]: llm },
+        },
+        defaults: { ...(config.defaults ?? {}), llm: name },
+    };
+}
+/** Apply a legacy-shape agent block onto the new-shape config. */
+function applyLegacyAgent(config, agent) {
+    if (!agent) {
+        return {
+            profiles: { ...(config.profiles ?? {}), agent: undefined },
+            defaults: { ...(config.defaults ?? {}), agent: undefined },
+        };
+    }
+    const v2Profiles = { ...(config.profiles?.agent ?? {}) };
+    for (const [name, profile] of Object.entries(agent.profiles ?? {})) {
+        const platform = profile.sdkMode
+            ? "opencode-sdk"
+            : name.toLowerCase().includes("claude")
+                ? "claude"
+                : "opencode";
+        v2Profiles[name] = {
+            platform,
+            ...(profile.bin ? { bin: profile.bin } : {}),
+            ...(profile.args ? { args: profile.args } : {}),
+            ...(profile.model ? { model: profile.model } : {}),
+        };
+    }
+    return {
+        profiles: { ...(config.profiles ?? {}), agent: v2Profiles },
+        defaults: { ...(config.defaults ?? {}), agent: agent.default },
+    };
+}
 /**
  * Recommended GitHub repositories shown during setup.
  */
@@ -122,7 +249,6 @@ function cloneLlmConfig(llm) {
     return {
         ...llm,
         ...(llm.capabilities ? { capabilities: { ...llm.capabilities } } : {}),
-        ...(llm.features ? { features: { ...llm.features } } : {}),
         ...(llm.extraParams ? { extraParams: { ...llm.extraParams } } : {}),
     };
 }
@@ -202,15 +328,27 @@ async function stepAdditionalSources(currentSources) {
     return sources;
 }
 /**
- * Quick connectivity check. Returns true if we can reach a public
- * endpoint within 3 seconds, false otherwise. Used to skip network-
- * dependent setup steps gracefully when offline.
+ * Quick connectivity check. Returns true if we can resolve a hostname
+ * the user has already implicitly trusted within 3 seconds, false
+ * otherwise. Used to skip network-dependent setup steps gracefully
+ * when offline.
+ *
+ * We use a DNS lookup against `github.com` rather than an HTTP request
+ * because (1) it doesn't actually send a request to anyone we aren't
+ * already talking to (the user got akm from GitHub and `akm upgrade`
+ * polls api.github.com), and (2) DNS is the right layer for "do we have
+ * working network" without making the user opt into yet another remote.
+ * The previous implementation pinged https://dns.google which
+ * contradicted the spirit of "no remote endpoints akm doesn't own."
  *
  * @internal Exported for testing only.
  */
 export async function isOnline() {
     try {
-        await fetch("https://dns.google", { signal: AbortSignal.timeout(3000) });
+        await Promise.race([
+            dnsPromises.lookup("github.com"),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("dns lookup timed out")), 3000).unref()),
+        ]);
         return true;
     }
     catch {
@@ -358,6 +496,14 @@ async function stepStashDir(current, options) {
         validate: (v) => {
             if (!v?.trim())
                 return "Path cannot be empty";
+            try {
+                assertSafeStashDir(v.trim());
+            }
+            catch (err) {
+                if (err instanceof Error)
+                    return err.message;
+                return "Refused: unsafe stash directory";
+            }
         },
     }));
     return customPath.trim();
@@ -492,21 +638,22 @@ export async function stepLlm(current, ollamaEndpoint, ollamaChatModels) {
     }
     options.push({ value: "custom", label: "Custom OpenAI-compatible endpoint" });
     options.push({ value: "none", label: "Skip LLM", hint: "no metadata enhancement during indexing" });
-    if (current.llm) {
+    const currentLlm = getCurrentLlm(current);
+    if (currentLlm) {
         options.push({
             value: "keep",
-            label: `Keep current: ${current.llm.provider ?? current.llm.endpoint}`,
-            hint: current.llm.model,
+            label: `Keep current: ${currentLlm.provider ?? currentLlm.endpoint}`,
+            hint: currentLlm.model,
         });
     }
-    const initialValue = current.llm ? "keep" : ollamaAvailable ? "ollama" : (LLM_PRESETS[0]?.value ?? "none");
+    const initialValue = currentLlm ? "keep" : ollamaAvailable ? "ollama" : (LLM_PRESETS[0]?.value ?? "none");
     const choice = await prompt(() => p.select({
         message: "Configure an LLM for richer metadata during indexing:",
         options,
         initialValue,
     }));
     if (choice === "keep")
-        return cloneLlmConfig(current.llm);
+        return cloneLlmConfig(currentLlm);
     if (choice === "none")
         return undefined;
     let llm;
@@ -768,21 +915,22 @@ export async function stepSmallModelConnection(current) {
         });
     }
     providerOptions.push({ value: "openai", label: "OpenAI", hint: "requires AKM_LLM_API_KEY" }, { value: "lmstudio", label: "LM Studio / local server", hint: "http://localhost:1234" }, { value: "custom", label: "Custom OpenAI-compatible endpoint" }, { value: "skip", label: "Skip — disable enrichment features" });
-    if (current.llm) {
+    const currentLlmSmall = getCurrentLlm(current);
+    if (currentLlmSmall) {
         providerOptions.push({
             value: "keep",
-            label: `Keep current: ${current.llm.provider ?? current.llm.endpoint}`,
-            hint: current.llm.model,
+            label: `Keep current: ${currentLlmSmall.provider ?? currentLlmSmall.endpoint}`,
+            hint: currentLlmSmall.model,
         });
     }
-    const initialValue = current.llm ? "keep" : ollama.available ? "ollama" : "openai";
+    const initialValue = currentLlmSmall ? "keep" : ollama.available ? "ollama" : "openai";
     const providerChoice = await prompt(() => p.select({
         message: "Provider:",
         options: providerOptions,
         initialValue,
     }));
     if (providerChoice === "keep") {
-        return { llm: cloneLlmConfig(current.llm), skipped: false, ollamaEndpoint };
+        return { llm: cloneLlmConfig(currentLlmSmall), skipped: false, ollamaEndpoint };
     }
     if (providerChoice === "skip") {
         p.note([
@@ -934,11 +1082,12 @@ export async function stepAgentConnection(current, smallModel) {
     p.note([
         "This connection is used for agentic commands:",
         "  • akm propose   (generate improvement proposals)",
-        "  • akm reflect   (reflect on assets and generate proposals)",
+        "  • akm improve   (run the reflect/distill/consolidate self-improvement pipeline)",
         "  • akm tasks run (run automated task prompts)",
     ].join("\n"));
     // Detect available CLI agents.
-    const detections = detectAgentCliProfiles(current.agent);
+    const detections = detectAgentCliProfiles(current);
+    const currentAgentBlock = getCurrentAgentBlock(current);
     const availableClis = detections.filter((d) => d.available);
     const agentOptions = [];
     if (!smallModel.skipped && smallModel.llm) {
@@ -957,15 +1106,15 @@ export async function stepAgentConnection(current, smallModel) {
         });
     }
     agentOptions.push({ value: "none", label: "None — disable agentic features" });
-    if (current.agent) {
-        const currentDesc = current.agent.default
-            ? `CLI: ${current.agent.default}`
-            : current.agent.profiles?.default?.model
-                ? `SDK: ${current.agent.profiles.default.model}`
+    if (currentAgentBlock) {
+        const currentDesc = currentAgentBlock.default
+            ? `CLI: ${currentAgentBlock.default}`
+            : currentAgentBlock.profiles?.default?.model
+                ? `SDK: ${currentAgentBlock.profiles.default.model}`
                 : "configured";
         agentOptions.push({ value: "keep", label: `Keep current: ${currentDesc}` });
     }
-    const initialAgentValue = current.agent
+    const initialAgentValue = currentAgentBlock
         ? "keep"
         : availableClis.length > 0 && smallModel.skipped
             ? "cli-agent"
@@ -980,13 +1129,13 @@ export async function stepAgentConnection(current, smallModel) {
         initialValue: initialAgentValue,
     }));
     if (agentChoice === "keep") {
-        return current.agent;
+        return currentAgentBlock;
     }
     if (agentChoice === "none") {
         p.note([
             "Agentic features disabled:",
             '  • akm propose — will show "no agent configured" error',
-            '  • akm reflect — will show "no agent configured" error',
+            '  • akm improve — will show "no agent configured" error',
             '  • akm tasks run — will show "no agent configured" error',
             "",
             "You can configure this later with `akm setup`.",
@@ -1008,11 +1157,11 @@ export async function stepAgentConnection(current, smallModel) {
             }));
             const profileName = smallModel.llm.provider ?? "default";
             return {
-                ...(current.agent ?? {}),
+                ...(currentAgentBlock ?? {}),
                 profiles: {
-                    ...(current.agent?.profiles ?? {}),
+                    ...(currentAgentBlock?.profiles ?? {}),
                     [profileName]: {
-                        ...(current.agent?.profiles?.[profileName] ?? {}),
+                        ...(currentAgentBlock?.profiles?.[profileName] ?? {}),
                         sdkMode: true,
                         model: agentModel.trim(),
                         endpoint: smallModel.llm.endpoint,
@@ -1025,9 +1174,9 @@ export async function stepAgentConnection(current, smallModel) {
     if (agentChoice === "cli-agent") {
         if (availableClis.length === 0) {
             p.log.warn("No agent CLIs detected on PATH.");
-            return current.agent;
+            return currentAgentBlock;
         }
-        const initialCli = pickDefaultAgentProfile(detections, current.agent?.default) ?? availableClis[0]?.name;
+        const initialCli = pickDefaultAgentProfile(detections, currentAgentBlock?.default) ?? availableClis[0]?.name;
         const selectedCli = await prompt(() => p.select({
             message: "Which CLI agent?",
             options: availableClis.map((d) => ({
@@ -1038,7 +1187,7 @@ export async function stepAgentConnection(current, smallModel) {
             initialValue: initialCli,
         }));
         return {
-            ...(current.agent ?? {}),
+            ...(currentAgentBlock ?? {}),
             default: selectedCli,
         };
     }
@@ -1069,9 +1218,9 @@ export async function stepAgentConnection(current, smallModel) {
         ...(newApiKeyInput?.trim() ? { apiKey: newApiKeyInput.trim() } : {}),
     };
     return {
-        ...(current.agent ?? {}),
+        ...(currentAgentBlock ?? {}),
         profiles: {
-            ...(current.agent?.profiles ?? {}),
+            ...(currentAgentBlock?.profiles ?? {}),
             custom: customProfile,
         },
         default: "custom",
@@ -1090,19 +1239,20 @@ function printCapabilitySummary(smallModelSkipped, agentConfigured) {
         lines.push("  ✗ akm index, akm distill, akm remember — run `akm setup` to enable");
     }
     if (agentConfigured) {
-        lines.push("  ✓ akm propose, akm reflect, akm tasks — agent configured");
+        lines.push("  ✓ akm propose, akm improve, akm tasks — agent configured");
     }
     else {
-        lines.push("  ✗ akm propose, akm reflect, akm tasks — run `akm setup` to enable");
+        lines.push("  ✗ akm propose, akm improve, akm tasks — run `akm setup` to enable");
     }
     p.note(lines.join("\n"), "Feature Summary");
 }
 export async function stepAgentSelection(current, detections) {
+    const currentAgentBlock = getCurrentAgentBlock(current);
     const available = detections.filter((d) => d.available);
     if (available.length === 0) {
-        return current.agent;
+        return currentAgentBlock;
     }
-    const initialValue = pickDefaultAgentProfile(detections, current.agent?.default) ?? available[0]?.name;
+    const initialValue = pickDefaultAgentProfile(detections, currentAgentBlock?.default) ?? available[0]?.name;
     const selectedDefault = await prompt(() => p.select({
         message: "Which detected agent CLI should be the default?",
         options: [
@@ -1116,16 +1266,16 @@ export async function stepAgentSelection(current, detections) {
         initialValue,
     }));
     if (selectedDefault === "disabled") {
-        if (!current.agent?.profiles && !current.agent?.timeoutMs) {
+        if (!currentAgentBlock?.profiles && !currentAgentBlock?.timeoutMs) {
             return undefined;
         }
         return {
-            ...(current.agent ?? {}),
+            ...(currentAgentBlock ?? {}),
             default: undefined,
         };
     }
     return {
-        ...(current.agent ?? {}),
+        ...(currentAgentBlock ?? {}),
         default: selectedDefault,
     };
 }
@@ -1162,14 +1312,15 @@ export async function stepOutputConfig(current) {
  * @internal Exported for testing only.
  */
 export function stepAgentCliDetection(current, detectFn = detectAgentCliProfiles) {
-    const detections = detectFn(current.agent);
-    const defaultName = pickDefaultAgentProfile(detections, current.agent?.default);
+    const detections = detectFn(current);
+    const currentAgentBlock = getCurrentAgentBlock(current);
+    const defaultName = pickDefaultAgentProfile(detections, currentAgentBlock?.default);
     // No installed agents found and no existing config → leave block absent.
-    if (!defaultName && !current.agent) {
+    if (!defaultName && !currentAgentBlock) {
         return { detections };
     }
     const agent = {
-        ...(current.agent ?? {}),
+        ...(currentAgentBlock ?? {}),
         ...(defaultName ? { default: defaultName } : {}),
     };
     return { agent, detections };
@@ -1221,11 +1372,10 @@ export function buildSetupSteps(options) {
             label: "LLM Provider",
             async run(ctx) {
                 if (!options.online) {
-                    ctx.apply({ llm: ctx.config.llm });
                     return;
                 }
                 const llm = await stepLlm(ctx.config, ollamaEndpoint, ollamaChatModels);
-                ctx.apply({ llm });
+                ctx.apply(applyLegacyLlm(ctx.config, llm));
             },
         },
         {
@@ -1273,8 +1423,11 @@ export function buildSetupSteps(options) {
                 else {
                     p.log.info("No agent CLIs detected on PATH. Agent commands will be disabled until one is installed and `akm setup` is re-run.");
                 }
-                const agent = await stepAgentSelection({ ...ctx.config, agent: result.agent }, result.detections);
-                ctx.apply({ agent });
+                // Inject the detected agent block into a synthetic AkmConfig so
+                // stepAgentSelection can read it via getCurrentAgentBlock().
+                const synthConfig = { ...ctx.config, ...applyLegacyAgent(ctx.config, result.agent) };
+                const agent = await stepAgentSelection(synthConfig, result.detections);
+                ctx.apply(applyLegacyAgent(ctx.config, agent));
             },
         },
         {
@@ -1294,6 +1447,10 @@ export async function runSetupWizard(opts) {
     const configPath = getConfigPath();
     // Resolve stash directory early so akmInit can run before any prompts
     const resolvedStashDir = opts?.dir ? path.resolve(opts.dir) : (current.stashDir ?? getDefaultStashDir());
+    // Refuse explicit --dir /tmp/... before doing any work — protects the host
+    // config from being clobbered with a stashDir that the OS may reap.
+    assertSetupSandbox(resolvedStashDir, opts?.dir != null);
+    applyStashIsolationToEnv(resolvedStashDir, opts?.dir != null);
     // Bootstrap directory structure before any prompts so the stash exists
     // even if the wizard is interrupted after this point.
     if (!opts?.noInit) {
@@ -1326,11 +1483,11 @@ export async function runSetupWizard(opts) {
     // Step 1/2: Small model connection (for enrichment features)
     const smallModelResult = await stepSmallModelConnection(ctx.config);
     if (!smallModelResult.skipped) {
-        ctx.apply({ llm: smallModelResult.llm });
+        ctx.apply(applyLegacyLlm(ctx.config, smallModelResult.llm));
     }
     // Step 2/2: Agent connection (for agentic features)
     const agentConfig = await stepAgentConnection(ctx.config, smallModelResult);
-    ctx.apply({ agent: agentConfig });
+    ctx.apply(applyLegacyAgent(ctx.config, agentConfig));
     const newConfig = {
         ...ctx.config,
         // Preserve fields the steps don't manage explicitly.
@@ -1339,7 +1496,7 @@ export async function runSetupWizard(opts) {
     const semanticSearchMode = outcome.semantic;
     const stashDir = newConfig.stashDir ?? current.stashDir ?? getDefaultStashDir();
     const embedding = newConfig.embedding;
-    const llm = newConfig.llm;
+    const llm = getDefaultLlmConfig(newConfig);
     const registries = newConfig.registries;
     const allStashes = newConfig.sources ?? [];
     // Feature capability summary
@@ -1354,7 +1511,7 @@ export async function runSetupWizard(opts) {
         `Semantic search:  ${semanticSearchMode.mode}`,
         `Registries:       ${effectiveRegistries.filter((r) => r.enabled !== false).length} enabled`,
         `Stash sources:    ${allStashes.length}`,
-        `Agent default:    ${newConfig.agent?.default ?? "disabled"}`,
+        `Agent default:    ${newConfig.defaults?.agent ?? "disabled"}`,
         `Output:           ${newConfig.output?.format ?? "json"} / ${newConfig.output?.detail ?? "brief"}`,
     ].join("\n"), "Configuration Summary");
     const shouldSave = await prompt(() => p.confirm({
@@ -1454,6 +1611,8 @@ export async function runSetupWizard(opts) {
 export async function runSetupWithDefaults(opts) {
     const current = loadUserConfig();
     const stashDir = opts.dir ? path.resolve(opts.dir) : (current.stashDir ?? getDefaultStashDir());
+    assertSetupSandbox(stashDir, opts.dir != null);
+    applyStashIsolationToEnv(stashDir, opts.dir != null);
     // Bootstrap directory structure first
     let initResult;
     if (!opts.noInit) {
@@ -1471,11 +1630,11 @@ export async function runSetupWithDefaults(opts) {
     if (!ctx.config.stashDir)
         ctx.apply({ stashDir });
     // Auto-detect agent CLI if not already configured
-    if (!ctx.config.agent) {
+    if (!ctx.config.defaults?.agent) {
         const detected = detectAgentCliProfiles(undefined);
         const defaultProfile = pickDefaultAgentProfile(detected, undefined);
         if (defaultProfile) {
-            ctx.apply({ agent: { default: defaultProfile } });
+            ctx.apply(applyLegacyAgent(ctx.config, { default: defaultProfile }));
         }
     }
     saveConfig(ctx.config);
@@ -1493,7 +1652,6 @@ export async function runSetupWithDefaults(opts) {
  * Validates required sub-fields and strips unknown/restricted keys.
  */
 export async function runSetupFromConfig(opts) {
-    // Phase 1: Parse JSON
     let incoming;
     try {
         incoming = JSON.parse(opts.configJson);
@@ -1502,7 +1660,16 @@ export async function runSetupFromConfig(opts) {
         throw new Error(`Invalid JSON in --config: ${e.message}`);
     }
     // Phase 2: Validate — only allow safe top-level keys
-    const ALLOWED_KEYS = new Set(["stashDir", "llm", "embedding", "agent", "semanticSearchMode", "output"]);
+    const ALLOWED_KEYS = new Set([
+        "stashDir",
+        "llm",
+        "embedding",
+        "agent",
+        "semanticSearchMode",
+        "output",
+        "profiles",
+        "defaults",
+    ]);
     for (const key of Object.keys(incoming)) {
         if (!ALLOWED_KEYS.has(key)) {
             warn(`[akm setup] Ignoring unknown or restricted config key: "${key}"`);
@@ -1529,22 +1696,42 @@ export async function runSetupFromConfig(opts) {
         : incoming.stashDir
             ? path.resolve(incoming.stashDir)
             : (current.stashDir ?? getDefaultStashDir());
-    const merged = {
-        ...current,
-        ...incoming,
-        stashDir,
-    };
+    const stashDirExplicit = opts.dir != null || incoming.stashDir != null;
+    assertSetupSandbox(stashDir, stashDirExplicit);
+    applyStashIsolationToEnv(stashDir, stashDirExplicit);
+    let merged = { ...current, stashDir };
+    // Apply non-llm/agent keys directly.
+    const mergedRec = merged;
+    for (const key of Object.keys(incoming)) {
+        if (key === "llm" || key === "agent")
+            continue;
+        mergedRec[key] = incoming[key];
+    }
+    // Translate legacy llm/agent inputs into the new shape.
+    if (incoming.llm) {
+        merged = { ...merged, ...applyLegacyLlm(merged, incoming.llm) };
+    }
+    if (incoming.agent) {
+        merged = { ...merged, ...applyLegacyAgent(merged, incoming.agent) };
+    }
     // Bootstrap directory structure
     let initResult;
     if (!opts.noInit) {
         initResult = await akmInit({ dir: stashDir });
     }
     // Optional probe
-    if (opts.probe && merged.llm) {
+    const mergedLlm = getDefaultLlmConfig(merged);
+    if (opts.probe && mergedLlm) {
         try {
-            const caps = await probeLlmCapabilities(merged.llm);
+            const caps = await probeLlmCapabilities(mergedLlm);
             if (caps.reachable) {
-                merged.llm = { ...merged.llm, capabilities: { structuredOutput: caps.structuredOutput ?? false } };
+                merged = {
+                    ...merged,
+                    ...applyLegacyLlm(merged, {
+                        ...mergedLlm,
+                        capabilities: { structuredOutput: caps.structuredOutput ?? false },
+                    }),
+                };
             }
         }
         catch {
@@ -1561,3 +1748,55 @@ export async function runSetupFromConfig(opts) {
         ripgrep: initResult?.ripgrep,
     };
 }
+// ── Setup --from <file> bootstrap helper ────────────────────────────────────
+/**
+ * Resolve a `--from <file>` argument to a JSON-encoded config payload suitable
+ * for `runSetupFromConfig({ configJson })`. Used by the CLI to bootstrap from
+ * a JSON or YAML file on disk; extracted as a standalone function so its
+ * filesystem and parser behaviour can be unit-tested directly.
+ *
+ * - Expands a leading `~` to the current user's home directory.
+ * - Resolves the path against `cwd ?? process.cwd()` for relative inputs.
+ * - Detects YAML vs JSON via the file extension (`.yml`/`.yaml` → YAML;
+ *   anything else, including `.json`, parses as JSON).
+ * - Throws `ConfigError("INVALID_CONFIG_FILE")` when the file does not exist,
+ *   cannot be read, cannot be parsed, or contains a non-object top level.
+ *
+ * Returns `{ configJson, resolvedPath, format }` so callers can log which
+ * file was actually loaded and which parser was used.
+ */
+export async function loadSetupConfigFromFile(filePath, opts) {
+    const cwd = opts?.cwd ?? process.cwd();
+    const homeDir = opts?.homeDir ?? os.homedir();
+    const expanded = filePath.startsWith("~") ? path.join(homeDir, filePath.slice(1)) : filePath;
+    const resolvedPath = path.resolve(cwd, expanded);
+    if (!fs.existsSync(resolvedPath)) {
+        throw new ConfigError(`Config file not found: ${resolvedPath}`, "INVALID_CONFIG_FILE");
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(resolvedPath, "utf8");
+    }
+    catch (err) {
+        throw new ConfigError(`Failed to read config file ${resolvedPath}: ${err instanceof Error ? err.message : String(err)}`, "INVALID_CONFIG_FILE");
+    }
+    const ext = path.extname(resolvedPath).toLowerCase();
+    const format = ext === ".yml" || ext === ".yaml" ? "yaml" : "json";
+    let parsed;
+    try {
+        if (format === "yaml") {
+            const { parse: yamlParse } = await import("yaml");
+            parsed = yamlParse(raw);
+        }
+        else {
+            parsed = JSON.parse(raw);
+        }
+    }
+    catch (err) {
+        throw new ConfigError(`Failed to parse ${format.toUpperCase()} config file ${resolvedPath}: ${err instanceof Error ? err.message : String(err)}`, "INVALID_CONFIG_FILE");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new ConfigError(`Config file ${resolvedPath} must contain a top-level object, got ${Array.isArray(parsed) ? "array" : typeof parsed}.`, "INVALID_CONFIG_FILE");
+    }
+    return { configJson: JSON.stringify(parsed), resolvedPath, format };
+}