zam-core 0.5.0 → 0.5.2

package/dist/cli/index.js

@@ -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();
@@ -4477,6 +4492,13 @@ function upsertConfiguredWorkspace(workspace, path = defaultConfigPath()) {
   saveConfiguredWorkspaces(next, path);
   return next;
 }
+function removeConfiguredWorkspace(id, path = defaultConfigPath()) {
+  const next = getConfiguredWorkspaces(path).filter(
+    (workspace) => workspace.id !== id
+  );
+  saveConfiguredWorkspaces(next, path);
+  return next;
+}
 function detectSyncProvider(dir) {
   const p = dir.toLowerCase();
   if (p.includes("onedrive")) return "OneDrive";
@@ -5352,15 +5374,37 @@ var agentCommand = new Command("agent").description("Provision and inspect the a
 // src/cli/commands/bridge.ts
 import { execFileSync as execFileSync4 } from "child_process";
 import { randomBytes as randomBytes2 } from "crypto";
-import { existsSync as existsSync17, readdirSync as readdirSync2, readFileSync as readFileSync11, rmSync as rmSync2 } from "fs";
+import {
+  existsSync as existsSync17,
+  mkdirSync as mkdirSync10,
+  readdirSync as readdirSync3,
+  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 { Command as Command5 } 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) {
@@ -5471,6 +5515,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 } : {}
   };
 }
