zam-core 0.5.1 → 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();
@@ -5368,12 +5383,28 @@ import {
 } 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) {
@@ -5484,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 } : {}
   };
 }
@@ -5566,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";
@@ -5589,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.
@@ -5643,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) {
@@ -5760,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");
@@ -5861,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";
@@ -5889,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 {
@@ -5905,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";
@@ -5927,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") {
@@ -6012,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 {
@@ -6200,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;
 }
@@ -6416,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,
@@ -6472,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: [
         {
@@ -6627,271 +6734,642 @@ function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-// src/cli/commands/resolve-user.ts
-async function ensureDefaultUser(db, preferredUserId) {
-  const stored = await getSetting(db, "user.id");
-  if (stored) return stored;
-  const userId = preferredUserId?.trim() || process.env.ZAM_USER?.trim() || process.env.USERNAME?.trim() || process.env.USER?.trim() || "default";
-  await setSetting(db, "user.id", userId);
-  return userId;
+// src/cli/commands/provider.ts
+import { password } from "@inquirer/prompts";
+import { Command as Command2 } from "commander";
+
+// src/cli/commands/shared/db.ts
+function defaultErrorHandler(message) {
+  console.error("Error:", message);
+  process.exit(1);
 }
-async function resolveUser(opts, db, resolveOpts) {
-  if (opts.user) return opts.user;
-  const stored = await getSetting(db, "user.id");
-  if (stored) return stored;
-  const message = "No user specified. Set a default with: zam whoami --set <id>";
-  if (resolveOpts?.json) {
-    console.log(JSON.stringify({ error: message }, null, 2));
-  } else {
-    console.error(message);
+async function withDb(fn, onError = defaultErrorHandler) {
+  let db;
+  try {
+    db = await openDatabase();
+    await fn(db);
+  } catch (err) {
+    onError(err.message);
+  } finally {
+    await db?.close();
   }
-  process.exit(1);
+}
+function jsonOut(data) {
+  console.log(JSON.stringify(data, null, 2));
 }
 
-// src/cli/commands/setup.ts
-import {
-  existsSync as existsSync15,
-  lstatSync,
-  mkdirSync as mkdirSync8,
-  readdirSync as readdirSync2,
-  readFileSync as readFileSync10,
-  realpathSync,
-  rmSync as rmSync2,
-  symlinkSync,
-  writeFileSync as writeFileSync7
-} from "fs";
-import { basename as basename4, dirname as dirname5, join as join15, resolve as resolve3 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { Command as Command2 } from "commander";
-var packageRoot = [
-  fileURLToPath2(new URL("../..", import.meta.url)),
-  fileURLToPath2(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync15(join15(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
-var ALL_SETUP_AGENTS = ["claude", "copilot", "codex", "agent"];
-var SKILL_PAIRS = [
-  {
-    from: join15(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
-    to: join15(".claude", "skills", "zam", "SKILL.md"),
-    agents: ["claude", "copilot"]
-  },
-  {
-    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.`
-      );
-    }
-    for (const item of mapped) selected.add(item);
-  }
-  return selected;
+// src/cli/commands/provider.ts
+var VALID_API_FLAVORS = [
+  "chat-completions",
+  "anthropic-messages"
+];
+var VALID_ROLES = ["vision", "recall", "text"];
+function upsertProviderRecord(providers, name, patch) {
+  const merged = { ...providers[name] ?? {} };
+  if (patch.url !== void 0) merged.url = patch.url;
+  if (patch.model !== void 0) merged.model = patch.model;
+  if (patch.apiFlavor !== void 0) merged.apiFlavor = patch.apiFlavor;
+  if (patch.apiKeyRef !== void 0) merged.apiKeyRef = patch.apiKeyRef;
+  if (patch.label !== void 0) merged.label = patch.label;
+  if (patch.local !== void 0) merged.local = patch.local;
+  if (patch.runner !== void 0) merged.runner = patch.runner;
+  return { ...providers, [name]: merged };
 }
-function pathExists(path) {
+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 {
-    lstatSync(path);
-    return true;
+    return JSON.parse(raw);
   } catch {
-    return false;
+    return fallback;
   }
 }
-function comparableRealPath(path) {
-  const real = realpathSync(path);
-  return process.platform === "win32" ? real.toLowerCase() : real;
+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 pathsResolveToSameDirectory(sourceDir, destinationDir) {
-  try {
-    return comparableRealPath(destinationDir) === comparableRealPath(sourceDir);
-  } catch {
-    return false;
+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 linkPointsTo(sourceDir, destinationDir) {
-  try {
-    return lstatSync(destinationDir).isSymbolicLink() && pathsResolveToSameDirectory(sourceDir, destinationDir);
-  } catch {
-    return false;
+async function writeScopedRoles(db, machine, r) {
+  if (machine) {
+    const config = getMachineAiConfig();
+    saveMachineAiConfig({ ...config, roles: r });
+    return;
   }
+  if (!db)
+    throw new Error("Database is required for shared provider settings.");
+  await setSetting(db, "llm.roles", JSON.stringify(r));
 }
-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;
+async function withProviderScope(machine, action) {
+  if (machine) {
+    await action(void 0);
+    return;
   }
+  await withDb(action);
 }
-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}`);
+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;
+    }
+    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}`);
       }
-      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;
+    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 (linkPointsTo(sourceDir, destinationDir)) {
-      log(`  skip  ${dirname5(to)} (already linked)`);
-      results.push({
-        source: sourceDir,
-        destination: destinationDir,
-        action: "skipped",
-        reason: "already-linked"
-      });
-      continue;
+    if (orphans.length > 0) {
+      console.log(
+        `
+\x1B[33mOrphan keys (stored but unreferenced):\x1B[0m ${orphans.join(", ")}`
+      );
     }
-    const destinationExists = pathExists(destinationDir);
-    const replaceExisting = destinationExists && (Boolean(opts.force) || isReplaceableCopiedSkill(destinationDir));
-    if (destinationExists && !replaceExisting) {
-      if (!opts.quiet) {
-        console.warn(
-          `  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;
+  });
+});
+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);
     }
-    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"
+    apiFlavor = opts.flavor;
+  }
+  const apiKeyRef = opts.keyRef ?? (opts.key ? name : void 0);
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const next = upsertProviderRecord(providers, name, {
+      label: opts.label,
+      url: opts.url,
+      model: opts.model,
+      apiFlavor,
+      apiKeyRef,
+      local: opts.local ? true : void 0,
+      runner: opts.runner
+    });
+    await writeScopedProviders(db, machine, next);
+    if (opts.key && apiKeyRef) setProviderApiKey(apiKeyRef, opts.key);
+    const rec = next[name];
+    console.log(
+      `Provider "${name}" saved (${machine ? "machine-local" : "shared"}):`
+    );
+    console.log(`  url:     ${rec.url ?? "(inherits llm.url)"}`);
+    console.log(`  model:   ${rec.model ?? "(inherits llm.model)"}`);
+    if (rec.label) console.log(`  label:   ${rec.label}`);
+    if (rec.local !== void 0) {
+      console.log(`  local:   ${rec.local ? "yes" : "no"}`);
+    }
+    if (rec.runner) console.log(`  runner:  ${rec.runner}`);
+    console.log(
+      `  flavor:  ${rec.apiFlavor ?? `${rec.url ? inferApiFlavor(rec.url) : "chat-completions"} (inferred)`}`
+    );
+    console.log(`  key-ref: ${rec.apiKeyRef ?? "(none \u2014 uses default key)"}`);
+    if (opts.key) {
+      console.log(`  key:     stored (${maskSecret(opts.key)})`);
+    } else if (rec.apiKeyRef && getProviderApiKey(rec.apiKeyRef) === null) {
+      console.log(
+        `
+  \u26A0 No key stored for "${rec.apiKeyRef}". Run: zam provider set-key ${rec.apiKeyRef}`
       );
-      log(`  ${action === "linked" ? "link" : "relink"}  ${dirname5(to)}`);
     }
-    results.push({ source: sourceDir, destination: destinationDir, action });
+    if (!rec.url) {
+      console.log(
+        "\n  \u26A0 No --url set; this provider inherits the base llm.url."
+      );
+    }
+    console.log(
+      `
+Bind it to a role: zam provider use recall --primary ${name}`
+    );
+  });
+});
+providerCommand.command("remove <name>").description("Remove a provider record from llm.providers").option("--machine", "Remove from ~/.zam/config.json instead of the DB").action(async (name, opts) => {
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const { providers: next, removed } = removeProviderRecord(
+      providers,
+      name
+    );
+    if (!removed) {
+      console.log(`No such provider: ${name}`);
+      return;
+    }
+    await writeScopedProviders(db, machine, next);
+    console.log(
+      `Removed provider "${name}" (${machine ? "machine-local" : "shared"}).`
+    );
+    const referencing = rolesReferencing(
+      await readScopedRoles(db, machine),
+      name
+    );
+    if (referencing.length > 0) {
+      console.log(
+        `  \u26A0 Still referenced by role(s): ${referencing.join(", ")} \u2014 rebind with: zam provider use <role> --primary <name>`
+      );
+    }
+  });
+});
+providerCommand.command("use <role>").description(`Bind providers to a role (${VALID_ROLES.join(" | ")})`).option("--primary <name>", "Primary provider").option("--fallback <name>", "Fallback provider (optional)").option("--machine", "Bind the role in ~/.zam/config.json").action(async (role, opts) => {
+  if (!VALID_ROLES.includes(role)) {
+    console.error(`Invalid role: ${role}. Use ${VALID_ROLES.join(", ")}.`);
+    process.exit(1);
   }
-  return results;
-}
-function formatDatabaseInitTarget(target) {
-  switch (target.kind) {
-    case "local":
-      return `ZAM database at ${target.location} (local SQLite)`;
-    case "turso-remote":
-      return `ZAM database via Turso remote at ${target.location}`;
-    case "turso-native":
-      return `ZAM database via Turso native driver at ${target.location}`;
-    case "turso-replica":
-      return `ZAM database replica at ${target.location} syncing from ${target.syncUrl}`;
+  if (!opts.primary) {
+    console.error("--primary is required.");
+    process.exit(1);
   }
-}
-async function initDatabase(skipInit) {
-  if (skipInit) return;
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    await writeScopedRoles(
+      db,
+      machine,
+      bindRoleProviders(
+        await readScopedRoles(db, machine),
+        role,
+        opts.primary,
+        opts.fallback
+      )
+    );
+    const fb = opts.fallback ? `, fallback: ${opts.fallback}` : "";
+    console.log(
+      `Role "${role}" \u2192 primary: ${opts.primary}${fb} (${machine ? "machine-local" : "shared"})`
+    );
+    for (const [label, ref] of [
+      ["primary", opts.primary],
+      ["fallback", opts.fallback]
+    ]) {
+      if (ref && !(ref in providers)) {
+        console.log(
+          `  \u26A0 ${label} "${ref}" is not a defined provider yet. Add it: zam provider add ${ref} --url <url> --model <model>`
+        );
+      }
+    }
+  });
+});
+providerCommand.command("set-key <ref>").description(
+  "Store an API key for a provider reference (in credentials.json)"
+).option(
+  "--key <value>",
+  "The API key (omit to enter it interactively, hidden)"
+).action(async (ref, opts) => {
   try {
-    const 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`);
+    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);
     }
-  }
-}
-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");
+    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);
     }
-    return "write";
+    console.error("Error:", err.message);
+    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()}
+});
+providerCommand.command("clear-key <ref>").description("Remove a stored API key").action((ref) => {
+  clearProviderApiKey(ref);
+  console.log(`Cleared API key for "${ref}".`);
+});
 
-${block}
-`;
-  if (!dryRun) writeFileSync7(dest, next, "utf8");
-  return start >= 0 && end > start ? "update" : "write";
+// 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;
 }
-function logInstructionAction(action, label, dryRun) {
-  if (action === "skip") {
-    console.log(`  skip  ${label} (ZAM block already present)`);
+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.log(`  ${dryRun ? "would " : ""}${action} ${label}`);
+    console.error(message);
   }
+  process.exit(1);
 }
-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(
+
+// 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.`
+      );
+    }
+    for (const item of mapped) selected.add(item);
+  }
+  return selected;
+}
+function pathExists(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+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;
+  }
+}
+function linkPointsTo(sourceDir, destinationDir) {
+  try {
+    return lstatSync(destinationDir).isSymbolicLink() && pathsResolveToSameDirectory(sourceDir, destinationDir);
+  } catch {
+    return false;
+  }
+}
+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;
+  }
+}
+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(
+          `  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;
+    }
+    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 });
+  }
+  return results;
+}
+function formatDatabaseInitTarget(target) {
+  switch (target.kind) {
+    case "local":
+      return `ZAM database at ${target.location} (local SQLite)`;
+    case "turso-remote":
+      return `ZAM database via Turso remote at ${target.location}`;
+    case "turso-native":
+      return `ZAM database via Turso native driver at ${target.location}`;
+    case "turso-replica":
+      return `ZAM database replica at ${target.location} syncing from ${target.syncUrl}`;
+  }
+}
+async function initDatabase(skipInit) {
+  if (skipInit) return;
+  try {
+    const target = getDatabaseTargetInfo();
+    const db = await openDatabaseWithSync({ initialize: true });
+    await db.close();
+    console.log(`  init  ${formatDatabaseInitTarget(target)}`);
+  } catch (err) {
+    const msg = err.message;
+    if (!msg.includes("already")) {
+      console.warn(`  warn  database init: ${msg}`);
+    } else {
+      console.log(`  skip  database already initialized`);
+    }
+  }
+}
+var ZAM_BLOCK_START = "<!-- ZAM:START -->";
+var ZAM_BLOCK_END = "<!-- ZAM:END -->";
+function upsertMarkedBlock(dest, blockBody, dryRun) {
+  const block = `${ZAM_BLOCK_START}
+${blockBody.trim()}
+${ZAM_BLOCK_END}`;
+  if (!existsSync15(dest)) {
+    if (!dryRun) {
+      mkdirSync8(dirname5(dest), { recursive: true });
+      writeFileSync7(dest, `${block}
+`, "utf8");
+    }
+    return "write";
+  }
+  const existing = readFileSync10(dest, "utf8");
+  if (existing.includes(block)) return "skip";
+  const start = existing.indexOf(ZAM_BLOCK_START);
+  const end = existing.indexOf(ZAM_BLOCK_END);
+  const next = start >= 0 && end > start ? `${existing.slice(0, start)}${block}${existing.slice(end + ZAM_BLOCK_END.length)}` : `${existing.trimEnd()}
+
+${block}
+`;
+  if (!dryRun) writeFileSync7(dest, next, "utf8");
+  return start >= 0 && end > start ? "update" : "write";
+}
+function logInstructionAction(action, label, dryRun) {
+  if (action === "skip") {
+    console.log(`  skip  ${label} (ZAM block already present)`);
+  } else {
+    console.log(`  ${dryRun ? "would " : ""}${action} ${label}`);
+  }
+}
+function writeClaudeMd(skipClaudeMd, cwd = process.cwd(), opts = {}) {
+  if (skipClaudeMd) return;
+  const dest = join15(cwd, "CLAUDE.md");
+  if (existsSync15(dest)) {
+    if (!opts.updateExisting) {
+      console.log(`  skip  CLAUDE.md (already present)`);
+      return;
+    }
+    const action = upsertMarkedBlock(
       dest,
       `## ZAM learning sessions
 
@@ -7008,7 +7486,7 @@ ZAM is available in this repository through \`.claude/skills/zam/\`. Use the \`z
     Boolean(opts.dryRun)
   );
 }
-var setupCommand = new Command2("setup").description(
+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>",
@@ -7061,33 +7539,13 @@ var setupCommand = new Command2("setup").description(
   }
 );
 
-// src/cli/commands/shared/db.ts
-function defaultErrorHandler(message) {
-  console.error("Error:", message);
-  process.exit(1);
-}
-async function withDb(fn, onError = defaultErrorHandler) {
-  let db;
-  try {
-    db = await openDatabase();
-    await fn(db);
-  } catch (err) {
-    onError(err.message);
-  } finally {
-    await db?.close();
-  }
-}
-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";
+import { Command as Command4 } from "commander";
 function runGit(cwd, args) {
   try {
     return execFileSync3("git", args, {
@@ -7105,7 +7563,7 @@ function ghRepoCreateArgs(repoName, repoVisibility) {
 function gitRemoteArgs(githubUrl, hasOrigin) {
   return hasOrigin ? ["remote", "set-url", "origin", githubUrl] : ["remote", "add", "origin", githubUrl];
 }
-var workspaceCommand = new Command3("workspace").description(
+var workspaceCommand = new Command4("workspace").description(
   "Manage your ZAM learning workspace"
 );
 var WORKSPACE_KINDS = [
@@ -7461,6 +7919,12 @@ function parseNonNegativeIntegerOption(name, value) {
   }
   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);
 }
@@ -7498,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) => {
@@ -7768,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, {
@@ -7780,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 {
       }
@@ -7809,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
     });
@@ -8908,6 +9378,188 @@ bridgeCommand.command("provider-status").description("Show secret-safe provider
     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(
   "Check if UI observer vision analysis is enabled and ready (JSON)"
 ).action(async () => {
@@ -8954,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) {
@@ -8965,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;
@@ -8974,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,
@@ -8984,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,
@@ -9223,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) => {
@@ -9422,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(
@@ -9449,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) {
@@ -9540,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) {
@@ -9569,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)) {
@@ -9599,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;
@@ -9691,7 +10350,7 @@ ZAM Auto-Stale Complete: Scanned ${changedFiles.length} file(s).`
 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;
@@ -9704,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(
@@ -9877,7 +10536,7 @@ import { existsSync as existsSync20, mkdirSync as mkdirSync12, writeFileSync as
 import { homedir as homedir11 } from "os";
 import { join as join19, resolve as resolve7 } from "path";
 import { confirm as confirm2, input as input4 } from "@inquirer/prompts";
-import { Command as Command9 } from "commander";
+import { 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`);
@@ -9914,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"
@@ -10090,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 = {
@@ -10428,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;
@@ -10484,7 +11143,7 @@ ${t(locale, "welcome", { count: queue.items.length })}`);
             question: item.question
           });
           if (healed) {
-            resolvedQuestion = healed;
+            resolvedQuestion = healed.question;
           }
         } catch {
         }
