zam-core 0.4.4 → 0.5.0

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { readFileSync as readFileSync14 } from "fs";
+import { readFileSync as readFileSync15 } from "fs";
 import { dirname as dirname10, join as join24 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 import { Command as Command25 } from "commander";
@@ -4422,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"));
@@ -4431,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";
@@ -5031,7 +5058,7 @@ function isItermRunning() {
     return false;
   }
 }
-function openMacTerminal(shellSetup, label, dir) {
+function openMacTerminal(shellSetup, label, dir, silent) {
   const useIterm = isItermRunning();
   const escaped = shellSetup.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
   const appleScript = useIterm ? `tell application "iTerm2"
@@ -5048,16 +5075,20 @@ end tell`;
   try {
     writeFileSync6(tmpFile, appleScript);
     execSync4(`osascript ${JSON.stringify(tmpFile)}`, { stdio: "ignore" });
-    console.log(
-      `Opened ${useIterm ? "iTerm2" : "Terminal.app"} window (${label})`
-    );
-    console.log(`  Directory: ${dir}`);
+    if (!silent) {
+      console.log(
+        `Opened ${useIterm ? "iTerm2" : "Terminal.app"} window (${label})`
+      );
+      console.log(`  Directory: ${dir}`);
+    }
   } catch (err) {
-    console.error(`Failed to open terminal: ${err.message}`);
-    console.log(`
+    if (!silent) {
+      console.error(`Failed to open terminal: ${err.message}`);
+      console.log(`
 Run this manually in a new terminal:
 `);
-    console.log(`  ${shellSetup}`);
+      console.log(`  ${shellSetup}`);
+    }
   } finally {
     try {
       unlinkSync(tmpFile);
@@ -5065,7 +5096,7 @@ Run this manually in a new terminal:
     }
   }
 }
-function openWindowsPowerShell(shellSetup, label, dir, requestedShell) {
+function openWindowsPowerShell(shellSetup, label, dir, requestedShell, silent) {
   const requestedExecutable = requestedShell === "powershell" ? "powershell.exe" : "pwsh.exe";
   const executable = findExecutable(requestedExecutable) ? requestedExecutable : "powershell.exe";
   const startCommand = [
@@ -5082,35 +5113,42 @@ function openWindowsPowerShell(shellSetup, label, dir, requestedShell) {
         stdio: "ignore"
       }
     );
-    console.log(
-      `Opened ${executable === "pwsh.exe" ? "PowerShell" : "Windows PowerShell"} window (${label})`
-    );
-    console.log(`  Directory: ${dir}`);
+    if (!silent) {
+      console.log(
+        `Opened ${executable === "pwsh.exe" ? "PowerShell" : "Windows PowerShell"} window (${label})`
+      );
+      console.log(`  Directory: ${dir}`);
+    }
   } catch (err) {
-    console.error(`Failed to open PowerShell: ${err.message}`);
-    console.log(`
+    if (!silent) {
+      console.error(`Failed to open PowerShell: ${err.message}`);
+      console.log(`
 Run this manually in a new PowerShell terminal:
 `);
-    console.log(`  ${shellSetup}`);
+      console.log(`  ${shellSetup}`);
+    }
   }
 }
 function openTerminalWindow(opts) {
-  const { shellSetup, label, dir, shell } = opts;
-  if (process.platform === "darwin" && !isPowerShellShell(shell)) {
-    openMacTerminal(shellSetup, label, dir);
+  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 (process.platform === "win32" && isPowerShellShell(shell)) {
-    openWindowsPowerShell(shellSetup, label, dir, shell);
+  if (platform === "win32" && isPowerShellShell(shell)) {
+    openWindowsPowerShell(shellSetup, label, dir, shell, silent);
     return;
   }
-  console.log(`Run this in a new terminal:
+  if (!silent) {
+    console.log(`Run this in a new terminal:
 `);
-  console.log(`  ${shellSetup}
+    console.log(`  ${shellSetup}
 `);
-  console.log(
-    `(Automatic terminal opening is only supported on macOS Terminal/iTerm2 and Windows PowerShell for now.)`
-  );
+    console.log(
+      `(Automatic terminal opening is only supported on macOS Terminal/iTerm2 and Windows PowerShell for now.)`
+    );
+  }
 }
 
 // src/cli/agent-harness.ts
@@ -5176,7 +5214,9 @@ function launchHarness(harness, opts) {
       shellSetup: plan.shellSetup,
       label: `agent-${harness.id}`,
       dir: opts.workspace,
-      shell: plan.shell
+      shell: plan.shell,
+      silent: opts.silent,
+      platform: opts.platform
     });
     return;
   }
@@ -5185,7 +5225,9 @@ function launchHarness(harness, opts) {
     stdio: "ignore",
     windowsHide: true
   }).unref();
-  console.log(`Launched ${harness.label} in ${opts.workspace}`);
+  if (!opts.silent) {
+    console.log(`Launched ${harness.label} in ${opts.workspace}`);
+  }
 }
 
 // src/cli/commands/agent.ts
