gnosys 5.11.3 → 5.12.0

package/dist/lib/setup.js

@@ -14,11 +14,16 @@ import fsSync from "fs";
 import path from "path";
 import os from "os";
 import { execSync } from "child_process";
-import { loadConfig, updateConfig, getProviderModel, } from "./config.js";
-import { validateModel } from "./modelValidation.js";
+import { loadConfig, updateConfig, resolveTaskModel, getProviderModel, } from "./config.js";
+import { isApiKeyValidationError, validateModel } from "./modelValidation.js";
+import { buildOpenRouterTiers, OPENROUTER_STATIC_TIERS, } from "./openrouterTiers.js";
+import { apiKeyServiceName, buildApiKeyRequirementsFromConfig, ensureApiKeys, getApiKeyForProviderFromConfig, providerNeedsApiKey, readFirstInChain, readStoredSecret, storeApiKeySecret, } from "./apiKeyVault.js";
 import { resolveActiveStorePath, ensureActiveStorePath } from "./setup/storePath.js";
 import { safeQuestion } from "./setup/ui/safePrompt.js";
+export { printStatus } from "./setup/ui/status.js";
 import { getClaudeDesktopConfigPath, getApiKeySkipHints } from "./platform.js";
+import { gnosysStdioMcpEntry, installStdioMcpJson, normalizeIdeKey, resolveGnosysMcpCommand, cursorMcpPaths, runCli, removeTomlSection, } from "./ideMcpInstall.js";
+import { runKeysSetup } from "./setupKeys.js";
 // ─── ANSI Colors ────────────────────────────────────────────────────────────
 const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
@@ -75,6 +80,7 @@ export const PROVIDER_TIERS = {
     lmstudio: [
         { name: "Default", model: "default", input: 0, output: 0, recommended: true },
     ],
+    openrouter: OPENROUTER_STATIC_TIERS,
     custom: [],
 };
 // ─── Dynamic Model Fetching (OpenRouter) ─────────────────────────────────────