@@ -5553,10 +5598,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";
@@ -5576,31 +5618,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.
@@ -5630,51 +5677,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) {
@@ -5747,6 +5802,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((resolve9) => setTimeout(resolve9, 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");
@@ -5848,13 +6004,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";
@@ -5876,7 +6027,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 {
@@ -5892,8 +6071,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";
@@ -5914,8 +6093,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") {
@@ -5974,7 +6153,7 @@ async function startLocalRunner(url, model, locale) {
   let attempts = 0;
   const dotsPerLine = 30;
   while (true) {
-    await new Promise((resolve8) => setTimeout(resolve8, 500));
+    await new Promise((resolve9) => setTimeout(resolve9, 500));
     if (await isLlmOnline(url)) {
       if (attempts > 0) process.stdout.write("\n");
       return true;
@@ -5999,105 +6178,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 {
@@ -6129,8 +6242,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
   const dotsPerLine = 30;
   while (true) {
     let timeoutId;
-    const timeoutPromise = new Promise((resolve8) => {
-      timeoutId = setTimeout(() => resolve8("timeout"), timeoutMs);
+    const timeoutPromise = new Promise((resolve9) => {
+      timeoutId = setTimeout(() => resolve9("timeout"), timeoutMs);
     });
     const dotsInterval = setInterval(() => {
       process.stdout.write(".");
@@ -6187,15 +6300,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;
 }
@@ -6240,25 +6360,25 @@ async function observeUiSnapshotViaLLM(db, input8) {
   const imageUrls = [];
   const isVideo = /\.(mp4|mov|m4v|avi|mkv|webm)$/i.test(input8.imagePath);
   if (isVideo) {
-    const { mkdirSync: mkdirSync13, readdirSync: readdirSync3, rmSync: rmSync3 } = await import("fs");
+    const { mkdirSync: mkdirSync14, readdirSync: readdirSync4, rmSync: rmSync4 } = await import("fs");
     const { execSync: execSync6 } = await import("child_process");
     const tempDir = join14(
       tmpdir2(),
       `zam-frames-${randomBytes(4).toString("hex")}`
     );
-    mkdirSync13(tempDir, { recursive: true });
+    mkdirSync14(tempDir, { recursive: true });
     try {
       execSync6(
         `ffmpeg -i "${input8.imagePath}" -vf "fps=1/3,scale=1280:-1" -vsync vfr "${tempDir}/frame_%03d.png"`,
         { stdio: "ignore" }
       );
-      let files = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
+      let files = readdirSync4(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 = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
+        files = readdirSync4(tempDir).filter((f) => f.endsWith(".png")).sort();
       }
       const maxFrames = cfg.maxFrames ?? 100;
       let sampledFiles = files;
@@ -6280,7 +6400,7 @@ async function observeUiSnapshotViaLLM(db, input8) {
       }
     } finally {
       try {
-        rmSync3(tempDir, { recursive: true, force: true });
+        rmSync4(tempDir, { recursive: true, force: true });
       } catch {
       }
     }
@@ -6403,7 +6523,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,
@@ -6459,7 +6579,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: [
         {
@@ -6614,26 +6734,9 @@ 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;
-}
-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);
-}
+// src/cli/commands/provider.ts
+import { password } from "@inquirer/prompts";
+import { Command as Command2 } from "commander";
 
 // src/cli/commands/shared/db.ts
 function defaultErrorHandler(message) {
@@ -6655,717 +6758,1187 @@ function jsonOut(data) {
   console.log(JSON.stringify(data, null, 2));
 }
 
-// src/cli/commands/workspace.ts
-import { execFileSync as execFileSync3 } from "child_process";
-import { existsSync as existsSync16, mkdirSync as mkdirSync9, writeFileSync as writeFileSync8 } from "fs";
-import { homedir as homedir9 } from "os";
-import { join as join16, resolve as resolve4 } from "path";
-import { confirm, input } from "@inquirer/prompts";
-import { Command as Command3 } from "commander";
-
-// src/cli/commands/setup.ts
-import {
-  copyFileSync as copyFileSync2,
-  existsSync as existsSync15,
-  mkdirSync as mkdirSync8,
-  readFileSync as readFileSync10,
-  writeFileSync as writeFileSync7
-} from "fs";
-import { basename as basename4, dirname as dirname5, join as join15, resolve as resolve3 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { Command as Command2 } from "commander";
-var packageRoot = [
-  fileURLToPath2(new URL("../..", import.meta.url)),
-  fileURLToPath2(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync15(join15(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
-var ALL_SETUP_AGENTS = ["claude", "copilot", "codex", "agent"];
-var SKILL_PAIRS = [
-  {
-    from: join15(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
-    to: join15(".claude", "skills", "zam", "SKILL.md"),
-    agents: ["claude"]
-  },
-  {
-    from: join15(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
-    to: join15(".agent", "skills", "zam", "SKILL.md"),
-    agents: ["agent"]
-  },
-  {
-    from: join15(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
-    to: join15(".agents", "skills", "zam", "SKILL.md"),
-    agents: ["copilot", "codex"]
-  }
+// src/cli/commands/provider.ts
+var VALID_API_FLAVORS = [
+  "chat-completions",
+  "anthropic-messages"
 ];
-function parseSetupAgents(value) {
-  if (!value || value.trim().toLowerCase() === "all") {
-    return new Set(ALL_SETUP_AGENTS);
-  }
-  const aliases = {
-    claude: ["claude"],
-    copilot: ["copilot"],
-    codex: ["codex"],
-    agent: ["agent"],
-    opencode: ["agent"]
-  };
-  const selected = /* @__PURE__ */ new Set();
-  for (const raw of value.split(",")) {
-    const key = raw.trim().toLowerCase();
-    const mapped = aliases[key];
-    if (!mapped) {
-      throw new Error(
-        `Unknown agent "${raw}". Use: all, claude, copilot, codex, agent.`
-      );
-    }
-    for (const item of mapped) selected.add(item);
-  }
-  return selected;
+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 copySkills(force, cwd = process.cwd(), agents = parseSetupAgents(), dryRun = false) {
-  let anyAction = false;
-  for (const { from, to, agents: pairAgents } of SKILL_PAIRS) {
-    if (!pairAgents.some((agent) => agents.has(agent))) continue;
-    const dest = join15(cwd, to);
-    if (!existsSync15(from)) {
-      console.warn(`  warn  source not found, skipping: ${from}`);
-      continue;
-    }
-    if (existsSync15(dest) && !force) {
-      console.log(`  skip  ${to} (already present \xE2\u20AC\u201D use --force to update)`);
-      continue;
-    }
-    if (dryRun) {
-      console.log(`  would copy  ${to}`);
-      anyAction = true;
-      continue;
-    }
-    mkdirSync8(dirname5(dest), { recursive: true });
-    copyFileSync2(from, dest);
-    console.log(`  copy  ${to}`);
-    anyAction = true;
-  }
-  if (!anyAction && !force) {
-    console.log(
-      "\nSkill files are already up to date. Run with --force to overwrite."
-    );
-  }
+function removeProviderRecord(providers, name) {
+  if (!(name in providers)) return { providers, removed: false };
+  const next = { ...providers };
+  delete next[name];
+  return { providers: next, removed: true };
 }
-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 rolesReferencing(roles, name) {
+  return VALID_ROLES.filter((role) => {
+    const binding = roles[role];
+    return binding?.primary === name || binding?.fallback === name;
+  });
 }
-async function initDatabase(skipInit) {
-  if (skipInit) return;
+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 {
-    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`);
-    }
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
   }
 }
-var ZAM_BLOCK_START = "<!-- ZAM:START -->";
-var ZAM_BLOCK_END = "<!-- ZAM:END -->";
-function upsertMarkedBlock(dest, blockBody, dryRun) {
-  const block = `${ZAM_BLOCK_START}
-${blockBody.trim()}
-${ZAM_BLOCK_END}`;
-  if (!existsSync15(dest)) {
-    if (!dryRun) {
-      mkdirSync8(dirname5(dest), { recursive: true });
-      writeFileSync7(dest, `${block}
-`, "utf8");
-    }
-    return "write";
-  }
-  const existing = readFileSync10(dest, "utf8");
-  if (existing.includes(block)) return "skip";
-  const start = existing.indexOf(ZAM_BLOCK_START);
-  const end = existing.indexOf(ZAM_BLOCK_END);
-  const next = start >= 0 && end > start ? `${existing.slice(0, start)}${block}${existing.slice(end + ZAM_BLOCK_END.length)}` : `${existing.trimEnd()}
-
-${block}
-`;
-  if (!dryRun) writeFileSync7(dest, next, "utf8");
-  return start >= 0 && end > start ? "update" : "write";
+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);
 }
-function logInstructionAction(action, label, dryRun) {
-  if (action === "skip") {
-    console.log(`  skip  ${label} (ZAM block already present)`);
-  } else {
-    console.log(`  ${dryRun ? "would " : ""}${action} ${label}`);
+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));
 }
-function writeClaudeMd(skipClaudeMd, cwd = process.cwd(), opts = {}) {
-  if (skipClaudeMd) return;
-  const dest = join15(cwd, "CLAUDE.md");
-  if (existsSync15(dest)) {
-    if (!opts.updateExisting) {
-      console.log(`  skip  CLAUDE.md (already present)`);
-      return;
-    }
-    const action = upsertMarkedBlock(
-      dest,
-      `## ZAM learning sessions
-
-ZAM is available in this repository. Use the \`zam\` skill in Claude Code to turn real work into an observed learning session with active recall and FSRS scheduling.
-
-- Skill files live under \`.claude/skills/zam/\`.
-- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
-- Run \`zam setup --target . --agents claude --force\` after upgrading ZAM to refresh the skill.`,
-      Boolean(opts.dryRun)
-    );
-    logInstructionAction(action, "CLAUDE.md", Boolean(opts.dryRun));
+async function writeScopedRoles(db, machine, r) {
+  if (machine) {
+    const config = getMachineAiConfig();
+    saveMachineAiConfig({ ...config, roles: r });
     return;
   }
-  const name = basename4(cwd);
-  const content = `# ZAM Personal Kernel \xE2\u20AC\u201D ${name}
-
-This is a ZAM personal instance. ZAM builds lasting skills through spaced
-repetition during real work \xE2\u20AC\u201D not separate study sessions.
-
-## First time here?
-Run \`/setup\` in Claude Code or Gemini CLI to complete first-time setup.
-
-## Regular use
-Run \`/zam\` to start a learning session on whatever you are working on.
-
-## What lives here
-- \`beliefs/\` \xE2\u20AC\u201D your worldview, approved by git commit
-- \`goals/\` \xE2\u20AC\u201D your objectives, decomposed into tasks and learning tokens
-
-## Fast-changing data
-Learning tokens, cards, and review history live in local SQLite by default.
-Use \`zam connector setup turso\` to store cloud credentials in
-\`~/.zam/credentials.json\` and use a Turso database across machines.
-`;
-  if (opts.dryRun) {
-    console.log(`  would write CLAUDE.md`);
-  } else {
-    writeFileSync7(dest, content, "utf8");
-    console.log(`  write CLAUDE.md`);
+  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);
 }
-function writeAgentsMd(skipAgentsMd, cwd = process.cwd(), opts = {}) {
-  if (skipAgentsMd) return;
-  const dest = join15(cwd, "AGENTS.md");
-  if (existsSync15(dest)) {
-    if (!opts.updateExisting) {
-      console.log(`  skip  AGENTS.md (already present)`);
+var providerCommand = new Command2("provider").description(
+  "Configure role-based AI providers (url/model/flavor/key, per role)"
+);
+providerCommand.command("list").description("Show configured providers, role bindings, and key status").option("--json", "Output as JSON").option("--machine", "Read machine-local providers from ~/.zam/config.json").action(async (opts) => {
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const roles = await readScopedRoles(db, machine);
+    const rows = buildProviderListing(
+      providers,
+      (ref) => getProviderApiKey(ref) !== null
+    );
+    const orphans = findOrphanKeyRefs(listProviderApiKeyRefs(), providers);
+    if (opts.json) {
+      console.log(
+        JSON.stringify(
+          {
+            scope: machine ? "machine" : "shared",
+            providers: rows,
+            roles,
+            orphans
+          },
+          null,
+          2
+        )
+      );
       return;
     }
-    const action = upsertMarkedBlock(
-      dest,
-      `## ZAM learning sessions
-
-ZAM is available in this repository. Select the \`zam\` skill through \`/skills\` or invoke \`$zam\` where supported to turn real work into an observed learning session with active recall and FSRS scheduling.
-
-- Skill files live under \`.agents/skills/zam/\`.
-- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
-- Run \`zam setup --target . --agents copilot,codex --force\` after upgrading ZAM to refresh the skill.`,
-      Boolean(opts.dryRun)
+    console.log(
+      `Providers (${opts.machine ? "~/.zam/config.json ai.providers" : "llm.providers"}):
+`
     );
-    logInstructionAction(action, "AGENTS.md", Boolean(opts.dryRun));
-    return;
-  }
-  const name = basename4(cwd);
-  const content = `# ZAM Personal Kernel - ${name}
-
-This is a ZAM personal instance. ZAM builds lasting skills through spaced
-repetition during real work, not separate study sessions.
-
-## First time here?
-Run \`zam setup\` from the shell. When this repository includes
-\`.agents/skills/setup/\`, you can instead select \`setup\` through \`/skills\`
-or invoke \`$setup\`.
-
-## Regular use
-Select the \`zam\` skill through \`/skills\` or invoke \`$zam\` to start a
-learning session on whatever you are working on.
-
-## What lives here
-- \`beliefs/\` - your worldview, approved by git commit
-- \`goals/\` - your objectives, decomposed into tasks and learning tokens
-
-## Fast-changing data
-Learning tokens, cards, and review history live in local SQLite by default.
-Use \`zam connector setup turso\` to store cloud credentials in
-\`~/.zam/credentials.json\` and use a Turso database across machines.
-
-## Codex skills
-Codex discovers repository skills under \`.agents/skills/\`. Run
-\`zam setup --force\` after upgrading \`zam-core\` to refresh them.
-`;
-  if (opts.dryRun) {
-    console.log(`  would write AGENTS.md`);
-  } else {
-    writeFileSync7(dest, content, "utf8");
-    console.log(`  write AGENTS.md`);
-  }
-}
-function writeCopilotInstructions(cwd = process.cwd(), opts = {}) {
-  const dest = join15(cwd, ".github", "copilot-instructions.md");
-  const action = upsertMarkedBlock(
-    dest,
-    `## ZAM learning sessions
-
-ZAM is available in this repository through \`.agents/skills/zam/\`. Use the \`zam\` skill from Copilot-compatible skill selection surfaces to turn real work into an observed learning session with active recall and FSRS scheduling.
-
-- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
-- Run \`zam setup --target . --agents copilot --force\` after upgrading ZAM to refresh the skill.`,
-    Boolean(opts.dryRun)
-  );
-  logInstructionAction(
-    action,
-    ".github/copilot-instructions.md",
-    Boolean(opts.dryRun)
-  );
-}
-var setupCommand = new Command2("setup").description(
-  "Distribute ZAM skill files into this personal instance and initialize the database"
+    if (rows.length === 0) {
+      console.log(
+        "  (none) \u2014 add one: zam provider add <name> --url <url> --model <model>"
+      );
+    } else {
+      for (const row of rows) {
+        const key = row.keyState === "set" ? "\x1B[32mkey \u2713\x1B[0m" : row.keyState === "missing" ? `\x1B[31mkey \u2717 (set: zam provider set-key ${row.apiKeyRef})\x1B[0m` : "\x1B[90mno key\x1B[0m";
+        console.log(`  \x1B[36m${row.name.padEnd(12)}\x1B[0m ${key}`);
+        console.log(`      url:    ${row.url ?? "(inherits llm.url)"}`);
+        console.log(`      model:  ${row.model ?? "(inherits llm.model)"}`);
+        console.log(`      flavor: ${row.apiFlavor}`);
+        if (row.label) console.log(`      label:  ${row.label}`);
+        if (row.local !== void 0) {
+          console.log(`      local:  ${row.local ? "yes" : "no"}`);
+        }
+        if (row.runner) console.log(`      runner: ${row.runner}`);
+        if (row.apiKeyRef) console.log(`      key-ref: ${row.apiKeyRef}`);
+      }
+    }
+    console.log("\nRoles (llm.roles):\n");
+    for (const role of VALID_ROLES) {
+      const binding = roles[role];
+      if (!binding?.primary) {
+        console.log(`  ${role.padEnd(7)} \x1B[90m(unset)\x1B[0m`);
+      } else {
+        const fb = binding.fallback ? ` \u2192 fallback: ${binding.fallback}` : "";
+        console.log(`  ${role.padEnd(7)} primary: ${binding.primary}${fb}`);
+      }
+    }
+    if (orphans.length > 0) {
+      console.log(
+        `
+\x1B[33mOrphan keys (stored but unreferenced):\x1B[0m ${orphans.join(", ")}`
+      );
+    }
+  });
+});
+providerCommand.command("add <name>").description("Add or update a provider record in llm.providers").option("--label <label>", "Human-readable provider label").option("--url <url>", "Endpoint base URL (e.g. https://api.deepseek.com/v1)").option("--model <model>", "Model id (e.g. deepseek-v4-flash)").option("--local", "Mark this provider as a local/on-device endpoint").option(
+  "--runner <runner>",
+  "Local runner hint (flm, foundry-local, ollama, ...)"
 ).option(
-  "--force",
-  "overwrite existing skill files (use after upgrading zam)",
-  false
-).option("--skip-init", "skip database initialization", false).option("--skip-claude-md", "skip CLAUDE.md generation", false).option("--skip-agents-md", "skip AGENTS.md generation", false).option("--target <path>", "repository/workspace directory to set up").option(
-  "--agents <list>",
-  "comma-separated agents to wire: all, claude, copilot, codex, agent"
+  "--flavor <flavor>",
+  `Wire protocol: ${VALID_API_FLAVORS.join(" | ")} (default: inferred from URL)`
 ).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}`);
+  "--key-ref <ref>",
+  "Credential reference for the API key (default: <name> when --key is given)"
+).option(
+  "--key <value>",
+  "Store this API key now (prefer `set-key` to keep it out of shell history)"
+).option("--machine", "Store this provider in ~/.zam/config.json").action(async (name, opts) => {
+  let apiFlavor;
+  if (opts.flavor) {
+    if (!VALID_API_FLAVORS.includes(opts.flavor)) {
+      console.error(
+        `Invalid --flavor: ${opts.flavor}. Use ${VALID_API_FLAVORS.join(" or ")}.`
+      );
       process.exit(1);
     }
-    const target = resolve3(opts.target ?? process.cwd());
-    const updateExistingInstructions = Boolean(opts.target) || opts.force;
+    apiFlavor = opts.flavor;
+  }
+  const apiKeyRef = opts.keyRef ?? (opts.key ? name : void 0);
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const next = upsertProviderRecord(providers, name, {
+      label: opts.label,
+      url: opts.url,
+      model: opts.model,
+      apiFlavor,
+      apiKeyRef,
+      local: opts.local ? true : void 0,
+      runner: opts.runner
+    });
+    await writeScopedProviders(db, machine, next);
+    if (opts.key && apiKeyRef) setProviderApiKey(apiKeyRef, opts.key);
+    const rec = next[name];
     console.log(
-      `Setting up ZAM in ${target}${opts.dryRun ? " (dry run)" : ""}
-`
+      `Provider "${name}" saved (${machine ? "machine-local" : "shared"}):`
     );
-    copySkills(opts.force, target, agents, opts.dryRun);
-    await initDatabase(opts.skipInit || opts.dryRun);
-    if (agents.has("claude")) {
-      writeClaudeMd(opts.skipClaudeMd, target, {
-        dryRun: opts.dryRun,
-        updateExisting: updateExistingInstructions
-      });
+    console.log(`  url:     ${rec.url ?? "(inherits llm.url)"}`);
+    console.log(`  model:   ${rec.model ?? "(inherits llm.model)"}`);
+    if (rec.label) console.log(`  label:   ${rec.label}`);
+    if (rec.local !== void 0) {
+      console.log(`  local:   ${rec.local ? "yes" : "no"}`);
     }
-    if (agents.has("copilot") || agents.has("codex") || agents.has("agent")) {
-      writeAgentsMd(opts.skipAgentsMd, target, {
-        dryRun: opts.dryRun,
-        updateExisting: updateExistingInstructions
-      });
+    if (rec.runner) console.log(`  runner:  ${rec.runner}`);
+    console.log(
+      `  flavor:  ${rec.apiFlavor ?? `${rec.url ? inferApiFlavor(rec.url) : "chat-completions"} (inferred)`}`
+    );
+    console.log(`  key-ref: ${rec.apiKeyRef ?? "(none \u2014 uses default key)"}`);
+    if (opts.key) {
+      console.log(`  key:     stored (${maskSecret(opts.key)})`);
+    } else if (rec.apiKeyRef && getProviderApiKey(rec.apiKeyRef) === null) {
+      console.log(
+        `
+  \u26A0 No key stored for "${rec.apiKeyRef}". Run: zam provider set-key ${rec.apiKeyRef}`
+      );
     }
-    if (agents.has("copilot") && (opts.target || opts.agents)) {
-      writeCopilotInstructions(target, {
-        dryRun: opts.dryRun,
-        updateExisting: updateExistingInstructions
-      });
+    if (!rec.url) {
+      console.log(
+        "\n  \u26A0 No --url set; this provider inherits the base llm.url."
+      );
     }
     console.log(
-      "\nDone. Run `zam whoami --set <your-id>` to set your identity. Start the `zam` skill with `/zam` in Claude/Gemini-compatible clients or `$zam` (or `/skills`) in Codex."
+      `
+Bind it to a role: zam provider use recall --primary ${name}`
+    );
+  });
+});
+providerCommand.command("remove <name>").description("Remove a provider record from llm.providers").option("--machine", "Remove from ~/.zam/config.json instead of the DB").action(async (name, opts) => {
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const { providers: next, removed } = removeProviderRecord(
+      providers,
+      name
+    );
+    if (!removed) {
+      console.log(`No such provider: ${name}`);
+      return;
+    }
+    await writeScopedProviders(db, machine, next);
+    console.log(
+      `Removed provider "${name}" (${machine ? "machine-local" : "shared"}).`
+    );
+    const referencing = rolesReferencing(
+      await readScopedRoles(db, machine),
+      name
     );
+    if (referencing.length > 0) {
+      console.log(
+        `  \u26A0 Still referenced by role(s): ${referencing.join(", ")} \u2014 rebind with: zam provider use <role> --primary <name>`
+      );
+    }
+  });
+});
+providerCommand.command("use <role>").description(`Bind providers to a role (${VALID_ROLES.join(" | ")})`).option("--primary <name>", "Primary provider").option("--fallback <name>", "Fallback provider (optional)").option("--machine", "Bind the role in ~/.zam/config.json").action(async (role, opts) => {
+  if (!VALID_ROLES.includes(role)) {
+    console.error(`Invalid role: ${role}. Use ${VALID_ROLES.join(", ")}.`);
+    process.exit(1);
   }
-);
-
-// src/cli/commands/workspace.ts
-function runGit(cwd, args) {
-  try {
-    return execFileSync3("git", args, {
-      cwd,
-      stdio: "pipe",
-      encoding: "utf8"
-    }).trim();
-  } catch (err) {
-    throw new Error(`Git command failed: ${err.message}`);
+  if (!opts.primary) {
+    console.error("--primary is required.");
+    process.exit(1);
   }
-}
-function ghRepoCreateArgs(repoName, repoVisibility) {
-  return ["repo", "create", repoName, repoVisibility, "--source=.", "--push"];
-}
-function gitRemoteArgs(githubUrl, hasOrigin) {
-  return hasOrigin ? ["remote", "set-url", "origin", githubUrl] : ["remote", "add", "origin", githubUrl];
-}
-var workspaceCommand = new Command3("workspace").description(
-  "Manage your ZAM learning workspace"
-);
-var WORKSPACE_KINDS = [
-  "personal",
-  "team",
-  "family",
-  "community",
-  "organization",
-  "custom"
-];
-var WORKSPACE_SOURCE_CONTROLS = [
-  "github",
-  "azure-devops",
-  "git",
-  "none"
-];
-function parseWorkspaceKind(value) {
-  const kind = (value ?? "custom").toLowerCase();
-  if (WORKSPACE_KINDS.includes(kind)) {
-    return kind;
-  }
-  throw new Error(
-    `Invalid workspace kind: ${value}. Use ${WORKSPACE_KINDS.join(", ")}.`
-  );
-}
-function parseWorkspaceSourceControl(value) {
-  if (!value) return void 0;
-  const source = value.toLowerCase();
-  if (WORKSPACE_SOURCE_CONTROLS.includes(source)) {
-    return source;
-  }
-  throw new Error(
-    `Invalid source control: ${value}. Use ${WORKSPACE_SOURCE_CONTROLS.join(", ")}.`
-  );
-}
-function parseScopes(value) {
-  if (!value) return void 0;
-  const scopes = value.split(",").map((item) => item.trim()).filter(Boolean);
-  return scopes.length > 0 ? scopes : void 0;
-}
-function requireWorkspace(id) {
-  const workspace = getConfiguredWorkspaces().find((item) => item.id === id);
-  if (!workspace) {
-    throw new Error(
-      `Workspace "${id}" is not configured. Add it with: zam workspace add ${id} --path <dir>`
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    await writeScopedRoles(
+      db,
+      machine,
+      bindRoleProviders(
+        await readScopedRoles(db, machine),
+        role,
+        opts.primary,
+        opts.fallback
+      )
     );
-  }
-  return workspace;
-}
-workspaceCommand.command("list").description("List configured ZAM workspaces").option("--json", "Output as JSON").action((opts) => {
-  const workspaces = getConfiguredWorkspaces();
-  if (opts.json) {
-    console.log(JSON.stringify({ workspaces }, null, 2));
-    return;
-  }
-  console.log("Configured ZAM workspaces:\n");
-  if (workspaces.length === 0) {
+    const fb = opts.fallback ? `, fallback: ${opts.fallback}` : "";
     console.log(
-      "  (none) \u2014 add one: zam workspace add personal --path <dir>"
+      `Role "${role}" \u2192 primary: ${opts.primary}${fb} (${machine ? "machine-local" : "shared"})`
     );
-    return;
-  }
-  for (const workspace of workspaces) {
-    const label = workspace.label ? ` (${workspace.label})` : "";
-    console.log(`  ${workspace.id}${label}`);
-    console.log(`      kind: ${workspace.kind}`);
-    console.log(`      path: ${workspace.path}`);
-    if (workspace.sourceControl) {
-      console.log(`      source: ${workspace.sourceControl}`);
-    }
-    if (workspace.knowledgeScopes?.length) {
-      console.log(`      scopes: ${workspace.knowledgeScopes.join(", ")}`);
+    for (const [label, ref] of [
+      ["primary", opts.primary],
+      ["fallback", opts.fallback]
+    ]) {
+      if (ref && !(ref in providers)) {
+        console.log(
+          `  \u26A0 ${label} "${ref}" is not a defined provider yet. Add it: zam provider add ${ref} --url <url> --model <model>`
+        );
+      }
     }
-  }
+  });
 });
-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) => {
+providerCommand.command("set-key <ref>").description(
+  "Store an API key for a provider reference (in credentials.json)"
+).option(
+  "--key <value>",
+  "The API key (omit to enter it interactively, hidden)"
+).action(async (ref, opts) => {
   try {
-    const path = resolve4(String(opts.path));
-    if (!existsSync16(path)) {
-      console.error(`Workspace path does not exist: ${path}`);
+    const key = opts.key ?? await password({ message: `API key for "${ref}":` });
+    if (!key || key.trim().length === 0) {
+      console.error("No key provided.");
       process.exit(1);
     }
-    const workspace = {
-      id,
-      kind: parseWorkspaceKind(opts.kind),
-      path,
-      ...opts.label ? { label: opts.label } : {},
-      ...opts.sourceControl ? { sourceControl: parseWorkspaceSourceControl(opts.sourceControl) } : {},
-      ...parseScopes(opts.scopes) ? { knowledgeScopes: parseScopes(opts.scopes) } : {},
-      ...opts.defaultAgent ? { defaultAgent: opts.defaultAgent } : {}
-    };
-    upsertConfiguredWorkspace(workspace);
-    console.log(`Registered workspace "${id}" at ${path}.`);
+    setProviderApiKey(ref, key.trim());
+    console.log(`Stored API key for "${ref}" (${maskSecret(key.trim())}).`);
   } catch (err) {
-    console.error(`Error: ${err.message}`);
+    if (err.name === "ExitPromptError") {
+      console.log("\nCancelled.");
+      process.exit(0);
+    }
+    console.error("Error:", err.message);
     process.exit(1);
   }
 });
-workspaceCommand.command("setup <id>").description("Install ZAM skills into a configured workspace").option(
-  "--agents <list>",
-  "comma-separated agents to wire: all, claude, copilot, codex, agent"
-).option(
-  "--force",
-  "overwrite existing skill files and refresh ZAM blocks",
-  false
-).option(
-  "--dry-run",
-  "show what would be written without changing files",
-  false
-).action((id, opts) => {
-  try {
-    const workspace = requireWorkspace(id);
-    const agents = parseSetupAgents(opts.agents);
-    console.log(
-      `Setting up workspace "${workspace.id}" in ${workspace.path}${opts.dryRun ? " (dry run)" : ""}
-`
-    );
-    copySkills(
-      Boolean(opts.force),
-      workspace.path,
-      agents,
-      Boolean(opts.dryRun)
-    );
-    if (agents.has("claude")) {
-      writeClaudeMd(false, workspace.path, {
-        dryRun: Boolean(opts.dryRun),
-        updateExisting: true
-      });
-    }
-    if (agents.has("copilot") || agents.has("codex") || agents.has("agent")) {
-      writeAgentsMd(false, workspace.path, {
-        dryRun: Boolean(opts.dryRun),
-        updateExisting: true
-      });
-    }
-    if (agents.has("copilot")) {
-      writeCopilotInstructions(workspace.path, {
-        dryRun: Boolean(opts.dryRun),
-        updateExisting: true
-      });
+providerCommand.command("clear-key <ref>").description("Remove a stored API key").action((ref) => {
+  clearProviderApiKey(ref);
+  console.log(`Cleared API key for "${ref}".`);
+});
+
+// src/cli/commands/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;
+}
+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);
+}
+
+// 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 Command3 } 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"]
+  },
+  {
+    from: join15(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
+    to: join15(".agent", "skills", "zam", "SKILL.md"),
+    agents: ["agent"]
+  },
+  {
+    from: join15(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
+    to: join15(".agents", "skills", "zam", "SKILL.md"),
+    agents: ["codex"]
+  }
+];
+function parseSetupAgents(value) {
+  if (!value || value.trim().toLowerCase() === "all") {
+    return new Set(ALL_SETUP_AGENTS);
+  }
+  const aliases = {
+    claude: ["claude"],
+    copilot: ["copilot"],
+    codex: ["codex"],
+    agent: ["agent"],
+    opencode: ["agent"]
+  };
+  const selected = /* @__PURE__ */ new Set();
+  for (const raw of value.split(",")) {
+    const key = raw.trim().toLowerCase();
+    const mapped = aliases[key];
+    if (!mapped) {
+      throw new Error(
+        `Unknown agent "${raw}". Use: all, claude, copilot, codex, agent.`
+      );
     }
-  } catch (err) {
-    console.error(`Error: ${err.message}`);
-    process.exit(1);
+    for (const item of mapped) selected.add(item);
   }
-});
-workspaceCommand.command("publish").description("Publish your local workspace sandbox to GitHub").action(async () => {
-  let db;
-  let workspaceDir = "";
+  return selected;
+}
+function pathExists(path) {
   try {
-    db = await openDatabase();
-    workspaceDir = await getSetting(db, "personal.workspace_dir") || "";
-    await db.close();
+    lstatSync(path);
+    return true;
   } catch {
-    await db?.close();
+    return false;
   }
-  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);
+}
+function comparableRealPath(path) {
+  const real = realpathSync(path);
+  return process.platform === "win32" ? real.toLowerCase() : real;
+}
+function pathsResolveToSameDirectory(sourceDir, destinationDir) {
+  try {
+    return comparableRealPath(destinationDir) === comparableRealPath(sourceDir);
+  } catch {
+    return false;
   }
-  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);
+}
+function linkPointsTo(sourceDir, destinationDir) {
+  try {
+    return lstatSync(destinationDir).isSymbolicLink() && pathsResolveToSameDirectory(sourceDir, destinationDir);
+  } catch {
+    return false;
   }
-  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"
+}
+function isReplaceableCopiedSkill(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")
     );
+  } catch {
+    return false;
   }
-  const hasGitRepo = existsSync16(join16(workspaceDir, ".git"));
-  if (!hasGitRepo) {
-    console.log("Initializing local Git repository...");
-    runGit(workspaceDir, ["init", "-b", "main"]);
-    runGit(workspaceDir, ["add", "."]);
-    runGit(workspaceDir, [
-      "commit",
-      "-m",
-      "chore: initial workspace sandbox bootstrap"
-    ]);
-    console.log("\x1B[32m\u2713 Local Git repository initialized.\x1B[0m");
-  } else {
-    console.log("Git repository is already initialized.");
-  }
-  const repoName = await input({
-    message: "Choose a name for your GitHub repository:",
-    default: "zam-personal"
-  });
-  const isPrivate = await confirm({
-    message: "Should the repository be private?",
-    default: true
-  });
-  const repoVisibility = isPrivate ? "--private" : "--public";
-  if (hasCommand("gh")) {
-    console.log("GitHub CLI detected! Automating repository creation...");
-    const proceedGh = await confirm({
-      message: "Would you like ZAM to create the repository using the GitHub CLI?",
-      default: true
-    });
-    if (proceedGh) {
-      try {
-        console.log(`Creating GitHub repository ${repoName}...`);
-        execFileSync3("gh", ghRepoCreateArgs(repoName, repoVisibility), {
-          cwd: workspaceDir,
-          stdio: "inherit"
-        });
-        console.log(
-          "\n\x1B[32m\u2713 Successfully published workspace to GitHub!\x1B[0m"
-        );
-        process.exit(0);
-      } catch (err) {
+}
+function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {}) {
+  const results = [];
+  const log = (message) => {
+    if (!opts.quiet) console.log(message);
+  };
+  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));
+    if (!existsSync15(sourceDir)) {
+      if (!opts.quiet) {
+        console.warn(`  warn  source not found, skipping: ${sourceDir}`);
+      }
+      results.push({
+        source: sourceDir,
+        destination: destinationDir,
+        action: "skipped",
+        reason: "source-not-found"
+      });
+      continue;
+    }
+    if (pathsResolveToSameDirectory(sourceDir, destinationDir) && !lstatSync(destinationDir).isSymbolicLink()) {
+      log(`  skip  ${dirname5(to)} (package source)`);
+      results.push({
+        source: sourceDir,
+        destination: destinationDir,
+        action: "skipped",
+        reason: "source-directory"
+      });
+      continue;
+    }
+    if (linkPointsTo(sourceDir, destinationDir)) {
+      log(`  skip  ${dirname5(to)} (already linked)`);
+      results.push({
+        source: sourceDir,
+        destination: destinationDir,
+        action: "skipped",
+        reason: "already-linked"
+      });
+      continue;
+    }
+    const destinationExists = pathExists(destinationDir);
+    const replaceExisting = destinationExists && (Boolean(opts.force) || isReplaceableCopiedSkill(destinationDir));
+    if (destinationExists && !replaceExisting) {
+      if (!opts.quiet) {
         console.warn(
-          `\x1B[33m\u26A0 GitHub CLI creation failed: ${err.message}\x1B[0m`
+          `  warn  ${dirname5(to)} already exists and is not managed by ZAM; use --force to replace it`
         );
       }
+      results.push({
+        source: sourceDir,
+        destination: destinationDir,
+        action: "skipped",
+        reason: "unmanaged-destination"
+      });
+      continue;
     }
-  }
-  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"
+    const action = destinationExists ? "relinked" : "linked";
+    if (opts.dryRun) {
+      log(`  would ${action === "linked" ? "link" : "relink"}  ${dirname5(to)}`);
+    } else {
+      if (destinationExists) {
+        rmSync2(destinationDir, { recursive: true, force: true });
+      }
+      mkdirSync8(dirname5(destinationDir), { recursive: true });
+      symlinkSync(
+        sourceDir,
+        destinationDir,
+        process.platform === "win32" ? "junction" : "dir"
       );
+      log(`  ${action === "linked" ? "link" : "relink"}  ${dirname5(to)}`);
     }
+    results.push({ source: sourceDir, destination: destinationDir, action });
   }
-});
-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;
+  return results;
 }
-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);
+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}`;
   }
-  let db;
+}
+async function initDatabase(skipInit) {
+  if (skipInit) return;
   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`);
-    }
+    const target = getDatabaseTargetInfo();
+    const db = await openDatabaseWithSync({ initialize: true });
+    await db.close();
+    console.log(`  init  ${formatDatabaseInitTarget(target)}`);
   } catch (err) {
-    const reason = err.message;
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, reason }));
+    const msg = err.message;
+    if (!msg.includes("already")) {
+      console.warn(`  warn  database init: ${msg}`);
     } else {
-      console.error(`\x1B[31m\u2717 Backup failed: ${reason}\x1B[0m`);
+      console.log(`  skip  database already initialized`);
     }
-    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 }));
+var ZAM_BLOCK_START = "<!-- ZAM:START -->";
+var ZAM_BLOCK_END = "<!-- ZAM:END -->";
+function upsertMarkedBlock(dest, blockBody, dryRun) {
+  const block = `${ZAM_BLOCK_START}
+${blockBody.trim()}
+${ZAM_BLOCK_END}`;
+  if (!existsSync15(dest)) {
+    if (!dryRun) {
+      mkdirSync8(dirname5(dest), { recursive: true });
+      writeFileSync7(dest, `${block}
+`, "utf8");
+    }
+    return "write";
   }
-  console.log(JSON.stringify({ error: message }, null, 2));
-  process.exit(1);
+  const existing = readFileSync10(dest, "utf8");
+  if (existing.includes(block)) return "skip";
+  const start = existing.indexOf(ZAM_BLOCK_START);
+  const end = existing.indexOf(ZAM_BLOCK_END);
+  const next = start >= 0 && end > start ? `${existing.slice(0, start)}${block}${existing.slice(end + ZAM_BLOCK_END.length)}` : `${existing.trimEnd()}
+
+${block}
+`;
+  if (!dryRun) writeFileSync7(dest, next, "utf8");
+  return start >= 0 && end > start ? "update" : "write";
 }
-function parseNonNegativeIntegerOption(name, value) {
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed < 0) {
-    jsonError(`${name} must be a non-negative integer`);
+function logInstructionAction(action, label, dryRun) {
+  if (action === "skip") {
+    console.log(`  skip  ${label} (ZAM block already present)`);
+  } else {
+    console.log(`  ${dryRun ? "would " : ""}${action} ${label}`);
   }
-  return parsed;
-}
-async function withDb2(fn) {
-  await withDb(fn, jsonError);
 }
-async function getReviewTarget2(db, cardId, userId) {
-  const target = await db.prepare(
-    `SELECT c.id AS card_id, c.token_id, c.user_id, t.slug
-       FROM cards c
-       JOIN tokens t ON t.id = c.token_id
-       WHERE c.id = ?`
-  ).get(cardId);
-  if (!target) {
-    jsonError(`Card not found: ${cardId}`);
-  }
-  if (target.user_id !== userId) {
+function writeClaudeMd(skipClaudeMd, cwd = process.cwd(), opts = {}) {
+  if (skipClaudeMd) return;
+  const dest = join15(cwd, "CLAUDE.md");
+  if (existsSync15(dest)) {
+    if (!opts.updateExisting) {
+      console.log(`  skip  CLAUDE.md (already present)`);
+      return;
+    }
+    const action = upsertMarkedBlock(
+      dest,
+      `## ZAM learning sessions
+
+ZAM is available in this repository. Use the \`zam\` skill in Claude Code to turn real work into an observed learning session with active recall and FSRS scheduling.
+
+- Skill files live under \`.claude/skills/zam/\`.
+- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
+- The skill directory is linked to this ZAM installation and updates with it.`,
+      Boolean(opts.dryRun)
+    );
+    logInstructionAction(action, "CLAUDE.md", Boolean(opts.dryRun));
+    return;
+  }
+  const name = basename4(cwd);
+  const content = `# ZAM Personal Kernel \xE2\u20AC\u201D ${name}
+
+This is a ZAM personal instance. ZAM builds lasting skills through spaced
+repetition during real work \xE2\u20AC\u201D not separate study sessions.
+
+## First time here?
+Run \`/setup\` in Claude Code or Gemini CLI to complete first-time setup.
+
+## Regular use
+Run \`/zam\` to start a learning session on whatever you are working on.
+
+## What lives here
+- \`beliefs/\` \xE2\u20AC\u201D your worldview, approved by git commit
+- \`goals/\` \xE2\u20AC\u201D your objectives, decomposed into tasks and learning tokens
+
+## Fast-changing data
+Learning tokens, cards, and review history live in local SQLite by default.
+Use \`zam connector setup turso\` to store cloud credentials in
+\`~/.zam/credentials.json\` and use a Turso database across machines.
+`;
+  if (opts.dryRun) {
+    console.log(`  would write CLAUDE.md`);
+  } else {
+    writeFileSync7(dest, content, "utf8");
+    console.log(`  write CLAUDE.md`);
+  }
+}
+function writeAgentsMd(skipAgentsMd, cwd = process.cwd(), opts = {}) {
+  if (skipAgentsMd) return;
+  const dest = join15(cwd, "AGENTS.md");
+  if (existsSync15(dest)) {
+    if (!opts.updateExisting) {
+      console.log(`  skip  AGENTS.md (already present)`);
+      return;
+    }
+    const action = upsertMarkedBlock(
+      dest,
+      `## ZAM learning sessions
+
+ZAM is available in this repository. Select the \`zam\` skill through \`/skills\` or invoke \`$zam\` where supported to turn real work into an observed learning session with active recall and FSRS scheduling.
+
+- Skill files live under \`.agents/skills/zam/\`.
+- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
+- The skill directory is linked to this ZAM installation and updates with it.`,
+      Boolean(opts.dryRun)
+    );
+    logInstructionAction(action, "AGENTS.md", Boolean(opts.dryRun));
+    return;
+  }
+  const name = basename4(cwd);
+  const content = `# ZAM Personal Kernel - ${name}
+
+This is a ZAM personal instance. ZAM builds lasting skills through spaced
+repetition during real work, not separate study sessions.
+
+## First time here?
+Run \`zam setup\` from the shell. When this repository includes
+\`.agents/skills/setup/\`, you can instead select \`setup\` through \`/skills\`
+or invoke \`$setup\`.
+
+## Regular use
+Select the \`zam\` skill through \`/skills\` or invoke \`$zam\` to start a
+learning session on whatever you are working on.
+
+## What lives here
+- \`beliefs/\` - your worldview, approved by git commit
+- \`goals/\` - your objectives, decomposed into tasks and learning tokens
+
+## Fast-changing data
+Learning tokens, cards, and review history live in local SQLite by default.
+Use \`zam connector setup turso\` to store cloud credentials in
+\`~/.zam/credentials.json\` and use a Turso database across machines.
+
+## Codex skills
+Codex discovers repository skills under \`.agents/skills/\`. Run
+\`zam setup --force\` after upgrading \`zam-core\` to refresh them.
+`;
+  if (opts.dryRun) {
+    console.log(`  would write AGENTS.md`);
+  } else {
+    writeFileSync7(dest, content, "utf8");
+    console.log(`  write AGENTS.md`);
+  }
+}
+function writeCopilotInstructions(cwd = process.cwd(), opts = {}) {
+  const dest = join15(cwd, ".github", "copilot-instructions.md");
+  const action = upsertMarkedBlock(
+    dest,
+    `## ZAM learning sessions
+
+ZAM is available in this repository through \`.claude/skills/zam/\`. Use the \`zam\` project skill from Copilot-compatible skill selection surfaces to turn real work into an observed learning session with active recall and FSRS scheduling.
+
+- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
+- The skill directory is linked to this ZAM installation and updates with it.`,
+    Boolean(opts.dryRun)
+  );
+  logInstructionAction(
+    action,
+    ".github/copilot-instructions.md",
+    Boolean(opts.dryRun)
+  );
+}
+var setupCommand = new Command3("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/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 Command4 } 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}`);
+  }
+}
+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 Command4("workspace").description(
+  "Manage your ZAM learning workspace"
+);
+var WORKSPACE_KINDS = [
+  "personal",
+  "team",
+  "family",
+  "community",
+  "organization",
+  "custom"
+];
+var WORKSPACE_SOURCE_CONTROLS = [
+  "github",
+  "azure-devops",
+  "git",
+  "none"
+];
+function parseWorkspaceKind(value) {
+  const kind = (value ?? "custom").toLowerCase();
+  if (WORKSPACE_KINDS.includes(kind)) {
+    return kind;
+  }
+  throw new Error(
+    `Invalid workspace kind: ${value}. Use ${WORKSPACE_KINDS.join(", ")}.`
+  );
+}
+function parseWorkspaceSourceControl(value) {
+  if (!value) return void 0;
+  const source = value.toLowerCase();
+  if (WORKSPACE_SOURCE_CONTROLS.includes(source)) {
+    return source;
+  }
+  throw new Error(
+    `Invalid source control: ${value}. Use ${WORKSPACE_SOURCE_CONTROLS.join(", ")}.`
+  );
+}
+function parseScopes(value) {
+  if (!value) return void 0;
+  const scopes = value.split(",").map((item) => item.trim()).filter(Boolean);
+  return scopes.length > 0 ? scopes : void 0;
+}
+function requireWorkspace(id) {
+  const workspace = getConfiguredWorkspaces().find((item) => item.id === id);
+  if (!workspace) {
+    throw new Error(
+      `Workspace "${id}" is not configured. Add it with: zam workspace add ${id} --path <dir>`
+    );
+  }
+  return workspace;
+}
+workspaceCommand.command("list").description("List configured ZAM workspaces").option("--json", "Output as JSON").action((opts) => {
+  const workspaces = getConfiguredWorkspaces();
+  if (opts.json) {
+    console.log(JSON.stringify({ workspaces }, null, 2));
+    return;
+  }
+  console.log("Configured ZAM workspaces:\n");
+  if (workspaces.length === 0) {
+    console.log(
+      "  (none) \u2014 add one: zam workspace add personal --path <dir>"
+    );
+    return;
+  }
+  for (const workspace of workspaces) {
+    const label = workspace.label ? ` (${workspace.label})` : "";
+    console.log(`  ${workspace.id}${label}`);
+    console.log(`      kind: ${workspace.kind}`);
+    console.log(`      path: ${workspace.path}`);
+    if (workspace.sourceControl) {
+      console.log(`      source: ${workspace.sourceControl}`);
+    }
+    if (workspace.knowledgeScopes?.length) {
+      console.log(`      scopes: ${workspace.knowledgeScopes.join(", ")}`);
+    }
+  }
+});
+workspaceCommand.command("add <id>").description("Register an existing directory as a ZAM workspace").requiredOption("--path <dir>", "Existing workspace/repository directory").option(
+  "--kind <kind>",
+  `Workspace kind (${WORKSPACE_KINDS.join(" | ")})`,
+  "custom"
+).option("--label <label>", "Human-readable label").option(
+  "--source-control <provider>",
+  `Source-control provider (${WORKSPACE_SOURCE_CONTROLS.join(" | ")})`
+).option("--scopes <list>", "Comma-separated knowledge scopes").option("--default-agent <id>", "Default agent harness for this workspace").action((id, opts) => {
+  try {
+    const path = resolve4(String(opts.path));
+    if (!existsSync16(path)) {
+      console.error(`Workspace path does not exist: ${path}`);
+      process.exit(1);
+    }
+    const workspace = {
+      id,
+      kind: parseWorkspaceKind(opts.kind),
+      path,
+      ...opts.label ? { label: opts.label } : {},
+      ...opts.sourceControl ? { sourceControl: parseWorkspaceSourceControl(opts.sourceControl) } : {},
+      ...parseScopes(opts.scopes) ? { knowledgeScopes: parseScopes(opts.scopes) } : {},
+      ...opts.defaultAgent ? { defaultAgent: opts.defaultAgent } : {}
+    };
+    wireSkills(path, parseSetupAgents());
+    upsertConfiguredWorkspace(workspace);
+    console.log(`Registered and linked workspace "${id}" at ${path}.`);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+});
+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);
+  }
+  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);
+  }
+});
+workspaceCommand.command("publish").description("Publish your local workspace sandbox to GitHub").action(async () => {
+  let db;
+  let workspaceDir = "";
+  try {
+    db = await openDatabase();
+    workspaceDir = await getSetting(db, "personal.workspace_dir") || "";
+    await db.close();
+  } catch {
+    await db?.close();
+  }
+  if (!workspaceDir) {
+    console.error(
+      "\x1B[31m\u2717 No active workspace configured. Please run `zam init` first.\x1B[0m"
+    );
+    process.exit(1);
+  }
+  if (!existsSync16(workspaceDir)) {
+    console.error(
+      `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
+    );
+    process.exit(1);
+  }
+  console.log(`
+Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
+  if (!hasCommand("git")) {
+    console.error(
+      "\x1B[31m\u2717 Git command was not found on this system. Please install Git first.\x1B[0m"
+    );
+    process.exit(1);
+  }
+  const gitignorePath = join16(workspaceDir, ".gitignore");
+  if (!existsSync16(gitignorePath)) {
+    writeFileSync8(
+      gitignorePath,
+      "node_modules/\n.agent/\n.agents/\n.claude/\n.gemini/\n.goose/\n*.log\n",
+      "utf8"
+    );
+  }
+  const hasGitRepo = existsSync16(join16(workspaceDir, ".git"));
+  if (!hasGitRepo) {
+    console.log("Initializing local Git repository...");
+    runGit(workspaceDir, ["init", "-b", "main"]);
+    runGit(workspaceDir, ["add", "."]);
+    runGit(workspaceDir, [
+      "commit",
+      "-m",
+      "chore: initial workspace sandbox bootstrap"
+    ]);
+    console.log("\x1B[32m\u2713 Local Git repository initialized.\x1B[0m");
+  } else {
+    console.log("Git repository is already initialized.");
+  }
+  const repoName = await input({
+    message: "Choose a name for your GitHub repository:",
+    default: "zam-personal"
+  });
+  const isPrivate = await confirm({
+    message: "Should the repository be private?",
+    default: true
+  });
+  const repoVisibility = isPrivate ? "--private" : "--public";
+  if (hasCommand("gh")) {
+    console.log("GitHub CLI detected! Automating repository creation...");
+    const proceedGh = await confirm({
+      message: "Would you like ZAM to create the repository using the GitHub CLI?",
+      default: true
+    });
+    if (proceedGh) {
+      try {
+        console.log(`Creating GitHub repository ${repoName}...`);
+        execFileSync3("gh", ghRepoCreateArgs(repoName, repoVisibility), {
+          cwd: workspaceDir,
+          stdio: "inherit"
+        });
+        console.log(
+          "\n\x1B[32m\u2713 Successfully published workspace to GitHub!\x1B[0m"
+        );
+        process.exit(0);
+      } catch (err) {
+        console.warn(
+          `\x1B[33m\u26A0 GitHub CLI creation failed: ${err.message}\x1B[0m`
+        );
+      }
+    }
+  }
+  console.log(
+    "\n\x1B[1mPlease create the repository manually on GitHub:\x1B[0m"
+  );
+  console.log("  1. Go to https://github.com/new");
+  console.log(`  2. Name it exactly: \x1B[36m${repoName}\x1B[0m`);
+  console.log(
+    `  3. Choose \x1B[36m${isPrivate ? "Private" : "Public"}\x1B[0m`
+  );
+  console.log(
+    "  4. Do NOT initialize it with README, .gitignore, or license"
+  );
+  console.log("  5. Click 'Create repository'\n");
+  const githubUrl = await input({
+    message: "Paste the repository Git URL (e.g. git@github.com:user/repo.git):"
+  });
+  if (githubUrl) {
+    try {
+      console.log("Linking remote repository and pushing...");
+      let hasOrigin = false;
+      try {
+        runGit(workspaceDir, ["remote", "get-url", "origin"]);
+        hasOrigin = true;
+      } catch {
+      }
+      runGit(workspaceDir, gitRemoteArgs(githubUrl, hasOrigin));
+      runGit(workspaceDir, ["push", "-u", "origin", "main"]);
+      console.log(
+        "\x1B[32m\u2713 Successfully linked and pushed to GitHub!\x1B[0m"
+      );
+    } catch (err) {
+      console.error(
+        `\x1B[31m\u2717 Push failed: ${err.message}\x1B[0m`
+      );
+      console.log(
+        "You can push manually later using: git push -u origin main"
+      );
+    }
+  }
+});
+async function backupDatabaseTo(db, targetDir) {
+  const backupDir = join16(targetDir, "zam-backups");
+  mkdirSync9(backupDir, { recursive: true });
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const dest = join16(backupDir, `zam-${stamp}.db`);
+  await db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
+  return dest;
+}
+workspaceCommand.command("data-dir").description("Print the ZAM data directory (database, credentials, config)").option("--json", "Output as JSON").action((opts) => {
+  const dir = join16(homedir9(), ".zam");
+  console.log(opts.json ? JSON.stringify({ dataDir: dir }) : dir);
+});
+workspaceCommand.command("backup").description("Back up the local ZAM database into your workspace").option(
+  "--dir <path>",
+  "Target directory (default: workspace dir, else ~/Documents/zam)"
+).option("--json", "Output as JSON").action(async (opts) => {
+  const target = getDatabaseTargetInfo();
+  if (target.kind !== "local") {
+    const reason = `The database is ${target.kind} (${target.location}); file backup applies only to a local database \u2014 your Turso remote is already the cloud backup.`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, reason }));
+      return;
+    }
+    console.error(`\x1B[33m\u26A0 ${reason}\x1B[0m`);
+    process.exit(1);
+  }
+  let db;
+  try {
+    db = await openDatabase();
+    const workspaceDir = opts.dir || await getSetting(db, "personal.workspace_dir") || join16(homedir9(), "Documents", "zam");
+    const dest = await backupDatabaseTo(db, workspaceDir);
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, path: dest }));
+    } else {
+      console.log(`\x1B[32m\u2713 Database backed up to ${dest}\x1B[0m`);
+    }
+  } catch (err) {
+    const reason = err.message;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, reason }));
+    } else {
+      console.error(`\x1B[31m\u2717 Backup failed: ${reason}\x1B[0m`);
+    }
+    process.exit(1);
+  } finally {
+    await db?.close();
+  }
+});
+
+// src/cli/commands/bridge.ts
+var isServeMode = false;
+function jsonOut2(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function jsonError(message) {
+  if (isServeMode) {
+    throw new Error(JSON.stringify({ error: message }));
+  }
+  console.log(JSON.stringify({ error: message }, null, 2));
+  process.exit(1);
+}
+function parseNonNegativeIntegerOption(name, value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    jsonError(`${name} must be a non-negative integer`);
+  }
+  return parsed;
+}
+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.`);
+}
+async function withDb2(fn) {
+  await withDb(fn, jsonError);
+}
+async function getReviewTarget2(db, cardId, userId) {
+  const target = await db.prepare(
+    `SELECT c.id AS card_id, c.token_id, c.user_id, t.slug
+       FROM cards c
+       JOIN tokens t ON t.id = c.token_id
+       WHERE c.id = ?`
+  ).get(cardId);
+  if (!target) {
+    jsonError(`Card not found: ${cardId}`);
+  }
+  if (target.user_id !== userId) {
     jsonError(`Card ${cardId} does not belong to user ${userId}`);
   }
   return target;
@@ -7389,7 +7962,7 @@ function parseTokenUpdates(opts) {
   }
   return updates;
 }
-var bridgeCommand = new Command4("bridge").description(
+var bridgeCommand = new Command5("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) => {
@@ -7447,6 +8020,37 @@ bridgeCommand.command("workspace-info").description("Report the workspace dir, i
     });
   });
 });
+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;
@@ -7487,6 +8091,7 @@ bridgeCommand.command("workspace-add").description("Register an existing directo
     kind: parseBridgeWorkspaceKind(opts.kind),
     path
   };
+  const skillLinks = wireSkills(path, parseSetupAgents(), { quiet: true });
   await withDb2(async (db) => {
     await setSetting(db, "personal.workspace_dir", path);
     upsertConfiguredWorkspace(workspace);
@@ -7494,7 +8099,39 @@ bridgeCommand.command("workspace-add").description("Register an existing directo
       ok: true,
       workspace,
       workspaces: getConfiguredWorkspaces(),
-      workspaceDir: path
+      workspaceDir: path,
+      skillLinks
+    });
+  });
+});
+bridgeCommand.command("workspace-remove").description("Unregister a ZAM workspace without deleting its files (JSON)").requiredOption("--id <id>", "Workspace id").action(async (opts) => {
+  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`);
+  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;
+      }
+    }
+    jsonOut2({
+      ok: true,
+      removed: workspace,
+      workspaces: getConfiguredWorkspaces(),
+      workspaceDir,
+      skillLinks
     });
   });
 });
@@ -7502,9 +8139,11 @@ bridgeCommand.command("set-workspace-dir").description("Set the personal workspa
   const raw = String(opts.dir ?? "").trim();
   if (!raw) jsonError("A non-empty --dir is required");
   const dir = resolve5(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 });
+    jsonOut2({ ok: true, workspaceDir: dir, skillLinks });
   });
 });
 bridgeCommand.command("agent-list").description("List agent harnesses with detection state + the default (JSON)").action(async () => {
@@ -7593,6 +8232,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, {
@@ -7605,7 +8246,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 {
       }
@@ -7634,6 +8277,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
     });
@@ -7932,7 +8577,7 @@ bridgeCommand.command("discover-skills").description(
     const monitorDir = join17(homedir10(), ".zam", "monitor");
     let files;
     try {
-      files = readdirSync2(monitorDir).filter((f) => f.endsWith(".jsonl"));
+      files = readdirSync3(monitorDir).filter((f) => f.endsWith(".jsonl"));
     } catch {
       jsonOut2({ proposals: [], message: "No monitor logs found." });
       return;
@@ -8455,7 +9100,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
       if (!post.allowed) {
         if (!opts.output) {
           try {
-            rmSync2(outputPath, { force: true });
+            rmSync3(outputPath, { force: true });
           } catch {
           }
         }
@@ -8594,7 +9239,7 @@ bridgeCommand.command("stop-recording").description(
   }
   const sessionId = opts.session;
   const statePath = join17(tmpdir3(), `zam-recording-${sessionId}.json`);
-  const { existsSync: existsSync25, readFileSync: readFileSync16, rmSync: rmSync3 } = await import("fs");
+  const { existsSync: existsSync25, readFileSync: readFileSync16, rmSync: rmSync4 } = await import("fs");
   if (!existsSync25(statePath)) {
     jsonOut2({
       sessionId,
@@ -8619,7 +9264,7 @@ bridgeCommand.command("stop-recording").description(
   };
   let attempts = 0;
   while (isProcessRunning(pid) && attempts < 20) {
-    await new Promise((resolve8) => setTimeout(resolve8, 250));
+    await new Promise((resolve9) => setTimeout(resolve9, 250));
     attempts++;
   }
   if (isProcessRunning(pid)) {
@@ -8629,7 +9274,7 @@ bridgeCommand.command("stop-recording").description(
     }
   }
   try {
-    rmSync3(statePath, { force: true });
+    rmSync4(statePath, { force: true });
   } catch {
   }
   if (!existsSync25(outputPath)) {
@@ -8658,7 +9303,7 @@ bridgeCommand.command("stop-recording").description(
     return;
   }
   try {
-    rmSync3(outputPath, { force: true });
+    rmSync4(outputPath, { force: true });
   } catch {
   }
   jsonOut2({
@@ -8725,12 +9370,194 @@ bridgeCommand.command("check-llm").description("Check if LLM is enabled and onli
 });
 bridgeCommand.command("provider-status").description("Show secret-safe provider status for LLM roles (JSON)").action(async () => {
   await withDb2(async (db) => {
-    const [recall, vision, text] = await Promise.all([
-      getProviderRoleStatus(db, "recall"),
-      getProviderRoleStatus(db, "vision"),
-      getProviderRoleStatus(db, "text")
-    ]);
-    jsonOut2({ roles: { recall, vision, text } });
+    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-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) => {
+    await setSetting(db, opts.key, opts.value);
+    jsonOut2({ ok: true, key: opts.key, value: opts.value });
   });
 });
 bridgeCommand.command("check-vision").description(
@@ -8779,7 +9606,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) {
@@ -8790,8 +9620,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;
@@ -8799,7 +9629,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,
@@ -8809,7 +9639,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,
@@ -8823,10 +9657,13 @@ 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);
     jsonOut2({
       userId,
       locale,
-      llm: { enabled, url, model }
+      llm: { enabled, url, model },
+      workspaceDir,
+      skillLinks
     });
   });
 });
@@ -9045,8 +9882,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 Command6 } from "commander";
+var cardCommand = new Command6("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) => {
@@ -9244,9 +10081,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 as input2, password as password2 } from "@inquirer/prompts";
+import { Command as Command7 } from "commander";
+var connectorCommand = new Command7("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(
@@ -9271,7 +10108,7 @@ connectorCommand.command("setup").description("Configure a connector").argument(
     const project = await input2({
       message: "Project name:"
     });
-    const pat = await password({
+    const pat = await password2({
       message: "Personal Access Token:"
     });
     if (!orgUrl || !project || !pat) {
@@ -9362,7 +10199,7 @@ async function setupTurso(urlArg, tokenArg, mode) {
     const url = urlArg ?? await input2({
       message: "Turso database URL (e.g. libsql://my-db-user.turso.io):"
     });
-    const token = tokenArg ?? await password({
+    const token = tokenArg ?? await password2({
       message: "Auth token:"
     });
     if (!url || !token) {
@@ -9391,7 +10228,7 @@ async function setupTurso(urlArg, tokenArg, mode) {
 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 { Command as Command8 } from "commander";
 function installHook2() {
   const gitDir = join18(process.cwd(), ".git");
   if (!existsSync18(gitDir)) {
@@ -9421,7 +10258,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 Command8("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;
@@ -9510,10 +10347,10 @@ ZAM Auto-Stale Complete: Scanned ${changedFiles.length} file(s).`
 });
 
 // src/cli/commands/goal.ts
-import { existsSync as existsSync19, mkdirSync as mkdirSync10 } from "fs";
+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 { Command as Command9 } from "commander";
 async function resolveGoalsDir() {
   let goalsDir;
   let db;
@@ -9526,7 +10363,7 @@ async function resolveGoalsDir() {
   }
   return goalsDir ? resolve6(goalsDir) : resolve6("goals");
 }
-var goalCommand = new Command8("goal").description(
+var goalCommand = new Command9("goal").description(
   "Manage learning goals (markdown files)"
 );
 goalCommand.command("list").description("List all goals").option(
@@ -9636,7 +10473,7 @@ ${"\u2500".repeat(50)}`);
 goalCommand.command("create").description("Create a new goal").option("--slug <slug>", "Goal slug (used as filename)").option("--title <title>", "Goal title").option("--parent <slug>", "Parent goal slug").option("--description <text>", "Goal description").option("--json", "Output as JSON").action(async (opts) => {
   const goalsDir = await resolveGoalsDir();
   if (!existsSync19(goalsDir)) {
-    mkdirSync10(goalsDir, { recursive: true });
+    mkdirSync11(goalsDir, { recursive: true });
   }
   let slug = opts.slug;
   let title = opts.title;
@@ -9695,19 +10532,19 @@ goalCommand.command("status <slug> <status>").description("Update a goal's statu
 });
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync20, mkdirSync as mkdirSync11, writeFileSync as writeFileSync10 } from "fs";
+import { existsSync as existsSync20, mkdirSync as mkdirSync12, writeFileSync as writeFileSync10 } from "fs";
 import { homedir as homedir11 } from "os";
-import { join as join19 } from "path";
+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 { Command as Command10 } 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) {
-  mkdirSync11(join19(workspaceDir, "beliefs"), { recursive: true });
-  mkdirSync11(join19(workspaceDir, "goals"), { recursive: true });
-  mkdirSync11(join19(workspaceDir, "skills"), { recursive: true });
+  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");
   if (!existsSync20(worldviewFile)) {
     writeFileSync10(
@@ -9736,7 +10573,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 Command10("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"
@@ -9747,12 +10584,21 @@ 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 = await input4({
-    message: "Choose your ZAM workspace directory:",
-    default: defaultWorkspace
-  });
+  const workspacePath = resolve7(
+    await input4({
+      message: "Choose your ZAM workspace directory:",
+      default: defaultWorkspace
+    })
+  );
   try {
     bootstrapSandboxWorkspace(workspacePath);
+    wireSkills(workspacePath, parseSetupAgents());
+    upsertConfiguredWorkspace({
+      id: "personal",
+      label: "Personal",
+      kind: "personal",
+      path: workspacePath
+    });
     console.log(
       `\x1B[32m\u2713 Local Sandbox created at: ${workspacePath}\x1B[0m`
     );
@@ -9903,7 +10749,7 @@ 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 { Command as Command11 } from "commander";
 
 // src/cli/learn-format.ts
 var BLOOM_VERBS3 = {
@@ -10241,7 +11087,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 Command11("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;
@@ -10297,7 +11143,7 @@ ${t(locale, "welcome", { count: queue.items.length })}`);
             question: item.question
           });
           if (healed) {
-            resolvedQuestion = healed;
+            resolvedQuestion = healed.question;
           }
         } catch {
         }
@@ -10362,7 +11208,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) {
@@ -10485,8 +11332,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 Command12 } from "commander";
+var monitorCommand = new Command12("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(
@@ -10549,593 +11396,244 @@ monitorCommand.command("stop").description("Output shell code to remove monitori
       session_id: opts.session
     };
     writeMonitorEvent(opts.session, meta);
-  }
-  let shell;
-  try {
-    shell = normalizeShell(opts.shell);
-  } catch (err) {
-    console.error(`# Error: ${err.message}`);
-    process.exit(1);
-  }
-  if (shell === "bash") {
-    console.log(generateBashUnhooks());
-  } else if (isPowerShellShell(shell)) {
-    console.log(generatePowerShellUnhooks());
-  } else {
-    console.log(generateZshUnhooks());
-  }
-});
-monitorCommand.command("status").description("Show monitoring status for a session").requiredOption("--session <id>", "Session ID").option("--json", "Output as JSON").action((opts) => {
-  const stats = getMonitorLogStats(opts.session);
-  if (!stats.exists) {
-    if (opts.json) {
-      console.log(JSON.stringify({ exists: false }));
-    } else {
-      console.log(`No monitor log found for session ${opts.session}`);
-    }
-    return;
-  }
-  const events = readMonitorLog(opts.session);
-  const commands = pairCommands(events);
-  const errors = commands.filter(
-    (c) => c.exitCode != null && c.exitCode !== 0
-  ).length;
-  const meta = events.find(
-    (e) => e.type === "monitor_meta" && e.event === "start"
-  );
-  const stopped = events.some(
-    (e) => e.type === "monitor_meta" && e.event === "stop"
-  );
-  const result = {
-    sessionId: opts.session,
-    exists: true,
-    active: !stopped,
-    shell: meta?.shell ?? "unknown",
-    totalCommands: commands.length,
-    errors,
-    sizeBytes: stats.sizeBytes,
-    timeSpan: commands.length > 0 ? {
-      start: commands[0].startedAt,
-      end: commands[commands.length - 1].endedAt ?? commands[commands.length - 1].startedAt
-    } : null
-  };
-  if (opts.json) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-  console.log(`Monitor: ${opts.session}`);
-  console.log(`  Status:   ${result.active ? "active" : "stopped"}`);
-  console.log(`  Shell:    ${result.shell}`);
-  console.log(`  Commands: ${result.totalCommands}`);
-  console.log(`  Errors:   ${result.errors}`);
-  if (result.timeSpan) {
-    console.log(`  From:     ${result.timeSpan.start}`);
-    console.log(`  To:       ${result.timeSpan.end}`);
-  }
-});
-function buildMonitorSetupCommand(dir, sessionId, shell) {
-  const zamInvocation = resolveZamInvocation(shell);
-  if (isPowerShellShell(shell)) {
-    return [
-      `Set-Location -LiteralPath ${psSingleQuoted2(dir)}`,
-      `$__zamHook = ${zamInvocation} monitor start --session ${psSingleQuoted2(sessionId)} --shell ${shell}`,
-      "Invoke-Expression ($__zamHook -join [Environment]::NewLine)",
-      "Remove-Variable __zamHook"
-    ].join("; ");
-  }
-  return `cd ${JSON.stringify(dir)} && eval "$(${zamInvocation} monitor start --session ${sessionId} --shell ${shell})"`;
-}
-monitorCommand.command("open").description("Open a new monitored terminal window for a session").requiredOption("--session <id>", "Session ID to monitor").option("--dir <path>", "Working directory (defaults to cwd)").option(
-  "--shell <type>",
-  "Shell type: zsh | bash | pwsh | powershell (auto-detected)"
-).action(async (opts) => {
-  let shell;
-  try {
-    shell = normalizeShell(opts.shell);
-  } catch (err) {
-    console.error(`Error: ${err.message}`);
-    process.exit(1);
-  }
-  let db;
-  try {
-    db = await openDatabase();
-    const session = await db.prepare("SELECT id, completed_at FROM sessions WHERE id = ?").get(opts.session);
-    if (!session) {
-      console.error(`Error: Session not found: ${opts.session}`);
-      process.exit(1);
-    }
-    if (session.completed_at) {
-      console.error(`Error: Session already completed: ${opts.session}`);
-      process.exit(1);
-    }
-    if (!await getSetting(db, "monitor_method")) {
-      await setSetting(db, "monitor_method", "terminal");
-    }
-  } catch (err) {
-    console.error(`Error: ${err.message}`);
-    process.exit(1);
-  } finally {
-    await db?.close();
-  }
-  const dir = opts.dir ?? process.cwd();
-  const shellSetup = buildMonitorSetupCommand(dir, opts.session, shell);
-  openTerminalWindow({
-    shellSetup,
-    label: `monitor-${opts.session}`,
-    dir,
-    shell
-  });
-});
-
-// src/cli/commands/observer.ts
-import { Command as Command12 } from "commander";
-var observerCommand = new Command12("observer").description(
-  "Configure what the UI observer may capture (Layer 2 policy)"
-);
-function applyObserverListChange(current, entry, op) {
-  const normalized = entry.trim().toLowerCase();
-  const list = parseObserverList(current);
-  const next = op === "add" ? [.../* @__PURE__ */ new Set([...list, normalized])] : list.filter((item) => item !== normalized);
-  return next.join(",");
-}
-observerCommand.command("status").description("Show the active observer policy").option("--json", "Output as JSON").action(async (opts) => {
-  await withDb(async (db) => {
-    const policy = await resolveObserverPolicy(db);
-    if (opts.json) {
-      console.log(JSON.stringify(policy, null, 2));
-      return;
-    }
-    console.log("Observer policy:\n");
-    console.log(`  Scope:         ${policy.scope}`);
-    console.log(`  Consent:       ${policy.consent}`);
-    console.log(`  Retention:     ${policy.retention}`);
-    console.log(
-      `  Allowlist:     ${policy.allowlist.length ? policy.allowlist.join(", ") : "(any targeted window)"}`
-    );
-    console.log(
-      `  Denylist:      ${policy.denylist.length ? policy.denylist.join(", ") : "(none)"}`
-    );
-    console.log(`  Redact titles: ${policy.redactWindowTitles}`);
-    console.log(
-      "\nBuilt-in sensitive surfaces (password managers, auth/UAC dialogs, banking) are always refused and cannot be allowlisted."
-    );
-  });
-});
-observerCommand.command("grant <process>").description(
-  "Allow the observer to capture a process (adds it to observer.allowlist)"
-).action(async (processName) => {
-  await withDb(async (db) => {
-    const next = applyObserverListChange(
-      await getSetting(db, "observer.allowlist"),
-      processName,
-      "add"
-    );
-    await setSetting(db, "observer.allowlist", next);
-    await syncObserverSidecarPolicy(db);
-    console.log(`Granted: ${processName.trim().toLowerCase()}`);
-    console.log(`observer.allowlist = ${next || "(empty)"}`);
-  });
-});
-observerCommand.command("revoke <process>").description("Remove a process from observer.allowlist").action(async (processName) => {
-  await withDb(async (db) => {
-    const next = applyObserverListChange(
-      await getSetting(db, "observer.allowlist"),
-      processName,
-      "remove"
-    );
-    await setSetting(db, "observer.allowlist", next);
-    await syncObserverSidecarPolicy(db);
-    console.log(`Revoked: ${processName.trim().toLowerCase()}`);
-    console.log(`observer.allowlist = ${next || "(empty)"}`);
-  });
-});
-
-// src/cli/commands/profile.ts
-import { homedir as homedir12 } from "os";
-import { dirname as dirname6, join as join20, resolve as resolve7 } from "path";
-import { Command as Command13 } from "commander";
-var C2 = {
-  reset: "\x1B[0m",
-  bold: "\x1B[1m",
-  cyan: "\x1B[36m",
-  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}`);
-  console.log(`  mode:          ${C2.cyan}${profile.mode}${C2.reset}`);
-  console.log(`  personal dir:  ${C2.cyan}${profile.personalDir}${C2.reset}`);
-  console.log(`  sync:          ${sync}`);
-  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) => {
-  if (opts.mode && opts.mode !== "developer" && opts.mode !== "default") {
-    console.error(`Invalid --mode: ${opts.mode}. Use developer or default.`);
-    process.exit(1);
-  }
-  let db;
-  try {
-    if (opts.mode) setInstallMode(opts.mode);
-    db = await openDatabaseWithSync({ initialize: true });
-    if (opts.dir) {
-      await setSetting(db, "personal.workspace_dir", resolve7(opts.dir));
-    }
-    const personalDir = await getSetting(db, "personal.workspace_dir") || defaultPersonalDir();
-    await db.close();
-    db = void 0;
-    const dbPath = getDefaultDbPath();
-    const profile = {
-      mode: getInstallMode(),
-      personalDir,
-      syncProvider: detectSyncProvider(personalDir),
-      dataDir: dirname6(dbPath),
-      dbPath
-    };
-    if (opts.json) {
-      console.log(JSON.stringify(profile, null, 2));
-      return;
-    }
-    render(profile);
+  }
+  let shell;
+  try {
+    shell = normalizeShell(opts.shell);
   } catch (err) {
-    await db?.close();
-    console.error("Error:", err.message);
+    console.error(`# Error: ${err.message}`);
     process.exit(1);
   }
-});
-
-// 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;
+  if (shell === "bash") {
+    console.log(generateBashUnhooks());
+  } else if (isPowerShellShell(shell)) {
+    console.log(generatePowerShellUnhooks());
+  } else {
+    console.log(generateZshUnhooks());
   }
-}
-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 });
+});
+monitorCommand.command("status").description("Show monitoring status for a session").requiredOption("--session <id>", "Session ID").option("--json", "Output as JSON").action((opts) => {
+  const stats = getMonitorLogStats(opts.session);
+  if (!stats.exists) {
+    if (opts.json) {
+      console.log(JSON.stringify({ exists: false }));
+    } else {
+      console.log(`No monitor log found for session ${opts.session}`);
+    }
     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 });
+  const events = readMonitorLog(opts.session);
+  const commands = pairCommands(events);
+  const errors = commands.filter(
+    (c) => c.exitCode != null && c.exitCode !== 0
+  ).length;
+  const meta = events.find(
+    (e) => e.type === "monitor_meta" && e.event === "start"
+  );
+  const stopped = events.some(
+    (e) => e.type === "monitor_meta" && e.event === "stop"
+  );
+  const result = {
+    sessionId: opts.session,
+    exists: true,
+    active: !stopped,
+    shell: meta?.shell ?? "unknown",
+    totalCommands: commands.length,
+    errors,
+    sizeBytes: stats.sizeBytes,
+    timeSpan: commands.length > 0 ? {
+      start: commands[0].startedAt,
+      end: commands[commands.length - 1].endedAt ?? commands[commands.length - 1].startedAt
+    } : null
+  };
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
     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;
+  console.log(`Monitor: ${opts.session}`);
+  console.log(`  Status:   ${result.active ? "active" : "stopped"}`);
+  console.log(`  Shell:    ${result.shell}`);
+  console.log(`  Commands: ${result.totalCommands}`);
+  console.log(`  Errors:   ${result.errors}`);
+  if (result.timeSpan) {
+    console.log(`  From:     ${result.timeSpan.start}`);
+    console.log(`  To:       ${result.timeSpan.end}`);
   }
-  await withDb(action);
+});
+function buildMonitorSetupCommand(dir, sessionId, shell) {
+  const zamInvocation = resolveZamInvocation(shell);
+  if (isPowerShellShell(shell)) {
+    return [
+      `Set-Location -LiteralPath ${psSingleQuoted2(dir)}`,
+      `$__zamHook = ${zamInvocation} monitor start --session ${psSingleQuoted2(sessionId)} --shell ${shell}`,
+      "Invoke-Expression ($__zamHook -join [Environment]::NewLine)",
+      "Remove-Variable __zamHook"
+    ].join("; ");
+  }
+  return `cd ${JSON.stringify(dir)} && eval "$(${zamInvocation} monitor start --session ${sessionId} --shell ${shell})"`;
 }
-var providerCommand = new Command14("provider").description(
-  "Configure role-based AI providers (url/model/flavor/key, per role)"
-);
-providerCommand.command("list").description("Show configured providers, role bindings, and key status").option("--json", "Output as JSON").option("--machine", "Read machine-local providers from ~/.zam/config.json").action(async (opts) => {
-  const machine = Boolean(opts.machine);
-  await withProviderScope(machine, async (db) => {
-    const providers = await readScopedProviders(db, machine);
-    const roles = await readScopedRoles(db, machine);
-    const rows = buildProviderListing(
-      providers,
-      (ref) => getProviderApiKey(ref) !== null
-    );
-    const orphans = findOrphanKeyRefs(listProviderApiKeyRefs(), providers);
-    if (opts.json) {
-      console.log(
-        JSON.stringify(
-          {
-            scope: machine ? "machine" : "shared",
-            providers: rows,
-            roles,
-            orphans
-          },
-          null,
-          2
-        )
-      );
-      return;
-    }
-    console.log(
-      `Providers (${opts.machine ? "~/.zam/config.json ai.providers" : "llm.providers"}):
-`
-    );
-    if (rows.length === 0) {
-      console.log(
-        "  (none) \u2014 add one: zam provider add <name> --url <url> --model <model>"
-      );
-    } else {
-      for (const row of rows) {
-        const key = row.keyState === "set" ? "\x1B[32mkey \u2713\x1B[0m" : row.keyState === "missing" ? `\x1B[31mkey \u2717 (set: zam provider set-key ${row.apiKeyRef})\x1B[0m` : "\x1B[90mno key\x1B[0m";
-        console.log(`  \x1B[36m${row.name.padEnd(12)}\x1B[0m ${key}`);
-        console.log(`      url:    ${row.url ?? "(inherits llm.url)"}`);
-        console.log(`      model:  ${row.model ?? "(inherits llm.model)"}`);
-        console.log(`      flavor: ${row.apiFlavor}`);
-        if (row.label) console.log(`      label:  ${row.label}`);
-        if (row.local !== void 0) {
-          console.log(`      local:  ${row.local ? "yes" : "no"}`);
-        }
-        if (row.runner) console.log(`      runner: ${row.runner}`);
-        if (row.apiKeyRef) console.log(`      key-ref: ${row.apiKeyRef}`);
-      }
+monitorCommand.command("open").description("Open a new monitored terminal window for a session").requiredOption("--session <id>", "Session ID to monitor").option("--dir <path>", "Working directory (defaults to cwd)").option(
+  "--shell <type>",
+  "Shell type: zsh | bash | pwsh | powershell (auto-detected)"
+).action(async (opts) => {
+  let shell;
+  try {
+    shell = normalizeShell(opts.shell);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+  let db;
+  try {
+    db = await openDatabase();
+    const session = await db.prepare("SELECT id, completed_at FROM sessions WHERE id = ?").get(opts.session);
+    if (!session) {
+      console.error(`Error: Session not found: ${opts.session}`);
+      process.exit(1);
     }
-    console.log("\nRoles (llm.roles):\n");
-    for (const role of VALID_ROLES) {
-      const binding = roles[role];
-      if (!binding?.primary) {
-        console.log(`  ${role.padEnd(7)} \x1B[90m(unset)\x1B[0m`);
-      } else {
-        const fb = binding.fallback ? ` \u2192 fallback: ${binding.fallback}` : "";
-        console.log(`  ${role.padEnd(7)} primary: ${binding.primary}${fb}`);
-      }
+    if (session.completed_at) {
+      console.error(`Error: Session already completed: ${opts.session}`);
+      process.exit(1);
     }
-    if (orphans.length > 0) {
-      console.log(
-        `
-\x1B[33mOrphan keys (stored but unreferenced):\x1B[0m ${orphans.join(", ")}`
-      );
+    if (!await getSetting(db, "monitor_method")) {
+      await setSetting(db, "monitor_method", "terminal");
     }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  } finally {
+    await db?.close();
+  }
+  const dir = opts.dir ?? process.cwd();
+  const shellSetup = buildMonitorSetupCommand(dir, opts.session, shell);
+  openTerminalWindow({
+    shellSetup,
+    label: `monitor-${opts.session}`,
+    dir,
+    shell
   });
 });
-providerCommand.command("add <name>").description("Add or update a provider record in llm.providers").option("--label <label>", "Human-readable provider label").option("--url <url>", "Endpoint base URL (e.g. https://api.deepseek.com/v1)").option("--model <model>", "Model id (e.g. deepseek-v4-flash)").option("--local", "Mark this provider as a local/on-device endpoint").option(
-  "--runner <runner>",
-  "Local runner hint (flm, foundry-local, ollama, ...)"
-).option(
-  "--flavor <flavor>",
-  `Wire protocol: ${VALID_API_FLAVORS.join(" | ")} (default: inferred from URL)`
-).option(
-  "--key-ref <ref>",
-  "Credential reference for the API key (default: <name> when --key is given)"
-).option(
-  "--key <value>",
-  "Store this API key now (prefer `set-key` to keep it out of shell history)"
-).option("--machine", "Store this provider in ~/.zam/config.json").action(async (name, opts) => {
-  let apiFlavor;
-  if (opts.flavor) {
-    if (!VALID_API_FLAVORS.includes(opts.flavor)) {
-      console.error(
-        `Invalid --flavor: ${opts.flavor}. Use ${VALID_API_FLAVORS.join(" or ")}.`
-      );
-      process.exit(1);
+
+// src/cli/commands/observer.ts
+import { Command as Command13 } from "commander";
+var observerCommand = new Command13("observer").description(
+  "Configure what the UI observer may capture (Layer 2 policy)"
+);
+function applyObserverListChange(current, entry, op) {
+  const normalized = entry.trim().toLowerCase();
+  const list = parseObserverList(current);
+  const next = op === "add" ? [.../* @__PURE__ */ new Set([...list, normalized])] : list.filter((item) => item !== normalized);
+  return next.join(",");
+}
+observerCommand.command("status").description("Show the active observer policy").option("--json", "Output as JSON").action(async (opts) => {
+  await withDb(async (db) => {
+    const policy = await resolveObserverPolicy(db);
+    if (opts.json) {
+      console.log(JSON.stringify(policy, null, 2));
+      return;
     }
-    apiFlavor = opts.flavor;
-  }
-  const apiKeyRef = opts.keyRef ?? (opts.key ? name : void 0);
-  const machine = Boolean(opts.machine);
-  await withProviderScope(machine, async (db) => {
-    const providers = await readScopedProviders(db, machine);
-    const next = upsertProviderRecord(providers, name, {
-      label: opts.label,
-      url: opts.url,
-      model: opts.model,
-      apiFlavor,
-      apiKeyRef,
-      local: opts.local ? true : void 0,
-      runner: opts.runner
-    });
-    await writeScopedProviders(db, machine, next);
-    if (opts.key && apiKeyRef) setProviderApiKey(apiKeyRef, opts.key);
-    const rec = next[name];
+    console.log("Observer policy:\n");
+    console.log(`  Scope:         ${policy.scope}`);
+    console.log(`  Consent:       ${policy.consent}`);
+    console.log(`  Retention:     ${policy.retention}`);
     console.log(
-      `Provider "${name}" saved (${machine ? "machine-local" : "shared"}):`
+      `  Allowlist:     ${policy.allowlist.length ? policy.allowlist.join(", ") : "(any targeted window)"}`
     );
-    console.log(`  url:     ${rec.url ?? "(inherits llm.url)"}`);
-    console.log(`  model:   ${rec.model ?? "(inherits llm.model)"}`);
-    if (rec.label) console.log(`  label:   ${rec.label}`);
-    if (rec.local !== void 0) {
-      console.log(`  local:   ${rec.local ? "yes" : "no"}`);
-    }
-    if (rec.runner) console.log(`  runner:  ${rec.runner}`);
     console.log(
-      `  flavor:  ${rec.apiFlavor ?? `${rec.url ? inferApiFlavor(rec.url) : "chat-completions"} (inferred)`}`
+      `  Denylist:      ${policy.denylist.length ? policy.denylist.join(", ") : "(none)"}`
     );
-    console.log(`  key-ref: ${rec.apiKeyRef ?? "(none \u2014 uses default key)"}`);
-    if (opts.key) {
-      console.log(`  key:     stored (${maskSecret(opts.key)})`);
-    } else if (rec.apiKeyRef && getProviderApiKey(rec.apiKeyRef) === null) {
-      console.log(
-        `
-  \u26A0 No key stored for "${rec.apiKeyRef}". Run: zam provider set-key ${rec.apiKeyRef}`
-      );
-    }
-    if (!rec.url) {
-      console.log(
-        "\n  \u26A0 No --url set; this provider inherits the base llm.url."
-      );
-    }
+    console.log(`  Redact titles: ${policy.redactWindowTitles}`);
     console.log(
-      `
-Bind it to a role: zam provider use recall --primary ${name}`
+      "\nBuilt-in sensitive surfaces (password managers, auth/UAC dialogs, banking) are always refused and cannot be allowlisted."
     );
   });
 });
-providerCommand.command("remove <name>").description("Remove a provider record from llm.providers").option("--machine", "Remove from ~/.zam/config.json instead of the DB").action(async (name, opts) => {
-  const machine = Boolean(opts.machine);
-  await withProviderScope(machine, async (db) => {
-    const providers = await readScopedProviders(db, machine);
-    const { providers: next, removed } = removeProviderRecord(
-      providers,
-      name
-    );
-    if (!removed) {
-      console.log(`No such provider: ${name}`);
-      return;
-    }
-    await writeScopedProviders(db, machine, next);
-    console.log(
-      `Removed provider "${name}" (${machine ? "machine-local" : "shared"}).`
-    );
-    const referencing = rolesReferencing(
-      await readScopedRoles(db, machine),
-      name
+observerCommand.command("grant <process>").description(
+  "Allow the observer to capture a process (adds it to observer.allowlist)"
+).action(async (processName) => {
+  await withDb(async (db) => {
+    const next = applyObserverListChange(
+      await getSetting(db, "observer.allowlist"),
+      processName,
+      "add"
     );
-    if (referencing.length > 0) {
-      console.log(
-        `  \u26A0 Still referenced by role(s): ${referencing.join(", ")} \u2014 rebind with: zam provider use <role> --primary <name>`
-      );
-    }
+    await setSetting(db, "observer.allowlist", next);
+    await syncObserverSidecarPolicy(db);
+    console.log(`Granted: ${processName.trim().toLowerCase()}`);
+    console.log(`observer.allowlist = ${next || "(empty)"}`);
   });
 });
-providerCommand.command("use <role>").description(`Bind providers to a role (${VALID_ROLES.join(" | ")})`).option("--primary <name>", "Primary provider").option("--fallback <name>", "Fallback provider (optional)").option("--machine", "Bind the role in ~/.zam/config.json").action(async (role, opts) => {
-  if (!VALID_ROLES.includes(role)) {
-    console.error(`Invalid role: ${role}. Use ${VALID_ROLES.join(", ")}.`);
-    process.exit(1);
-  }
-  if (!opts.primary) {
-    console.error("--primary is required.");
-    process.exit(1);
-  }
-  const machine = Boolean(opts.machine);
-  await withProviderScope(machine, async (db) => {
-    const providers = await readScopedProviders(db, machine);
-    await writeScopedRoles(
-      db,
-      machine,
-      bindRoleProviders(
-        await readScopedRoles(db, machine),
-        role,
-        opts.primary,
-        opts.fallback
-      )
-    );
-    const fb = opts.fallback ? `, fallback: ${opts.fallback}` : "";
-    console.log(
-      `Role "${role}" \u2192 primary: ${opts.primary}${fb} (${machine ? "machine-local" : "shared"})`
+observerCommand.command("revoke <process>").description("Remove a process from observer.allowlist").action(async (processName) => {
+  await withDb(async (db) => {
+    const next = applyObserverListChange(
+      await getSetting(db, "observer.allowlist"),
+      processName,
+      "remove"
     );
-    for (const [label, ref] of [
-      ["primary", opts.primary],
-      ["fallback", opts.fallback]
-    ]) {
-      if (ref && !(ref in providers)) {
-        console.log(
-          `  \u26A0 ${label} "${ref}" is not a defined provider yet. Add it: zam provider add ${ref} --url <url> --model <model>`
-        );
-      }
-    }
+    await setSetting(db, "observer.allowlist", next);
+    await syncObserverSidecarPolicy(db);
+    console.log(`Revoked: ${processName.trim().toLowerCase()}`);
+    console.log(`observer.allowlist = ${next || "(empty)"}`);
   });
 });
-providerCommand.command("set-key <ref>").description(
-  "Store an API key for a provider reference (in credentials.json)"
-).option(
-  "--key <value>",
-  "The API key (omit to enter it interactively, hidden)"
-).action(async (ref, opts) => {
+
+// 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 Command14 } from "commander";
+var C2 = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  cyan: "\x1B[36m",
+  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}`);
+  console.log(`  mode:          ${C2.cyan}${profile.mode}${C2.reset}`);
+  console.log(`  personal dir:  ${C2.cyan}${profile.personalDir}${C2.reset}`);
+  console.log(`  sync:          ${sync}`);
+  console.log(`  data dir:      ${C2.cyan}${profile.dataDir}${C2.reset}`);
+  console.log(`  database:      ${C2.cyan}${profile.dbPath}${C2.reset}`);
+}
+var profileCommand = new Command14("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);
+  }
+  let db;
   try {
-    const key = opts.key ?? await password2({ message: `API key for "${ref}":` });
-    if (!key || key.trim().length === 0) {
-      console.error("No key provided.");
-      process.exit(1);
+    if (opts.mode) setInstallMode(opts.mode);
+    db = await openDatabaseWithSync({ initialize: true });
+    if (opts.dir) {
+      await setSetting(db, "personal.workspace_dir", resolve8(opts.dir));
     }
-    setProviderApiKey(ref, key.trim());
-    console.log(`Stored API key for "${ref}" (${maskSecret(key.trim())}).`);
-  } catch (err) {
-    if (err.name === "ExitPromptError") {
-      console.log("\nCancelled.");
-      process.exit(0);
+    const personalDir = await getSetting(db, "personal.workspace_dir") || defaultPersonalDir();
+    await db.close();
+    db = void 0;
+    const dbPath = getDefaultDbPath();
+    const profile = {
+      mode: getInstallMode(),
+      personalDir,
+      syncProvider: detectSyncProvider(personalDir),
+      dataDir: dirname6(dbPath),
+      dbPath
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(profile, null, 2));
+      return;
     }
+    render(profile);
+  } catch (err) {
+    await db?.close();
     console.error("Error:", err.message);
     process.exit(1);
   }
 });
-providerCommand.command("clear-key <ref>").description("Remove a stored API key").action((ref) => {
-  clearProviderApiKey(ref);
-  console.log(`Cleared API key for "${ref}".`);
-});
 
 // src/cli/commands/review.ts
 import { Command as Command15 } from "commander";
@@ -11897,7 +12395,7 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
 });
 
 // src/cli/commands/snapshot.ts
-import { existsSync as existsSync22, mkdirSync as mkdirSync12, readFileSync as readFileSync13, writeFileSync as writeFileSync11 } from "fs";
+import { existsSync as existsSync22, mkdirSync as mkdirSync13, readFileSync as readFileSync13, writeFileSync as writeFileSync11 } from "fs";
 import { homedir as homedir13 } from "os";
 import { dirname as dirname7, join as join21 } from "path";
 import { Command as Command19 } from "commander";
@@ -11931,7 +12429,7 @@ var exportCmd = new Command19("export").description("Write a portable SQL-text s
     const out = opts.out ?? join21(personalDir, "snapshots", defaultOutName());
     const dir = dirname7(out);
     if (dir && dir !== "." && !existsSync22(dir)) {
-      mkdirSync12(dir, { recursive: true });
+      mkdirSync13(dir, { recursive: true });
     }
     writeFileSync11(out, snapshot, "utf-8");
     console.log(`Snapshot written: ${out}`);
@@ -12601,7 +13099,7 @@ ${C3.dim}After that, 'zam ui' launches it directly.${C3.reset}`
 
 // src/cli/commands/update.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync24, readFileSync as readFileSync14, realpathSync } from "fs";
+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";
@@ -12715,7 +13213,7 @@ var checkCmd = new Command23("check").description("Check whether a newer ZAM has
   }
 );
 function findSourceRepo() {
-  let dir = realpathSync(dirname9(fileURLToPath4(import.meta.url)));
+  let dir = realpathSync2(dirname9(fileURLToPath4(import.meta.url)));
   let parent = dirname9(dir);
   while (parent !== dir) {
     if (existsSync24(join23(dir, ".git"))) return dir;