akm-cli 0.7.5 → 0.8.0-rc.11

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,22 +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, getConfigPath, loadUserConfig, saveConfig } from "../core/config";
-import { 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.
  */
@@ -121,7 +249,6 @@ function cloneLlmConfig(llm) {
     return {
         ...llm,
         ...(llm.capabilities ? { capabilities: { ...llm.capabilities } } : {}),
-        ...(llm.features ? { features: { ...llm.features } } : {}),
         ...(llm.extraParams ? { extraParams: { ...llm.extraParams } } : {}),
     };
 }
@@ -201,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 {
@@ -337,8 +476,11 @@ async function prepareSemanticSearchAssets(config) {
     return { ok: true };
 }
 // ── Steps ───────────────────────────────────────────────────────────────────
-async function stepStashDir(current) {
-    const defaultDir = current.stashDir ?? getDefaultStashDir();
+async function stepStashDir(current, options) {
+    const defaultDir = options?.preferredDir ?? current.stashDir ?? getDefaultStashDir();
+    if (options?.nonInteractive) {
+        return defaultDir;
+    }
     const choice = await prompt(() => p.select({
         message: "Where should akm store skills, commands, and other assets?",
         options: [
@@ -354,6 +496,14 @@ async function stepStashDir(current) {
         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();
@@ -488,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;
@@ -635,7 +786,7 @@ export async function stepRegistries(current) {
  * @internal Exported for testing only.
  */
 export async function stepAddSources(current, options) {
-    const existingSources = [...(current.sources ?? current.stashes ?? [])];
+    const existingSources = [...(current.sources ?? [])];
     const sources = [];
     if (existingSources.length > 0) {
         p.note(renderConfiguredSourceList(existingSources), "Configured stash sources");
@@ -705,7 +856,7 @@ async function stepAgentPlatforms(current) {
         p.log.info("No agent platform configurations detected.");
         return [];
     }
-    const existingPaths = new Set((current.sources ?? current.stashes ?? []).map((s) => s.path));
+    const existingPaths = new Set((current.sources ?? []).map((s) => s.path));
     // Filter out platforms already configured
     const newPlatforms = platforms.filter((pl) => !existingPaths.has(pl.path));
     if (newPlatforms.length === 0) {
@@ -734,12 +885,374 @@ async function stepAgentPlatforms(current) {
     }
     return entries;
 }
+/**
+ * Step 1/2: Configure the small model connection used for metadata and bounded LLM features.
+ *
+ * Detects Ollama automatically and pre-selects it. The user may also choose
+ * OpenAI, LM Studio, a custom endpoint, or skip the step entirely.
+ */
+export async function stepSmallModelConnection(current) {
+    p.log.step("Step 1/2: Configure your small model connection");
+    p.note([
+        "This connection is used for background processing:",
+        "  • akm index           (metadata enhancement)",
+        "  • akm distill         (lesson distillation)",
+        "  • akm remember --enrich (memory compression)",
+        "  • akm curate --rerank   (search reranking)",
+    ].join("\n"));
+    // Probe for Ollama in the background while showing the note.
+    const spin = p.spinner();
+    spin.start("Detecting local services...");
+    const ollama = await detectOllama();
+    spin.stop(ollama.available ? `Ollama detected at ${ollama.endpoint}` : "No local services detected");
+    const ollamaEndpoint = ollama.available ? ollama.endpoint : undefined;
+    const providerOptions = [];
+    if (ollama.available) {
+        providerOptions.push({
+            value: "ollama",
+            label: "Ollama (local)",
+            hint: `detected at ${ollama.endpoint}`,
+        });
+    }
+    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" });
+    const currentLlmSmall = getCurrentLlm(current);
+    if (currentLlmSmall) {
+        providerOptions.push({
+            value: "keep",
+            label: `Keep current: ${currentLlmSmall.provider ?? currentLlmSmall.endpoint}`,
+            hint: currentLlmSmall.model,
+        });
+    }
+    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(currentLlmSmall), skipped: false, ollamaEndpoint };
+    }
+    if (providerChoice === "skip") {
+        p.note([
+            "Enrichment features disabled:",
+            "  • akm index           — metadata enhancement disabled",
+            "  • akm distill         — lesson generation",
+            "  • akm remember --enrich",
+            "  • akm curate --rerank",
+            "",
+            "You can configure this later with `akm setup`.",
+        ].join("\n"), "Warning");
+        return { llm: undefined, skipped: true, ollamaEndpoint };
+    }
+    let llm;
+    if (providerChoice === "ollama") {
+        const ollamaChatModels = ollama.models.filter((m) => !m.includes("embed") && !m.includes("nomic") && !m.includes("minilm") && !m.includes("bge"));
+        let model;
+        if (ollamaChatModels.length > 0) {
+            model = await prompt(() => p.select({
+                message: "Model name:",
+                options: [
+                    ...ollamaChatModels.map((m) => ({ value: m, label: m })),
+                    { value: "__custom__", label: "Enter a model name manually..." },
+                ],
+                initialValue: ollamaChatModels[0],
+            }));
+            if (model === "__custom__") {
+                model = await prompt(() => p.text({
+                    message: "Model name:",
+                    placeholder: "llama3.2",
+                    validate: (v) => (!v?.trim() ? "Model name cannot be empty" : undefined),
+                }));
+            }
+        }
+        else {
+            model = await prompt(() => p.text({
+                message: "Model name (e.g. llama3.2):",
+                placeholder: "llama3.2",
+                defaultValue: "llama3.2",
+                validate: (v) => (!v?.trim() ? "Model name cannot be empty" : undefined),
+            }));
+        }
+        llm = {
+            provider: "ollama",
+            endpoint: `${ollama.endpoint}/v1/chat/completions`,
+            model: model.trim(),
+            temperature: 0.3,
+            maxTokens: 1024,
+        };
+    }
+    else if (providerChoice === "openai") {
+        const model = await prompt(() => p.text({
+            message: "Model name:",
+            placeholder: "gpt-4o-mini",
+            defaultValue: "gpt-4o-mini",
+            validate: (v) => (!v?.trim() ? "Model name cannot be empty" : undefined),
+        }));
+        if (!process.env.AKM_LLM_API_KEY) {
+            p.log.info("Set AKM_LLM_API_KEY in your shell before running `akm index`.");
+        }
+        llm = {
+            provider: "openai",
+            endpoint: "https://api.openai.com/v1/chat/completions",
+            model: model.trim() || "gpt-4o-mini",
+            temperature: 0.3,
+            maxTokens: 1024,
+        };
+    }
+    else if (providerChoice === "lmstudio") {
+        const endpoint = await prompt(() => p.text({
+            message: "Endpoint URL:",
+            placeholder: "http://localhost:1234/v1/chat/completions",
+            defaultValue: "http://localhost:1234/v1/chat/completions",
+            validate: (v) => {
+                if (!v?.trim())
+                    return "Endpoint cannot be empty";
+                if (!v.startsWith("http://") && !v.startsWith("https://"))
+                    return "Must start with http:// or https://";
+            },
+        }));
+        const model = await prompt(() => p.text({
+            message: "Model name:",
+            placeholder: "local-model",
+            validate: (v) => (!v?.trim() ? "Model name cannot be empty" : undefined),
+        }));
+        llm = {
+            provider: "lmstudio",
+            endpoint: endpoint.trim(),
+            model: model.trim(),
+            temperature: 0.3,
+            maxTokens: 1024,
+        };
+    }
+    else {
+        // custom
+        const endpoint = await prompt(() => p.text({
+            message: "OpenAI-compatible chat completions endpoint:",
+            placeholder: "https://your-host/v1/chat/completions",
+            validate: (v) => {
+                if (!v?.trim())
+                    return "Endpoint cannot be empty";
+                if (!v.startsWith("http://") && !v.startsWith("https://"))
+                    return "Must start with http:// or https://";
+            },
+        }));
+        const model = await prompt(() => p.text({
+            message: "Model name:",
+            placeholder: "gpt-4o-mini",
+            validate: (v) => (!v?.trim() ? "Model name cannot be empty" : undefined),
+        }));
+        const apiKeyInput = await promptOrBack(() => p.text({
+            message: "API key (optional — press Enter to skip):",
+            placeholder: "",
+        }));
+        llm = {
+            provider: "custom",
+            endpoint: endpoint.trim(),
+            model: model.trim(),
+            temperature: 0.3,
+            maxTokens: 1024,
+            ...(apiKeyInput?.trim() ? { apiKey: apiKeyInput.trim() } : {}),
+        };
+    }
+    // Best-effort probe — never blocks setup.
+    const probeSpin = p.spinner();
+    probeSpin.start("Probing LLM (structured-output round-trip)...");
+    const probe = await probeLlmCapabilities(llm);
+    if (probe.reachable && probe.structuredOutput) {
+        probeSpin.stop("LLM reachable; structured output verified.");
+        llm.capabilities = { ...(llm.capabilities ?? {}), structuredOutput: true };
+    }
+    else if (probe.reachable) {
+        probeSpin.stop("LLM reachable but structured-output probe failed.");
+        llm.capabilities = { ...(llm.capabilities ?? {}), structuredOutput: false };
+    }
+    else {
+        probeSpin.stop("LLM not reachable.");
+        p.log.warn(`Could not reach the LLM endpoint${probe.error ? ` (${probe.error})` : ""}. Configuration was saved; verify your endpoint and API key, then retry.`);
+    }
+    return { llm, skipped: false, ollamaEndpoint };
+}
+/**
+ * Step 2/2: Configure the agent connection used for agentic features.
+ *
+ * Options depend on whether Step 1 was completed or skipped.
+ */
+export async function stepAgentConnection(current, smallModel) {
+    p.log.step("Step 2/2: Configure your agent connection");
+    p.note([
+        "This connection is used for agentic commands:",
+        "  • akm propose   (generate improvement 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);
+    const currentAgentBlock = getCurrentAgentBlock(current);
+    const availableClis = detections.filter((d) => d.available);
+    const agentOptions = [];
+    if (!smallModel.skipped && smallModel.llm) {
+        agentOptions.push({
+            value: "same-connection",
+            label: "Same connection, select model",
+            hint: `uses ${smallModel.llm.endpoint.replace("/v1/chat/completions", "")}`,
+        });
+    }
+    agentOptions.push({ value: "new-connection", label: "New connection (different endpoint)" });
+    if (availableClis.length > 0) {
+        agentOptions.push({
+            value: "cli-agent",
+            label: "Installed CLI agent",
+            hint: `${availableClis.map((d) => d.name).join(", ")} detected`,
+        });
+    }
+    agentOptions.push({ value: "none", label: "None — disable agentic features" });
+    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 = currentAgentBlock
+        ? "keep"
+        : availableClis.length > 0 && smallModel.skipped
+            ? "cli-agent"
+            : !smallModel.skipped && smallModel.llm
+                ? "same-connection"
+                : availableClis.length > 0
+                    ? "cli-agent"
+                    : "none";
+    const agentChoice = await prompt(() => p.select({
+        message: "How do you want to run agent commands?",
+        options: agentOptions,
+        initialValue: initialAgentValue,
+    }));
+    if (agentChoice === "keep") {
+        return currentAgentBlock;
+    }
+    if (agentChoice === "none") {
+        p.note([
+            "Agentic features disabled:",
+            '  • akm propose — 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`.",
+        ].join("\n"), "Warning");
+        return undefined;
+    }
+    if (agentChoice === "same-connection") {
+        if (smallModel.skipped || !smallModel.llm) {
+            p.log.warn("You skipped the small model connection. Configure one to use the same connection. Falling back to 'new connection'.");
+            // Fall through to new-connection flow
+        }
+        else {
+            const baseEndpoint = smallModel.llm.endpoint.replace("/v1/chat/completions", "");
+            p.log.info(`Endpoint: ${baseEndpoint} (from Step 1)`);
+            const agentModel = await prompt(() => p.text({
+                message: "Model to use for agent tasks (same model is fine, larger models work better):",
+                placeholder: "qwen2.5-coder:32b",
+                validate: (v) => (!v?.trim() ? "Model name cannot be empty" : undefined),
+            }));
+            const profileName = smallModel.llm.provider ?? "default";
+            return {
+                ...(currentAgentBlock ?? {}),
+                profiles: {
+                    ...(currentAgentBlock?.profiles ?? {}),
+                    [profileName]: {
+                        ...(currentAgentBlock?.profiles?.[profileName] ?? {}),
+                        sdkMode: true,
+                        model: agentModel.trim(),
+                        endpoint: smallModel.llm.endpoint,
+                    },
+                },
+                default: profileName,
+            };
+        }
+    }
+    if (agentChoice === "cli-agent") {
+        if (availableClis.length === 0) {
+            p.log.warn("No agent CLIs detected on PATH.");
+            return currentAgentBlock;
+        }
+        const initialCli = pickDefaultAgentProfile(detections, currentAgentBlock?.default) ?? availableClis[0]?.name;
+        const selectedCli = await prompt(() => p.select({
+            message: "Which CLI agent?",
+            options: availableClis.map((d) => ({
+                value: d.name,
+                label: d.name,
+                hint: d.resolvedPath ?? d.bin,
+            })),
+            initialValue: initialCli,
+        }));
+        return {
+            ...(currentAgentBlock ?? {}),
+            default: selectedCli,
+        };
+    }
+    // "new-connection" (also fall-through from "same-provider" when Step 1 was skipped)
+    const newEndpoint = await prompt(() => p.text({
+        message: "OpenAI-compatible chat completions endpoint:",
+        placeholder: "https://your-host/v1/chat/completions",
+        validate: (v) => {
+            if (!v?.trim())
+                return "Endpoint cannot be empty";
+            if (!v.startsWith("http://") && !v.startsWith("https://"))
+                return "Must start with http:// or https://";
+        },
+    }));
+    const newApiKeyInput = await promptOrBack(() => p.text({
+        message: "API key (optional — press Enter to skip):",
+        placeholder: "",
+    }));
+    const newModel = await prompt(() => p.text({
+        message: "Model name (larger is better, e.g. gpt-4o):",
+        placeholder: "gpt-4o",
+        validate: (v) => (!v?.trim() ? "Model name cannot be empty" : undefined),
+    }));
+    const customProfile = {
+        sdkMode: true,
+        endpoint: newEndpoint.trim(),
+        model: newModel.trim(),
+        ...(newApiKeyInput?.trim() ? { apiKey: newApiKeyInput.trim() } : {}),
+    };
+    return {
+        ...(currentAgentBlock ?? {}),
+        profiles: {
+            ...(currentAgentBlock?.profiles ?? {}),
+            custom: customProfile,
+        },
+        default: "custom",
+    };
+}
+/**
+ * Print a feature capability summary after both connection steps are complete.
+ */
+function printCapabilitySummary(smallModelSkipped, agentConfigured) {
+    const lines = ["Setup complete. Here's what's enabled:", ""];
+    lines.push("  ✓ akm search, akm curate, akm show — always available");
+    if (!smallModelSkipped) {
+        lines.push("  ✓ akm index, akm distill, akm remember — small model configured");
+    }
+    else {
+        lines.push("  ✗ akm index, akm distill, akm remember — run `akm setup` to enable");
+    }
+    if (agentConfigured) {
+        lines.push("  ✓ akm propose, akm improve, akm tasks — agent configured");
+    }
+    else {
+        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: [
@@ -753,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,
     };
 }
@@ -799,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 };
@@ -832,7 +1346,10 @@ export function buildSetupSteps(options) {
             label: "Stash Directory",
             nonInteractive: true,
             async run(ctx) {
-                const stashDir = await stepStashDir(ctx.config);
+                const stashDir = await stepStashDir(ctx.config, {
+                    nonInteractive: ctx.nonInteractive,
+                    preferredDir: options.preferredStashDir,
+                });
                 ctx.apply({ stashDir });
             },
         },
@@ -855,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));
             },
         },
         {
@@ -907,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));
             },
         },
         {
@@ -922,10 +1441,21 @@ export function buildSetupSteps(options) {
     ];
     return { steps, outcome };
 }
-export async function runSetupWizard() {
+export async function runSetupWizard(opts) {
     p.intro("akm setup");
     const current = loadUserConfig();
     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) {
+        await akmInit({ dir: resolvedStashDir });
+    }
     // Quick connectivity check — skip network-dependent steps when offline
     const online = await isOnline();
     if (!online) {
@@ -936,6 +1466,7 @@ export async function runSetupWizard() {
     const { steps, outcome } = buildSetupSteps({
         online,
         semanticSearchOutcome: { mode: current.semanticSearchMode, prepareAssets: false },
+        preferredStashDir: resolvedStashDir,
     });
     // Wrap each step with a `p.log.step()` header so the wizard UI is
     // unchanged. The canonical `runSetupSteps()` runner is used directly by
@@ -948,6 +1479,15 @@ export async function runSetupWizard() {
         },
     }));
     await runSetupSteps(labeledSteps, ctx);
+    // ── Two-step connection configuration ──────────────────────────────────────
+    // Step 1/2: Small model connection (for enrichment features)
+    const smallModelResult = await stepSmallModelConnection(ctx.config);
+    if (!smallModelResult.skipped) {
+        ctx.apply(applyLegacyLlm(ctx.config, smallModelResult.llm));
+    }
+    // Step 2/2: Agent connection (for agentic features)
+    const agentConfig = await stepAgentConnection(ctx.config, smallModelResult);
+    ctx.apply(applyLegacyAgent(ctx.config, agentConfig));
     const newConfig = {
         ...ctx.config,
         // Preserve fields the steps don't manage explicitly.
@@ -956,9 +1496,12 @@ export async function runSetupWizard() {
     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 ?? newConfig.stashes ?? [];
+    const allStashes = newConfig.sources ?? [];
+    // Feature capability summary
+    const agentConfigured = Boolean(agentConfig);
+    printCapabilitySummary(smallModelResult.skipped, agentConfigured);
     // Confirm before saving
     const effectiveRegistries = registries ?? DEFAULT_CONFIG.registries ?? [];
     p.note([
@@ -968,7 +1511,7 @@ export async function runSetupWizard() {
         `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({
@@ -979,8 +1522,6 @@ export async function runSetupWizard() {
         bail();
     // Save config
     saveConfig(newConfig);
-    // Initialize stash directory
-    await akmInit({ dir: stashDir });
     if (semanticSearchMode.mode === "off") {
         clearSemanticStatus();
     }
@@ -1062,3 +1603,200 @@ export async function runSetupWizard() {
     }
     p.outro(`Configuration saved to ${configPath}`);
 }
+// ── Non-interactive / scripting entry points ─────────────────────────────────
+/**
+ * Run setup in non-interactive mode, applying all defaults.
+ * Safe to call from CI or scripts. Idempotent — re-running produces the same result.
+ */
+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) {
+        initResult = await akmInit({ dir: stashDir });
+    }
+    // Run steps in non-interactive mode (applies defaults, skips prompts)
+    const ctx = createSetupContext(current, { nonInteractive: true });
+    const { steps } = buildSetupSteps({
+        online: false,
+        semanticSearchOutcome: { mode: current.semanticSearchMode, prepareAssets: false },
+        preferredStashDir: stashDir,
+    });
+    await runSetupSteps(steps, ctx);
+    // Ensure stashDir is set
+    if (!ctx.config.stashDir)
+        ctx.apply({ stashDir });
+    // Auto-detect agent CLI if not already configured
+    if (!ctx.config.defaults?.agent) {
+        const detected = detectAgentCliProfiles(undefined);
+        const defaultProfile = pickDefaultAgentProfile(detected, undefined);
+        if (defaultProfile) {
+            ctx.apply(applyLegacyAgent(ctx.config, { default: defaultProfile }));
+        }
+    }
+    saveConfig(ctx.config);
+    return {
+        configPath: getConfigPath(),
+        stashDir,
+        stashCreated: initResult?.created ?? false,
+        written: true,
+        fields: Object.keys(ctx.config).filter((k) => ctx.config[k] !== undefined),
+        ripgrep: initResult?.ripgrep,
+    };
+}
+/**
+ * Apply a JSON config blob non-interactively, merging it with the current config.
+ * Validates required sub-fields and strips unknown/restricted keys.
+ */
+export async function runSetupFromConfig(opts) {
+    let incoming;
+    try {
+        incoming = JSON.parse(opts.configJson);
+    }
+    catch (e) {
+        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",
+        "profiles",
+        "defaults",
+    ]);
+    for (const key of Object.keys(incoming)) {
+        if (!ALLOWED_KEYS.has(key)) {
+            warn(`[akm setup] Ignoring unknown or restricted config key: "${key}"`);
+            delete incoming[key];
+        }
+    }
+    // Validate required sub-fields
+    if (incoming.llm) {
+        if (!incoming.llm.endpoint?.trim())
+            throw new Error("llm.endpoint is required when llm is provided");
+        if (!incoming.llm.model?.trim())
+            throw new Error("llm.model is required when llm is provided");
+    }
+    if (incoming.embedding) {
+        if (!incoming.embedding.endpoint?.trim())
+            throw new Error("embedding.endpoint is required when embedding is provided");
+        if (!incoming.embedding.model?.trim())
+            throw new Error("embedding.model is required when embedding is provided");
+    }
+    // Phase 3: Merge with existing config
+    const current = loadUserConfig();
+    const stashDir = opts.dir
+        ? path.resolve(opts.dir)
+        : incoming.stashDir
+            ? path.resolve(incoming.stashDir)
+            : (current.stashDir ?? getDefaultStashDir());
+    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
+    const mergedLlm = getDefaultLlmConfig(merged);
+    if (opts.probe && mergedLlm) {
+        try {
+            const caps = await probeLlmCapabilities(mergedLlm);
+            if (caps.reachable) {
+                merged = {
+                    ...merged,
+                    ...applyLegacyLlm(merged, {
+                        ...mergedLlm,
+                        capabilities: { structuredOutput: caps.structuredOutput ?? false },
+                    }),
+                };
+            }
+        }
+        catch {
+            // Non-fatal: probe failure is informational only
+        }
+    }
+    saveConfig(merged);
+    return {
+        configPath: getConfigPath(),
+        stashDir,
+        stashCreated: initResult?.created ?? false,
+        written: true,
+        fields: Object.keys(incoming).filter((k) => incoming[k] !== undefined),
+        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 };
+}