@@ -5310,10 +5352,10 @@ var agentCommand = new Command("agent").description("Provision and inspect the a
 // src/cli/commands/bridge.ts
 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 { existsSync as existsSync17, readdirSync as readdirSync2, readFileSync as readFileSync11, rmSync as rmSync2 } from "fs";
 import { homedir as homedir10, tmpdir as tmpdir3 } from "os";
-import { join as join16, resolve as resolve3 } from "path";
-import { Command as Command3 } from "commander";
+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 as spawn2 } from "child_process";
@@ -5379,14 +5421,44 @@ async function getProviderForRole(db, role) {
   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);
-    const fallback = binding.fallback && providers[binding.fallback] ? materializeProvider(providers[binding.fallback], base, role) : void 0;
+    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 base;
+  return resolved;
 }
-function materializeProvider(rec, base, role) {
+function materializeProvider(rec, base, role, meta) {
   const url = rec.url || base.url;
   return {
     enabled: base.enabled,
@@ -5395,6 +5467,10 @@ function materializeProvider(rec, base, role) {
     apiKey: resolveProviderApiKey(rec),
     apiFlavor: rec.apiFlavor || inferApiFlavor(url),
     locale: base.locale,
+    providerName: meta.providerName,
+    label: rec.label,
+    source: meta.source,
+    local: rec.local ?? isLocalEndpoint(url),
     ...role === "vision" ? { maxFrames: base.maxFrames } : {}
   };
 }
@@ -5413,6 +5489,8 @@ async function getLegacyRoleConfig(db, role, enabled) {
       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
     };
   }
@@ -5422,7 +5500,9 @@ async function getLegacyRoleConfig(db, role, enabled) {
     model: base.model,
     apiKey: base.apiKey,
     apiFlavor: inferApiFlavor(base.url),
-    locale: base.locale
+    locale: base.locale,
+    source: "legacy",
+    local: isLocalEndpoint(base.url)
   };
 }
 function assertChatCompletions(cfg) {
@@ -5672,10 +5752,17 @@ async function isVisionProviderModelExplicit(db, active) {
   const providers = await readJsonSetting(db, "llm.providers");
   const roles = await readJsonSetting(db, "llm.roles");
   const binding = roles?.vision;
-  if (!providers || !binding) return false;
-  return [binding.primary, binding.fallback].some((id) => {
+  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 = providers[id];
+    const rec = machine.providers?.[id];
     return rec?.model === active.model && (rec.url === void 0 || rec.url === active.url);
   });
 }
@@ -5708,6 +5795,87 @@ async function checkVisionReadiness(db) {
     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";
@@ -5806,7 +5974,7 @@ async function startLocalRunner(url, model, locale) {
   let attempts = 0;
   const dotsPerLine = 30;
   while (true) {
-    await new Promise((resolve6) => setTimeout(resolve6, 500));
+    await new Promise((resolve8) => setTimeout(resolve8, 500));
     if (await isLlmOnline(url)) {
       if (attempts > 0) process.stdout.write("\n");
       return true;
@@ -5961,8 +6129,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
   const dotsPerLine = 30;
   while (true) {
     let timeoutId;
-    const timeoutPromise = new Promise((resolve6) => {
-      timeoutId = setTimeout(() => resolve6("timeout"), timeoutMs);
+    const timeoutPromise = new Promise((resolve8) => {
+      timeoutId = setTimeout(() => resolve8("timeout"), timeoutMs);
     });
     const dotsInterval = setInterval(() => {
       process.stdout.write(".");
@@ -6489,11 +6657,338 @@ function jsonOut(data) {
 
 // src/cli/commands/workspace.ts
 import { execFileSync as execFileSync3 } from "child_process";
-import { existsSync as existsSync15, mkdirSync as mkdirSync8, writeFileSync as writeFileSync7 } from "fs";
+import { existsSync as existsSync16, mkdirSync as mkdirSync9, writeFileSync as writeFileSync8 } from "fs";
 import { homedir as homedir9 } from "os";
-import { join as join15 } from "path";
+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 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."
+    );
+  }
+}
+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}`);
+    } else {
+      console.log(`  skip  database already initialized`);
+    }
+  }
+}
+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";
+  }
+  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}`);
+  }
+}
+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, {
@@ -6502,18 +6997,169 @@ function runGit(cwd, args) {
       encoding: "utf8"
     }).trim();
   } catch (err) {
-    throw new Error(`Git command failed: ${err.message}`);
+    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);
   }
-}
-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 Command2("workspace").description(
-  "Manage your ZAM learning workspace"
-);
+});
 workspaceCommand.command("publish").description("Publish your local workspace sandbox to GitHub").action(async () => {
   let db;
   let workspaceDir = "";
@@ -6530,7 +7176,7 @@ workspaceCommand.command("publish").description("Publish your local workspace sa
     );
     process.exit(1);
   }
-  if (!existsSync15(workspaceDir)) {
+  if (!existsSync16(workspaceDir)) {
     console.error(
       `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
     );
@@ -6544,15 +7190,15 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
     );
     process.exit(1);
   }
-  const gitignorePath = join15(workspaceDir, ".gitignore");
-  if (!existsSync15(gitignorePath)) {
-    writeFileSync7(
+  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 = existsSync15(join15(workspaceDir, ".git"));
+  const hasGitRepo = existsSync16(join16(workspaceDir, ".git"));
   if (!hasGitRepo) {
     console.log("Initializing local Git repository...");
     runGit(workspaceDir, ["init", "-b", "main"]);
@@ -6639,15 +7285,15 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
   }
 });
 async function backupDatabaseTo(db, targetDir) {
-  const backupDir = join15(targetDir, "zam-backups");
-  mkdirSync8(backupDir, { recursive: true });
+  const backupDir = join16(targetDir, "zam-backups");
+  mkdirSync9(backupDir, { recursive: true });
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const dest = join15(backupDir, `zam-${stamp}.db`);
+  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 = join15(homedir9(), ".zam");
+  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(
@@ -6667,7 +7313,7 @@ workspaceCommand.command("backup").description("Back up the local ZAM database i
   let db;
   try {
     db = await openDatabase();
-    const workspaceDir = opts.dir || await getSetting(db, "personal.workspace_dir") || join15(homedir9(), "Documents", "zam");
+    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 }));
@@ -6743,7 +7389,7 @@ function parseTokenUpdates(opts) {
   }
   return updates;
 }
-var bridgeCommand = new Command3("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) => {
@@ -6786,7 +7432,7 @@ bridgeCommand.command("backup-db").description("Back up the local database into
     return;
   }
   await withDb2(async (db) => {
-    const workspaceDir = opts.dir || await getSetting(db, "personal.workspace_dir") || join16(homedir10(), "Documents", "zam");
+    const workspaceDir = opts.dir || await getSetting(db, "personal.workspace_dir") || join17(homedir10(), "Documents", "zam");
     const path = await backupDatabaseTo(db, workspaceDir);
     jsonOut2({ ok: true, path });
   });
@@ -6796,20 +7442,135 @@ bridgeCommand.command("workspace-info").description("Report the workspace dir, i
     const workspaceDir = await getSetting(db, "personal.workspace_dir") || null;
     jsonOut2({
       workspaceDir,
-      defaultWorkspaceDir: join16(homedir10(), "Documents", "zam"),
-      dataDir: join16(homedir10(), ".zam")
+      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 = resolve3(raw);
+  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 });
@@ -7168,7 +7929,7 @@ bridgeCommand.command("discover-skills").description(
   "20"
 ).action(async (opts) => {
   try {
-    const monitorDir = join16(homedir10(), ".zam", "monitor");
+    const monitorDir = join17(homedir10(), ".zam", "monitor");
     let files;
     try {
       files = readdirSync2(monitorDir).filter((f) => f.endsWith(".jsonl"));
@@ -7181,7 +7942,7 @@ bridgeCommand.command("discover-skills").description(
       return;
     }
     const limit = Number(opts.limit);
-    const sorted = files.map((f) => ({ name: f, path: join16(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", "");
@@ -7683,7 +8444,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
         return;
       }
     }
-    const outputPath = opts.image ?? opts.output ?? join16(tmpdir3(), `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, {
@@ -7711,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,
@@ -7738,11 +8499,11 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     return;
   }
   const sessionId = opts.session;
-  const statePath = join16(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const statePath = join17(tmpdir3(), `zam-recording-${sessionId}.json`);
   const defaultExt = platform === "win32" ? ".mkv" : ".mov";
-  const outputPath = opts.output ?? join16(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
-  const { existsSync: existsSync24, writeFileSync: writeFileSync12, openSync, closeSync } = await import("fs");
-  if (existsSync24(statePath)) {
+  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,
@@ -7750,7 +8511,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     });
     return;
   }
-  const logPath = join16(tmpdir3(), `zam-recording-${sessionId}.log`);
+  const logPath = join17(tmpdir3(), `zam-recording-${sessionId}.log`);
   let logFd;
   try {
     logFd = openSync(logPath, "w");
@@ -7832,9 +8593,9 @@ bridgeCommand.command("stop-recording").description(
     return;
   }
   const sessionId = opts.session;
-  const statePath = join16(tmpdir3(), `zam-recording-${sessionId}.json`);
-  const { existsSync: existsSync24, readFileSync: readFileSync15, rmSync: rmSync3 } = await import("fs");
-  if (!existsSync24(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,
@@ -7842,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");
@@ -7858,7 +8619,7 @@ bridgeCommand.command("stop-recording").description(
   };
   let attempts = 0;
   while (isProcessRunning(pid) && attempts < 20) {
-    await new Promise((resolve6) => setTimeout(resolve6, 250));
+    await new Promise((resolve8) => setTimeout(resolve8, 250));
     attempts++;
   }
   if (isProcessRunning(pid)) {
@@ -7871,7 +8632,7 @@ bridgeCommand.command("stop-recording").description(
     rmSync3(statePath, { force: true });
   } catch {
   }
-  if (!existsSync24(outputPath)) {
+  if (!existsSync25(outputPath)) {
     jsonOut2({
       sessionId,
       stopped: false,
@@ -7962,6 +8723,16 @@ bridgeCommand.command("check-llm").description("Check if LLM is enabled and onli
     });
   });
 });
+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 () => {
@@ -8274,8 +9045,8 @@ bridgeCommand.command("serve").description("Start the persistent JSON-RPC stdin/
 });
 
 // src/cli/commands/card.ts
-import { Command as Command4 } from "commander";
-var cardCommand = new Command4("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) => {
@@ -8474,8 +9245,8 @@ cardCommand.command("delete").description("Delete one user's card for a token").
 
 // src/cli/commands/connector.ts
 import { input as input2, password } from "@inquirer/prompts";
-import { Command as Command5 } from "commander";
-var connectorCommand = new Command5("connector").description(
+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(
@@ -8618,26 +9389,26 @@ async function setupTurso(urlArg, tokenArg, mode) {
 
 // src/cli/commands/git-sync.ts
 import { execSync as execSync5 } from "child_process";
-import { chmodSync as chmodSync2, existsSync as existsSync16, writeFileSync as writeFileSync8 } from "fs";
-import { join as join17 } from "path";
-import { Command as Command6 } from "commander";
+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 = join17(process.cwd(), ".git");
-  if (!existsSync16(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 = join17(gitDir, "hooks");
-  const hookPath = join17(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 {
-    writeFileSync8(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
+    writeFileSync9(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
     try {
       chmodSync2(hookPath, "755");
     } catch (_e) {
@@ -8650,7 +9421,7 @@ zam git-sync --commit HEAD --quiet
     process.exit(1);
   }
 }
-var gitSyncCommand = new Command6("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;
@@ -8739,10 +9510,10 @@ ZAM Auto-Stale Complete: Scanned ${changedFiles.length} file(s).`
 });
 
 // src/cli/commands/goal.ts
-import { existsSync as existsSync17, mkdirSync as mkdirSync9 } from "fs";
-import { resolve as resolve4 } from "path";
+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 Command7 } from "commander";
+import { Command as Command8 } from "commander";
 async function resolveGoalsDir() {
   let goalsDir;
   let db;
@@ -8753,9 +9524,9 @@ async function resolveGoalsDir() {
   } finally {
     await db?.close();
   }
-  return goalsDir ? resolve4(goalsDir) : resolve4("goals");
+  return goalsDir ? resolve6(goalsDir) : resolve6("goals");
 }
-var goalCommand = new Command7("goal").description(
+var goalCommand = new Command8("goal").description(
   "Manage learning goals (markdown files)"
 );
 goalCommand.command("list").description("List all goals").option(
@@ -8763,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 (!existsSync17(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"
@@ -8864,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 (!existsSync17(goalsDir)) {
-    mkdirSync9(goalsDir, { recursive: true });
+  if (!existsSync19(goalsDir)) {
+    mkdirSync10(goalsDir, { recursive: true });
   }
   let slug = opts.slug;
   let title = opts.title;
@@ -8924,22 +9695,22 @@ goalCommand.command("status <slug> <status>").description("Update a goal's statu
 });
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync18, mkdirSync as mkdirSync10, writeFileSync as writeFileSync9 } from "fs";
+import { existsSync as existsSync20, mkdirSync as mkdirSync11, writeFileSync as writeFileSync10 } from "fs";
 import { homedir as homedir11 } from "os";
-import { join as join18 } from "path";
+import { join as join19 } from "path";
 import { confirm as confirm2, input as input4 } from "@inquirer/prompts";
-import { Command as Command8 } from "commander";
+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) {
-  mkdirSync10(join18(workspaceDir, "beliefs"), { recursive: true });
-  mkdirSync10(join18(workspaceDir, "goals"), { recursive: true });
-  mkdirSync10(join18(workspaceDir, "skills"), { recursive: true });
-  const worldviewFile = join18(workspaceDir, "beliefs", "worldview.md");
-  if (!existsSync18(worldviewFile)) {
-    writeFileSync9(
+  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
 
@@ -8951,9 +9722,9 @@ Here, I declare the core concepts and principles I want to master.
       "utf8"
     );
   }
-  const goalsFile = join18(workspaceDir, "goals", "goals.md");
-  if (!existsSync18(goalsFile)) {
-    writeFileSync9(
+  const goalsFile = join19(workspaceDir, "goals", "goals.md");
+  if (!existsSync20(goalsFile)) {
+    writeFileSync10(
       goalsFile,
       `# Personal Goals
 
@@ -8965,7 +9736,7 @@ Here, I declare the core concepts and principles I want to master.
     );
   }
 }
-var initCommand = new Command8("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"
@@ -8975,7 +9746,7 @@ var initCommand = new Command8("init").description("Launch the guided interactiv
   );
   printLine();
   console.log("\n\x1B[1m[1/5] Setting up Local Workspace Sandbox\x1B[0m");
-  const defaultWorkspace = join18(HOME2, "Documents", "zam");
+  const defaultWorkspace = join19(HOME2, "Documents", "zam");
   const workspacePath = await input4({
     message: "Choose your ZAM workspace directory:",
     default: defaultWorkspace
@@ -9132,7 +9903,7 @@ var initCommand = new Command8("init").description("Launch the guided interactiv
 
 // src/cli/commands/learn.ts
 import { input as input6 } from "@inquirer/prompts";
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 
 // src/cli/learn-format.ts
 var BLOOM_VERBS3 = {
@@ -9470,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 Command9("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;
@@ -9714,8 +10485,8 @@ learnCommand.command("open").description("Open a new terminal window running zam
 });
 
 // src/cli/commands/monitor.ts
-import { Command as Command10 } from "commander";
-var monitorCommand = new Command10("monitor").description(
+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(
@@ -9897,8 +10668,8 @@ monitorCommand.command("open").description("Open a new monitored terminal window
 });
 
 // src/cli/commands/observer.ts
-import { Command as Command11 } from "commander";
-var observerCommand = new Command11("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) {
@@ -9961,8 +10732,8 @@ observerCommand.command("revoke <process>").description("Remove a process from o
 
 // src/cli/commands/profile.ts
 import { homedir as homedir12 } from "os";
-import { dirname as dirname5, join as join19, resolve as resolve5 } from "path";
-import { Command as Command12 } from "commander";
+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",
@@ -9971,7 +10742,7 @@ var C2 = {
   green: "\x1B[32m"
 };
 function defaultPersonalDir() {
-  return join19(homedir12(), "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}`;
@@ -9982,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 Command12("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);
@@ -9992,7 +10763,7 @@ var profileCommand = new Command12("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", resolve5(opts.dir));
+      await setSetting(db, "personal.workspace_dir", resolve7(opts.dir));
     }
     const personalDir = await getSetting(db, "personal.workspace_dir") || defaultPersonalDir();
     await db.close();
@@ -10002,7 +10773,7 @@ var profileCommand = new Command12("profile").description("Show or change this m
       mode: getInstallMode(),
       personalDir,
       syncProvider: detectSyncProvider(personalDir),
-      dataDir: dirname5(dbPath),
+      dataDir: dirname6(dbPath),
       dbPath
     };
     if (opts.json) {
@@ -10019,7 +10790,7 @@ var profileCommand = new Command12("profile").description("Show or change this m
 
 // src/cli/commands/provider.ts
 import { password as password2 } from "@inquirer/prompts";
-import { Command as Command13 } from "commander";
+import { Command as Command14 } from "commander";
 var VALID_API_FLAVORS = [
   "chat-completions",
   "anthropic-messages"
@@ -10031,6 +10802,9 @@ function upsertProviderRecord(providers, name, patch) {
   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) {
@@ -10059,7 +10833,7 @@ function buildProviderListing(providers, hasKey) {
     let keyState;
     if (!rec.apiKeyRef) keyState = "none";
     else keyState = hasKey(rec.apiKeyRef) ? "set" : "missing";
-    return {
+    const row = {
       name,
       url: rec.url,
       model: rec.model,
@@ -10067,6 +10841,10 @@ function buildProviderListing(providers, hasKey) {
       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) {
@@ -10086,19 +10864,53 @@ async function readJson(db, key, fallback) {
 }
 var readProviders = (db) => readJson(db, "llm.providers", {});
 var readRoles = (db) => readJson(db, "llm.roles", {});
-async function writeProviders(db, p) {
+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 writeRoles(db, r) {
+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));
 }
-var providerCommand = new Command13("provider").description(
+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").action(async (opts) => {
-  await withDb(async (db) => {
-    const providers = await readProviders(db);
-    const roles = await readRoles(db);
+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
@@ -10106,11 +10918,23 @@ providerCommand.command("list").description("Show configured providers, role bin
     const orphans = findOrphanKeyRefs(listProviderApiKeyRefs(), providers);
     if (opts.json) {
       console.log(
-        JSON.stringify({ providers: rows, roles, orphans }, null, 2)
+        JSON.stringify(
+          {
+            scope: machine ? "machine" : "shared",
+            providers: rows,
+            roles,
+            orphans
+          },
+          null,
+          2
+        )
       );
       return;
     }
-    console.log("Providers (llm.providers):\n");
+    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>"
@@ -10122,6 +10946,11 @@ providerCommand.command("list").description("Show configured providers, role bin
         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}`);
       }
     }
@@ -10143,7 +10972,10 @@ providerCommand.command("list").description("Show configured providers, role bin
     }
   });
 });
-providerCommand.command("add <name>").description("Add or update a provider record in llm.providers").option("--url <url>", "Endpoint base URL (e.g. https://api.deepseek.com/v1)").option("--model <model>", "Model id (e.g. deepseek-v4-flash)").option(
+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(
@@ -10152,7 +10984,7 @@ providerCommand.command("add <name>").description("Add or update a provider reco
 ).option(
   "--key <value>",
   "Store this API key now (prefer `set-key` to keep it out of shell history)"
-).action(async (name, opts) => {
+).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)) {
@@ -10164,20 +10996,31 @@ providerCommand.command("add <name>").description("Add or update a provider reco
     apiFlavor = opts.flavor;
   }
   const apiKeyRef = opts.keyRef ?? (opts.key ? name : void 0);
-  await withDb(async (db) => {
-    const providers = await readProviders(db);
+  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
+      apiKeyRef,
+      local: opts.local ? true : void 0,
+      runner: opts.runner
     });
-    await writeProviders(db, next);
+    await writeScopedProviders(db, machine, next);
     if (opts.key && apiKeyRef) setProviderApiKey(apiKeyRef, opts.key);
     const rec = next[name];
-    console.log(`Provider "${name}" saved:`);
+    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)`}`
     );
@@ -10201,9 +11044,10 @@ Bind it to a role: zam provider use recall --primary ${name}`
     );
   });
 });
-providerCommand.command("remove <name>").description("Remove a provider record from llm.providers").action(async (name) => {
-  await withDb(async (db) => {
-    const providers = await readProviders(db);
+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
@@ -10212,9 +11056,14 @@ providerCommand.command("remove <name>").description("Remove a provider record f
       console.log(`No such provider: ${name}`);
       return;
     }
-    await writeProviders(db, next);
-    console.log(`Removed provider "${name}".`);
-    const referencing = rolesReferencing(await readRoles(db), name);
+    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>`
@@ -10222,7 +11071,7 @@ providerCommand.command("remove <name>").description("Remove a provider record f
     }
   });
 });
-providerCommand.command("use <role>").description(`Bind providers to a role (${VALID_ROLES.join(" | ")})`).option("--primary <name>", "Primary provider").option("--fallback <name>", "Fallback provider (optional)").action(async (role, opts) => {
+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);
@@ -10231,19 +11080,23 @@ providerCommand.command("use <role>").description(`Bind providers to a role (${V
     console.error("--primary is required.");
     process.exit(1);
   }
-  await withDb(async (db) => {
-    const providers = await readProviders(db);
-    await writeRoles(
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    await writeScopedRoles(
       db,
+      machine,
       bindRoleProviders(
-        await readRoles(db),
+        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}`);
+    console.log(
+      `Role "${role}" \u2192 primary: ${opts.primary}${fb} (${machine ? "machine-local" : "shared"})`
+    );
     for (const [label, ref] of [
       ["primary", opts.primary],
       ["fallback", opts.fallback]
@@ -10285,8 +11138,8 @@ providerCommand.command("clear-key <ref>").description("Remove a stored API key"
 });
 
 // src/cli/commands/review.ts
-import { Command as Command14 } from "commander";
-var reviewCommand = new Command14("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();
@@ -10399,10 +11252,10 @@ ${"\u2550".repeat(50)}`);
 });
 
 // src/cli/commands/session.ts
-import { readFileSync as readFileSync11 } from "fs";
+import { readFileSync as readFileSync12 } from "fs";
 import { input as input7, select as select2 } from "@inquirer/prompts";
-import { Command as Command15 } from "commander";
-var sessionCommand = new Command15("session").description(
+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(
@@ -10591,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}`
@@ -10781,9 +11634,9 @@ sessionCommand.command("end").description("End a session and show summary").requ
 });
 
 // src/cli/commands/settings.ts
-import { existsSync as existsSync19 } from "fs";
-import { Command as Command16 } from "commander";
-var settingsCommand = new Command16("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"]);
@@ -10946,7 +11799,7 @@ settingsCommand.command("repos").description("Show or set Personal, Team, and Or
     console.log("\nValidation:");
     for (const [name, path] of Object.entries(paths)) {
       if (path) {
-        const exists = existsSync19(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"}`
         );
@@ -10957,175 +11810,6 @@ settingsCommand.command("repos").description("Show or set Personal, Team, and Or
   });
 });
 
-// src/cli/commands/setup.ts
-import { copyFileSync as copyFileSync2, existsSync as existsSync20, mkdirSync as mkdirSync11, writeFileSync as writeFileSync10 } from "fs";
-import { basename as basename4, dirname as dirname6, join as join20 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { Command as Command17 } from "commander";
-var packageRoot = [
-  fileURLToPath2(new URL("../..", import.meta.url)),
-  fileURLToPath2(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync20(join20(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
-var SKILL_PAIRS = [
-  {
-    from: join20(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
-    to: join20(".claude", "skills", "zam", "SKILL.md")
-  },
-  {
-    from: join20(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
-    to: join20(".agent", "skills", "zam", "SKILL.md")
-  },
-  {
-    from: join20(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
-    to: join20(".agents", "skills", "zam", "SKILL.md")
-  }
-];
-function copySkills(force, cwd = process.cwd()) {
-  let anyAction = false;
-  for (const { from, to } of SKILL_PAIRS) {
-    const dest = join20(cwd, to);
-    if (!existsSync20(from)) {
-      console.warn(`  warn  source not found, skipping: ${from}`);
-      continue;
-    }
-    if (existsSync20(dest) && !force) {
-      console.log(`  skip  ${to} (already present \xE2\u20AC\u201D use --force to update)`);
-      continue;
-    }
-    mkdirSync11(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}`);
-    } else {
-      console.log(`  skip  database already initialized`);
-    }
-  }
-}
-function writeClaudeMd(skipClaudeMd, cwd = process.cwd()) {
-  if (skipClaudeMd) return;
-  const dest = join20(cwd, "CLAUDE.md");
-  if (existsSync20(dest)) {
-    console.log(`  skip  CLAUDE.md (already present)`);
-    return;
-  }
-  const name = basename4(cwd);
-  writeFileSync10(
-    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 = join20(cwd, "AGENTS.md");
-  if (existsSync20(dest)) {
-    console.log(`  skip  AGENTS.md (already present)`);
-    return;
-  }
-  const name = basename4(cwd);
-  writeFileSync10(
-    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 Command17("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);
-    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/skill.ts
 import { Command as Command18 } from "commander";
 var skillCommand = new Command18("skill").description(
@@ -11213,7 +11897,7 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
 });
 
 // src/cli/commands/snapshot.ts
-import { existsSync as existsSync21, mkdirSync as mkdirSync12, readFileSync as readFileSync12, writeFileSync as writeFileSync11 } from "fs";
+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";
@@ -11246,7 +11930,7 @@ var exportCmd = new Command19("export").description("Write a portable SQL-text s
     }
     const out = opts.out ?? join21(personalDir, "snapshots", defaultOutName());
     const dir = dirname7(out);
-    if (dir && dir !== "." && !existsSync21(dir)) {
+    if (dir && dir !== "." && !existsSync22(dir)) {
       mkdirSync12(dir, { recursive: true });
     }
     writeFileSync11(out, snapshot, "utf-8");
@@ -11263,11 +11947,11 @@ var exportCmd = new Command19("export").description("Write a portable SQL-text s
 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 (!existsSync21(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();
@@ -11285,11 +11969,11 @@ var importCmd = new Command19("import").description("Restore a snapshot into the
 });
 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 (!existsSync21(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}`);
@@ -11629,7 +12313,7 @@ tokenCommand.command("status").description("Show full status of a token for a us
 
 // src/cli/commands/ui.ts
 import { spawn as spawn3, spawnSync } from "child_process";
-import { existsSync as existsSync22 } from "fs";
+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";
@@ -11647,7 +12331,7 @@ function findDesktopDir() {
   for (const start of starts) {
     let dir = start;
     for (let i = 0; i < 10; i++) {
-      if (existsSync22(join22(dir, "desktop", "src-tauri", "tauri.conf.json"))) {
+      if (existsSync23(join22(dir, "desktop", "src-tauri", "tauri.conf.json"))) {
         return join22(dir, "desktop");
       }
       const parent = dirname8(dir);
@@ -11662,15 +12346,15 @@ function findBuiltApp(desktopDir) {
   if (process.platform === "win32") {
     for (const name of ["ZAM.exe", "zam.exe", "zam-desktop.exe"]) {
       const p = join22(releaseDir, name);
-      if (existsSync22(p)) return p;
+      if (existsSync23(p)) return p;
     }
   } else if (process.platform === "darwin") {
     const app = join22(releaseDir, "bundle", "macos", "ZAM.app");
-    if (existsSync22(app)) return app;
+    if (existsSync23(app)) return app;
   } else {
     for (const name of ["zam", "ZAM", "zam-desktop"]) {
       const p = join22(releaseDir, name);
-      if (existsSync22(p)) return p;
+      if (existsSync23(p)) return p;
     }
   }
   return null;
@@ -11681,7 +12365,7 @@ function findInstalledApp() {
     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 && existsSync22(candidate)) || null;
+  return candidates.find((candidate) => candidate && existsSync23(candidate)) || null;
 }
 function runNpm(args, opts) {
   const res = spawnSync("npm", args, {
@@ -11692,7 +12376,7 @@ function runNpm(args, opts) {
   return res.status ?? 1;
 }
 function ensureDesktopDeps(desktopDir) {
-  if (existsSync22(join22(desktopDir, "node_modules"))) return true;
+  if (existsSync23(join22(desktopDir, "node_modules"))) return true;
   console.log(
     `${C3.cyan}Installing desktop dependencies (one-time)...${C3.reset}`
   );
@@ -11724,7 +12408,7 @@ function hasMsvcBuildTools() {
     "Installer",
     "vswhere.exe"
   );
-  if (!existsSync22(vswhere)) return false;
+  if (!existsSync23(vswhere)) return false;
   const res = spawnSync(
     vswhere,
     [
@@ -11756,7 +12440,7 @@ function requireMsvcOnWindows() {
   return false;
 }
 function warnIfCliMissing(repoRoot) {
-  if (!existsSync22(join22(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}`
     );
@@ -11917,7 +12601,7 @@ ${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 existsSync23, readFileSync as readFileSync13, realpathSync } from "fs";
+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 confirm4 } from "@inquirer/prompts";
@@ -11943,7 +12627,7 @@ function currentVersion() {
   for (const up of ["..", "../..", "../../.."]) {
     try {
       const pkg2 = JSON.parse(
-        readFileSync13(join23(here, up, "package.json"), "utf-8")
+        readFileSync14(join23(here, up, "package.json"), "utf-8")
       );
       if (pkg2.version) return pkg2.version;
     } catch {
@@ -11954,7 +12638,7 @@ function currentVersion() {
 function versionAt(dir) {
   try {
     const pkg2 = JSON.parse(
-      readFileSync13(join23(dir, "package.json"), "utf-8")
+      readFileSync14(join23(dir, "package.json"), "utf-8")
     );
     return pkg2.version ?? "unknown";
   } catch {
@@ -12034,11 +12718,11 @@ function findSourceRepo() {
   let dir = realpathSync(dirname9(fileURLToPath4(import.meta.url)));
   let parent = dirname9(dir);
   while (parent !== dir) {
-    if (existsSync23(join23(dir, ".git"))) return dir;
+    if (existsSync24(join23(dir, ".git"))) return dir;
     dir = parent;
     parent = dirname9(dir);
   }
-  return existsSync23(join23(dir, ".git")) ? dir : null;
+  return existsSync24(join23(dir, ".git")) ? dir : null;
 }
 function runGit2(cwd, args, capture) {
   const res = spawnSync2("git", args, {
@@ -12215,7 +12899,7 @@ var whoamiCommand = new Command24("whoami").description("Show or set the default
 // src/cli/index.ts
 var __dirname = dirname10(fileURLToPath5(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync14(join24(__dirname, "..", "..", "package.json"), "utf-8")
+  readFileSync15(join24(__dirname, "..", "..", "package.json"), "utf-8")
 );
 var program = new Command25();
 program.name("zam").description(