zam-core 0.5.1 → 0.5.3

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 
 // src/cli/index.ts
 import { readFileSync as readFileSync15 } from "fs";
-import { dirname as dirname10, join as join24 } from "path";
+import { dirname as dirname10, join as join25 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 import { Command as Command25 } from "commander";
 
@@ -3630,6 +3630,11 @@ function generatePrompt(input8) {
 import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
 import { dirname as dirname3, join as join7, resolve } from "path";
 var DEFAULT_REVIEW_CONTEXT_MAX_CHARS = 6e3;
+var REVIEW_CONTEXT_CACHE_TTL_MS = 5 * 60 * 1e3;
+var reviewContextCache = /* @__PURE__ */ new Map();
+function reviewContextCacheKey(sourceLink, maxChars) {
+  return `${sourceLink}\0${maxChars}`;
+}
 function htmlToText(html) {
   let content = html;
   const bodyMatch = /<body[^>]*>([\s\S]*?)<\/body>/i.exec(html);
@@ -3772,6 +3777,11 @@ async function resolveReviewContext(sourceLink, opts = {}) {
   const cleaned = sourceLink?.trim();
   if (!cleaned) return null;
   const maxChars = opts.maxChars ?? DEFAULT_REVIEW_CONTEXT_MAX_CHARS;
+  const cacheKey = reviewContextCacheKey(cleaned, maxChars);
+  const cached = reviewContextCache.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.context;
+  }
   const resolved = await resolveReference(cleaned);
   let content = resolved.content;
   let truncated = false;
@@ -3779,7 +3789,7 @@ async function resolveReviewContext(sourceLink, opts = {}) {
     content = content.slice(0, maxChars);
     truncated = true;
   }
-  return {
+  const context = {
     sourceLink: cleaned,
     sourceType: resolved.sourceType,
     content,
@@ -3787,6 +3797,11 @@ async function resolveReviewContext(sourceLink, opts = {}) {
     url: resolved.url,
     truncated
   };
+  reviewContextCache.set(cacheKey, {
+    context,
+    expiresAt: Date.now() + REVIEW_CONTEXT_CACHE_TTL_MS
+  });
+  return context;
 }
 function normalizePath(p) {
   const base = p.split("#")[0].trim();
@@ -4463,25 +4478,41 @@ function saveMachineAiConfig(ai, path = defaultConfigPath()) {
 function getConfiguredWorkspaces(path = defaultConfigPath()) {
   return loadInstallConfig(path).workspaces ?? [];
 }
-function saveConfiguredWorkspaces(workspaces, path = defaultConfigPath()) {
+function setActiveWorkspaceId(id, path = defaultConfigPath()) {
   const config = loadInstallConfig(path);
-  config.workspaces = workspaces;
+  if (id) {
+    config.activeWorkspaceId = id;
+  } else {
+    delete config.activeWorkspaceId;
+  }
   saveInstallConfig(config, path);
 }
+function getActiveWorkspace(path = defaultConfigPath()) {
+  const config = loadInstallConfig(path);
+  const id = config.activeWorkspaceId;
+  return id ? config.workspaces?.find((workspace) => workspace.id === id) : void 0;
+}
 function upsertConfiguredWorkspace(workspace, path = defaultConfigPath()) {
-  const current = getConfiguredWorkspaces(path);
+  const config = loadInstallConfig(path);
+  const current = config.workspaces ?? [];
   const next = [
     ...current.filter((candidate) => candidate.id !== workspace.id),
     workspace
   ];
-  saveConfiguredWorkspaces(next, path);
+  config.workspaces = next;
+  saveInstallConfig(config, path);
   return next;
 }
 function removeConfiguredWorkspace(id, path = defaultConfigPath()) {
-  const next = getConfiguredWorkspaces(path).filter(
+  const config = loadInstallConfig(path);
+  const next = (config.workspaces ?? []).filter(
     (workspace) => workspace.id !== id
   );
-  saveConfiguredWorkspaces(next, path);
+  config.workspaces = next;
+  if (config.activeWorkspaceId === id) {
+    config.activeWorkspaceId = next[0]?.id;
+  }
+  saveInstallConfig(config, path);
   return next;
 }
 function detectSyncProvider(dir) {
@@ -4813,7 +4844,7 @@ function getSystemProfile() {
 import { existsSync as existsSync10 } from "fs";
 import { resolve as resolve2 } from "path";
 async function getRepoPaths(db) {
-  const personalSetting = await getSetting(db, "repo.personal") || await getSetting(db, "personal.workspace_dir");
+  const personalSetting = await getSetting(db, "repo.personal") || getActiveWorkspace()?.path;
   const teamSetting = await getSetting(db, "repo.team");
   const orgSetting = await getSetting(db, "repo.org");
   return {
@@ -5357,23 +5388,33 @@ var openCmd = new Command("open").description("Open an agent harness in the work
 var agentCommand = new Command("agent").description("Provision and inspect the agent that drives ZAM sessions").addCommand(installCmd).addCommand(statusCmd).addCommand(openCmd).addCommand(listCmd).action(printStatus);
 
 // src/cli/commands/bridge.ts
-import { execFileSync as execFileSync4 } from "child_process";
+import { execFileSync as execFileSync3 } from "child_process";
 import { randomBytes as randomBytes2 } from "crypto";
-import {
-  existsSync as existsSync17,
-  mkdirSync as mkdirSync10,
-  readdirSync as readdirSync3,
-  readFileSync as readFileSync11,
-  rmSync as rmSync3
-} from "fs";
+import { existsSync as existsSync17, readdirSync as readdirSync2, readFileSync as readFileSync11, rmSync as rmSync3 } from "fs";
 import { homedir as homedir10, tmpdir as tmpdir3 } from "os";
-import { basename as basename5, join as join17, resolve as resolve5 } from "path";
-import { Command as Command4 } from "commander";
+import { join as join18, resolve as resolve4 } from "path";
+import { Command as Command2 } from "commander";
 
 // src/cli/llm/client.ts
 import { spawn as spawn2 } from "child_process";
 import { existsSync as existsSync14 } from "fs";
 var DEFAULT_LLM_URL = "http://localhost:8000/v1";
+var DEFAULT_LLM_MAX_TOKENS = 1e4;
+var RECALL_QUESTION_MAX_OUTPUT_TOKENS = 400;
+var RECALL_EVALUATION_MAX_OUTPUT_TOKENS = 1200;
+var RECALL_ENDPOINT_CACHE_MS = 6e4;
+var cachedRecallEndpoint = null;
+function recallEndpointSignature(cfg) {
+  return [
+    cfg.enabled ? "on" : "off",
+    cfg.providerName ?? "",
+    cfg.url,
+    cfg.model,
+    cfg.apiFlavor,
+    cfg.fallback?.url ?? "",
+    cfg.fallback?.model ?? ""
+  ].join("|");
+}
 var DEFAULT_LLM_MODEL = "qwen3.5:4b";
 var DEFAULT_LLM_API_KEY = "sk-none";
 async function getLlmConfig(db) {
@@ -5388,19 +5429,25 @@ async function getLlmConfig(db) {
 function getCloudModelRecommendation(url) {
   const lowercase = url.toLowerCase();
   if (lowercase.includes("openrouter.ai")) {
-    return "openrouter/free";
+    return { model: "openrouter/free", flavor: "chat-completions" };
   }
   if (lowercase.includes("openai.com") || lowercase.includes("api.openai")) {
-    return "gpt-5-mini";
+    return { model: "gpt-5-mini", flavor: "chat-completions" };
   }
   if (lowercase.includes("googleapis.com") || lowercase.includes("google")) {
-    return "gemini-3.5-flash";
+    return { model: "gemini-3.5-flash", flavor: "chat-completions" };
   }
   if (lowercase.includes("deepseek.com")) {
-    return "deepseek-v4-flash";
+    return { model: "deepseek-v4-flash", flavor: "chat-completions" };
   }
   if (lowercase.includes("mimo")) {
-    return "mimo-v2.5";
+    return { model: "mimo-v2.5", flavor: "chat-completions" };
+  }
+  if (lowercase.includes("anthropic.com")) {
+    return {
+      model: "claude-haiku-4-5-20251001",
+      flavor: "anthropic-messages"
+    };
   }
   return null;
 }
@@ -5484,6 +5531,7 @@ function materializeProvider(rec, base, role, meta) {
     label: rec.label,
     source: meta.source,
     local: rec.local ?? isLocalEndpoint(url),
+    ...rec.runner ? { runner: rec.runner } : {},
     ...role === "vision" ? { maxFrames: base.maxFrames } : {}
   };
 }
@@ -5493,14 +5541,15 @@ async function getLegacyRoleConfig(db, role, enabled) {
     const maxFramesStr = await getSetting(db, "llm.vision.max_frames");
     const parsed = maxFramesStr ? parseInt(maxFramesStr, 10) : 100;
     const url = await getSetting(db, "llm.vision.url") || base.url;
+    const recommendation = getCloudModelRecommendation(url);
     let model = await getSetting(db, "llm.vision.model");
-    if (!model) model = getCloudModelRecommendation(url) || base.model;
+    if (!model) model = recommendation?.model || base.model;
     return {
       enabled,
       url,
       model,
       apiKey: await getSetting(db, "llm.vision.api_key") || base.apiKey,
-      apiFlavor: inferApiFlavor(url),
+      apiFlavor: recommendation?.flavor || inferApiFlavor(url),
       locale: base.locale,
       source: "legacy",
       local: isLocalEndpoint(url),
@@ -5566,10 +5615,7 @@ async function readChatContent(res, label) {
 }
 async function generateQuestionViaLLM(db, input8) {
   const cfg = await getProviderForRole(db, "recall");
-  if (!cfg.enabled) {
-    throw new Error("LLM integration is disabled in settings (llm.enabled)");
-  }
-  assertChatCompletions(cfg);
+  const endpoint = await resolveUsableRecallEndpoint(db);
   const bloom = input8.bloomLevel >= 1 && input8.bloomLevel <= 5 ? input8.bloomLevel : 1;
   const verb = BLOOM_VERBS2[bloom];
   const langName = LANGUAGE_NAMES[cfg.locale] || "English";
@@ -5589,31 +5635,36 @@ ${input8.sourceLinkContent ? `Source Reference:
 ${input8.sourceLinkContent}` : ""}
 
 Active-Recall Question:`;
-  const res = await fetchWithInteractiveTimeout(`${cfg.url}/chat/completions`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${cfg.apiKey}`
-    },
-    body: JSON.stringify({
-      model: cfg.model,
-      messages: [
-        { role: "system", content: systemPrompt },
-        { role: "user", content: userPrompt }
-      ],
-      temperature: 0.1,
-      max_tokens: 150
-    }),
-    locale: cfg.locale
-  });
-  return readChatContent(res, "LLM request");
+  const res = await fetchWithInteractiveTimeout(
+    `${endpoint.url}/chat/completions`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${endpoint.apiKey}`
+      },
+      body: JSON.stringify({
+        model: endpoint.model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt }
+        ],
+        temperature: 0.1,
+        max_tokens: RECALL_QUESTION_MAX_OUTPUT_TOKENS
+      }),
+      locale: cfg.locale
+    }
+  );
+  const text = await readChatContent(res, "LLM request");
+  return {
+    text,
+    model: endpoint.model,
+    providerName: endpoint.providerName
+  };
 }
 async function evaluateAnswerViaLLM(db, input8) {
   const cfg = await getProviderForRole(db, "recall");
-  if (!cfg.enabled) {
-    throw new Error("LLM integration is disabled in settings (llm.enabled)");
-  }
-  assertChatCompletions(cfg);
+  const endpoint = await resolveUsableRecallEndpoint(db);
   const langName = LANGUAGE_NAMES[cfg.locale] || "English";
   const ratingPrefix = LOCALIZED_RATING_PREFIX[cfg.locale] || "Suggested rating";
   const systemPrompt = `You are ZAM, an extremely warm, encouraging, and patient skills trainer.
@@ -5643,51 +5694,59 @@ ${input8.sourceLinkContent ? `Source Code Reference:
 ${input8.sourceLinkContent}` : ""}
 
 Evaluation:`;
-  const res = await fetchWithInteractiveTimeout(`${cfg.url}/chat/completions`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${cfg.apiKey}`
-    },
-    body: JSON.stringify({
-      model: cfg.model,
-      messages: [
-        { role: "system", content: systemPrompt },
-        { role: "user", content: userPrompt }
-      ],
-      temperature: 0.2,
-      max_tokens: 300
-    }),
-    locale: cfg.locale
-  });
-  return readChatContent(res, "LLM evaluation");
+  const res = await fetchWithInteractiveTimeout(
+    `${endpoint.url}/chat/completions`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${endpoint.apiKey}`
+      },
+      body: JSON.stringify({
+        model: endpoint.model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt }
+        ],
+        temperature: 0.2,
+        max_tokens: RECALL_EVALUATION_MAX_OUTPUT_TOKENS
+      }),
+      locale: cfg.locale
+    }
+  );
+  const text = await readChatContent(res, "LLM evaluation");
+  return {
+    text,
+    model: endpoint.model,
+    providerName: endpoint.providerName
+  };
 }
 async function translateQuestionViaLLM(db, question) {
   const cfg = await getProviderForRole(db, "recall");
-  if (!cfg.enabled) {
-    throw new Error("LLM integration is disabled in settings");
-  }
-  assertChatCompletions(cfg);
+  const endpoint = await resolveUsableRecallEndpoint(db);
   const targetLang = LANGUAGE_NAMES[cfg.locale] || "English";
   const systemPrompt = `You are a highly precise translator. Translate the given active-recall question into clear, natural ${targetLang}.
 Output ONLY the raw translation. Do not include any headers, preamble, quotes, or conversational filler.`;
-  const res = await fetchWithInteractiveTimeout(`${cfg.url}/chat/completions`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${cfg.apiKey}`
-    },
-    body: JSON.stringify({
-      model: cfg.model,
-      messages: [
-        { role: "system", content: systemPrompt },
-        { role: "user", content: question }
-      ],
-      temperature: 0.1,
-      max_tokens: 150
-    }),
-    locale: cfg.locale
-  });
+  const res = await fetchWithInteractiveTimeout(
+    `${endpoint.url}/chat/completions`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${endpoint.apiKey}`
+      },
+      body: JSON.stringify({
+        model: endpoint.model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: question }
+        ],
+        temperature: 0.1,
+        max_tokens: DEFAULT_LLM_MAX_TOKENS
+      }),
+      locale: cfg.locale
+    }
+  );
   return readChatContent(res, "Translation");
 }
 async function isLlmOnline(url) {
@@ -5760,6 +5819,107 @@ async function checkProviderChain(primary) {
   }
   return { primary: first };
 }
+async function resolveUsableRecallEndpoint(db) {
+  const cfg = await getProviderForRole(db, "recall");
+  if (!cfg.enabled) {
+    throw new Error("LLM integration is disabled in settings (llm.enabled)");
+  }
+  assertChatCompletions(cfg);
+  const signature = recallEndpointSignature(cfg);
+  if (cachedRecallEndpoint && cachedRecallEndpoint.signature === signature && cachedRecallEndpoint.expiresAt > Date.now()) {
+    return cachedRecallEndpoint.endpoint;
+  }
+  const chain = await checkProviderChain(cfg);
+  const selected = chain.firstUsable;
+  if (!selected || !isEndpointUsable(selected)) {
+    throw new Error("No recall LLM endpoint is online");
+  }
+  cachedRecallEndpoint = {
+    endpoint: selected.endpoint,
+    signature,
+    expiresAt: Date.now() + RECALL_ENDPOINT_CACHE_MS
+  };
+  return selected.endpoint;
+}
+async function prepareRecallChain(db, opts) {
+  const cfg = await getProviderForRole(db, "recall");
+  const fail = (reason, partial = {}) => ({
+    usable: false,
+    reason,
+    online: false,
+    model: cfg.model,
+    availableModels: [],
+    providerName: cfg.providerName,
+    label: cfg.label,
+    local: cfg.local ?? isLocalEndpoint(cfg.url),
+    activeTier: "primary",
+    ...partial
+  });
+  if (!cfg.enabled) return fail("disabled");
+  if (cfg.apiFlavor !== "chat-completions") return fail("unsupported-provider");
+  const chain = providerChain(cfg);
+  const deadline = Date.now() + opts.timeoutMs;
+  let lastReason = "offline";
+  let lastOnline = false;
+  let lastModel = cfg.model;
+  let lastAvailable = [];
+  for (let index = 0; index < chain.length; index++) {
+    const endpoint = chain[index];
+    let online = await isLlmOnline(endpoint.url);
+    if (!online && (endpoint.local ?? isLocalEndpoint(endpoint.url))) {
+      if (opts.interactive) {
+        online = await startLocalRunner(
+          endpoint.url,
+          endpoint.model,
+          cfg.locale,
+          endpoint.runner
+        );
+      } else {
+        spawnLocalRunner(endpoint.url, endpoint.model, endpoint.runner);
+        while (Date.now() < deadline) {
+          await new Promise((resolve10) => setTimeout(resolve10, 1e3));
+          if (await isLlmOnline(endpoint.url)) {
+            online = true;
+            break;
+          }
+        }
+      }
+    }
+    lastOnline = online;
+    lastModel = endpoint.model;
+    if (!online) {
+      lastReason = "offline";
+      continue;
+    }
+    const availableModels = await getAvailableModels(
+      endpoint.url,
+      endpoint.apiKey
+    );
+    lastAvailable = availableModels;
+    const modelKnown = availableModels.length === 0 || availableModels.some(
+      (candidate) => candidate.toLowerCase() === endpoint.model.toLowerCase()
+    );
+    if (!modelKnown) {
+      lastReason = "model-not-found";
+      continue;
+    }
+    return {
+      usable: true,
+      online: true,
+      model: endpoint.model,
+      availableModels,
+      providerName: endpoint.providerName,
+      label: endpoint.label,
+      local: endpoint.local ?? isLocalEndpoint(endpoint.url),
+      activeTier: index === 0 ? "primary" : "fallback"
+    };
+  }
+  return fail(lastReason, {
+    online: lastOnline,
+    model: lastModel,
+    availableModels: lastAvailable
+  });
+}
 async function isVisionProviderModelExplicit(db, active) {
   if (await getSetting(db, "llm.vision.model")) return true;
   const providers = await readJsonSetting(db, "llm.providers");
@@ -5791,7 +5951,7 @@ async function checkVisionReadiness(db) {
   let warning;
   if (cfg.enabled && online && modelAvailable && !visionModelExplicit) {
     const cloudRec = getCloudModelRecommendation(active.url);
-    if (cloudRec && active.model === cloudRec) {
+    if (cloudRec && active.model === cloudRec.model) {
     } else {
       warning = `No explicit vision model configured (llm.vision.model). Falling back to base model "${active.model}", which may not support image input. Set a multimodal model: zam settings set llm.vision.model <model>`;
     }
@@ -5861,13 +6021,8 @@ async function getProviderRoleStatus(db, role) {
       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 chain = await checkProviderChain(cfg);
+  const selected = chain.firstUsable ?? chain.primary;
   const active = selected.endpoint;
   const usable = selected.online && selected.modelAvailable;
   const reason = usable ? void 0 : selected.online ? "model-not-found" : "offline";
@@ -5889,7 +6044,35 @@ async function getProviderRoleStatus(db, role) {
     fallback: summarizeFallback(cfg.fallback)
   };
 }
-function detectRunner(url, model) {
+function runnerKindFromHint(hint) {
+  if (!hint) return void 0;
+  const normalized = hint.trim().toLowerCase();
+  if (normalized === "flm" || normalized === "fastflowlm") {
+    return "fastflowlm";
+  }
+  if (normalized === "ollama") return "ollama";
+  if (normalized === "foundry-local" || normalized === "foundry" || normalized === "generic") {
+    return "generic";
+  }
+  return void 0;
+}
+function defaultPortForRunner(runner, url) {
+  try {
+    const urlObj = new URL(url);
+    const explicit = urlObj.port;
+    if (explicit) return explicit;
+    if (runner === "ollama") return "11434";
+    if (urlObj.protocol === "https:") return "443";
+    return "80";
+  } catch {
+    return runner === "ollama" ? "11434" : "8000";
+  }
+}
+function detectRunner(url, model, hint) {
+  const fromHint = runnerKindFromHint(hint);
+  if (fromHint) {
+    return { runner: fromHint, port: defaultPortForRunner(fromHint, url) };
+  }
   let runner = "unknown";
   let port = "8000";
   try {
@@ -5905,8 +6088,8 @@ function detectRunner(url, model) {
   }
   return { runner, port };
 }
-function spawnLocalRunner(url, model) {
-  const { runner, port } = detectRunner(url, model);
+function spawnLocalRunner(url, model, hint) {
+  const { runner, port } = detectRunner(url, model, hint);
   try {
     if (runner === "fastflowlm") {
       const flmExe = existsSync14("C:\\Program Files\\flm\\flm.exe") ? "C:\\Program Files\\flm\\flm.exe" : "flm";
@@ -5927,8 +6110,8 @@ function spawnLocalRunner(url, model) {
   } catch {
   }
 }
-async function startLocalRunner(url, model, locale) {
-  const { runner, port } = detectRunner(url, model);
+async function startLocalRunner(url, model, locale, hint) {
+  const { runner, port } = detectRunner(url, model, hint);
   if (runner === "fastflowlm") {
     const flmExe = existsSync14("C:\\Program Files\\flm\\flm.exe") ? "C:\\Program Files\\flm\\flm.exe" : "flm";
     if (!hasCommand("flm") && flmExe === "flm") {
@@ -5987,7 +6170,7 @@ async function startLocalRunner(url, model, locale) {
   let attempts = 0;
   const dotsPerLine = 30;
   while (true) {
-    await new Promise((resolve9) => setTimeout(resolve9, 500));
+    await new Promise((resolve10) => setTimeout(resolve10, 500));
     if (await isLlmOnline(url)) {
       if (attempts > 0) process.stdout.write("\n");
       return true;
@@ -6012,105 +6195,39 @@ async function startLocalRunner(url, model, locale) {
   }
 }
 async function ensureLocalLlmRunning(db) {
-  const cfg = await getProviderForRole(db, "recall");
-  if (!cfg.enabled) {
-    return { usable: false, reason: "disabled" };
-  }
-  if (cfg.apiFlavor !== "chat-completions") {
-    console.warn(
-      `\x1B[31m\u2717 Recall is configured for "${cfg.apiFlavor}", but active recall currently supports chat-completions providers only.\x1B[0m`
-    );
-    return { usable: false, reason: "unsupported-provider" };
-  }
-  const { url, model, apiKey, locale } = cfg;
-  const isLocal = isLocalEndpoint(url);
-  console.log(`Checking if local LLM server is online at ${url}...`);
-  let online = await isLlmOnline(url);
-  if (!online && isLocal) {
-    console.log(`\x1B[33m\u26A0 Local LLM server is offline on ${url}.\x1B[0m`);
-    online = await startLocalRunner(url, model, locale);
-  }
-  if (!online) {
-    console.warn(
-      `\x1B[33m\u26A0 LLM server is not reachable at ${url}. Continuing without AI coaching.\x1B[0m
-`
+  const result = await prepareRecallChain(db, {
+    timeoutMs: 25e3,
+    interactive: true
+  });
+  if (result.usable) {
+    const location = result.local ? "local" : "cloud";
+    console.log(
+      `\x1B[32m\u2713 Recall LLM ready (${location}: ${result.model}).\x1B[0m`
     );
-    return { usable: false, reason: "offline" };
+    return { usable: true };
   }
-  console.log("\x1B[32m\u2713 Local LLM server is online.\x1B[0m");
-  const available = await getAvailableModels(url, apiKey);
-  const modelKnown = available.length === 0 || available.some((m) => m.toLowerCase() === model.toLowerCase());
-  if (!modelKnown) {
+  if (result.reason === "unsupported-provider") {
     console.warn(
-      `\x1B[31m\u2717 Configured model "${model}" is not available on the server.\x1B[0m`
+      `\x1B[31m\u2717 Recall provider is not supported for active recall.\x1B[0m`
     );
-    console.warn(`  Available models: ${available.join(", ")}`);
+  } else if (result.reason === "model-not-found") {
     console.warn(
-      `  Set the right one: \x1B[36mzam settings set llm.model <name>\x1B[0m`
+      `\x1B[31m\u2717 Configured model "${result.model}" is not available on the server.\x1B[0m`
     );
+    console.warn(`  Available models: ${result.availableModels.join(", ")}`);
+  } else if (result.reason === "offline") {
     console.warn(
-      "\x1B[33m  Continuing this session without AI coaching.\x1B[0m\n"
+      `\x1B[33m\u26A0 No recall LLM endpoint is reachable. Continuing without AI coaching.\x1B[0m
+`
     );
-    return { usable: false, reason: "model-not-found" };
   }
-  return { usable: true };
+  return { usable: false, reason: result.reason };
 }
 async function ensureLlmReadyHeadless(db, opts = {}) {
-  const timeoutMs = opts.timeoutMs ?? 25e3;
-  const cfg = await getProviderForRole(db, "recall");
-  const { url, model, apiKey } = cfg;
-  if (!cfg.enabled) {
-    return {
-      usable: false,
-      reason: "disabled",
-      online: false,
-      model,
-      availableModels: []
-    };
-  }
-  if (cfg.apiFlavor !== "chat-completions") {
-    return {
-      usable: false,
-      reason: "unsupported-provider",
-      online: false,
-      model,
-      availableModels: []
-    };
-  }
-  const isLocal = isLocalEndpoint(url);
-  let online = await isLlmOnline(url);
-  if (!online && isLocal) {
-    spawnLocalRunner(url, model);
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-      await new Promise((r) => setTimeout(r, 1e3));
-      if (await isLlmOnline(url)) {
-        online = true;
-        break;
-      }
-    }
-  }
-  if (!online) {
-    return {
-      usable: false,
-      reason: "offline",
-      online: false,
-      model,
-      availableModels: []
-    };
-  }
-  const availableModels = await getAvailableModels(url, apiKey);
-  const modelKnown = availableModels.length === 0 || availableModels.some((m) => m.toLowerCase() === model.toLowerCase());
-  if (!modelKnown) {
-    return {
-      usable: false,
-      reason: "model-not-found",
-      online: true,
-      model,
-      availableModels
-    };
-  }
-  return { usable: true, online: true, model, availableModels };
+  return prepareRecallChain(db, {
+    timeoutMs: opts.timeoutMs ?? 25e3,
+    interactive: false
+  });
 }
 async function fetchWithInteractiveTimeout(url, options = {}) {
   const {
@@ -6142,8 +6259,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
   const dotsPerLine = 30;
   while (true) {
     let timeoutId;
-    const timeoutPromise = new Promise((resolve9) => {
-      timeoutId = setTimeout(() => resolve9("timeout"), timeoutMs);
+    const timeoutPromise = new Promise((resolve10) => {
+      timeoutId = setTimeout(() => resolve10("timeout"), timeoutMs);
     });
     const dotsInterval = setInterval(() => {
       process.stdout.write(".");
@@ -6200,15 +6317,22 @@ async function ensureHighQualityQuestion(db, token) {
         bloomLevel: token.bloomLevel,
         sourceLinkContent
       });
-      if (generated && generated.trim().length > 0) {
-        await updateToken(db, token.slug, { question: generated });
-        return generated;
+      if (generated.text.trim().length > 0) {
+        await updateToken(db, token.slug, { question: generated.text });
+        return {
+          question: generated.text,
+          source: "llm",
+          model: generated.model
+        };
       }
     } catch {
     }
   }
   if (token.question && token.question.trim().length > 0) {
-    return token.question;
+    return {
+      question: token.question.trim(),
+      source: "original"
+    };
   }
   return null;
 }
@@ -6253,7 +6377,7 @@ async function observeUiSnapshotViaLLM(db, input8) {
   const imageUrls = [];
   const isVideo = /\.(mp4|mov|m4v|avi|mkv|webm)$/i.test(input8.imagePath);
   if (isVideo) {
-    const { mkdirSync: mkdirSync14, readdirSync: readdirSync4, rmSync: rmSync4 } = await import("fs");
+    const { mkdirSync: mkdirSync14, readdirSync: readdirSync3, rmSync: rmSync4 } = await import("fs");
     const { execSync: execSync6 } = await import("child_process");
     const tempDir = join14(
       tmpdir2(),
@@ -6265,13 +6389,13 @@ async function observeUiSnapshotViaLLM(db, input8) {
         `ffmpeg -i "${input8.imagePath}" -vf "fps=1/3,scale=1280:-1" -vsync vfr "${tempDir}/frame_%03d.png"`,
         { stdio: "ignore" }
       );
-      let files = readdirSync4(tempDir).filter((f) => f.endsWith(".png")).sort();
+      let files = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
       if (files.length === 0) {
         execSync6(
           `ffmpeg -i "${input8.imagePath}" -vframes 1 "${tempDir}/frame_001.png"`,
           { stdio: "ignore" }
         );
-        files = readdirSync4(tempDir).filter((f) => f.endsWith(".png")).sort();
+        files = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
       }
       const maxFrames = cfg.maxFrames ?? 100;
       let sampledFiles = files;
@@ -6416,7 +6540,7 @@ async function requestChatCompletionsVisionDraft(args) {
           }
         ],
         temperature: 0,
-        max_tokens: args.input.maxTokens ?? 450,
+        max_tokens: args.input.maxTokens ?? DEFAULT_LLM_MAX_TOKENS,
         ...args.url.includes("11434") || args.url.includes("localhost") || args.url.includes("127.0.0.1") ? { options: { num_ctx: 32768 } } : {}
       }),
       locale: args.locale,
@@ -6472,7 +6596,7 @@ async function requestAnthropicVisionDraft(args) {
     },
     body: JSON.stringify({
       model: args.model,
-      max_tokens: args.input.maxTokens ?? 450,
+      max_tokens: args.input.maxTokens ?? DEFAULT_LLM_MAX_TOKENS,
       system: VISION_SYSTEM_PROMPT,
       messages: [
         {
@@ -6627,54 +6751,165 @@ function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-// src/cli/commands/resolve-user.ts
-async function ensureDefaultUser(db, preferredUserId) {
-  const stored = await getSetting(db, "user.id");
-  if (stored) return stored;
-  const userId = preferredUserId?.trim() || process.env.ZAM_USER?.trim() || process.env.USERNAME?.trim() || process.env.USER?.trim() || "default";
-  await setSetting(db, "user.id", userId);
-  return userId;
+// src/cli/commands/shared/db.ts
+function defaultErrorHandler(message) {
+  console.error("Error:", message);
+  process.exit(1);
 }
-async function resolveUser(opts, db, resolveOpts) {
-  if (opts.user) return opts.user;
-  const stored = await getSetting(db, "user.id");
-  if (stored) return stored;
-  const message = "No user specified. Set a default with: zam whoami --set <id>";
-  if (resolveOpts?.json) {
-    console.log(JSON.stringify({ error: message }, null, 2));
-  } else {
-    console.error(message);
+async function withDb(fn, onError = defaultErrorHandler) {
+  let db;
+  try {
+    db = await openDatabase();
+    await fn(db);
+  } catch (err) {
+    onError(err.message);
+  } finally {
+    await db?.close();
   }
-  process.exit(1);
+}
+function jsonOut(data) {
+  console.log(JSON.stringify(data, null, 2));
 }
 
-// src/cli/commands/setup.ts
-import {
-  existsSync as existsSync15,
-  lstatSync,
-  mkdirSync as mkdirSync8,
-  readdirSync as readdirSync2,
-  readFileSync as readFileSync10,
-  realpathSync,
-  rmSync as rmSync2,
-  symlinkSync,
-  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", "copilot"]
-  },
-  {
+// src/cli/providers/config.ts
+var VALID_API_FLAVORS = [
+  "chat-completions",
+  "anthropic-messages"
+];
+var VALID_ROLES = ["vision", "recall", "text"];
+function upsertProviderRecord(providers, name, patch) {
+  const merged = { ...providers[name] ?? {} };
+  if (patch.url !== void 0) merged.url = patch.url;
+  if (patch.model !== void 0) merged.model = patch.model;
+  if (patch.apiFlavor !== void 0) merged.apiFlavor = patch.apiFlavor;
+  if (patch.apiKeyRef !== void 0) merged.apiKeyRef = patch.apiKeyRef;
+  if (patch.label !== void 0) merged.label = patch.label;
+  if (patch.local !== void 0) merged.local = patch.local;
+  if (patch.runner !== void 0) merged.runner = patch.runner;
+  return { ...providers, [name]: merged };
+}
+function removeProviderRecord(providers, name) {
+  if (!(name in providers)) return { providers, removed: false };
+  const next = { ...providers };
+  delete next[name];
+  return { providers: next, removed: true };
+}
+function rolesReferencing(roles, name) {
+  return VALID_ROLES.filter((role) => {
+    const binding = roles[role];
+    return binding?.primary === name || binding?.fallback === name;
+  });
+}
+function bindRoleProviders(roles, role, primary, fallback) {
+  const binding = { primary };
+  if (fallback) binding.fallback = fallback;
+  return { ...roles, [role]: binding };
+}
+function maskSecret(key) {
+  return key.length <= 4 ? "\u2022\u2022\u2022\u2022" : `\u2026${key.slice(-4)}`;
+}
+function buildProviderListing(providers, hasKey) {
+  return Object.entries(providers).map(([name, rec]) => {
+    const apiFlavor = rec.apiFlavor ?? (rec.url ? inferApiFlavor(rec.url) : "chat-completions");
+    let keyState;
+    if (!rec.apiKeyRef) keyState = "none";
+    else keyState = hasKey(rec.apiKeyRef) ? "set" : "missing";
+    const row = {
+      name,
+      url: rec.url,
+      model: rec.model,
+      apiFlavor,
+      apiKeyRef: rec.apiKeyRef,
+      keyState
+    };
+    if (rec.label !== void 0) row.label = rec.label;
+    if (rec.local !== void 0) row.local = rec.local;
+    if (rec.runner !== void 0) row.runner = rec.runner;
+    return row;
+  });
+}
+function findOrphanKeyRefs(storedRefs, providers) {
+  const used = new Set(
+    Object.values(providers).map((rec) => rec.apiKeyRef).filter((ref) => !!ref)
+  );
+  return storedRefs.filter((ref) => !used.has(ref));
+}
+async function readJson(db, key, fallback) {
+  const raw = await getSetting(db, key);
+  if (!raw) return fallback;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+var readProviders = (db) => readJson(db, "llm.providers", {});
+var readRoles = (db) => readJson(db, "llm.roles", {});
+async function readScopedProviders(db, machine) {
+  if (machine) return getMachineAiConfig().providers ?? {};
+  if (!db)
+    throw new Error("Database is required for shared provider settings.");
+  return readProviders(db);
+}
+async function readScopedRoles(db, machine) {
+  if (machine) return getMachineAiConfig().roles ?? {};
+  if (!db)
+    throw new Error("Database is required for shared provider settings.");
+  return readRoles(db);
+}
+async function writeScopedProviders(db, machine, p) {
+  if (machine) {
+    const config = getMachineAiConfig();
+    saveMachineAiConfig({ ...config, providers: p });
+    return;
+  }
+  if (!db)
+    throw new Error("Database is required for shared provider settings.");
+  await setSetting(db, "llm.providers", JSON.stringify(p));
+}
+async function writeScopedRoles(db, machine, r) {
+  if (machine) {
+    const config = getMachineAiConfig();
+    saveMachineAiConfig({ ...config, roles: r });
+    return;
+  }
+  if (!db)
+    throw new Error("Database is required for shared provider settings.");
+  await setSetting(db, "llm.roles", JSON.stringify(r));
+}
+async function withProviderScope(machine, action) {
+  if (machine) {
+    await action(void 0);
+    return;
+  }
+  await withDb(action);
+}
+
+// src/cli/provisioning/index.ts
+import {
+  existsSync as existsSync15,
+  lstatSync,
+  mkdirSync as mkdirSync8,
+  readFileSync as readFileSync10,
+  realpathSync,
+  rmSync as rmSync2,
+  symlinkSync,
+  writeFileSync as writeFileSync7
+} from "fs";
+import { basename as basename4, dirname as dirname5, join as join15 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+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", "copilot"]
+  },
+  {
     from: join15(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
     to: join15(".agent", "skills", "zam", "SKILL.md"),
     agents: ["agent"]
@@ -6717,6 +6952,13 @@ function pathExists(path) {
     return false;
   }
 }
+function isSymbolicLink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
 function comparableRealPath(path) {
   const real = realpathSync(path);
   return process.platform === "win32" ? real.toLowerCase() : real;
@@ -6729,24 +6971,29 @@ function pathsResolveToSameDirectory(sourceDir, destinationDir) {
   }
 }
 function linkPointsTo(sourceDir, destinationDir) {
-  try {
-    return lstatSync(destinationDir).isSymbolicLink() && pathsResolveToSameDirectory(sourceDir, destinationDir);
-  } catch {
-    return false;
-  }
+  return isSymbolicLink(destinationDir) && pathsResolveToSameDirectory(sourceDir, destinationDir);
 }
-function isReplaceableCopiedSkill(destinationDir) {
+function isZamSkillCopy(destinationDir) {
   try {
     if (!lstatSync(destinationDir).isDirectory()) return false;
-    const entries = readdirSync2(destinationDir);
-    if (entries.length !== 1 || entries[0] !== "SKILL.md") return false;
-    return /^name:\s*zam\s*$/m.test(
-      readFileSync10(join15(destinationDir, "SKILL.md"), "utf8")
-    );
+    const skillFile = join15(destinationDir, "SKILL.md");
+    if (!existsSync15(skillFile)) return false;
+    return /^name:\s*zam\s*$/m.test(readFileSync10(skillFile, "utf8"));
   } catch {
     return false;
   }
 }
+function classifySkillDestination(sourceDir, destinationDir) {
+  if (!existsSync15(sourceDir)) return "source-missing";
+  if (!isSymbolicLink(destinationDir) && pathsResolveToSameDirectory(sourceDir, destinationDir)) {
+    return "source-directory";
+  }
+  if (linkPointsTo(sourceDir, destinationDir)) return "linked";
+  if (!pathExists(destinationDir)) return "missing";
+  if (isSymbolicLink(destinationDir)) return "broken";
+  if (isZamSkillCopy(destinationDir)) return "stale-copy";
+  return "unmanaged";
+}
 function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {}) {
   const results = [];
   const log = (message) => {
@@ -6756,7 +7003,9 @@ function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {})
     if (!pairAgents.some((agent) => agents.has(agent))) continue;
     const sourceDir = dirname5(from);
     const destinationDir = dirname5(join15(cwd, to));
-    if (!existsSync15(sourceDir)) {
+    const label = dirname5(to);
+    const state = classifySkillDestination(sourceDir, destinationDir);
+    if (state === "source-missing") {
       if (!opts.quiet) {
         console.warn(`  warn  source not found, skipping: ${sourceDir}`);
       }
@@ -6768,8 +7017,8 @@ function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {})
       });
       continue;
     }
-    if (pathsResolveToSameDirectory(sourceDir, destinationDir) && !lstatSync(destinationDir).isSymbolicLink()) {
-      log(`  skip  ${dirname5(to)} (package source)`);
+    if (state === "source-directory") {
+      log(`  skip  ${label} (package source)`);
       results.push({
         source: sourceDir,
         destination: destinationDir,
@@ -6778,8 +7027,8 @@ function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {})
       });
       continue;
     }
-    if (linkPointsTo(sourceDir, destinationDir)) {
-      log(`  skip  ${dirname5(to)} (already linked)`);
+    if (state === "linked") {
+      log(`  skip  ${label} (already linked)`);
       results.push({
         source: sourceDir,
         destination: destinationDir,
@@ -6788,12 +7037,12 @@ function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {})
       });
       continue;
     }
-    const destinationExists = pathExists(destinationDir);
-    const replaceExisting = destinationExists && (Boolean(opts.force) || isReplaceableCopiedSkill(destinationDir));
+    const destinationExists = state !== "missing";
+    const replaceExisting = destinationExists && (Boolean(opts.force) || state === "broken" || state === "stale-copy");
     if (destinationExists && !replaceExisting) {
       if (!opts.quiet) {
         console.warn(
-          `  warn  ${dirname5(to)} already exists and is not managed by ZAM; use --force to replace it`
+          `  warn  ${label} already exists and is not managed by ZAM; use --force to replace it`
         );
       }
       results.push({
@@ -6806,7 +7055,7 @@ function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {})
     }
     const action = destinationExists ? "relinked" : "linked";
     if (opts.dryRun) {
-      log(`  would ${action === "linked" ? "link" : "relink"}  ${dirname5(to)}`);
+      log(`  would ${action === "linked" ? "link" : "relink"}  ${label}`);
     } else {
       if (destinationExists) {
         rmSync2(destinationDir, { recursive: true, force: true });
@@ -6817,39 +7066,36 @@ function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {})
         destinationDir,
         process.platform === "win32" ? "junction" : "dir"
       );
-      log(`  ${action === "linked" ? "link" : "relink"}  ${dirname5(to)}`);
+      log(`  ${action === "linked" ? "link" : "relink"}  ${label}`);
     }
     results.push({ source: sourceDir, destination: destinationDir, action });
   }
   return results;
 }
-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}`;
+function inspectSkillLinks(cwd = process.cwd(), agents = parseSetupAgents()) {
+  const results = [];
+  for (const { from, to, agents: pairAgents } of SKILL_PAIRS) {
+    if (!pairAgents.some((agent) => agents.has(agent))) continue;
+    const sourceDir = dirname5(from);
+    const destinationDir = dirname5(join15(cwd, to));
+    results.push({
+      agents: pairAgents,
+      source: sourceDir,
+      destination: destinationDir,
+      state: classifySkillDestination(sourceDir, destinationDir)
+    });
   }
+  return results;
 }
-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 summarizeSkillLinkHealth(inspections) {
+  if (inspections.some((item) => item.state === "unmanaged")) {
+    return "unmanaged";
   }
+  const repairable = ["missing", "broken", "stale-copy"];
+  if (inspections.some((item) => repairable.includes(item.state))) {
+    return "needs-repair";
+  }
+  return "healthy";
 }
 var ZAM_BLOCK_START = "<!-- ZAM:START -->";
 var ZAM_BLOCK_END = "<!-- ZAM:END -->";
@@ -6906,10 +7152,10 @@ ZAM is available in this repository. Use the \`zam\` skill in Claude Code to tur
     return;
   }
   const name = basename4(cwd);
-  const content = `# ZAM Personal Kernel \xE2\u20AC\u201D ${name}
+  const content = `# ZAM Personal Kernel \u2014 ${name}
 
 This is a ZAM personal instance. ZAM builds lasting skills through spaced
-repetition during real work \xE2\u20AC\u201D not separate study sessions.
+repetition during real work \u2014 not separate study sessions.
 
 ## First time here?
 Run \`/setup\` in Claude Code or Gemini CLI to complete first-time setup.
@@ -6918,8 +7164,8 @@ Run \`/setup\` in Claude Code or Gemini CLI to complete first-time setup.
 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
+- \`beliefs/\` \u2014 your worldview, approved by git commit
+- \`goals/\` \u2014 your objectives, decomposed into tasks and learning tokens
 
 ## Fast-changing data
 Learning tokens, cards, and review history live in local SQLite by default.
@@ -7008,605 +7254,356 @@ ZAM is available in this repository through \`.claude/skills/zam/\`. Use the \`z
     Boolean(opts.dryRun)
   );
 }
-var setupCommand = new Command2("setup").description(
-  "Link ZAM skill directories into this workspace and initialize the database"
-).option("--force", "replace an unmanaged existing ZAM skill directory", 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)" : ""}
-`
-    );
-    wireSkills(target, agents, {
-      force: opts.force,
-      dryRun: opts.dryRun
-    });
-    await initDatabase(opts.skipInit || opts.dryRun);
-    if (agents.has("claude")) {
-      writeClaudeMd(opts.skipClaudeMd, target, {
-        dryRun: opts.dryRun,
-        updateExisting: updateExistingInstructions
-      });
-    }
-    if (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/Copilot/Gemini-compatible clients or `$zam` (or `/skills`) in Codex."
-    );
-  }
-);
 
-// src/cli/commands/shared/db.ts
-function defaultErrorHandler(message) {
-  console.error("Error:", message);
+// src/cli/users/identity.ts
+async function ensureDefaultUser(db, preferredUserId) {
+  const stored = await getSetting(db, "user.id");
+  if (stored) return stored;
+  const userId = preferredUserId?.trim() || process.env.ZAM_USER?.trim() || process.env.USERNAME?.trim() || process.env.USER?.trim() || "default";
+  await setSetting(db, "user.id", userId);
+  return userId;
+}
+async function resolveUser(opts, db, resolveOpts) {
+  if (opts.user) return opts.user;
+  const stored = await getSetting(db, "user.id");
+  if (stored) return stored;
+  const message = "No user specified. Set a default with: zam whoami --set <id>";
+  if (resolveOpts?.json) {
+    console.log(JSON.stringify({ error: message }, null, 2));
+  } else {
+    console.error(message);
+  }
   process.exit(1);
 }
-async function withDb(fn, onError = defaultErrorHandler) {
-  let db;
-  try {
-    db = await openDatabase();
-    await fn(db);
-  } catch (err) {
-    onError(err.message);
-  } finally {
-    await db?.close();
+
+// src/cli/workspaces/active.ts
+import { existsSync as existsSync16, mkdirSync as mkdirSync9 } from "fs";
+import { homedir as homedir9 } from "os";
+import { basename as basename5, join as join16, resolve as resolve3 } from "path";
+var LEGACY_WORKSPACE_DIR_KEY = "personal.workspace_dir";
+var DEFAULT_WORKSPACE_ID = "personal";
+function defaultWorkspaceDir() {
+  return join16(homedir9(), "Documents", "zam");
+}
+function normalizeWorkspacePath(path) {
+  const resolved = resolve3(path);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function sameWorkspacePath(left, right) {
+  return normalizeWorkspacePath(left) === normalizeWorkspacePath(right);
+}
+function labelFromPath(path) {
+  return basename5(path) || "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 findWorkspaceByPath(dir) {
+  return getConfiguredWorkspaces().find(
+    (workspace) => sameWorkspacePath(workspace.path, dir)
+  );
+}
+async function clearLegacyWorkspaceDir(db) {
+  await deleteSetting(db, LEGACY_WORKSPACE_DIR_KEY);
+}
+async function migrateLegacyWorkspaceDir(db) {
+  const legacyDir = await getSetting(db, LEGACY_WORKSPACE_DIR_KEY);
+  if (!legacyDir) return void 0;
+  const path = resolve3(legacyDir);
+  const existing = findWorkspaceByPath(path);
+  const migrated = existing ?? {
+    id: getConfiguredWorkspaces().some(
+      (workspace) => workspace.id === DEFAULT_WORKSPACE_ID
+    ) ? workspaceIdFromPath(path) : DEFAULT_WORKSPACE_ID,
+    label: labelFromPath(path),
+    kind: "personal",
+    path
+  };
+  if (!existing) {
+    upsertConfiguredWorkspace(migrated);
+  }
+  if (!getActiveWorkspace()) {
+    setActiveWorkspaceId(migrated.id);
   }
+  await clearLegacyWorkspaceDir(db);
+  return migrated;
 }
-function jsonOut(data) {
-  console.log(JSON.stringify(data, null, 2));
+async function ensureActiveWorkspace(db) {
+  await migrateLegacyWorkspaceDir(db);
+  const active = getActiveWorkspace();
+  if (active) {
+    mkdirSync9(active.path, { recursive: true });
+    return active;
+  }
+  const configured = getConfiguredWorkspaces()[0];
+  if (configured) {
+    setActiveWorkspaceId(configured.id);
+    mkdirSync9(configured.path, { recursive: true });
+    return configured;
+  }
+  const workspace = {
+    id: DEFAULT_WORKSPACE_ID,
+    label: "Personal",
+    kind: "personal",
+    path: defaultWorkspaceDir()
+  };
+  mkdirSync9(workspace.path, { recursive: true });
+  upsertConfiguredWorkspace(workspace);
+  setActiveWorkspaceId(workspace.id);
+  await clearLegacyWorkspaceDir(db);
+  return workspace;
 }
-
-// src/cli/commands/workspace.ts
-import { execFileSync as execFileSync3 } from "child_process";
-import { existsSync as existsSync16, mkdirSync as mkdirSync9, writeFileSync as writeFileSync8 } from "fs";
-import { homedir as homedir9 } from "os";
-import { join as join16, resolve as resolve4 } from "path";
-import { confirm, input } from "@inquirer/prompts";
-import { Command as Command3 } from "commander";
-function runGit(cwd, args) {
-  try {
-    return execFileSync3("git", args, {
-      cwd,
-      stdio: "pipe",
-      encoding: "utf8"
-    }).trim();
-  } catch (err) {
-    throw new Error(`Git command failed: ${err.message}`);
+async function activateWorkspace(db, workspace) {
+  upsertConfiguredWorkspace(workspace);
+  setActiveWorkspaceId(workspace.id);
+  await clearLegacyWorkspaceDir(db);
+  return workspace;
+}
+async function activateWorkspacePath(db, dir, opts = {}) {
+  await migrateLegacyWorkspaceDir(db);
+  const path = resolve3(dir);
+  const existing = opts.id ? void 0 : findWorkspaceByPath(path);
+  if (existing) {
+    setActiveWorkspaceId(existing.id);
+    await clearLegacyWorkspaceDir(db);
+    return existing;
   }
+  const workspace = {
+    id: opts.id || workspaceIdFromPath(path),
+    label: opts.label || labelFromPath(path),
+    kind: opts.kind || "personal",
+    path
+  };
+  return activateWorkspace(db, workspace);
 }
-function ghRepoCreateArgs(repoName, repoVisibility) {
-  return ["repo", "create", repoName, repoVisibility, "--source=.", "--push"];
+async function removeWorkspaceAndResolveActive(db, id) {
+  removeConfiguredWorkspace(id);
+  await clearLegacyWorkspaceDir(db);
+  const activeWorkspace = await ensureActiveWorkspace(db);
+  return {
+    activeWorkspace,
+    workspaces: getConfiguredWorkspaces()
+  };
 }
-function gitRemoteArgs(githubUrl, hasOrigin) {
-  return hasOrigin ? ["remote", "set-url", "origin", githubUrl] : ["remote", "add", "origin", githubUrl];
+function existingWorkspaceDirOrHome(workspace) {
+  return existsSync16(workspace.path) ? workspace.path : homedir9();
 }
-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;
+
+// src/cli/workspaces/backup.ts
+import { mkdirSync as mkdirSync10 } from "fs";
+import { join as join17 } from "path";
+async function backupDatabaseTo(db, targetDir) {
+  const backupDir = join17(targetDir, "zam-backups");
+  mkdirSync10(backupDir, { recursive: true });
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const dest = join17(backupDir, `zam-${stamp}.db`);
+  await db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
+  return dest;
+}
+
+// src/cli/commands/bridge.ts
+var isServeMode = false;
+function jsonOut2(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function jsonError(message) {
+  if (isServeMode) {
+    throw new Error(JSON.stringify({ error: message }));
   }
-  throw new Error(
-    `Invalid workspace kind: ${value}. Use ${WORKSPACE_KINDS.join(", ")}.`
-  );
+  console.log(JSON.stringify({ error: message }, null, 2));
+  process.exit(1);
 }
-function parseWorkspaceSourceControl(value) {
-  if (!value) return void 0;
-  const source = value.toLowerCase();
-  if (WORKSPACE_SOURCE_CONTROLS.includes(source)) {
-    return source;
+function parseNonNegativeIntegerOption(name, value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    jsonError(`${name} must be a non-negative integer`);
   }
-  throw new Error(
-    `Invalid source control: ${value}. Use ${WORKSPACE_SOURCE_CONTROLS.join(", ")}.`
-  );
+  return parsed;
 }
-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 parseProviderScope(scope) {
+  const value = scope ?? "machine";
+  if (value === "machine") return true;
+  if (value === "shared") return false;
+  jsonError(`Invalid --scope: ${value}. Use machine or shared.`);
 }
-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;
+async function withDb2(fn) {
+  await withDb(fn, jsonError);
 }
-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;
+async function getReviewTarget2(db, cardId, userId) {
+  const target = await db.prepare(
+    `SELECT c.id AS card_id, c.token_id, c.user_id, t.slug
+       FROM cards c
+       JOIN tokens t ON t.id = c.token_id
+       WHERE c.id = ?`
+  ).get(cardId);
+  if (!target) {
+    jsonError(`Card not found: ${cardId}`);
   }
-  console.log("Configured ZAM workspaces:\n");
-  if (workspaces.length === 0) {
-    console.log(
-      "  (none) \u2014 add one: zam workspace add personal --path <dir>"
-    );
-    return;
+  if (target.user_id !== userId) {
+    jsonError(`Card ${cardId} does not belong to user ${userId}`);
   }
-  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(", ")}`);
-    }
+  return target;
+}
+function parseTokenUpdates(opts) {
+  const updates = {};
+  if (opts.concept !== void 0) updates.concept = opts.concept;
+  if (opts.domain !== void 0) updates.domain = opts.domain;
+  if (opts.bloom !== void 0)
+    updates.bloom_level = Number(opts.bloom);
+  if (opts.context !== void 0) updates.context = opts.context;
+  if (opts.sourceLink !== void 0) {
+    updates.source_link = opts.sourceLink === "" ? null : opts.sourceLink;
   }
-});
-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);
+  if (opts.mode !== void 0) {
+    const validModes = ["shadowing", "copilot", "autonomy", "none"];
+    if (!validModes.includes(opts.mode)) {
+      jsonError(`Invalid mode: ${opts.mode}`);
     }
-    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 } : {}
-    };
-    wireSkills(path, parseSetupAgents());
-    upsertConfiguredWorkspace(workspace);
-    console.log(`Registered and linked workspace "${id}" at ${path}.`);
-  } catch (err) {
-    console.error(`Error: ${err.message}`);
-    process.exit(1);
+    updates.symbiosis_mode = opts.mode === "none" ? null : opts.mode;
   }
+  return updates;
+}
+var bridgeCommand = new Command2("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) => {
+  await withDb2(async (db) => {
+    const userId = await resolveUser(opts, db, { json: true });
+    const dueCards = await getDueCards(db, userId, void 0, opts.domain);
+    const domains = [
+      ...new Set(dueCards.map((c) => c.domain).filter(Boolean))
+    ].sort();
+    jsonOut2({
+      userId,
+      domain: opts.domain ?? null,
+      dueCount: dueCards.length,
+      domains,
+      cards: dueCards.map((c) => ({
+        cardId: c.id,
+        tokenId: c.token_id,
+        slug: c.slug,
+        concept: c.concept,
+        domain: c.domain,
+        bloomLevel: c.bloom_level,
+        state: c.state,
+        dueAt: c.due_at
+      }))
+    });
+  });
 });
-workspaceCommand.command("remove <id>").description("Unregister a ZAM workspace without deleting its files").action((id) => {
-  const existing = getConfiguredWorkspaces().find((item) => item.id === id);
-  if (!existing) {
-    console.error(`Workspace "${id}" is not configured.`);
-    process.exit(1);
+bridgeCommand.command("backup-db").description("Back up the local database into the workspace (JSON)").option(
+  "--dir <path>",
+  "Target directory (default: workspace dir, else ~/Documents/zam)"
+).action(async (opts) => {
+  const target = getDatabaseTargetInfo();
+  if (target.kind !== "local") {
+    jsonOut2({
+      ok: false,
+      reason: "remote",
+      target: target.kind,
+      location: target.location
+    });
+    return;
   }
-  removeConfiguredWorkspace(id);
-  console.log(
-    `Unregistered workspace "${id}". Files in ${existing.path} were not changed.`
-  );
+  await withDb2(async (db) => {
+    const workspaceDir = opts.dir || (await ensureActiveWorkspace(db)).path;
+    const path = await backupDatabaseTo(db, workspaceDir);
+    jsonOut2({ ok: true, path });
+  });
 });
-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)" : ""}
-`
-    );
-    wireSkills(workspace.path, agents, {
-      force: Boolean(opts.force),
-      dryRun: Boolean(opts.dryRun)
-    });
-    if (agents.has("claude")) {
-      writeClaudeMd(false, workspace.path, {
-        dryRun: Boolean(opts.dryRun),
-        updateExisting: true
-      });
-    }
-    if (agents.has("codex") || agents.has("agent")) {
-      writeAgentsMd(false, workspace.path, {
-        dryRun: Boolean(opts.dryRun),
-        updateExisting: true
-      });
-    }
-    if (agents.has("copilot")) {
-      writeCopilotInstructions(workspace.path, {
-        dryRun: Boolean(opts.dryRun),
-        updateExisting: true
-      });
-    }
-  } catch (err) {
-    console.error(`Error: ${err.message}`);
-    process.exit(1);
-  }
-});
-workspaceCommand.command("publish").description("Publish your local workspace sandbox to GitHub").action(async () => {
-  let db;
-  let workspaceDir = "";
-  try {
-    db = await openDatabase();
-    workspaceDir = await getSetting(db, "personal.workspace_dir") || "";
-    await db.close();
-  } catch {
-    await db?.close();
-  }
-  if (!workspaceDir) {
-    console.error(
-      "\x1B[31m\u2717 No active workspace configured. Please run `zam init` first.\x1B[0m"
-    );
-    process.exit(1);
-  }
-  if (!existsSync16(workspaceDir)) {
-    console.error(
-      `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
-    );
-    process.exit(1);
-  }
-  console.log(`
-Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
-  if (!hasCommand("git")) {
-    console.error(
-      "\x1B[31m\u2717 Git command was not found on this system. Please install Git first.\x1B[0m"
-    );
-    process.exit(1);
-  }
-  const gitignorePath = join16(workspaceDir, ".gitignore");
-  if (!existsSync16(gitignorePath)) {
-    writeFileSync8(
-      gitignorePath,
-      "node_modules/\n.agent/\n.agents/\n.claude/\n.gemini/\n.goose/\n*.log\n",
-      "utf8"
-    );
-  }
-  const hasGitRepo = existsSync16(join16(workspaceDir, ".git"));
-  if (!hasGitRepo) {
-    console.log("Initializing local Git repository...");
-    runGit(workspaceDir, ["init", "-b", "main"]);
-    runGit(workspaceDir, ["add", "."]);
-    runGit(workspaceDir, [
-      "commit",
-      "-m",
-      "chore: initial workspace sandbox bootstrap"
-    ]);
-    console.log("\x1B[32m\u2713 Local Git repository initialized.\x1B[0m");
-  } else {
-    console.log("Git repository is already initialized.");
-  }
-  const repoName = await input({
-    message: "Choose a name for your GitHub repository:",
-    default: "zam-personal"
-  });
-  const isPrivate = await confirm({
-    message: "Should the repository be private?",
-    default: true
-  });
-  const repoVisibility = isPrivate ? "--private" : "--public";
-  if (hasCommand("gh")) {
-    console.log("GitHub CLI detected! Automating repository creation...");
-    const proceedGh = await confirm({
-      message: "Would you like ZAM to create the repository using the GitHub CLI?",
-      default: true
+bridgeCommand.command("workspace-info").description("Report the workspace dir, its default, and the data dir (JSON)").action(async () => {
+  await withDb2(async (db) => {
+    const activeWorkspace = await ensureActiveWorkspace(db);
+    jsonOut2({
+      activeWorkspaceId: activeWorkspace.id,
+      activeWorkspace,
+      workspaceDir: activeWorkspace.path,
+      defaultWorkspaceDir: defaultWorkspaceDir(),
+      dataDir: join18(homedir10(), ".zam")
     });
-    if (proceedGh) {
-      try {
-        console.log(`Creating GitHub repository ${repoName}...`);
-        execFileSync3("gh", ghRepoCreateArgs(repoName, repoVisibility), {
-          cwd: workspaceDir,
-          stdio: "inherit"
-        });
-        console.log(
-          "\n\x1B[32m\u2713 Successfully published workspace to GitHub!\x1B[0m"
-        );
-        process.exit(0);
-      } catch (err) {
-        console.warn(
-          `\x1B[33m\u26A0 GitHub CLI creation failed: ${err.message}\x1B[0m`
-        );
-      }
-    }
-  }
-  console.log(
-    "\n\x1B[1mPlease create the repository manually on GitHub:\x1B[0m"
-  );
-  console.log("  1. Go to https://github.com/new");
-  console.log(`  2. Name it exactly: \x1B[36m${repoName}\x1B[0m`);
-  console.log(
-    `  3. Choose \x1B[36m${isPrivate ? "Private" : "Public"}\x1B[0m`
-  );
-  console.log(
-    "  4. Do NOT initialize it with README, .gitignore, or license"
-  );
-  console.log("  5. Click 'Create repository'\n");
-  const githubUrl = await input({
-    message: "Paste the repository Git URL (e.g. git@github.com:user/repo.git):"
   });
-  if (githubUrl) {
-    try {
-      console.log("Linking remote repository and pushing...");
-      let hasOrigin = false;
-      try {
-        runGit(workspaceDir, ["remote", "get-url", "origin"]);
-        hasOrigin = true;
-      } catch {
-      }
-      runGit(workspaceDir, gitRemoteArgs(githubUrl, hasOrigin));
-      runGit(workspaceDir, ["push", "-u", "origin", "main"]);
-      console.log(
-        "\x1B[32m\u2713 Successfully linked and pushed to GitHub!\x1B[0m"
-      );
-    } catch (err) {
-      console.error(
-        `\x1B[31m\u2717 Push failed: ${err.message}\x1B[0m`
-      );
-      console.log(
-        "You can push manually later using: git push -u origin main"
-      );
-    }
-  }
 });
-async function backupDatabaseTo(db, targetDir) {
-  const backupDir = join16(targetDir, "zam-backups");
-  mkdirSync9(backupDir, { recursive: true });
-  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const dest = join16(backupDir, `zam-${stamp}.db`);
-  await db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
-  return dest;
-}
-workspaceCommand.command("data-dir").description("Print the ZAM data directory (database, credentials, config)").option("--json", "Output as JSON").action((opts) => {
-  const dir = join16(homedir9(), ".zam");
-  console.log(opts.json ? JSON.stringify({ dataDir: dir }) : dir);
-});
-workspaceCommand.command("backup").description("Back up the local ZAM database into your workspace").option(
-  "--dir <path>",
-  "Target directory (default: workspace dir, else ~/Documents/zam)"
-).option("--json", "Output as JSON").action(async (opts) => {
-  const target = getDatabaseTargetInfo();
-  if (target.kind !== "local") {
-    const reason = `The database is ${target.kind} (${target.location}); file backup applies only to a local database \u2014 your Turso remote is already the cloud backup.`;
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, reason }));
-      return;
-    }
-    console.error(`\x1B[33m\u26A0 ${reason}\x1B[0m`);
-    process.exit(1);
-  }
-  let db;
-  try {
-    db = await openDatabase();
-    const workspaceDir = opts.dir || await getSetting(db, "personal.workspace_dir") || join16(homedir9(), "Documents", "zam");
-    const dest = await backupDatabaseTo(db, workspaceDir);
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: true, path: dest }));
-    } else {
-      console.log(`\x1B[32m\u2713 Database backed up to ${dest}\x1B[0m`);
-    }
-  } catch (err) {
-    const reason = err.message;
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, reason }));
-    } else {
-      console.error(`\x1B[31m\u2717 Backup failed: ${reason}\x1B[0m`);
-    }
-    process.exit(1);
-  } finally {
-    await db?.close();
-  }
-});
-
-// src/cli/commands/bridge.ts
-var isServeMode = false;
-function jsonOut2(data) {
-  console.log(JSON.stringify(data, null, 2));
-}
-function jsonError(message) {
-  if (isServeMode) {
-    throw new Error(JSON.stringify({ error: message }));
-  }
-  console.log(JSON.stringify({ error: message }, null, 2));
-  process.exit(1);
-}
-function parseNonNegativeIntegerOption(name, value) {
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed < 0) {
-    jsonError(`${name} must be a non-negative integer`);
-  }
-  return parsed;
-}
-async function withDb2(fn) {
-  await withDb(fn, jsonError);
+function provisionConfiguredWorkspaces() {
+  return getConfiguredWorkspaces().flatMap(
+    (workspace) => existsSync17(workspace.path) ? wireSkills(workspace.path, parseSetupAgents(), { quiet: true }) : []
+  );
 }
-async function getReviewTarget2(db, cardId, userId) {
-  const target = await db.prepare(
-    `SELECT c.id AS card_id, c.token_id, c.user_id, t.slug
-       FROM cards c
-       JOIN tokens t ON t.id = c.token_id
-       WHERE c.id = ?`
-  ).get(cardId);
-  if (!target) {
-    jsonError(`Card not found: ${cardId}`);
-  }
-  if (target.user_id !== userId) {
-    jsonError(`Card ${cardId} does not belong to user ${userId}`);
+function buildWorkspaceLinkHealth(workspaces) {
+  const agents = parseSetupAgents();
+  const map = {};
+  for (const workspace of workspaces) {
+    if (!existsSync17(workspace.path)) continue;
+    const links = inspectSkillLinks(workspace.path, agents);
+    map[workspace.id] = {
+      health: summarizeSkillLinkHealth(links),
+      states: Object.fromEntries(
+        links.map((link) => [link.agents.join("+"), link.state])
+      )
+    };
   }
-  return target;
+  return map;
 }
-function parseTokenUpdates(opts) {
-  const updates = {};
-  if (opts.concept !== void 0) updates.concept = opts.concept;
-  if (opts.domain !== void 0) updates.domain = opts.domain;
-  if (opts.bloom !== void 0)
-    updates.bloom_level = Number(opts.bloom);
-  if (opts.context !== void 0) updates.context = opts.context;
-  if (opts.sourceLink !== void 0) {
-    updates.source_link = opts.sourceLink === "" ? null : opts.sourceLink;
-  }
-  if (opts.mode !== void 0) {
-    const validModes = ["shadowing", "copilot", "autonomy", "none"];
-    if (!validModes.includes(opts.mode)) {
-      jsonError(`Invalid mode: ${opts.mode}`);
-    }
-    updates.symbiosis_mode = opts.mode === "none" ? null : opts.mode;
-  }
-  return updates;
+async function ensureDesktopWorkspace(db) {
+  const activeWorkspace = await ensureActiveWorkspace(db);
+  const skillLinks = provisionConfiguredWorkspaces();
+  return {
+    workspaceDir: activeWorkspace.path,
+    activeWorkspaceId: activeWorkspace.id,
+    skillLinks
+  };
 }
-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) => {
+bridgeCommand.command("workspace-list").description("List configured ZAM workspaces (JSON)").action(async () => {
   await withDb2(async (db) => {
-    const userId = await resolveUser(opts, db, { json: true });
-    const dueCards = await getDueCards(db, userId, void 0, opts.domain);
-    const domains = [
-      ...new Set(dueCards.map((c) => c.domain).filter(Boolean))
-    ].sort();
+    const activeWorkspace = await ensureActiveWorkspace(db);
+    const workspaces = getConfiguredWorkspaces();
     jsonOut2({
-      userId,
-      domain: opts.domain ?? null,
-      dueCount: dueCards.length,
-      domains,
-      cards: dueCards.map((c) => ({
-        cardId: c.id,
-        tokenId: c.token_id,
-        slug: c.slug,
-        concept: c.concept,
-        domain: c.domain,
-        bloomLevel: c.bloom_level,
-        state: c.state,
-        dueAt: c.due_at
-      }))
+      workspaces,
+      activeWorkspaceId: activeWorkspace.id,
+      activeWorkspace,
+      workspaceDir: activeWorkspace.path,
+      defaultWorkspaceDir: defaultWorkspaceDir(),
+      dataDir: join18(homedir10(), ".zam"),
+      linkHealth: buildWorkspaceLinkHealth(workspaces)
     });
   });
 });
-bridgeCommand.command("backup-db").description("Back up the local database into the workspace (JSON)").option(
-  "--dir <path>",
-  "Target directory (default: workspace dir, else ~/Documents/zam)"
+bridgeCommand.command("workspace-repair-links").description(
+  "Relink ZAM skill junctions for a configured workspace, replacing broken links and outdated copies (JSON)"
+).requiredOption("--id <id>", "Workspace id").option(
+  "--agents <list>",
+  "comma-separated agents to wire: all, claude, copilot, codex, agent"
 ).action(async (opts) => {
-  const target = getDatabaseTargetInfo();
-  if (target.kind !== "local") {
-    jsonOut2({
-      ok: false,
-      reason: "remote",
-      target: target.kind,
-      location: target.location
-    });
-    return;
+  const id = String(opts.id ?? "").trim();
+  if (!id) jsonError("A non-empty --id is required");
+  const workspace = getConfiguredWorkspaces().find((item) => item.id === id);
+  if (!workspace) jsonError(`Workspace "${id}" is not configured`);
+  if (!existsSync17(workspace.path)) {
+    jsonError(`Workspace path does not exist: ${workspace.path}`);
   }
-  await withDb2(async (db) => {
-    const workspaceDir = opts.dir || await getSetting(db, "personal.workspace_dir") || join17(homedir10(), "Documents", "zam");
-    const path = await backupDatabaseTo(db, workspaceDir);
-    jsonOut2({ ok: true, path });
-  });
-});
-bridgeCommand.command("workspace-info").description("Report the workspace dir, its default, and the data dir (JSON)").action(async () => {
-  await withDb2(async (db) => {
-    const workspaceDir = await getSetting(db, "personal.workspace_dir") || null;
-    jsonOut2({
-      workspaceDir,
-      defaultWorkspaceDir: join17(homedir10(), "Documents", "zam"),
-      dataDir: join17(homedir10(), ".zam")
-    });
+  const agents = parseSetupAgents(opts.agents);
+  const skillLinks = wireSkills(workspace.path, agents, {
+    force: true,
+    quiet: true
   });
-});
-function sameWorkspacePath(left, right) {
-  const normalize = (value) => {
-    const path = resolve5(value);
-    return process.platform === "win32" ? path.toLowerCase() : path;
-  };
-  return normalize(left) === normalize(right);
-}
-async function ensureDesktopWorkspace(db) {
-  const configured = getConfiguredWorkspaces();
-  const savedWorkspaceDir = await getSetting(db, "personal.workspace_dir");
-  const workspaceDir = savedWorkspaceDir || configured.find((workspace) => workspace.kind === "personal")?.path || join17(homedir10(), "Documents", "zam");
-  mkdirSync10(workspaceDir, { recursive: true });
-  if (!savedWorkspaceDir) {
-    await setSetting(db, "personal.workspace_dir", workspaceDir);
-  }
-  if (!configured.some(
-    (workspace) => sameWorkspacePath(workspace.path, workspaceDir)
-  )) {
-    const id = configured.some((workspace) => workspace.id === "personal") ? workspaceIdFromPath(workspaceDir) : "personal";
-    upsertConfiguredWorkspace({
-      id,
-      label: basename5(workspaceDir) || "ZAM",
-      kind: "personal",
-      path: workspaceDir
-    });
-  }
-  const skillLinks = getConfiguredWorkspaces().flatMap(
-    (workspace) => existsSync17(workspace.path) ? wireSkills(workspace.path, parseSetupAgents(), { quiet: true }) : []
-  );
-  return { workspaceDir, skillLinks };
-}
-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")
-    });
+  const links = inspectSkillLinks(workspace.path, agents);
+  jsonOut2({
+    ok: true,
+    workspace,
+    skillLinks,
+    linkHealth: {
+      health: summarizeSkillLinkHealth(links),
+      states: Object.fromEntries(
+        links.map((link) => [link.agents.join("+"), link.state])
+      )
+    }
   });
 });
-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") {
@@ -7617,25 +7614,25 @@ function parseBridgeWorkspaceKind(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);
+  const path = resolve4(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
-  };
+  const id = opts.id ? String(opts.id).trim() : void 0;
+  if (opts.id && !id) jsonError("A non-empty --id is required");
+  const kind = parseBridgeWorkspaceKind(opts.kind);
   const skillLinks = wireSkills(path, parseSetupAgents(), { quiet: true });
   await withDb2(async (db) => {
-    await setSetting(db, "personal.workspace_dir", path);
-    upsertConfiguredWorkspace(workspace);
+    const workspace = await activateWorkspacePath(db, path, {
+      ...id ? { id } : {},
+      ...opts.label ? { label: opts.label } : {},
+      kind
+    });
     jsonOut2({
       ok: true,
       workspace,
       workspaces: getConfiguredWorkspaces(),
-      workspaceDir: path,
+      activeWorkspaceId: workspace.id,
+      activeWorkspace: workspace,
+      workspaceDir: workspace.path,
       skillLinks
     });
   });
@@ -7646,27 +7643,15 @@ bridgeCommand.command("workspace-remove").description("Unregister a ZAM workspac
   const workspace = getConfiguredWorkspaces().find((item) => item.id === id);
   if (!workspace) jsonError(`Workspace "${id}" is not configured`);
   await withDb2(async (db) => {
-    const activeWorkspaceDir = await getSetting(db, "personal.workspace_dir") || null;
-    const remaining = removeConfiguredWorkspace(id);
-    let workspaceDir = activeWorkspaceDir;
-    let skillLinks = [];
-    if (activeWorkspaceDir && sameWorkspacePath(activeWorkspaceDir, workspace.path)) {
-      if (remaining.length > 0) {
-        workspaceDir = remaining[0].path;
-        await setSetting(db, "personal.workspace_dir", workspaceDir);
-      } else {
-        workspaceDir = join17(homedir10(), "Documents", "zam");
-        await setSetting(db, "personal.workspace_dir", workspaceDir);
-        const ensured = await ensureDesktopWorkspace(db);
-        workspaceDir = ensured.workspaceDir;
-        skillLinks = ensured.skillLinks;
-      }
-    }
+    const { activeWorkspace, workspaces } = await removeWorkspaceAndResolveActive(db, id);
+    const skillLinks = provisionConfiguredWorkspaces();
     jsonOut2({
       ok: true,
       removed: workspace,
-      workspaces: getConfiguredWorkspaces(),
-      workspaceDir,
+      workspaces,
+      activeWorkspaceId: activeWorkspace.id,
+      activeWorkspace,
+      workspaceDir: activeWorkspace.path,
       skillLinks
     });
   });
@@ -7674,12 +7659,20 @@ bridgeCommand.command("workspace-remove").description("Unregister a ZAM workspac
 bridgeCommand.command("set-workspace-dir").description("Set the personal workspace directory (JSON)").requiredOption("--dir <path>", "Path to the workspace directory").action(async (opts) => {
   const raw = String(opts.dir ?? "").trim();
   if (!raw) jsonError("A non-empty --dir is required");
-  const dir = resolve5(raw);
+  const dir = resolve4(raw);
   if (!existsSync17(dir)) jsonError(`Workspace path does not exist: ${dir}`);
   const skillLinks = wireSkills(dir, parseSetupAgents(), { quiet: true });
   await withDb2(async (db) => {
-    await setSetting(db, "personal.workspace_dir", dir);
-    jsonOut2({ ok: true, workspaceDir: dir, skillLinks });
+    const workspace = await activateWorkspacePath(db, dir);
+    jsonOut2({
+      ok: true,
+      workspace,
+      workspaces: getConfiguredWorkspaces(),
+      activeWorkspaceId: workspace.id,
+      activeWorkspace: workspace,
+      workspaceDir: workspace.path,
+      skillLinks
+    });
   });
 });
 bridgeCommand.command("agent-list").description("List agent harnesses with detection state + the default (JSON)").action(async () => {
@@ -7729,8 +7722,8 @@ bridgeCommand.command("agent-open").description("Launch an agent harness in the
     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();
+    const activeWorkspace = await ensureActiveWorkspace(db);
+    const workspace = opts.dir ? existsSync17(opts.dir) ? opts.dir : homedir10() : existingWorkspaceDirOrHome(configuredWorkspace ?? activeWorkspace);
     launchHarness(harness, {
       executable,
       workspace,
@@ -7768,6 +7761,8 @@ bridgeCommand.command("get-review").description("Get next review card with promp
     const item = queue.items[0];
     const isLlmEnabled = await getSetting(db, "llm.enabled") === "true";
     let resolvedQuestion = item.question;
+    let questionSource = "original";
+    let questionModel;
     if (isLlmEnabled) {
       try {
         const healed = await ensureHighQualityQuestion(db, {
@@ -7780,7 +7775,9 @@ bridgeCommand.command("get-review").description("Get next review card with promp
           question: item.question
         });
         if (healed) {
-          resolvedQuestion = healed;
+          resolvedQuestion = healed.question;
+          questionSource = healed.source;
+          questionModel = healed.model;
         }
       } catch {
       }
@@ -7809,6 +7806,8 @@ bridgeCommand.command("get-review").description("Get next review card with promp
       hasReview: true,
       card: item,
       prompt,
+      questionSource,
+      questionModel: questionModel ?? null,
       resolvedContext,
       queueSize: fullQueue.items.length
     });
@@ -8104,10 +8103,10 @@ bridgeCommand.command("discover-skills").description(
   "20"
 ).action(async (opts) => {
   try {
-    const monitorDir = join17(homedir10(), ".zam", "monitor");
+    const monitorDir = join18(homedir10(), ".zam", "monitor");
     let files;
     try {
-      files = readdirSync3(monitorDir).filter((f) => f.endsWith(".jsonl"));
+      files = readdirSync2(monitorDir).filter((f) => f.endsWith(".jsonl"));
     } catch {
       jsonOut2({ proposals: [], message: "No monitor logs found." });
       return;
@@ -8117,7 +8116,7 @@ bridgeCommand.command("discover-skills").description(
       return;
     }
     const limit = Number(opts.limit);
-    const sorted = files.map((f) => ({ name: f, path: join17(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
+    const sorted = files.map((f) => ({ name: f, path: join18(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", "");
@@ -8229,7 +8228,7 @@ bridgeCommand.command("observe-ui-snapshot").description(
 });
 function resolveWindowsPowerShell() {
   try {
-    execFileSync4("where.exe", ["pwsh.exe"], { stdio: "ignore" });
+    execFileSync3("where.exe", ["pwsh.exe"], { stdio: "ignore" });
     return "pwsh";
   } catch {
     return "powershell";
@@ -8244,7 +8243,7 @@ function captureScreenshot(outputPath, hwnd, processName) {
     throw new Error(`Invalid process name format: ${processName}`);
   }
   if (platform === "win32") {
-    const stdout = execFileSync4(
+    const stdout = execFileSync3(
       resolveWindowsPowerShell(),
       [
         "-NoProfile",
@@ -8557,13 +8556,13 @@ Write-CaptureResult "fullscreen" $hwndVal $matchedBy
   } else if (platform === "darwin") {
     if (hwnd) {
       const parsedHwnd = hwnd.startsWith("0x") ? parseInt(hwnd, 16) : parseInt(hwnd, 10);
-      execFileSync4("screencapture", ["-l", String(parsedHwnd), outputPath], {
+      execFileSync3("screencapture", ["-l", String(parsedHwnd), outputPath], {
         stdio: "pipe"
       });
       return { method: "screencapture-window", target: null };
     } else if (processName) {
       try {
-        const windowId = execFileSync4(
+        const windowId = execFileSync3(
           "osascript",
           [
             "-e",
@@ -8572,17 +8571,17 @@ Write-CaptureResult "fullscreen" $hwndVal $matchedBy
           { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }
         ).trim();
         if (windowId && /^\d+$/.test(windowId)) {
-          execFileSync4("screencapture", ["-l", windowId, outputPath], {
+          execFileSync3("screencapture", ["-l", windowId, outputPath], {
             stdio: "pipe"
           });
           return { method: "screencapture-window", target: null };
         }
       } catch {
       }
-      execFileSync4("screencapture", ["-x", outputPath], { stdio: "pipe" });
+      execFileSync3("screencapture", ["-x", outputPath], { stdio: "pipe" });
       return { method: "screencapture-full", target: null };
     } else {
-      execFileSync4("screencapture", ["-x", outputPath], { stdio: "pipe" });
+      execFileSync3("screencapture", ["-x", outputPath], { stdio: "pipe" });
       return { method: "screencapture-full", target: null };
     }
   } else {
@@ -8619,7 +8618,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
         return;
       }
     }
-    const outputPath = opts.image ?? opts.output ?? join17(tmpdir3(), `zam-capture-${randomBytes2(4).toString("hex")}.png`);
+    const outputPath = opts.image ?? opts.output ?? join18(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, {
@@ -8674,11 +8673,11 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     return;
   }
   const sessionId = opts.session;
-  const statePath = join17(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const statePath = join18(tmpdir3(), `zam-recording-${sessionId}.json`);
   const defaultExt = platform === "win32" ? ".mkv" : ".mov";
-  const outputPath = opts.output ?? join17(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
-  const { existsSync: existsSync25, writeFileSync: writeFileSync12, openSync, closeSync } = await import("fs");
-  if (existsSync25(statePath)) {
+  const outputPath = opts.output ?? join18(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
+  const { existsSync: existsSync26, writeFileSync: writeFileSync12, openSync, closeSync } = await import("fs");
+  if (existsSync26(statePath)) {
     jsonOut2({
       sessionId,
       started: false,
@@ -8686,7 +8685,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     });
     return;
   }
-  const logPath = join17(tmpdir3(), `zam-recording-${sessionId}.log`);
+  const logPath = join18(tmpdir3(), `zam-recording-${sessionId}.log`);
   let logFd;
   try {
     logFd = openSync(logPath, "w");
@@ -8768,9 +8767,9 @@ bridgeCommand.command("stop-recording").description(
     return;
   }
   const sessionId = opts.session;
-  const statePath = join17(tmpdir3(), `zam-recording-${sessionId}.json`);
-  const { existsSync: existsSync25, readFileSync: readFileSync16, rmSync: rmSync4 } = await import("fs");
-  if (!existsSync25(statePath)) {
+  const statePath = join18(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const { existsSync: existsSync26, readFileSync: readFileSync16, rmSync: rmSync4 } = await import("fs");
+  if (!existsSync26(statePath)) {
     jsonOut2({
       sessionId,
       stopped: false,
@@ -8794,7 +8793,7 @@ bridgeCommand.command("stop-recording").description(
   };
   let attempts = 0;
   while (isProcessRunning(pid) && attempts < 20) {
-    await new Promise((resolve9) => setTimeout(resolve9, 250));
+    await new Promise((resolve10) => setTimeout(resolve10, 250));
     attempts++;
   }
   if (isProcessRunning(pid)) {
@@ -8807,7 +8806,7 @@ bridgeCommand.command("stop-recording").description(
     rmSync4(statePath, { force: true });
   } catch {
   }
-  if (!existsSync25(outputPath)) {
+  if (!existsSync26(outputPath)) {
     jsonOut2({
       sessionId,
       stopped: false,
@@ -8887,25 +8886,207 @@ bridgeCommand.command("check-llm").description("Check if LLM is enabled and onli
       }
     }
     jsonOut2({
-      enabled,
-      online,
-      url,
-      model,
-      modelAvailable,
-      availableModels,
-      apiFlavor: provider.apiFlavor,
-      unsupportedProvider
+      enabled,
+      online,
+      url,
+      model,
+      modelAvailable,
+      availableModels,
+      apiFlavor: provider.apiFlavor,
+      unsupportedProvider
+    });
+  });
+});
+bridgeCommand.command("provider-status").description("Show secret-safe provider status for LLM roles (JSON)").action(async () => {
+  await withDb2(async (db) => {
+    const [recall, vision, text] = await Promise.all([
+      getProviderRoleStatus(db, "recall"),
+      getProviderRoleStatus(db, "vision"),
+      getProviderRoleStatus(db, "text")
+    ]);
+    jsonOut2({ roles: { recall, vision, text } });
+  });
+});
+bridgeCommand.command("provider-config-list").description("List provider records and role bindings (JSON)").option("--scope <scope>", "machine (default) or shared", "machine").action(async (opts) => {
+  const machine = parseProviderScope(opts.scope);
+  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
+    );
+    jsonOut2({
+      scope: machine ? "machine" : "shared",
+      providers: rows,
+      roles,
+      orphans: findOrphanKeyRefs(listProviderApiKeyRefs(), providers)
+    });
+  });
+});
+bridgeCommand.command("provider-config-upsert").description("Add or update a provider record (JSON)").requiredOption("--name <name>", "Provider name").option("--label <label>", "Human-readable label").option("--url <url>", "Endpoint base URL").option("--model <model>", "Model id").option(
+  "--flavor <flavor>",
+  `Wire protocol: ${VALID_API_FLAVORS.join(" | ")}`
+).option("--local", "Mark as local endpoint").option("--no-local", "Mark as cloud/non-local endpoint").option("--runner <runner>", "Local runner hint").option("--key-ref <ref>", "Credential reference for API key").option("--scope <scope>", "machine (default) or shared", "machine").action(async (opts, command) => {
+  const machine = parseProviderScope(opts.scope);
+  let apiFlavor;
+  if (opts.flavor) {
+    if (!VALID_API_FLAVORS.includes(opts.flavor)) {
+      jsonError(
+        `Invalid --flavor: ${opts.flavor}. Use ${VALID_API_FLAVORS.join(" or ")}.`
+      );
+    }
+    apiFlavor = opts.flavor;
+  }
+  let local;
+  if (command.getOptionValueSource("local") === "cli") {
+    local = opts.local === true;
+  }
+  const patch = {};
+  if (opts.label !== void 0) patch.label = opts.label;
+  if (opts.url !== void 0) patch.url = opts.url;
+  if (opts.model !== void 0) patch.model = opts.model;
+  if (apiFlavor !== void 0) patch.apiFlavor = apiFlavor;
+  if (opts.keyRef !== void 0) patch.apiKeyRef = opts.keyRef;
+  if (local !== void 0) patch.local = local;
+  if (opts.runner !== void 0) patch.runner = opts.runner;
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const next = upsertProviderRecord(providers, opts.name, patch);
+    await writeScopedProviders(db, machine, next);
+    const rows = buildProviderListing(
+      next,
+      (ref) => getProviderApiKey(ref) !== null
+    );
+    const row = rows.find((entry) => entry.name === opts.name);
+    jsonOut2({
+      ok: true,
+      scope: machine ? "machine" : "shared",
+      name: opts.name,
+      provider: row,
+      cloudModelHint: opts.url ? getCloudModelRecommendation(opts.url) : null
+    });
+  });
+});
+bridgeCommand.command("provider-config-remove").description("Remove a provider record (JSON)").requiredOption("--name <name>", "Provider name").option("--scope <scope>", "machine (default) or shared", "machine").action(async (opts) => {
+  const machine = parseProviderScope(opts.scope);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const { providers: next, removed } = removeProviderRecord(
+      providers,
+      opts.name
+    );
+    if (!removed) {
+      jsonError(`No such provider: ${opts.name}`);
+    }
+    await writeScopedProviders(db, machine, next);
+    jsonOut2({
+      ok: true,
+      scope: machine ? "machine" : "shared",
+      name: opts.name,
+      removed: true,
+      referencingRoles: rolesReferencing(
+        await readScopedRoles(db, machine),
+        opts.name
+      )
+    });
+  });
+});
+bridgeCommand.command("provider-config-bind").description("Bind providers to an LLM role (JSON)").requiredOption("--role <role>", `Role: ${VALID_ROLES.join(" | ")}`).requiredOption("--primary <name>", "Primary provider name").option("--fallback <name>", "Fallback provider name").option("--scope <scope>", "machine (default) or shared", "machine").action(async (opts) => {
+  if (!VALID_ROLES.includes(opts.role)) {
+    jsonError(`Invalid --role: ${opts.role}. Use ${VALID_ROLES.join(", ")}.`);
+  }
+  const machine = parseProviderScope(opts.scope);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const roles = await readScopedRoles(db, machine);
+    const nextRoles = bindRoleProviders(
+      roles,
+      opts.role,
+      opts.primary,
+      opts.fallback
+    );
+    await writeScopedRoles(db, machine, nextRoles);
+    const binding = nextRoles[opts.role];
+    const primary = providers[opts.primary];
+    jsonOut2({
+      ok: true,
+      scope: machine ? "machine" : "shared",
+      role: opts.role,
+      binding,
+      warnings: [
+        ...primary && primary.apiFlavor === "anthropic-messages" && (opts.role === "recall" || opts.role === "text") ? ["unsupported-provider-for-role"] : [],
+        ...opts.primary && !(opts.primary in providers) ? ["primary-provider-undefined"] : [],
+        ...opts.fallback && !(opts.fallback in providers) ? ["fallback-provider-undefined"] : []
+      ]
     });
   });
 });
-bridgeCommand.command("provider-status").description("Show secret-safe provider status for LLM roles (JSON)").action(async () => {
+bridgeCommand.command("provider-set-key").description("Store an API key for a provider reference (JSON)").requiredOption("--ref <ref>", "Credential reference name").requiredOption("--key <value>", "API key value (write-only)").action((opts) => {
+  const key = opts.key.trim();
+  if (!key) jsonError("No key provided.");
+  setProviderApiKey(opts.ref, key);
+  jsonOut2({ ok: true, ref: opts.ref, masked: maskSecret(key) });
+});
+bridgeCommand.command("provider-clear-key").description("Remove a stored provider API key (JSON)").requiredOption("--ref <ref>", "Credential reference name").action((opts) => {
+  clearProviderApiKey(opts.ref);
+  jsonOut2({ ok: true, ref: opts.ref });
+});
+bridgeCommand.command("list-models").description("List models exposed by an LLM endpoint (JSON)").requiredOption("--url <url>", "Endpoint base URL").option("--key-ref <ref>", "Resolve API key from credentials by reference").action(async (opts) => {
+  const apiKey = opts.keyRef ? getProviderApiKey(opts.keyRef) ?? void 0 : void 0;
+  const models = await getAvailableModels(opts.url, apiKey);
+  jsonOut2({ models });
+});
+bridgeCommand.command("cloud-model-hint").description("Suggest a cloud model for an endpoint URL (JSON)").requiredOption("--url <url>", "Endpoint base URL").action((opts) => {
+  jsonOut2({ recommendation: getCloudModelRecommendation(opts.url) });
+});
+bridgeCommand.command("local-llm-hints").description("Detect installed local LLM servers and suggest defaults (JSON)").action(() => {
+  const profile = getSystemProfile();
+  const flmInstalled = hasCommand("flm") || existsSync17("C:\\Program Files\\flm\\flm.exe");
+  const ollamaInstalled = hasCommand("ollama");
+  const runners = [
+    { id: "flm", label: "FastFlowLM", installed: flmInstalled },
+    { id: "ollama", label: "Ollama", installed: ollamaInstalled },
+    {
+      id: "foundry-local",
+      label: "Foundry Local",
+      installed: false
+    }
+  ];
+  let recommended = "ollama";
+  if (profile.recommendedRunner === "fastflowlm" && flmInstalled) {
+    recommended = "flm";
+  } else if (profile.recommendedRunner === "ollama" && ollamaInstalled) {
+    recommended = "ollama";
+  } else if (flmInstalled) {
+    recommended = "flm";
+  } else if (ollamaInstalled) {
+    recommended = "ollama";
+  } else if (profile.recommendedRunner === "fastflowlm") {
+    recommended = "flm";
+  }
+  const defaultUrl = recommended === "ollama" ? "http://localhost:11434/v1" : DEFAULT_LLM_URL;
+  jsonOut2({
+    runners,
+    recommended,
+    defaultUrl,
+    defaultModel: profile.recommendedModel || DEFAULT_LLM_MODEL
+  });
+});
+var UI_WRITABLE_SETTINGS = /* @__PURE__ */ new Set([
+  "llm.enabled",
+  "llm.vision.enabled",
+  "system.locale"
+]);
+bridgeCommand.command("setting-set").description("Set a single allowlisted ZAM setting value (JSON)").requiredOption("--key <key>", "Setting key").requiredOption("--value <value>", "Setting value").action(async (opts) => {
+  if (!UI_WRITABLE_SETTINGS.has(opts.key)) {
+    jsonError(
+      `Setting "${opts.key}" is not writable via setting-set. Allowed: ${[...UI_WRITABLE_SETTINGS].join(", ")}.`
+    );
+  }
   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 } });
+    await setSetting(db, opts.key, opts.value);
+    jsonOut2({ ok: true, key: opts.key, value: opts.value });
   });
 });
 bridgeCommand.command("check-vision").description(
@@ -8954,7 +9135,10 @@ bridgeCommand.command("translate-question").description("Translate a question dy
 });
 bridgeCommand.command("evaluate-answer").description(
   "Evaluate the learner's active-recall answer using the local LLM (JSON)"
-).requiredOption("--slug <slug>", "Token slug").requiredOption("--concept <concept>", "Target concept text").requiredOption("--domain <domain>", "Token domain").requiredOption("--bloom-level <level>", "Bloom taxonomy level").requiredOption("--question <question>", "Question prompt presented").requiredOption("--user-answer <answer>", "User's typed answer").option("--context <context>", "Optional token context details").option("--source-link <link>", "Optional source link").action(async (opts) => {
+).requiredOption("--slug <slug>", "Token slug").requiredOption("--concept <concept>", "Target concept text").requiredOption("--domain <domain>", "Token domain").requiredOption("--bloom-level <level>", "Bloom taxonomy level").requiredOption("--question <question>", "Question prompt presented").requiredOption("--user-answer <answer>", "User's typed answer").option("--context <context>", "Optional token context details").option("--source-link <link>", "Optional source link").option(
+  "--source-content <content>",
+  "Pre-resolved source reference content (skips re-fetch when set)"
+).action(async (opts) => {
   await withDb2(async (db) => {
     const isEnabled = await getSetting(db, "llm.enabled") === "true";
     if (!isEnabled) {
@@ -8965,8 +9149,8 @@ bridgeCommand.command("evaluate-answer").description(
       });
       return;
     }
-    let resolvedContextContent = null;
-    if (opts.sourceLink) {
+    let resolvedContextContent = opts.sourceContent ?? null;
+    if (resolvedContextContent == null && opts.sourceLink) {
       try {
         const resolved = await resolveReviewContext(opts.sourceLink);
         resolvedContextContent = resolved?.content ?? null;
@@ -8974,7 +9158,7 @@ bridgeCommand.command("evaluate-answer").description(
       }
     }
     try {
-      const evaluation = await evaluateAnswerViaLLM(db, {
+      const result = await evaluateAnswerViaLLM(db, {
         slug: opts.slug,
         concept: opts.concept,
         domain: opts.domain,
@@ -8984,7 +9168,11 @@ bridgeCommand.command("evaluate-answer").description(
         userAnswer: opts.userAnswer,
         sourceLinkContent: resolvedContextContent
       });
-      jsonOut2({ success: true, evaluation });
+      jsonOut2({
+        success: true,
+        evaluation: result.text,
+        evaluationModel: result.model
+      });
     } catch (err) {
       jsonOut2({
         success: false,
@@ -8998,11 +9186,12 @@ bridgeCommand.command("desktop-bootstrap").description("Initialize first-run des
   await withDb2(async (db) => {
     const userId = await ensureDefaultUser(db, opts.user);
     const { enabled, url, model, locale } = await getLlmConfig(db);
-    const { workspaceDir, skillLinks } = await ensureDesktopWorkspace(db);
+    const { workspaceDir, activeWorkspaceId, skillLinks } = await ensureDesktopWorkspace(db);
     jsonOut2({
       userId,
       locale,
       llm: { enabled, url, model },
+      activeWorkspaceId,
       workspaceDir,
       skillLinks
     });
@@ -9223,8 +9412,8 @@ bridgeCommand.command("serve").description("Start the persistent JSON-RPC stdin/
 });
 
 // src/cli/commands/card.ts
-import { Command as Command5 } from "commander";
-var cardCommand = new Command5("card").description(
+import { Command as Command3 } from "commander";
+var cardCommand = new Command3("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) => {
@@ -9422,9 +9611,9 @@ 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 Command6 } from "commander";
-var connectorCommand = new Command6("connector").description(
+import { input, password } from "@inquirer/prompts";
+import { Command as Command4 } from "commander";
+var connectorCommand = new Command4("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(
@@ -9443,10 +9632,10 @@ connectorCommand.command("setup").description("Configure a connector").argument(
     process.exit(1);
   }
   try {
-    const orgUrl = await input2({
+    const orgUrl = await input({
       message: "Organization URL (e.g. https://dev.azure.com/myorg):"
     });
-    const project = await input2({
+    const project = await input({
       message: "Project name:"
     });
     const pat = await password({
@@ -9536,8 +9725,16 @@ connectorCommand.command("sync").description("Verify the Turso cloud database co
 });
 async function setupTurso(urlArg, tokenArg, mode) {
   let db;
+  const arch = getSystemProfile().arch;
+  const isWindowsArm64 = process.platform === "win32" && arch === "arm64";
+  const effectiveMode = mode ?? (isWindowsArm64 ? "remote" : void 0);
+  if (!mode && isWindowsArm64) {
+    console.log(
+      "Detected Windows ARM64 \u2014 defaulting to remote (HTTP) mode.\n  The native libsql driver is not available on this architecture.\n  Remote mode uses the Turso HTTP API and works everywhere.\n"
+    );
+  }
   try {
-    const url = urlArg ?? await input2({
+    const url = urlArg ?? await input({
       message: "Turso database URL (e.g. libsql://my-db-user.turso.io):"
     });
     const token = tokenArg ?? await password({
@@ -9547,12 +9744,12 @@ async function setupTurso(urlArg, tokenArg, mode) {
       console.error("Both URL and token are required.");
       process.exit(1);
     }
-    setTursoCredentials(url, token, void 0, mode);
+    setTursoCredentials(url, token, void 0, effectiveMode);
     db = await openDatabaseWithSync({ initialize: true });
     await db.prepare("SELECT 1").get();
     await db.close();
     console.log(
-      `Turso cloud database configured and verified: ${url}` + (mode ? ` (mode: ${mode})` : "")
+      `Turso cloud database configured and verified: ${url}` + (effectiveMode ? ` (mode: ${effectiveMode})` : "")
     );
   } catch (err) {
     await db?.close();
@@ -9567,26 +9764,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 existsSync18, writeFileSync as writeFileSync9 } from "fs";
-import { join as join18 } from "path";
-import { Command as Command7 } from "commander";
+import { chmodSync as chmodSync2, existsSync as existsSync18, writeFileSync as writeFileSync8 } from "fs";
+import { join as join19 } from "path";
+import { Command as Command5 } from "commander";
 function installHook2() {
-  const gitDir = join18(process.cwd(), ".git");
+  const gitDir = join19(process.cwd(), ".git");
   if (!existsSync18(gitDir)) {
     console.error(
       "Error: Current directory is not the root of a Git repository."
     );
     process.exit(1);
   }
-  const hooksDir = join18(gitDir, "hooks");
-  const hookPath = join18(hooksDir, "post-commit");
+  const hooksDir = join19(gitDir, "hooks");
+  const hookPath = join19(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 {
-    writeFileSync9(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
+    writeFileSync8(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
     try {
       chmodSync2(hookPath, "755");
     } catch (_e) {
@@ -9599,7 +9796,7 @@ zam git-sync --commit HEAD --quiet
     process.exit(1);
   }
 }
-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) => {
+var gitSyncCommand = new Command5("git-sync").description("Sync learning cards with recent Git file modifications").option("--commit <hash>", "Git commit hash to check", "HEAD").option("--user <id>", "User ID (default: whoami)").option("--install", "Install git post-commit hook in current repo").option("--quiet", "Suppress verbose output").action(async (opts) => {
   if (opts.install) {
     installHook2();
     return;
@@ -9689,9 +9886,9 @@ ZAM Auto-Stale Complete: Scanned ${changedFiles.length} file(s).`
 
 // src/cli/commands/goal.ts
 import { existsSync as existsSync19, mkdirSync as mkdirSync11 } from "fs";
-import { resolve as resolve6 } from "path";
-import { input as input3 } from "@inquirer/prompts";
-import { Command as Command8 } from "commander";
+import { resolve as resolve5 } from "path";
+import { input as input2 } from "@inquirer/prompts";
+import { Command as Command6 } from "commander";
 async function resolveGoalsDir() {
   let goalsDir;
   let db;
@@ -9702,9 +9899,9 @@ async function resolveGoalsDir() {
   } finally {
     await db?.close();
   }
-  return goalsDir ? resolve6(goalsDir) : resolve6("goals");
+  return goalsDir ? resolve5(goalsDir) : resolve5("goals");
 }
-var goalCommand = new Command8("goal").description(
+var goalCommand = new Command6("goal").description(
   "Manage learning goals (markdown files)"
 );
 goalCommand.command("list").description("List all goals").option(
@@ -9823,11 +10020,11 @@ goalCommand.command("create").description("Create a new goal").option("--slug <s
   if (!slug || !title) {
     try {
       if (!title) {
-        title = await input3({ message: "Goal title:" });
+        title = await input2({ message: "Goal title:" });
       }
       if (!slug) {
         const suggested = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-        slug = await input3({
+        slug = await input2({
           message: "Goal slug (filename):",
           default: suggested
         });
@@ -9873,22 +10070,22 @@ goalCommand.command("status <slug> <status>").description("Update a goal's statu
 });
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync20, mkdirSync as mkdirSync12, writeFileSync as writeFileSync10 } from "fs";
+import { existsSync as existsSync20, mkdirSync as mkdirSync12, writeFileSync as writeFileSync9 } from "fs";
 import { homedir as homedir11 } from "os";
-import { join as join19, resolve as resolve7 } from "path";
-import { confirm as confirm2, input as input4 } from "@inquirer/prompts";
-import { Command as Command9 } from "commander";
+import { join as join20, resolve as resolve6 } from "path";
+import { confirm, input as input3 } from "@inquirer/prompts";
+import { Command as Command7 } 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) {
-  mkdirSync12(join19(workspaceDir, "beliefs"), { recursive: true });
-  mkdirSync12(join19(workspaceDir, "goals"), { recursive: true });
-  mkdirSync12(join19(workspaceDir, "skills"), { recursive: true });
-  const worldviewFile = join19(workspaceDir, "beliefs", "worldview.md");
+  mkdirSync12(join20(workspaceDir, "beliefs"), { recursive: true });
+  mkdirSync12(join20(workspaceDir, "goals"), { recursive: true });
+  mkdirSync12(join20(workspaceDir, "skills"), { recursive: true });
+  const worldviewFile = join20(workspaceDir, "beliefs", "worldview.md");
   if (!existsSync20(worldviewFile)) {
-    writeFileSync10(
+    writeFileSync9(
       worldviewFile,
       `# Personal Worldview
 
@@ -9900,9 +10097,9 @@ Here, I declare the core concepts and principles I want to master.
       "utf8"
     );
   }
-  const goalsFile = join19(workspaceDir, "goals", "goals.md");
+  const goalsFile = join20(workspaceDir, "goals", "goals.md");
   if (!existsSync20(goalsFile)) {
-    writeFileSync10(
+    writeFileSync9(
       goalsFile,
       `# Personal Goals
 
@@ -9914,7 +10111,7 @@ Here, I declare the core concepts and principles I want to master.
     );
   }
 }
-var initCommand = new Command9("init").description("Launch the guided interactive onboarding wizard").action(async () => {
+var initCommand = new Command7("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"
@@ -9924,9 +10121,9 @@ var initCommand = new Command9("init").description("Launch the guided interactiv
   );
   printLine();
   console.log("\n\x1B[1m[1/5] Setting up Local Workspace Sandbox\x1B[0m");
-  const defaultWorkspace = join19(HOME2, "Documents", "zam");
-  const workspacePath = resolve7(
-    await input4({
+  const defaultWorkspace = join20(HOME2, "Documents", "zam");
+  const workspacePath = resolve6(
+    await input3({
       message: "Choose your ZAM workspace directory:",
       default: defaultWorkspace
     })
@@ -9940,6 +10137,7 @@ var initCommand = new Command9("init").description("Launch the guided interactiv
       kind: "personal",
       path: workspacePath
     });
+    setActiveWorkspaceId("personal");
     console.log(
       `\x1B[32m\u2713 Local Sandbox created at: ${workspacePath}\x1B[0m`
     );
@@ -9970,7 +10168,7 @@ var initCommand = new Command9("init").description("Launch the guided interactiv
   \x1B[1mRecommendation:\x1B[0m ZAM suggests installing \x1B[32m${runnerLabel}\x1B[0m with \x1B[36m${profile.recommendedModel}\x1B[0m.`
   );
   console.log("\n\x1B[1m[3/5] Setting up Local LLM Runner\x1B[0m");
-  const proceedInstall = await confirm2({
+  const proceedInstall = await confirm({
     message: `Would you like ZAM to install and configure ${runnerLabel} automatically?`,
     default: true
   });
@@ -10007,7 +10205,7 @@ var initCommand = new Command9("init").description("Launch the guided interactiv
   let db;
   try {
     db = await openDatabaseWithSync({ initialize: true });
-    await setSetting(db, "personal.workspace_dir", workspacePath);
+    await deleteSetting(db, "personal.workspace_dir");
     const detectedLocale = detectSystemLocale();
     await setSetting(db, "system.locale", detectedLocale);
     console.log(
@@ -10038,7 +10236,7 @@ var initCommand = new Command9("init").description("Launch the guided interactiv
   console.log(
     "\n\x1B[1m[5/5] Wiring Developer Agents & Terminal Helpers\x1B[0m"
   );
-  const proceedHooks = await confirm2({
+  const proceedHooks = await confirm({
     message: "Distribute ZAM skills and install optional monitored-session shell helpers?",
     default: true
   });
@@ -10089,8 +10287,8 @@ var initCommand = new Command9("init").description("Launch the guided interactiv
 });
 
 // src/cli/commands/learn.ts
-import { input as input6 } from "@inquirer/prompts";
-import { Command as Command10 } from "commander";
+import { input as input5 } from "@inquirer/prompts";
+import { Command as Command8 } from "commander";
 
 // src/cli/learn-format.ts
 var BLOOM_VERBS3 = {
@@ -10139,7 +10337,7 @@ function formatReveal(input8) {
 }
 
 // src/cli/review-actions.ts
-import { confirm as confirm3, input as input5, select } from "@inquirer/prompts";
+import { confirm as confirm2, input as input4, select } from "@inquirer/prompts";
 async function runInteractiveReviewAction(inputData) {
   let currentItem = { ...inputData.item };
   while (true) {
@@ -10254,7 +10452,7 @@ async function runInteractiveReviewAction(inputData) {
       continue;
     }
     if (choice === "deprecate-token") {
-      const approved = await confirm3({
+      const approved = await confirm2({
         message: `Deprecate ${currentItem.slug} so it stops appearing in review queues?`,
         default: false
       });
@@ -10285,7 +10483,7 @@ async function runInteractiveReviewAction(inputData) {
       console.log(`  Session steps:         ${impact.session_steps}`);
       console.log(`  Sessions touched:      ${impact.sessions_touched}`);
       console.log(`  Agent skills updated:  ${impact.agent_skills}`);
-      const approved = await confirm3({
+      const approved = await confirm2({
         message: "Permanently delete this token and its dependent learning data?",
         default: false
       });
@@ -10310,7 +10508,7 @@ async function runInteractiveReviewAction(inputData) {
       );
       console.log(`Delete your card for ${currentItem.slug}?`);
       console.log(`  Review logs removed: ${impact.review_logs}`);
-      const approved = await confirm3({
+      const approved = await confirm2({
         message: "Delete only your card for this token?",
         default: false
       });
@@ -10348,21 +10546,21 @@ async function promptTokenEdit(token) {
   }
   switch (field) {
     case "concept": {
-      const concept = await input5({
+      const concept = await input4({
         message: "Concept:",
         default: token.concept
       });
       return concept === token.concept ? null : { concept };
     }
     case "domain": {
-      const domain = await input5({
+      const domain = await input4({
         message: "Domain (blank allowed):",
         default: token.domain
       });
       return domain === token.domain ? null : { domain };
     }
     case "context": {
-      const context = await input5({
+      const context = await input4({
         message: "Context (blank allowed):",
         default: token.context
       });
@@ -10403,14 +10601,14 @@ async function promptTokenEdit(token) {
       return mode === token.symbiosis_mode ? null : { symbiosis_mode: mode };
     }
     case "source_link": {
-      const link = await input5({
+      const link = await input4({
         message: "Source link (blank allowed):",
         default: token.source_link ?? ""
       });
       return link === token.source_link ? null : { source_link: link || null };
     }
     case "question": {
-      const question = await input5({
+      const question = await input4({
         message: "Recall question (blank allowed):",
         default: token.question ?? ""
       });
@@ -10428,7 +10626,7 @@ var STOP_WORDS = /* @__PURE__ */ new Set(["q", ":q", "quit", "stop"]);
 function isExitPrompt(err) {
   return err instanceof Error && err.name === "ExitPromptError";
 }
-var learnCommand = new Command10("learn").description(
+var learnCommand = new Command8("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;
@@ -10484,7 +10682,7 @@ ${t(locale, "welcome", { count: queue.items.length })}`);
             question: item.question
           });
           if (healed) {
-            resolvedQuestion = healed;
+            resolvedQuestion = healed.question;
           }
         } catch {
         }
@@ -10508,7 +10706,7 @@ ${"\u2500".repeat(50)}`);
   ${prompt.question}`);
       let answer;
       try {
-        answer = await input6({
+        answer = await input5({
           message: t(locale, "prompt_answer")
         });
       } catch (err) {
@@ -10549,7 +10747,8 @@ ${"\u2500".repeat(50)}`);
             `
   ${t(locale, "feedback_title", { line: "\u2500".repeat(34) })}`
           );
-          for (const line of evaluation.split("\n")) {
+          console.log(`  \x1B[2m[${evaluation.model}]\x1B[0m`);
+          for (const line of evaluation.text.split("\n")) {
             console.log(`  ${line}`);
           }
         } catch (err) {
@@ -10672,8 +10871,8 @@ learnCommand.command("open").description("Open a new terminal window running zam
 });
 
 // src/cli/commands/monitor.ts
-import { Command as Command11 } from "commander";
-var monitorCommand = new Command11("monitor").description(
+import { Command as Command9 } from "commander";
+var monitorCommand = new Command9("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(
@@ -10855,8 +11054,8 @@ monitorCommand.command("open").description("Open a new monitored terminal window
 });
 
 // src/cli/commands/observer.ts
-import { Command as Command12 } from "commander";
-var observerCommand = new Command12("observer").description(
+import { Command as Command10 } from "commander";
+var observerCommand = new Command10("observer").description(
   "Configure what the UI observer may capture (Layer 2 policy)"
 );
 function applyObserverListChange(current, entry, op) {
@@ -10918,9 +11117,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 dirname6, join as join20, resolve as resolve8 } from "path";
-import { Command as Command13 } from "commander";
+import { dirname as dirname6, resolve as resolve7 } from "path";
+import { Command as Command11 } from "commander";
 var C2 = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -10928,9 +11126,6 @@ var C2 = {
   dim: "\x1B[2m",
   green: "\x1B[32m"
 };
-function defaultPersonalDir() {
-  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}`;
   console.log(`${C2.bold}ZAM install profile${C2.reset}`);
@@ -10940,7 +11135,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 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) => {
+var profileCommand = new Command11("profile").description("Show or change this machine's ZAM install profile").option("--mode <mode>", "Set install mode: developer | default").option("--dir <path>", "Set the personal-content folder").option("--json", "Output as JSON").action(async (opts) => {
   if (opts.mode && opts.mode !== "developer" && opts.mode !== "default") {
     console.error(`Invalid --mode: ${opts.mode}. Use developer or default.`);
     process.exit(1);
@@ -10950,9 +11145,12 @@ var profileCommand = new Command13("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", resolve8(opts.dir));
+      await activateWorkspacePath(db, resolve7(opts.dir), {
+        kind: "personal",
+        label: "Personal"
+      });
     }
-    const personalDir = await getSetting(db, "personal.workspace_dir") || defaultPersonalDir();
+    const personalDir = (await ensureActiveWorkspace(db)).path;
     await db.close();
     db = void 0;
     const dbPath = getDefaultDbPath();
@@ -10977,120 +11175,8 @@ var profileCommand = new Command13("profile").description("Show or change this m
 
 // src/cli/commands/provider.ts
 import { password as password2 } from "@inquirer/prompts";
-import { Command as Command14 } from "commander";
-var VALID_API_FLAVORS = [
-  "chat-completions",
-  "anthropic-messages"
-];
-var VALID_ROLES = ["vision", "recall", "text"];
-function upsertProviderRecord(providers, name, patch) {
-  const merged = { ...providers[name] ?? {} };
-  if (patch.url !== void 0) merged.url = patch.url;
-  if (patch.model !== void 0) merged.model = patch.model;
-  if (patch.apiFlavor !== void 0) merged.apiFlavor = patch.apiFlavor;
-  if (patch.apiKeyRef !== void 0) merged.apiKeyRef = patch.apiKeyRef;
-  if (patch.label !== void 0) merged.label = patch.label;
-  if (patch.local !== void 0) merged.local = patch.local;
-  if (patch.runner !== void 0) merged.runner = patch.runner;
-  return { ...providers, [name]: merged };
-}
-function removeProviderRecord(providers, name) {
-  if (!(name in providers)) return { providers, removed: false };
-  const next = { ...providers };
-  delete next[name];
-  return { providers: next, removed: true };
-}
-function rolesReferencing(roles, name) {
-  return VALID_ROLES.filter((role) => {
-    const binding = roles[role];
-    return binding?.primary === name || binding?.fallback === name;
-  });
-}
-function bindRoleProviders(roles, role, primary, fallback) {
-  const binding = { primary };
-  if (fallback) binding.fallback = fallback;
-  return { ...roles, [role]: binding };
-}
-function maskSecret(key) {
-  return key.length <= 4 ? "\u2022\u2022\u2022\u2022" : `\u2026${key.slice(-4)}`;
-}
-function buildProviderListing(providers, hasKey) {
-  return Object.entries(providers).map(([name, rec]) => {
-    const apiFlavor = rec.apiFlavor ?? (rec.url ? inferApiFlavor(rec.url) : "chat-completions");
-    let keyState;
-    if (!rec.apiKeyRef) keyState = "none";
-    else keyState = hasKey(rec.apiKeyRef) ? "set" : "missing";
-    const row = {
-      name,
-      url: rec.url,
-      model: rec.model,
-      apiFlavor,
-      apiKeyRef: rec.apiKeyRef,
-      keyState
-    };
-    if (rec.label !== void 0) row.label = rec.label;
-    if (rec.local !== void 0) row.local = rec.local;
-    if (rec.runner !== void 0) row.runner = rec.runner;
-    return row;
-  });
-}
-function findOrphanKeyRefs(storedRefs, providers) {
-  const used = new Set(
-    Object.values(providers).map((rec) => rec.apiKeyRef).filter((ref) => !!ref)
-  );
-  return storedRefs.filter((ref) => !used.has(ref));
-}
-async function readJson(db, key, fallback) {
-  const raw = await getSetting(db, key);
-  if (!raw) return fallback;
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return fallback;
-  }
-}
-var readProviders = (db) => readJson(db, "llm.providers", {});
-var readRoles = (db) => readJson(db, "llm.roles", {});
-async function readScopedProviders(db, machine) {
-  if (machine) return getMachineAiConfig().providers ?? {};
-  if (!db)
-    throw new Error("Database is required for shared provider settings.");
-  return readProviders(db);
-}
-async function readScopedRoles(db, machine) {
-  if (machine) return getMachineAiConfig().roles ?? {};
-  if (!db)
-    throw new Error("Database is required for shared provider settings.");
-  return readRoles(db);
-}
-async function writeScopedProviders(db, machine, p) {
-  if (machine) {
-    const config = getMachineAiConfig();
-    saveMachineAiConfig({ ...config, providers: p });
-    return;
-  }
-  if (!db)
-    throw new Error("Database is required for shared provider settings.");
-  await setSetting(db, "llm.providers", JSON.stringify(p));
-}
-async function writeScopedRoles(db, machine, r) {
-  if (machine) {
-    const config = getMachineAiConfig();
-    saveMachineAiConfig({ ...config, roles: r });
-    return;
-  }
-  if (!db)
-    throw new Error("Database is required for shared provider settings.");
-  await setSetting(db, "llm.roles", JSON.stringify(r));
-}
-async function withProviderScope(machine, action) {
-  if (machine) {
-    await action(void 0);
-    return;
-  }
-  await withDb(action);
-}
-var providerCommand = new Command14("provider").description(
+import { Command as Command12 } from "commander";
+var providerCommand = new Command12("provider").description(
   "Configure role-based AI providers (url/model/flavor/key, per role)"
 );
 providerCommand.command("list").description("Show configured providers, role bindings, and key status").option("--json", "Output as JSON").option("--machine", "Read machine-local providers from ~/.zam/config.json").action(async (opts) => {
@@ -11325,8 +11411,8 @@ providerCommand.command("clear-key <ref>").description("Remove a stored API key"
 });
 
 // src/cli/commands/review.ts
-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) => {
+import { Command as Command13 } from "commander";
+var reviewCommand = new Command13("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();
@@ -11440,9 +11526,9 @@ ${"\u2550".repeat(50)}`);
 
 // src/cli/commands/session.ts
 import { readFileSync as readFileSync12 } from "fs";
-import { input as input7, select as select2 } from "@inquirer/prompts";
-import { Command as Command16 } from "commander";
-var sessionCommand = new Command16("session").description(
+import { input as input6, select as select2 } from "@inquirer/prompts";
+import { Command as Command14 } from "commander";
+var sessionCommand = new Command14("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(
@@ -11619,7 +11705,7 @@ async function selectTask() {
       console.log("No active work items found in Azure DevOps.");
     }
   }
-  return input7({ message: "Task description:" });
+  return input6({ message: "Task description:" });
 }
 var RATING_LABELS = {
   1: "Again",
@@ -11822,8 +11908,8 @@ sessionCommand.command("end").description("End a session and show summary").requ
 
 // src/cli/commands/settings.ts
 import { existsSync as existsSync21 } from "fs";
-import { Command as Command17 } from "commander";
-var settingsCommand = new Command17("settings").description(
+import { Command as Command15 } from "commander";
+var settingsCommand = new Command15("settings").description(
   "Manage user settings"
 );
 var BOOLEAN_SETTING_KEYS = /* @__PURE__ */ new Set(["llm.enabled", "llm.vision.enabled"]);
@@ -11994,12 +12080,108 @@ settingsCommand.command("repos").description("Show or set Personal, Team, and Or
         console.log(`  ${name.padEnd(9)}: \x1B[33m- Not Set\x1B[0m`);
       }
     }
-  });
-});
+  });
+});
+
+// src/cli/commands/setup.ts
+import { resolve as resolve8 } from "path";
+import { Command as Command16 } from "commander";
+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 activateMachineProviderConfig(db);
+    await db.close();
+    console.log(`  init  ${formatDatabaseInitTarget(target)}`);
+  } catch (err) {
+    const msg = err.message;
+    if (!msg.includes("already")) {
+      console.warn(`  warn  database init: ${msg}`);
+    } else {
+      console.log(`  skip  database already initialized`);
+    }
+  }
+}
+async function activateMachineProviderConfig(db) {
+  const machineAi = getMachineAiConfig();
+  const providerCount = Object.keys(machineAi.providers ?? {}).length;
+  const roleCount = Object.keys(machineAi.roles ?? {}).length;
+  if (providerCount === 0 && roleCount === 0) return;
+  if (await getSetting(db, "llm.enabled") !== void 0) return;
+  await setSetting(db, "llm.enabled", "true");
+  console.log(
+    `  activate  ${providerCount} machine-local provider(s) from ~/.zam/config.json`
+  );
+}
+var setupCommand = new Command16("setup").description(
+  "Link ZAM skill directories into this workspace and initialize the database"
+).option("--force", "replace an unmanaged existing ZAM skill directory", 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 = resolve8(opts.target ?? process.cwd());
+    const updateExistingInstructions = Boolean(opts.target) || opts.force;
+    console.log(
+      `Setting up ZAM in ${target}${opts.dryRun ? " (dry run)" : ""}
+`
+    );
+    wireSkills(target, agents, {
+      force: opts.force,
+      dryRun: opts.dryRun
+    });
+    await initDatabase(opts.skipInit || opts.dryRun);
+    if (agents.has("claude")) {
+      writeClaudeMd(opts.skipClaudeMd, target, {
+        dryRun: opts.dryRun,
+        updateExisting: updateExistingInstructions
+      });
+    }
+    if (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/Copilot/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(
+import { Command as Command17 } from "commander";
+var skillCommand = new Command17("skill").description(
   "Manage agent skill entries (task recipes)"
 );
 skillCommand.command("list").description("List all agent skills").option("--json", "Output as JSON").action(async (opts) => {
@@ -12084,10 +12266,9 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
 });
 
 // src/cli/commands/snapshot.ts
-import { existsSync as existsSync22, mkdirSync as mkdirSync13, readFileSync as readFileSync13, writeFileSync as writeFileSync11 } from "fs";
-import { homedir as homedir13 } from "os";
+import { existsSync as existsSync22, mkdirSync as mkdirSync13, readFileSync as readFileSync13, writeFileSync as writeFileSync10 } from "fs";
 import { dirname as dirname7, join as join21 } from "path";
-import { Command as Command19 } from "commander";
+import { Command as Command18 } from "commander";
 function defaultOutName() {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
   return `zam-snapshot-${stamp}.sql`;
@@ -12101,12 +12282,12 @@ function summarize(tables) {
   }
   return { total, nonEmpty };
 }
-var exportCmd = new Command19("export").description("Write a portable SQL-text snapshot of the database").option("--out <file>", "Output file (use - for stdout)").action(async (opts) => {
+var exportCmd = new Command18("export").description("Write a portable SQL-text snapshot of the database").option("--out <file>", "Output file (use - for stdout)").action(async (opts) => {
   let db;
   try {
     db = await openDatabaseWithSync({ initialize: true });
     const snapshot = await exportSnapshot(db);
-    const personalDir = await getSetting(db, "personal.workspace_dir") || join21(homedir13(), "Documents", "zam");
+    const personalDir = (await ensureActiveWorkspace(db)).path;
     await db.close();
     db = void 0;
     const manifest = verifySnapshot(snapshot);
@@ -12120,7 +12301,7 @@ var exportCmd = new Command19("export").description("Write a portable SQL-text s
     if (dir && dir !== "." && !existsSync22(dir)) {
       mkdirSync13(dir, { recursive: true });
     }
-    writeFileSync11(out, snapshot, "utf-8");
+    writeFileSync10(out, snapshot, "utf-8");
     console.log(`Snapshot written: ${out}`);
     console.log(
       `  ${total} row(s)${nonEmpty.length ? ` \u2014 ${nonEmpty.join(", ")}` : ""}`
@@ -12131,7 +12312,7 @@ var exportCmd = new Command19("export").description("Write a portable SQL-text s
     process.exit(1);
   }
 });
-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) => {
+var importCmd = new Command18("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 (!existsSync22(file)) {
@@ -12154,7 +12335,7 @@ var importCmd = new Command19("import").description("Restore a snapshot into the
     process.exit(1);
   }
 });
-var verifyCmd = new Command19("verify").description("Check a snapshot's manifest and checksum without importing").argument("<file>", "Snapshot file to verify").action((file) => {
+var verifyCmd = new Command18("verify").description("Check a snapshot's manifest and checksum without importing").argument("<file>", "Snapshot file to verify").action((file) => {
   try {
     if (!existsSync22(file)) {
       console.error(`Error: Snapshot file not found: ${file}`);
@@ -12172,11 +12353,11 @@ var verifyCmd = new Command19("verify").description("Check a snapshot's manifest
     process.exit(1);
   }
 });
-var snapshotCommand = new Command19("snapshot").description("Export, import, or verify a portable database snapshot").addCommand(exportCmd).addCommand(importCmd).addCommand(verifyCmd);
+var snapshotCommand = new Command18("snapshot").description("Export, import, or verify a portable database snapshot").addCommand(exportCmd).addCommand(importCmd).addCommand(verifyCmd);
 
 // src/cli/commands/stats.ts
-import { Command as Command20 } from "commander";
-var statsCommand = new Command20("stats").description("Show learning dashboard for a user").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").action(async (opts) => {
+import { Command as Command19 } from "commander";
+var statsCommand = new Command19("stats").description("Show learning dashboard for a user").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").action(async (opts) => {
   await withDb(async (db) => {
     const userId = await resolveUser(opts, db);
     const stats = await getUserStats(db, userId);
@@ -12212,8 +12393,8 @@ var statsCommand = new Command20("stats").description("Show learning dashboard f
 });
 
 // src/cli/commands/token.ts
-import { Command as Command21 } from "commander";
-var tokenCommand = new Command21("token").description(
+import { Command as Command20 } from "commander";
+var tokenCommand = new Command20("token").description(
   "Manage knowledge tokens"
 );
 tokenCommand.command("register").description("Register a new knowledge token").requiredOption("--slug <slug>", "Unique token slug").requiredOption("--concept <concept>", "Concept description").option("--domain <domain>", "Knowledge domain", "").option("--bloom <level>", "Bloom taxonomy level (1-5)", "1").option("--source-link <link>", "Source file path or reference URL", "").option("--question <question>", "Specific question prompt for recall", "").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
@@ -12501,10 +12682,10 @@ 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 existsSync23 } from "fs";
-import { homedir as homedir14 } from "os";
+import { homedir as homedir12 } from "os";
 import { dirname as dirname8, join as join22 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
-import { Command as Command22 } from "commander";
+import { Command as Command21 } from "commander";
 var C3 = {
   reset: "\x1B[0m",
   red: "\x1B[31m",
@@ -12551,7 +12732,7 @@ function findInstalledApp() {
     process.env.LOCALAPPDATA && join22(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
     process.env.ProgramFiles && join22(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
     process.env["ProgramFiles(x86)"] && join22(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
-  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join22(homedir14(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
+  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join22(homedir12(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
   return candidates.find((candidate) => candidate && existsSync23(candidate)) || null;
 }
 function runNpm(args, opts) {
@@ -12684,13 +12865,13 @@ function createShortcuts(appPath, repoRoot) {
     console.error(`${C3.red}\u2717 Could not create shortcuts.${C3.reset}`);
   }
 }
-var uiCommand = new Command22("ui").description("Launch the ZAM Desktop GUI (Active-Recall Studio)").option("--dev", "Run in hot-reload development mode (needs Rust)").option(
+var uiCommand = new Command21("ui").description("Launch the ZAM Desktop GUI (Active-Recall Studio)").option("--dev", "Run in hot-reload development mode (needs Rust)").option(
   "--build",
   "Build the native installer for your OS (needs Rust, one-time)"
 ).option("--shortcut", "Create Desktop + Start-menu shortcuts to the GUI").action((opts) => {
   const installedApp = findInstalledApp();
   if (!opts.dev && !opts.build && !opts.shortcut && installedApp) {
-    launchApp(installedApp, homedir14());
+    launchApp(installedApp, homedir12());
     return;
   }
   const desktopDir = findDesktopDir();
@@ -12791,8 +12972,8 @@ import { spawnSync as spawnSync2 } from "child_process";
 import { existsSync as existsSync24, readFileSync as readFileSync14, realpathSync as realpathSync2 } from "fs";
 import { dirname as dirname9, join as join23 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
-import { confirm as confirm4 } from "@inquirer/prompts";
-import { Command as Command23 } from "commander";
+import { confirm as confirm3 } from "@inquirer/prompts";
+import { Command as Command22 } from "commander";
 var GITHUB_REPO = "zam-os/zam";
 var CHANNELS = [
   "developer",
@@ -12820,273 +13001,647 @@ function currentVersion() {
     } catch {
     }
   }
-  return "0.0.0";
+  return "0.0.0";
+}
+function versionAt(dir) {
+  try {
+    const pkg2 = JSON.parse(
+      readFileSync14(join23(dir, "package.json"), "utf-8")
+    );
+    return pkg2.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function fetchLatestVersion(repo) {
+  const res = await fetch(
+    `https://api.github.com/repos/${repo}/releases/latest`,
+    {
+      headers: {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "zam-cli"
+      }
+    }
+  );
+  if (!res.ok) {
+    throw new Error(
+      `Could not reach the release server (HTTP ${res.status}). Pass --latest <version> to check offline.`
+    );
+  }
+  const data = await res.json();
+  if (!data.tag_name) throw new Error("No published release found yet.");
+  return data.tag_name;
+}
+function render2(decision) {
+  if (!decision.updateAvailable) {
+    console.log(
+      `${C4.green}\u2713${C4.reset} ZAM is up to date (${C4.cyan}${decision.currentVersion}${C4.reset}).`
+    );
+    return;
+  }
+  console.log(
+    `${C4.yellow}\u2191${C4.reset} ${C4.bold}Update available${C4.reset}: ${C4.dim}${decision.currentVersion}${C4.reset} \u2192 ${C4.cyan}${decision.latestVersion}${C4.reset}`
+  );
+  console.log(`  ${decision.reason}`);
+  if (decision.action === "run-command" || decision.action === "inform") {
+    console.log(`  Run: ${C4.cyan}${decision.command}${C4.reset}`);
+  } else if (decision.action === "self-update") {
+    console.log(
+      `  ${C4.dim}The desktop app can apply this update for you.${C4.reset}`
+    );
+  }
+}
+var checkCmd = new Command22("check").description("Check whether a newer ZAM has been released").option(
+  "--latest <version>",
+  "Compare against this version instead of fetching"
+).option("--channel <channel>", "Override the detected install channel").option("--json", "Output as JSON").action(
+  async (opts) => {
+    try {
+      if (opts.channel && !CHANNELS.includes(opts.channel)) {
+        console.error(
+          `Invalid --channel: ${opts.channel}. Use ${CHANNELS.join(", ")}.`
+        );
+        process.exit(1);
+      }
+      const current = currentVersion();
+      const latest = opts.latest ?? await fetchLatestVersion(GITHUB_REPO);
+      const channel = opts.channel ?? getInstallChannel();
+      const decision = decideUpdate({
+        currentVersion: current,
+        latestVersion: latest,
+        channel
+      });
+      if (opts.json) {
+        console.log(JSON.stringify(decision, null, 2));
+        return;
+      }
+      render2(decision);
+    } catch (err) {
+      console.error("Error:", err.message);
+      process.exit(1);
+    }
+  }
+);
+function findSourceRepo() {
+  let dir = realpathSync2(dirname9(fileURLToPath4(import.meta.url)));
+  let parent = dirname9(dir);
+  while (parent !== dir) {
+    if (existsSync24(join23(dir, ".git"))) return dir;
+    dir = parent;
+    parent = dirname9(dir);
+  }
+  return existsSync24(join23(dir, ".git")) ? dir : null;
+}
+function runGit(cwd, args, capture) {
+  const res = spawnSync2("git", args, {
+    cwd,
+    stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
+    encoding: "utf8"
+  });
+  return { ok: res.status === 0, out: (res.stdout ?? "").trim() };
+}
+function runNpm2(args, cwd) {
+  const res = spawnSync2("npm", args, {
+    cwd,
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+  return res.status ?? 1;
+}
+function runShell(command) {
+  const res = spawnSync2(command, { stdio: "inherit", shell: true });
+  return res.status === 0;
+}
+function applyDeveloperUpdate(force) {
+  if (!hasCommand("git")) {
+    console.error(`${C4.red}\u2717${C4.reset} git was not found on PATH.`);
+    process.exit(1);
+  }
+  const src = findSourceRepo();
+  if (!src) {
+    console.error(
+      `${C4.red}\u2717${C4.reset} Could not locate the ZAM source checkout to update.`
+    );
+    process.exit(1);
+  }
+  const status = runGit(src, ["status", "--porcelain"], true);
+  if (status.ok && status.out && !force) {
+    console.error(
+      `${C4.red}\u2717${C4.reset} The source checkout has uncommitted changes:
+${status.out}
+Commit or stash them, or re-run with ${C4.cyan}--force${C4.reset}.`
+    );
+    process.exit(1);
+  }
+  console.log(
+    `${C4.dim}\u2192 git pull --ff-only${C4.reset}  ${C4.dim}(${src})${C4.reset}`
+  );
+  if (!runGit(src, ["pull", "--ff-only"], false).ok) {
+    console.error(
+      `${C4.red}\u2717${C4.reset} git pull failed \u2014 the branch may have diverged or you are offline. Resolve it manually, then retry.`
+    );
+    process.exit(1);
+  }
+  console.log(`${C4.dim}\u2192 npm install${C4.reset}`);
+  if (runNpm2(["install"], src) !== 0) {
+    console.error(`${C4.red}\u2717${C4.reset} npm install failed.`);
+    process.exit(1);
+  }
+  console.log(`${C4.dim}\u2192 npm run build${C4.reset}`);
+  if (runNpm2(["run", "build"], src) !== 0) {
+    console.error(`${C4.red}\u2717${C4.reset} Build failed.`);
+    process.exit(1);
+  }
+  console.log(`${C4.dim}\u2192 zam setup --force${C4.reset}`);
+  const setup = spawnSync2(
+    process.execPath,
+    [join23(src, "dist", "cli", "index.js"), "setup", "--force"],
+    { cwd: process.cwd(), stdio: "inherit" }
+  );
+  if (setup.status !== 0) {
+    console.warn(
+      `${C4.yellow}\u26A0${C4.reset} Skill refresh reported a problem \u2014 run '${C4.cyan}zam setup --force${C4.reset}' here manually.`
+    );
+  }
+  console.log(
+    `
+${C4.green}\u2713${C4.reset} Updated to ${C4.cyan}${versionAt(src)}${C4.reset}. Restart your agent client (e.g. Claude Code) to load the refreshed ${C4.cyan}/zam${C4.reset} skill.`
+  );
+}
+async function applyUpdate(opts) {
+  try {
+    const current = currentVersion();
+    const latest = await fetchLatestVersion(GITHUB_REPO);
+    const channel = getInstallChannel();
+    const decision = decideUpdate({
+      currentVersion: current,
+      latestVersion: latest,
+      channel
+    });
+    if (!decision.updateAvailable) {
+      console.log(
+        `${C4.green}\u2713${C4.reset} ZAM is up to date (${C4.cyan}${current}${C4.reset}).`
+      );
+      return;
+    }
+    console.log(
+      `${C4.yellow}\u2191${C4.reset} ${C4.bold}Update available${C4.reset}: ${C4.dim}${current}${C4.reset} \u2192 ${C4.cyan}${latest}${C4.reset} ${C4.dim}(${channel} install)${C4.reset}`
+    );
+    for (const step of planUpdate(decision)) {
+      console.log(`  ${C4.dim}\u2022${C4.reset} ${step.label}`);
+    }
+    if (channel === "direct") {
+      console.log(
+        `
+${C4.dim}This install updates through the desktop app's signed updater \u2014 open ZAM Desktop to install ${latest}.${C4.reset}`
+      );
+      return;
+    }
+    if (!opts.yes) {
+      const ok = await confirm3({
+        message: "Apply this update?",
+        default: true
+      });
+      if (!ok) {
+        console.log("Aborted.");
+        return;
+      }
+    }
+    console.log();
+    if (channel === "winget" || channel === "homebrew") {
+      if (!decision.command || !runShell(decision.command)) process.exit(1);
+      return;
+    }
+    applyDeveloperUpdate(opts.force ?? false);
+  } catch (err) {
+    console.error("Error:", err.message);
+    process.exit(1);
+  }
+}
+var updateCommand = new Command22("update").description(
+  "Update ZAM to the latest release (use `update check` to only check)"
+).option("-y, --yes", "Apply without confirmation").option(
+  "--force",
+  "Update even if the source checkout has uncommitted changes"
+).action(async (opts) => {
+  await applyUpdate(opts);
+}).addCommand(checkCmd);
+
+// src/cli/commands/whoami.ts
+import { Command as Command23 } from "commander";
+var whoamiCommand = new Command23("whoami").description("Show or set the default user identity").option("--set <id>", "Set the default user ID").option("--clear", "Remove the default user ID").option("--json", "Output as JSON").action(async (opts) => {
+  await withDb(async (db) => {
+    if (opts.set) {
+      await setSetting(db, "user.id", opts.set);
+      if (opts.json) {
+        console.log(JSON.stringify({ userId: opts.set }));
+      } else {
+        console.log(`Default user set to: ${opts.set}`);
+      }
+      return;
+    }
+    if (opts.clear) {
+      const deleted = await deleteSetting(db, "user.id");
+      if (opts.json) {
+        console.log(JSON.stringify({ userId: null, cleared: deleted }));
+      } else if (deleted) {
+        console.log("Default user cleared.");
+      } else {
+        console.log("No default user was set.");
+      }
+      return;
+    }
+    const userId = await getSetting(db, "user.id");
+    if (opts.json) {
+      console.log(JSON.stringify({ userId: userId ?? null }));
+      return;
+    }
+    if (userId) {
+      console.log(userId);
+    } else {
+      console.log("No default user set. Use: zam whoami --set <id>");
+    }
+  });
+});
+
+// src/cli/commands/workspace.ts
+import { execFileSync as execFileSync4 } from "child_process";
+import { existsSync as existsSync25, writeFileSync as writeFileSync11 } from "fs";
+import { homedir as homedir13 } from "os";
+import { join as join24, resolve as resolve9 } from "path";
+import { confirm as confirm4, input as input7 } from "@inquirer/prompts";
+import { Command as Command24 } from "commander";
+function runGit2(cwd, args) {
+  try {
+    return execFileSync4("git", args, {
+      cwd,
+      stdio: "pipe",
+      encoding: "utf8"
+    }).trim();
+  } catch (err) {
+    throw new Error(`Git command failed: ${err.message}`);
+  }
 }
-function versionAt(dir) {
-  try {
-    const pkg2 = JSON.parse(
-      readFileSync14(join23(dir, "package.json"), "utf-8")
-    );
-    return pkg2.version ?? "unknown";
-  } catch {
-    return "unknown";
+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 Command24("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(", ")}.`
+  );
 }
-async function fetchLatestVersion(repo) {
-  const res = await fetch(
-    `https://api.github.com/repos/${repo}/releases/latest`,
-    {
-      headers: {
-        Accept: "application/vnd.github+json",
-        "User-Agent": "zam-cli"
-      }
-    }
+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(", ")}.`
   );
-  if (!res.ok) {
+}
+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(
-      `Could not reach the release server (HTTP ${res.status}). Pass --latest <version> to check offline.`
+      `Workspace "${id}" is not configured. Add it with: zam workspace add ${id} --path <dir>`
     );
   }
-  const data = await res.json();
-  if (!data.tag_name) throw new Error("No published release found yet.");
-  return data.tag_name;
+  return workspace;
 }
-function render2(decision) {
-  if (!decision.updateAvailable) {
-    console.log(
-      `${C4.green}\u2713${C4.reset} ZAM is up to date (${C4.cyan}${decision.currentVersion}${C4.reset}).`
-    );
-    return;
+function formatLinkHealth(id, health) {
+  switch (health) {
+    case "healthy":
+      return "ok";
+    case "needs-repair":
+      return `needs repair \u2014 run: zam workspace setup ${id}`;
+    case "unmanaged":
+      return `unmanaged skill dir \u2014 run: zam workspace setup ${id} --force`;
   }
-  console.log(
-    `${C4.yellow}\u2191${C4.reset} ${C4.bold}Update available${C4.reset}: ${C4.dim}${decision.currentVersion}${C4.reset} \u2192 ${C4.cyan}${decision.latestVersion}${C4.reset}`
+}
+workspaceCommand.command("list").description("List configured ZAM workspaces").option("--json", "Output as JSON").action((opts) => {
+  const workspaces = getConfiguredWorkspaces();
+  const agents = parseSetupAgents();
+  const linkHealth = Object.fromEntries(
+    workspaces.filter((workspace) => existsSync25(workspace.path)).map((workspace) => [
+      workspace.id,
+      summarizeSkillLinkHealth(inspectSkillLinks(workspace.path, agents))
+    ])
   );
-  console.log(`  ${decision.reason}`);
-  if (decision.action === "run-command" || decision.action === "inform") {
-    console.log(`  Run: ${C4.cyan}${decision.command}${C4.reset}`);
-  } else if (decision.action === "self-update") {
+  if (opts.json) {
+    console.log(JSON.stringify({ workspaces, linkHealth }, null, 2));
+    return;
+  }
+  console.log("Configured ZAM workspaces:\n");
+  if (workspaces.length === 0) {
     console.log(
-      `  ${C4.dim}The desktop app can apply this update for you.${C4.reset}`
+      "  (none) \u2014 add one: zam workspace add personal --path <dir>"
     );
+    return;
   }
-}
-var checkCmd = new Command23("check").description("Check whether a newer ZAM has been released").option(
-  "--latest <version>",
-  "Compare against this version instead of fetching"
-).option("--channel <channel>", "Override the detected install channel").option("--json", "Output as JSON").action(
-  async (opts) => {
-    try {
-      if (opts.channel && !CHANNELS.includes(opts.channel)) {
-        console.error(
-          `Invalid --channel: ${opts.channel}. Use ${CHANNELS.join(", ")}.`
-        );
-        process.exit(1);
-      }
-      const current = currentVersion();
-      const latest = opts.latest ?? await fetchLatestVersion(GITHUB_REPO);
-      const channel = opts.channel ?? getInstallChannel();
-      const decision = decideUpdate({
-        currentVersion: current,
-        latestVersion: latest,
-        channel
-      });
-      if (opts.json) {
-        console.log(JSON.stringify(decision, null, 2));
-        return;
-      }
-      render2(decision);
-    } catch (err) {
-      console.error("Error:", err.message);
+  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(", ")}`);
+    }
+    const health = linkHealth[workspace.id];
+    if (health) {
+      console.log(`      links: ${formatLinkHealth(workspace.id, health)}`);
+    }
+  }
+});
+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 = resolve9(String(opts.path));
+    if (!existsSync25(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 } : {}
+    };
+    wireSkills(path, parseSetupAgents());
+    upsertConfiguredWorkspace(workspace);
+    console.log(`Registered and linked workspace "${id}" at ${path}.`);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
   }
-);
-function findSourceRepo() {
-  let dir = realpathSync2(dirname9(fileURLToPath4(import.meta.url)));
-  let parent = dirname9(dir);
-  while (parent !== dir) {
-    if (existsSync24(join23(dir, ".git"))) return dir;
-    dir = parent;
-    parent = dirname9(dir);
+});
+workspaceCommand.command("remove <id>").description("Unregister a ZAM workspace without deleting its files").action((id) => {
+  const existing = getConfiguredWorkspaces().find((item) => item.id === id);
+  if (!existing) {
+    console.error(`Workspace "${id}" is not configured.`);
+    process.exit(1);
   }
-  return existsSync24(join23(dir, ".git")) ? dir : null;
-}
-function runGit2(cwd, args, capture) {
-  const res = spawnSync2("git", args, {
-    cwd,
-    stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
-    encoding: "utf8"
-  });
-  return { ok: res.status === 0, out: (res.stdout ?? "").trim() };
-}
-function runNpm2(args, cwd) {
-  const res = spawnSync2("npm", args, {
-    cwd,
-    stdio: "inherit",
-    shell: process.platform === "win32"
-  });
-  return res.status ?? 1;
-}
-function runShell(command) {
-  const res = spawnSync2(command, { stdio: "inherit", shell: true });
-  return res.status === 0;
-}
-function applyDeveloperUpdate(force) {
-  if (!hasCommand("git")) {
-    console.error(`${C4.red}\u2717${C4.reset} git was not found on PATH.`);
+  removeConfiguredWorkspace(id);
+  console.log(
+    `Unregistered workspace "${id}". Files in ${existing.path} were not changed.`
+  );
+});
+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)" : ""}
+`
+    );
+    wireSkills(workspace.path, agents, {
+      force: Boolean(opts.force),
+      dryRun: Boolean(opts.dryRun)
+    });
+    if (agents.has("claude")) {
+      writeClaudeMd(false, workspace.path, {
+        dryRun: Boolean(opts.dryRun),
+        updateExisting: true
+      });
+    }
+    if (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);
   }
-  const src = findSourceRepo();
-  if (!src) {
+});
+workspaceCommand.command("publish").description("Publish your local workspace sandbox to GitHub").action(async () => {
+  let db;
+  let workspaceDir = "";
+  try {
+    db = await openDatabase();
+    workspaceDir = (await ensureActiveWorkspace(db)).path;
+    await db.close();
+  } catch {
+    await db?.close();
+  }
+  if (!workspaceDir) {
     console.error(
-      `${C4.red}\u2717${C4.reset} Could not locate the ZAM source checkout to update.`
+      "\x1B[31m\u2717 No active workspace configured. Please run `zam init` first.\x1B[0m"
     );
     process.exit(1);
   }
-  const status = runGit2(src, ["status", "--porcelain"], true);
-  if (status.ok && status.out && !force) {
+  if (!existsSync25(workspaceDir)) {
     console.error(
-      `${C4.red}\u2717${C4.reset} The source checkout has uncommitted changes:
-${status.out}
-Commit or stash them, or re-run with ${C4.cyan}--force${C4.reset}.`
+      `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
     );
     process.exit(1);
   }
-  console.log(
-    `${C4.dim}\u2192 git pull --ff-only${C4.reset}  ${C4.dim}(${src})${C4.reset}`
-  );
-  if (!runGit2(src, ["pull", "--ff-only"], false).ok) {
+  console.log(`
+Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
+  if (!hasCommand("git")) {
     console.error(
-      `${C4.red}\u2717${C4.reset} git pull failed \u2014 the branch may have diverged or you are offline. Resolve it manually, then retry.`
+      "\x1B[31m\u2717 Git command was not found on this system. Please install Git first.\x1B[0m"
     );
     process.exit(1);
   }
-  console.log(`${C4.dim}\u2192 npm install${C4.reset}`);
-  if (runNpm2(["install"], src) !== 0) {
-    console.error(`${C4.red}\u2717${C4.reset} npm install failed.`);
-    process.exit(1);
+  const gitignorePath = join24(workspaceDir, ".gitignore");
+  if (!existsSync25(gitignorePath)) {
+    writeFileSync11(
+      gitignorePath,
+      "node_modules/\n.agent/\n.agents/\n.claude/\n.gemini/\n.goose/\n*.log\n",
+      "utf8"
+    );
   }
-  console.log(`${C4.dim}\u2192 npm run build${C4.reset}`);
-  if (runNpm2(["run", "build"], src) !== 0) {
-    console.error(`${C4.red}\u2717${C4.reset} Build failed.`);
-    process.exit(1);
+  const hasGitRepo = existsSync25(join24(workspaceDir, ".git"));
+  if (!hasGitRepo) {
+    console.log("Initializing local Git repository...");
+    runGit2(workspaceDir, ["init", "-b", "main"]);
+    runGit2(workspaceDir, ["add", "."]);
+    runGit2(workspaceDir, [
+      "commit",
+      "-m",
+      "chore: initial workspace sandbox bootstrap"
+    ]);
+    console.log("\x1B[32m\u2713 Local Git repository initialized.\x1B[0m");
+  } else {
+    console.log("Git repository is already initialized.");
   }
-  console.log(`${C4.dim}\u2192 zam setup --force${C4.reset}`);
-  const setup = spawnSync2(
-    process.execPath,
-    [join23(src, "dist", "cli", "index.js"), "setup", "--force"],
-    { cwd: process.cwd(), stdio: "inherit" }
-  );
-  if (setup.status !== 0) {
-    console.warn(
-      `${C4.yellow}\u26A0${C4.reset} Skill refresh reported a problem \u2014 run '${C4.cyan}zam setup --force${C4.reset}' here manually.`
-    );
+  const repoName = await input7({
+    message: "Choose a name for your GitHub repository:",
+    default: "zam-personal"
+  });
+  const isPrivate = await confirm4({
+    message: "Should the repository be private?",
+    default: true
+  });
+  const repoVisibility = isPrivate ? "--private" : "--public";
+  if (hasCommand("gh")) {
+    console.log("GitHub CLI detected! Automating repository creation...");
+    const proceedGh = await confirm4({
+      message: "Would you like ZAM to create the repository using the GitHub CLI?",
+      default: true
+    });
+    if (proceedGh) {
+      try {
+        console.log(`Creating GitHub repository ${repoName}...`);
+        execFileSync4("gh", ghRepoCreateArgs(repoName, repoVisibility), {
+          cwd: workspaceDir,
+          stdio: "inherit"
+        });
+        console.log(
+          "\n\x1B[32m\u2713 Successfully published workspace to GitHub!\x1B[0m"
+        );
+        process.exit(0);
+      } catch (err) {
+        console.warn(
+          `\x1B[33m\u26A0 GitHub CLI creation failed: ${err.message}\x1B[0m`
+        );
+      }
+    }
   }
   console.log(
-    `
-${C4.green}\u2713${C4.reset} Updated to ${C4.cyan}${versionAt(src)}${C4.reset}. Restart your agent client (e.g. Claude Code) to load the refreshed ${C4.cyan}/zam${C4.reset} skill.`
+    "\n\x1B[1mPlease create the repository manually on GitHub:\x1B[0m"
   );
-}
-async function applyUpdate(opts) {
-  try {
-    const current = currentVersion();
-    const latest = await fetchLatestVersion(GITHUB_REPO);
-    const channel = getInstallChannel();
-    const decision = decideUpdate({
-      currentVersion: current,
-      latestVersion: latest,
-      channel
-    });
-    if (!decision.updateAvailable) {
+  console.log("  1. Go to https://github.com/new");
+  console.log(`  2. Name it exactly: \x1B[36m${repoName}\x1B[0m`);
+  console.log(
+    `  3. Choose \x1B[36m${isPrivate ? "Private" : "Public"}\x1B[0m`
+  );
+  console.log(
+    "  4. Do NOT initialize it with README, .gitignore, or license"
+  );
+  console.log("  5. Click 'Create repository'\n");
+  const githubUrl = await input7({
+    message: "Paste the repository Git URL (e.g. git@github.com:user/repo.git):"
+  });
+  if (githubUrl) {
+    try {
+      console.log("Linking remote repository and pushing...");
+      let hasOrigin = false;
+      try {
+        runGit2(workspaceDir, ["remote", "get-url", "origin"]);
+        hasOrigin = true;
+      } catch {
+      }
+      runGit2(workspaceDir, gitRemoteArgs(githubUrl, hasOrigin));
+      runGit2(workspaceDir, ["push", "-u", "origin", "main"]);
       console.log(
-        `${C4.green}\u2713${C4.reset} ZAM is up to date (${C4.cyan}${current}${C4.reset}).`
+        "\x1B[32m\u2713 Successfully linked and pushed to GitHub!\x1B[0m"
+      );
+    } catch (err) {
+      console.error(
+        `\x1B[31m\u2717 Push failed: ${err.message}\x1B[0m`
       );
-      return;
-    }
-    console.log(
-      `${C4.yellow}\u2191${C4.reset} ${C4.bold}Update available${C4.reset}: ${C4.dim}${current}${C4.reset} \u2192 ${C4.cyan}${latest}${C4.reset} ${C4.dim}(${channel} install)${C4.reset}`
-    );
-    for (const step of planUpdate(decision)) {
-      console.log(`  ${C4.dim}\u2022${C4.reset} ${step.label}`);
-    }
-    if (channel === "direct") {
       console.log(
-        `
-${C4.dim}This install updates through the desktop app's signed updater \u2014 open ZAM Desktop to install ${latest}.${C4.reset}`
+        "You can push manually later using: git push -u origin main"
       );
-      return;
-    }
-    if (!opts.yes) {
-      const ok = await confirm4({
-        message: "Apply this update?",
-        default: true
-      });
-      if (!ok) {
-        console.log("Aborted.");
-        return;
-      }
     }
-    console.log();
-    if (channel === "winget" || channel === "homebrew") {
-      if (!decision.command || !runShell(decision.command)) process.exit(1);
+  }
+});
+workspaceCommand.command("data-dir").description("Print the ZAM data directory (database, credentials, config)").option("--json", "Output as JSON").action((opts) => {
+  const dir = join24(homedir13(), ".zam");
+  console.log(opts.json ? JSON.stringify({ dataDir: dir }) : dir);
+});
+workspaceCommand.command("backup").description("Back up the local ZAM database into your workspace").option(
+  "--dir <path>",
+  "Target directory (default: workspace dir, else ~/Documents/zam)"
+).option("--json", "Output as JSON").action(async (opts) => {
+  const target = getDatabaseTargetInfo();
+  if (target.kind !== "local") {
+    const reason = `The database is ${target.kind} (${target.location}); file backup applies only to a local database \u2014 your Turso remote is already the cloud backup.`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, reason }));
       return;
     }
-    applyDeveloperUpdate(opts.force ?? false);
-  } catch (err) {
-    console.error("Error:", err.message);
+    console.error(`\x1B[33m\u26A0 ${reason}\x1B[0m`);
     process.exit(1);
   }
-}
-var updateCommand = new Command23("update").description(
-  "Update ZAM to the latest release (use `update check` to only check)"
-).option("-y, --yes", "Apply without confirmation").option(
-  "--force",
-  "Update even if the source checkout has uncommitted changes"
-).action(async (opts) => {
-  await applyUpdate(opts);
-}).addCommand(checkCmd);
-
-// src/cli/commands/whoami.ts
-import { Command as Command24 } from "commander";
-var whoamiCommand = new Command24("whoami").description("Show or set the default user identity").option("--set <id>", "Set the default user ID").option("--clear", "Remove the default user ID").option("--json", "Output as JSON").action(async (opts) => {
-  await withDb(async (db) => {
-    if (opts.set) {
-      await setSetting(db, "user.id", opts.set);
-      if (opts.json) {
-        console.log(JSON.stringify({ userId: opts.set }));
-      } else {
-        console.log(`Default user set to: ${opts.set}`);
-      }
-      return;
-    }
-    if (opts.clear) {
-      const deleted = await deleteSetting(db, "user.id");
-      if (opts.json) {
-        console.log(JSON.stringify({ userId: null, cleared: deleted }));
-      } else if (deleted) {
-        console.log("Default user cleared.");
-      } else {
-        console.log("No default user was set.");
-      }
-      return;
-    }
-    const userId = await getSetting(db, "user.id");
+  let db;
+  try {
+    db = await openDatabase();
+    const workspaceDir = opts.dir || (await ensureActiveWorkspace(db)).path;
+    const dest = await backupDatabaseTo(db, workspaceDir);
     if (opts.json) {
-      console.log(JSON.stringify({ userId: userId ?? null }));
-      return;
+      console.log(JSON.stringify({ ok: true, path: dest }));
+    } else {
+      console.log(`\x1B[32m\u2713 Database backed up to ${dest}\x1B[0m`);
     }
-    if (userId) {
-      console.log(userId);
+  } catch (err) {
+    const reason = err.message;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, reason }));
     } else {
-      console.log("No default user set. Use: zam whoami --set <id>");
+      console.error(`\x1B[31m\u2717 Backup failed: ${reason}\x1B[0m`);
     }
-  });
+    process.exit(1);
+  } finally {
+    await db?.close();
+  }
 });
 
 // src/cli/index.ts
 var __dirname = dirname10(fileURLToPath5(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync15(join24(__dirname, "..", "..", "package.json"), "utf-8")
+  readFileSync15(join25(__dirname, "..", "..", "package.json"), "utf-8")
 );
 var program = new Command25();
 program.name("zam").description(