zam-core 0.4.3 → 0.5.0

package/dist/cli/index.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { readFileSync as readFileSync14 } from "fs";
-import { dirname as dirname10, join as join23 } from "path";
+import { readFileSync as readFileSync15 } from "fs";
+import { dirname as dirname10, join as join24 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
-import { Command as Command24 } from "commander";
+import { Command as Command25 } from "commander";
 
 // src/cli/commands/agent.ts
-import { existsSync as existsSync11 } from "fs";
-import { join as join11 } from "path";
+import { existsSync as existsSync13 } from "fs";
+import { join as join13 } from "path";
 import { Command } from "commander";
 
 // src/kernel/analytics/stats.ts
@@ -203,6 +203,25 @@ function clearADOCredentials(path) {
   delete creds.ado;
   saveCredentials(creds, path);
 }
+function getProviderApiKey(name, path) {
+  const key = loadCredentials(path).llmProviders?.[name]?.apiKey;
+  return key && key.length > 0 ? key : null;
+}
+function setProviderApiKey(name, apiKey, path) {
+  const creds = loadCredentials(path);
+  creds.llmProviders = { ...creds.llmProviders, [name]: { apiKey } };
+  saveCredentials(creds, path);
+}
+function clearProviderApiKey(name, path) {
+  const creds = loadCredentials(path);
+  if (creds.llmProviders && name in creds.llmProviders) {
+    delete creds.llmProviders[name];
+    saveCredentials(creds, path);
+  }
+}
+function listProviderApiKeyRefs(path) {
+  return Object.keys(loadCredentials(path).llmProviders ?? {});
+}
 
 // src/kernel/connectors/azure-devops.ts
 function loadADOConfig() {
@@ -4403,8 +4422,10 @@ function t(locale, key, params = {}) {
 import { existsSync as existsSync8, mkdirSync as mkdirSync7, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "fs";
 import { homedir as homedir6 } from "os";
 import { dirname as dirname4, join as join9 } from "path";
-var DEFAULT_CONFIG_PATH = join9(homedir6(), ".zam", "config.json");
-function loadInstallConfig(path = DEFAULT_CONFIG_PATH) {
+function defaultConfigPath() {
+  return process.env.ZAM_CONFIG_PATH || join9(homedir6(), ".zam", "config.json");
+}
+function loadInstallConfig(path = defaultConfigPath()) {
   if (!existsSync8(path)) return {};
   try {
     return JSON.parse(readFileSync8(path, "utf-8"));
@@ -4412,25 +4433,50 @@ function loadInstallConfig(path = DEFAULT_CONFIG_PATH) {
     return {};
   }
 }
-function saveInstallConfig(config, path = DEFAULT_CONFIG_PATH) {
+function saveInstallConfig(config, path = defaultConfigPath()) {
   const dir = dirname4(path);
   if (!existsSync8(dir)) mkdirSync7(dir, { recursive: true });
   writeFileSync5(path, `${JSON.stringify(config, null, 2)}
 `, "utf-8");
 }
-function getInstallMode(path = DEFAULT_CONFIG_PATH) {
+function getInstallMode(path = defaultConfigPath()) {
   return loadInstallConfig(path).mode ?? "developer";
 }
-function setInstallMode(mode, path = DEFAULT_CONFIG_PATH) {
+function setInstallMode(mode, path = defaultConfigPath()) {
   const config = loadInstallConfig(path);
   config.mode = mode;
   saveInstallConfig(config, path);
 }
-function getInstallChannel(path = DEFAULT_CONFIG_PATH) {
+function getInstallChannel(path = defaultConfigPath()) {
   const config = loadInstallConfig(path);
   if (config.channel) return config.channel;
   return (config.mode ?? "developer") === "developer" ? "developer" : "direct";
 }
+function getMachineAiConfig(path = defaultConfigPath()) {
+  return loadInstallConfig(path).ai ?? {};
+}
+function saveMachineAiConfig(ai, path = defaultConfigPath()) {
+  const config = loadInstallConfig(path);
+  config.ai = ai;
+  saveInstallConfig(config, path);
+}
+function getConfiguredWorkspaces(path = defaultConfigPath()) {
+  return loadInstallConfig(path).workspaces ?? [];
+}
+function saveConfiguredWorkspaces(workspaces, path = defaultConfigPath()) {
+  const config = loadInstallConfig(path);
+  config.workspaces = workspaces;
+  saveInstallConfig(config, path);
+}
+function upsertConfiguredWorkspace(workspace, path = defaultConfigPath()) {
+  const current = getConfiguredWorkspaces(path);
+  const next = [
+    ...current.filter((candidate) => candidate.id !== workspace.id),
+    workspace
+  ];
+  saveConfiguredWorkspaces(next, path);
+  return next;
+}
 function detectSyncProvider(dir) {
   const p = dir.toLowerCase();
   if (p.includes("onedrive")) return "OneDrive";
@@ -4707,13 +4753,11 @@ function runCommand(cmd) {
     return "";
   }
 }
-function detectWindowsAMDIPU() {
+function detectWindowsNPU() {
   if (process.platform !== "win32") return false;
-  const cmd = `powershell -NoProfile -Command "Get-CimInstance Win32_PnPEntity | Where-Object { $_.Name -like '*AMD IPU*' -or $_.Name -like '*AMD NPU*' -or $_.Name -like '*NPU Compute*' -or $_.Name -like '*Ryzen AI*' -or $_.HardwareID -like '*VEN_1022&DEV_1502*' -or $_.HardwareID -like '*VEN_1022&DEV_17F0*' } | Select-Object -First 1 -ExpandProperty Name"`;
+  const cmd = `powershell -NoProfile -Command "Get-CimInstance Win32_PnPEntity | Where-Object { $_.PNPClass -eq 'ComputeAccelerator' -or $_.Name -like '*AMD IPU*' -or $_.Name -like '*AMD NPU*' -or $_.Name -like '*Qualcomm*NPU*' -or $_.Name -like '*Hexagon*NPU*' -or $_.Name -like '*Intel*AI Boost*' -or $_.Name -like '*NPU Compute*' -or $_.Name -like '*Ryzen AI*' } | Select-Object -First 1 -ExpandProperty Name"`;
   const output = runCommand(cmd);
-  return Boolean(
-    output && (output.toLowerCase().includes("amd") || output.toLowerCase().includes("ipu") || output.toLowerCase().includes("npu") || output.toLowerCase().includes("ryzen"))
-  );
+  return Boolean(output && output.length > 0);
 }
 function getSystemProfile() {
   const platform = process.platform;
@@ -4725,13 +4769,21 @@ function getSystemProfile() {
   let arch = "unknown";
   if (archStr === "x64") arch = "x64";
   else if (archStr === "arm64") arch = "arm64";
-  const hasRyzenNPU = os === "windows" && detectWindowsAMDIPU();
+  const hasNpu = os === "windows" && detectWindowsNPU();
   const hasAppleSilicon = os === "macos" && arch === "arm64";
   let recommendedRunner = "generic";
   let recommendedModel = "qwen3.5:4b";
-  if (hasRyzenNPU) {
-    recommendedRunner = "fastflowlm";
-    recommendedModel = "qwen3.5:4b";
+  if (hasNpu) {
+    const isQualcomm = runCommand(
+      `powershell -NoProfile -Command "Get-CimInstance Win32_PnPEntity | Where-Object { $_.Name -like '*Qualcomm*' } | Select-Object -First 1"`
+    ).length > 0;
+    if (isQualcomm) {
+      recommendedRunner = "generic";
+      recommendedModel = "qwen3.5-4b";
+    } else {
+      recommendedRunner = "fastflowlm";
+      recommendedModel = "qwen3.5:4b";
+    }
   } else if (hasAppleSilicon) {
     recommendedRunner = "ollama";
     recommendedModel = "llama3.2:3b";
@@ -4742,7 +4794,8 @@ function getSystemProfile() {
   return {
     os,
     arch,
-    hasRyzenNPU,
+    hasRyzenNPU: hasNpu && !archStr.includes("arm64"),
+    // backwards compatibility flag
     hasAppleSilicon,
     recommendedRunner,
     recommendedModel
@@ -4879,6 +4932,304 @@ function planUpdate(decision) {
   }
 }
 
+// src/cli/agent-harness.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync12 } from "fs";
+import { homedir as homedir8 } from "os";
+import { join as join12 } from "path";
+
+// src/cli/terminal-open.ts
+import { execFileSync as execFileSync2, execSync as execSync4 } from "child_process";
+import {
+  accessSync,
+  constants,
+  existsSync as existsSync11,
+  unlinkSync,
+  writeFileSync as writeFileSync6
+} from "fs";
+import { tmpdir } from "os";
+import { basename as basename2, delimiter, extname, isAbsolute, join as join11 } from "path";
+function isPowerShellShell(shell) {
+  return shell === "pwsh" || shell === "powershell";
+}
+function psSingleQuoted2(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+function detectShell() {
+  if (process.platform === "win32")
+    return findExecutable("pwsh.exe") ? "pwsh" : "powershell";
+  const shell = process.env.SHELL ?? "";
+  return basename2(shell) === "bash" ? "bash" : "zsh";
+}
+function normalizeShell(shell) {
+  if (!shell) return detectShell();
+  const normalized = shell.toLowerCase();
+  if (normalized === "zsh" || normalized === "bash" || normalized === "pwsh" || normalized === "powershell") {
+    return normalized;
+  }
+  throw new Error(
+    `Unsupported shell: ${shell}. Expected zsh, bash, pwsh, or powershell.`
+  );
+}
+function selectWindowsExecutable(results, pathext = process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD") {
+  if (results.length === 0) return null;
+  const extensions = pathext.split(";").map((ext) => ext.trim().toLowerCase()).filter(Boolean);
+  const runnable = results.find(
+    (result) => extensions.some((ext) => result.toLowerCase().endsWith(ext))
+  );
+  return runnable ?? results[0];
+}
+function stripSurroundingQuotes(command) {
+  const trimmed = command.trim();
+  if (trimmed.length < 2) return trimmed;
+  const first = trimmed[0];
+  const last = trimmed[trimmed.length - 1];
+  if (first === '"' && last === '"' || first === "'" && last === "'") {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+function executableExists(path) {
+  if (!existsSync11(path)) return false;
+  if (process.platform === "win32") return true;
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function windowsExecutableNames(command) {
+  if (process.platform !== "win32") return [command];
+  if (extname(command)) return [command];
+  const extensions = (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((ext) => ext.trim()).filter(Boolean);
+  return extensions.map((ext) => `${command}${ext}`);
+}
+function hasDirectoryPart(command) {
+  return isAbsolute(command) || command.includes("/") || command.includes("\\");
+}
+function findExecutable(command) {
+  const normalized = stripSurroundingQuotes(command);
+  if (!normalized) return null;
+  const matches = [];
+  if (hasDirectoryPart(normalized)) {
+    for (const candidate of windowsExecutableNames(normalized)) {
+      if (executableExists(candidate)) matches.push(candidate);
+    }
+    return process.platform === "win32" ? selectWindowsExecutable(matches) : matches[0] ?? null;
+  }
+  const pathEntries = (process.env.PATH ?? "").split(delimiter).map((entry) => entry.trim()).filter(Boolean);
+  for (const entry of pathEntries) {
+    for (const name of windowsExecutableNames(normalized)) {
+      const candidate = join11(entry, name);
+      if (executableExists(candidate)) matches.push(candidate);
+    }
+  }
+  return process.platform === "win32" ? selectWindowsExecutable(matches) : matches[0] ?? null;
+}
+function resolveZamInvocation(shell) {
+  const installed = findExecutable("zam");
+  if (installed) {
+    return isPowerShellShell(shell) ? `& ${psSingleQuoted2(installed)}` : installed;
+  }
+  const projectRoot = join11(import.meta.dirname, "..", "..");
+  const cliSource = join11(projectRoot, "src/cli/index.ts");
+  if (isPowerShellShell(shell)) {
+    return `& npx --prefix ${psSingleQuoted2(projectRoot)} tsx ${psSingleQuoted2(cliSource)}`;
+  }
+  return `npx --prefix ${JSON.stringify(projectRoot)} tsx ${JSON.stringify(cliSource)}`;
+}
+function buildShellSetupCommand(dir, shell, command) {
+  if (isPowerShellShell(shell)) {
+    return [`Set-Location -LiteralPath ${psSingleQuoted2(dir)}`, command].join(
+      "; "
+    );
+  }
+  return `cd ${JSON.stringify(dir)} && ${command}`;
+}
+function isItermRunning() {
+  try {
+    const result = execSync4(
+      `osascript -e 'tell application "System Events" to (name of processes) contains "iTerm2"' 2>/dev/null`,
+      { encoding: "utf-8" }
+    ).trim();
+    return result === "true";
+  } catch {
+    return false;
+  }
+}
+function openMacTerminal(shellSetup, label, dir, silent) {
+  const useIterm = isItermRunning();
+  const escaped = shellSetup.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  const appleScript = useIterm ? `tell application "iTerm2"
+  activate
+  set newWindow to (create window with default profile)
+  tell current session of newWindow
+    write text "${escaped}"
+  end tell
+end tell` : `tell application "Terminal"
+  activate
+  do script "${escaped}"
+end tell`;
+  const tmpFile = join11(tmpdir(), `zam-terminal-${label}.scpt`);
+  try {
+    writeFileSync6(tmpFile, appleScript);
+    execSync4(`osascript ${JSON.stringify(tmpFile)}`, { stdio: "ignore" });
+    if (!silent) {
+      console.log(
+        `Opened ${useIterm ? "iTerm2" : "Terminal.app"} window (${label})`
+      );
+      console.log(`  Directory: ${dir}`);
+    }
+  } catch (err) {
+    if (!silent) {
+      console.error(`Failed to open terminal: ${err.message}`);
+      console.log(`
+Run this manually in a new terminal:
+`);
+      console.log(`  ${shellSetup}`);
+    }
+  } finally {
+    try {
+      unlinkSync(tmpFile);
+    } catch {
+    }
+  }
+}
+function openWindowsPowerShell(shellSetup, label, dir, requestedShell, silent) {
+  const requestedExecutable = requestedShell === "powershell" ? "powershell.exe" : "pwsh.exe";
+  const executable = findExecutable(requestedExecutable) ? requestedExecutable : "powershell.exe";
+  const startCommand = [
+    "Start-Process",
+    `-FilePath ${psSingleQuoted2(executable)}`,
+    `-ArgumentList @('-NoExit','-NoProfile','-Command',${psSingleQuoted2(shellSetup)})`
+  ].join(" ");
+  const launcher = findExecutable("pwsh.exe") ? "pwsh.exe" : "powershell.exe";
+  try {
+    execFileSync2(
+      launcher,
+      ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", startCommand],
+      {
+        stdio: "ignore"
+      }
+    );
+    if (!silent) {
+      console.log(
+        `Opened ${executable === "pwsh.exe" ? "PowerShell" : "Windows PowerShell"} window (${label})`
+      );
+      console.log(`  Directory: ${dir}`);
+    }
+  } catch (err) {
+    if (!silent) {
+      console.error(`Failed to open PowerShell: ${err.message}`);
+      console.log(`
+Run this manually in a new PowerShell terminal:
+`);
+      console.log(`  ${shellSetup}`);
+    }
+  }
+}
+function openTerminalWindow(opts) {
+  const { shellSetup, label, dir, shell, silent = false } = opts;
+  const platform = opts.platform ?? process.platform;
+  if (platform === "darwin" && !isPowerShellShell(shell)) {
+    openMacTerminal(shellSetup, label, dir, silent);
+    return;
+  }
+  if (platform === "win32" && isPowerShellShell(shell)) {
+    openWindowsPowerShell(shellSetup, label, dir, shell, silent);
+    return;
+  }
+  if (!silent) {
+    console.log(`Run this in a new terminal:
+`);
+    console.log(`  ${shellSetup}
+`);
+    console.log(
+      `(Automatic terminal opening is only supported on macOS Terminal/iTerm2 and Windows PowerShell for now.)`
+    );
+  }
+}
+
+// src/cli/agent-harness.ts
+var AGENT_HARNESSES = [
+  { id: "claude-code", label: "Claude Code", kind: "cli", command: "claude" },
+  { id: "codex", label: "Codex", kind: "cli", command: "codex" },
+  { id: "opencode", label: "opencode", kind: "cli", command: "opencode" },
+  {
+    id: "cursor",
+    label: "Cursor",
+    kind: "app",
+    command: "cursor",
+    candidatePaths: {
+      win32: [
+        join12(homedir8(), "AppData", "Local", "Programs", "cursor", "Cursor.exe")
+      ],
+      darwin: ["/Applications/Cursor.app/Contents/MacOS/Cursor"]
+    }
+  },
+  { id: "copilot", label: "GitHub Copilot", kind: "app", command: "copilot" },
+  {
+    id: "antigravity",
+    label: "Antigravity",
+    kind: "app",
+    command: "antigravity"
+  }
+];
+function getHarness(id) {
+  return AGENT_HARNESSES.find((h) => h.id === id);
+}
+function resolveHarnessExecutable(harness, overrideCommand, deps = {}) {
+  const find = deps.find ?? findExecutable;
+  const exists = deps.exists ?? existsSync12;
+  const platform = deps.platform ?? process.platform;
+  const found = find(overrideCommand || harness.command);
+  if (found) return found;
+  if (harness.kind === "app") {
+    for (const candidate of harness.candidatePaths?.[platform] ?? []) {
+      if (exists(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+function planHarnessLaunch(harness, opts) {
+  if (harness.kind === "cli") {
+    const invocation = isPowerShellShell(opts.shell) ? `& ${psSingleQuoted2(opts.executable)}` : JSON.stringify(opts.executable);
+    return {
+      kind: "cli",
+      shell: opts.shell,
+      shellSetup: buildShellSetupCommand(
+        opts.workspace,
+        opts.shell,
+        invocation
+      )
+    };
+  }
+  return { kind: "app", executable: opts.executable, args: [opts.workspace] };
+}
+function launchHarness(harness, opts) {
+  const plan = planHarnessLaunch(harness, opts);
+  if (plan.kind === "cli") {
+    openTerminalWindow({
+      shellSetup: plan.shellSetup,
+      label: `agent-${harness.id}`,
+      dir: opts.workspace,
+      shell: plan.shell,
+      silent: opts.silent,
+      platform: opts.platform
+    });
+    return;
+  }
+  spawn(plan.executable, plan.args, {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true
+  }).unref();
+  if (!opts.silent) {
+    console.log(`Launched ${harness.label} in ${opts.workspace}`);
+  }
+}
+
 // src/cli/commands/agent.ts
 var C = {
   reset: "\x1B[0m",
@@ -4890,7 +5241,7 @@ var C = {
 };
 var SUPPORTED_AGENTS = ["opencode"];
 function agentsMdPresent(cwd = process.cwd()) {
-  return existsSync11(join11(cwd, "AGENTS.md"));
+  return existsSync13(join13(cwd, "AGENTS.md"));
 }
 function printStatus() {
   const installed = hasCommand("opencode");
@@ -4928,19 +5279,87 @@ var installCmd = new Command("install").description("Download and install the de
   console.log(`  Start it with: ${C.cyan}opencode${C.reset}`);
 });
 var statusCmd = new Command("status").description("Show whether the agent is installed and wired to ZAM").action(printStatus);
-var agentCommand = new Command("agent").description("Provision and inspect the agent that drives ZAM sessions").addCommand(installCmd).addCommand(statusCmd).action(printStatus);
+var listCmd = new Command("list").description("List known agent harnesses and whether each is detected").action(() => {
+  console.log(`${C.bold}Agent harnesses${C.reset}`);
+  for (const h of AGENT_HARNESSES) {
+    const status = resolveHarnessExecutable(h) ? `${C.green}detected${C.reset}` : `${C.yellow}not found${C.reset}`;
+    console.log(
+      `  ${h.id.padEnd(13)} ${status}  ${C.dim}${h.label} (${h.kind})${C.reset}`
+    );
+  }
+  console.log(`
+  ${C.dim}Open one: zam agent open --id <id>${C.reset}`);
+  console.log(
+    `  ${C.dim}Point ZAM at a custom path: zam settings set agent.<id>.command <path>${C.reset}`
+  );
+});
+var openCmd = new Command("open").description("Open an agent harness in the workspace, ready to drive ZAM").option(
+  "--id <id>",
+  "Harness id (default: agent.default setting, else first detected)"
+).option("--dir <path>", "Workspace directory (defaults to cwd)").option(
+  "--shell <type>",
+  "Shell type: zsh | bash | pwsh | powershell (auto-detected)"
+).action(async (opts) => {
+  let shell;
+  try {
+    shell = normalizeShell(opts.shell);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+  let id = opts.id;
+  let override;
+  let db;
+  try {
+    db = await openDatabase();
+    if (!id) {
+      id = await getSetting(db, "agent.default") || void 0;
+    }
+    if (!id) {
+      id = AGENT_HARNESSES.find((h) => resolveHarnessExecutable(h))?.id;
+    }
+    if (id) {
+      override = await getSetting(db, `agent.${id}.command`) || void 0;
+    }
+  } finally {
+    await db?.close();
+  }
+  if (!id) {
+    console.error(
+      "No agent harness configured or detected. Install one (e.g. zam agent install), then set a default: zam settings set agent.default <id>."
+    );
+    process.exit(1);
+  }
+  const harness = getHarness(id);
+  if (!harness) {
+    console.error(
+      `Unknown harness: ${id}. Known: ${AGENT_HARNESSES.map((h) => h.id).join(", ")}.`
+    );
+    process.exit(1);
+  }
+  const executable = resolveHarnessExecutable(harness, override);
+  if (!executable) {
+    console.error(
+      `${harness.label} was not detected. Install it, or point ZAM at it: zam settings set agent.${harness.id}.command <path>.`
+    );
+    process.exit(1);
+  }
+  const workspace = opts.dir ?? process.cwd();
+  launchHarness(harness, { executable, workspace, shell });
+});
+var agentCommand = new Command("agent").description("Provision and inspect the agent that drives ZAM sessions").addCommand(installCmd).addCommand(statusCmd).addCommand(openCmd).addCommand(listCmd).action(printStatus);
 
 // src/cli/commands/bridge.ts
-import { execFileSync as execFileSync2 } from "child_process";
+import { execFileSync as execFileSync4 } from "child_process";
 import { randomBytes as randomBytes2 } from "crypto";
-import { readdirSync as readdirSync2, readFileSync as readFileSync10, rmSync as rmSync2 } from "fs";
-import { homedir as homedir8, tmpdir as tmpdir2 } from "os";
-import { join as join13 } from "path";
-import { Command as Command2 } from "commander";
+import { existsSync as existsSync17, readdirSync as readdirSync2, readFileSync as readFileSync11, rmSync as rmSync2 } from "fs";
+import { homedir as homedir10, tmpdir as tmpdir3 } from "os";
+import { basename as basename5, join as join17, resolve as resolve5 } from "path";
+import { Command as Command4 } from "commander";
 
 // src/cli/llm/client.ts
-import { spawn } from "child_process";
-import { existsSync as existsSync12 } from "fs";
+import { spawn as spawn2 } from "child_process";
+import { existsSync as existsSync14 } from "fs";
 var DEFAULT_LLM_URL = "http://localhost:8000/v1";
 var DEFAULT_LLM_MODEL = "qwen3.5:4b";
 var DEFAULT_LLM_API_KEY = "sk-none";
@@ -4953,22 +5372,149 @@ async function getLlmConfig(db) {
     locale: await getSetting(db, "system.locale") || "en"
   };
 }
-async function getVisionConfig(db) {
-  const base = await getLlmConfig(db);
-  const maxFramesStr = await getSetting(db, "llm.vision.max_frames");
-  const maxFrames = maxFramesStr ? parseInt(maxFramesStr, 10) : 100;
+function getCloudModelRecommendation(url) {
+  const lowercase = url.toLowerCase();
+  if (lowercase.includes("openrouter.ai")) {
+    return "openrouter/free";
+  }
+  if (lowercase.includes("openai.com") || lowercase.includes("api.openai")) {
+    return "gpt-5-mini";
+  }
+  if (lowercase.includes("googleapis.com") || lowercase.includes("google")) {
+    return "gemini-3.5-flash";
+  }
+  if (lowercase.includes("deepseek.com")) {
+    return "deepseek-v4-flash";
+  }
+  if (lowercase.includes("mimo")) {
+    return "mimo-v2.5";
+  }
+  return null;
+}
+function inferApiFlavor(url) {
+  try {
+    return new URL(url).hostname.toLowerCase().endsWith("anthropic.com") ? "anthropic-messages" : "chat-completions";
+  } catch {
+    return "chat-completions";
+  }
+}
+async function readJsonSetting(db, key) {
+  const raw = await getSetting(db, key);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function resolveProviderApiKey(rec) {
+  if (rec.apiKey) return rec.apiKey;
+  if (rec.apiKeyRef) {
+    const key = getProviderApiKey(rec.apiKeyRef);
+    if (key) return key;
+  }
+  return DEFAULT_LLM_API_KEY;
+}
+async function getProviderForRole(db, role) {
+  const enabled = role === "vision" ? await getSetting(db, "llm.vision.enabled") === "true" : await getSetting(db, "llm.enabled") === "true";
+  const base = await getLegacyRoleConfig(db, role, enabled);
+  const providers = await readJsonSetting(db, "llm.providers");
+  const roles = await readJsonSetting(db, "llm.roles");
+  const binding = roles?.[role];
+  let resolved = base;
+  if (providers && binding?.primary && providers[binding.primary]) {
+    const primary = materializeProvider(
+      providers[binding.primary],
+      base,
+      role,
+      {
+        providerName: binding.primary,
+        source: "shared"
+      }
+    );
+    const fallback = binding.fallback && providers[binding.fallback] ? materializeProvider(providers[binding.fallback], base, role, {
+      providerName: binding.fallback,
+      source: "shared"
+    }) : void 0;
+    resolved = { ...primary, fallback };
+  }
+  const machine = getMachineAiConfig();
+  const machineProviders = machine.providers;
+  const machineBinding = machine.roles?.[role];
+  if (machineProviders && machineBinding?.primary && machineProviders[machineBinding.primary]) {
+    const primary = materializeProvider(
+      machineProviders[machineBinding.primary],
+      resolved,
+      role,
+      { providerName: machineBinding.primary, source: "machine" }
+    );
+    const fallback = machineBinding.fallback && machineProviders[machineBinding.fallback] ? materializeProvider(
+      machineProviders[machineBinding.fallback],
+      resolved,
+      role,
+      { providerName: machineBinding.fallback, source: "machine" }
+    ) : void 0;
+    return { ...primary, fallback };
+  }
+  return resolved;
+}
+function materializeProvider(rec, base, role, meta) {
+  const url = rec.url || base.url;
   return {
-    enabled: await getSetting(db, "llm.vision.enabled") === "true",
-    url: await getSetting(db, "llm.vision.url") || base.url,
-    model: await getSetting(db, "llm.vision.model") || base.model,
-    apiKey: await getSetting(db, "llm.vision.api_key") || base.apiKey,
+    enabled: base.enabled,
+    url,
+    model: rec.model || base.model,
+    apiKey: resolveProviderApiKey(rec),
+    apiFlavor: rec.apiFlavor || inferApiFlavor(url),
     locale: base.locale,
-    maxFrames: Number.isNaN(maxFrames) ? 100 : maxFrames
+    providerName: meta.providerName,
+    label: rec.label,
+    source: meta.source,
+    local: rec.local ?? isLocalEndpoint(url),
+    ...role === "vision" ? { maxFrames: base.maxFrames } : {}
   };
 }
-var LANGUAGE_NAMES = {
-  en: "English",
-  de: "German",
+async function getLegacyRoleConfig(db, role, enabled) {
+  const base = await getLlmConfig(db);
+  if (role === "vision") {
+    const maxFramesStr = await getSetting(db, "llm.vision.max_frames");
+    const parsed = maxFramesStr ? parseInt(maxFramesStr, 10) : 100;
+    const url = await getSetting(db, "llm.vision.url") || base.url;
+    let model = await getSetting(db, "llm.vision.model");
+    if (!model) model = getCloudModelRecommendation(url) || base.model;
+    return {
+      enabled,
+      url,
+      model,
+      apiKey: await getSetting(db, "llm.vision.api_key") || base.apiKey,
+      apiFlavor: inferApiFlavor(url),
+      locale: base.locale,
+      source: "legacy",
+      local: isLocalEndpoint(url),
+      maxFrames: Number.isNaN(parsed) ? 100 : parsed
+    };
+  }
+  return {
+    enabled,
+    url: base.url,
+    model: base.model,
+    apiKey: base.apiKey,
+    apiFlavor: inferApiFlavor(base.url),
+    locale: base.locale,
+    source: "legacy",
+    local: isLocalEndpoint(base.url)
+  };
+}
+function assertChatCompletions(cfg) {
+  if (cfg.apiFlavor !== "chat-completions") {
+    throw new Error(
+      `This role is configured for a "${cfg.apiFlavor}" provider, which is not supported here yet. Use a chat-completions provider for the recall role.`
+    );
+  }
+}
+var LANGUAGE_NAMES = {
+  en: "English",
+  de: "German",
   es: "Spanish",
   fr: "French",
   pt: "Portuguese",
@@ -5006,10 +5552,11 @@ async function readChatContent(res, label) {
   return content.trim();
 }
 async function generateQuestionViaLLM(db, input8) {
-  const cfg = await getLlmConfig(db);
+  const cfg = await getProviderForRole(db, "recall");
   if (!cfg.enabled) {
     throw new Error("LLM integration is disabled in settings (llm.enabled)");
   }
+  assertChatCompletions(cfg);
   const bloom = input8.bloomLevel >= 1 && input8.bloomLevel <= 5 ? input8.bloomLevel : 1;
   const verb = BLOOM_VERBS2[bloom];
   const langName = LANGUAGE_NAMES[cfg.locale] || "English";
@@ -5049,10 +5596,11 @@ Active-Recall Question:`;
   return readChatContent(res, "LLM request");
 }
 async function evaluateAnswerViaLLM(db, input8) {
-  const cfg = await getLlmConfig(db);
+  const cfg = await getProviderForRole(db, "recall");
   if (!cfg.enabled) {
     throw new Error("LLM integration is disabled in settings (llm.enabled)");
   }
+  assertChatCompletions(cfg);
   const langName = LANGUAGE_NAMES[cfg.locale] || "English";
   const ratingPrefix = LOCALIZED_RATING_PREFIX[cfg.locale] || "Suggested rating";
   const systemPrompt = `You are ZAM, an extremely warm, encouraging, and patient skills trainer.
@@ -5102,10 +5650,11 @@ Evaluation:`;
   return readChatContent(res, "LLM evaluation");
 }
 async function translateQuestionViaLLM(db, question) {
-  const cfg = await getLlmConfig(db);
+  const cfg = await getProviderForRole(db, "recall");
   if (!cfg.enabled) {
     throw new Error("LLM integration is disabled in settings");
   }
+  assertChatCompletions(cfg);
   const targetLang = LANGUAGE_NAMES[cfg.locale] || "English";
   const systemPrompt = `You are a highly precise translator. Translate the given active-recall question into clear, natural ${targetLang}.
 Output ONLY the raw translation. Do not include any headers, preamble, quotes, or conversational filler.`;
@@ -5159,38 +5708,174 @@ async function getAvailableModels(url, apiKey = DEFAULT_LLM_API_KEY) {
     return [];
   }
 }
-async function checkVisionReadiness(db) {
-  const { enabled, url, model, apiKey } = await getVisionConfig(db);
-  const visionModelSetting = await getSetting(db, "llm.vision.model");
-  const visionModelExplicit = !!visionModelSetting;
-  let online = false;
-  let availableModels = [];
-  let modelAvailable = false;
-  if (enabled) {
-    online = await isLlmOnline(url);
-    if (online) {
-      availableModels = await getAvailableModels(url, apiKey);
-      modelAvailable = availableModels.length === 0 || availableModels.some(
-        (candidate) => candidate.toLowerCase() === model.toLowerCase()
-      );
-    }
+function isLocalEndpoint(url) {
+  return url.includes("localhost") || url.includes("127.0.0.1") || url.includes("[::1]") || url.includes("::1");
+}
+async function checkProviderEndpoint(endpoint) {
+  const online = await isLlmOnline(endpoint.url);
+  if (!online) {
+    return {
+      endpoint,
+      online: false,
+      availableModels: [],
+      modelAvailable: false
+    };
   }
+  const availableModels = await getAvailableModels(
+    endpoint.url,
+    endpoint.apiKey
+  );
+  const modelAvailable = availableModels.length === 0 || availableModels.some(
+    (candidate) => candidate.toLowerCase() === endpoint.model.toLowerCase()
+  );
+  return { endpoint, online, availableModels, modelAvailable };
+}
+function isEndpointUsable(readiness) {
+  return readiness.online && readiness.modelAvailable;
+}
+function providerChain(primary) {
+  return [primary, ...primary.fallback ? [primary.fallback] : []];
+}
+async function checkProviderChain(primary) {
+  let first;
+  for (const endpoint of providerChain(primary)) {
+    const readiness = await checkProviderEndpoint(endpoint);
+    first ??= readiness;
+    if (isEndpointUsable(readiness)) {
+      return { primary: first, firstUsable: readiness };
+    }
+  }
+  return { primary: first };
+}
+async function isVisionProviderModelExplicit(db, active) {
+  if (await getSetting(db, "llm.vision.model")) return true;
+  const providers = await readJsonSetting(db, "llm.providers");
+  const roles = await readJsonSetting(db, "llm.roles");
+  const binding = roles?.vision;
+  const sharedExplicit = [binding?.primary, binding?.fallback].some((id) => {
+    if (!id) return false;
+    const rec = providers?.[id];
+    return rec?.model === active.model && (rec.url === void 0 || rec.url === active.url);
+  });
+  if (sharedExplicit) return true;
+  const machine = getMachineAiConfig();
+  const machineBinding = machine.roles?.vision;
+  return [machineBinding?.primary, machineBinding?.fallback].some((id) => {
+    if (!id) return false;
+    const rec = machine.providers?.[id];
+    return rec?.model === active.model && (rec.url === void 0 || rec.url === active.url);
+  });
+}
+async function checkVisionReadiness(db) {
+  const cfg = await getProviderForRole(db, "vision");
+  const chain = cfg.enabled ? await checkProviderChain(cfg) : void 0;
+  const selected = chain?.firstUsable ?? chain?.primary;
+  const active = selected?.endpoint ?? cfg;
+  const online = selected?.online ?? false;
+  const availableModels = selected?.availableModels ?? [];
+  const modelAvailable = selected?.modelAvailable ?? false;
+  const visionModelExplicit = await isVisionProviderModelExplicit(db, active);
   let warning;
-  if (enabled && online && modelAvailable && !visionModelExplicit) {
-    warning = `No explicit vision model configured (llm.vision.model). Falling back to base model "${model}", which may not support image input. Set a multimodal model: zam settings set llm.vision.model <model>`;
+  if (cfg.enabled && online && modelAvailable && !visionModelExplicit) {
+    const cloudRec = getCloudModelRecommendation(active.url);
+    if (cloudRec && active.model === cloudRec) {
+    } else {
+      warning = `No explicit vision model configured (llm.vision.model). Falling back to base model "${active.model}", which may not support image input. Set a multimodal model: zam settings set llm.vision.model <model>`;
+    }
   }
   return {
-    enabled,
+    enabled: cfg.enabled,
     online,
-    url,
-    model,
+    url: active.url,
+    model: active.model,
     modelAvailable,
     availableModels,
-    usable: enabled && online && modelAvailable,
+    usable: cfg.enabled && online && modelAvailable,
     visionModelExplicit,
     warning
   };
 }
+function summarizeFallback(provider) {
+  if (!provider) return void 0;
+  return {
+    providerName: provider.providerName,
+    label: provider.label,
+    source: provider.source,
+    url: provider.url,
+    model: provider.model,
+    apiFlavor: provider.apiFlavor,
+    local: provider.local
+  };
+}
+async function getProviderRoleStatus(db, role) {
+  const cfg = await getProviderForRole(db, role);
+  const unsupportedProvider = role !== "vision" && cfg.apiFlavor !== "chat-completions";
+  if (!cfg.enabled) {
+    return {
+      role,
+      enabled: false,
+      providerName: cfg.providerName,
+      label: cfg.label,
+      source: cfg.source,
+      url: cfg.url,
+      model: cfg.model,
+      apiFlavor: cfg.apiFlavor,
+      local: cfg.local,
+      online: false,
+      modelAvailable: false,
+      availableModels: [],
+      usable: false,
+      reason: "disabled",
+      fallback: summarizeFallback(cfg.fallback)
+    };
+  }
+  if (unsupportedProvider) {
+    return {
+      role,
+      enabled: true,
+      providerName: cfg.providerName,
+      label: cfg.label,
+      source: cfg.source,
+      url: cfg.url,
+      model: cfg.model,
+      apiFlavor: cfg.apiFlavor,
+      local: cfg.local,
+      online: false,
+      modelAvailable: false,
+      availableModels: [],
+      usable: false,
+      reason: "unsupported-provider",
+      fallback: summarizeFallback(cfg.fallback)
+    };
+  }
+  let selected;
+  if (role === "vision") {
+    const chain = await checkProviderChain(cfg);
+    selected = chain.firstUsable ?? chain.primary;
+  } else {
+    selected = await checkProviderEndpoint(cfg);
+  }
+  const active = selected.endpoint;
+  const usable = selected.online && selected.modelAvailable;
+  const reason = usable ? void 0 : selected.online ? "model-not-found" : "offline";
+  return {
+    role,
+    enabled: true,
+    providerName: active.providerName,
+    label: active.label,
+    source: active.source,
+    url: active.url,
+    model: active.model,
+    apiFlavor: active.apiFlavor,
+    local: active.local,
+    online: selected.online,
+    modelAvailable: selected.modelAvailable,
+    availableModels: selected.availableModels,
+    usable,
+    reason,
+    fallback: summarizeFallback(cfg.fallback)
+  };
+}
 function detectRunner(url, model) {
   let runner = "unknown";
   let port = "8000";
@@ -5211,16 +5896,16 @@ function spawnLocalRunner(url, model) {
   const { runner, port } = detectRunner(url, model);
   try {
     if (runner === "fastflowlm") {
-      const flmExe = existsSync12("C:\\Program Files\\flm\\flm.exe") ? "C:\\Program Files\\flm\\flm.exe" : "flm";
+      const flmExe = existsSync14("C:\\Program Files\\flm\\flm.exe") ? "C:\\Program Files\\flm\\flm.exe" : "flm";
       if (!hasCommand("flm") && flmExe === "flm") return;
-      spawn(flmExe, ["serve", model, "--port", port], {
+      spawn2(flmExe, ["serve", model, "--port", port], {
         detached: true,
         stdio: "ignore",
         windowsHide: true
       }).unref();
     } else if (runner === "ollama" || runner === "generic") {
       if (!hasCommand("ollama")) return;
-      spawn("ollama", ["serve"], {
+      spawn2("ollama", ["serve"], {
         detached: true,
         stdio: "ignore",
         windowsHide: true
@@ -5232,7 +5917,7 @@ function spawnLocalRunner(url, model) {
 async function startLocalRunner(url, model, locale) {
   const { runner, port } = detectRunner(url, model);
   if (runner === "fastflowlm") {
-    const flmExe = existsSync12("C:\\Program Files\\flm\\flm.exe") ? "C:\\Program Files\\flm\\flm.exe" : "flm";
+    const flmExe = existsSync14("C:\\Program Files\\flm\\flm.exe") ? "C:\\Program Files\\flm\\flm.exe" : "flm";
     if (!hasCommand("flm") && flmExe === "flm") {
       console.warn(
         "\x1B[31m\u2717 FastFlowLM is configured but could not be found on the system.\x1B[0m"
@@ -5245,7 +5930,7 @@ async function startLocalRunner(url, model, locale) {
       `\x1B[36mStarting FastFlowLM serve process: ${flmExe} ${args.join(" ")}\x1B[0m`
     );
     try {
-      spawn(flmExe, args, {
+      spawn2(flmExe, args, {
         detached: true,
         stdio: "ignore",
         windowsHide: true
@@ -5266,7 +5951,7 @@ async function startLocalRunner(url, model, locale) {
     }
     console.log("\x1B[36mStarting Ollama serve process: ollama serve\x1B[0m");
     try {
-      spawn("ollama", ["serve"], {
+      spawn2("ollama", ["serve"], {
         detached: true,
         stdio: "ignore",
         windowsHide: true
@@ -5289,7 +5974,7 @@ async function startLocalRunner(url, model, locale) {
   let attempts = 0;
   const dotsPerLine = 30;
   while (true) {
-    await new Promise((resolve5) => setTimeout(resolve5, 500));
+    await new Promise((resolve8) => setTimeout(resolve8, 500));
     if (await isLlmOnline(url)) {
       if (attempts > 0) process.stdout.write("\n");
       return true;
@@ -5314,12 +5999,18 @@ async function startLocalRunner(url, model, locale) {
   }
 }
 async function ensureLocalLlmRunning(db) {
-  const cfg = await getLlmConfig(db);
+  const cfg = await getProviderForRole(db, "recall");
   if (!cfg.enabled) {
     return { usable: false, reason: "disabled" };
   }
+  if (cfg.apiFlavor !== "chat-completions") {
+    console.warn(
+      `\x1B[31m\u2717 Recall is configured for "${cfg.apiFlavor}", but active recall currently supports chat-completions providers only.\x1B[0m`
+    );
+    return { usable: false, reason: "unsupported-provider" };
+  }
   const { url, model, apiKey, locale } = cfg;
-  const isLocal = url.includes("localhost") || url.includes("127.0.0.1");
+  const isLocal = isLocalEndpoint(url);
   console.log(`Checking if local LLM server is online at ${url}...`);
   let online = await isLlmOnline(url);
   if (!online && isLocal) {
@@ -5353,8 +6044,9 @@ async function ensureLocalLlmRunning(db) {
 }
 async function ensureLlmReadyHeadless(db, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 25e3;
-  const { enabled, url, model, apiKey } = await getLlmConfig(db);
-  if (!enabled) {
+  const cfg = await getProviderForRole(db, "recall");
+  const { url, model, apiKey } = cfg;
+  if (!cfg.enabled) {
     return {
       usable: false,
       reason: "disabled",
@@ -5363,7 +6055,16 @@ async function ensureLlmReadyHeadless(db, opts = {}) {
       availableModels: []
     };
   }
-  const isLocal = url.includes("localhost") || url.includes("127.0.0.1");
+  if (cfg.apiFlavor !== "chat-completions") {
+    return {
+      usable: false,
+      reason: "unsupported-provider",
+      online: false,
+      model,
+      availableModels: []
+    };
+  }
+  const isLocal = isLocalEndpoint(url);
   let online = await isLlmOnline(url);
   if (!online && isLocal) {
     spawnLocalRunner(url, model);
@@ -5428,8 +6129,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
   const dotsPerLine = 30;
   while (true) {
     let timeoutId;
-    const timeoutPromise = new Promise((resolve5) => {
-      timeoutId = setTimeout(() => resolve5("timeout"), timeoutMs);
+    const timeoutPromise = new Promise((resolve8) => {
+      timeoutId = setTimeout(() => resolve8("timeout"), timeoutMs);
     });
     const dotsInterval = setInterval(() => {
       process.stdout.write(".");
@@ -5502,8 +6203,8 @@ async function ensureHighQualityQuestion(db, token) {
 // src/cli/llm/vision.ts
 import { randomBytes } from "crypto";
 import { readFileSync as readFileSync9 } from "fs";
-import { tmpdir } from "os";
-import { basename as basename2, join as join12 } from "path";
+import { tmpdir as tmpdir2 } from "os";
+import { basename as basename3, join as join14 } from "path";
 var LANGUAGE_NAMES2 = {
   en: "English",
   de: "German",
@@ -5530,7 +6231,7 @@ var ACTION_TYPES2 = /* @__PURE__ */ new Set([
   "window-change"
 ]);
 async function observeUiSnapshotViaLLM(db, input8) {
-  const cfg = await getVisionConfig(db);
+  const cfg = await getProviderForRole(db, "vision");
   if (!cfg.enabled) {
     throw new Error(
       "Vision observation is disabled in settings (llm.vision.enabled)"
@@ -5539,21 +6240,21 @@ async function observeUiSnapshotViaLLM(db, input8) {
   const imageUrls = [];
   const isVideo = /\.(mp4|mov|m4v|avi|mkv|webm)$/i.test(input8.imagePath);
   if (isVideo) {
-    const { mkdirSync: mkdirSync12, readdirSync: readdirSync3, rmSync: rmSync3 } = await import("fs");
-    const { execSync: execSync7 } = await import("child_process");
-    const tempDir = join12(
-      tmpdir(),
+    const { mkdirSync: mkdirSync13, readdirSync: readdirSync3, rmSync: rmSync3 } = await import("fs");
+    const { execSync: execSync6 } = await import("child_process");
+    const tempDir = join14(
+      tmpdir2(),
       `zam-frames-${randomBytes(4).toString("hex")}`
     );
-    mkdirSync12(tempDir, { recursive: true });
+    mkdirSync13(tempDir, { recursive: true });
     try {
-      execSync7(
+      execSync6(
         `ffmpeg -i "${input8.imagePath}" -vf "fps=1/3,scale=1280:-1" -vsync vfr "${tempDir}/frame_%03d.png"`,
         { stdio: "ignore" }
       );
       let files = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
       if (files.length === 0) {
-        execSync7(
+        execSync6(
           `ffmpeg -i "${input8.imagePath}" -vframes 1 "${tempDir}/frame_001.png"`,
           { stdio: "ignore" }
         );
@@ -5574,7 +6275,7 @@ async function observeUiSnapshotViaLLM(db, input8) {
         }
       }
       for (const file of sampledFiles) {
-        const bytes = readFileSync9(join12(tempDir, file));
+        const bytes = readFileSync9(join14(tempDir, file));
         imageUrls.push(`data:image/png;base64,${bytes.toString("base64")}`);
       }
     } finally {
@@ -5592,42 +6293,92 @@ async function observeUiSnapshotViaLLM(db, input8) {
   if (imageUrls.length === 0) {
     throw new Error("No image data available for vision analysis");
   }
-  const model = input8.model ?? cfg.model;
-  const content = await requestVisionDraft({
-    url: cfg.url,
-    apiKey: cfg.apiKey || DEFAULT_LLM_API_KEY,
-    model,
-    locale: cfg.locale,
-    imageUrls,
-    input: input8
-  });
-  let draft;
-  try {
-    draft = extractDraft(content);
-  } catch {
-    return uncertainReport(
-      input8,
-      "Vision model returned output that could not be parsed as JSON."
-    );
+  const endpoints = [
+    {
+      url: cfg.url,
+      apiKey: cfg.apiKey || DEFAULT_LLM_API_KEY,
+      model: input8.model ?? cfg.model,
+      apiFlavor: cfg.apiFlavor
+    }
+  ];
+  if (cfg.fallback) {
+    endpoints.push({
+      url: cfg.fallback.url,
+      apiKey: cfg.fallback.apiKey || DEFAULT_LLM_API_KEY,
+      model: cfg.fallback.model,
+      apiFlavor: cfg.fallback.apiFlavor
+    });
   }
-  const report = buildReport(input8, draft);
-  if (!isUiObservationReport(report)) {
+  let lastRequestError;
+  let sawUnparseableDraft = false;
+  let sawInvalidDraft = false;
+  for (const endpoint of endpoints) {
+    let content;
+    try {
+      content = await requestVisionDraft({
+        ...endpoint,
+        locale: cfg.locale,
+        imageUrls,
+        input: input8
+      });
+    } catch (err) {
+      lastRequestError = err;
+      continue;
+    }
+    let draft;
+    try {
+      draft = extractDraft(content);
+    } catch {
+      sawUnparseableDraft = true;
+      continue;
+    }
+    const report = buildReport(input8, draft);
+    if (isUiObservationReport(report)) {
+      return report;
+    }
+    sawInvalidDraft = true;
+  }
+  if (lastRequestError && !sawUnparseableDraft && !sawInvalidDraft) {
+    throw lastRequestError;
+  }
+  if (sawInvalidDraft) {
     return uncertainReport(
       input8,
       "Vision model returned an invalid UI report draft."
     );
   }
-  return report;
+  return uncertainReport(
+    input8,
+    "Vision model returned output that could not be parsed as JSON."
+  );
 }
-async function requestVisionDraft(args) {
-  const language = LANGUAGE_NAMES2[args.locale] ?? "English";
-  const schema = `{
+var VISION_SYSTEM_PROMPT = "You are ZAM's UI observer. Return only strict JSON. Do not include markdown, prose, or fields outside the requested schema.";
+function visionSchema(language) {
+  return `{
   "kind": "progress | step-completed | error | help-seeking | uncertain",
   "summary": "short factual UI summary in ${language}",
   "actions": [{"type": "click | shortcut | typing | scroll | window-change", "target": "optional UI target", "result": "optional visible result"}],
   "candidateTokens": [{"slug": "optional-kebab-case-skill-token", "confidence": 0.0, "rationale": "why this token may matter"}],
   "confidence": 0.0
 }`;
+}
+function visionUserText(args, language) {
+  const intro = args.imageUrls.length > 1 ? "Observe this sequence of Windows/macOS application snapshots showing a task performed over time." : "Observe this Windows/macOS application snapshot for a learning session.";
+  return `${intro}
+Application process: ${args.input.application.processName}
+Window title: ${args.input.application.windowTitle ?? "(unknown)"}
+
+Return this JSON draft only:
+${visionSchema(language)}`;
+}
+async function requestVisionDraft(args) {
+  if (args.apiFlavor === "anthropic-messages") {
+    return requestAnthropicVisionDraft(args);
+  }
+  return requestChatCompletionsVisionDraft(args);
+}
+async function requestChatCompletionsVisionDraft(args) {
+  const language = LANGUAGE_NAMES2[args.locale] ?? "English";
   const res = await fetchWithInteractiveTimeout(
     `${args.url}/chat/completions`,
     {
@@ -5639,27 +6390,11 @@ async function requestVisionDraft(args) {
       body: JSON.stringify({
         model: args.model,
         messages: [
-          {
-            role: "system",
-            content: "You are ZAM's UI observer. Return only strict JSON. Do not include markdown, prose, or fields outside the requested schema."
-          },
+          { role: "system", content: VISION_SYSTEM_PROMPT },
           {
             role: "user",
             content: [
-              {
-                type: "text",
-                text: args.imageUrls.length > 1 ? `Observe this sequence of Windows/macOS application snapshots showing a task performed over time.
-Application process: ${args.input.application.processName}
-Window title: ${args.input.application.windowTitle ?? "(unknown)"}
-
-Return this JSON draft only:
-${schema}` : `Observe this Windows/macOS application snapshot for a learning session.
-Application process: ${args.input.application.processName}
-Window title: ${args.input.application.windowTitle ?? "(unknown)"}
-
-Return this JSON draft only:
-${schema}`
-              },
+              { type: "text", text: visionUserText(args, language) },
               ...args.imageUrls.map((url) => ({
                 type: "image_url",
                 image_url: { url }
@@ -5702,6 +6437,64 @@ ${schema}`
   }
   return content.trim();
 }
+function dataUrlToAnthropicImage(dataUrl) {
+  const match = dataUrl.match(/^data:(image\/[a-zA-Z]+);base64,(.+)$/);
+  if (!match) {
+    throw new Error("Unsupported image data for Anthropic vision request");
+  }
+  return {
+    type: "image",
+    source: { type: "base64", media_type: match[1], data: match[2] }
+  };
+}
+async function requestAnthropicVisionDraft(args) {
+  const language = LANGUAGE_NAMES2[args.locale] ?? "English";
+  const base = args.url.replace(/\/+$/, "").replace(/\/v1$/, "");
+  const res = await fetchWithInteractiveTimeout(`${base}/v1/messages`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": args.apiKey,
+      "anthropic-version": "2023-06-01"
+    },
+    body: JSON.stringify({
+      model: args.model,
+      max_tokens: args.input.maxTokens ?? 450,
+      system: VISION_SYSTEM_PROMPT,
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: visionUserText(args, language) },
+            ...args.imageUrls.map(dataUrlToAnthropicImage)
+          ]
+        }
+      ]
+    }),
+    locale: args.locale,
+    hardTimeoutMs: args.input.hardTimeoutMs ?? 18e4
+  });
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(
+      `Vision LLM request failed: ${res.statusText} (${res.status}) - ${errorText}`
+    );
+  }
+  const data = await res.json();
+  if (data.error !== void 0) {
+    throw new Error(`Vision model failed: ${formatModelError(data.error)}`);
+  }
+  if (data.stop_reason === "refusal") {
+    throw new Error("Vision model refused the request (safety classifier).");
+  }
+  const text = data.content?.find(
+    (b) => b.type === "text" && typeof b.text === "string"
+  )?.text;
+  if (!text) {
+    throw new Error("Empty response from vision model");
+  }
+  return text.trim();
+}
 function extractDraft(content) {
   const fenced = content.match(/```(?:json)?\s*([\s\S]*?)```/i);
   const candidate = (fenced?.[1] ?? content).trim();
@@ -5730,7 +6523,7 @@ function buildReport(input8, draft) {
     evidence: [
       {
         type: "keyframe",
-        ref: input8.evidenceRef ?? basename2(input8.imagePath),
+        ref: input8.evidenceRef ?? basename3(input8.imagePath),
         redacted: input8.redacted ?? false
       }
     ],
@@ -5752,7 +6545,7 @@ function uncertainReport(input8, summary) {
     evidence: [
       {
         type: "keyframe",
-        ref: input8.evidenceRef ?? basename2(input8.imagePath),
+        ref: input8.evidenceRef ?? basename3(input8.imagePath),
         redacted: input8.redacted ?? false
       }
     ],
@@ -5862,50 +6655,728 @@ function jsonOut(data) {
   console.log(JSON.stringify(data, null, 2));
 }
 
-// src/cli/commands/bridge.ts
-var isServeMode = false;
-function jsonOut2(data) {
-  console.log(JSON.stringify(data, null, 2));
+// src/cli/commands/workspace.ts
+import { execFileSync as execFileSync3 } from "child_process";
+import { existsSync as existsSync16, mkdirSync as mkdirSync9, writeFileSync as writeFileSync8 } from "fs";
+import { homedir as homedir9 } from "os";
+import { join as join16, resolve as resolve4 } from "path";
+import { confirm, input } from "@inquirer/prompts";
+import { Command as Command3 } from "commander";
+
+// src/cli/commands/setup.ts
+import {
+  copyFileSync as copyFileSync2,
+  existsSync as existsSync15,
+  mkdirSync as mkdirSync8,
+  readFileSync as readFileSync10,
+  writeFileSync as writeFileSync7
+} from "fs";
+import { basename as basename4, dirname as dirname5, join as join15, resolve as resolve3 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { Command as Command2 } from "commander";
+var packageRoot = [
+  fileURLToPath2(new URL("../..", import.meta.url)),
+  fileURLToPath2(new URL("../../..", import.meta.url))
+].find((candidate) => existsSync15(join15(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
+var ALL_SETUP_AGENTS = ["claude", "copilot", "codex", "agent"];
+var SKILL_PAIRS = [
+  {
+    from: join15(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
+    to: join15(".claude", "skills", "zam", "SKILL.md"),
+    agents: ["claude"]
+  },
+  {
+    from: join15(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
+    to: join15(".agent", "skills", "zam", "SKILL.md"),
+    agents: ["agent"]
+  },
+  {
+    from: join15(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
+    to: join15(".agents", "skills", "zam", "SKILL.md"),
+    agents: ["copilot", "codex"]
+  }
+];
+function parseSetupAgents(value) {
+  if (!value || value.trim().toLowerCase() === "all") {
+    return new Set(ALL_SETUP_AGENTS);
+  }
+  const aliases = {
+    claude: ["claude"],
+    copilot: ["copilot"],
+    codex: ["codex"],
+    agent: ["agent"],
+    opencode: ["agent"]
+  };
+  const selected = /* @__PURE__ */ new Set();
+  for (const raw of value.split(",")) {
+    const key = raw.trim().toLowerCase();
+    const mapped = aliases[key];
+    if (!mapped) {
+      throw new Error(
+        `Unknown agent "${raw}". Use: all, claude, copilot, codex, agent.`
+      );
+    }
+    for (const item of mapped) selected.add(item);
+  }
+  return selected;
 }
-function jsonError(message) {
-  if (isServeMode) {
-    throw new Error(JSON.stringify({ error: message }));
+function copySkills(force, cwd = process.cwd(), agents = parseSetupAgents(), dryRun = false) {
+  let anyAction = false;
+  for (const { from, to, agents: pairAgents } of SKILL_PAIRS) {
+    if (!pairAgents.some((agent) => agents.has(agent))) continue;
+    const dest = join15(cwd, to);
+    if (!existsSync15(from)) {
+      console.warn(`  warn  source not found, skipping: ${from}`);
+      continue;
+    }
+    if (existsSync15(dest) && !force) {
+      console.log(`  skip  ${to} (already present \xE2\u20AC\u201D use --force to update)`);
+      continue;
+    }
+    if (dryRun) {
+      console.log(`  would copy  ${to}`);
+      anyAction = true;
+      continue;
+    }
+    mkdirSync8(dirname5(dest), { recursive: true });
+    copyFileSync2(from, dest);
+    console.log(`  copy  ${to}`);
+    anyAction = true;
+  }
+  if (!anyAction && !force) {
+    console.log(
+      "\nSkill files are already up to date. Run with --force to overwrite."
+    );
   }
-  console.log(JSON.stringify({ error: message }, null, 2));
-  process.exit(1);
 }
-function parseNonNegativeIntegerOption(name, value) {
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed < 0) {
-    jsonError(`${name} must be a non-negative integer`);
+function formatDatabaseInitTarget(target) {
+  switch (target.kind) {
+    case "local":
+      return `ZAM database at ${target.location} (local SQLite)`;
+    case "turso-remote":
+      return `ZAM database via Turso remote at ${target.location}`;
+    case "turso-native":
+      return `ZAM database via Turso native driver at ${target.location}`;
+    case "turso-replica":
+      return `ZAM database replica at ${target.location} syncing from ${target.syncUrl}`;
   }
-  return parsed;
 }
-async function withDb2(fn) {
-  await withDb(fn, jsonError);
+async function initDatabase(skipInit) {
+  if (skipInit) return;
+  try {
+    const target = getDatabaseTargetInfo();
+    const db = await openDatabaseWithSync({ initialize: true });
+    await db.close();
+    console.log(`  init  ${formatDatabaseInitTarget(target)}`);
+  } catch (err) {
+    const msg = err.message;
+    if (!msg.includes("already")) {
+      console.warn(`  warn  database init: ${msg}`);
+    } else {
+      console.log(`  skip  database already initialized`);
+    }
+  }
 }
-async function getReviewTarget2(db, cardId, userId) {
-  const target = await db.prepare(
-    `SELECT c.id AS card_id, c.token_id, c.user_id, t.slug
-       FROM cards c
-       JOIN tokens t ON t.id = c.token_id
-       WHERE c.id = ?`
-  ).get(cardId);
-  if (!target) {
-    jsonError(`Card not found: ${cardId}`);
+var ZAM_BLOCK_START = "<!-- ZAM:START -->";
+var ZAM_BLOCK_END = "<!-- ZAM:END -->";
+function upsertMarkedBlock(dest, blockBody, dryRun) {
+  const block = `${ZAM_BLOCK_START}
+${blockBody.trim()}
+${ZAM_BLOCK_END}`;
+  if (!existsSync15(dest)) {
+    if (!dryRun) {
+      mkdirSync8(dirname5(dest), { recursive: true });
+      writeFileSync7(dest, `${block}
+`, "utf8");
+    }
+    return "write";
   }
-  if (target.user_id !== userId) {
-    jsonError(`Card ${cardId} does not belong to user ${userId}`);
+  const existing = readFileSync10(dest, "utf8");
+  if (existing.includes(block)) return "skip";
+  const start = existing.indexOf(ZAM_BLOCK_START);
+  const end = existing.indexOf(ZAM_BLOCK_END);
+  const next = start >= 0 && end > start ? `${existing.slice(0, start)}${block}${existing.slice(end + ZAM_BLOCK_END.length)}` : `${existing.trimEnd()}
+
+${block}
+`;
+  if (!dryRun) writeFileSync7(dest, next, "utf8");
+  return start >= 0 && end > start ? "update" : "write";
+}
+function logInstructionAction(action, label, dryRun) {
+  if (action === "skip") {
+    console.log(`  skip  ${label} (ZAM block already present)`);
+  } else {
+    console.log(`  ${dryRun ? "would " : ""}${action} ${label}`);
   }
-  return target;
 }
-function parseTokenUpdates(opts) {
-  const updates = {};
-  if (opts.concept !== void 0) updates.concept = opts.concept;
-  if (opts.domain !== void 0) updates.domain = opts.domain;
-  if (opts.bloom !== void 0)
-    updates.bloom_level = Number(opts.bloom);
-  if (opts.context !== void 0) updates.context = opts.context;
+function writeClaudeMd(skipClaudeMd, cwd = process.cwd(), opts = {}) {
+  if (skipClaudeMd) return;
+  const dest = join15(cwd, "CLAUDE.md");
+  if (existsSync15(dest)) {
+    if (!opts.updateExisting) {
+      console.log(`  skip  CLAUDE.md (already present)`);
+      return;
+    }
+    const action = upsertMarkedBlock(
+      dest,
+      `## ZAM learning sessions
+
+ZAM is available in this repository. Use the \`zam\` skill in Claude Code to turn real work into an observed learning session with active recall and FSRS scheduling.
+
+- Skill files live under \`.claude/skills/zam/\`.
+- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
+- Run \`zam setup --target . --agents claude --force\` after upgrading ZAM to refresh the skill.`,
+      Boolean(opts.dryRun)
+    );
+    logInstructionAction(action, "CLAUDE.md", Boolean(opts.dryRun));
+    return;
+  }
+  const name = basename4(cwd);
+  const content = `# ZAM Personal Kernel \xE2\u20AC\u201D ${name}
+
+This is a ZAM personal instance. ZAM builds lasting skills through spaced
+repetition during real work \xE2\u20AC\u201D not separate study sessions.
+
+## First time here?
+Run \`/setup\` in Claude Code or Gemini CLI to complete first-time setup.
+
+## Regular use
+Run \`/zam\` to start a learning session on whatever you are working on.
+
+## What lives here
+- \`beliefs/\` \xE2\u20AC\u201D your worldview, approved by git commit
+- \`goals/\` \xE2\u20AC\u201D your objectives, decomposed into tasks and learning tokens
+
+## Fast-changing data
+Learning tokens, cards, and review history live in local SQLite by default.
+Use \`zam connector setup turso\` to store cloud credentials in
+\`~/.zam/credentials.json\` and use a Turso database across machines.
+`;
+  if (opts.dryRun) {
+    console.log(`  would write CLAUDE.md`);
+  } else {
+    writeFileSync7(dest, content, "utf8");
+    console.log(`  write CLAUDE.md`);
+  }
+}
+function writeAgentsMd(skipAgentsMd, cwd = process.cwd(), opts = {}) {
+  if (skipAgentsMd) return;
+  const dest = join15(cwd, "AGENTS.md");
+  if (existsSync15(dest)) {
+    if (!opts.updateExisting) {
+      console.log(`  skip  AGENTS.md (already present)`);
+      return;
+    }
+    const action = upsertMarkedBlock(
+      dest,
+      `## ZAM learning sessions
+
+ZAM is available in this repository. Select the \`zam\` skill through \`/skills\` or invoke \`$zam\` where supported to turn real work into an observed learning session with active recall and FSRS scheduling.
+
+- Skill files live under \`.agents/skills/zam/\`.
+- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
+- Run \`zam setup --target . --agents copilot,codex --force\` after upgrading ZAM to refresh the skill.`,
+      Boolean(opts.dryRun)
+    );
+    logInstructionAction(action, "AGENTS.md", Boolean(opts.dryRun));
+    return;
+  }
+  const name = basename4(cwd);
+  const content = `# ZAM Personal Kernel - ${name}
+
+This is a ZAM personal instance. ZAM builds lasting skills through spaced
+repetition during real work, not separate study sessions.
+
+## First time here?
+Run \`zam setup\` from the shell. When this repository includes
+\`.agents/skills/setup/\`, you can instead select \`setup\` through \`/skills\`
+or invoke \`$setup\`.
+
+## Regular use
+Select the \`zam\` skill through \`/skills\` or invoke \`$zam\` to start a
+learning session on whatever you are working on.
+
+## What lives here
+- \`beliefs/\` - your worldview, approved by git commit
+- \`goals/\` - your objectives, decomposed into tasks and learning tokens
+
+## Fast-changing data
+Learning tokens, cards, and review history live in local SQLite by default.
+Use \`zam connector setup turso\` to store cloud credentials in
+\`~/.zam/credentials.json\` and use a Turso database across machines.
+
+## Codex skills
+Codex discovers repository skills under \`.agents/skills/\`. Run
+\`zam setup --force\` after upgrading \`zam-core\` to refresh them.
+`;
+  if (opts.dryRun) {
+    console.log(`  would write AGENTS.md`);
+  } else {
+    writeFileSync7(dest, content, "utf8");
+    console.log(`  write AGENTS.md`);
+  }
+}
+function writeCopilotInstructions(cwd = process.cwd(), opts = {}) {
+  const dest = join15(cwd, ".github", "copilot-instructions.md");
+  const action = upsertMarkedBlock(
+    dest,
+    `## ZAM learning sessions
+
+ZAM is available in this repository through \`.agents/skills/zam/\`. Use the \`zam\` skill from Copilot-compatible skill selection surfaces to turn real work into an observed learning session with active recall and FSRS scheduling.
+
+- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
+- Run \`zam setup --target . --agents copilot --force\` after upgrading ZAM to refresh the skill.`,
+    Boolean(opts.dryRun)
+  );
+  logInstructionAction(
+    action,
+    ".github/copilot-instructions.md",
+    Boolean(opts.dryRun)
+  );
+}
+var setupCommand = new Command2("setup").description(
+  "Distribute ZAM skill files into this personal instance and initialize the database"
+).option(
+  "--force",
+  "overwrite existing skill files (use after upgrading zam)",
+  false
+).option("--skip-init", "skip database initialization", false).option("--skip-claude-md", "skip CLAUDE.md generation", false).option("--skip-agents-md", "skip AGENTS.md generation", false).option("--target <path>", "repository/workspace directory to set up").option(
+  "--agents <list>",
+  "comma-separated agents to wire: all, claude, copilot, codex, agent"
+).option(
+  "--dry-run",
+  "show what would be written without changing files",
+  false
+).action(
+  async (opts) => {
+    let agents;
+    try {
+      agents = parseSetupAgents(opts.agents);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    const target = resolve3(opts.target ?? process.cwd());
+    const updateExistingInstructions = Boolean(opts.target) || opts.force;
+    console.log(
+      `Setting up ZAM in ${target}${opts.dryRun ? " (dry run)" : ""}
+`
+    );
+    copySkills(opts.force, target, agents, opts.dryRun);
+    await initDatabase(opts.skipInit || opts.dryRun);
+    if (agents.has("claude")) {
+      writeClaudeMd(opts.skipClaudeMd, target, {
+        dryRun: opts.dryRun,
+        updateExisting: updateExistingInstructions
+      });
+    }
+    if (agents.has("copilot") || agents.has("codex") || agents.has("agent")) {
+      writeAgentsMd(opts.skipAgentsMd, target, {
+        dryRun: opts.dryRun,
+        updateExisting: updateExistingInstructions
+      });
+    }
+    if (agents.has("copilot") && (opts.target || opts.agents)) {
+      writeCopilotInstructions(target, {
+        dryRun: opts.dryRun,
+        updateExisting: updateExistingInstructions
+      });
+    }
+    console.log(
+      "\nDone. Run `zam whoami --set <your-id>` to set your identity. Start the `zam` skill with `/zam` in Claude/Gemini-compatible clients or `$zam` (or `/skills`) in Codex."
+    );
+  }
+);
+
+// src/cli/commands/workspace.ts
+function runGit(cwd, args) {
+  try {
+    return execFileSync3("git", args, {
+      cwd,
+      stdio: "pipe",
+      encoding: "utf8"
+    }).trim();
+  } catch (err) {
+    throw new Error(`Git command failed: ${err.message}`);
+  }
+}
+function ghRepoCreateArgs(repoName, repoVisibility) {
+  return ["repo", "create", repoName, repoVisibility, "--source=.", "--push"];
+}
+function gitRemoteArgs(githubUrl, hasOrigin) {
+  return hasOrigin ? ["remote", "set-url", "origin", githubUrl] : ["remote", "add", "origin", githubUrl];
+}
+var workspaceCommand = new Command3("workspace").description(
+  "Manage your ZAM learning workspace"
+);
+var WORKSPACE_KINDS = [
+  "personal",
+  "team",
+  "family",
+  "community",
+  "organization",
+  "custom"
+];
+var WORKSPACE_SOURCE_CONTROLS = [
+  "github",
+  "azure-devops",
+  "git",
+  "none"
+];
+function parseWorkspaceKind(value) {
+  const kind = (value ?? "custom").toLowerCase();
+  if (WORKSPACE_KINDS.includes(kind)) {
+    return kind;
+  }
+  throw new Error(
+    `Invalid workspace kind: ${value}. Use ${WORKSPACE_KINDS.join(", ")}.`
+  );
+}
+function parseWorkspaceSourceControl(value) {
+  if (!value) return void 0;
+  const source = value.toLowerCase();
+  if (WORKSPACE_SOURCE_CONTROLS.includes(source)) {
+    return source;
+  }
+  throw new Error(
+    `Invalid source control: ${value}. Use ${WORKSPACE_SOURCE_CONTROLS.join(", ")}.`
+  );
+}
+function parseScopes(value) {
+  if (!value) return void 0;
+  const scopes = value.split(",").map((item) => item.trim()).filter(Boolean);
+  return scopes.length > 0 ? scopes : void 0;
+}
+function requireWorkspace(id) {
+  const workspace = getConfiguredWorkspaces().find((item) => item.id === id);
+  if (!workspace) {
+    throw new Error(
+      `Workspace "${id}" is not configured. Add it with: zam workspace add ${id} --path <dir>`
+    );
+  }
+  return workspace;
+}
+workspaceCommand.command("list").description("List configured ZAM workspaces").option("--json", "Output as JSON").action((opts) => {
+  const workspaces = getConfiguredWorkspaces();
+  if (opts.json) {
+    console.log(JSON.stringify({ workspaces }, null, 2));
+    return;
+  }
+  console.log("Configured ZAM workspaces:\n");
+  if (workspaces.length === 0) {
+    console.log(
+      "  (none) \u2014 add one: zam workspace add personal --path <dir>"
+    );
+    return;
+  }
+  for (const workspace of workspaces) {
+    const label = workspace.label ? ` (${workspace.label})` : "";
+    console.log(`  ${workspace.id}${label}`);
+    console.log(`      kind: ${workspace.kind}`);
+    console.log(`      path: ${workspace.path}`);
+    if (workspace.sourceControl) {
+      console.log(`      source: ${workspace.sourceControl}`);
+    }
+    if (workspace.knowledgeScopes?.length) {
+      console.log(`      scopes: ${workspace.knowledgeScopes.join(", ")}`);
+    }
+  }
+});
+workspaceCommand.command("add <id>").description("Register an existing directory as a ZAM workspace").requiredOption("--path <dir>", "Existing workspace/repository directory").option(
+  "--kind <kind>",
+  `Workspace kind (${WORKSPACE_KINDS.join(" | ")})`,
+  "custom"
+).option("--label <label>", "Human-readable label").option(
+  "--source-control <provider>",
+  `Source-control provider (${WORKSPACE_SOURCE_CONTROLS.join(" | ")})`
+).option("--scopes <list>", "Comma-separated knowledge scopes").option("--default-agent <id>", "Default agent harness for this workspace").action((id, opts) => {
+  try {
+    const path = resolve4(String(opts.path));
+    if (!existsSync16(path)) {
+      console.error(`Workspace path does not exist: ${path}`);
+      process.exit(1);
+    }
+    const workspace = {
+      id,
+      kind: parseWorkspaceKind(opts.kind),
+      path,
+      ...opts.label ? { label: opts.label } : {},
+      ...opts.sourceControl ? { sourceControl: parseWorkspaceSourceControl(opts.sourceControl) } : {},
+      ...parseScopes(opts.scopes) ? { knowledgeScopes: parseScopes(opts.scopes) } : {},
+      ...opts.defaultAgent ? { defaultAgent: opts.defaultAgent } : {}
+    };
+    upsertConfiguredWorkspace(workspace);
+    console.log(`Registered workspace "${id}" at ${path}.`);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+});
+workspaceCommand.command("setup <id>").description("Install ZAM skills into a configured workspace").option(
+  "--agents <list>",
+  "comma-separated agents to wire: all, claude, copilot, codex, agent"
+).option(
+  "--force",
+  "overwrite existing skill files and refresh ZAM blocks",
+  false
+).option(
+  "--dry-run",
+  "show what would be written without changing files",
+  false
+).action((id, opts) => {
+  try {
+    const workspace = requireWorkspace(id);
+    const agents = parseSetupAgents(opts.agents);
+    console.log(
+      `Setting up workspace "${workspace.id}" in ${workspace.path}${opts.dryRun ? " (dry run)" : ""}
+`
+    );
+    copySkills(
+      Boolean(opts.force),
+      workspace.path,
+      agents,
+      Boolean(opts.dryRun)
+    );
+    if (agents.has("claude")) {
+      writeClaudeMd(false, workspace.path, {
+        dryRun: Boolean(opts.dryRun),
+        updateExisting: true
+      });
+    }
+    if (agents.has("copilot") || agents.has("codex") || agents.has("agent")) {
+      writeAgentsMd(false, workspace.path, {
+        dryRun: Boolean(opts.dryRun),
+        updateExisting: true
+      });
+    }
+    if (agents.has("copilot")) {
+      writeCopilotInstructions(workspace.path, {
+        dryRun: Boolean(opts.dryRun),
+        updateExisting: true
+      });
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+});
+workspaceCommand.command("publish").description("Publish your local workspace sandbox to GitHub").action(async () => {
+  let db;
+  let workspaceDir = "";
+  try {
+    db = await openDatabase();
+    workspaceDir = await getSetting(db, "personal.workspace_dir") || "";
+    await db.close();
+  } catch {
+    await db?.close();
+  }
+  if (!workspaceDir) {
+    console.error(
+      "\x1B[31m\u2717 No active workspace configured. Please run `zam init` first.\x1B[0m"
+    );
+    process.exit(1);
+  }
+  if (!existsSync16(workspaceDir)) {
+    console.error(
+      `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
+    );
+    process.exit(1);
+  }
+  console.log(`
+Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
+  if (!hasCommand("git")) {
+    console.error(
+      "\x1B[31m\u2717 Git command was not found on this system. Please install Git first.\x1B[0m"
+    );
+    process.exit(1);
+  }
+  const gitignorePath = join16(workspaceDir, ".gitignore");
+  if (!existsSync16(gitignorePath)) {
+    writeFileSync8(
+      gitignorePath,
+      "node_modules/\n.agent/\n.agents/\n.claude/\n.gemini/\n.goose/\n*.log\n",
+      "utf8"
+    );
+  }
+  const hasGitRepo = existsSync16(join16(workspaceDir, ".git"));
+  if (!hasGitRepo) {
+    console.log("Initializing local Git repository...");
+    runGit(workspaceDir, ["init", "-b", "main"]);
+    runGit(workspaceDir, ["add", "."]);
+    runGit(workspaceDir, [
+      "commit",
+      "-m",
+      "chore: initial workspace sandbox bootstrap"
+    ]);
+    console.log("\x1B[32m\u2713 Local Git repository initialized.\x1B[0m");
+  } else {
+    console.log("Git repository is already initialized.");
+  }
+  const repoName = await input({
+    message: "Choose a name for your GitHub repository:",
+    default: "zam-personal"
+  });
+  const isPrivate = await confirm({
+    message: "Should the repository be private?",
+    default: true
+  });
+  const repoVisibility = isPrivate ? "--private" : "--public";
+  if (hasCommand("gh")) {
+    console.log("GitHub CLI detected! Automating repository creation...");
+    const proceedGh = await confirm({
+      message: "Would you like ZAM to create the repository using the GitHub CLI?",
+      default: true
+    });
+    if (proceedGh) {
+      try {
+        console.log(`Creating GitHub repository ${repoName}...`);
+        execFileSync3("gh", ghRepoCreateArgs(repoName, repoVisibility), {
+          cwd: workspaceDir,
+          stdio: "inherit"
+        });
+        console.log(
+          "\n\x1B[32m\u2713 Successfully published workspace to GitHub!\x1B[0m"
+        );
+        process.exit(0);
+      } catch (err) {
+        console.warn(
+          `\x1B[33m\u26A0 GitHub CLI creation failed: ${err.message}\x1B[0m`
+        );
+      }
+    }
+  }
+  console.log(
+    "\n\x1B[1mPlease create the repository manually on GitHub:\x1B[0m"
+  );
+  console.log("  1. Go to https://github.com/new");
+  console.log(`  2. Name it exactly: \x1B[36m${repoName}\x1B[0m`);
+  console.log(
+    `  3. Choose \x1B[36m${isPrivate ? "Private" : "Public"}\x1B[0m`
+  );
+  console.log(
+    "  4. Do NOT initialize it with README, .gitignore, or license"
+  );
+  console.log("  5. Click 'Create repository'\n");
+  const githubUrl = await input({
+    message: "Paste the repository Git URL (e.g. git@github.com:user/repo.git):"
+  });
+  if (githubUrl) {
+    try {
+      console.log("Linking remote repository and pushing...");
+      let hasOrigin = false;
+      try {
+        runGit(workspaceDir, ["remote", "get-url", "origin"]);
+        hasOrigin = true;
+      } catch {
+      }
+      runGit(workspaceDir, gitRemoteArgs(githubUrl, hasOrigin));
+      runGit(workspaceDir, ["push", "-u", "origin", "main"]);
+      console.log(
+        "\x1B[32m\u2713 Successfully linked and pushed to GitHub!\x1B[0m"
+      );
+    } catch (err) {
+      console.error(
+        `\x1B[31m\u2717 Push failed: ${err.message}\x1B[0m`
+      );
+      console.log(
+        "You can push manually later using: git push -u origin main"
+      );
+    }
+  }
+});
+async function backupDatabaseTo(db, targetDir) {
+  const backupDir = join16(targetDir, "zam-backups");
+  mkdirSync9(backupDir, { recursive: true });
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const dest = join16(backupDir, `zam-${stamp}.db`);
+  await db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
+  return dest;
+}
+workspaceCommand.command("data-dir").description("Print the ZAM data directory (database, credentials, config)").option("--json", "Output as JSON").action((opts) => {
+  const dir = join16(homedir9(), ".zam");
+  console.log(opts.json ? JSON.stringify({ dataDir: dir }) : dir);
+});
+workspaceCommand.command("backup").description("Back up the local ZAM database into your workspace").option(
+  "--dir <path>",
+  "Target directory (default: workspace dir, else ~/Documents/zam)"
+).option("--json", "Output as JSON").action(async (opts) => {
+  const target = getDatabaseTargetInfo();
+  if (target.kind !== "local") {
+    const reason = `The database is ${target.kind} (${target.location}); file backup applies only to a local database \u2014 your Turso remote is already the cloud backup.`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, reason }));
+      return;
+    }
+    console.error(`\x1B[33m\u26A0 ${reason}\x1B[0m`);
+    process.exit(1);
+  }
+  let db;
+  try {
+    db = await openDatabase();
+    const workspaceDir = opts.dir || await getSetting(db, "personal.workspace_dir") || join16(homedir9(), "Documents", "zam");
+    const dest = await backupDatabaseTo(db, workspaceDir);
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, path: dest }));
+    } else {
+      console.log(`\x1B[32m\u2713 Database backed up to ${dest}\x1B[0m`);
+    }
+  } catch (err) {
+    const reason = err.message;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, reason }));
+    } else {
+      console.error(`\x1B[31m\u2717 Backup failed: ${reason}\x1B[0m`);
+    }
+    process.exit(1);
+  } finally {
+    await db?.close();
+  }
+});
+
+// src/cli/commands/bridge.ts
+var isServeMode = false;
+function jsonOut2(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function jsonError(message) {
+  if (isServeMode) {
+    throw new Error(JSON.stringify({ error: message }));
+  }
+  console.log(JSON.stringify({ error: message }, null, 2));
+  process.exit(1);
+}
+function parseNonNegativeIntegerOption(name, value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    jsonError(`${name} must be a non-negative integer`);
+  }
+  return parsed;
+}
+async function withDb2(fn) {
+  await withDb(fn, jsonError);
+}
+async function getReviewTarget2(db, cardId, userId) {
+  const target = await db.prepare(
+    `SELECT c.id AS card_id, c.token_id, c.user_id, t.slug
+       FROM cards c
+       JOIN tokens t ON t.id = c.token_id
+       WHERE c.id = ?`
+  ).get(cardId);
+  if (!target) {
+    jsonError(`Card not found: ${cardId}`);
+  }
+  if (target.user_id !== userId) {
+    jsonError(`Card ${cardId} does not belong to user ${userId}`);
+  }
+  return target;
+}
+function parseTokenUpdates(opts) {
+  const updates = {};
+  if (opts.concept !== void 0) updates.concept = opts.concept;
+  if (opts.domain !== void 0) updates.domain = opts.domain;
+  if (opts.bloom !== void 0)
+    updates.bloom_level = Number(opts.bloom);
+  if (opts.context !== void 0) updates.context = opts.context;
   if (opts.sourceLink !== void 0) {
     updates.source_link = opts.sourceLink === "" ? null : opts.sourceLink;
   }
@@ -5918,7 +7389,7 @@ function parseTokenUpdates(opts) {
   }
   return updates;
 }
-var bridgeCommand = new Command2("bridge").description(
+var bridgeCommand = new Command4("bridge").description(
   "Machine-readable JSON protocol for AI integration"
 );
 bridgeCommand.command("check-due").description("Check due cards for a user (JSON)").option("--user <id>", "User ID (default: whoami)").option("--domain <domain>", "Filter by knowledge domain").action(async (opts) => {
@@ -5946,6 +7417,160 @@ bridgeCommand.command("check-due").description("Check due cards for a user (JSON
     });
   });
 });
+bridgeCommand.command("backup-db").description("Back up the local database into the workspace (JSON)").option(
+  "--dir <path>",
+  "Target directory (default: workspace dir, else ~/Documents/zam)"
+).action(async (opts) => {
+  const target = getDatabaseTargetInfo();
+  if (target.kind !== "local") {
+    jsonOut2({
+      ok: false,
+      reason: "remote",
+      target: target.kind,
+      location: target.location
+    });
+    return;
+  }
+  await withDb2(async (db) => {
+    const workspaceDir = opts.dir || await getSetting(db, "personal.workspace_dir") || join17(homedir10(), "Documents", "zam");
+    const path = await backupDatabaseTo(db, workspaceDir);
+    jsonOut2({ ok: true, path });
+  });
+});
+bridgeCommand.command("workspace-info").description("Report the workspace dir, its default, and the data dir (JSON)").action(async () => {
+  await withDb2(async (db) => {
+    const workspaceDir = await getSetting(db, "personal.workspace_dir") || null;
+    jsonOut2({
+      workspaceDir,
+      defaultWorkspaceDir: join17(homedir10(), "Documents", "zam"),
+      dataDir: join17(homedir10(), ".zam")
+    });
+  });
+});
+bridgeCommand.command("workspace-list").description("List configured ZAM workspaces (JSON)").action(async () => {
+  await withDb2(async (db) => {
+    const workspaceDir = await getSetting(db, "personal.workspace_dir") || null;
+    jsonOut2({
+      workspaces: getConfiguredWorkspaces(),
+      workspaceDir,
+      defaultWorkspaceDir: join17(homedir10(), "Documents", "zam"),
+      dataDir: join17(homedir10(), ".zam")
+    });
+  });
+});
+function workspaceIdFromPath(dir) {
+  const base = basename5(dir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  const prefix = base || "workspace";
+  const existing = new Set(getConfiguredWorkspaces().map((item) => item.id));
+  if (!existing.has(prefix)) return prefix;
+  let index = 2;
+  while (existing.has(`${prefix}-${index}`)) index++;
+  return `${prefix}-${index}`;
+}
+function parseBridgeWorkspaceKind(value) {
+  const kind = (value || "custom").toLowerCase();
+  if (kind === "personal" || kind === "team" || kind === "family" || kind === "community" || kind === "organization" || kind === "custom") {
+    return kind;
+  }
+  jsonError(`Invalid workspace kind: ${value}`);
+}
+bridgeCommand.command("workspace-add").description("Register an existing directory as a ZAM workspace (JSON)").requiredOption("--path <dir>", "Existing workspace/repository directory").option("--id <id>", "Workspace id").option("--label <label>", "Human-readable label").option("--kind <kind>", "Workspace kind", "custom").action(async (opts) => {
+  const raw = String(opts.path ?? "").trim();
+  if (!raw) jsonError("A non-empty --path is required");
+  const path = resolve5(raw);
+  if (!existsSync17(path)) jsonError(`Workspace path does not exist: ${path}`);
+  const id = String(opts.id || workspaceIdFromPath(path)).trim();
+  if (!id) jsonError("A non-empty --id is required");
+  const workspace = {
+    id,
+    label: opts.label || basename5(path) || id,
+    kind: parseBridgeWorkspaceKind(opts.kind),
+    path
+  };
+  await withDb2(async (db) => {
+    await setSetting(db, "personal.workspace_dir", path);
+    upsertConfiguredWorkspace(workspace);
+    jsonOut2({
+      ok: true,
+      workspace,
+      workspaces: getConfiguredWorkspaces(),
+      workspaceDir: path
+    });
+  });
+});
+bridgeCommand.command("set-workspace-dir").description("Set the personal workspace directory (JSON)").requiredOption("--dir <path>", "Path to the workspace directory").action(async (opts) => {
+  const raw = String(opts.dir ?? "").trim();
+  if (!raw) jsonError("A non-empty --dir is required");
+  const dir = resolve5(raw);
+  await withDb2(async (db) => {
+    await setSetting(db, "personal.workspace_dir", dir);
+    jsonOut2({ ok: true, workspaceDir: dir });
+  });
+});
+bridgeCommand.command("agent-list").description("List agent harnesses with detection state + the default (JSON)").action(async () => {
+  await withDb2(async (db) => {
+    const configuredDefault = await getSetting(db, "agent.default") || null;
+    const harnesses = await Promise.all(
+      AGENT_HARNESSES.map(async (h) => {
+        const override = await getSetting(db, `agent.${h.id}.command`) || void 0;
+        return {
+          id: h.id,
+          label: h.label,
+          kind: h.kind,
+          detected: resolveHarnessExecutable(h, override) !== null
+        };
+      })
+    );
+    const fallbackDefault = harnesses.find((h) => h.detected)?.id ?? null;
+    jsonOut2({ harnesses, default: configuredDefault ?? fallbackDefault });
+  });
+});
+bridgeCommand.command("agent-open").description("Launch an agent harness in the workspace (JSON)").option(
+  "--id <id>",
+  "Harness id (default: agent.default setting, else first detected)"
+).option("--workspace <id>", "Configured workspace id to open").option("--dir <path>", "Explicit workspace directory to open").action(async (opts) => {
+  await withDb2(async (db) => {
+    let id = opts.id || await getSetting(db, "agent.default") || void 0;
+    if (!id) {
+      id = AGENT_HARNESSES.find((h) => resolveHarnessExecutable(h))?.id;
+    }
+    if (!id) {
+      jsonError(
+        "No agent harness configured or detected. Install one (Claude Code, Codex, opencode) or set agent.default."
+      );
+    }
+    const harness = getHarness(id);
+    if (!harness) {
+      jsonError(`Unknown harness: ${id}`);
+    }
+    const override = await getSetting(db, `agent.${harness.id}.command`) || void 0;
+    const executable = resolveHarnessExecutable(harness, override);
+    if (!executable) {
+      jsonError(
+        `${harness.label} was not detected. Set its path: zam settings set agent.${harness.id}.command <path>`
+      );
+    }
+    const configuredWorkspace = opts.workspace ? getConfiguredWorkspaces().find((item) => item.id === opts.workspace) : void 0;
+    if (opts.workspace && !configuredWorkspace) {
+      jsonError(`Workspace is not configured: ${opts.workspace}`);
+    }
+    let workspace = opts.dir || configuredWorkspace?.path || await getSetting(db, "personal.workspace_dir") || join17(homedir10(), "Documents", "zam");
+    if (!existsSync17(workspace)) workspace = homedir10();
+    launchHarness(harness, {
+      executable,
+      workspace,
+      shell: normalizeShell(void 0),
+      silent: true
+    });
+    jsonOut2({
+      ok: true,
+      id: harness.id,
+      label: harness.label,
+      kind: harness.kind,
+      workspace
+    });
+  });
+});
 bridgeCommand.command("get-review").description("Get next review card with prompt (JSON)").option("--user <id>", "User ID (default: whoami)").option("--no-resolve", "Skip resolving the token's source_link into context").action(async (opts) => {
   await withDb2(async (db) => {
     const userId = await resolveUser(opts, db, { json: true });
@@ -6304,7 +7929,7 @@ bridgeCommand.command("discover-skills").description(
   "20"
 ).action(async (opts) => {
   try {
-    const monitorDir = join13(homedir8(), ".zam", "monitor");
+    const monitorDir = join17(homedir10(), ".zam", "monitor");
     let files;
     try {
       files = readdirSync2(monitorDir).filter((f) => f.endsWith(".jsonl"));
@@ -6317,7 +7942,7 @@ bridgeCommand.command("discover-skills").description(
       return;
     }
     const limit = Number(opts.limit);
-    const sorted = files.map((f) => ({ name: f, path: join13(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
+    const sorted = files.map((f) => ({ name: f, path: join17(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
     const sessionCommands = /* @__PURE__ */ new Map();
     for (const file of sorted) {
       const sessionId = file.name.replace(".jsonl", "");
@@ -6429,7 +8054,7 @@ bridgeCommand.command("observe-ui-snapshot").description(
 });
 function resolveWindowsPowerShell() {
   try {
-    execFileSync2("where.exe", ["pwsh.exe"], { stdio: "ignore" });
+    execFileSync4("where.exe", ["pwsh.exe"], { stdio: "ignore" });
     return "pwsh";
   } catch {
     return "powershell";
@@ -6444,7 +8069,7 @@ function captureScreenshot(outputPath, hwnd, processName) {
     throw new Error(`Invalid process name format: ${processName}`);
   }
   if (platform === "win32") {
-    const stdout = execFileSync2(
+    const stdout = execFileSync4(
       resolveWindowsPowerShell(),
       [
         "-NoProfile",
@@ -6757,13 +8382,13 @@ Write-CaptureResult "fullscreen" $hwndVal $matchedBy
   } else if (platform === "darwin") {
     if (hwnd) {
       const parsedHwnd = hwnd.startsWith("0x") ? parseInt(hwnd, 16) : parseInt(hwnd, 10);
-      execFileSync2("screencapture", ["-l", String(parsedHwnd), outputPath], {
+      execFileSync4("screencapture", ["-l", String(parsedHwnd), outputPath], {
         stdio: "pipe"
       });
       return { method: "screencapture-window", target: null };
     } else if (processName) {
       try {
-        const windowId = execFileSync2(
+        const windowId = execFileSync4(
           "osascript",
           [
             "-e",
@@ -6772,17 +8397,17 @@ Write-CaptureResult "fullscreen" $hwndVal $matchedBy
           { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }
         ).trim();
         if (windowId && /^\d+$/.test(windowId)) {
-          execFileSync2("screencapture", ["-l", windowId, outputPath], {
+          execFileSync4("screencapture", ["-l", windowId, outputPath], {
             stdio: "pipe"
           });
           return { method: "screencapture-window", target: null };
         }
       } catch {
       }
-      execFileSync2("screencapture", ["-x", outputPath], { stdio: "pipe" });
+      execFileSync4("screencapture", ["-x", outputPath], { stdio: "pipe" });
       return { method: "screencapture-full", target: null };
     } else {
-      execFileSync2("screencapture", ["-x", outputPath], { stdio: "pipe" });
+      execFileSync4("screencapture", ["-x", outputPath], { stdio: "pipe" });
       return { method: "screencapture-full", target: null };
     }
   } else {
@@ -6819,7 +8444,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
         return;
       }
     }
-    const outputPath = opts.image ?? opts.output ?? join13(tmpdir2(), `zam-capture-${randomBytes2(4).toString("hex")}.png`);
+    const outputPath = opts.image ?? opts.output ?? join17(tmpdir3(), `zam-capture-${randomBytes2(4).toString("hex")}.png`);
     const captureResult = isProvided ? { method: "provided", target: null } : captureScreenshot(outputPath, opts.hwnd, opts.processName);
     if (!isProvided) {
       const post = decidePostCapture(policy, {
@@ -6847,7 +8472,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
         return;
       }
     }
-    const imageBytes = readFileSync10(outputPath);
+    const imageBytes = readFileSync11(outputPath);
     const base64 = imageBytes.toString("base64");
     jsonOut2({
       sessionId: opts.session ?? null,
@@ -6863,21 +8488,22 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
     });
   });
 });
-bridgeCommand.command("start-recording").description("Start screen recording in the background (macOS only) (JSON)").requiredOption("--session <id>", "ZAM session ID").option("--output <path>", "Video output path").action(async (opts) => {
+bridgeCommand.command("start-recording").description("Start screen recording in the background (JSON)").requiredOption("--session <id>", "ZAM session ID").option("--output <path>", "Video output path").action(async (opts) => {
   const platform = process.platform;
-  if (platform !== "darwin") {
+  if (platform !== "darwin" && platform !== "win32") {
     jsonOut2({
       sessionId: opts.session,
       started: false,
-      error: "Screen recording is only supported on macOS (darwin)"
+      error: "Screen recording is only supported on macOS (darwin) and Windows (win32)"
     });
     return;
   }
   const sessionId = opts.session;
-  const statePath = join13(tmpdir2(), `zam-recording-${sessionId}.json`);
-  const outputPath = opts.output ?? join13(tmpdir2(), `zam-recording-${sessionId}.mov`);
-  const { existsSync: existsSync22, writeFileSync: writeFileSync12, openSync, closeSync } = await import("fs");
-  if (existsSync22(statePath)) {
+  const statePath = join17(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const defaultExt = platform === "win32" ? ".mkv" : ".mov";
+  const outputPath = opts.output ?? join17(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
+  const { existsSync: existsSync25, writeFileSync: writeFileSync12, openSync, closeSync } = await import("fs");
+  if (existsSync25(statePath)) {
     jsonOut2({
       sessionId,
       started: false,
@@ -6885,7 +8511,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     });
     return;
   }
-  const logPath = join13(tmpdir2(), `zam-recording-${sessionId}.log`);
+  const logPath = join17(tmpdir3(), `zam-recording-${sessionId}.log`);
   let logFd;
   try {
     logFd = openSync(logPath, "w");
@@ -6897,26 +8523,34 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     });
     return;
   }
-  const { spawn: spawn3 } = await import("child_process");
-  const child = spawn3(
-    "ffmpeg",
-    [
-      "-y",
-      "-f",
-      "avfoundation",
-      "-r",
-      "5",
-      "-i",
-      "0",
-      "-pix_fmt",
-      "yuv420p",
-      outputPath
-    ],
-    {
-      detached: true,
-      stdio: ["pipe", logFd, logFd]
-    }
-  );
+  const { spawn: spawn4 } = await import("child_process");
+  const ffmpegArgs = platform === "darwin" ? [
+    "-y",
+    "-f",
+    "avfoundation",
+    "-r",
+    "5",
+    "-i",
+    "0",
+    "-pix_fmt",
+    "yuv420p",
+    outputPath
+  ] : [
+    "-y",
+    "-f",
+    "gdigrab",
+    "-framerate",
+    "5",
+    "-i",
+    "desktop",
+    "-pix_fmt",
+    "yuv420p",
+    outputPath
+  ];
+  const child = spawn4("ffmpeg", ffmpegArgs, {
+    detached: true,
+    stdio: ["pipe", logFd, logFd]
+  });
   try {
     closeSync(logFd);
   } catch {
@@ -6947,21 +8581,21 @@ bridgeCommand.command("start-recording").description("Start screen recording in
   }
 });
 bridgeCommand.command("stop-recording").description(
-  "Stop active screen recording and apply idle-frame compression (macOS only) (JSON)"
+  "Stop active screen recording and apply idle-frame compression (JSON)"
 ).requiredOption("--session <id>", "ZAM session ID").action(async (opts) => {
   const platform = process.platform;
-  if (platform !== "darwin") {
+  if (platform !== "darwin" && platform !== "win32") {
     jsonOut2({
       sessionId: opts.session,
       stopped: false,
-      error: "Screen recording is only supported on macOS (darwin)"
+      error: "Screen recording is only supported on macOS (darwin) and Windows (win32)"
     });
     return;
   }
   const sessionId = opts.session;
-  const statePath = join13(tmpdir2(), `zam-recording-${sessionId}.json`);
-  const { existsSync: existsSync22, readFileSync: readFileSync15, rmSync: rmSync3 } = await import("fs");
-  if (!existsSync22(statePath)) {
+  const statePath = join17(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const { existsSync: existsSync25, readFileSync: readFileSync16, rmSync: rmSync3 } = await import("fs");
+  if (!existsSync25(statePath)) {
     jsonOut2({
       sessionId,
       stopped: false,
@@ -6969,7 +8603,7 @@ bridgeCommand.command("stop-recording").description(
     });
     return;
   }
-  const state = JSON.parse(readFileSync15(statePath, "utf8"));
+  const state = JSON.parse(readFileSync16(statePath, "utf8"));
   const { pid, outputPath } = state;
   try {
     process.kill(pid, "SIGINT");
@@ -6985,7 +8619,7 @@ bridgeCommand.command("stop-recording").description(
   };
   let attempts = 0;
   while (isProcessRunning(pid) && attempts < 20) {
-    await new Promise((resolve5) => setTimeout(resolve5, 250));
+    await new Promise((resolve8) => setTimeout(resolve8, 250));
     attempts++;
   }
   if (isProcessRunning(pid)) {
@@ -6998,7 +8632,7 @@ bridgeCommand.command("stop-recording").description(
     rmSync3(statePath, { force: true });
   } catch {
   }
-  if (!existsSync22(outputPath)) {
+  if (!existsSync25(outputPath)) {
     jsonOut2({
       sessionId,
       stopped: false,
@@ -7007,9 +8641,9 @@ bridgeCommand.command("stop-recording").description(
     return;
   }
   const decimatedPath = outputPath.replace(/\.[^.]+$/, "-decimated.mp4");
-  const { execSync: execSync7 } = await import("child_process");
+  const { execSync: execSync6 } = await import("child_process");
   try {
-    execSync7(
+    execSync6(
       `ffmpeg -y -i "${outputPath}" -vf "mpdecimate,setpts=N/FRAME_RATE/TB" -an -pix_fmt yuv420p "${decimatedPath}"`,
       { stdio: "ignore" }
     );
@@ -7062,11 +8696,13 @@ bridgeCommand.command("sync-observer-policy").description(
 });
 bridgeCommand.command("check-llm").description("Check if LLM is enabled and online (JSON)").action(async () => {
   await withDb2(async (db) => {
-    const { enabled, url, model, apiKey } = await getLlmConfig(db);
+    const provider = await getProviderForRole(db, "recall");
+    const { enabled, url, model, apiKey } = provider;
+    const unsupportedProvider = provider.apiFlavor !== "chat-completions";
     let online = false;
     let availableModels = [];
     let modelAvailable = false;
-    if (enabled) {
+    if (enabled && !unsupportedProvider) {
       online = await isLlmOnline(url);
       if (online) {
         availableModels = await getAvailableModels(url, apiKey);
@@ -7081,10 +8717,22 @@ bridgeCommand.command("check-llm").description("Check if LLM is enabled and onli
       url,
       model,
       modelAvailable,
-      availableModels
+      availableModels,
+      apiFlavor: provider.apiFlavor,
+      unsupportedProvider
     });
   });
 });
+bridgeCommand.command("provider-status").description("Show secret-safe provider status for LLM roles (JSON)").action(async () => {
+  await withDb2(async (db) => {
+    const [recall, vision, text] = await Promise.all([
+      getProviderRoleStatus(db, "recall"),
+      getProviderRoleStatus(db, "vision"),
+      getProviderRoleStatus(db, "text")
+    ]);
+    jsonOut2({ roles: { recall, vision, text } });
+  });
+});
 bridgeCommand.command("check-vision").description(
   "Check if UI observer vision analysis is enabled and ready (JSON)"
 ).action(async () => {
@@ -7397,8 +9045,8 @@ bridgeCommand.command("serve").description("Start the persistent JSON-RPC stdin/
 });
 
 // src/cli/commands/card.ts
-import { Command as Command3 } from "commander";
-var cardCommand = new Command3("card").description(
+import { Command as Command5 } from "commander";
+var cardCommand = new Command5("card").description(
   "Manage spaced-repetition cards"
 );
 cardCommand.command("due").description("Show due tokens for a user").option("--user <id>", "User ID (default: whoami)").option("--domain <domain>", "Filter by knowledge domain").option("--json", "Output as JSON").option("--summary", "Show only counts per domain (no slugs or concepts)").action(async (opts) => {
@@ -7596,9 +9244,9 @@ cardCommand.command("delete").description("Delete one user's card for a token").
 });
 
 // src/cli/commands/connector.ts
-import { input, password } from "@inquirer/prompts";
-import { Command as Command4 } from "commander";
-var connectorCommand = new Command4("connector").description(
+import { input as input2, password } from "@inquirer/prompts";
+import { Command as Command6 } from "commander";
+var connectorCommand = new Command6("connector").description(
   "Manage external service connectors"
 );
 connectorCommand.command("setup").description("Configure a connector").argument("<type>", "Connector type (ado, turso)").option("--url <url>", "Turso database URL (non-interactive)").option("--token <token>", "Turso auth token (non-interactive)").option(
@@ -7617,10 +9265,10 @@ connectorCommand.command("setup").description("Configure a connector").argument(
     process.exit(1);
   }
   try {
-    const orgUrl = await input({
+    const orgUrl = await input2({
       message: "Organization URL (e.g. https://dev.azure.com/myorg):"
     });
-    const project = await input({
+    const project = await input2({
       message: "Project name:"
     });
     const pat = await password({
@@ -7711,7 +9359,7 @@ connectorCommand.command("sync").description("Verify the Turso cloud database co
 async function setupTurso(urlArg, tokenArg, mode) {
   let db;
   try {
-    const url = urlArg ?? await input({
+    const url = urlArg ?? await input2({
       message: "Turso database URL (e.g. libsql://my-db-user.turso.io):"
     });
     const token = tokenArg ?? await password({
@@ -7740,27 +9388,27 @@ async function setupTurso(urlArg, tokenArg, mode) {
 }
 
 // src/cli/commands/git-sync.ts
-import { execSync as execSync4 } from "child_process";
-import { chmodSync as chmodSync2, existsSync as existsSync13, writeFileSync as writeFileSync6 } from "fs";
-import { join as join14 } from "path";
-import { Command as Command5 } from "commander";
+import { execSync as execSync5 } from "child_process";
+import { chmodSync as chmodSync2, existsSync as existsSync18, writeFileSync as writeFileSync9 } from "fs";
+import { join as join18 } from "path";
+import { Command as Command7 } from "commander";
 function installHook2() {
-  const gitDir = join14(process.cwd(), ".git");
-  if (!existsSync13(gitDir)) {
+  const gitDir = join18(process.cwd(), ".git");
+  if (!existsSync18(gitDir)) {
     console.error(
       "Error: Current directory is not the root of a Git repository."
     );
     process.exit(1);
   }
-  const hooksDir = join14(gitDir, "hooks");
-  const hookPath = join14(hooksDir, "post-commit");
+  const hooksDir = join18(gitDir, "hooks");
+  const hookPath = join18(hooksDir, "post-commit");
   const hookContent = `#!/bin/sh
 # ZAM Spaced Repetition Auto-Stale Hook
 # Triggered automatically on git commits to decay modified concept cards.
 zam git-sync --commit HEAD --quiet
 `;
   try {
-    writeFileSync6(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
+    writeFileSync9(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
     try {
       chmodSync2(hookPath, "755");
     } catch (_e) {
@@ -7773,7 +9421,7 @@ zam git-sync --commit HEAD --quiet
     process.exit(1);
   }
 }
-var gitSyncCommand = new Command5("git-sync").description("Sync learning cards with recent Git file modifications").option("--commit <hash>", "Git commit hash to check", "HEAD").option("--user <id>", "User ID (default: whoami)").option("--install", "Install git post-commit hook in current repo").option("--quiet", "Suppress verbose output").action(async (opts) => {
+var gitSyncCommand = new Command7("git-sync").description("Sync learning cards with recent Git file modifications").option("--commit <hash>", "Git commit hash to check", "HEAD").option("--user <id>", "User ID (default: whoami)").option("--install", "Install git post-commit hook in current repo").option("--quiet", "Suppress verbose output").action(async (opts) => {
   if (opts.install) {
     installHook2();
     return;
@@ -7782,7 +9430,7 @@ var gitSyncCommand = new Command5("git-sync").description("Sync learning cards w
     const userId = await resolveUser(opts, db);
     let changedFiles = [];
     try {
-      const output = execSync4(
+      const output = execSync5(
         `git diff-tree --no-commit-id --name-only -r ${opts.commit}`,
         {
           encoding: "utf-8",
@@ -7862,10 +9510,10 @@ ZAM Auto-Stale Complete: Scanned ${changedFiles.length} file(s).`
 });
 
 // src/cli/commands/goal.ts
-import { existsSync as existsSync14, mkdirSync as mkdirSync8 } from "fs";
-import { resolve as resolve3 } from "path";
-import { input as input2 } from "@inquirer/prompts";
-import { Command as Command6 } from "commander";
+import { existsSync as existsSync19, mkdirSync as mkdirSync10 } from "fs";
+import { resolve as resolve6 } from "path";
+import { input as input3 } from "@inquirer/prompts";
+import { Command as Command8 } from "commander";
 async function resolveGoalsDir() {
   let goalsDir;
   let db;
@@ -7876,9 +9524,9 @@ async function resolveGoalsDir() {
   } finally {
     await db?.close();
   }
-  return goalsDir ? resolve3(goalsDir) : resolve3("goals");
+  return goalsDir ? resolve6(goalsDir) : resolve6("goals");
 }
-var goalCommand = new Command6("goal").description(
+var goalCommand = new Command8("goal").description(
   "Manage learning goals (markdown files)"
 );
 goalCommand.command("list").description("List all goals").option(
@@ -7886,7 +9534,7 @@ goalCommand.command("list").description("List all goals").option(
   "Filter by status (active, completed, paused, abandoned)"
 ).option("--tree", "Show goals as a tree with parent/child relationships").option("--json", "Output as JSON").action(async (opts) => {
   const goalsDir = await resolveGoalsDir();
-  if (!existsSync14(goalsDir)) {
+  if (!existsSync19(goalsDir)) {
     console.error(`Goals directory not found: ${goalsDir}`);
     console.error(
       "Set it with: zam settings set personal.goals_dir /path/to/goals"
@@ -7987,8 +9635,8 @@ ${"\u2500".repeat(50)}`);
 });
 goalCommand.command("create").description("Create a new goal").option("--slug <slug>", "Goal slug (used as filename)").option("--title <title>", "Goal title").option("--parent <slug>", "Parent goal slug").option("--description <text>", "Goal description").option("--json", "Output as JSON").action(async (opts) => {
   const goalsDir = await resolveGoalsDir();
-  if (!existsSync14(goalsDir)) {
-    mkdirSync8(goalsDir, { recursive: true });
+  if (!existsSync19(goalsDir)) {
+    mkdirSync10(goalsDir, { recursive: true });
   }
   let slug = opts.slug;
   let title = opts.title;
@@ -7997,11 +9645,11 @@ goalCommand.command("create").description("Create a new goal").option("--slug <s
   if (!slug || !title) {
     try {
       if (!title) {
-        title = await input2({ message: "Goal title:" });
+        title = await input3({ message: "Goal title:" });
       }
       if (!slug) {
         const suggested = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-        slug = await input2({
+        slug = await input3({
           message: "Goal slug (filename):",
           default: suggested
         });
@@ -8047,22 +9695,22 @@ goalCommand.command("status <slug> <status>").description("Update a goal's statu
 });
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync15, mkdirSync as mkdirSync9, writeFileSync as writeFileSync7 } from "fs";
-import { homedir as homedir9 } from "os";
-import { join as join15 } from "path";
-import { confirm, input as input3 } from "@inquirer/prompts";
-import { Command as Command7 } from "commander";
-var HOME2 = homedir9();
+import { existsSync as existsSync20, mkdirSync as mkdirSync11, writeFileSync as writeFileSync10 } from "fs";
+import { homedir as homedir11 } from "os";
+import { join as join19 } from "path";
+import { confirm as confirm2, input as input4 } from "@inquirer/prompts";
+import { Command as Command9 } from "commander";
+var HOME2 = homedir11();
 function printLine(char = "\u2550", len = 60, color = "\x1B[36m") {
   console.log(`${color}${char.repeat(len)}\x1B[0m`);
 }
 function bootstrapSandboxWorkspace(workspaceDir) {
-  mkdirSync9(join15(workspaceDir, "beliefs"), { recursive: true });
-  mkdirSync9(join15(workspaceDir, "goals"), { recursive: true });
-  mkdirSync9(join15(workspaceDir, "skills"), { recursive: true });
-  const worldviewFile = join15(workspaceDir, "beliefs", "worldview.md");
-  if (!existsSync15(worldviewFile)) {
-    writeFileSync7(
+  mkdirSync11(join19(workspaceDir, "beliefs"), { recursive: true });
+  mkdirSync11(join19(workspaceDir, "goals"), { recursive: true });
+  mkdirSync11(join19(workspaceDir, "skills"), { recursive: true });
+  const worldviewFile = join19(workspaceDir, "beliefs", "worldview.md");
+  if (!existsSync20(worldviewFile)) {
+    writeFileSync10(
       worldviewFile,
       `# Personal Worldview
 
@@ -8074,9 +9722,9 @@ Here, I declare the core concepts and principles I want to master.
       "utf8"
     );
   }
-  const goalsFile = join15(workspaceDir, "goals", "goals.md");
-  if (!existsSync15(goalsFile)) {
-    writeFileSync7(
+  const goalsFile = join19(workspaceDir, "goals", "goals.md");
+  if (!existsSync20(goalsFile)) {
+    writeFileSync10(
       goalsFile,
       `# Personal Goals
 
@@ -8088,7 +9736,7 @@ Here, I declare the core concepts and principles I want to master.
     );
   }
 }
-var initCommand = new Command7("init").description("Launch the guided interactive onboarding wizard").action(async () => {
+var initCommand = new Command9("init").description("Launch the guided interactive onboarding wizard").action(async () => {
   printLine();
   console.log(
     "\x1B[1m\x1B[32m          ZAM \u2014 The Symbiotic Learning Agent Onboarding\x1B[0m"
@@ -8098,8 +9746,8 @@ var initCommand = new Command7("init").description("Launch the guided interactiv
   );
   printLine();
   console.log("\n\x1B[1m[1/5] Setting up Local Workspace Sandbox\x1B[0m");
-  const defaultWorkspace = join15(HOME2, "Documents", "zam");
-  const workspacePath = await input3({
+  const defaultWorkspace = join19(HOME2, "Documents", "zam");
+  const workspacePath = await input4({
     message: "Choose your ZAM workspace directory:",
     default: defaultWorkspace
   });
@@ -8135,7 +9783,7 @@ var initCommand = new Command7("init").description("Launch the guided interactiv
   \x1B[1mRecommendation:\x1B[0m ZAM suggests installing \x1B[32m${runnerLabel}\x1B[0m with \x1B[36m${profile.recommendedModel}\x1B[0m.`
   );
   console.log("\n\x1B[1m[3/5] Setting up Local LLM Runner\x1B[0m");
-  const proceedInstall = await confirm({
+  const proceedInstall = await confirm2({
     message: `Would you like ZAM to install and configure ${runnerLabel} automatically?`,
     default: true
   });
@@ -8203,7 +9851,7 @@ var initCommand = new Command7("init").description("Launch the guided interactiv
   console.log(
     "\n\x1B[1m[5/5] Wiring Developer Agents & Terminal Helpers\x1B[0m"
   );
-  const proceedHooks = await confirm({
+  const proceedHooks = await confirm2({
     message: "Distribute ZAM skills and install optional monitored-session shell helpers?",
     default: true
   });
@@ -8254,8 +9902,8 @@ var initCommand = new Command7("init").description("Launch the guided interactiv
 });
 
 // src/cli/commands/learn.ts
-import { input as input5 } from "@inquirer/prompts";
-import { Command as Command8 } from "commander";
+import { input as input6 } from "@inquirer/prompts";
+import { Command as Command10 } from "commander";
 
 // src/cli/learn-format.ts
 var BLOOM_VERBS3 = {
@@ -8304,7 +9952,7 @@ function formatReveal(input8) {
 }
 
 // src/cli/review-actions.ts
-import { confirm as confirm2, input as input4, select } from "@inquirer/prompts";
+import { confirm as confirm3, input as input5, select } from "@inquirer/prompts";
 async function runInteractiveReviewAction(inputData) {
   let currentItem = { ...inputData.item };
   while (true) {
@@ -8419,7 +10067,7 @@ async function runInteractiveReviewAction(inputData) {
       continue;
     }
     if (choice === "deprecate-token") {
-      const approved = await confirm2({
+      const approved = await confirm3({
         message: `Deprecate ${currentItem.slug} so it stops appearing in review queues?`,
         default: false
       });
@@ -8450,7 +10098,7 @@ async function runInteractiveReviewAction(inputData) {
       console.log(`  Session steps:         ${impact.session_steps}`);
       console.log(`  Sessions touched:      ${impact.sessions_touched}`);
       console.log(`  Agent skills updated:  ${impact.agent_skills}`);
-      const approved = await confirm2({
+      const approved = await confirm3({
         message: "Permanently delete this token and its dependent learning data?",
         default: false
       });
@@ -8475,7 +10123,7 @@ async function runInteractiveReviewAction(inputData) {
       );
       console.log(`Delete your card for ${currentItem.slug}?`);
       console.log(`  Review logs removed: ${impact.review_logs}`);
-      const approved = await confirm2({
+      const approved = await confirm3({
         message: "Delete only your card for this token?",
         default: false
       });
@@ -8513,21 +10161,21 @@ async function promptTokenEdit(token) {
   }
   switch (field) {
     case "concept": {
-      const concept = await input4({
+      const concept = await input5({
         message: "Concept:",
         default: token.concept
       });
       return concept === token.concept ? null : { concept };
     }
     case "domain": {
-      const domain = await input4({
+      const domain = await input5({
         message: "Domain (blank allowed):",
         default: token.domain
       });
       return domain === token.domain ? null : { domain };
     }
     case "context": {
-      const context = await input4({
+      const context = await input5({
         message: "Context (blank allowed):",
         default: token.context
       });
@@ -8568,14 +10216,14 @@ async function promptTokenEdit(token) {
       return mode === token.symbiosis_mode ? null : { symbiosis_mode: mode };
     }
     case "source_link": {
-      const link = await input4({
+      const link = await input5({
         message: "Source link (blank allowed):",
         default: token.source_link ?? ""
       });
       return link === token.source_link ? null : { source_link: link || null };
     }
     case "question": {
-      const question = await input4({
+      const question = await input5({
         message: "Recall question (blank allowed):",
         default: token.question ?? ""
       });
@@ -8593,7 +10241,7 @@ var STOP_WORDS = /* @__PURE__ */ new Set(["q", ":q", "quit", "stop"]);
 function isExitPrompt(err) {
   return err instanceof Error && err.name === "ExitPromptError";
 }
-var learnCommand = new Command8("learn").description(
+var learnCommand = new Command10("learn").description(
   "Run a spoiler-free, in-process learning session (recall \u2192 reveal \u2192 self-rate)"
 ).option("--user <id>", "User ID (default: whoami)").option("--max-new <n>", "Maximum new cards", "10").option("--max-reviews <n>", "Maximum review cards", "50").option("--no-resolve", "Skip resolving source_link into the revealed answer").action(async (opts) => {
   let db;
@@ -8673,7 +10321,7 @@ ${"\u2500".repeat(50)}`);
   ${prompt.question}`);
       let answer;
       try {
-        answer = await input5({
+        answer = await input6({
           message: t(locale, "prompt_answer")
         });
       } catch (err) {
@@ -8793,36 +10441,52 @@ ${"\u2550".repeat(50)}`);
     process.exit(1);
   }
 });
-
-// src/cli/commands/monitor.ts
-import { execFileSync as execFileSync3, execSync as execSync5 } from "child_process";
-import { unlinkSync, writeFileSync as writeFileSync8 } from "fs";
-import { tmpdir as tmpdir3 } from "os";
-import { basename as basename3, join as join16 } from "path";
-import { Command as Command9 } from "commander";
-function isPowerShellShell(shell) {
-  return shell === "pwsh" || shell === "powershell";
+function buildLearnCommand(shell, userId) {
+  const zamInvocation = resolveZamInvocation(shell);
+  const learnArgs = userId ? ` learn --user ${userId}` : " learn";
+  return `${zamInvocation}${learnArgs}`;
 }
-function normalizeShell(shell) {
-  if (!shell) return detectShell();
-  const normalized = shell.toLowerCase();
-  if (normalized === "zsh" || normalized === "bash" || normalized === "pwsh" || normalized === "powershell") {
-    return normalized;
+learnCommand.command("open").description("Open a new terminal window running zam learn (Active Recall)").option("--user <id>", "User ID (default: whoami)").option("--dir <path>", "Working directory (defaults to cwd)").option(
+  "--shell <type>",
+  "Shell type: zsh | bash | pwsh | powershell (auto-detected)"
+).action(async (opts) => {
+  let shell;
+  try {
+    shell = normalizeShell(opts.shell);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
   }
-  throw new Error(
-    `Unsupported shell: ${shell}. Expected zsh, bash, pwsh, or powershell.`
-  );
-}
-function psSingleQuoted2(value) {
-  return `'${value.replace(/'/g, "''")}'`;
-}
-function detectShell() {
-  if (process.platform === "win32")
-    return findExecutable("pwsh.exe") ? "pwsh" : "powershell";
-  const shell = process.env.SHELL ?? "";
-  return basename3(shell) === "bash" ? "bash" : "zsh";
-}
-var monitorCommand = new Command9("monitor").description(
+  let db;
+  let userId = opts.user;
+  try {
+    db = await openDatabase();
+    if (!userId) {
+      userId = await resolveUser(opts, db);
+    }
+    if (!await getSetting(db, "review_method")) {
+      await setSetting(db, "review_method", "console");
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  } finally {
+    await db?.close();
+  }
+  const dir = opts.dir ?? process.cwd();
+  const learnCommandLine = buildLearnCommand(shell, userId);
+  const shellSetup = buildShellSetupCommand(dir, shell, learnCommandLine);
+  openTerminalWindow({
+    shellSetup,
+    label: "learn",
+    dir,
+    shell
+  });
+});
+
+// src/cli/commands/monitor.ts
+import { Command as Command11 } from "commander";
+var monitorCommand = new Command11("monitor").description(
   "Shell observation for real-time task monitoring"
 );
 monitorCommand.command("start").description("Output shell hook code to install monitoring").requiredOption("--session <id>", "Session ID to monitor").option(
@@ -8949,39 +10613,6 @@ monitorCommand.command("status").description("Show monitoring status for a sessi
     console.log(`  To:       ${result.timeSpan.end}`);
   }
 });
-function selectWindowsExecutable(results, pathext = process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD") {
-  if (results.length === 0) return null;
-  const extensions = pathext.split(";").map((ext) => ext.trim().toLowerCase()).filter(Boolean);
-  const runnable = results.find(
-    (result) => extensions.some((ext) => result.toLowerCase().endsWith(ext))
-  );
-  return runnable ?? results[0];
-}
-function findExecutable(command) {
-  try {
-    const lookup = process.platform === "win32" ? `where.exe ${command}` : `command -v ${command}`;
-    const results = execSync5(lookup, { encoding: "utf-8" }).split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
-    if (results.length === 0) return null;
-    if (process.platform === "win32") {
-      return selectWindowsExecutable(results);
-    }
-    return results[0];
-  } catch {
-    return null;
-  }
-}
-function resolveZamInvocation(shell) {
-  const installed = findExecutable("zam");
-  if (installed) {
-    return isPowerShellShell(shell) ? `& ${psSingleQuoted2(installed)}` : installed;
-  }
-  const projectRoot = join16(import.meta.dirname, "..", "..", "..");
-  const cliSource = join16(projectRoot, "src/cli/index.ts");
-  if (isPowerShellShell(shell)) {
-    return `& npx --prefix ${psSingleQuoted2(projectRoot)} tsx ${psSingleQuoted2(cliSource)}`;
-  }
-  return `npx --prefix ${JSON.stringify(projectRoot)} tsx ${JSON.stringify(cliSource)}`;
-}
 function buildMonitorSetupCommand(dir, sessionId, shell) {
   const zamInvocation = resolveZamInvocation(shell);
   if (isPowerShellShell(shell)) {
@@ -8994,17 +10625,6 @@ function buildMonitorSetupCommand(dir, sessionId, shell) {
   }
   return `cd ${JSON.stringify(dir)} && eval "$(${zamInvocation} monitor start --session ${sessionId} --shell ${shell})"`;
 }
-function isItermRunning() {
-  try {
-    const result = execSync5(
-      `osascript -e 'tell application "System Events" to (name of processes) contains "iTerm2"' 2>/dev/null`,
-      { encoding: "utf-8" }
-    ).trim();
-    return result === "true";
-  } catch {
-    return false;
-  }
-}
 monitorCommand.command("open").description("Open a new monitored terminal window for a session").requiredOption("--session <id>", "Session ID to monitor").option("--dir <path>", "Working directory (defaults to cwd)").option(
   "--shell <type>",
   "Shell type: zsh | bash | pwsh | powershell (auto-detected)"
@@ -9019,107 +10639,37 @@ monitorCommand.command("open").description("Open a new monitored terminal window
   let db;
   try {
     db = await openDatabase();
-    const session = await db.prepare("SELECT id, completed_at FROM sessions WHERE id = ?").get(opts.session);
-    if (!session) {
-      console.error(`Error: Session not found: ${opts.session}`);
-      process.exit(1);
-    }
-    if (session.completed_at) {
-      console.error(`Error: Session already completed: ${opts.session}`);
-      process.exit(1);
-    }
-    if (!await getSetting(db, "monitor_method")) {
-      await setSetting(db, "monitor_method", "terminal");
-    }
-  } catch (err) {
-    console.error(`Error: ${err.message}`);
-    process.exit(1);
-  } finally {
-    await db?.close();
-  }
-  const dir = opts.dir ?? process.cwd();
-  const shellSetup = buildMonitorSetupCommand(dir, opts.session, shell);
-  if (process.platform === "darwin" && !isPowerShellShell(shell)) {
-    openMacTerminal(shellSetup, opts.session, dir);
-  } else if (process.platform === "win32" && isPowerShellShell(shell)) {
-    openWindowsPowerShell(shellSetup, opts.session, dir, shell);
-  } else {
-    console.log(`Run this in a new terminal:
-`);
-    console.log(`  ${shellSetup}
-`);
-    console.log(
-      `(Automatic terminal opening is only supported on macOS Terminal/iTerm2 and Windows PowerShell for now.)`
-    );
-  }
-});
-function openMacTerminal(shellSetup, sessionId, dir) {
-  const useIterm = isItermRunning();
-  const escaped = shellSetup.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-  const appleScript = useIterm ? `tell application "iTerm2"
-  activate
-  set newWindow to (create window with default profile)
-  tell current session of newWindow
-    write text "${escaped}"
-  end tell
-end tell` : `tell application "Terminal"
-  activate
-  do script "${escaped}"
-end tell`;
-  const tmpFile = join16(tmpdir3(), `zam-monitor-${sessionId}.scpt`);
-  try {
-    writeFileSync8(tmpFile, appleScript);
-    execSync5(`osascript ${JSON.stringify(tmpFile)}`, { stdio: "ignore" });
-    console.log(
-      `Opened ${useIterm ? "iTerm2" : "Terminal.app"} window with monitoring for session ${sessionId}`
-    );
-    console.log(`  Directory: ${dir}`);
-  } catch (err) {
-    console.error(`Failed to open terminal: ${err.message}`);
-    console.log(`
-Run this manually in a new terminal:
-`);
-    console.log(`  ${shellSetup}`);
-  } finally {
-    try {
-      unlinkSync(tmpFile);
-    } catch {
-    }
-  }
-}
-function openWindowsPowerShell(shellSetup, sessionId, dir, requestedShell) {
-  const requestedExecutable = requestedShell === "powershell" ? "powershell.exe" : "pwsh.exe";
-  const executable = findExecutable(requestedExecutable) ? requestedExecutable : "powershell.exe";
-  const startCommand = [
-    "Start-Process",
-    `-FilePath ${psSingleQuoted2(executable)}`,
-    `-ArgumentList @('-NoExit','-NoProfile','-Command',${psSingleQuoted2(shellSetup)})`
-  ].join(" ");
-  const launcher = findExecutable("pwsh.exe") ? "pwsh.exe" : "powershell.exe";
-  try {
-    execFileSync3(
-      launcher,
-      ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", startCommand],
-      {
-        stdio: "ignore"
-      }
-    );
-    console.log(
-      `Opened ${executable === "pwsh.exe" ? "PowerShell" : "Windows PowerShell"} window with monitoring for session ${sessionId}`
-    );
-    console.log(`  Directory: ${dir}`);
+    const session = await db.prepare("SELECT id, completed_at FROM sessions WHERE id = ?").get(opts.session);
+    if (!session) {
+      console.error(`Error: Session not found: ${opts.session}`);
+      process.exit(1);
+    }
+    if (session.completed_at) {
+      console.error(`Error: Session already completed: ${opts.session}`);
+      process.exit(1);
+    }
+    if (!await getSetting(db, "monitor_method")) {
+      await setSetting(db, "monitor_method", "terminal");
+    }
   } catch (err) {
-    console.error(`Failed to open PowerShell: ${err.message}`);
-    console.log(`
-Run this manually in a new PowerShell terminal:
-`);
-    console.log(`  ${shellSetup}`);
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  } finally {
+    await db?.close();
   }
-}
+  const dir = opts.dir ?? process.cwd();
+  const shellSetup = buildMonitorSetupCommand(dir, opts.session, shell);
+  openTerminalWindow({
+    shellSetup,
+    label: `monitor-${opts.session}`,
+    dir,
+    shell
+  });
+});
 
 // src/cli/commands/observer.ts
-import { Command as Command10 } from "commander";
-var observerCommand = new Command10("observer").description(
+import { Command as Command12 } from "commander";
+var observerCommand = new Command12("observer").description(
   "Configure what the UI observer may capture (Layer 2 policy)"
 );
 function applyObserverListChange(current, entry, op) {
@@ -9181,9 +10731,9 @@ observerCommand.command("revoke <process>").description("Remove a process from o
 });
 
 // src/cli/commands/profile.ts
-import { homedir as homedir10 } from "os";
-import { dirname as dirname5, join as join17, resolve as resolve4 } from "path";
-import { Command as Command11 } from "commander";
+import { homedir as homedir12 } from "os";
+import { dirname as dirname6, join as join20, resolve as resolve7 } from "path";
+import { Command as Command13 } from "commander";
 var C2 = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -9192,7 +10742,7 @@ var C2 = {
   green: "\x1B[32m"
 };
 function defaultPersonalDir() {
-  return join17(homedir10(), "Documents", "zam");
+  return join20(homedir12(), "Documents", "zam");
 }
 function render(profile) {
   const sync = profile.syncProvider ? `${C2.green}${profile.syncProvider}${C2.reset} ${C2.dim}(good for cross-device snapshots)${C2.reset}` : `${C2.dim}local folder (use a synced folder or snapshots to move between machines)${C2.reset}`;
@@ -9203,7 +10753,7 @@ function render(profile) {
   console.log(`  data dir:      ${C2.cyan}${profile.dataDir}${C2.reset}`);
   console.log(`  database:      ${C2.cyan}${profile.dbPath}${C2.reset}`);
 }
-var profileCommand = new Command11("profile").description("Show or change this machine's ZAM install profile").option("--mode <mode>", "Set install mode: developer | default").option("--dir <path>", "Set the personal-content folder").option("--json", "Output as JSON").action(async (opts) => {
+var profileCommand = new Command13("profile").description("Show or change this machine's ZAM install profile").option("--mode <mode>", "Set install mode: developer | default").option("--dir <path>", "Set the personal-content folder").option("--json", "Output as JSON").action(async (opts) => {
   if (opts.mode && opts.mode !== "developer" && opts.mode !== "default") {
     console.error(`Invalid --mode: ${opts.mode}. Use developer or default.`);
     process.exit(1);
@@ -9213,7 +10763,7 @@ var profileCommand = new Command11("profile").description("Show or change this m
     if (opts.mode) setInstallMode(opts.mode);
     db = await openDatabaseWithSync({ initialize: true });
     if (opts.dir) {
-      await setSetting(db, "personal.workspace_dir", resolve4(opts.dir));
+      await setSetting(db, "personal.workspace_dir", resolve7(opts.dir));
     }
     const personalDir = await getSetting(db, "personal.workspace_dir") || defaultPersonalDir();
     await db.close();
@@ -9223,7 +10773,7 @@ var profileCommand = new Command11("profile").description("Show or change this m
       mode: getInstallMode(),
       personalDir,
       syncProvider: detectSyncProvider(personalDir),
-      dataDir: dirname5(dbPath),
+      dataDir: dirname6(dbPath),
       dbPath
     };
     if (opts.json) {
@@ -9238,9 +10788,358 @@ var profileCommand = new Command11("profile").description("Show or change this m
   }
 });
 
+// src/cli/commands/provider.ts
+import { password as password2 } from "@inquirer/prompts";
+import { Command as Command14 } from "commander";
+var VALID_API_FLAVORS = [
+  "chat-completions",
+  "anthropic-messages"
+];
+var VALID_ROLES = ["vision", "recall", "text"];
+function upsertProviderRecord(providers, name, patch) {
+  const merged = { ...providers[name] ?? {} };
+  if (patch.url !== void 0) merged.url = patch.url;
+  if (patch.model !== void 0) merged.model = patch.model;
+  if (patch.apiFlavor !== void 0) merged.apiFlavor = patch.apiFlavor;
+  if (patch.apiKeyRef !== void 0) merged.apiKeyRef = patch.apiKeyRef;
+  if (patch.label !== void 0) merged.label = patch.label;
+  if (patch.local !== void 0) merged.local = patch.local;
+  if (patch.runner !== void 0) merged.runner = patch.runner;
+  return { ...providers, [name]: merged };
+}
+function removeProviderRecord(providers, name) {
+  if (!(name in providers)) return { providers, removed: false };
+  const next = { ...providers };
+  delete next[name];
+  return { providers: next, removed: true };
+}
+function rolesReferencing(roles, name) {
+  return VALID_ROLES.filter((role) => {
+    const binding = roles[role];
+    return binding?.primary === name || binding?.fallback === name;
+  });
+}
+function bindRoleProviders(roles, role, primary, fallback) {
+  const binding = { primary };
+  if (fallback) binding.fallback = fallback;
+  return { ...roles, [role]: binding };
+}
+function maskSecret(key) {
+  return key.length <= 4 ? "\u2022\u2022\u2022\u2022" : `\u2026${key.slice(-4)}`;
+}
+function buildProviderListing(providers, hasKey) {
+  return Object.entries(providers).map(([name, rec]) => {
+    const apiFlavor = rec.apiFlavor ?? (rec.url ? inferApiFlavor(rec.url) : "chat-completions");
+    let keyState;
+    if (!rec.apiKeyRef) keyState = "none";
+    else keyState = hasKey(rec.apiKeyRef) ? "set" : "missing";
+    const row = {
+      name,
+      url: rec.url,
+      model: rec.model,
+      apiFlavor,
+      apiKeyRef: rec.apiKeyRef,
+      keyState
+    };
+    if (rec.label !== void 0) row.label = rec.label;
+    if (rec.local !== void 0) row.local = rec.local;
+    if (rec.runner !== void 0) row.runner = rec.runner;
+    return row;
+  });
+}
+function findOrphanKeyRefs(storedRefs, providers) {
+  const used = new Set(
+    Object.values(providers).map((rec) => rec.apiKeyRef).filter((ref) => !!ref)
+  );
+  return storedRefs.filter((ref) => !used.has(ref));
+}
+async function readJson(db, key, fallback) {
+  const raw = await getSetting(db, key);
+  if (!raw) return fallback;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+var readProviders = (db) => readJson(db, "llm.providers", {});
+var readRoles = (db) => readJson(db, "llm.roles", {});
+async function readScopedProviders(db, machine) {
+  if (machine) return getMachineAiConfig().providers ?? {};
+  if (!db)
+    throw new Error("Database is required for shared provider settings.");
+  return readProviders(db);
+}
+async function readScopedRoles(db, machine) {
+  if (machine) return getMachineAiConfig().roles ?? {};
+  if (!db)
+    throw new Error("Database is required for shared provider settings.");
+  return readRoles(db);
+}
+async function writeScopedProviders(db, machine, p) {
+  if (machine) {
+    const config = getMachineAiConfig();
+    saveMachineAiConfig({ ...config, providers: p });
+    return;
+  }
+  if (!db)
+    throw new Error("Database is required for shared provider settings.");
+  await setSetting(db, "llm.providers", JSON.stringify(p));
+}
+async function writeScopedRoles(db, machine, r) {
+  if (machine) {
+    const config = getMachineAiConfig();
+    saveMachineAiConfig({ ...config, roles: r });
+    return;
+  }
+  if (!db)
+    throw new Error("Database is required for shared provider settings.");
+  await setSetting(db, "llm.roles", JSON.stringify(r));
+}
+async function withProviderScope(machine, action) {
+  if (machine) {
+    await action(void 0);
+    return;
+  }
+  await withDb(action);
+}
+var providerCommand = new Command14("provider").description(
+  "Configure role-based AI providers (url/model/flavor/key, per role)"
+);
+providerCommand.command("list").description("Show configured providers, role bindings, and key status").option("--json", "Output as JSON").option("--machine", "Read machine-local providers from ~/.zam/config.json").action(async (opts) => {
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const roles = await readScopedRoles(db, machine);
+    const rows = buildProviderListing(
+      providers,
+      (ref) => getProviderApiKey(ref) !== null
+    );
+    const orphans = findOrphanKeyRefs(listProviderApiKeyRefs(), providers);
+    if (opts.json) {
+      console.log(
+        JSON.stringify(
+          {
+            scope: machine ? "machine" : "shared",
+            providers: rows,
+            roles,
+            orphans
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    console.log(
+      `Providers (${opts.machine ? "~/.zam/config.json ai.providers" : "llm.providers"}):
+`
+    );
+    if (rows.length === 0) {
+      console.log(
+        "  (none) \u2014 add one: zam provider add <name> --url <url> --model <model>"
+      );
+    } else {
+      for (const row of rows) {
+        const key = row.keyState === "set" ? "\x1B[32mkey \u2713\x1B[0m" : row.keyState === "missing" ? `\x1B[31mkey \u2717 (set: zam provider set-key ${row.apiKeyRef})\x1B[0m` : "\x1B[90mno key\x1B[0m";
+        console.log(`  \x1B[36m${row.name.padEnd(12)}\x1B[0m ${key}`);
+        console.log(`      url:    ${row.url ?? "(inherits llm.url)"}`);
+        console.log(`      model:  ${row.model ?? "(inherits llm.model)"}`);
+        console.log(`      flavor: ${row.apiFlavor}`);
+        if (row.label) console.log(`      label:  ${row.label}`);
+        if (row.local !== void 0) {
+          console.log(`      local:  ${row.local ? "yes" : "no"}`);
+        }
+        if (row.runner) console.log(`      runner: ${row.runner}`);
+        if (row.apiKeyRef) console.log(`      key-ref: ${row.apiKeyRef}`);
+      }
+    }
+    console.log("\nRoles (llm.roles):\n");
+    for (const role of VALID_ROLES) {
+      const binding = roles[role];
+      if (!binding?.primary) {
+        console.log(`  ${role.padEnd(7)} \x1B[90m(unset)\x1B[0m`);
+      } else {
+        const fb = binding.fallback ? ` \u2192 fallback: ${binding.fallback}` : "";
+        console.log(`  ${role.padEnd(7)} primary: ${binding.primary}${fb}`);
+      }
+    }
+    if (orphans.length > 0) {
+      console.log(
+        `
+\x1B[33mOrphan keys (stored but unreferenced):\x1B[0m ${orphans.join(", ")}`
+      );
+    }
+  });
+});
+providerCommand.command("add <name>").description("Add or update a provider record in llm.providers").option("--label <label>", "Human-readable provider label").option("--url <url>", "Endpoint base URL (e.g. https://api.deepseek.com/v1)").option("--model <model>", "Model id (e.g. deepseek-v4-flash)").option("--local", "Mark this provider as a local/on-device endpoint").option(
+  "--runner <runner>",
+  "Local runner hint (flm, foundry-local, ollama, ...)"
+).option(
+  "--flavor <flavor>",
+  `Wire protocol: ${VALID_API_FLAVORS.join(" | ")} (default: inferred from URL)`
+).option(
+  "--key-ref <ref>",
+  "Credential reference for the API key (default: <name> when --key is given)"
+).option(
+  "--key <value>",
+  "Store this API key now (prefer `set-key` to keep it out of shell history)"
+).option("--machine", "Store this provider in ~/.zam/config.json").action(async (name, opts) => {
+  let apiFlavor;
+  if (opts.flavor) {
+    if (!VALID_API_FLAVORS.includes(opts.flavor)) {
+      console.error(
+        `Invalid --flavor: ${opts.flavor}. Use ${VALID_API_FLAVORS.join(" or ")}.`
+      );
+      process.exit(1);
+    }
+    apiFlavor = opts.flavor;
+  }
+  const apiKeyRef = opts.keyRef ?? (opts.key ? name : void 0);
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const next = upsertProviderRecord(providers, name, {
+      label: opts.label,
+      url: opts.url,
+      model: opts.model,
+      apiFlavor,
+      apiKeyRef,
+      local: opts.local ? true : void 0,
+      runner: opts.runner
+    });
+    await writeScopedProviders(db, machine, next);
+    if (opts.key && apiKeyRef) setProviderApiKey(apiKeyRef, opts.key);
+    const rec = next[name];
+    console.log(
+      `Provider "${name}" saved (${machine ? "machine-local" : "shared"}):`
+    );
+    console.log(`  url:     ${rec.url ?? "(inherits llm.url)"}`);
+    console.log(`  model:   ${rec.model ?? "(inherits llm.model)"}`);
+    if (rec.label) console.log(`  label:   ${rec.label}`);
+    if (rec.local !== void 0) {
+      console.log(`  local:   ${rec.local ? "yes" : "no"}`);
+    }
+    if (rec.runner) console.log(`  runner:  ${rec.runner}`);
+    console.log(
+      `  flavor:  ${rec.apiFlavor ?? `${rec.url ? inferApiFlavor(rec.url) : "chat-completions"} (inferred)`}`
+    );
+    console.log(`  key-ref: ${rec.apiKeyRef ?? "(none \u2014 uses default key)"}`);
+    if (opts.key) {
+      console.log(`  key:     stored (${maskSecret(opts.key)})`);
+    } else if (rec.apiKeyRef && getProviderApiKey(rec.apiKeyRef) === null) {
+      console.log(
+        `
+  \u26A0 No key stored for "${rec.apiKeyRef}". Run: zam provider set-key ${rec.apiKeyRef}`
+      );
+    }
+    if (!rec.url) {
+      console.log(
+        "\n  \u26A0 No --url set; this provider inherits the base llm.url."
+      );
+    }
+    console.log(
+      `
+Bind it to a role: zam provider use recall --primary ${name}`
+    );
+  });
+});
+providerCommand.command("remove <name>").description("Remove a provider record from llm.providers").option("--machine", "Remove from ~/.zam/config.json instead of the DB").action(async (name, opts) => {
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const { providers: next, removed } = removeProviderRecord(
+      providers,
+      name
+    );
+    if (!removed) {
+      console.log(`No such provider: ${name}`);
+      return;
+    }
+    await writeScopedProviders(db, machine, next);
+    console.log(
+      `Removed provider "${name}" (${machine ? "machine-local" : "shared"}).`
+    );
+    const referencing = rolesReferencing(
+      await readScopedRoles(db, machine),
+      name
+    );
+    if (referencing.length > 0) {
+      console.log(
+        `  \u26A0 Still referenced by role(s): ${referencing.join(", ")} \u2014 rebind with: zam provider use <role> --primary <name>`
+      );
+    }
+  });
+});
+providerCommand.command("use <role>").description(`Bind providers to a role (${VALID_ROLES.join(" | ")})`).option("--primary <name>", "Primary provider").option("--fallback <name>", "Fallback provider (optional)").option("--machine", "Bind the role in ~/.zam/config.json").action(async (role, opts) => {
+  if (!VALID_ROLES.includes(role)) {
+    console.error(`Invalid role: ${role}. Use ${VALID_ROLES.join(", ")}.`);
+    process.exit(1);
+  }
+  if (!opts.primary) {
+    console.error("--primary is required.");
+    process.exit(1);
+  }
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    await writeScopedRoles(
+      db,
+      machine,
+      bindRoleProviders(
+        await readScopedRoles(db, machine),
+        role,
+        opts.primary,
+        opts.fallback
+      )
+    );
+    const fb = opts.fallback ? `, fallback: ${opts.fallback}` : "";
+    console.log(
+      `Role "${role}" \u2192 primary: ${opts.primary}${fb} (${machine ? "machine-local" : "shared"})`
+    );
+    for (const [label, ref] of [
+      ["primary", opts.primary],
+      ["fallback", opts.fallback]
+    ]) {
+      if (ref && !(ref in providers)) {
+        console.log(
+          `  \u26A0 ${label} "${ref}" is not a defined provider yet. Add it: zam provider add ${ref} --url <url> --model <model>`
+        );
+      }
+    }
+  });
+});
+providerCommand.command("set-key <ref>").description(
+  "Store an API key for a provider reference (in credentials.json)"
+).option(
+  "--key <value>",
+  "The API key (omit to enter it interactively, hidden)"
+).action(async (ref, opts) => {
+  try {
+    const key = opts.key ?? await password2({ message: `API key for "${ref}":` });
+    if (!key || key.trim().length === 0) {
+      console.error("No key provided.");
+      process.exit(1);
+    }
+    setProviderApiKey(ref, key.trim());
+    console.log(`Stored API key for "${ref}" (${maskSecret(key.trim())}).`);
+  } catch (err) {
+    if (err.name === "ExitPromptError") {
+      console.log("\nCancelled.");
+      process.exit(0);
+    }
+    console.error("Error:", err.message);
+    process.exit(1);
+  }
+});
+providerCommand.command("clear-key <ref>").description("Remove a stored API key").action((ref) => {
+  clearProviderApiKey(ref);
+  console.log(`Cleared API key for "${ref}".`);
+});
+
 // src/cli/commands/review.ts
-import { Command as Command12 } from "commander";
-var reviewCommand = new Command12("review").description("Start an interactive review session").option("--user <id>", "User ID (default: whoami)").option("--max-new <n>", "Maximum new cards", "10").option("--max-reviews <n>", "Maximum review cards", "50").option("--no-resolve", "Skip resolving source_link into inline context").action(async (opts) => {
+import { Command as Command15 } from "commander";
+var reviewCommand = new Command15("review").description("Start an interactive review session").option("--user <id>", "User ID (default: whoami)").option("--max-new <n>", "Maximum new cards", "10").option("--max-reviews <n>", "Maximum review cards", "50").option("--no-resolve", "Skip resolving source_link into inline context").action(async (opts) => {
   let db;
   try {
     db = await openDatabase();
@@ -9353,10 +11252,10 @@ ${"\u2550".repeat(50)}`);
 });
 
 // src/cli/commands/session.ts
-import { readFileSync as readFileSync11 } from "fs";
-import { input as input6, select as select2 } from "@inquirer/prompts";
-import { Command as Command13 } from "commander";
-var sessionCommand = new Command13("session").description(
+import { readFileSync as readFileSync12 } from "fs";
+import { input as input7, select as select2 } from "@inquirer/prompts";
+import { Command as Command16 } from "commander";
+var sessionCommand = new Command16("session").description(
   "Manage learning sessions"
 );
 sessionCommand.command("start").description("Start a new learning session (review \u2192 task)").option("--user <id>", "User ID (default: whoami)").option("--task <description>", "Task description (interactive if omitted)").option(
@@ -9533,7 +11432,7 @@ async function selectTask() {
       console.log("No active work items found in Azure DevOps.");
     }
   }
-  return input6({ message: "Task description:" });
+  return input7({ message: "Task description:" });
 }
 var RATING_LABELS = {
   1: "Again",
@@ -9545,7 +11444,7 @@ function loadPatternFile(path) {
   if (!path) return [];
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync11(path, "utf-8"));
+    parsed = JSON.parse(readFileSync12(path, "utf-8"));
   } catch (err) {
     throw new Error(
       `Cannot read synthesis patterns from ${path}: ${err.message}`
@@ -9735,9 +11634,9 @@ sessionCommand.command("end").description("End a session and show summary").requ
 });
 
 // src/cli/commands/settings.ts
-import { existsSync as existsSync16 } from "fs";
-import { Command as Command14 } from "commander";
-var settingsCommand = new Command14("settings").description(
+import { existsSync as existsSync21 } from "fs";
+import { Command as Command17 } from "commander";
+var settingsCommand = new Command17("settings").description(
   "Manage user settings"
 );
 var BOOLEAN_SETTING_KEYS = /* @__PURE__ */ new Set(["llm.enabled", "llm.vision.enabled"]);
@@ -9860,229 +11759,60 @@ settingsCommand.command("locale [lang]").description(
       );
       process.exit(1);
     }
-    await setSetting(db, "system.locale", lower);
-    console.log(`Language set to: \x1B[32m${lower}\x1B[0m`);
-  });
-});
-settingsCommand.command("repos").description("Show or set Personal, Team, and Organization repository paths").option("--personal <path>", "Set the Personal Repository path").option("--team <path>", "Set the Team Repository path").option("--org <path>", "Set the Organization Repository path").action(async (opts) => {
-  await withDb(async (db) => {
-    let changed = false;
-    if (opts.personal !== void 0) {
-      await setSetting(db, "repo.personal", opts.personal);
-      console.log(`Set repo.personal = ${opts.personal}`);
-      changed = true;
-    }
-    if (opts.team !== void 0) {
-      await setSetting(db, "repo.team", opts.team);
-      console.log(`Set repo.team = ${opts.team}`);
-      changed = true;
-    }
-    if (opts.org !== void 0) {
-      await setSetting(db, "repo.org", opts.org);
-      console.log(`Set repo.org = ${opts.org}`);
-      changed = true;
-    }
-    if (changed) {
-      console.log("\nUpdated Repository Settings:\n");
-    } else {
-      console.log("Repository Settings:\n");
-    }
-    const paths = await getRepoPaths(db);
-    console.log(
-      `Personal Repo:  ${paths.personal ? `\x1B[32m${paths.personal}\x1B[0m` : "\x1B[31mNot Configured\x1B[0m"}`
-    );
-    console.log(
-      `Team Repo:      ${paths.team ? `\x1B[32m${paths.team}\x1B[0m` : "\x1B[31mNot Configured\x1B[0m"}`
-    );
-    console.log(
-      `Org Repo:       ${paths.org ? `\x1B[32m${paths.org}\x1B[0m` : "\x1B[31mNot Configured\x1B[0m"}`
-    );
-    console.log("\nValidation:");
-    for (const [name, path] of Object.entries(paths)) {
-      if (path) {
-        const exists = existsSync16(path);
-        console.log(
-          `  ${name.padEnd(9)}: ${exists ? "\x1B[32m\u2713 Valid folder\x1B[0m" : "\x1B[31m\u2717 Directory does not exist\x1B[0m"}`
-        );
-      } else {
-        console.log(`  ${name.padEnd(9)}: \x1B[33m- Not Set\x1B[0m`);
-      }
-    }
-  });
-});
-
-// src/cli/commands/setup.ts
-import { copyFileSync as copyFileSync2, existsSync as existsSync17, mkdirSync as mkdirSync10, writeFileSync as writeFileSync9 } from "fs";
-import { basename as basename4, dirname as dirname6, join as join18 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { Command as Command15 } from "commander";
-var packageRoot = [
-  fileURLToPath2(new URL("../..", import.meta.url)),
-  fileURLToPath2(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync17(join18(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
-var SKILL_PAIRS = [
-  {
-    from: join18(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
-    to: join18(".claude", "skills", "zam", "SKILL.md")
-  },
-  {
-    from: join18(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
-    to: join18(".agent", "skills", "zam", "SKILL.md")
-  },
-  {
-    from: join18(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
-    to: join18(".agents", "skills", "zam", "SKILL.md")
-  }
-];
-function copySkills(force, cwd = process.cwd()) {
-  let anyAction = false;
-  for (const { from, to } of SKILL_PAIRS) {
-    const dest = join18(cwd, to);
-    if (!existsSync17(from)) {
-      console.warn(`  warn  source not found, skipping: ${from}`);
-      continue;
-    }
-    if (existsSync17(dest) && !force) {
-      console.log(`  skip  ${to} (already present \xE2\u20AC\u201D use --force to update)`);
-      continue;
-    }
-    mkdirSync10(dirname6(dest), { recursive: true });
-    copyFileSync2(from, dest);
-    console.log(`  copy  ${to}`);
-    anyAction = true;
-  }
-  if (!anyAction && !force) {
-    console.log(
-      "\nSkill files are already up to date. Run with --force to overwrite."
-    );
-  }
-}
-function formatDatabaseInitTarget(target) {
-  switch (target.kind) {
-    case "local":
-      return `ZAM database at ${target.location} (local SQLite)`;
-    case "turso-remote":
-      return `ZAM database via Turso remote at ${target.location}`;
-    case "turso-native":
-      return `ZAM database via Turso native driver at ${target.location}`;
-    case "turso-replica":
-      return `ZAM database replica at ${target.location} syncing from ${target.syncUrl}`;
-  }
-}
-async function initDatabase(skipInit) {
-  if (skipInit) return;
-  try {
-    const target = getDatabaseTargetInfo();
-    const db = await openDatabaseWithSync({ initialize: true });
-    await db.close();
-    console.log(`  init  ${formatDatabaseInitTarget(target)}`);
-  } catch (err) {
-    const msg = err.message;
-    if (!msg.includes("already")) {
-      console.warn(`  warn  database init: ${msg}`);
+    await setSetting(db, "system.locale", lower);
+    console.log(`Language set to: \x1B[32m${lower}\x1B[0m`);
+  });
+});
+settingsCommand.command("repos").description("Show or set Personal, Team, and Organization repository paths").option("--personal <path>", "Set the Personal Repository path").option("--team <path>", "Set the Team Repository path").option("--org <path>", "Set the Organization Repository path").action(async (opts) => {
+  await withDb(async (db) => {
+    let changed = false;
+    if (opts.personal !== void 0) {
+      await setSetting(db, "repo.personal", opts.personal);
+      console.log(`Set repo.personal = ${opts.personal}`);
+      changed = true;
+    }
+    if (opts.team !== void 0) {
+      await setSetting(db, "repo.team", opts.team);
+      console.log(`Set repo.team = ${opts.team}`);
+      changed = true;
+    }
+    if (opts.org !== void 0) {
+      await setSetting(db, "repo.org", opts.org);
+      console.log(`Set repo.org = ${opts.org}`);
+      changed = true;
+    }
+    if (changed) {
+      console.log("\nUpdated Repository Settings:\n");
     } else {
-      console.log(`  skip  database already initialized`);
+      console.log("Repository Settings:\n");
     }
-  }
-}
-function writeClaudeMd(skipClaudeMd, cwd = process.cwd()) {
-  if (skipClaudeMd) return;
-  const dest = join18(cwd, "CLAUDE.md");
-  if (existsSync17(dest)) {
-    console.log(`  skip  CLAUDE.md (already present)`);
-    return;
-  }
-  const name = basename4(cwd);
-  writeFileSync9(
-    dest,
-    `# ZAM Personal Kernel \xE2\u20AC\u201D ${name}
-
-This is a ZAM personal instance. ZAM builds lasting skills through spaced
-repetition during real work \xE2\u20AC\u201D not separate study sessions.
-
-## First time here?
-Run \`/setup\` in Claude Code or Gemini CLI to complete first-time setup.
-
-## Regular use
-Run \`/zam\` to start a learning session on whatever you are working on.
-
-## What lives here
-- \`beliefs/\` \xE2\u20AC\u201D your worldview, approved by git commit
-- \`goals/\` \xE2\u20AC\u201D your objectives, decomposed into tasks and learning tokens
-
-## Fast-changing data
-Learning tokens, cards, and review history live in local SQLite by default.
-Use \`zam connector setup turso\` to store cloud credentials in
-\`~/.zam/credentials.json\` and use a Turso database across machines.
-`,
-    "utf8"
-  );
-  console.log(`  write CLAUDE.md`);
-}
-function writeAgentsMd(skipAgentsMd, cwd = process.cwd()) {
-  if (skipAgentsMd) return;
-  const dest = join18(cwd, "AGENTS.md");
-  if (existsSync17(dest)) {
-    console.log(`  skip  AGENTS.md (already present)`);
-    return;
-  }
-  const name = basename4(cwd);
-  writeFileSync9(
-    dest,
-    `# ZAM Personal Kernel - ${name}
-
-This is a ZAM personal instance. ZAM builds lasting skills through spaced
-repetition during real work, not separate study sessions.
-
-## First time here?
-Run \`zam setup\` from the shell. When this repository includes
-\`.agents/skills/setup/\`, you can instead select \`setup\` through \`/skills\`
-or invoke \`$setup\`.
-
-## Regular use
-Select the \`zam\` skill through \`/skills\` or invoke \`$zam\` to start a
-learning session on whatever you are working on.
-
-## What lives here
-- \`beliefs/\` - your worldview, approved by git commit
-- \`goals/\` - your objectives, decomposed into tasks and learning tokens
-
-## Fast-changing data
-Learning tokens, cards, and review history live in local SQLite by default.
-Use \`zam connector setup turso\` to store cloud credentials in
-\`~/.zam/credentials.json\` and use a Turso database across machines.
-
-## Codex skills
-Codex discovers repository skills under \`.agents/skills/\`. Run
-\`zam setup --force\` after upgrading \`zam-core\` to refresh them.
-`,
-    "utf8"
-  );
-  console.log(`  write AGENTS.md`);
-}
-var setupCommand = new Command15("setup").description(
-  "Distribute ZAM skill files into this personal instance and initialize the database"
-).option(
-  "--force",
-  "overwrite existing skill files (use after upgrading zam)",
-  false
-).option("--skip-init", "skip database initialization", false).option("--skip-claude-md", "skip CLAUDE.md generation", false).option("--skip-agents-md", "skip AGENTS.md generation", false).action(
-  async (opts) => {
-    console.log(`Setting up ZAM in ${process.cwd()}
-`);
-    copySkills(opts.force);
-    await initDatabase(opts.skipInit);
-    writeClaudeMd(opts.skipClaudeMd);
-    writeAgentsMd(opts.skipAgentsMd);
+    const paths = await getRepoPaths(db);
     console.log(
-      "\nDone. Run `zam whoami --set <your-id>` to set your identity. Start the `zam` skill with `/zam` in Claude/Gemini-compatible clients or `$zam` (or `/skills`) in Codex."
+      `Personal Repo:  ${paths.personal ? `\x1B[32m${paths.personal}\x1B[0m` : "\x1B[31mNot Configured\x1B[0m"}`
     );
-  }
-);
+    console.log(
+      `Team Repo:      ${paths.team ? `\x1B[32m${paths.team}\x1B[0m` : "\x1B[31mNot Configured\x1B[0m"}`
+    );
+    console.log(
+      `Org Repo:       ${paths.org ? `\x1B[32m${paths.org}\x1B[0m` : "\x1B[31mNot Configured\x1B[0m"}`
+    );
+    console.log("\nValidation:");
+    for (const [name, path] of Object.entries(paths)) {
+      if (path) {
+        const exists = existsSync21(path);
+        console.log(
+          `  ${name.padEnd(9)}: ${exists ? "\x1B[32m\u2713 Valid folder\x1B[0m" : "\x1B[31m\u2717 Directory does not exist\x1B[0m"}`
+        );
+      } else {
+        console.log(`  ${name.padEnd(9)}: \x1B[33m- Not Set\x1B[0m`);
+      }
+    }
+  });
+});
 
 // src/cli/commands/skill.ts
-import { Command as Command16 } from "commander";
-var skillCommand = new Command16("skill").description(
+import { Command as Command18 } from "commander";
+var skillCommand = new Command18("skill").description(
   "Manage agent skill entries (task recipes)"
 );
 skillCommand.command("list").description("List all agent skills").option("--json", "Output as JSON").action(async (opts) => {
@@ -10167,10 +11897,10 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
 });
 
 // src/cli/commands/snapshot.ts
-import { existsSync as existsSync18, mkdirSync as mkdirSync11, readFileSync as readFileSync12, writeFileSync as writeFileSync10 } from "fs";
-import { homedir as homedir11 } from "os";
-import { dirname as dirname7, join as join19 } from "path";
-import { Command as Command17 } from "commander";
+import { existsSync as existsSync22, mkdirSync as mkdirSync12, readFileSync as readFileSync13, writeFileSync as writeFileSync11 } from "fs";
+import { homedir as homedir13 } from "os";
+import { dirname as dirname7, join as join21 } from "path";
+import { Command as Command19 } from "commander";
 function defaultOutName() {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
   return `zam-snapshot-${stamp}.sql`;
@@ -10184,12 +11914,12 @@ function summarize(tables) {
   }
   return { total, nonEmpty };
 }
-var exportCmd = new Command17("export").description("Write a portable SQL-text snapshot of the database").option("--out <file>", "Output file (use - for stdout)").action(async (opts) => {
+var exportCmd = new Command19("export").description("Write a portable SQL-text snapshot of the database").option("--out <file>", "Output file (use - for stdout)").action(async (opts) => {
   let db;
   try {
     db = await openDatabaseWithSync({ initialize: true });
     const snapshot = await exportSnapshot(db);
-    const personalDir = await getSetting(db, "personal.workspace_dir") || join19(homedir11(), "Documents", "zam");
+    const personalDir = await getSetting(db, "personal.workspace_dir") || join21(homedir13(), "Documents", "zam");
     await db.close();
     db = void 0;
     const manifest = verifySnapshot(snapshot);
@@ -10198,12 +11928,12 @@ var exportCmd = new Command17("export").description("Write a portable SQL-text s
       process.stdout.write(snapshot);
       return;
     }
-    const out = opts.out ?? join19(personalDir, "snapshots", defaultOutName());
+    const out = opts.out ?? join21(personalDir, "snapshots", defaultOutName());
     const dir = dirname7(out);
-    if (dir && dir !== "." && !existsSync18(dir)) {
-      mkdirSync11(dir, { recursive: true });
+    if (dir && dir !== "." && !existsSync22(dir)) {
+      mkdirSync12(dir, { recursive: true });
     }
-    writeFileSync10(out, snapshot, "utf-8");
+    writeFileSync11(out, snapshot, "utf-8");
     console.log(`Snapshot written: ${out}`);
     console.log(
       `  ${total} row(s)${nonEmpty.length ? ` \u2014 ${nonEmpty.join(", ")}` : ""}`
@@ -10214,14 +11944,14 @@ var exportCmd = new Command17("export").description("Write a portable SQL-text s
     process.exit(1);
   }
 });
-var importCmd = new Command17("import").description("Restore a snapshot into the database").argument("<file>", "Snapshot file to restore").option("--force", "Overwrite a non-empty database", false).action(async (file, opts) => {
+var importCmd = new Command19("import").description("Restore a snapshot into the database").argument("<file>", "Snapshot file to restore").option("--force", "Overwrite a non-empty database", false).action(async (file, opts) => {
   let db;
   try {
-    if (!existsSync18(file)) {
+    if (!existsSync22(file)) {
       console.error(`Error: Snapshot file not found: ${file}`);
       process.exit(1);
     }
-    const snapshot = readFileSync12(file, "utf-8");
+    const snapshot = readFileSync13(file, "utf-8");
     db = await openDatabaseWithSync({ initialize: true });
     const result = await importSnapshot(db, snapshot, { force: opts.force });
     await db.close();
@@ -10237,13 +11967,13 @@ var importCmd = new Command17("import").description("Restore a snapshot into the
     process.exit(1);
   }
 });
-var verifyCmd = new Command17("verify").description("Check a snapshot's manifest and checksum without importing").argument("<file>", "Snapshot file to verify").action((file) => {
+var verifyCmd = new Command19("verify").description("Check a snapshot's manifest and checksum without importing").argument("<file>", "Snapshot file to verify").action((file) => {
   try {
-    if (!existsSync18(file)) {
+    if (!existsSync22(file)) {
       console.error(`Error: Snapshot file not found: ${file}`);
       process.exit(1);
     }
-    const manifest = verifySnapshot(readFileSync12(file, "utf-8"));
+    const manifest = verifySnapshot(readFileSync13(file, "utf-8"));
     const { total, nonEmpty } = summarize(manifest.tables);
     console.log(`Valid snapshot (format v${manifest.version})`);
     console.log(`  created: ${manifest.createdAt}`);
@@ -10255,11 +11985,11 @@ var verifyCmd = new Command17("verify").description("Check a snapshot's manifest
     process.exit(1);
   }
 });
-var snapshotCommand = new Command17("snapshot").description("Export, import, or verify a portable database snapshot").addCommand(exportCmd).addCommand(importCmd).addCommand(verifyCmd);
+var snapshotCommand = new Command19("snapshot").description("Export, import, or verify a portable database snapshot").addCommand(exportCmd).addCommand(importCmd).addCommand(verifyCmd);
 
 // src/cli/commands/stats.ts
-import { Command as Command18 } from "commander";
-var statsCommand = new Command18("stats").description("Show learning dashboard for a user").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").action(async (opts) => {
+import { Command as Command20 } from "commander";
+var statsCommand = new Command20("stats").description("Show learning dashboard for a user").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").action(async (opts) => {
   await withDb(async (db) => {
     const userId = await resolveUser(opts, db);
     const stats = await getUserStats(db, userId);
@@ -10295,8 +12025,8 @@ var statsCommand = new Command18("stats").description("Show learning dashboard f
 });
 
 // src/cli/commands/token.ts
-import { Command as Command19 } from "commander";
-var tokenCommand = new Command19("token").description(
+import { Command as Command21 } from "commander";
+var tokenCommand = new Command21("token").description(
   "Manage knowledge tokens"
 );
 tokenCommand.command("register").description("Register a new knowledge token").requiredOption("--slug <slug>", "Unique token slug").requiredOption("--concept <concept>", "Concept description").option("--domain <domain>", "Knowledge domain", "").option("--bloom <level>", "Bloom taxonomy level (1-5)", "1").option("--source-link <link>", "Source file path or reference URL", "").option("--question <question>", "Specific question prompt for recall", "").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
@@ -10582,12 +12312,12 @@ tokenCommand.command("status").description("Show full status of a token for a us
 });
 
 // src/cli/commands/ui.ts
-import { spawn as spawn2, spawnSync } from "child_process";
-import { existsSync as existsSync19 } from "fs";
-import { homedir as homedir12 } from "os";
-import { dirname as dirname8, join as join20 } from "path";
+import { spawn as spawn3, spawnSync } from "child_process";
+import { existsSync as existsSync23 } from "fs";
+import { homedir as homedir14 } from "os";
+import { dirname as dirname8, join as join22 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
-import { Command as Command20 } from "commander";
+import { Command as Command22 } from "commander";
 var C3 = {
   reset: "\x1B[0m",
   red: "\x1B[31m",
@@ -10601,8 +12331,8 @@ function findDesktopDir() {
   for (const start of starts) {
     let dir = start;
     for (let i = 0; i < 10; i++) {
-      if (existsSync19(join20(dir, "desktop", "src-tauri", "tauri.conf.json"))) {
-        return join20(dir, "desktop");
+      if (existsSync23(join22(dir, "desktop", "src-tauri", "tauri.conf.json"))) {
+        return join22(dir, "desktop");
       }
       const parent = dirname8(dir);
       if (parent === dir) break;
@@ -10612,30 +12342,30 @@ function findDesktopDir() {
   return null;
 }
 function findBuiltApp(desktopDir) {
-  const releaseDir = join20(desktopDir, "src-tauri", "target", "release");
+  const releaseDir = join22(desktopDir, "src-tauri", "target", "release");
   if (process.platform === "win32") {
     for (const name of ["ZAM.exe", "zam.exe", "zam-desktop.exe"]) {
-      const p = join20(releaseDir, name);
-      if (existsSync19(p)) return p;
+      const p = join22(releaseDir, name);
+      if (existsSync23(p)) return p;
     }
   } else if (process.platform === "darwin") {
-    const app = join20(releaseDir, "bundle", "macos", "ZAM.app");
-    if (existsSync19(app)) return app;
+    const app = join22(releaseDir, "bundle", "macos", "ZAM.app");
+    if (existsSync23(app)) return app;
   } else {
     for (const name of ["zam", "ZAM", "zam-desktop"]) {
-      const p = join20(releaseDir, name);
-      if (existsSync19(p)) return p;
+      const p = join22(releaseDir, name);
+      if (existsSync23(p)) return p;
     }
   }
   return null;
 }
 function findInstalledApp() {
   const candidates = process.platform === "win32" ? [
-    process.env.LOCALAPPDATA && join20(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
-    process.env.ProgramFiles && join20(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
-    process.env["ProgramFiles(x86)"] && join20(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
-  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join20(homedir12(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
-  return candidates.find((candidate) => candidate && existsSync19(candidate)) || null;
+    process.env.LOCALAPPDATA && join22(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
+    process.env.ProgramFiles && join22(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
+    process.env["ProgramFiles(x86)"] && join22(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
+  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join22(homedir14(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
+  return candidates.find((candidate) => candidate && existsSync23(candidate)) || null;
 }
 function runNpm(args, opts) {
   const res = spawnSync("npm", args, {
@@ -10646,7 +12376,7 @@ function runNpm(args, opts) {
   return res.status ?? 1;
 }
 function ensureDesktopDeps(desktopDir) {
-  if (existsSync19(join20(desktopDir, "node_modules"))) return true;
+  if (existsSync23(join22(desktopDir, "node_modules"))) return true;
   console.log(
     `${C3.cyan}Installing desktop dependencies (one-time)...${C3.reset}`
   );
@@ -10672,13 +12402,13 @@ function requireRust() {
 function hasMsvcBuildTools() {
   if (process.platform !== "win32") return true;
   const pf86 = process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)";
-  const vswhere = join20(
+  const vswhere = join22(
     pf86,
     "Microsoft Visual Studio",
     "Installer",
     "vswhere.exe"
   );
-  if (!existsSync19(vswhere)) return false;
+  if (!existsSync23(vswhere)) return false;
   const res = spawnSync(
     vswhere,
     [
@@ -10710,7 +12440,7 @@ function requireMsvcOnWindows() {
   return false;
 }
 function warnIfCliMissing(repoRoot) {
-  if (!existsSync19(join20(repoRoot, "dist", "cli", "index.js"))) {
+  if (!existsSync23(join22(repoRoot, "dist", "cli", "index.js"))) {
     console.warn(
       `${C3.yellow}\u26A0 CLI build not found (dist/cli/index.js). The GUI bridge needs it \u2014 run 'npm run build' at the repo root.${C3.reset}`
     );
@@ -10719,13 +12449,13 @@ function warnIfCliMissing(repoRoot) {
 function launchApp(appPath, workingDir) {
   console.log(`${C3.green}\u2713 Launching ZAM Desktop...${C3.reset}`);
   if (process.platform === "darwin" && appPath.endsWith(".app")) {
-    spawn2("open", [appPath], {
+    spawn3("open", [appPath], {
       cwd: workingDir,
       detached: true,
       stdio: "ignore"
     }).unref();
   } else {
-    spawn2(appPath, [], {
+    spawn3(appPath, [], {
       cwd: workingDir,
       detached: true,
       stdio: "ignore",
@@ -10767,13 +12497,13 @@ function createShortcuts(appPath, repoRoot) {
     console.error(`${C3.red}\u2717 Could not create shortcuts.${C3.reset}`);
   }
 }
-var uiCommand = new Command20("ui").description("Launch the ZAM Desktop GUI (Active-Recall Studio)").option("--dev", "Run in hot-reload development mode (needs Rust)").option(
+var uiCommand = new Command22("ui").description("Launch the ZAM Desktop GUI (Active-Recall Studio)").option("--dev", "Run in hot-reload development mode (needs Rust)").option(
   "--build",
   "Build the native installer for your OS (needs Rust, one-time)"
 ).option("--shortcut", "Create Desktop + Start-menu shortcuts to the GUI").action((opts) => {
   const installedApp = findInstalledApp();
   if (!opts.dev && !opts.build && !opts.shortcut && installedApp) {
-    launchApp(installedApp, homedir12());
+    launchApp(installedApp, homedir14());
     return;
   }
   const desktopDir = findDesktopDir();
@@ -10794,7 +12524,7 @@ var uiCommand = new Command20("ui").description("Launch the ZAM Desktop GUI (Act
     );
     const code = runNpm(["run", "tauri", "build"], { cwd: desktopDir });
     if (code === 0) {
-      const bundle = join20(
+      const bundle = join22(
         desktopDir,
         "src-tauri",
         "target",
@@ -10871,11 +12601,11 @@ ${C3.dim}After that, 'zam ui' launches it directly.${C3.reset}`
 
 // src/cli/commands/update.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync20, readFileSync as readFileSync13, realpathSync } from "fs";
-import { dirname as dirname9, join as join21 } from "path";
+import { existsSync as existsSync24, readFileSync as readFileSync14, realpathSync } from "fs";
+import { dirname as dirname9, join as join23 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
-import { confirm as confirm3 } from "@inquirer/prompts";
-import { Command as Command21 } from "commander";
+import { confirm as confirm4 } from "@inquirer/prompts";
+import { Command as Command23 } from "commander";
 var GITHUB_REPO = "zam-os/zam";
 var CHANNELS = [
   "developer",
@@ -10897,7 +12627,7 @@ function currentVersion() {
   for (const up of ["..", "../..", "../../.."]) {
     try {
       const pkg2 = JSON.parse(
-        readFileSync13(join21(here, up, "package.json"), "utf-8")
+        readFileSync14(join23(here, up, "package.json"), "utf-8")
       );
       if (pkg2.version) return pkg2.version;
     } catch {
@@ -10908,7 +12638,7 @@ function currentVersion() {
 function versionAt(dir) {
   try {
     const pkg2 = JSON.parse(
-      readFileSync13(join21(dir, "package.json"), "utf-8")
+      readFileSync14(join23(dir, "package.json"), "utf-8")
     );
     return pkg2.version ?? "unknown";
   } catch {
@@ -10953,7 +12683,7 @@ function render2(decision) {
     );
   }
 }
-var checkCmd = new Command21("check").description("Check whether a newer ZAM has been released").option(
+var checkCmd = new Command23("check").description("Check whether a newer ZAM has been released").option(
   "--latest <version>",
   "Compare against this version instead of fetching"
 ).option("--channel <channel>", "Override the detected install channel").option("--json", "Output as JSON").action(
@@ -10988,13 +12718,13 @@ function findSourceRepo() {
   let dir = realpathSync(dirname9(fileURLToPath4(import.meta.url)));
   let parent = dirname9(dir);
   while (parent !== dir) {
-    if (existsSync20(join21(dir, ".git"))) return dir;
+    if (existsSync24(join23(dir, ".git"))) return dir;
     dir = parent;
     parent = dirname9(dir);
   }
-  return existsSync20(join21(dir, ".git")) ? dir : null;
+  return existsSync24(join23(dir, ".git")) ? dir : null;
 }
-function runGit(cwd, args, capture) {
+function runGit2(cwd, args, capture) {
   const res = spawnSync2("git", args, {
     cwd,
     stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
@@ -11026,7 +12756,7 @@ function applyDeveloperUpdate(force) {
     );
     process.exit(1);
   }
-  const status = runGit(src, ["status", "--porcelain"], true);
+  const status = runGit2(src, ["status", "--porcelain"], true);
   if (status.ok && status.out && !force) {
     console.error(
       `${C4.red}\u2717${C4.reset} The source checkout has uncommitted changes:
@@ -11038,7 +12768,7 @@ Commit or stash them, or re-run with ${C4.cyan}--force${C4.reset}.`
   console.log(
     `${C4.dim}\u2192 git pull --ff-only${C4.reset}  ${C4.dim}(${src})${C4.reset}`
   );
-  if (!runGit(src, ["pull", "--ff-only"], false).ok) {
+  if (!runGit2(src, ["pull", "--ff-only"], false).ok) {
     console.error(
       `${C4.red}\u2717${C4.reset} git pull failed \u2014 the branch may have diverged or you are offline. Resolve it manually, then retry.`
     );
@@ -11057,7 +12787,7 @@ Commit or stash them, or re-run with ${C4.cyan}--force${C4.reset}.`
   console.log(`${C4.dim}\u2192 zam setup --force${C4.reset}`);
   const setup = spawnSync2(
     process.execPath,
-    [join21(src, "dist", "cli", "index.js"), "setup", "--force"],
+    [join23(src, "dist", "cli", "index.js"), "setup", "--force"],
     { cwd: process.cwd(), stdio: "inherit" }
   );
   if (setup.status !== 0) {
@@ -11100,7 +12830,7 @@ ${C4.dim}This install updates through the desktop app's signed updater \u2014 op
       return;
     }
     if (!opts.yes) {
-      const ok = await confirm3({
+      const ok = await confirm4({
         message: "Apply this update?",
         default: true
       });
@@ -11120,7 +12850,7 @@ ${C4.dim}This install updates through the desktop app's signed updater \u2014 op
     process.exit(1);
   }
 }
-var updateCommand = new Command21("update").description(
+var updateCommand = new Command23("update").description(
   "Update ZAM to the latest release (use `update check` to only check)"
 ).option("-y, --yes", "Apply without confirmation").option(
   "--force",
@@ -11130,8 +12860,8 @@ var updateCommand = new Command21("update").description(
 }).addCommand(checkCmd);
 
 // src/cli/commands/whoami.ts
-import { Command as Command22 } from "commander";
-var whoamiCommand = new Command22("whoami").description("Show or set the default user identity").option("--set <id>", "Set the default user ID").option("--clear", "Remove the default user ID").option("--json", "Output as JSON").action(async (opts) => {
+import { Command as Command24 } from "commander";
+var whoamiCommand = new Command24("whoami").description("Show or set the default user identity").option("--set <id>", "Set the default user ID").option("--clear", "Remove the default user ID").option("--json", "Output as JSON").action(async (opts) => {
   await withDb(async (db) => {
     if (opts.set) {
       await setSetting(db, "user.id", opts.set);
@@ -11166,163 +12896,12 @@ var whoamiCommand = new Command22("whoami").description("Show or set the default
   });
 });
 
-// src/cli/commands/workspace.ts
-import { execSync as execSync6 } from "child_process";
-import { existsSync as existsSync21, writeFileSync as writeFileSync11 } from "fs";
-import { join as join22 } from "path";
-import { confirm as confirm4, input as input7 } from "@inquirer/prompts";
-import { Command as Command23 } from "commander";
-function runGit2(cwd, args) {
-  try {
-    return execSync6(`git ${args}`, {
-      cwd,
-      stdio: "pipe",
-      encoding: "utf8"
-    }).trim();
-  } catch (err) {
-    throw new Error(`Git command failed: ${err.message}`);
-  }
-}
-var workspaceCommand = new Command23("workspace").description(
-  "Manage your ZAM learning workspace"
-);
-workspaceCommand.command("publish").description("Publish your local workspace sandbox to GitHub").action(async () => {
-  let db;
-  let workspaceDir = "";
-  try {
-    db = await openDatabase();
-    workspaceDir = await getSetting(db, "personal.workspace_dir") || "";
-    await db.close();
-  } catch {
-    await db?.close();
-  }
-  if (!workspaceDir) {
-    console.error(
-      "\x1B[31m\u2717 No active workspace configured. Please run `zam init` first.\x1B[0m"
-    );
-    process.exit(1);
-  }
-  if (!existsSync21(workspaceDir)) {
-    console.error(
-      `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
-    );
-    process.exit(1);
-  }
-  console.log(`
-Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
-  if (!hasCommand("git")) {
-    console.error(
-      "\x1B[31m\u2717 Git command was not found on this system. Please install Git first.\x1B[0m"
-    );
-    process.exit(1);
-  }
-  const gitignorePath = join22(workspaceDir, ".gitignore");
-  if (!existsSync21(gitignorePath)) {
-    writeFileSync11(
-      gitignorePath,
-      "node_modules/\n.agent/\n.agents/\n.claude/\n.gemini/\n.goose/\n*.log\n",
-      "utf8"
-    );
-  }
-  const hasGitRepo = existsSync21(join22(workspaceDir, ".git"));
-  if (!hasGitRepo) {
-    console.log("Initializing local Git repository...");
-    runGit2(workspaceDir, "init -b main");
-    runGit2(workspaceDir, "add .");
-    runGit2(
-      workspaceDir,
-      'commit -m "chore: initial workspace sandbox bootstrap"'
-    );
-    console.log("\x1B[32m\u2713 Local Git repository initialized.\x1B[0m");
-  } else {
-    console.log("Git repository is already initialized.");
-  }
-  const repoName = await input7({
-    message: "Choose a name for your GitHub repository:",
-    default: "zam-personal"
-  });
-  const isPrivate = await confirm4({
-    message: "Should the repository be private?",
-    default: true
-  });
-  const repoVisibility = isPrivate ? "--private" : "--public";
-  if (hasCommand("gh")) {
-    console.log("GitHub CLI detected! Automating repository creation...");
-    const proceedGh = await confirm4({
-      message: "Would you like ZAM to create the repository using the GitHub CLI?",
-      default: true
-    });
-    if (proceedGh) {
-      try {
-        console.log(`Creating GitHub repository ${repoName}...`);
-        execSync6(
-          `gh repo create ${repoName} ${repoVisibility} --source=. --push`,
-          {
-            cwd: workspaceDir,
-            stdio: "inherit"
-          }
-        );
-        console.log(
-          "\n\x1B[32m\u2713 Successfully published workspace to GitHub!\x1B[0m"
-        );
-        process.exit(0);
-      } catch (err) {
-        console.warn(
-          `\x1B[33m\u26A0 GitHub CLI creation failed: ${err.message}\x1B[0m`
-        );
-      }
-    }
-  }
-  console.log(
-    "\n\x1B[1mPlease create the repository manually on GitHub:\x1B[0m"
-  );
-  console.log("  1. Go to https://github.com/new");
-  console.log(`  2. Name it exactly: \x1B[36m${repoName}\x1B[0m`);
-  console.log(
-    `  3. Choose \x1B[36m${isPrivate ? "Private" : "Public"}\x1B[0m`
-  );
-  console.log(
-    "  4. Do NOT initialize it with README, .gitignore, or license"
-  );
-  console.log("  5. Click 'Create repository'\n");
-  const githubUrl = await input7({
-    message: "Paste the repository Git URL (e.g. git@github.com:user/repo.git):"
-  });
-  if (githubUrl) {
-    try {
-      console.log("Linking remote repository and pushing...");
-      let hasOrigin = false;
-      try {
-        runGit2(workspaceDir, "remote get-url origin");
-        hasOrigin = true;
-      } catch {
-      }
-      if (hasOrigin) {
-        runGit2(workspaceDir, `remote set-url origin ${githubUrl}`);
-      } else {
-        runGit2(workspaceDir, `remote add origin ${githubUrl}`);
-      }
-      runGit2(workspaceDir, "push -u origin main");
-      console.log(
-        "\x1B[32m\u2713 Successfully linked and pushed to GitHub!\x1B[0m"
-      );
-    } catch (err) {
-      console.error(
-        `\x1B[31m\u2717 Push failed: ${err.message}\x1B[0m`
-      );
-      console.log(
-        "You can push manually later using: git push -u origin main"
-      );
-    }
-  }
-});
-
 // src/cli/index.ts
 var __dirname = dirname10(fileURLToPath5(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync14(join23(__dirname, "..", "..", "package.json"), "utf-8")
+  readFileSync15(join24(__dirname, "..", "..", "package.json"), "utf-8")
 );
-var program = new Command24();
+var program = new Command25();
 program.name("zam").description(
   "The Symbiotic Learning Kernel: Elevating Human Intelligence through AI Collaboration."
 ).version(pkg.version);
@@ -11342,6 +12921,7 @@ program.addCommand(observerCommand);
 program.addCommand(settingsCommand);
 program.addCommand(whoamiCommand);
 program.addCommand(connectorCommand);
+program.addCommand(providerCommand);
 program.addCommand(snapshotCommand);
 program.addCommand(profileCommand);
 program.addCommand(updateCommand);