@@ -94,7 +100,7 @@ const OPENROUTER_PREFIX_MAP = {
  * Fetch models from OpenRouter, cache for 24 hours, fall back to hardcoded.
  * Returns updated PROVIDER_TIERS for cloud providers only.
  */
-async function fetchDynamicModels() {
+export async function fetchDynamicModels() {
     // Check cache first
     try {
         const stat = await fs.stat(CACHE_FILE);
@@ -249,6 +255,7 @@ async function fetchDynamicModels() {
             }
             result[ourProvider] = tiers;
         }
+        result.openrouter = buildOpenRouterTiers(data.data);
         // Cache the result
         try {
             await fs.mkdir(path.dirname(CACHE_FILE), { recursive: true });
@@ -283,6 +290,7 @@ const PROVIDER_DISPLAY = {
     xai: "xAI (Grok)",
     mistral: "Mistral",
     lmstudio: "LM Studio (local, free)",
+    openrouter: "OpenRouter (free + paid models)",
     custom: "Custom (any OpenAI-compatible API)",
 };
 const PROVIDER_ENV_VAR = {
@@ -291,6 +299,7 @@ const PROVIDER_ENV_VAR = {
     groq: "GNOSYS_GROQ_KEY",
     xai: "GNOSYS_XAI_KEY",
     mistral: "GNOSYS_MISTRAL_KEY",
+    openrouter: "GNOSYS_OPENROUTER_KEY",
     custom: "GNOSYS_CUSTOM_KEY",
 };
 // Ordered list for the menu
@@ -302,16 +311,40 @@ const PROVIDER_ORDER = [
     "xai",
     "mistral",
     "lmstudio",
+    "openrouter",
     "custom",
 ];
 // Task descriptions for display
-const TASK_DESCRIPTIONS = {
+export const TASK_DESCRIPTIONS = {
     structuring: "adding memories, tagging",
     synthesis: "Q&A answers",
+    chat: "interactive chat TUI",
     vision: "images, PDFs",
     transcription: "audio files",
     dream: "overnight consolidation",
 };
+/** Tasks routed via taskModels in gnosys.json */
+const ROUTABLE_TASK_LIST = [
+    "structuring",
+    "synthesis",
+    "vision",
+    "transcription",
+    "chat",
+];
+export const ASSIGNABLE_TASK_LIST = [
+    ...ROUTABLE_TASK_LIST,
+    "dream",
+];
+export function getAssignableRouting(cfg, task) {
+    if (task === "dream") {
+        const dreamProvider = (cfg.dream?.provider ?? "ollama");
+        return {
+            provider: dreamProvider,
+            model: cfg.dream?.model ?? getProviderModel(cfg, dreamProvider),
+        };
+    }
+    return resolveTaskModel(cfg, task);
+}
 // ─── Exported Helpers ───────────────────────────────────────────────────────
 /**
  * Returns the cheapest capable model for structuring tasks.
@@ -333,8 +366,10 @@ export function getStructuringModel(provider, chosenModel) {
  * Creates the directory and file if they don't exist.
  * Replaces an existing key line if found, otherwise appends.
  */
-export async function writeApiKey(provider, key) {
-    const envVar = PROVIDER_ENV_VAR[provider];
+export async function writeApiKey(provider, key, opts) {
+    const envVar = opts?.scope === "global"
+        ? apiKeyServiceName(provider, "global")
+        : PROVIDER_ENV_VAR[provider];
     if (!envVar)
         return;
     const configDir = path.join(os.homedir(), ".config", "gnosys");
@@ -417,6 +452,68 @@ function hasSecretTool() {
         return false;
     }
 }
+/**
+ * Prompt for a replacement API key after validation fails, storing it in the
+ * platform secure store when available (Keychain / GNOME Keyring), else .env.
+ */
+async function promptAndStoreProviderApiKey(rl, provider, scope = "provider") {
+    if (provider === "ollama" || provider === "lmstudio" || provider === "skip") {
+        return null;
+    }
+    const service = apiKeyServiceName(provider, scope);
+    console.log();
+    console.log(`  ${WARN} Your API key may be expired or invalid.`);
+    console.log(`  ${DIM}Enter a new key — saved as ${service}${RESET}`);
+    console.log();
+    const key = await askInput(rl, `Enter your ${provider} API key`);
+    if (!key) {
+        return null;
+    }
+    if (storeApiKeySecret(service, key, provider)) {
+        const store = process.platform === "darwin" ? "macOS Keychain" : "GNOME Keyring";
+        console.log(`  ${CHECK} Key saved to ${store} (${maskKey(key)})`);
+        return key;
+    }
+    console.log(`  ${CROSS} Failed to write to secure store. Saving to ~/.config/gnosys/.env instead.`);
+    await writeApiKey(provider, key);
+    console.log(`  ${CHECK} Key saved to ~/.config/gnosys/.env (${maskKey(key)})`);
+    return key;
+}
+/**
+ * Run model validation; on API-key auth failures, offer to rotate the key and
+ * retry once before asking whether to save config anyway.
+ */
+async function validateModelWithKeyRotation(opts) {
+    const { Spinner } = await import("./setup/ui/spinner.js");
+    let apiKey = opts.apiKey;
+    const validateSpin = Spinner(`validating ${opts.provider} / ${opts.model}…`);
+    let result = await validateModel(opts.provider, opts.model, apiKey, {
+        customBaseUrl: opts.customBaseUrl,
+    });
+    if (result.ok) {
+        validateSpin.ok("model validated", `${result.latencyMs} ms · ${opts.provider} / ${opts.model}`);
+        return { proceed: true, apiKey };
+    }
+    validateSpin.fail("model test failed", result.error);
+    if (!opts.isLocalProvider &&
+        isApiKeyValidationError(result.error)) {
+        const newKey = await promptAndStoreProviderApiKey(opts.rl, opts.provider, opts.keyScope ?? "global");
+        if (newKey) {
+            apiKey = newKey;
+            const retrySpin = Spinner(`re-validating ${opts.provider} / ${opts.model}…`);
+            result = await validateModel(opts.provider, opts.model, apiKey, {
+                customBaseUrl: opts.customBaseUrl,
+            });
+            if (result.ok) {
+                retrySpin.ok("model validated", `${result.latencyMs} ms · ${opts.provider} / ${opts.model}`);
+                return { proceed: true, apiKey };
+            }
+            retrySpin.fail("model test failed", result.error);
+        }
+    }
+    const proceed = await askYesNo(opts.rl, opts.saveAnywayPrompt, opts.saveAnywayDefault);
+    return { proceed, apiKey };
+}
 /**
  * Detect where an existing API key is stored.
  * Returns description like "macOS Keychain", "env var", ".env file", or empty string.
@@ -567,24 +664,6 @@ export async function detectIDEs(projectDir) {
     }
     return detected;
 }
-/** Remove a single `[section]` block from Grok TOML (hand-rolled; see upsertGrokMcpBlock). */
-function removeGrokTomlSection(existing, sectionHeader) {
-    const lines = existing.split("\n");
-    const headerIdx = lines.findIndex((line) => line.trim() === sectionHeader);
-    if (headerIdx === -1)
-        return existing;
-    let endIdx = lines.length;
-    for (let i = headerIdx + 1; i < lines.length; i++) {
-        if (/^\s*\[/.test(lines[i])) {
-            endIdx = i;
-            break;
-        }
-    }
-    const before = lines.slice(0, headerIdx).join("\n");
-    const after = lines.slice(endIdx).join("\n");
-    const merged = [before, after].filter((s) => s.length > 0).join("\n");
-    return merged.length > 0 ? `${merged}\n` : "";
-}
 /**
  * Replace (or append) a `[mcp_servers.<name>]` block inside Grok Build's
  * `~/.grok/config.toml`. Preserves every line outside that block (deci-046).
@@ -596,7 +675,7 @@ function removeGrokTomlSection(existing, sectionHeader) {
  */
 export function upsertGrokMcpBlock(existing, name, entry) {
     // Drop mistaken v5.9.4 `[mcp.<name>]` sections so we don't leave dead config.
-    let content = removeGrokTomlSection(existing, `[mcp.${name}]`);
+    let content = removeTomlSection(existing, `[mcp.${name}]`);
     const sectionHeader = `[mcp_servers.${name}]`;
     const lines = content.split("\n");
     const headerIdx = lines.findIndex((line) => line.trim() === sectionHeader);
@@ -632,25 +711,6 @@ export function upsertGrokMcpBlock(existing, name, entry) {
     const afterBlock = afterLines.join("\n");
     return `${head}${sectionHeader}\n${blockBody}${gap}${afterBlock}`;
 }
-/**
- * Absolute path to the `gnosys-mcp` stdio entry (dist/index.js).
- * Prefer this over `gnosys serve` — v5.11.0 `gnosys serve` imported index.js but
- * did not call startMcpServer(), so MCP hosts saw "connection closed" on init.
- */
-function resolveGnosysMcpCommand() {
-    try {
-        const p = execSync("command -v gnosys-mcp", { encoding: "utf-8" }).trim();
-        if (p)
-            return p;
-    }
-    catch {
-        // Fall back to bare name on PATH.
-    }
-    return "gnosys-mcp";
-}
-function gnosysMcpServerEntry() {
-    return { command: resolveGnosysMcpCommand(), args: [] };
-}
 function renderGrokMcpBlock(entry) {
     const argsStr = `[${entry.args.map((a) => JSON.stringify(a)).join(", ")}]`;
     const lines = [
@@ -666,48 +726,45 @@ function renderGrokMcpBlock(entry) {
  * Set up Gnosys MCP integration for a specific IDE.
  */
 export async function setupIDE(ide, projectDir) {
+    const canonical = normalizeIdeKey(ide);
+    if (!canonical) {
+        return { success: false, message: `Unknown IDE: ${ide}` };
+    }
     try {
-        switch (ide) {
+        switch (canonical) {
             case "claude": {
                 const mcpCmd = resolveGnosysMcpCommand();
+                let codeMsg = `Claude Code MCP registered (${mcpCmd})`;
                 try {
-                    try {
-                        execSync("claude mcp remove gnosys", { stdio: "pipe" });
-                    }
-                    catch {
-                        // Not registered yet — fine.
-                    }
-                    execSync(`claude mcp add -s user gnosys -- ${mcpCmd}`, {
-                        stdio: "pipe",
-                    });
+                    runCli("claude", ["mcp", "remove", "gnosys"], { allowFailure: true });
+                    runCli("claude", ["mcp", "add", "-s", "user", "gnosys", "--", mcpCmd]);
                 }
                 catch (e) {
                     const msg = e instanceof Error ? e.message : String(e);
                     if (msg.includes("already exists")) {
-                        return { success: true, message: "Claude Code MCP server already configured" };
+                        codeMsg = "Claude Code MCP server already configured";
+                    }
+                    else {
+                        codeMsg = `Claude Code MCP skipped (is \`claude\` on PATH?): ${msg}`;
                     }
-                    throw e;
                 }
-                return { success: true, message: `Claude Code MCP server registered (${mcpCmd})` };
+                const desktop = await setupIDE("claude-desktop", projectDir);
+                return {
+                    success: desktop.success,
+                    message: desktop.success
+                        ? `${codeMsg}; ${desktop.message}`
+                        : `${codeMsg}; Claude Desktop: ${desktop.message}`,
+                };
             }
             case "cursor": {
-                const cursorDir = path.join(projectDir, ".cursor");
-                const mcpPath = path.join(cursorDir, "mcp.json");
-                await fs.mkdir(cursorDir, { recursive: true });
-                let config = {};
-                try {
-                    const existing = await fs.readFile(mcpPath, "utf-8");
-                    config = JSON.parse(existing);
-                }
-                catch {
-                    // File doesn't exist or is invalid — start fresh
-                }
-                // Merge gnosys entry
-                const servers = (config.mcpServers ?? {});
-                servers.gnosys = gnosysMcpServerEntry();
-                config.mcpServers = servers;
-                await fs.writeFile(mcpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
-                return { success: true, message: "Cursor MCP config updated (.cursor/mcp.json)" };
+                const paths = cursorMcpPaths(projectDir);
+                await fs.mkdir(path.dirname(paths.project), { recursive: true });
+                await installStdioMcpJson(paths.project);
+                await installStdioMcpJson(paths.user);
+                return {
+                    success: true,
+                    message: "Cursor MCP updated (project .cursor/mcp.json and ~/.cursor/mcp.json)",
+                };
             }
             case "codex": {
                 // v5.8.5: register via `codex mcp add` (the real Codex CLI registration
@@ -719,19 +776,13 @@ export async function setupIDE(ide, projectDir) {
                 //
                 // We also migrate away from those legacy blocks in
                 // `~/.codex/config.toml` so users on stale configs get cleaned up.
-                const os = await import("os");
-                // 1. Migrate (strip) legacy hand-written blocks in ~/.codex/config.toml.
+                // 1. Strip legacy hand-written sections in ~/.codex/config.toml.
                 const userCodexConfig = path.join(os.homedir(), ".codex", "config.toml");
                 try {
                     let existing = await fs.readFile(userCodexConfig, "utf-8");
-                    const before = existing;
-                    // Old shape (pre-v5.8.4): [gnosys] command/args
-                    existing = existing.replace(/\n?\[gnosys\][^[]*?command\s*=\s*"gnosys"[^[]*?args\s*=\s*\[[^\]]*\]\s*\n?/, "\n");
-                    // v5.8.4 shape: [mcp.gnosys] type/command
-                    existing = existing.replace(/\n?\[mcp\.gnosys\][^[]*?type\s*=\s*"local"[^[]*?command\s*=\s*\[[^\]]*\]\s*\n?/, "\n");
-                    if (existing !== before) {
-                        existing = existing.replace(/\n{3,}/g, "\n\n");
-                        await fs.writeFile(userCodexConfig, existing, "utf-8");
+                    const cleaned = removeTomlSection(removeTomlSection(existing, "[mcp.gnosys]"), "[gnosys]");
+                    if (cleaned !== existing) {
+                        await fs.writeFile(userCodexConfig, cleaned, "utf-8");
                     }
                 }
                 catch {
@@ -744,25 +795,16 @@ export async function setupIDE(ide, projectDir) {
                 //    remove and re-add.
                 let alreadyCorrect = false;
                 try {
-                    const existing = execSync("codex mcp get gnosys 2>/dev/null", {
-                        encoding: "utf-8",
-                    });
+                    const existing = runCli("codex", ["mcp", "get", "gnosys"], { allowFailure: true });
                     if (existing && existing.includes(gnosysCmd) && !existing.includes(" serve")) {
                         alreadyCorrect = true;
                     }
                     else if (existing) {
-                        // Different command — remove so we can re-add with the right one.
-                        try {
-                            execSync("codex mcp remove gnosys", { stdio: "pipe" });
-                        }
-                        catch {
-                            // Non-fatal — `mcp add` below will overwrite or fail loudly.
-                        }
+                        runCli("codex", ["mcp", "remove", "gnosys"], { allowFailure: true });
                     }
                 }
                 catch {
-                    // `codex mcp get` returns non-zero when the server isn't registered —
-                    // that's the common case on first install; proceed to add.
+                    // `codex mcp get` failed — proceed to add.
                 }
                 if (alreadyCorrect) {
                     return {
@@ -772,7 +814,7 @@ export async function setupIDE(ide, projectDir) {
                 }
                 // 4. Register via the canonical Codex CLI command.
                 try {
-                    execSync(`codex mcp add gnosys -- ${gnosysCmd}`, { stdio: "pipe" });
+                    runCli("codex", ["mcp", "add", "gnosys", "--", gnosysCmd]);
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
@@ -789,43 +831,19 @@ export async function setupIDE(ide, projectDir) {
                 };
             }
             case "gemini-cli": {
-                // Gemini CLI reads MCP servers from ~/.gemini/settings.json (user-level)
-                const geminiDir = path.join(os.homedir(), ".gemini");
-                const settingsPath = path.join(geminiDir, "settings.json");
-                await fs.mkdir(geminiDir, { recursive: true });
-                let config = {};
-                try {
-                    const existing = await fs.readFile(settingsPath, "utf-8");
-                    config = JSON.parse(existing);
-                }
-                catch {
-                    // File doesn't exist or is invalid — start fresh
-                }
-                const servers = (config.mcpServers ?? {});
-                servers.gnosys = gnosysMcpServerEntry();
-                config.mcpServers = servers;
-                await fs.writeFile(settingsPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+                const settingsPath = path.join(os.homedir(), ".gemini", "settings.json");
+                await fs.mkdir(path.dirname(settingsPath), { recursive: true });
+                await installStdioMcpJson(settingsPath);
                 return { success: true, message: "Gemini CLI MCP config updated (~/.gemini/settings.json)" };
             }
             case "antigravity": {
-                // Antigravity reads MCP servers from ~/.gemini/antigravity/mcp_config.json
-                // (separate file from Gemini CLI's settings.json, even though they share the parent dir)
-                const antigravityDir = path.join(os.homedir(), ".gemini", "antigravity");
-                const configPath = path.join(antigravityDir, "mcp_config.json");
-                await fs.mkdir(antigravityDir, { recursive: true });
-                let config = {};
-                try {
-                    const existing = await fs.readFile(configPath, "utf-8");
-                    config = JSON.parse(existing);
-                }
-                catch {
-                    // File doesn't exist or is invalid — start fresh
-                }
-                const servers = (config.mcpServers ?? {});
-                servers.gnosys = gnosysMcpServerEntry();
-                config.mcpServers = servers;
-                await fs.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
-                return { success: true, message: "Antigravity MCP config updated (~/.gemini/antigravity/mcp_config.json)" };
+                const configPath = path.join(os.homedir(), ".gemini", "antigravity", "mcp_config.json");
+                await fs.mkdir(path.dirname(configPath), { recursive: true });
+                await installStdioMcpJson(configPath);
+                return {
+                    success: true,
+                    message: "Antigravity MCP config updated (~/.gemini/antigravity/mcp_config.json)",
+                };
             }
             case "grok-build": {
                 // v5.9.4 Bug 12 — Grok Build reads MCP from `[mcp_servers.<name>]`
@@ -842,32 +860,16 @@ export async function setupIDE(ide, projectDir) {
                     // File doesn't exist yet — start fresh
                 }
                 const updated = upsertGrokMcpBlock(existing, "gnosys", {
-                    ...gnosysMcpServerEntry(),
+                    ...gnosysStdioMcpEntry(),
                     startup_timeout_sec: 90,
                 });
                 await fs.writeFile(configPath, updated, "utf-8");
                 return { success: true, message: "Grok Build MCP config updated (~/.grok/config.toml)" };
             }
             case "claude-desktop": {
-                // Claude Desktop reads MCP servers from claude_desktop_config.json
-                // in a platform-specific app data directory. Distinct from Claude
-                // Code CLI which uses `claude mcp add`.
                 const configPath = getClaudeDesktopConfigPath();
-                const configDir = path.dirname(configPath);
-                await fs.mkdir(configDir, { recursive: true });
-                let config = {};
-                try {
-                    const existing = await fs.readFile(configPath, "utf-8");
-                    config = JSON.parse(existing);
-                }
-                catch {
-                    // File doesn't exist or is invalid — start fresh
-                }
-                const servers = (config.mcpServers ?? {});
-                servers.gnosys = gnosysMcpServerEntry();
-                config.mcpServers = servers;
-                await fs.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
-                // Display path with ~ prefix when inside HOME for clarity
+                await fs.mkdir(path.dirname(configPath), { recursive: true });
+                await installStdioMcpJson(configPath);
                 const home = os.homedir();
                 const displayPath = configPath.startsWith(home)
                     ? configPath.replace(home, "~")
@@ -877,9 +879,8 @@ export async function setupIDE(ide, projectDir) {
                     message: `Claude Desktop MCP config updated (${displayPath}). Restart Claude Desktop for the change to take effect.`,
                 };
             }
-            default:
-                return { success: false, message: `Unknown IDE: ${ide}` };
         }
+        return { success: false, message: `Unhandled IDE: ${canonical}` };
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -912,16 +913,20 @@ async function askChoice(rl, question, options) {
 /**
  * Read a single line of input with an optional default value.
  */
-async function askInput(rl, prompt, opts) {
+export async function askInput(rl, prompt, opts) {
     const suffix = opts?.default ? ` ${DIM}(${opts.default})${RESET}` : "";
     const answer = await safeQuestion(rl, `${prompt}${suffix}: `);
     const trimmed = answer.trim();
     return trimmed || opts?.default || "";
 }
+export function printInfo(text, meta) {
+    const suffix = meta ? ` ${DIM}${meta}${RESET}` : "";
+    console.log(`  ${text}${suffix}`);
+}
 /**
  * Y/n prompt. Returns true for yes.
  */
-async function askYesNo(rl, question, defaultYes = true) {
+export async function askYesNo(rl, question, defaultYes = true) {
     const hint = defaultYes ? "Y/n" : "y/N";
     const answer = await safeQuestion(rl, `${question} [${hint}] `);
     const trimmed = answer.trim().toLowerCase();
@@ -929,6 +934,78 @@ async function askYesNo(rl, question, defaultYes = true) {
         return defaultYes;
     return trimmed === "y" || trimmed === "yes";
 }
+/**
+ * Read a password/API key without echoing it back to the terminal.
+ */
+export async function askPassword(rl, prompt) {
+    if (!stdin.isTTY || typeof stdin.setRawMode !== "function") {
+        return askInput(rl, prompt);
+    }
+    return new Promise((resolve) => {
+        let value = "";
+        stdout.write(`${prompt}: `);
+        stdin.setRawMode(true);
+        stdin.resume();
+        const cleanup = () => {
+            stdin.setRawMode(false);
+            stdin.off("data", onData);
+            stdout.write("\n");
+        };
+        const onData = (chunk) => {
+            const input = chunk.toString("utf-8");
+            for (const char of input) {
+                const code = char.charCodeAt(0);
+                if (code === 3) {
+                    cleanup();
+                    try {
+                        rl.close();
+                    }
+                    catch {
+                        // already closed
+                    }
+                    process.exit(130);
+                }
+                if (code === 13 || code === 10) {
+                    cleanup();
+                    resolve(value.trim());
+                    return;
+                }
+                if (code === 127 || code === 8) {
+                    value = value.slice(0, -1);
+                    continue;
+                }
+                value += char;
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+/** Parse `1,3,5`, `all`, or `none` into 0-based task indices. */
+export function parseCommaSeparatedTaskSelection(input, count) {
+    const trimmed = input.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    if (trimmed === "all" || trimmed === "*") {
+        return "all";
+    }
+    if (trimmed === "none" || trimmed === "-") {
+        return "none";
+    }
+    const indices = [];
+    for (const part of trimmed.split(/[,;\s]+/)) {
+        const n = parseInt(part.trim(), 10);
+        if (Number.isNaN(n) || n < 1 || n > count) {
+            return null;
+        }
+        if (!indices.includes(n - 1)) {
+            indices.push(n - 1);
+        }
+    }
+    return indices.length > 0 ? indices : null;
+}
+export function modelForTaskAssignment(task, provider, model) {
+    return task === "structuring" ? getStructuringModel(provider, model) : model;
+}
 /**
  * Format a price for display: "$0.80" or "free".
  */
@@ -1021,7 +1098,7 @@ async function loadExistingConfig(projectDir) {
  * Returns the provider name or "skip".
  * If currentProvider is given, shows it as the current value.
  */
-async function pickProvider(rl, dynamicModels, stepLabel, currentProvider) {
+export async function pickProvider(rl, dynamicModels, stepLabel, currentProvider) {
     const currentHint = currentProvider ? ` ${DIM}(current: ${currentProvider})${RESET}` : "";
     const providerOptions = PROVIDER_ORDER.map((key) => {
         const tiers = dynamicModels[key] ?? PROVIDER_TIERS[key];
@@ -1042,7 +1119,7 @@ async function pickProvider(rl, dynamicModels, stepLabel, currentProvider) {
  * Returns the model string. Includes a "Custom (enter model name)"
  * option so users can type any model ID not in the curated list.
  */
-async function pickModel(rl, provider, dynamicModels, stepLabel, currentModel) {
+export async function pickModel(rl, provider, dynamicModels, stepLabel, currentModel) {
     const tiers = dynamicModels[provider] ?? PROVIDER_TIERS[provider];
     if (!tiers || tiers.length === 0) {
         // No tiers available — fall back to direct entry
@@ -1066,8 +1143,10 @@ async function pickModel(rl, provider, dynamicModels, stepLabel, currentModel) {
     }
     return tiers[tierIndex].model;
 }
-// ─── Main Setup Wizard ──────────────────────────────────────────────────────
 export async function runSetup(opts) {
+    if (opts.section === "keys") {
+        return runKeysSetup();
+    }
     const version = getVersion();
     const projectDir = opts.directory ? path.resolve(opts.directory) : process.cwd();
     // ─── Non-interactive mode ─────────────────────────────────────────────
@@ -1294,6 +1373,7 @@ export async function runSetup(opts) {
             groq: "GROQ_API_KEY",
             xai: "XAI_API_KEY",
             mistral: "MISTRAL_API_KEY",
+            openrouter: "OPENROUTER_API_KEY",
         };
         const legacyEnvVar = legacyEnvVars[provider] ?? "";
         if (needsKey) {
@@ -1468,26 +1548,27 @@ export async function runSetup(opts) {
             console.log();
             console.log(`${DIM}Testing ${provider}/${model}...${RESET}`);
             try {
-                const { validateModel } = await import("./modelValidation.js");
                 const customBaseUrl = provider === "custom"
                     ? process.env.GNOSYS_LLM_BASE_URL
                     : undefined;
-                const result = await validateModel(provider, model, capturedApiKey, { customBaseUrl });
-                if (result.ok) {
-                    console.log(`  ${CHECK} Model validated (${result.latencyMs}ms)`);
-                }
-                else {
-                    console.log(`  ${WARN} Model test failed: ${result.error}`);
-                    const proceed = await askYesNo(rl, "  Continue anyway?", true);
-                    if (!proceed) {
-                        console.log(`  ${DIM}Setup paused. Re-run when ready: gnosys setup${RESET}`);
-                        setupCompleted = true;
-                        rl.close();
-                        return {
-                            provider, model, structuringModel: "",
-                            apiKeyWritten, ides: [], mode: "agent", upgraded,
-                        };
-                    }
+                const { proceed } = await validateModelWithKeyRotation({
+                    rl,
+                    provider,
+                    model,
+                    apiKey: capturedApiKey,
+                    customBaseUrl,
+                    isLocalProvider,
+                    saveAnywayPrompt: "  Continue anyway?",
+                    saveAnywayDefault: true,
+                });
+                if (!proceed) {
+                    console.log(`  ${DIM}Setup paused. Re-run when ready: gnosys setup${RESET}`);
+                    setupCompleted = true;
+                    rl.close();
+                    return {
+                        provider, model, structuringModel: "",
+                        apiKeyWritten, ides: [], mode: "agent", upgraded,
+                    };
                 }
             }
             catch (err) {
@@ -1766,6 +1847,18 @@ export async function runSetup(opts) {
                 await updateConfig(storePath, configUpdates);
                 console.log();
                 console.log(`  ${CHECK} Config written to ${storePath}/gnosys.json`);
+                const savedCfg = await loadConfig(storePath);
+                const keyReqs = buildApiKeyRequirementsFromConfig(savedCfg);
+                if (keyReqs.length > 0) {
+                    await ensureApiKeys(rl, keyReqs, askInput, {
+                        warn: WARN,
+                        check: CHECK,
+                        cross: CROSS,
+                        dim: DIM,
+                        reset: RESET,
+                        maskKey,
+                    });
+                }
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
@@ -1935,6 +2028,166 @@ export async function runProviderOnlySetup(opts = {}) {
             rl.close();
     }
 }
+/**
+ * Build API key requirements from the selected task set only (§3.7).
+ * One global key per distinct cloud provider in the selection.
+ */
+export function buildInlineKeyRequirements(selectedTasks, providerForTask) {
+    const providers = [
+        ...new Set(selectedTasks
+            .map((t) => providerForTask(t))
+            .filter((p) => providerNeedsApiKey(p))
+            .map((p) => p)),
+    ];
+    return providers.map((provider) => ({ provider, scope: "global" }));
+}
+/** Write or replace a single `NAME=value` line in ~/.config/gnosys/.env. */
+export async function writeServiceKeyToEnv(service, key) {
+    const configDir = path.join(os.homedir(), ".config", "gnosys");
+    await fs.mkdir(configDir, { recursive: true, mode: 0o700 });
+    await fs.chmod(configDir, 0o700);
+    const envPath = path.join(configDir, ".env");
+    let lines = [];
+    try {
+        lines = (await fs.readFile(envPath, "utf-8")).split("\n");
+    }
+    catch {
+        // fresh file
+    }
+    const prefix = `${service}=`;
+    let replaced = false;
+    lines = lines.map((line) => {
+        if (line.startsWith(prefix)) {
+            replaced = true;
+            return `${service}=${key}`;
+        }
+        return line;
+    });
+    if (!replaced) {
+        if (lines.length > 0 && lines[lines.length - 1] !== "") {
+            lines.push("");
+        }
+        lines.push(`${service}=${key}`);
+    }
+    await fs.writeFile(envPath, lines.join("\n"), { mode: 0o600 });
+    await fs.chmod(envPath, 0o600);
+}
+/**
+ * Validate a provider/model/key triple without persisting the key (§3.8).
+ * On auth failure, re-prompt for a replacement key in memory only.
+ */
+export async function validateTaskCombo(opts) {
+    const { Spinner } = await import("./setup/ui/spinner.js");
+    const reprompt = opts.repromptKey ??
+        (async (rl, provider) => {
+            console.log();
+            console.log(`  ${WARN} Your API key may be expired or invalid.`);
+            const key = await askInput(rl, `Enter your ${provider} API key`);
+            return key || null;
+        });
+    let apiKey = opts.apiKey;
+    const validateSpin = Spinner(`validating ${opts.provider} / ${opts.model}…`);
+    let result = await validateModel(opts.provider, opts.model, apiKey, {
+        customBaseUrl: opts.customBaseUrl,
+    });
+    if (result.ok) {
+        validateSpin.ok("model validated", `${result.latencyMs} ms · ${opts.provider} / ${opts.model}`);
+        return { proceed: true, apiKey };
+    }
+    validateSpin.fail("model test failed", result.error);
+    if (!opts.isLocalProvider && isApiKeyValidationError(result.error)) {
+        const newKey = await reprompt(opts.rl, opts.provider);
+        if (newKey) {
+            apiKey = newKey;
+            const retrySpin = Spinner(`re-validating ${opts.provider} / ${opts.model}…`);
+            result = await validateModel(opts.provider, opts.model, apiKey, {
+                customBaseUrl: opts.customBaseUrl,
+            });
+            if (result.ok) {
+                retrySpin.ok("model validated", `${result.latencyMs} ms · ${opts.provider} / ${opts.model}`);
+                return { proceed: true, apiKey };
+            }
+            retrySpin.fail("model test failed", result.error);
+        }
+    }
+    const proceed = await askYesNo(opts.rl, opts.saveAnywayPrompt ?? "Save routing anyway?", opts.saveAnywayDefault ?? false);
+    return { proceed, apiKey };
+}
+const LEGACY_PROVIDER_ENV = {
+    anthropic: "ANTHROPIC_API_KEY",
+    openai: "OPENAI_API_KEY",
+    groq: "GROQ_API_KEY",
+    xai: "XAI_API_KEY",
+    mistral: "MISTRAL_API_KEY",
+    openrouter: "OPENROUTER_API_KEY",
+};
+/** Ask where to store a validated key; persist or print env-var hints (§3.10). */
+export async function promptKeyDestinationAndPersist(opts) {
+    const isMac = process.platform === "darwin";
+    const isLinux = process.platform === "linux";
+    const hasSecret = isLinux && hasSecretTool();
+    const options = [];
+    if (isMac) {
+        options.push("OS secure store (macOS Keychain) — recommended");
+    }
+    else if (hasSecret) {
+        options.push("OS secure store (GNOME Keyring) — recommended");
+    }
+    else {
+        options.push("OS secure store — recommended");
+    }
+    options.push("Config file (~/.config/gnosys/.env)");
+    options.push("Don't store — I'll set it as an environment variable myself");
+    const choice = opts.destinationChoice ??
+        (await askChoice(opts.rl, "Where should I store this key?", options));
+    const secureIdx = 0;
+    const dotenvIdx = 1;
+    const noneIdx = 2;
+    if (choice === secureIdx) {
+        if (storeApiKeySecret(opts.service, opts.key, opts.provider)) {
+            const store = process.platform === "darwin" ? "macOS Keychain" : "GNOME Keyring";
+            console.log(`  ${CHECK} Key saved to ${store} (${maskKey(opts.key)})`);
+            return "secure";
+        }
+        console.log(`  ${CROSS} Failed to write to secure store. Saving to ~/.config/gnosys/.env instead.`);
+        await writeServiceKeyToEnv(opts.service, opts.key);
+        console.log(`  ${CHECK} Key saved to ~/.config/gnosys/.env (${maskKey(opts.key)})`);
+        return "dotenv";
+    }
+    if (choice === dotenvIdx) {
+        await writeServiceKeyToEnv(opts.service, opts.key);
+        console.log(`  ${CHECK} Key saved to ~/.config/gnosys/.env (${maskKey(opts.key)})`);
+        return "dotenv";
+    }
+    const legacy = LEGACY_PROVIDER_ENV[opts.provider];
+    const providerSvc = apiKeyServiceName(opts.provider, "provider");
+    console.log();
+    console.log(`  ${DIM}Set one of these environment variables:${RESET}`);
+    console.log(`  ${GREEN}export ${opts.service}=your-key-here${RESET}`);
+    if (opts.service !== providerSvc) {
+        console.log(`  ${DIM}or provider fallback:${RESET} ${GREEN}export ${providerSvc}=…${RESET}`);
+    }
+    if (legacy) {
+        console.log(`  ${DIM}or legacy:${RESET} ${GREEN}export ${legacy}=…${RESET}`);
+    }
+    return "none";
+}
+/** Build taskModels patch — only selected routable tasks that changed. */
+export function buildTaskModelsPatchFromAccepted(accepted, currentByTask, selectedSet) {
+    const patch = {};
+    for (const task of ROUTABLE_TASK_LIST) {
+        if (!selectedSet.has(task))
+            continue;
+        const next = accepted[task];
+        if (!next)
+            continue;
+        const cur = currentByTask[task];
+        if (next.provider !== cur.provider || next.model !== cur.model) {
+            patch[task] = next;
+        }
+    }
+    return Object.keys(patch).length > 0 ? patch : undefined;
+}
 /**
  * Models-only configuration — prompts for provider, model, and key (or accepts
  * them via options for non-interactive use). Validates the model against the
@@ -1945,7 +2198,6 @@ export async function runModelsSetup(opts = {}) {
     const ownsRl = !opts.rl;
     const rl = opts.rl ?? createInterface({ input: stdin, output: stdout });
     try {
-        // v5.9.3 Screen 3 — Header + Title at the top.
         const { Header } = await import("./setup/ui/header.js");
         const { Title } = await import("./setup/ui/title.js");
         const { Spinner } = await import("./setup/ui/spinner.js");
@@ -1954,16 +2206,13 @@ export async function runModelsSetup(opts = {}) {
         console.log();
         console.log(Header(["gnosys", "setup", "models"]));
         console.log();
-        console.log(Title("Model configuration", "pick a provider and model — we'll validate it before saving"));
+        console.log(Title("Model configuration", "pick a provider — then default or per-task routing"));
         console.log();
         const existingConfig = await loadExistingConfig(projectDir);
         const currentProvider = existingConfig?.llm.defaultProvider;
         const currentModel = existingConfig
             ? getProviderModel(existingConfig, existingConfig.llm.defaultProvider)
             : undefined;
-        // Step 1: provider (or use --provider flag). v5.9.3: animate the
-        // OpenRouter pricing fetch under a Spinner so the user gets feedback
-        // on what would otherwise feel like a hang.
         const pricingSpin = Spinner("fetching latest pricing from openrouter…");
         const fetchStart = Date.now();
         const dynamicModels = await fetchDynamicModels();
@@ -1973,8 +2222,6 @@ export async function runModelsSetup(opts = {}) {
             pricingSpin.ok(`pricing loaded · ${modelCount} models cached`, `${fetchMs} ms`);
         }
         else {
-            // No-op fallback (cache miss + network fail) — keep the hardcoded
-            // tiers but signal that we're running offline.
             pricingSpin.fail("pricing fetch failed", "using bundled tiers");
         }
         console.log();
@@ -1990,103 +2237,339 @@ export async function runModelsSetup(opts = {}) {
         else {
             provider = await pickProvider(rl, dynamicModels, "Choose your LLM provider", currentProvider);
         }
-        // Step 2: model (or use --model flag)
-        let model;
-        if (opts.model) {
-            model = opts.model;
-            printStatus("ok", "model", model);
+        const storePath = ensureActiveStorePath(projectDir);
+        const cfgBefore = existingConfig ?? (await loadConfig(storePath));
+        const nonInteractiveDefault = !!(opts.provider || opts.model);
+        if (nonInteractiveDefault) {
+            await runModelsDefaultOnlySetup({
+                rl,
+                opts,
+                provider,
+                dynamicModels,
+                storePath,
+                existingConfig,
+                currentProvider,
+                currentModel,
+                printDiff,
+                printStatus,
+            });
+            return;
+        }
+        console.log();
+        const intentChoice = await askChoice(rl, "What do you want to configure?", [
+            "Default only — set default provider and model",
+            "Assign to specific tasks — route selected tasks only (does not change default)",
+        ]);
+        if (intentChoice === 0) {
+            await runModelsDefaultOnlySetup({
+                rl,
+                opts,
+                provider,
+                dynamicModels,
+                storePath,
+                existingConfig,
+                currentProvider,
+                currentModel,
+                printDiff,
+                printStatus,
+            });
+            return;
+        }
+        await runModelsTaskRoutingSetup({
+            rl,
+            opts,
+            provider,
+            dynamicModels,
+            storePath,
+            cfgBefore,
+            printStatus,
+        });
+    }
+    finally {
+        if (ownsRl)
+            rl.close();
+    }
+}
+async function resolveKeyInMemory(opts) {
+    if (!providerNeedsApiKey(opts.provider))
+        return "";
+    const cached = opts.keyCache.get(opts.provider);
+    if (cached)
+        return cached;
+    const stored = readStoredSecret(apiKeyServiceName(opts.provider, "global"));
+    if (stored) {
+        opts.keyCache.set(opts.provider, stored);
+        return stored;
+    }
+    const key = await askInput(opts.rl, `API key for ${opts.provider} (shared across selected tasks)`);
+    opts.keyCache.set(opts.provider, key);
+    return key;
+}
+async function runModelsDefaultOnlySetup(ctx) {
+    const { rl, opts, provider, dynamicModels, storePath, printDiff, printStatus } = ctx;
+    const isLocalProvider = provider === "ollama" || provider === "lmstudio";
+    let model;
+    if (opts.model) {
+        model = opts.model;
+        printStatus("ok", "model", model);
+    }
+    else {
+        const tiers = dynamicModels[provider] ?? PROVIDER_TIERS[provider];
+        if (provider === "custom" || !tiers || tiers.length === 0) {
+            model = await askInput(rl, "Model name");
         }
         else {
-            const tiers = dynamicModels[provider] ?? PROVIDER_TIERS[provider];
-            if (provider === "custom" || !tiers || tiers.length === 0) {
-                model = await askInput(rl, "Model name");
-            }
-            else {
-                const showCurrent = currentProvider === provider ? currentModel : undefined;
-                model = await pickModel(rl, provider, dynamicModels, "Choose model", showCurrent);
-            }
+            const showCurrent = ctx.currentProvider === provider ? ctx.currentModel : undefined;
+            model = await pickModel(rl, provider, dynamicModels, "Choose model", showCurrent);
+        }
+    }
+    if (!model) {
+        printStatus("fail", "no model selected · aborting");
+        return;
+    }
+    let apiKey = readFirstInChain(provider) ?? "";
+    let keyEnteredThisRun = false;
+    if (!apiKey && !isLocalProvider) {
+        console.log();
+        apiKey = await askInput(rl, `API key for ${provider}`);
+        keyEnteredThisRun = !!apiKey;
+        if (!apiKey) {
+            console.log(`${WARN} No API key found for ${provider}. Validation may be skipped.`);
         }
-        if (!model) {
-            printStatus("fail", "no model selected · aborting");
+    }
+    const shouldValidate = opts.validate !== false;
+    if (shouldValidate && (apiKey || isLocalProvider)) {
+        console.log();
+        const customBaseUrl = provider === "custom" ? process.env.GNOSYS_LLM_BASE_URL : undefined;
+        const { proceed, apiKey: validatedKey } = await validateModelWithKeyRotation({
+            rl,
+            provider,
+            model,
+            apiKey,
+            customBaseUrl,
+            isLocalProvider,
+            saveAnywayPrompt: "Save config anyway?",
+            saveAnywayDefault: false,
+            keyScope: "provider",
+        });
+        apiKey = validatedKey;
+        if (!proceed) {
+            printStatus("warn", "cancelled · no changes written");
             return;
         }
-        // Step 3: load API key from existing storage (if available)
-        const envVarName = provider === "custom" ? "GNOSYS_CUSTOM_KEY" :
-            `GNOSYS_${provider.toUpperCase()}_KEY`;
-        const legacyEnvVars = {
-            anthropic: "ANTHROPIC_API_KEY",
-            openai: "OPENAI_API_KEY",
-            groq: "GROQ_API_KEY",
-            xai: "XAI_API_KEY",
-            mistral: "MISTRAL_API_KEY",
-        };
-        const legacyEnvVar = legacyEnvVars[provider] ?? "";
-        let apiKey = process.env[envVarName] || (legacyEnvVar ? process.env[legacyEnvVar] : "") || "";
-        if (!apiKey && process.platform === "darwin") {
-            try {
-                apiKey = execSync(`security find-generic-password -a "$USER" -s "${envVarName}" -w`, { stdio: "pipe", encoding: "utf-8" }).trim();
-            }
-            catch {
-                // No key in keychain
-            }
+        if (keyEnteredThisRun && apiKey && !isLocalProvider) {
+            const service = apiKeyServiceName(provider, "provider");
+            await promptKeyDestinationAndPersist({
+                rl,
+                service,
+                provider,
+                key: apiKey,
+                scope: "provider",
+            });
+        }
+    }
+    const existingLlm = ctx.existingConfig?.llm;
+    const existingProviderConfig = existingLlm
+        ? existingLlm[provider]
+        : undefined;
+    const providerConfigBase = typeof existingProviderConfig === "object" && existingProviderConfig !== null
+        ? existingProviderConfig
+        : {};
+    await updateConfig(storePath, {
+        llm: {
+            ...(existingLlm ?? {}),
+            defaultProvider: provider,
+            [provider]: {
+                ...providerConfigBase,
+                model,
+            },
+        },
+    });
+    const { buildModelsDiffRows } = await import("./setup/modelsRender.js");
+    console.log();
+    printDiff(buildModelsDiffRows(ctx.currentProvider, ctx.currentModel, provider, model));
+    printStatus("ok", `saved · ${storePath}/gnosys.json`);
+}
+async function runModelsTaskRoutingSetup(ctx) {
+    const { rl, opts, provider: initialProvider, dynamicModels, storePath, cfgBefore, printStatus } = ctx;
+    const tasks = ASSIGNABLE_TASK_LIST;
+    const currentByTask = {};
+    for (const task of tasks) {
+        currentByTask[task] = getAssignableRouting(cfgBefore, task);
+    }
+    const dreamEnabledBefore = !!cfgBefore.dream?.enabled;
+    console.log();
+    console.log(`${BOLD}Which tasks should use ${initialProvider}?${RESET}`);
+    console.log(`${DIM}Enter numbers (comma-separated), ${BOLD}all${RESET}${DIM}, or ${BOLD}none${RESET}${DIM}. Unlisted tasks keep their current routing.${RESET}`);
+    console.log();
+    for (let i = 0; i < tasks.length; i++) {
+        const task = tasks[i];
+        const cur = currentByTask[task];
+        const desc = TASK_DESCRIPTIONS[task] ?? "";
+        const off = task === "dream" && !dreamEnabledBefore ? `  ${DIM}[off]${RESET}` : "";
+        console.log(`  ${BOLD}${i + 1}.${RESET} ${task.padEnd(14)} ${DIM}now:${RESET} ${cur.provider} / ${cur.model}  ${DIM}(${desc})${RESET}${off}`);
+    }
+    console.log();
+    let selectedIndices = [];
+    while (true) {
+        const raw = await askInput(rl, `Tasks for ${initialProvider} (e.g. 5,6 or all)`, { default: "all" });
+        const parsed = parseCommaSeparatedTaskSelection(raw, tasks.length);
+        if (parsed === "all") {
+            selectedIndices = tasks.map((_, i) => i);
+            break;
         }
-        if (!apiKey && provider !== "ollama" && provider !== "lmstudio") {
-            console.log(`${WARN} No API key found for ${provider}. Run 'gnosys setup' to configure one.`);
-            // Continue anyway — user might just want to update the model in config
+        if (parsed === "none") {
+            selectedIndices = [];
+            break;
         }
-        // Step 4: validate (default: true) — v5.9.3 Screen 3: animated
-        // Spinner with latency reported on success.
-        const shouldValidate = opts.validate !== false;
-        const isLocalProvider = provider === "ollama" || provider === "lmstudio";
-        if (shouldValidate && (apiKey || isLocalProvider)) {
+        if (parsed && parsed.length > 0) {
+            selectedIndices = parsed;
+            break;
+        }
+        console.log(`${RED}Enter numbers 1-${tasks.length}, comma-separated, or 'all'.${RESET}`);
+    }
+    const selectedSet = new Set(selectedIndices.map((i) => tasks[i]));
+    if (selectedSet.size === 0) {
+        printStatus("warn", "no tasks selected · no changes written");
+        return;
+    }
+    const selectedTasks = [...selectedSet];
+    const keyRequirements = buildInlineKeyRequirements(selectedTasks, () => initialProvider);
+    if (keyRequirements.length > 0) {
+        console.log();
+        console.log(`  ${DIM}Keys needed for:${RESET}`);
+        for (const req of keyRequirements) {
+            const svc = apiKeyServiceName(req.provider, req.scope);
+            console.log(`  ${DIM}  all selected → ${req.provider} (${svc})${RESET}`);
+        }
+        console.log();
+    }
+    const keyCache = new Map();
+    const persistedServices = new Set();
+    const accepted = {};
+    for (const task of selectedTasks) {
+        let taskProvider = initialProvider;
+        const cur = currentByTask[task];
+        while (true) {
+            const isLocal = taskProvider === "ollama" || taskProvider === "lmstudio";
+            const showCurrent = cur.provider === taskProvider ? cur.model : undefined;
             console.log();
-            const validateSpin = Spinner(`validating ${provider} / ${model}…`);
-            const customBaseUrl = provider === "custom"
-                ? process.env.GNOSYS_LLM_BASE_URL
-                : undefined;
-            const result = await validateModel(provider, model, apiKey, { customBaseUrl });
-            if (result.ok) {
-                validateSpin.ok("model validated", `${result.latencyMs} ms · ${provider} / ${model}`);
+            const model = await pickModel(rl, taskProvider, dynamicModels, `Model for ${task}`, showCurrent);
+            if (!model) {
+                printStatus("fail", `no model for ${task} · skipping`);
+                accepted[task] = cur;
+                break;
             }
-            else {
-                validateSpin.fail("model test failed", result.error);
-                const proceed = await askYesNo(rl, "Save config anyway?", false);
-                if (!proceed) {
-                    printStatus("warn", "cancelled · no changes written");
-                    return;
+            const apiKey = await resolveKeyInMemory({
+                rl,
+                provider: taskProvider,
+                keyCache,
+            });
+            const shouldValidate = opts.validate !== false;
+            let proceed = true;
+            let validatedKey = apiKey;
+            if (shouldValidate && (apiKey || isLocal)) {
+                const customBaseUrl = taskProvider === "custom" ? process.env.GNOSYS_LLM_BASE_URL : undefined;
+                const result = await validateTaskCombo({
+                    rl,
+                    provider: taskProvider,
+                    model,
+                    apiKey,
+                    customBaseUrl,
+                    isLocalProvider: isLocal,
+                    saveAnywayPrompt: `Save ${task} routing anyway?`,
+                    saveAnywayDefault: false,
+                });
+                proceed = result.proceed;
+                validatedKey = result.apiKey;
+            }
+            if (proceed) {
+                accepted[task] = {
+                    provider: taskProvider,
+                    model,
+                };
+                if (validatedKey && !isLocal) {
+                    const service = apiKeyServiceName(taskProvider, "global");
+                    if (!persistedServices.has(service)) {
+                        await promptKeyDestinationAndPersist({
+                            rl,
+                            service,
+                            provider: taskProvider,
+                            key: validatedKey,
+                            scope: "global",
+                        });
+                        persistedServices.add(service);
+                    }
+                    keyCache.set(taskProvider, validatedKey);
                 }
+                break;
+            }
+            const retryChoice = await askChoice(rl, "Validation failed. What next?", [
+                "Pick a different provider + model",
+                "Keep provider, pick a new model",
+                "Skip this task (keep current routing)",
+            ]);
+            if (retryChoice === 0) {
+                const picked = await pickProvider(rl, dynamicModels, `Provider for ${task}`, taskProvider);
+                if (picked)
+                    taskProvider = picked;
+                continue;
+            }
+            if (retryChoice === 1) {
+                continue;
             }
+            accepted[task] = cur;
+            break;
         }
-        // Step 5: write config (v5.9.4 Bug 10 — unified store resolution).
-        const storePath = ensureActiveStorePath(projectDir);
-        const existingLlm = existingConfig?.llm;
-        const existingProviderConfig = existingLlm
-            ? existingLlm[provider]
-            : undefined;
-        const providerConfigBase = (typeof existingProviderConfig === "object" && existingProviderConfig !== null)
-            ? existingProviderConfig
-            : {};
-        await updateConfig(storePath, {
-            llm: {
-                ...(existingLlm ?? {}),
-                defaultProvider: provider,
-                [provider]: {
-                    ...providerConfigBase,
-                    model,
-                },
-            },
-        });
-        // v5.9.3 Screen 3 — Diff() before the saved confirmation. Shows what
-        // landed in gnosys.json.
-        const { buildModelsDiffRows } = await import("./setup/modelsRender.js");
-        console.log();
-        printDiff(buildModelsDiffRows(currentProvider, currentModel, provider, model));
-        printStatus("ok", `saved · ${storePath}/gnosys.json`);
     }
-    finally {
-        if (ownsRl)
-            rl.close();
+    const planned = { ...currentByTask };
+    for (const task of selectedTasks) {
+        if (accepted[task])
+            planned[task] = accepted[task];
+    }
+    console.log();
+    console.log(`${BOLD}Planned task routing${RESET}`);
+    console.log(`  ${"Task".padEnd(16)}${"Provider / model".padEnd(42)}${RESET}`);
+    console.log(`  ${"\u2500".repeat(56)}`);
+    for (const task of tasks) {
+        const p = planned[task];
+        const marker = selectedSet.has(task) ? `${CYAN}*${RESET} ` : "  ";
+        const off = task === "dream" && !dreamEnabledBefore
+            ? `  ${DIM}(dream off)${RESET}`
+            : "";
+        console.log(`${marker}${task.padEnd(14)}${p.provider} / ${p.model}${off}`);
     }
+    console.log(`${DIM}  * = changed in this run${RESET}`);
+    console.log();
+    const confirmed = await askYesNo(rl, "Save this routing?", true);
+    if (!confirmed) {
+        printStatus("warn", "cancelled · no changes written");
+        return;
+    }
+    const taskModelsPatch = buildTaskModelsPatchFromAccepted(accepted, currentByTask, selectedSet);
+    let dreamPatch;
+    if (selectedSet.has("dream") && accepted.dream) {
+        dreamPatch = {
+            ...(cfgBefore.dream ?? {}),
+            provider: accepted.dream.provider,
+            model: accepted.dream.model,
+        };
+        if (!dreamEnabledBefore &&
+            (await askYesNo(rl, "Enable dream mode with this routing?", true))) {
+            dreamPatch.enabled = true;
+        }
+    }
+    const updatePayload = {};
+    if (taskModelsPatch)
+        updatePayload.taskModels = taskModelsPatch;
+    if (dreamPatch)
+        updatePayload.dream = dreamPatch;
+    if (!taskModelsPatch && !dreamPatch) {
+        printStatus("warn", "no routing changes to save");
+        return;
+    }
+    await updateConfig(storePath, updatePayload);
+    printStatus("ok", `saved task routing · ${storePath}/gnosys.json`);
 }
 /**
  * Lightweight model-management command. Supports three operations:
@@ -2238,8 +2721,12 @@ export async function runDreamSetup(opts = {}) {
                 dream: { ...(existingDream ?? {}), enabled: false },
             });
             clearDreamMachineEverywhere();
+            const { uninstallDreamLaunchAgent } = await import("./dreamLaunchd.js");
+            const launchdPath = uninstallDreamLaunchAgent();
             console.log();
             printStatus("ok", "dream mode disabled · designation cleared");
+            if (launchdPath)
+                printStatus("ok", "launchd agent removed", launchdPath);
             localDb.close();
             remoteDb?.close();
             return;
@@ -2296,26 +2783,27 @@ export async function runDreamSetup(opts = {}) {
         }
         // Validate — animated Spinner with the model latency reported.
         if (dreamProvider !== "skip") {
-            const apiKey = await getApiKeyForProvider(dreamProvider);
+            const apiKey = await getApiKeyForProvider(dreamProvider, { task: "dream" });
             const isLocalProvider = dreamProvider === "ollama" || dreamProvider === "lmstudio";
             if (apiKey || isLocalProvider) {
                 console.log();
-                const validateSpin = Spinner(`validating ${dreamProvider} / ${dreamModel}…`);
                 try {
                     const customBaseUrl = dreamProvider === "custom" ? process.env.GNOSYS_LLM_BASE_URL : undefined;
-                    const result = await validateModel(dreamProvider, dreamModel, apiKey, { customBaseUrl });
-                    if (result.ok) {
-                        validateSpin.ok("model validated", `${result.latencyMs} ms · ${dreamProvider} / ${dreamModel}`);
-                    }
-                    else {
-                        validateSpin.fail("could not reach model", result.error);
-                        const proceed = await askYesNo(rl, "save config anyway?", true);
-                        if (!proceed) {
-                            printStatus("warn", "setup cancelled · no changes written");
-                            localDb.close();
-                            remoteDb?.close();
-                            return;
-                        }
+                    const { proceed } = await validateModelWithKeyRotation({
+                        rl,
+                        provider: dreamProvider,
+                        model: dreamModel,
+                        apiKey,
+                        customBaseUrl,
+                        isLocalProvider,
+                        saveAnywayPrompt: "save config anyway?",
+                        saveAnywayDefault: true,
+                    });
+                    if (!proceed) {
+                        printStatus("warn", "setup cancelled · no changes written");
+                        localDb.close();
+                        remoteDb?.close();
+                        return;
                     }
                 }
                 catch (err) {
@@ -2323,7 +2811,7 @@ export async function runDreamSetup(opts = {}) {
                 }
             }
             else {
-                printStatus("warn", `no API key for ${dreamProvider}`, "set one via `gnosys setup models`");
+                printStatus("warn", `no API key for ${dreamProvider}`, "set one via `gnosys setup providers`");
             }
         }
         // ─── 7.2  Thresholds + sub-tasks ───────────────────────────────────
@@ -2336,6 +2824,12 @@ export async function runDreamSetup(opts = {}) {
         const dIdle = existingDream?.idleMinutes ?? 10;
         const dRuntime = existingDream?.maxRuntimeMinutes ?? 30;
         const dMinMem = existingDream?.minMemories ?? 10;
+        const dScheduleStart = existingDream?.schedule?.startHour ?? 2;
+        const dScheduleEnd = existingDream?.schedule?.endHour ?? 5;
+        const dSystemIdle = existingDream?.systemIdleMinutes ?? 30;
+        const dMinNewMemories = existingDream?.minNewMemoriesToDream ?? 10;
+        const dMinHours = existingDream?.minHoursBetweenRuns ?? 20;
+        const dMaxCalls = existingDream?.maxLLMCallsPerRun ?? 12;
         const dSelfCritique = existingDream?.selfCritique ?? true;
         const dGenSummaries = existingDream?.generateSummaries ?? true;
         const dDiscover = existingDream?.discoverRelationships ?? true;
@@ -2352,6 +2846,12 @@ export async function runDreamSetup(opts = {}) {
         let idleMinutes = dIdle;
         let maxRuntimeMinutes = dRuntime;
         let minMemories = dMinMem;
+        let scheduleStartHour = dScheduleStart;
+        let scheduleEndHour = dScheduleEnd;
+        let systemIdleMinutes = dSystemIdle;
+        let minNewMemoriesToDream = dMinNewMemories;
+        let minHoursBetweenRuns = dMinHours;
+        let maxLLMCallsPerRun = dMaxCalls;
         let selfCritique = dSelfCritique;
         let generateSummaries = dGenSummaries;
         let discoverRelationships = dDiscover;
@@ -2362,6 +2862,18 @@ export async function runDreamSetup(opts = {}) {
             maxRuntimeMinutes = Math.max(1, parseInt(runtimeAns) || dRuntime);
             const minMemAns = await askInput(rl, "minimum memories before activating", { default: String(dMinMem) });
             minMemories = Math.max(1, parseInt(minMemAns) || dMinMem);
+            const scheduleStartAns = await askInput(rl, "night window start hour (0-23)", { default: String(dScheduleStart) });
+            scheduleStartHour = Math.min(23, Math.max(0, parseInt(scheduleStartAns) || dScheduleStart));
+            const scheduleEndAns = await askInput(rl, "night window end hour (0-23)", { default: String(dScheduleEnd) });
+            scheduleEndHour = Math.min(23, Math.max(0, parseInt(scheduleEndAns) || dScheduleEnd));
+            const systemIdleAns = await askInput(rl, "real machine idle minutes required", { default: String(dSystemIdle) });
+            systemIdleMinutes = Math.max(1, parseInt(systemIdleAns) || dSystemIdle);
+            const minNewAns = await askInput(rl, "minimum changed memories before dreaming", { default: String(dMinNewMemories) });
+            minNewMemoriesToDream = Math.max(0, parseInt(minNewAns) || dMinNewMemories);
+            const minHoursAns = await askInput(rl, "minimum hours between successful dreams", { default: String(dMinHours) });
+            minHoursBetweenRuns = Math.max(0, parseInt(minHoursAns) || dMinHours);
+            const maxCallsAns = await askInput(rl, "maximum LLM calls per dream run", { default: String(dMaxCalls) });
+            maxLLMCallsPerRun = Math.max(0, parseInt(maxCallsAns) || dMaxCalls);
             selfCritique = await askYesNo(rl, "self-critique (rule + LLM-based review flagging)", dSelfCritique);
             generateSummaries = await askYesNo(rl, "generate summaries (LLM)", dGenSummaries);
             discoverRelationships = await askYesNo(rl, "discover relationships (LLM)", dDiscover);
@@ -2376,6 +2888,11 @@ export async function runDreamSetup(opts = {}) {
                 minMemories,
                 provider: dreamProvider,
                 model: dreamModel || undefined,
+                schedule: { startHour: scheduleStartHour, endHour: scheduleEndHour },
+                systemIdleMinutes,
+                minNewMemoriesToDream,
+                minHoursBetweenRuns,
+                maxLLMCallsPerRun,
                 selfCritique,
                 generateSummaries,
                 discoverRelationships,
@@ -2384,6 +2901,8 @@ export async function runDreamSetup(opts = {}) {
         // Reset consecutive failure counter on a fresh setup so Layer 4
         // doesn't fire immediately based on stale history.
         localDb.resetDreamConsecutiveFailures();
+        const { installDreamLaunchAgent } = await import("./dreamLaunchd.js");
+        const launchdPath = installDreamLaunchAgent();
         localDb.close();
         remoteDb?.close();
         // Final Diff block per the design — provider/machine + the two
@@ -2411,7 +2930,9 @@ export async function runDreamSetup(opts = {}) {
             discoverRelationships,
         }));
         const dreamerName = designate ? localMachine : (designatedMachine ?? "the designated machine");
-        printStatus("progress", `first cycle runs after ${dreamerName} is idle for ${idleMinutes} min`);
+        printStatus("progress", `scheduled dream checks run nightly (${scheduleStartHour}:00-${scheduleEndHour}:00) on ${dreamerName}`);
+        if (launchdPath)
+            printStatus("ok", "launchd agent installed", launchdPath);
         printStatus("progress", "check status anytime with `gnosys status --system`");
     }
     finally {
@@ -2474,29 +2995,18 @@ async function openRemoteDbIfConfigured(localDb) {
  * Best-effort lookup of the API key for a provider. Used by the dream setup
  * wizard to power the validation step. Mirrors the resolveApiKey precedence.
  */
-export async function getApiKeyForProvider(provider) {
-    if (provider === "ollama" || provider === "lmstudio" || provider === "skip")
+export async function getApiKeyForProvider(provider, opts) {
+    if (provider === "ollama" || provider === "lmstudio" || provider === "skip") {
         return "";
-    const envVarName = provider === "custom" ? "GNOSYS_CUSTOM_KEY" : `GNOSYS_${provider.toUpperCase()}_KEY`;
-    const legacyVars = {
-        anthropic: "ANTHROPIC_API_KEY",
-        openai: "OPENAI_API_KEY",
-        groq: "GROQ_API_KEY",
-        xai: "XAI_API_KEY",
-        mistral: "MISTRAL_API_KEY",
-    };
-    const fromEnv = process.env[envVarName] || (legacyVars[provider] && process.env[legacyVars[provider]]) || "";
-    if (fromEnv)
-        return fromEnv;
-    if (process.platform === "darwin") {
-        try {
-            return execSync(`security find-generic-password -a "$USER" -s "${envVarName}" -w 2>/dev/null`, {
-                stdio: "pipe", encoding: "utf-8", timeout: 2000,
-            }).trim();
-        }
-        catch {
-            // fall through
+    }
+    if (opts?.directory) {
+        const cfg = await loadExistingConfig(opts.directory);
+        if (cfg) {
+            const fromCfg = getApiKeyForProviderFromConfig(cfg, provider);
+            if (fromCfg)
+                return fromCfg;
         }
     }
-    return "";
+    return readFirstInChain(provider) ?? "";
 }
+export { getApiKeyForProviderFromConfig } from "./apiKeyVault.js";