@@ -10549,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) {
@@ -10672,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(
@@ -10832,497 +11492,148 @@ monitorCommand.command("open").description("Open a new monitored terminal window
       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 resolve8 } 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", resolve8(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);
-  } catch (err) {
-    await db?.close();
-    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;
-  }
-}
-var readProviders = (db) => readJson(db, "llm.providers", {});
-var readRoles = (db) => readJson(db, "llm.roles", {});
-async function readScopedProviders(db, machine) {
-  if (machine) return getMachineAiConfig().providers ?? {};
-  if (!db)
-    throw new Error("Database is required for shared provider settings.");
-  return readProviders(db);
-}
-async function readScopedRoles(db, machine) {
-  if (machine) return getMachineAiConfig().roles ?? {};
-  if (!db)
-    throw new Error("Database is required for shared provider settings.");
-  return readRoles(db);
-}
-async function writeScopedProviders(db, machine, p) {
-  if (machine) {
-    const config = getMachineAiConfig();
-    saveMachineAiConfig({ ...config, providers: p });
-    return;
-  }
-  if (!db)
-    throw new Error("Database is required for shared provider settings.");
-  await setSetting(db, "llm.providers", JSON.stringify(p));
-}
-async function writeScopedRoles(db, machine, r) {
-  if (machine) {
-    const config = getMachineAiConfig();
-    saveMachineAiConfig({ ...config, roles: r });
-    return;
-  }
-  if (!db)
-    throw new Error("Database is required for shared provider settings.");
-  await setSetting(db, "llm.roles", JSON.stringify(r));
-}
-async function withProviderScope(machine, action) {
-  if (machine) {
-    await action(void 0);
-    return;
-  }
-  await withDb(action);
-}
-var providerCommand = new Command14("provider").description(
-  "Configure role-based AI providers (url/model/flavor/key, per role)"
-);
-providerCommand.command("list").description("Show configured providers, role bindings, and key status").option("--json", "Output as JSON").option("--machine", "Read machine-local providers from ~/.zam/config.json").action(async (opts) => {
-  const machine = Boolean(opts.machine);
-  await withProviderScope(machine, async (db) => {
-    const providers = await readScopedProviders(db, machine);
-    const roles = await readScopedRoles(db, machine);
-    const rows = buildProviderListing(
-      providers,
-      (ref) => getProviderApiKey(ref) !== null
-    );
-    const orphans = findOrphanKeyRefs(listProviderApiKeyRefs(), providers);
-    if (opts.json) {
-      console.log(
-        JSON.stringify(
-          {
-            scope: machine ? "machine" : "shared",
-            providers: rows,
-            roles,
-            orphans
-          },
-          null,
-          2
-        )
-      );
-      return;
-    }
-    console.log(
-      `Providers (${opts.machine ? "~/.zam/config.json ai.providers" : "llm.providers"}):
-`
-    );
-    if (rows.length === 0) {
-      console.log(
-        "  (none) \u2014 add one: zam provider add <name> --url <url> --model <model>"
-      );
-    } else {
-      for (const row of rows) {
-        const key = row.keyState === "set" ? "\x1B[32mkey \u2713\x1B[0m" : row.keyState === "missing" ? `\x1B[31mkey \u2717 (set: zam provider set-key ${row.apiKeyRef})\x1B[0m` : "\x1B[90mno key\x1B[0m";
-        console.log(`  \x1B[36m${row.name.padEnd(12)}\x1B[0m ${key}`);
-        console.log(`      url:    ${row.url ?? "(inherits llm.url)"}`);
-        console.log(`      model:  ${row.model ?? "(inherits llm.model)"}`);
-        console.log(`      flavor: ${row.apiFlavor}`);
-        if (row.label) console.log(`      label:  ${row.label}`);
-        if (row.local !== void 0) {
-          console.log(`      local:  ${row.local ? "yes" : "no"}`);
-        }
-        if (row.runner) console.log(`      runner: ${row.runner}`);
-        if (row.apiKeyRef) console.log(`      key-ref: ${row.apiKeyRef}`);
-      }
-    }
-    console.log("\nRoles (llm.roles):\n");
-    for (const role of VALID_ROLES) {
-      const binding = roles[role];
-      if (!binding?.primary) {
-        console.log(`  ${role.padEnd(7)} \x1B[90m(unset)\x1B[0m`);
-      } else {
-        const fb = binding.fallback ? ` \u2192 fallback: ${binding.fallback}` : "";
-        console.log(`  ${role.padEnd(7)} primary: ${binding.primary}${fb}`);
-      }
-    }
-    if (orphans.length > 0) {
-      console.log(
-        `
-\x1B[33mOrphan keys (stored but unreferenced):\x1B[0m ${orphans.join(", ")}`
-      );
+      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
   });
 });
-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";