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

package/dist/setup/setup.js

@@ -9,19 +9,22 @@
  * Collects all choices and writes config once at the end.
  *
  * This module holds the wizard orchestration; the individual wizard steps,
- * config-shape adapters, prompt shims, provider table, and semantic-asset
- * preparation live in sibling modules (`steps/*`, `legacy-config`, `prompt`,
+ * engine writers, prompt shims, provider table, and semantic-asset preparation
+ * live in sibling modules (`steps/*`, `engine-config`, `prompt`,
  * `providers`, `semantic-assets`).
  */
 import { promises as dnsPromises } from "node:dns";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import * as p from "../cli/clack.js";
 import { akmInit } from "../commands/sources/init.js";
-import { DEFAULT_CONFIG, getDefaultLlmConfig, loadUserConfig, saveConfig } from "../core/config/config.js";
-import { backupExistingConfig } from "../core/config/config-io.js";
-import { deepMergeConfig } from "../core/deep-merge.js";
+import { deriveBundleIds } from "../core/bundle-id.js";
+import { bundleEntryToSourceEntry, DEFAULT_CONFIG, loadUserConfig, mutateConfigWithPrecommit, parseAndValidateConfigText, primaryBundlePath, validateCompleteConfig, } from "../core/config/config.js";
+import { readConfigText } from "../core/config/config-io.js";
+import { listTopLevelConfigKeys } from "../core/config/config-schema.js";
+import { deepMergeConfig } from "../core/config/deep-merge.js";
 import { ConfigError, UsageError } from "../core/errors.js";
 import { getConfigPath, getDefaultStashDir, isTransientStashPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
@@ -29,11 +32,12 @@ import { akmIndex } from "../indexer/indexer.js";
 import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "../indexer/search/semantic-status.js";
 import { detectAgentCliProfiles, pickDefaultAgentProfile } from "../integrations/agent/index.js";
 import { defaultProfileName } from "../integrations/harnesses/index.js";
+import { readLockfile } from "../integrations/lockfile.js";
 import { probeLlmCapabilities } from "../llm/client.js";
-import { getOutputMode } from "../output/context.js";
 import { detectEnvironment, detectLMStudio, renderDetectionSummary, } from "./detect.js";
+import { upsertDetectedAgentEngine, upsertDetectedLlmEngine, verifyOpenAiCompatibleEndpoint } from "./detected-engines.js";
+import { readCurrentLlmEngine, writeAgentEngines, writeLlmEngine } from "./engine-config.js";
 import { detectHarnessConfigs } from "./harness-config-import.js";
-import { applyLegacyAgent, applyLegacyLlm } from "./legacy-config.js";
 import { bail, prompt } from "./prompt.js";
 import { PROVIDER_DEFAULTS } from "./providers.js";
 import { prepareSemanticSearchAssets } from "./semantic-assets.js";
@@ -44,21 +48,21 @@ import { printCapabilitySummary, stepAgentCliDetection, stepAgentPlatforms, step
 import { stepSemanticSearch } from "./steps/semantic.js";
 import { stepAdditionalSources, stepAddSources, stepRegistries } from "./steps/sources.js";
 import { stepStashDir } from "./steps/stashdir.js";
-import { stepDefaultImproveTasks, stepScheduledTasks } from "./steps/tasks.js";
+import { stepScheduledTasks } from "./steps/tasks.js";
 // ── 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
+ * Refuse to persist an explicit `--dir /tmp/...` as the default bundle path.
+ * The OS may reap the directory at any time, leaving the next run with a
+ * default bundle that points at a deleted path. 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`.
+ * silently clobber the host config (the 2026-05-23 setup-clobbers-user-config
+ * incident).
  *
  * 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
+ * `AKM_BUNDLE_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`.
  */
@@ -70,7 +74,7 @@ function assertSetupSandbox(stashDir, dirExplicitlyProvided) {
     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). " +
+        "Persisting it as the default bundle would leave the next run pointing at a deleted path. " +
         "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");
 }
@@ -78,11 +82,11 @@ function assertSetupSandbox(stashDir, dirExplicitlyProvided) {
  * 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`
+ * caller who passes `--dir /tmp/X` but doesn't pre-export `AKM_BUNDLE_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).
+ *   - `AKM_BUNDLE_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.
@@ -90,11 +94,215 @@ function assertSetupSandbox(stashDir, dirExplicitlyProvided) {
 function applyStashIsolationToEnv(stashDir, dirExplicitlyProvided) {
     if (!dirExplicitlyProvided)
         return;
-    if (process.env.AKM_STASH_DIR?.trim())
+    if (process.env.AKM_BUNDLE_DIR?.trim())
         return;
-    process.env.AKM_STASH_DIR = stashDir;
+    process.env.AKM_BUNDLE_DIR = stashDir;
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
+/** Raw preflight used before setup performs prompts, initialization, or writes. */
+export function assertSetupConfigPreflight() {
+    const configPath = getConfigPath();
+    let text;
+    try {
+        text = readConfigText(configPath);
+    }
+    catch (error) {
+        throw new ConfigError(`Could not read config at ${configPath}: ${error instanceof Error ? error.message : String(error)}`, "INVALID_CONFIG_FILE");
+    }
+    if (text !== undefined)
+        parseAndValidateConfigText(text, configPath);
+}
+function isPlainRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function sameConfigValue(left, right) {
+    return isDeepStrictEqual(left, right);
+}
+function configArrayItemKey(value) {
+    if (!isPlainRecord(value))
+        return `value:${JSON.stringify(value)}`;
+    if (typeof value.id === "string")
+        return `id:${value.id}`;
+    if (typeof value.type === "string" && typeof value.url === "string")
+        return `source:${value.type}:url:${value.url}`;
+    if (typeof value.type === "string" && typeof value.path === "string")
+        return `source:${value.type}:path:${path.resolve(value.path)}`;
+    if (typeof value.url === "string")
+        return `url:${value.url}`;
+    if (typeof value.name === "string")
+        return `name:${value.name}`;
+    return `value:${JSON.stringify(value)}`;
+}
+function setupConflict(pathParts) {
+    const field = pathParts.length > 0 ? pathParts.join(".") : "(root)";
+    throw new ConfigError(`Setup config conflict at ${field}: another process changed the same field after setup started. Rerun setup against the latest config.`, "INVALID_CONFIG_FILE");
+}
+/** Reapply setup's changes while rejecting concurrent edits to the same field. */
+export function rebaseSetupChanges(original, desired, latest, pathParts = []) {
+    if (sameConfigValue(original, desired))
+        return latest;
+    if (Array.isArray(original) && Array.isArray(desired)) {
+        if (latest !== undefined && !Array.isArray(latest))
+            setupConflict(pathParts);
+        const latestItems = Array.isArray(latest) ? latest : [];
+        const originalByKey = new Map(original.map((item) => [configArrayItemKey(item), item]));
+        const desiredByKey = new Map(desired.map((item) => [configArrayItemKey(item), item]));
+        const latestByKey = new Map(latestItems.map((item) => [configArrayItemKey(item), item]));
+        const result = [];
+        for (const [key, desiredItem] of desiredByKey) {
+            const originalItem = originalByKey.get(key);
+            const latestItem = latestByKey.get(key);
+            if (originalByKey.has(key)) {
+                if (!latestByKey.has(key))
+                    setupConflict([...pathParts, key]);
+                result.push(rebaseSetupChanges(originalItem, desiredItem, latestItem, [...pathParts, key]));
+            }
+            else if (!latestByKey.has(key) || sameConfigValue(latestItem, desiredItem)) {
+                result.push(desiredItem);
+            }
+            else {
+                setupConflict([...pathParts, key]);
+            }
+        }
+        for (const [key, originalItem] of originalByKey) {
+            if (desiredByKey.has(key) || !latestByKey.has(key))
+                continue;
+            if (!sameConfigValue(latestByKey.get(key), originalItem))
+                setupConflict([...pathParts, key]);
+        }
+        for (const item of latestItems) {
+            const key = configArrayItemKey(item);
+            if (!originalByKey.has(key) && !desiredByKey.has(key))
+                result.push(item);
+        }
+        return result;
+    }
+    if (!isPlainRecord(original) || !isPlainRecord(desired)) {
+        if (!sameConfigValue(latest, original) && !sameConfigValue(latest, desired))
+            setupConflict(pathParts);
+        return desired;
+    }
+    if (latest !== undefined && !isPlainRecord(latest))
+        setupConflict(pathParts);
+    const result = isPlainRecord(latest) ? { ...latest } : {};
+    for (const key of new Set([...Object.keys(original), ...Object.keys(desired)])) {
+        if (!Object.hasOwn(desired, key)) {
+            if (Object.hasOwn(result, key) && !sameConfigValue(result[key], original[key]))
+                setupConflict([...pathParts, key]);
+            delete result[key];
+            continue;
+        }
+        result[key] = rebaseSetupChanges(original[key], desired[key], result[key], [...pathParts, key]);
+    }
+    return result;
+}
+async function saveSetupConfig(original, desired, precommit) {
+    const result = await mutateConfigWithPrecommit((latest) => rebaseSetupChanges(original, desired, latest), precommit);
+    return { config: result.config, precommit: result.precommit };
+}
+/** Registry-managed bundles are not editable through setup's source picker. */
+function managedBundleIds() {
+    return new Set(readLockfile().map((entry) => entry.id));
+}
+function setupSourceDescriptor(source) {
+    switch (source.type) {
+        case "filesystem":
+            return source.path ? { path: source.path } : undefined;
+        case "git":
+            return source.url ? { git: source.url } : undefined;
+        case "website":
+            return source.url ? { website: { url: source.url, ...(source.options ?? {}) } } : undefined;
+        case "npm":
+            return source.path ? { npm: source.path } : undefined;
+        default:
+            return undefined;
+    }
+}
+function selectsExistingBundle(source, id, bundle) {
+    const configured = bundleEntryToSourceEntry(id, bundle);
+    return (configured !== undefined &&
+        configured.type === source.type &&
+        configured.path === source.path &&
+        configured.url === source.url);
+}
+/** Convert only the wizard's private drafts, leaving current bundle entries intact. */
+function finalizeSetupDraft(draft) {
+    const { primaryPath, additionalSources, ...canonical } = draft;
+    const finalized = canonical;
+    if (primaryPath === undefined && additionalSources === undefined)
+        return finalized;
+    const bundles = { ...(draft.bundles ?? {}) };
+    const managedIds = managedBundleIds();
+    const newBundles = [];
+    if (additionalSources !== undefined) {
+        const selectedExistingIds = new Set();
+        for (const source of additionalSources) {
+            const existing = source.name ? bundles[source.name] : undefined;
+            if (source.name &&
+                source.name !== draft.defaultBundle &&
+                existing &&
+                selectsExistingBundle(source, source.name, existing)) {
+                selectedExistingIds.add(source.name);
+                continue;
+            }
+            const descriptor = setupSourceDescriptor(source);
+            if (!descriptor)
+                continue;
+            newBundles.push({
+                descriptor,
+                derivationPath: source.path ? path.resolve(source.path) : (source.url ?? ""),
+                preferredId: source.name,
+                primary: false,
+                writable: source.writable,
+            });
+        }
+        for (const id of Object.keys(bundles)) {
+            if (id === draft.defaultBundle || managedIds.has(id) || selectedExistingIds.has(id))
+                continue;
+            delete bundles[id];
+        }
+    }
+    let defaultBundle = draft.defaultBundle;
+    const configuredPrimaryPath = primaryBundlePath(draft);
+    if (primaryPath !== undefined &&
+        (configuredPrimaryPath === undefined || path.resolve(configuredPrimaryPath) !== path.resolve(primaryPath))) {
+        if (defaultBundle && !managedIds.has(defaultBundle))
+            delete bundles[defaultBundle];
+        defaultBundle = undefined;
+        newBundles.unshift({
+            descriptor: { path: primaryPath },
+            derivationPath: path.resolve(primaryPath),
+            primary: true,
+            writable: true,
+        });
+    }
+    const reserved = Object.keys(bundles).map((id) => ({ path: id, registryId: id }));
+    const ids = deriveBundleIds([
+        ...reserved,
+        ...newBundles.map((bundle) => ({ path: bundle.derivationPath, registryId: bundle.preferredId })),
+    ]).slice(reserved.length);
+    for (const [index, bundle] of newBundles.entries()) {
+        const id = ids[index];
+        bundles[id] = {
+            ...bundle.descriptor,
+            ...(bundle.writable !== undefined ? { writable: bundle.writable } : {}),
+        };
+        if (bundle.primary)
+            defaultBundle = id;
+    }
+    if (Object.keys(bundles).length > 0)
+        finalized.bundles = bundles;
+    else
+        delete finalized.bundles;
+    if (defaultBundle !== undefined)
+        finalized.defaultBundle = defaultBundle;
+    else
+        delete finalized.defaultBundle;
+    return finalized;
+}
 /**
  * Quick connectivity check. Returns true if we can resolve a hostname
  * the user has already implicitly trusted within 3 seconds, false
@@ -145,14 +353,14 @@ export function buildSetupSteps(options) {
     const steps = [
         {
             id: "stash-dir",
-            label: "Stash Directory",
+            label: "Bundle Directory",
             nonInteractive: true,
             async run(ctx) {
                 const stashDir = await stepStashDir(ctx.config, {
                     nonInteractive: ctx.nonInteractive,
                     preferredDir: options.preferredStashDir,
                 });
-                ctx.apply({ stashDir });
+                ctx.apply({ primaryPath: stashDir });
             },
         },
         {
@@ -178,7 +386,7 @@ export function buildSetupSteps(options) {
                     return;
                 }
                 const llm = await stepLlm(ctx.config, ollamaEndpoint, ollamaChatModels, lmStudioResult, harnessConfigs);
-                ctx.apply(applyLegacyLlm(ctx.config, llm));
+                ctx.apply(writeLlmEngine(ctx.config, llm));
             },
         },
         {
@@ -200,17 +408,17 @@ export function buildSetupSteps(options) {
         },
         {
             id: "stash-sources",
-            label: "Stash Sources",
+            label: "Bundle Sources",
             async run(ctx) {
                 const stashes = await stepAddSources(ctx.config, { promptForAdditional: false });
-                const platforms = await stepAgentPlatforms({ ...ctx.config, sources: stashes });
+                const platforms = await stepAgentPlatforms({ ...ctx.config, additionalSources: stashes });
                 const merged = [...stashes];
                 for (const ps of platforms) {
                     if (!merged.some((s) => s.path === ps.path))
                         merged.push(ps);
                 }
                 const withAdditional = await stepAdditionalSources(merged);
-                ctx.apply({ sources: withAdditional.length > 0 ? withAdditional : undefined });
+                ctx.apply({ additionalSources: withAdditional });
             },
         },
         {
@@ -226,11 +434,10 @@ 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.");
                 }
-                // 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) };
+                // Apply detected engines to a synthetic config for the selection UI.
+                const synthConfig = deepMergeConfig(ctx.config, writeAgentEngines(ctx.config, result.agent));
                 const agent = await stepAgentSelection(synthConfig, result.detections);
-                ctx.apply(applyLegacyAgent(ctx.config, agent));
+                ctx.apply(writeAgentEngines(ctx.config, agent));
             },
         },
         {
@@ -241,34 +448,27 @@ export function buildSetupSteps(options) {
                 ctx.apply({ output });
             },
         },
-        {
-            id: "scheduled-tasks",
-            label: "Scheduled Tasks",
-            // Interactive-only: `akm init` / `--yes` skip this step so headless
-            // runs never enable a scheduled task (see issue #512).
-            async run() {
-                await stepDefaultImproveTasks();
-                await stepScheduledTasks();
-            },
-        },
+        // NOTE: the "Scheduled Tasks" step is deliberately NOT part of this list.
+        // It is the only wizard step with externally-visible side effects (task
+        // files + OS scheduler entries), so `runSetupWizard` runs it by hand AFTER
+        // the config is confirmed and persisted — see the call there. Keeping it
+        // out of the step list also preserves the issue #512 guard: the
+        // non-interactive entry points (`akm init` / `--yes`) run this list but
+        // never that step, so headless runs never enable a scheduled task.
     ];
     return { steps, outcome };
 }
 export async function runSetupWizard(opts) {
+    assertSetupConfigPreflight();
     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());
+    const resolvedStashDir = opts?.dir ? path.resolve(opts.dir) : (primaryBundlePath(current) ?? 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, setDefault: true });
-    }
     // Quick connectivity check — skip network-dependent steps when offline
     const online = await isOnline();
     if (!online) {
@@ -278,9 +478,9 @@ export async function runSetupWizard(opts) {
     // Aggregate environment detection — run once before any prompt and surface
     // a summary so the user sees what was auto-detected. NAMES only, never
     // API key values.
-    const detection = await detectEnvironment({ existingStashDir: current.stashDir });
+    const detection = await detectEnvironment({ existingStashDir: primaryBundlePath(current) });
     p.note(renderDetectionSummary(detection), "Detected environment");
-    // Interactive entry point for `--reset-recommended`: offer to apply the
+    // Interactive entry point for `runResetRecommended`: offer to apply the
     // opinionated, detection-derived defaults and skip the step-by-step wizard.
     const useRecommended = await prompt(() => p.confirm({
         message: "Apply recommended defaults from the detected environment (merged into your existing config)?",
@@ -313,35 +513,31 @@ 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(applyLegacyLlm(ctx.config, smallModelResult.llm));
+        ctx.apply(writeLlmEngine(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.
-        installed: current.installed,
-    };
+    ctx.apply(writeAgentEngines(ctx.config, agentConfig));
+    const newConfig = { ...ctx.config };
     const semanticSearchMode = outcome.semantic;
-    const stashDir = newConfig.stashDir ?? current.stashDir ?? getDefaultStashDir();
+    const stashDir = newConfig.primaryPath ?? primaryBundlePath(current) ?? getDefaultStashDir();
     const embedding = newConfig.embedding;
-    const llm = getDefaultLlmConfig(newConfig);
+    const llm = readCurrentLlmEngine(newConfig);
     const registries = newConfig.registries;
-    const allStashes = newConfig.sources ?? [];
+    const allStashes = newConfig.additionalSources ?? [];
     // Feature capability summary
-    const agentConfigured = Boolean(agentConfig);
+    const agentConfigured = Boolean(agentConfig && !agentConfig.disabled);
     printCapabilitySummary(smallModelResult.skipped, agentConfigured);
     // Confirm before saving
     const effectiveRegistries = registries ?? DEFAULT_CONFIG.registries ?? [];
     p.note([
-        `Stash directory:  ${stashDir}`,
+        `Bundle directory: ${stashDir}`,
         `Embedding:        ${embedding ? `${embedding.provider ?? "remote"} / ${embedding.model}` : "built-in local"}`,
         `LLM:              ${llm ? `${llm.provider ?? "remote"} / ${llm.model}` : "disabled"}`,
         `Semantic search:  ${semanticSearchMode.mode}`,
         `Registries:       ${effectiveRegistries.filter((r) => r.enabled !== false).length} enabled`,
-        `Stash sources:    ${allStashes.length}`,
-        `Agent default:    ${newConfig.defaults?.agent ?? "disabled"}`,
+        `Bundle sources:   ${allStashes.length}`,
+        `Agent default:    ${newConfig.defaults?.engine ?? "disabled"}`,
         `Output:           ${newConfig.output?.format ?? "json"} / ${newConfig.output?.detail ?? "brief"}`,
     ].join("\n"), "Configuration Summary");
     const shouldSave = await prompt(() => p.confirm({
@@ -350,22 +546,29 @@ export async function runSetupWizard(opts) {
     }));
     if (!shouldSave)
         bail();
-    // Save config
-    const cfgPath1 = getConfigPath();
-    backupAndAnnounce(cfgPath1);
-    saveConfig(newConfig);
+    const finalConfig = finalizeSetupDraft(newConfig);
+    validateCompleteConfig(finalConfig);
+    const { config: savedConfig } = await saveSetupConfig(current, finalConfig, async () => {
+        if (!opts?.noInit)
+            await akmInit({ dir: stashDir, setDefault: true, persistConfig: false });
+    });
+    // After config persistence, the task step reviews the plan and asks one
+    // explicit confirmation before changing task files or scheduler state.
+    // Non-interactive setup paths never reach this interactive-only step.
+    p.log.step("Scheduled Tasks");
+    await stepScheduledTasks();
     if (semanticSearchMode.mode === "off") {
         clearSemanticStatus();
     }
     if (semanticSearchMode.mode === "auto") {
         if (semanticSearchMode.prepareAssets) {
-            const ready = await prepareSemanticSearchAssets(newConfig);
+            const ready = await prepareSemanticSearchAssets(savedConfig);
             if (!ready.ok) {
                 writeSemanticStatus({
                     status: "blocked",
                     reason: ready.reason,
                     message: ready.message,
-                    providerFingerprint: deriveSemanticProviderFingerprint(newConfig.embedding),
+                    providerFingerprint: deriveSemanticProviderFingerprint(savedConfig.embedding),
                     lastCheckedAt: new Date().toISOString(),
                 });
                 p.log.warn("Semantic search remains set to auto, but is currently blocked. Re-run `akm index --full --verbose` once the issue is resolved.");
@@ -374,7 +577,7 @@ export async function runSetupWizard(opts) {
                 writeSemanticStatus({
                     status: "pending",
                     message: "Semantic prerequisites verified. Building the index to finish activation.",
-                    providerFingerprint: deriveSemanticProviderFingerprint(newConfig.embedding),
+                    providerFingerprint: deriveSemanticProviderFingerprint(savedConfig.embedding),
                     lastCheckedAt: new Date().toISOString(),
                 });
             }
@@ -383,7 +586,7 @@ export async function runSetupWizard(opts) {
             writeSemanticStatus({
                 status: "pending",
                 message: "Semantic search is enabled, but asset preparation was skipped.",
-                providerFingerprint: deriveSemanticProviderFingerprint(newConfig.embedding),
+                providerFingerprint: deriveSemanticProviderFingerprint(savedConfig.embedding),
                 lastCheckedAt: new Date().toISOString(),
             });
             p.log.info("Semantic search is set to auto, but asset preparation was skipped. Run `akm index --full --verbose` later to verify it.");
@@ -396,7 +599,7 @@ export async function runSetupWizard(opts) {
     try {
         const indexResult = await akmIndex({ stashDir });
         spin.stop(`Indexed ${indexResult.totalEntries} assets.`);
-        if (newConfig.semanticSearchMode === "auto") {
+        if (savedConfig.semanticSearchMode === "auto") {
             if (indexResult.verification.ok) {
                 p.log.success(indexResult.verification.message);
             }
@@ -411,12 +614,12 @@ export async function runSetupWizard(opts) {
     catch (err) {
         spin.stop("Indexing failed — you can run `akm index` manually later.");
         p.log.warn(String(err));
-        if (newConfig.semanticSearchMode === "auto") {
+        if (savedConfig.semanticSearchMode === "auto") {
             writeSemanticStatus({
                 status: "blocked",
                 reason: "index-failed",
                 message: String(err),
-                providerFingerprint: deriveSemanticProviderFingerprint(newConfig.embedding),
+                providerFingerprint: deriveSemanticProviderFingerprint(savedConfig.embedding),
                 lastCheckedAt: new Date().toISOString(),
             });
         }
@@ -433,57 +636,32 @@ export async function runSetupWizard(opts) {
             p.log.info("Reminder: Set your LLM API key via the AKM_LLM_API_KEY environment variable.");
         }
     }
-    p.outro(`Configuration saved to ${configPath}`);
+    p.outro(`Configuration saved to ${configPath}\n` +
+        'Next: `akm bundle add <source>`, `akm index`, `akm search "<query>"`, `akm help agents`');
 }
 // ── Non-interactive / scripting entry points ─────────────────────────────────
-/**
- * Back up an existing config file and print the real, timestamped backup
- * location (not a generic display string). On a fresh install where there is
- * nothing to back up, print a "nothing to back up" notice instead.
- */
-function backupAndAnnounce(configPath) {
-    const result = backupExistingConfig(configPath);
-    const message = result ? `Config backed up to ${result.timestamped}` : "No existing config to back up.";
-    // In JSON output mode the structured envelope (which already carries
-    // `configPath`) MUST be the only thing on stdout — `setup --yes | jq` is a
-    // supported scripting contract. @clack's `p.log.info` writes to stdout, which
-    // would corrupt that envelope, so route this human-progress notice to stderr
-    // when emitting JSON. Interactive/text runs keep the inline clack banner.
-    if (isJsonOutputMode()) {
-        process.stderr.write(`${message}\n`);
-    }
-    else {
-        p.log.info(message);
-    }
-}
-/**
- * True when the process-level output mode is JSON (the default machine format).
- * Defensive: setup is also invoked programmatically (tests) where the output
- * mode singleton may not be initialized — treat that as "not JSON" so the
- * human-readable clack banner is used.
- */
-function isJsonOutputMode() {
-    try {
-        return getOutputMode().format === "json";
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * 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, setDefault: true });
+    assertSetupConfigPreflight();
+    const explicitStashDir = opts.dir != null ? path.resolve(opts.dir) : undefined;
+    // R-066 #4: a second `assertSetupSandbox(stashDir, explicitStashDir != null)`
+    // + `applyStashIsolationToEnv(stashDir, explicitStashDir != null)` pair used
+    // to follow `stashDir`'s resolution below. It was strictly redundant: unlike
+    // `runSetupFromConfig` (which can also derive an explicit stash dir from an
+    // incoming config file's bundle path, a case the early block below can't
+    // see yet), `runSetupWithDefaults` has only one source of an explicit dir —
+    // `opts.dir` — so `stashDir` always equals `explicitStashDir` whenever the
+    // `if` below ran, and always fails `dirExplicitlyProvided` (an immediate
+    // no-op in both helpers) whenever it didn't. Removed rather than duplicated.
+    if (explicitStashDir) {
+        assertSetupSandbox(explicitStashDir, true);
+        applyStashIsolationToEnv(explicitStashDir, true);
     }
+    const current = loadUserConfig();
+    const stashDir = explicitStashDir ?? primaryBundlePath(current) ?? getDefaultStashDir();
     // Run steps in non-interactive mode (applies defaults, skips prompts)
     const ctx = createSetupContext(current, { nonInteractive: true });
     const { steps } = buildSetupSteps({
@@ -492,18 +670,17 @@ export async function runSetupWithDefaults(opts) {
         preferredStashDir: stashDir,
     });
     await runSetupSteps(steps, ctx);
-    // Ensure stashDir is set
-    if (!ctx.config.stashDir)
-        ctx.apply({ stashDir });
+    if (!ctx.config.primaryPath)
+        ctx.apply({ primaryPath: stashDir });
     // Aggregate environment detection — apply detected values directly.
-    const env = await detectEnvironment({ existingStashDir: ctx.config.stashDir });
+    const env = await detectEnvironment({ existingStashDir: ctx.config.primaryPath });
     // Apply a detected LLM (live local server) when the config has none yet.
-    if (!getDefaultLlmConfig(ctx.config)) {
+    if (!readCurrentLlmEngine(ctx.config) && opts.probe) {
         const liveLocal = env.localServers.find((s) => s.available && s.defaultModel);
         if (liveLocal?.defaultModel) {
             const llm = {
                 provider: "local",
-                endpoint: `${liveLocal.baseUrl.replace(/\/$/, "")}/v1`,
+                endpoint: `${liveLocal.baseUrl.replace(/\/$/, "")}/v1/chat/completions`,
                 model: liveLocal.defaultModel,
             };
             // A required field being unresolvable must fail loudly rather than write
@@ -511,11 +688,22 @@ export async function runSetupWithDefaults(opts) {
             if (!llm.endpoint?.trim() || !llm.model?.trim()) {
                 throw new UsageError("Detected a local LLM server but could not resolve a required field (endpoint/model). Re-run `akm setup` interactively.", "MISSING_REQUIRED_ARGUMENT");
             }
-            ctx.apply(applyLegacyLlm(ctx.config, llm));
+            const verified = await verifyOpenAiCompatibleEndpoint(llm);
+            if (verified.ok) {
+                const applied = upsertDetectedLlmEngine(ctx.config, {
+                    provider: llm.provider ?? "local",
+                    endpoint: verified.endpoint,
+                    model: llm.model,
+                });
+                ctx.apply(applied.config);
+            }
+            else {
+                warn(`[akm setup] Skipping detected local LLM: ${verified.reason}. Verify it and rerun setup.`);
+            }
         }
     }
     // Auto-detect agent CLI if not already configured
-    if (!ctx.config.defaults?.agent) {
+    if (!ctx.config.defaults?.engine) {
         let defaultProfile;
         if (env.harness !== "none") {
             defaultProfile = env.harness;
@@ -525,31 +713,33 @@ export async function runSetupWithDefaults(opts) {
             defaultProfile = pickDefaultAgentProfile(detected, undefined);
         }
         if (defaultProfile) {
-            ctx.apply(applyLegacyAgent(ctx.config, { default: defaultProfile }));
+            ctx.apply(upsertDetectedAgentEngine(ctx.config, defaultProfile).config);
         }
     }
-    const cfgPath2 = getConfigPath();
-    backupAndAnnounce(cfgPath2);
-    saveConfig(ctx.config);
+    const finalConfig = finalizeSetupDraft(ctx.config);
+    validateCompleteConfig(finalConfig);
+    const { precommit: initResult } = await saveSetupConfig(current, finalConfig, async () => {
+        if (opts.noInit)
+            return undefined;
+        return akmInit({ dir: stashDir, setDefault: true, persistConfig: false });
+    });
     return {
         configPath: getConfigPath(),
-        stashDir,
+        bundleDir: stashDir,
         stashCreated: initResult?.created ?? false,
         written: true,
-        fields: Object.keys(ctx.config).filter((k) => ctx.config[k] !== undefined),
-        ripgrep: initResult?.ripgrep,
+        fields: Object.keys(finalConfig).filter((k) => finalConfig[k] !== undefined),
     };
 }
 /**
  * Run ONLY environment detection and return the typed result. Performs no
- * config writes and shows no prompts. Backs `akm setup --detect-only`.
+ * config writes and shows no prompts.
  *
  * SAFETY: The returned object carries env var NAMES only — never any API key
  * value.
  */
 export async function runDetectOnly() {
-    const current = loadUserConfig();
-    return detectEnvironment({ existingStashDir: current.stashDir });
+    return detectEnvironment();
 }
 /**
  * Derive opinionated defaults from a detection result.
@@ -557,9 +747,8 @@ export async function runDetectOnly() {
  * - Best harness → agent default (when a profile maps to it).
  * - Fastest live local model, else the first detected cloud key's provider.
  * - `nomic-embed-text` embeddings when a local LLM is live.
- * - improve task `0 2 * * *`, index task `0 4 * * *`.
  *
- * Returns a partial `AkmConfig`-shaped object plus a legacy `llm` block, ready
+ * Returns a partial `AkmConfig`-shaped object plus an LLM connection block, ready
  * to merge. Never includes an API key value.
  */
 export function deriveRecommendedConfig(env) {
@@ -590,31 +779,59 @@ export function deriveRecommendedConfig(env) {
             const defaults = PROVIDER_DEFAULTS[cloud.provider];
             if (defaults) {
                 result.llm = { provider: cloud.provider, endpoint: defaults.endpoint, model: defaults.model };
+                result.llmApiKeyEnvVar = cloud.envVar;
             }
         }
     }
-    result.taskSchedules = { improve: "0 2 * * *", index: "0 4 * * *" };
     return result;
 }
 /**
- * `akm setup --reset-recommended`: merge opinionated, detection-derived
- * defaults into the existing config WITHOUT removing pre-existing custom keys.
- * Uses the same merge path as {@link runSetupFromConfig} so custom keys survive
- * (follows #511 semantics).
+ * Merge opinionated, detection-derived defaults into the existing config
+ * WITHOUT removing pre-existing custom keys. Backs the interactive wizard's
+ * "apply recommended defaults" prompt. Uses the same merge path as
+ * {@link runSetupFromConfig} so custom keys survive (follows #511 semantics).
  */
 export async function runResetRecommended(opts) {
+    assertSetupConfigPreflight();
+    const explicitStashDir = opts.dir != null ? path.resolve(opts.dir) : undefined;
+    if (explicitStashDir) {
+        assertSetupSandbox(explicitStashDir, true);
+        applyStashIsolationToEnv(explicitStashDir, true);
+    }
     const current = loadUserConfig();
-    const env = await detectEnvironment({ existingStashDir: current.stashDir });
+    const env = await detectEnvironment({ existingStashDir: primaryBundlePath(current) });
     const recommended = deriveRecommendedConfig(env);
-    const incoming = {};
-    if (recommended.llm)
-        incoming.llm = recommended.llm;
+    let incoming = {};
+    if (recommended.llm && recommended.llm.provider !== "anthropic") {
+        let endpoint = recommended.llm.endpoint;
+        let accepted = true;
+        if (opts.probe) {
+            const verified = await verifyOpenAiCompatibleEndpoint({
+                endpoint,
+                model: recommended.llm.model,
+                apiKeyEnvVar: recommended.llmApiKeyEnvVar,
+            });
+            if (verified.ok) {
+                endpoint = verified.endpoint;
+            }
+            else {
+                accepted = false;
+                warn(`[akm setup] Skipping detected LLM: ${verified.reason}. Verify it and rerun setup.`);
+            }
+        }
+        if (accepted) {
+            incoming = upsertDetectedLlmEngine(incoming, {
+                provider: recommended.llm.provider ?? "local",
+                endpoint,
+                model: recommended.llm.model,
+                apiKeyEnvVar: recommended.llmApiKeyEnvVar,
+            }).config;
+        }
+    }
     if (recommended.embedding)
         incoming.embedding = recommended.embedding;
-    if (recommended.agentDefault)
-        incoming.agent = { default: recommended.agentDefault };
-    if (recommended.taskSchedules) {
-        incoming.setup = { taskSchedules: recommended.taskSchedules };
+    if (recommended.agentDefault) {
+        incoming = deepMergeConfig(incoming, writeAgentEngines(incoming, { default: recommended.agentDefault }));
     }
     return runSetupFromConfig({
         configJson: JSON.stringify(incoming),
@@ -628,25 +845,38 @@ export async function runResetRecommended(opts) {
  * Validates required sub-fields and strips unknown/restricted keys.
  */
 export async function runSetupFromConfig(opts) {
-    let incoming;
+    assertSetupConfigPreflight();
+    // Phase 1: Parse JSON
+    let parsed;
     try {
-        incoming = JSON.parse(opts.configJson);
+        parsed = JSON.parse(opts.configJson);
     }
     catch (e) {
         throw new Error(`Invalid JSON in --config: ${e.message}`);
     }
+    if (!isPlainRecord(parsed)) {
+        throw new ConfigError("Setup config must contain a top-level object.", "INVALID_CONFIG_FILE");
+    }
+    const incoming = parsed;
     // Phase 2: Validate — only allow safe top-level keys
-    const ALLOWED_KEYS = new Set([
-        "stashDir",
-        "llm",
-        "embedding",
-        "agent",
-        "semanticSearchMode",
-        "output",
-        "profiles",
-        "defaults",
-        "setup",
-    ]);
+    for (const key of ["stashDir", "sources", "installed"]) {
+        if (key in incoming) {
+            throw new ConfigError(`${key} is not supported by the current config schema; run the standalone akm-migrate tool first.`, "INVALID_CONFIG_FILE");
+        }
+    }
+    // Derived from AkmConfigShape (via `listTopLevelConfigKeys`) rather than a
+    // hand-copied set: a hand-copied allowlist silently fell out of sync as the
+    // schema grew (R-017 — `index`, `search`, `feedback`, `archiveRetentionDays`,
+    // `workflow`, and `experimental` were all valid schema keys that this list
+    // forgot, each dropped with only a warning while the command exited 0).
+    // Every key the schema recognizes is a legitimate thing to set via
+    // `--config`/`--from`; there is no key a user can set here that they
+    // couldn't set by hand-editing config.json and letting `akm config set`
+    // validate it. Keys that remain genuinely retired (`profiles`, `llm`,
+    // `agent`, `features`, `stashes`, `bindings`, `writable`) are not part of
+    // the schema shape, so they still fall into the warn-and-drop branch below;
+    // `stashDir`/`sources`/`installed` get the more specific migration error above.
+    const ALLOWED_KEYS = new Set(listTopLevelConfigKeys());
     for (const key of Object.keys(incoming)) {
         if (!ALLOWED_KEYS.has(key)) {
             warn(`[akm setup] Ignoring unknown or restricted config key: "${key}"`);
@@ -654,12 +884,6 @@ export async function runSetupFromConfig(opts) {
         }
     }
     // 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");
@@ -667,34 +891,45 @@ export async function runSetupFromConfig(opts) {
             throw new Error("embedding.model is required when embedding is provided");
     }
     // Phase 3: Merge with existing config
+    //
+    // R-066 #4 (verified, NOT reduced — unlike the `runSetupWithDefaults` pair
+    // above, this one is NOT strictly redundant): the `assertSetupSandbox` +
+    // `applyStashIsolationToEnv` pair below looks like a duplicate of the pair
+    // here, but each guards a case the other cannot:
+    //   - THIS early pair must run before `loadUserConfig()` so an explicit
+    //     `--dir` pointed at a force-escaped transient sandbox isolates the
+    //     config READ too, not just the later write (the isolation env var has
+    //     to be set before `loadUserConfig()` executes, or `current` below is
+    //     read from the host config instead of the sandboxed one — the exact
+    //     failure class the "2026-05-23 setup-clobbers-user-config incident"
+    //     comment on `assertSetupSandbox` describes).
+    //   - The LATER pair below additionally covers a case this one can't see
+    //     yet: an incoming `--config`/`--file` JSON blob that names its own
+    //     bundle path (`incomingPrimaryPath`) with no `--dir` at all — that
+    //     path is only known after the merge, so it cannot be checked early.
+    // When `explicitStashDir` is set both pairs do end up asserting the same
+    // (stashDir, true), but removing either one changes behavior in the case
+    // it uniquely covers, so both stay.
+    const explicitStashDir = opts.dir != null ? path.resolve(opts.dir) : undefined;
+    if (explicitStashDir) {
+        assertSetupSandbox(explicitStashDir, true);
+        applyStashIsolationToEnv(explicitStashDir, true);
+    }
     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;
+    let merged = deepMergeConfig(current, incoming);
+    const incomingPrimaryPath = primaryBundlePath(incoming);
+    const configuredPrimaryPath = primaryBundlePath(merged);
+    const stashDir = explicitStashDir ?? configuredPrimaryPath ?? getDefaultStashDir();
+    const stashDirExplicit = explicitStashDir != null || incomingPrimaryPath !== undefined;
     assertSetupSandbox(stashDir, stashDirExplicit);
     applyStashIsolationToEnv(stashDir, stashDirExplicit);
-    let merged = { ...current, stashDir };
-    // Deep-merge non-llm/agent keys: nested objects merge key-by-key so a
+    if (explicitStashDir !== undefined || configuredPrimaryPath === undefined) {
+        merged = deepMergeConfig(merged, { primaryPath: stashDir });
+    }
+    // Deep-merge canonical keys: nested objects merge key-by-key so a
     // partial `--file` only updates the keys it carries and never drops sibling
     // subkeys (e.g. output.detail survives an output.format-only file). Arrays
     // and scalars replace wholesale.
-    for (const key of Object.keys(incoming)) {
-        if (key === "llm" || key === "agent")
-            continue;
-        const incomingVal = incoming[key];
-        const mergedRec = merged;
-        mergedRec[key] = deepMergeConfig(mergedRec[key], incomingVal);
-    }
-    // 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) };
-    }
     // With `--yes`, fill keys still missing after the merge with non-interactive
     // defaults. Steps start from `merged` and their nonInteractive path only
     // populates absent values, so nothing the file or existing config supplied
@@ -707,31 +942,30 @@ export async function runSetupFromConfig(opts) {
             preferredStashDir: stashDir,
         });
         await runSetupSteps(steps, ctx);
-        if (!ctx.config.stashDir)
-            ctx.apply({ stashDir });
-        if (!ctx.config.defaults?.agent) {
+        if (!ctx.config.primaryPath)
+            ctx.apply({ primaryPath: stashDir });
+        if (!ctx.config.defaults?.engine) {
             const detected = detectAgentCliProfiles(undefined);
             const defaultProfile = pickDefaultAgentProfile(detected, undefined);
             if (defaultProfile) {
-                ctx.apply(applyLegacyAgent(ctx.config, { default: defaultProfile }));
+                ctx.apply(upsertDetectedAgentEngine(ctx.config, defaultProfile).config);
             }
         }
         merged = ctx.config;
     }
-    // Bootstrap directory structure
-    let initResult;
-    if (!opts.noInit) {
-        initResult = await akmInit({ dir: stashDir, setDefault: true });
-    }
+    // Convert the private setup draft to the persisted bundle shape.
+    let finalizedMerged = finalizeSetupDraft(merged);
+    // Reject an invalid merged engine graph before probing or touching the stash.
+    validateCompleteConfig(finalizedMerged);
     // Optional probe
-    const mergedLlm = getDefaultLlmConfig(merged);
+    const mergedLlm = readCurrentLlmEngine(finalizedMerged);
     if (opts.probe && mergedLlm) {
         try {
             const caps = await probeLlmCapabilities(mergedLlm);
             if (caps.reachable) {
-                merged = {
-                    ...merged,
-                    ...applyLegacyLlm(merged, {
+                finalizedMerged = {
+                    ...finalizedMerged,
+                    ...writeLlmEngine(finalizedMerged, {
                         ...mergedLlm,
                         capabilities: { structuredOutput: caps.structuredOutput ?? false },
                     }),
@@ -742,16 +976,18 @@ export async function runSetupFromConfig(opts) {
             // Non-fatal: probe failure is informational only
         }
     }
-    const cfgPath3 = getConfigPath();
-    backupAndAnnounce(cfgPath3);
-    saveConfig(merged);
+    validateCompleteConfig(finalizedMerged);
+    const { precommit: initResult } = await saveSetupConfig(current, finalizedMerged, async () => {
+        if (opts.noInit)
+            return undefined;
+        return akmInit({ dir: stashDir, setDefault: true, persistConfig: false });
+    });
     return {
         configPath: getConfigPath(),
-        stashDir,
+        bundleDir: stashDir,
         stashCreated: initResult?.created ?? false,
         written: true,
         fields: Object.keys(incoming).filter((k) => incoming[k] !== undefined),
-        ripgrep: initResult?.ripgrep,
     };
 }
 // ── Setup --from <file> bootstrap helper ────────────────────────────────────