zam-core 0.5.2 → 0.5.3

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 
 // src/cli/index.ts
 import { readFileSync as readFileSync15 } from "fs";
-import { dirname as dirname10, join as join24 } from "path";
+import { dirname as dirname10, join as join25 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 import { Command as Command25 } from "commander";
 
@@ -4478,25 +4478,41 @@ function saveMachineAiConfig(ai, path = defaultConfigPath()) {
 function getConfiguredWorkspaces(path = defaultConfigPath()) {
   return loadInstallConfig(path).workspaces ?? [];
 }
-function saveConfiguredWorkspaces(workspaces, path = defaultConfigPath()) {
+function setActiveWorkspaceId(id, path = defaultConfigPath()) {
   const config = loadInstallConfig(path);
-  config.workspaces = workspaces;
+  if (id) {
+    config.activeWorkspaceId = id;
+  } else {
+    delete config.activeWorkspaceId;
+  }
   saveInstallConfig(config, path);
 }
+function getActiveWorkspace(path = defaultConfigPath()) {
+  const config = loadInstallConfig(path);
+  const id = config.activeWorkspaceId;
+  return id ? config.workspaces?.find((workspace) => workspace.id === id) : void 0;
+}
 function upsertConfiguredWorkspace(workspace, path = defaultConfigPath()) {
-  const current = getConfiguredWorkspaces(path);
+  const config = loadInstallConfig(path);
+  const current = config.workspaces ?? [];
   const next = [
     ...current.filter((candidate) => candidate.id !== workspace.id),
     workspace
   ];
-  saveConfiguredWorkspaces(next, path);
+  config.workspaces = next;
+  saveInstallConfig(config, path);
   return next;
 }
 function removeConfiguredWorkspace(id, path = defaultConfigPath()) {
-  const next = getConfiguredWorkspaces(path).filter(
+  const config = loadInstallConfig(path);
+  const next = (config.workspaces ?? []).filter(
     (workspace) => workspace.id !== id
   );
-  saveConfiguredWorkspaces(next, path);
+  config.workspaces = next;
+  if (config.activeWorkspaceId === id) {
+    config.activeWorkspaceId = next[0]?.id;
+  }
+  saveInstallConfig(config, path);
   return next;
 }
 function detectSyncProvider(dir) {
@@ -4828,7 +4844,7 @@ function getSystemProfile() {
 import { existsSync as existsSync10 } from "fs";
 import { resolve as resolve2 } from "path";
 async function getRepoPaths(db) {
-  const personalSetting = await getSetting(db, "repo.personal") || await getSetting(db, "personal.workspace_dir");
+  const personalSetting = await getSetting(db, "repo.personal") || getActiveWorkspace()?.path;
   const teamSetting = await getSetting(db, "repo.team");
   const orgSetting = await getSetting(db, "repo.org");
   return {
@@ -5372,18 +5388,12 @@ var openCmd = new Command("open").description("Open an agent harness in the work
 var agentCommand = new Command("agent").description("Provision and inspect the agent that drives ZAM sessions").addCommand(installCmd).addCommand(statusCmd).addCommand(openCmd).addCommand(listCmd).action(printStatus);
 
 // src/cli/commands/bridge.ts
-import { execFileSync as execFileSync4 } from "child_process";
+import { execFileSync as execFileSync3 } from "child_process";
 import { randomBytes as randomBytes2 } from "crypto";
-import {
-  existsSync as existsSync17,
-  mkdirSync as mkdirSync10,
-  readdirSync as readdirSync3,
-  readFileSync as readFileSync11,
-  rmSync as rmSync3
-} from "fs";
+import { existsSync as existsSync17, readdirSync as readdirSync2, readFileSync as readFileSync11, rmSync as rmSync3 } from "fs";
 import { homedir as homedir10, tmpdir as tmpdir3 } from "os";
-import { basename as basename5, join as join17, resolve as resolve5 } from "path";
-import { Command as Command5 } from "commander";
+import { join as join18, resolve as resolve4 } from "path";
+import { Command as Command2 } from "commander";
 
 // src/cli/llm/client.ts
 import { spawn as spawn2 } from "child_process";
@@ -5419,19 +5429,25 @@ async function getLlmConfig(db) {
 function getCloudModelRecommendation(url) {
   const lowercase = url.toLowerCase();
   if (lowercase.includes("openrouter.ai")) {
-    return "openrouter/free";
+    return { model: "openrouter/free", flavor: "chat-completions" };
   }
   if (lowercase.includes("openai.com") || lowercase.includes("api.openai")) {
-    return "gpt-5-mini";
+    return { model: "gpt-5-mini", flavor: "chat-completions" };
   }
   if (lowercase.includes("googleapis.com") || lowercase.includes("google")) {
-    return "gemini-3.5-flash";
+    return { model: "gemini-3.5-flash", flavor: "chat-completions" };
   }
   if (lowercase.includes("deepseek.com")) {
-    return "deepseek-v4-flash";
+    return { model: "deepseek-v4-flash", flavor: "chat-completions" };
   }
   if (lowercase.includes("mimo")) {
-    return "mimo-v2.5";
+    return { model: "mimo-v2.5", flavor: "chat-completions" };
+  }
+  if (lowercase.includes("anthropic.com")) {
+    return {
+      model: "claude-haiku-4-5-20251001",
+      flavor: "anthropic-messages"
+    };
   }
   return null;
 }
@@ -5525,14 +5541,15 @@ async function getLegacyRoleConfig(db, role, enabled) {
     const maxFramesStr = await getSetting(db, "llm.vision.max_frames");
     const parsed = maxFramesStr ? parseInt(maxFramesStr, 10) : 100;
     const url = await getSetting(db, "llm.vision.url") || base.url;
+    const recommendation = getCloudModelRecommendation(url);
     let model = await getSetting(db, "llm.vision.model");
-    if (!model) model = getCloudModelRecommendation(url) || base.model;
+    if (!model) model = recommendation?.model || base.model;
     return {
       enabled,
       url,
       model,
       apiKey: await getSetting(db, "llm.vision.api_key") || base.apiKey,
-      apiFlavor: inferApiFlavor(url),
+      apiFlavor: recommendation?.flavor || inferApiFlavor(url),
       locale: base.locale,
       source: "legacy",
       local: isLocalEndpoint(url),
@@ -5860,7 +5877,7 @@ async function prepareRecallChain(db, opts) {
       } else {
         spawnLocalRunner(endpoint.url, endpoint.model, endpoint.runner);
         while (Date.now() < deadline) {
-          await new Promise((resolve9) => setTimeout(resolve9, 1e3));
+          await new Promise((resolve10) => setTimeout(resolve10, 1e3));
           if (await isLlmOnline(endpoint.url)) {
             online = true;
             break;
@@ -5934,7 +5951,7 @@ async function checkVisionReadiness(db) {
   let warning;
   if (cfg.enabled && online && modelAvailable && !visionModelExplicit) {
     const cloudRec = getCloudModelRecommendation(active.url);
-    if (cloudRec && active.model === cloudRec) {
+    if (cloudRec && active.model === cloudRec.model) {
     } else {
       warning = `No explicit vision model configured (llm.vision.model). Falling back to base model "${active.model}", which may not support image input. Set a multimodal model: zam settings set llm.vision.model <model>`;
     }
@@ -6153,7 +6170,7 @@ async function startLocalRunner(url, model, locale, hint) {
   let attempts = 0;
   const dotsPerLine = 30;
   while (true) {
-    await new Promise((resolve9) => setTimeout(resolve9, 500));
+    await new Promise((resolve10) => setTimeout(resolve10, 500));
     if (await isLlmOnline(url)) {
       if (attempts > 0) process.stdout.write("\n");
       return true;
@@ -6242,8 +6259,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
   const dotsPerLine = 30;
   while (true) {
     let timeoutId;
-    const timeoutPromise = new Promise((resolve9) => {
-      timeoutId = setTimeout(() => resolve9("timeout"), timeoutMs);
+    const timeoutPromise = new Promise((resolve10) => {
+      timeoutId = setTimeout(() => resolve10("timeout"), timeoutMs);
     });
     const dotsInterval = setInterval(() => {
       process.stdout.write(".");
@@ -6360,7 +6377,7 @@ async function observeUiSnapshotViaLLM(db, input8) {
   const imageUrls = [];
   const isVideo = /\.(mp4|mov|m4v|avi|mkv|webm)$/i.test(input8.imagePath);
   if (isVideo) {
-    const { mkdirSync: mkdirSync14, readdirSync: readdirSync4, rmSync: rmSync4 } = await import("fs");
+    const { mkdirSync: mkdirSync14, readdirSync: readdirSync3, rmSync: rmSync4 } = await import("fs");
     const { execSync: execSync6 } = await import("child_process");
     const tempDir = join14(
       tmpdir2(),
@@ -6372,13 +6389,13 @@ async function observeUiSnapshotViaLLM(db, input8) {
         `ffmpeg -i "${input8.imagePath}" -vf "fps=1/3,scale=1280:-1" -vsync vfr "${tempDir}/frame_%03d.png"`,
         { stdio: "ignore" }
       );
-      let files = readdirSync4(tempDir).filter((f) => f.endsWith(".png")).sort();
+      let files = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
       if (files.length === 0) {
         execSync6(
           `ffmpeg -i "${input8.imagePath}" -vframes 1 "${tempDir}/frame_001.png"`,
           { stdio: "ignore" }
         );
-        files = readdirSync4(tempDir).filter((f) => f.endsWith(".png")).sort();
+        files = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
       }
       const maxFrames = cfg.maxFrames ?? 100;
       let sampledFiles = files;
@@ -6734,10 +6751,6 @@ function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-// 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);
@@ -6758,7 +6771,7 @@ function jsonOut(data) {
   console.log(JSON.stringify(data, null, 2));
 }
 
-// src/cli/commands/provider.ts
+// src/cli/providers/config.ts
 var VALID_API_FLAVORS = [
   "chat-completions",
   "anthropic-messages"
@@ -6871,1034 +6884,528 @@ async function withProviderScope(machine, action) {
   }
   await withDb(action);
 }
-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
-        )
+
+// src/cli/provisioning/index.ts
+import {
+  existsSync as existsSync15,
+  lstatSync,
+  mkdirSync as mkdirSync8,
+  readFileSync as readFileSync10,
+  realpathSync,
+  rmSync as rmSync2,
+  symlinkSync,
+  writeFileSync as writeFileSync7
+} from "fs";
+import { basename as basename4, dirname as dirname5, join as join15 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var packageRoot = [
+  fileURLToPath2(new URL("../..", import.meta.url)),
+  fileURLToPath2(new URL("../../..", import.meta.url))
+].find((candidate) => existsSync15(join15(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
+var ALL_SETUP_AGENTS = ["claude", "copilot", "codex", "agent"];
+var SKILL_PAIRS = [
+  {
+    from: join15(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
+    to: join15(".claude", "skills", "zam", "SKILL.md"),
+    agents: ["claude", "copilot"]
+  },
+  {
+    from: join15(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
+    to: join15(".agent", "skills", "zam", "SKILL.md"),
+    agents: ["agent"]
+  },
+  {
+    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.`
       );
-      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}`);
+    for (const item of mapped) selected.add(item);
+  }
+  return selected;
+}
+function pathExists(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isSymbolicLink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+function comparableRealPath(path) {
+  const real = realpathSync(path);
+  return process.platform === "win32" ? real.toLowerCase() : real;
+}
+function pathsResolveToSameDirectory(sourceDir, destinationDir) {
+  try {
+    return comparableRealPath(destinationDir) === comparableRealPath(sourceDir);
+  } catch {
+    return false;
+  }
+}
+function linkPointsTo(sourceDir, destinationDir) {
+  return isSymbolicLink(destinationDir) && pathsResolveToSameDirectory(sourceDir, destinationDir);
+}
+function isZamSkillCopy(destinationDir) {
+  try {
+    if (!lstatSync(destinationDir).isDirectory()) return false;
+    const skillFile = join15(destinationDir, "SKILL.md");
+    if (!existsSync15(skillFile)) return false;
+    return /^name:\s*zam\s*$/m.test(readFileSync10(skillFile, "utf8"));
+  } catch {
+    return false;
+  }
+}
+function classifySkillDestination(sourceDir, destinationDir) {
+  if (!existsSync15(sourceDir)) return "source-missing";
+  if (!isSymbolicLink(destinationDir) && pathsResolveToSameDirectory(sourceDir, destinationDir)) {
+    return "source-directory";
+  }
+  if (linkPointsTo(sourceDir, destinationDir)) return "linked";
+  if (!pathExists(destinationDir)) return "missing";
+  if (isSymbolicLink(destinationDir)) return "broken";
+  if (isZamSkillCopy(destinationDir)) return "stale-copy";
+  return "unmanaged";
+}
+function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {}) {
+  const results = [];
+  const log = (message) => {
+    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));
+    const label = dirname5(to);
+    const state = classifySkillDestination(sourceDir, destinationDir);
+    if (state === "source-missing") {
+      if (!opts.quiet) {
+        console.warn(`  warn  source not found, skipping: ${sourceDir}`);
       }
+      results.push({
+        source: sourceDir,
+        destination: destinationDir,
+        action: "skipped",
+        reason: "source-not-found"
+      });
+      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 (state === "source-directory") {
+      log(`  skip  ${label} (package source)`);
+      results.push({
+        source: sourceDir,
+        destination: destinationDir,
+        action: "skipped",
+        reason: "source-directory"
+      });
+      continue;
     }
-    if (orphans.length > 0) {
-      console.log(
-        `
-\x1B[33mOrphan keys (stored but unreferenced):\x1B[0m ${orphans.join(", ")}`
-      );
+    if (state === "linked") {
+      log(`  skip  ${label} (already linked)`);
+      results.push({
+        source: sourceDir,
+        destination: destinationDir,
+        action: "skipped",
+        reason: "already-linked"
+      });
+      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 ")}.`
+    const destinationExists = state !== "missing";
+    const replaceExisting = destinationExists && (Boolean(opts.force) || state === "broken" || state === "stale-copy");
+    if (destinationExists && !replaceExisting) {
+      if (!opts.quiet) {
+        console.warn(
+          `  warn  ${label} 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"}  ${label}`);
+    } else {
+      if (destinationExists) {
+        rmSync2(destinationDir, { recursive: true, force: true });
+      }
+      mkdirSync8(dirname5(destinationDir), { recursive: true });
+      symlinkSync(
+        sourceDir,
+        destinationDir,
+        process.platform === "win32" ? "junction" : "dir"
       );
-      process.exit(1);
+      log(`  ${action === "linked" ? "link" : "relink"}  ${label}`);
     }
-    apiFlavor = opts.flavor;
+    results.push({ source: sourceDir, destination: destinationDir, action });
   }
-  const apiKeyRef = opts.keyRef ?? (opts.key ? name : void 0);
-  const machine = Boolean(opts.machine);
-  await withProviderScope(machine, async (db) => {
-    const providers = await readScopedProviders(db, machine);
-    const next = upsertProviderRecord(providers, name, {
-      label: opts.label,
-      url: opts.url,
-      model: opts.model,
-      apiFlavor,
-      apiKeyRef,
-      local: opts.local ? true : void 0,
-      runner: opts.runner
-    });
-    await writeScopedProviders(db, machine, next);
-    if (opts.key && apiKeyRef) setProviderApiKey(apiKeyRef, opts.key);
-    const rec = next[name];
-    console.log(
-      `Provider "${name}" saved (${machine ? "machine-local" : "shared"}):`
-    );
-    console.log(`  url:     ${rec.url ?? "(inherits llm.url)"}`);
-    console.log(`  model:   ${rec.model ?? "(inherits llm.model)"}`);
-    if (rec.label) console.log(`  label:   ${rec.label}`);
-    if (rec.local !== void 0) {
-      console.log(`  local:   ${rec.local ? "yes" : "no"}`);
-    }
-    if (rec.runner) console.log(`  runner:  ${rec.runner}`);
-    console.log(
-      `  flavor:  ${rec.apiFlavor ?? `${rec.url ? inferApiFlavor(rec.url) : "chat-completions"} (inferred)`}`
-    );
-    console.log(`  key-ref: ${rec.apiKeyRef ?? "(none \u2014 uses default key)"}`);
-    if (opts.key) {
-      console.log(`  key:     stored (${maskSecret(opts.key)})`);
-    } else if (rec.apiKeyRef && getProviderApiKey(rec.apiKeyRef) === null) {
-      console.log(
-        `
-  \u26A0 No key stored for "${rec.apiKeyRef}". Run: zam provider set-key ${rec.apiKeyRef}`
-      );
-    }
-    if (!rec.url) {
-      console.log(
-        "\n  \u26A0 No --url set; this provider inherits the base llm.url."
-      );
-    }
-    console.log(
-      `
-Bind it to a role: zam provider use recall --primary ${name}`
-    );
-  });
-});
-providerCommand.command("remove <name>").description("Remove a provider record from llm.providers").option("--machine", "Remove from ~/.zam/config.json instead of the DB").action(async (name, opts) => {
-  const machine = Boolean(opts.machine);
-  await withProviderScope(machine, async (db) => {
-    const providers = await readScopedProviders(db, machine);
-    const { providers: next, removed } = removeProviderRecord(
-      providers,
-      name
-    );
-    if (!removed) {
-      console.log(`No such provider: ${name}`);
-      return;
-    }
-    await writeScopedProviders(db, machine, next);
-    console.log(
-      `Removed provider "${name}" (${machine ? "machine-local" : "shared"}).`
-    );
-    const referencing = rolesReferencing(
-      await readScopedRoles(db, machine),
-      name
-    );
-    if (referencing.length > 0) {
-      console.log(
-        `  \u26A0 Still referenced by role(s): ${referencing.join(", ")} \u2014 rebind with: zam provider use <role> --primary <name>`
-      );
-    }
-  });
-});
-providerCommand.command("use <role>").description(`Bind providers to a role (${VALID_ROLES.join(" | ")})`).option("--primary <name>", "Primary provider").option("--fallback <name>", "Fallback provider (optional)").option("--machine", "Bind the role in ~/.zam/config.json").action(async (role, opts) => {
-  if (!VALID_ROLES.includes(role)) {
-    console.error(`Invalid role: ${role}. Use ${VALID_ROLES.join(", ")}.`);
-    process.exit(1);
-  }
-  if (!opts.primary) {
-    console.error("--primary is required.");
-    process.exit(1);
-  }
-  const machine = Boolean(opts.machine);
-  await withProviderScope(machine, async (db) => {
-    const providers = await readScopedProviders(db, machine);
-    await writeScopedRoles(
-      db,
-      machine,
-      bindRoleProviders(
-        await readScopedRoles(db, machine),
-        role,
-        opts.primary,
-        opts.fallback
-      )
-    );
-    const fb = opts.fallback ? `, fallback: ${opts.fallback}` : "";
-    console.log(
-      `Role "${role}" \u2192 primary: ${opts.primary}${fb} (${machine ? "machine-local" : "shared"})`
-    );
-    for (const [label, ref] of [
-      ["primary", opts.primary],
-      ["fallback", opts.fallback]
-    ]) {
-      if (ref && !(ref in providers)) {
-        console.log(
-          `  \u26A0 ${label} "${ref}" is not a defined provider yet. Add it: zam provider add ${ref} --url <url> --model <model>`
-        );
-      }
-    }
-  });
-});
-providerCommand.command("set-key <ref>").description(
-  "Store an API key for a provider reference (in credentials.json)"
-).option(
-  "--key <value>",
-  "The API key (omit to enter it interactively, hidden)"
-).action(async (ref, opts) => {
-  try {
-    const key = opts.key ?? await password({ message: `API key for "${ref}":` });
-    if (!key || key.trim().length === 0) {
-      console.error("No key provided.");
-      process.exit(1);
-    }
-    setProviderApiKey(ref, key.trim());
-    console.log(`Stored API key for "${ref}" (${maskSecret(key.trim())}).`);
-  } catch (err) {
-    if (err.name === "ExitPromptError") {
-      console.log("\nCancelled.");
-      process.exit(0);
-    }
-    console.error("Error:", err.message);
-    process.exit(1);
-  }
-});
-providerCommand.command("clear-key <ref>").description("Remove a stored API key").action((ref) => {
-  clearProviderApiKey(ref);
-  console.log(`Cleared API key for "${ref}".`);
-});
-
-// src/cli/commands/resolve-user.ts
-async function ensureDefaultUser(db, preferredUserId) {
-  const stored = await getSetting(db, "user.id");
-  if (stored) return stored;
-  const userId = preferredUserId?.trim() || process.env.ZAM_USER?.trim() || process.env.USERNAME?.trim() || process.env.USER?.trim() || "default";
-  await setSetting(db, "user.id", userId);
-  return userId;
-}
-async function resolveUser(opts, db, resolveOpts) {
-  if (opts.user) return opts.user;
-  const stored = await getSetting(db, "user.id");
-  if (stored) return stored;
-  const message = "No user specified. Set a default with: zam whoami --set <id>";
-  if (resolveOpts?.json) {
-    console.log(JSON.stringify({ error: message }, null, 2));
-  } else {
-    console.error(message);
-  }
-  process.exit(1);
-}
-
-// src/cli/commands/setup.ts
-import {
-  existsSync as existsSync15,
-  lstatSync,
-  mkdirSync as mkdirSync8,
-  readdirSync as readdirSync2,
-  readFileSync as readFileSync10,
-  realpathSync,
-  rmSync as rmSync2,
-  symlinkSync,
-  writeFileSync as writeFileSync7
-} from "fs";
-import { basename as basename4, dirname as dirname5, join as join15, resolve as resolve3 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { Command as Command3 } from "commander";
-var packageRoot = [
-  fileURLToPath2(new URL("../..", import.meta.url)),
-  fileURLToPath2(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync15(join15(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
-var ALL_SETUP_AGENTS = ["claude", "copilot", "codex", "agent"];
-var SKILL_PAIRS = [
-  {
-    from: join15(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
-    to: join15(".claude", "skills", "zam", "SKILL.md"),
-    agents: ["claude", "copilot"]
-  },
-  {
-    from: join15(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
-    to: join15(".agent", "skills", "zam", "SKILL.md"),
-    agents: ["agent"]
-  },
-  {
-    from: join15(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
-    to: join15(".agents", "skills", "zam", "SKILL.md"),
-    agents: ["codex"]
-  }
-];
-function parseSetupAgents(value) {
-  if (!value || value.trim().toLowerCase() === "all") {
-    return new Set(ALL_SETUP_AGENTS);
-  }
-  const aliases = {
-    claude: ["claude"],
-    copilot: ["copilot"],
-    codex: ["codex"],
-    agent: ["agent"],
-    opencode: ["agent"]
-  };
-  const selected = /* @__PURE__ */ new Set();
-  for (const raw of value.split(",")) {
-    const key = raw.trim().toLowerCase();
-    const mapped = aliases[key];
-    if (!mapped) {
-      throw new Error(
-        `Unknown agent "${raw}". Use: all, claude, copilot, codex, agent.`
-      );
-    }
-    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
-
-ZAM is available in this repository. Use the \`zam\` skill in Claude Code to turn real work into an observed learning session with active recall and FSRS scheduling.
-
-- Skill files live under \`.claude/skills/zam/\`.
-- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
-- The skill directory is linked to this ZAM installation and updates with it.`,
-      Boolean(opts.dryRun)
-    );
-    logInstructionAction(action, "CLAUDE.md", Boolean(opts.dryRun));
-    return;
-  }
-  const name = basename4(cwd);
-  const content = `# ZAM Personal Kernel \xE2\u20AC\u201D ${name}
-
-This is a ZAM personal instance. ZAM builds lasting skills through spaced
-repetition during real work \xE2\u20AC\u201D not separate study sessions.
-
-## First time here?
-Run \`/setup\` in Claude Code or Gemini CLI to complete first-time setup.
-
-## Regular use
-Run \`/zam\` to start a learning session on whatever you are working on.
-
-## What lives here
-- \`beliefs/\` \xE2\u20AC\u201D your worldview, approved by git commit
-- \`goals/\` \xE2\u20AC\u201D your objectives, decomposed into tasks and learning tokens
-
-## Fast-changing data
-Learning tokens, cards, and review history live in local SQLite by default.
-Use \`zam connector setup turso\` to store cloud credentials in
-\`~/.zam/credentials.json\` and use a Turso database across machines.
-`;
-  if (opts.dryRun) {
-    console.log(`  would write CLAUDE.md`);
-  } else {
-    writeFileSync7(dest, content, "utf8");
-    console.log(`  write CLAUDE.md`);
-  }
-}
-function writeAgentsMd(skipAgentsMd, cwd = process.cwd(), opts = {}) {
-  if (skipAgentsMd) return;
-  const dest = join15(cwd, "AGENTS.md");
-  if (existsSync15(dest)) {
-    if (!opts.updateExisting) {
-      console.log(`  skip  AGENTS.md (already present)`);
-      return;
-    }
-    const action = upsertMarkedBlock(
-      dest,
-      `## ZAM learning sessions
-
-ZAM is available in this repository. Select the \`zam\` skill through \`/skills\` or invoke \`$zam\` where supported to turn real work into an observed learning session with active recall and FSRS scheduling.
-
-- Skill files live under \`.agents/skills/zam/\`.
-- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
-- The skill directory is linked to this ZAM installation and updates with it.`,
-      Boolean(opts.dryRun)
-    );
-    logInstructionAction(action, "AGENTS.md", Boolean(opts.dryRun));
-    return;
-  }
-  const name = basename4(cwd);
-  const content = `# ZAM Personal Kernel - ${name}
-
-This is a ZAM personal instance. ZAM builds lasting skills through spaced
-repetition during real work, not separate study sessions.
-
-## First time here?
-Run \`zam setup\` from the shell. When this repository includes
-\`.agents/skills/setup/\`, you can instead select \`setup\` through \`/skills\`
-or invoke \`$setup\`.
-
-## Regular use
-Select the \`zam\` skill through \`/skills\` or invoke \`$zam\` to start a
-learning session on whatever you are working on.
-
-## What lives here
-- \`beliefs/\` - your worldview, approved by git commit
-- \`goals/\` - your objectives, decomposed into tasks and learning tokens
-
-## Fast-changing data
-Learning tokens, cards, and review history live in local SQLite by default.
-Use \`zam connector setup turso\` to store cloud credentials in
-\`~/.zam/credentials.json\` and use a Turso database across machines.
-
-## Codex skills
-Codex discovers repository skills under \`.agents/skills/\`. Run
-\`zam setup --force\` after upgrading \`zam-core\` to refresh them.
-`;
-  if (opts.dryRun) {
-    console.log(`  would write AGENTS.md`);
-  } else {
-    writeFileSync7(dest, content, "utf8");
-    console.log(`  write AGENTS.md`);
-  }
-}
-function writeCopilotInstructions(cwd = process.cwd(), opts = {}) {
-  const dest = join15(cwd, ".github", "copilot-instructions.md");
-  const action = upsertMarkedBlock(
-    dest,
-    `## ZAM learning sessions
-
-ZAM is available in this repository through \`.claude/skills/zam/\`. Use the \`zam\` project skill from Copilot-compatible skill selection surfaces to turn real work into an observed learning session with active recall and FSRS scheduling.
-
-- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
-- The skill directory is linked to this ZAM installation and updates with it.`,
-    Boolean(opts.dryRun)
-  );
-  logInstructionAction(
-    action,
-    ".github/copilot-instructions.md",
-    Boolean(opts.dryRun)
-  );
-}
-var setupCommand = new Command3("setup").description(
-  "Link ZAM skill directories into this workspace and initialize the database"
-).option("--force", "replace an unmanaged existing ZAM skill directory", false).option("--skip-init", "skip database initialization", false).option("--skip-claude-md", "skip CLAUDE.md generation", false).option("--skip-agents-md", "skip AGENTS.md generation", false).option("--target <path>", "repository/workspace directory to set up").option(
-  "--agents <list>",
-  "comma-separated agents to wire: all, claude, copilot, codex, agent"
-).option(
-  "--dry-run",
-  "show what would be written without changing files",
-  false
-).action(
-  async (opts) => {
-    let agents;
-    try {
-      agents = parseSetupAgents(opts.agents);
-    } catch (err) {
-      console.error(`Error: ${err.message}`);
-      process.exit(1);
-    }
-    const target = resolve3(opts.target ?? process.cwd());
-    const updateExistingInstructions = Boolean(opts.target) || opts.force;
-    console.log(
-      `Setting up ZAM in ${target}${opts.dryRun ? " (dry run)" : ""}
-`
-    );
-    wireSkills(target, agents, {
-      force: opts.force,
-      dryRun: opts.dryRun
-    });
-    await initDatabase(opts.skipInit || opts.dryRun);
-    if (agents.has("claude")) {
-      writeClaudeMd(opts.skipClaudeMd, target, {
-        dryRun: opts.dryRun,
-        updateExisting: updateExistingInstructions
-      });
-    }
-    if (agents.has("codex") || agents.has("agent")) {
-      writeAgentsMd(opts.skipAgentsMd, target, {
-        dryRun: opts.dryRun,
-        updateExisting: updateExistingInstructions
-      });
-    }
-    if (agents.has("copilot") && (opts.target || opts.agents)) {
-      writeCopilotInstructions(target, {
-        dryRun: opts.dryRun,
-        updateExisting: updateExistingInstructions
-      });
-    }
-    console.log(
-      "\nDone. Run `zam whoami --set <your-id>` to set your identity. Start the `zam` skill with `/zam` in Claude/Copilot/Gemini-compatible clients or `$zam` (or `/skills`) in Codex."
-    );
-  }
-);
-
-// src/cli/commands/workspace.ts
-import { execFileSync as execFileSync3 } from "child_process";
-import { existsSync as existsSync16, mkdirSync as mkdirSync9, writeFileSync as writeFileSync8 } from "fs";
-import { homedir as homedir9 } from "os";
-import { join as join16, resolve as resolve4 } from "path";
-import { confirm, input } from "@inquirer/prompts";
-import { Command as Command4 } from "commander";
-function runGit(cwd, args) {
-  try {
-    return execFileSync3("git", args, {
-      cwd,
-      stdio: "pipe",
-      encoding: "utf8"
-    }).trim();
-  } catch (err) {
-    throw new Error(`Git command failed: ${err.message}`);
-  }
-}
-function ghRepoCreateArgs(repoName, repoVisibility) {
-  return ["repo", "create", repoName, repoVisibility, "--source=.", "--push"];
-}
-function gitRemoteArgs(githubUrl, hasOrigin) {
-  return hasOrigin ? ["remote", "set-url", "origin", githubUrl] : ["remote", "add", "origin", githubUrl];
-}
-var workspaceCommand = new Command4("workspace").description(
-  "Manage your ZAM learning workspace"
-);
-var WORKSPACE_KINDS = [
-  "personal",
-  "team",
-  "family",
-  "community",
-  "organization",
-  "custom"
-];
-var WORKSPACE_SOURCE_CONTROLS = [
-  "github",
-  "azure-devops",
-  "git",
-  "none"
-];
-function parseWorkspaceKind(value) {
-  const kind = (value ?? "custom").toLowerCase();
-  if (WORKSPACE_KINDS.includes(kind)) {
-    return kind;
-  }
-  throw new Error(
-    `Invalid workspace kind: ${value}. Use ${WORKSPACE_KINDS.join(", ")}.`
-  );
-}
-function parseWorkspaceSourceControl(value) {
-  if (!value) return void 0;
-  const source = value.toLowerCase();
-  if (WORKSPACE_SOURCE_CONTROLS.includes(source)) {
-    return source;
-  }
-  throw new Error(
-    `Invalid source control: ${value}. Use ${WORKSPACE_SOURCE_CONTROLS.join(", ")}.`
-  );
-}
-function parseScopes(value) {
-  if (!value) return void 0;
-  const scopes = value.split(",").map((item) => item.trim()).filter(Boolean);
-  return scopes.length > 0 ? scopes : void 0;
+  return results;
 }
-function requireWorkspace(id) {
-  const workspace = getConfiguredWorkspaces().find((item) => item.id === id);
-  if (!workspace) {
-    throw new Error(
-      `Workspace "${id}" is not configured. Add it with: zam workspace add ${id} --path <dir>`
-    );
+function inspectSkillLinks(cwd = process.cwd(), agents = parseSetupAgents()) {
+  const results = [];
+  for (const { from, to, agents: pairAgents } of SKILL_PAIRS) {
+    if (!pairAgents.some((agent) => agents.has(agent))) continue;
+    const sourceDir = dirname5(from);
+    const destinationDir = dirname5(join15(cwd, to));
+    results.push({
+      agents: pairAgents,
+      source: sourceDir,
+      destination: destinationDir,
+      state: classifySkillDestination(sourceDir, destinationDir)
+    });
   }
-  return workspace;
+  return results;
 }
-workspaceCommand.command("list").description("List configured ZAM workspaces").option("--json", "Output as JSON").action((opts) => {
-  const workspaces = getConfiguredWorkspaces();
-  if (opts.json) {
-    console.log(JSON.stringify({ workspaces }, null, 2));
-    return;
+function summarizeSkillLinkHealth(inspections) {
+  if (inspections.some((item) => item.state === "unmanaged")) {
+    return "unmanaged";
   }
-  console.log("Configured ZAM workspaces:\n");
-  if (workspaces.length === 0) {
-    console.log(
-      "  (none) \u2014 add one: zam workspace add personal --path <dir>"
-    );
-    return;
-  }
-  for (const workspace of workspaces) {
-    const label = workspace.label ? ` (${workspace.label})` : "";
-    console.log(`  ${workspace.id}${label}`);
-    console.log(`      kind: ${workspace.kind}`);
-    console.log(`      path: ${workspace.path}`);
-    if (workspace.sourceControl) {
-      console.log(`      source: ${workspace.sourceControl}`);
-    }
-    if (workspace.knowledgeScopes?.length) {
-      console.log(`      scopes: ${workspace.knowledgeScopes.join(", ")}`);
-    }
+  const repairable = ["missing", "broken", "stale-copy"];
+  if (inspections.some((item) => repairable.includes(item.state))) {
+    return "needs-repair";
   }
-});
-workspaceCommand.command("add <id>").description("Register an existing directory as a ZAM workspace").requiredOption("--path <dir>", "Existing workspace/repository directory").option(
-  "--kind <kind>",
-  `Workspace kind (${WORKSPACE_KINDS.join(" | ")})`,
-  "custom"
-).option("--label <label>", "Human-readable label").option(
-  "--source-control <provider>",
-  `Source-control provider (${WORKSPACE_SOURCE_CONTROLS.join(" | ")})`
-).option("--scopes <list>", "Comma-separated knowledge scopes").option("--default-agent <id>", "Default agent harness for this workspace").action((id, opts) => {
-  try {
-    const path = resolve4(String(opts.path));
-    if (!existsSync16(path)) {
-      console.error(`Workspace path does not exist: ${path}`);
-      process.exit(1);
+  return "healthy";
+}
+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");
     }
-    const workspace = {
-      id,
-      kind: parseWorkspaceKind(opts.kind),
-      path,
-      ...opts.label ? { label: opts.label } : {},
-      ...opts.sourceControl ? { sourceControl: parseWorkspaceSourceControl(opts.sourceControl) } : {},
-      ...parseScopes(opts.scopes) ? { knowledgeScopes: parseScopes(opts.scopes) } : {},
-      ...opts.defaultAgent ? { defaultAgent: opts.defaultAgent } : {}
-    };
-    wireSkills(path, parseSetupAgents());
-    upsertConfiguredWorkspace(workspace);
-    console.log(`Registered and linked workspace "${id}" at ${path}.`);
-  } catch (err) {
-    console.error(`Error: ${err.message}`);
-    process.exit(1);
+    return "write";
   }
-});
-workspaceCommand.command("remove <id>").description("Unregister a ZAM workspace without deleting its files").action((id) => {
-  const existing = getConfiguredWorkspaces().find((item) => item.id === id);
-  if (!existing) {
-    console.error(`Workspace "${id}" is not configured.`);
-    process.exit(1);
+  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}`);
   }
-  removeConfiguredWorkspace(id);
-  console.log(
-    `Unregistered workspace "${id}". Files in ${existing.path} were not changed.`
-  );
-});
-workspaceCommand.command("setup <id>").description("Install ZAM skills into a configured workspace").option(
-  "--agents <list>",
-  "comma-separated agents to wire: all, claude, copilot, codex, agent"
-).option(
-  "--force",
-  "overwrite existing skill files and refresh ZAM blocks",
-  false
-).option(
-  "--dry-run",
-  "show what would be written without changing files",
-  false
-).action((id, opts) => {
-  try {
-    const workspace = requireWorkspace(id);
-    const agents = parseSetupAgents(opts.agents);
-    console.log(
-      `Setting up workspace "${workspace.id}" in ${workspace.path}${opts.dryRun ? " (dry run)" : ""}
-`
-    );
-    wireSkills(workspace.path, agents, {
-      force: Boolean(opts.force),
-      dryRun: Boolean(opts.dryRun)
-    });
-    if (agents.has("claude")) {
-      writeClaudeMd(false, workspace.path, {
-        dryRun: Boolean(opts.dryRun),
-        updateExisting: true
-      });
-    }
-    if (agents.has("codex") || agents.has("agent")) {
-      writeAgentsMd(false, workspace.path, {
-        dryRun: Boolean(opts.dryRun),
-        updateExisting: true
-      });
-    }
-    if (agents.has("copilot")) {
-      writeCopilotInstructions(workspace.path, {
-        dryRun: Boolean(opts.dryRun),
-        updateExisting: true
-      });
+}
+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;
     }
-  } catch (err) {
-    console.error(`Error: ${err.message}`);
-    process.exit(1);
-  }
-});
-workspaceCommand.command("publish").description("Publish your local workspace sandbox to GitHub").action(async () => {
-  let db;
-  let workspaceDir = "";
-  try {
-    db = await openDatabase();
-    workspaceDir = await getSetting(db, "personal.workspace_dir") || "";
-    await db.close();
-  } catch {
-    await db?.close();
-  }
-  if (!workspaceDir) {
-    console.error(
-      "\x1B[31m\u2717 No active workspace configured. Please run `zam init` first.\x1B[0m"
-    );
-    process.exit(1);
-  }
-  if (!existsSync16(workspaceDir)) {
-    console.error(
-      `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
+    const action = upsertMarkedBlock(
+      dest,
+      `## ZAM learning sessions
+
+ZAM is available in this repository. Use the \`zam\` skill in Claude Code to turn real work into an observed learning session with active recall and FSRS scheduling.
+
+- Skill files live under \`.claude/skills/zam/\`.
+- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
+- The skill directory is linked to this ZAM installation and updates with it.`,
+      Boolean(opts.dryRun)
     );
-    process.exit(1);
+    logInstructionAction(action, "CLAUDE.md", Boolean(opts.dryRun));
+    return;
   }
-  console.log(`
-Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
-  if (!hasCommand("git")) {
-    console.error(
-      "\x1B[31m\u2717 Git command was not found on this system. Please install Git first.\x1B[0m"
-    );
-    process.exit(1);
+  const name = basename4(cwd);
+  const content = `# ZAM Personal Kernel \u2014 ${name}
+
+This is a ZAM personal instance. ZAM builds lasting skills through spaced
+repetition during real work \u2014 not separate study sessions.
+
+## First time here?
+Run \`/setup\` in Claude Code or Gemini CLI to complete first-time setup.
+
+## Regular use
+Run \`/zam\` to start a learning session on whatever you are working on.
+
+## What lives here
+- \`beliefs/\` \u2014 your worldview, approved by git commit
+- \`goals/\` \u2014 your objectives, decomposed into tasks and learning tokens
+
+## Fast-changing data
+Learning tokens, cards, and review history live in local SQLite by default.
+Use \`zam connector setup turso\` to store cloud credentials in
+\`~/.zam/credentials.json\` and use a Turso database across machines.
+`;
+  if (opts.dryRun) {
+    console.log(`  would write CLAUDE.md`);
+  } else {
+    writeFileSync7(dest, content, "utf8");
+    console.log(`  write CLAUDE.md`);
   }
-  const gitignorePath = join16(workspaceDir, ".gitignore");
-  if (!existsSync16(gitignorePath)) {
-    writeFileSync8(
-      gitignorePath,
-      "node_modules/\n.agent/\n.agents/\n.claude/\n.gemini/\n.goose/\n*.log\n",
-      "utf8"
+}
+function writeAgentsMd(skipAgentsMd, cwd = process.cwd(), opts = {}) {
+  if (skipAgentsMd) return;
+  const dest = join15(cwd, "AGENTS.md");
+  if (existsSync15(dest)) {
+    if (!opts.updateExisting) {
+      console.log(`  skip  AGENTS.md (already present)`);
+      return;
+    }
+    const action = upsertMarkedBlock(
+      dest,
+      `## ZAM learning sessions
+
+ZAM is available in this repository. Select the \`zam\` skill through \`/skills\` or invoke \`$zam\` where supported to turn real work into an observed learning session with active recall and FSRS scheduling.
+
+- Skill files live under \`.agents/skills/zam/\`.
+- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
+- The skill directory is linked to this ZAM installation and updates with it.`,
+      Boolean(opts.dryRun)
     );
+    logInstructionAction(action, "AGENTS.md", Boolean(opts.dryRun));
+    return;
   }
-  const hasGitRepo = existsSync16(join16(workspaceDir, ".git"));
-  if (!hasGitRepo) {
-    console.log("Initializing local Git repository...");
-    runGit(workspaceDir, ["init", "-b", "main"]);
-    runGit(workspaceDir, ["add", "."]);
-    runGit(workspaceDir, [
-      "commit",
-      "-m",
-      "chore: initial workspace sandbox bootstrap"
-    ]);
-    console.log("\x1B[32m\u2713 Local Git repository initialized.\x1B[0m");
+  const name = basename4(cwd);
+  const content = `# ZAM Personal Kernel - ${name}
+
+This is a ZAM personal instance. ZAM builds lasting skills through spaced
+repetition during real work, not separate study sessions.
+
+## First time here?
+Run \`zam setup\` from the shell. When this repository includes
+\`.agents/skills/setup/\`, you can instead select \`setup\` through \`/skills\`
+or invoke \`$setup\`.
+
+## Regular use
+Select the \`zam\` skill through \`/skills\` or invoke \`$zam\` to start a
+learning session on whatever you are working on.
+
+## What lives here
+- \`beliefs/\` - your worldview, approved by git commit
+- \`goals/\` - your objectives, decomposed into tasks and learning tokens
+
+## Fast-changing data
+Learning tokens, cards, and review history live in local SQLite by default.
+Use \`zam connector setup turso\` to store cloud credentials in
+\`~/.zam/credentials.json\` and use a Turso database across machines.
+
+## Codex skills
+Codex discovers repository skills under \`.agents/skills/\`. Run
+\`zam setup --force\` after upgrading \`zam-core\` to refresh them.
+`;
+  if (opts.dryRun) {
+    console.log(`  would write AGENTS.md`);
   } else {
-    console.log("Git repository is already initialized.");
-  }
-  const repoName = await input({
-    message: "Choose a name for your GitHub repository:",
-    default: "zam-personal"
-  });
-  const isPrivate = await confirm({
-    message: "Should the repository be private?",
-    default: true
-  });
-  const repoVisibility = isPrivate ? "--private" : "--public";
-  if (hasCommand("gh")) {
-    console.log("GitHub CLI detected! Automating repository creation...");
-    const proceedGh = await confirm({
-      message: "Would you like ZAM to create the repository using the GitHub CLI?",
-      default: true
-    });
-    if (proceedGh) {
-      try {
-        console.log(`Creating GitHub repository ${repoName}...`);
-        execFileSync3("gh", ghRepoCreateArgs(repoName, repoVisibility), {
-          cwd: workspaceDir,
-          stdio: "inherit"
-        });
-        console.log(
-          "\n\x1B[32m\u2713 Successfully published workspace to GitHub!\x1B[0m"
-        );
-        process.exit(0);
-      } catch (err) {
-        console.warn(
-          `\x1B[33m\u26A0 GitHub CLI creation failed: ${err.message}\x1B[0m`
-        );
-      }
-    }
+    writeFileSync7(dest, content, "utf8");
+    console.log(`  write AGENTS.md`);
   }
-  console.log(
-    "\n\x1B[1mPlease create the repository manually on GitHub:\x1B[0m"
+}
+function writeCopilotInstructions(cwd = process.cwd(), opts = {}) {
+  const dest = join15(cwd, ".github", "copilot-instructions.md");
+  const action = upsertMarkedBlock(
+    dest,
+    `## ZAM learning sessions
+
+ZAM is available in this repository through \`.claude/skills/zam/\`. Use the \`zam\` project skill from Copilot-compatible skill selection surfaces to turn real work into an observed learning session with active recall and FSRS scheduling.
+
+- Fast-changing review data lives in \`~/.zam/\`, not in this repository.
+- The skill directory is linked to this ZAM installation and updates with it.`,
+    Boolean(opts.dryRun)
   );
-  console.log("  1. Go to https://github.com/new");
-  console.log(`  2. Name it exactly: \x1B[36m${repoName}\x1B[0m`);
-  console.log(
-    `  3. Choose \x1B[36m${isPrivate ? "Private" : "Public"}\x1B[0m`
+  logInstructionAction(
+    action,
+    ".github/copilot-instructions.md",
+    Boolean(opts.dryRun)
   );
-  console.log(
-    "  4. Do NOT initialize it with README, .gitignore, or license"
+}
+
+// src/cli/users/identity.ts
+async function ensureDefaultUser(db, preferredUserId) {
+  const stored = await getSetting(db, "user.id");
+  if (stored) return stored;
+  const userId = preferredUserId?.trim() || process.env.ZAM_USER?.trim() || process.env.USERNAME?.trim() || process.env.USER?.trim() || "default";
+  await setSetting(db, "user.id", userId);
+  return userId;
+}
+async function resolveUser(opts, db, resolveOpts) {
+  if (opts.user) return opts.user;
+  const stored = await getSetting(db, "user.id");
+  if (stored) return stored;
+  const message = "No user specified. Set a default with: zam whoami --set <id>";
+  if (resolveOpts?.json) {
+    console.log(JSON.stringify({ error: message }, null, 2));
+  } else {
+    console.error(message);
+  }
+  process.exit(1);
+}
+
+// src/cli/workspaces/active.ts
+import { existsSync as existsSync16, mkdirSync as mkdirSync9 } from "fs";
+import { homedir as homedir9 } from "os";
+import { basename as basename5, join as join16, resolve as resolve3 } from "path";
+var LEGACY_WORKSPACE_DIR_KEY = "personal.workspace_dir";
+var DEFAULT_WORKSPACE_ID = "personal";
+function defaultWorkspaceDir() {
+  return join16(homedir9(), "Documents", "zam");
+}
+function normalizeWorkspacePath(path) {
+  const resolved = resolve3(path);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function sameWorkspacePath(left, right) {
+  return normalizeWorkspacePath(left) === normalizeWorkspacePath(right);
+}
+function labelFromPath(path) {
+  return basename5(path) || "ZAM";
+}
+function workspaceIdFromPath(dir) {
+  const base = basename5(dir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  const prefix = base || "workspace";
+  const existing = new Set(getConfiguredWorkspaces().map((item) => item.id));
+  if (!existing.has(prefix)) return prefix;
+  let index = 2;
+  while (existing.has(`${prefix}-${index}`)) index++;
+  return `${prefix}-${index}`;
+}
+function findWorkspaceByPath(dir) {
+  return getConfiguredWorkspaces().find(
+    (workspace) => sameWorkspacePath(workspace.path, dir)
   );
-  console.log("  5. Click 'Create repository'\n");
-  const githubUrl = await input({
-    message: "Paste the repository Git URL (e.g. git@github.com:user/repo.git):"
-  });
-  if (githubUrl) {
-    try {
-      console.log("Linking remote repository and pushing...");
-      let hasOrigin = false;
-      try {
-        runGit(workspaceDir, ["remote", "get-url", "origin"]);
-        hasOrigin = true;
-      } catch {
-      }
-      runGit(workspaceDir, gitRemoteArgs(githubUrl, hasOrigin));
-      runGit(workspaceDir, ["push", "-u", "origin", "main"]);
-      console.log(
-        "\x1B[32m\u2713 Successfully linked and pushed to GitHub!\x1B[0m"
-      );
-    } catch (err) {
-      console.error(
-        `\x1B[31m\u2717 Push failed: ${err.message}\x1B[0m`
-      );
-      console.log(
-        "You can push manually later using: git push -u origin main"
-      );
-    }
+}
+async function clearLegacyWorkspaceDir(db) {
+  await deleteSetting(db, LEGACY_WORKSPACE_DIR_KEY);
+}
+async function migrateLegacyWorkspaceDir(db) {
+  const legacyDir = await getSetting(db, LEGACY_WORKSPACE_DIR_KEY);
+  if (!legacyDir) return void 0;
+  const path = resolve3(legacyDir);
+  const existing = findWorkspaceByPath(path);
+  const migrated = existing ?? {
+    id: getConfiguredWorkspaces().some(
+      (workspace) => workspace.id === DEFAULT_WORKSPACE_ID
+    ) ? workspaceIdFromPath(path) : DEFAULT_WORKSPACE_ID,
+    label: labelFromPath(path),
+    kind: "personal",
+    path
+  };
+  if (!existing) {
+    upsertConfiguredWorkspace(migrated);
   }
-});
+  if (!getActiveWorkspace()) {
+    setActiveWorkspaceId(migrated.id);
+  }
+  await clearLegacyWorkspaceDir(db);
+  return migrated;
+}
+async function ensureActiveWorkspace(db) {
+  await migrateLegacyWorkspaceDir(db);
+  const active = getActiveWorkspace();
+  if (active) {
+    mkdirSync9(active.path, { recursive: true });
+    return active;
+  }
+  const configured = getConfiguredWorkspaces()[0];
+  if (configured) {
+    setActiveWorkspaceId(configured.id);
+    mkdirSync9(configured.path, { recursive: true });
+    return configured;
+  }
+  const workspace = {
+    id: DEFAULT_WORKSPACE_ID,
+    label: "Personal",
+    kind: "personal",
+    path: defaultWorkspaceDir()
+  };
+  mkdirSync9(workspace.path, { recursive: true });
+  upsertConfiguredWorkspace(workspace);
+  setActiveWorkspaceId(workspace.id);
+  await clearLegacyWorkspaceDir(db);
+  return workspace;
+}
+async function activateWorkspace(db, workspace) {
+  upsertConfiguredWorkspace(workspace);
+  setActiveWorkspaceId(workspace.id);
+  await clearLegacyWorkspaceDir(db);
+  return workspace;
+}
+async function activateWorkspacePath(db, dir, opts = {}) {
+  await migrateLegacyWorkspaceDir(db);
+  const path = resolve3(dir);
+  const existing = opts.id ? void 0 : findWorkspaceByPath(path);
+  if (existing) {
+    setActiveWorkspaceId(existing.id);
+    await clearLegacyWorkspaceDir(db);
+    return existing;
+  }
+  const workspace = {
+    id: opts.id || workspaceIdFromPath(path),
+    label: opts.label || labelFromPath(path),
+    kind: opts.kind || "personal",
+    path
+  };
+  return activateWorkspace(db, workspace);
+}
+async function removeWorkspaceAndResolveActive(db, id) {
+  removeConfiguredWorkspace(id);
+  await clearLegacyWorkspaceDir(db);
+  const activeWorkspace = await ensureActiveWorkspace(db);
+  return {
+    activeWorkspace,
+    workspaces: getConfiguredWorkspaces()
+  };
+}
+function existingWorkspaceDirOrHome(workspace) {
+  return existsSync16(workspace.path) ? workspace.path : homedir9();
+}
+
+// src/cli/workspaces/backup.ts
+import { mkdirSync as mkdirSync10 } from "fs";
+import { join as join17 } from "path";
 async function backupDatabaseTo(db, targetDir) {
-  const backupDir = join16(targetDir, "zam-backups");
-  mkdirSync9(backupDir, { recursive: true });
+  const backupDir = join17(targetDir, "zam-backups");
+  mkdirSync10(backupDir, { recursive: true });
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const dest = join16(backupDir, `zam-${stamp}.db`);
+  const dest = join17(backupDir, `zam-${stamp}.db`);
   await db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
   return dest;
 }
-workspaceCommand.command("data-dir").description("Print the ZAM data directory (database, credentials, config)").option("--json", "Output as JSON").action((opts) => {
-  const dir = join16(homedir9(), ".zam");
-  console.log(opts.json ? JSON.stringify({ dataDir: dir }) : dir);
-});
-workspaceCommand.command("backup").description("Back up the local ZAM database into your workspace").option(
-  "--dir <path>",
-  "Target directory (default: workspace dir, else ~/Documents/zam)"
-).option("--json", "Output as JSON").action(async (opts) => {
-  const target = getDatabaseTargetInfo();
-  if (target.kind !== "local") {
-    const reason = `The database is ${target.kind} (${target.location}); file backup applies only to a local database \u2014 your Turso remote is already the cloud backup.`;
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, reason }));
-      return;
-    }
-    console.error(`\x1B[33m\u26A0 ${reason}\x1B[0m`);
-    process.exit(1);
-  }
-  let db;
-  try {
-    db = await openDatabase();
-    const workspaceDir = opts.dir || await getSetting(db, "personal.workspace_dir") || join16(homedir9(), "Documents", "zam");
-    const dest = await backupDatabaseTo(db, workspaceDir);
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: true, path: dest }));
-    } else {
-      console.log(`\x1B[32m\u2713 Database backed up to ${dest}\x1B[0m`);
-    }
-  } catch (err) {
-    const reason = err.message;
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, reason }));
-    } else {
-      console.error(`\x1B[31m\u2717 Backup failed: ${reason}\x1B[0m`);
-    }
-    process.exit(1);
-  } finally {
-    await db?.close();
-  }
-});
 
 // src/cli/commands/bridge.ts
 var isServeMode = false;
@@ -7962,7 +7469,7 @@ function parseTokenUpdates(opts) {
   }
   return updates;
 }
-var bridgeCommand = new Command5("bridge").description(
+var bridgeCommand = new Command2("bridge").description(
   "Machine-readable JSON protocol for AI integration"
 );
 bridgeCommand.command("check-due").description("Check due cards for a user (JSON)").option("--user <id>", "User ID (default: whoami)").option("--domain <domain>", "Filter by knowledge domain").action(async (opts) => {
@@ -8005,72 +7512,98 @@ bridgeCommand.command("backup-db").description("Back up the local database into
     return;
   }
   await withDb2(async (db) => {
-    const workspaceDir = opts.dir || await getSetting(db, "personal.workspace_dir") || join17(homedir10(), "Documents", "zam");
+    const workspaceDir = opts.dir || (await ensureActiveWorkspace(db)).path;
     const path = await backupDatabaseTo(db, workspaceDir);
     jsonOut2({ ok: true, path });
   });
 });
 bridgeCommand.command("workspace-info").description("Report the workspace dir, its default, and the data dir (JSON)").action(async () => {
   await withDb2(async (db) => {
-    const workspaceDir = await getSetting(db, "personal.workspace_dir") || null;
+    const activeWorkspace = await ensureActiveWorkspace(db);
     jsonOut2({
-      workspaceDir,
-      defaultWorkspaceDir: join17(homedir10(), "Documents", "zam"),
-      dataDir: join17(homedir10(), ".zam")
+      activeWorkspaceId: activeWorkspace.id,
+      activeWorkspace,
+      workspaceDir: activeWorkspace.path,
+      defaultWorkspaceDir: defaultWorkspaceDir(),
+      dataDir: join18(homedir10(), ".zam")
     });
   });
 });
-function sameWorkspacePath(left, right) {
-  const normalize = (value) => {
-    const path = resolve5(value);
-    return process.platform === "win32" ? path.toLowerCase() : path;
-  };
-  return normalize(left) === normalize(right);
-}
-async function ensureDesktopWorkspace(db) {
-  const configured = getConfiguredWorkspaces();
-  const savedWorkspaceDir = await getSetting(db, "personal.workspace_dir");
-  const workspaceDir = savedWorkspaceDir || configured.find((workspace) => workspace.kind === "personal")?.path || join17(homedir10(), "Documents", "zam");
-  mkdirSync10(workspaceDir, { recursive: true });
-  if (!savedWorkspaceDir) {
-    await setSetting(db, "personal.workspace_dir", workspaceDir);
-  }
-  if (!configured.some(
-    (workspace) => sameWorkspacePath(workspace.path, workspaceDir)
-  )) {
-    const id = configured.some((workspace) => workspace.id === "personal") ? workspaceIdFromPath(workspaceDir) : "personal";
-    upsertConfiguredWorkspace({
-      id,
-      label: basename5(workspaceDir) || "ZAM",
-      kind: "personal",
-      path: workspaceDir
-    });
-  }
-  const skillLinks = getConfiguredWorkspaces().flatMap(
+function provisionConfiguredWorkspaces() {
+  return getConfiguredWorkspaces().flatMap(
     (workspace) => existsSync17(workspace.path) ? wireSkills(workspace.path, parseSetupAgents(), { quiet: true }) : []
   );
-  return { workspaceDir, skillLinks };
+}
+function buildWorkspaceLinkHealth(workspaces) {
+  const agents = parseSetupAgents();
+  const map = {};
+  for (const workspace of workspaces) {
+    if (!existsSync17(workspace.path)) continue;
+    const links = inspectSkillLinks(workspace.path, agents);
+    map[workspace.id] = {
+      health: summarizeSkillLinkHealth(links),
+      states: Object.fromEntries(
+        links.map((link) => [link.agents.join("+"), link.state])
+      )
+    };
+  }
+  return map;
+}
+async function ensureDesktopWorkspace(db) {
+  const activeWorkspace = await ensureActiveWorkspace(db);
+  const skillLinks = provisionConfiguredWorkspaces();
+  return {
+    workspaceDir: activeWorkspace.path,
+    activeWorkspaceId: activeWorkspace.id,
+    skillLinks
+  };
 }
 bridgeCommand.command("workspace-list").description("List configured ZAM workspaces (JSON)").action(async () => {
   await withDb2(async (db) => {
-    const workspaceDir = await getSetting(db, "personal.workspace_dir") || null;
+    const activeWorkspace = await ensureActiveWorkspace(db);
+    const workspaces = getConfiguredWorkspaces();
     jsonOut2({
-      workspaces: getConfiguredWorkspaces(),
-      workspaceDir,
-      defaultWorkspaceDir: join17(homedir10(), "Documents", "zam"),
-      dataDir: join17(homedir10(), ".zam")
+      workspaces,
+      activeWorkspaceId: activeWorkspace.id,
+      activeWorkspace,
+      workspaceDir: activeWorkspace.path,
+      defaultWorkspaceDir: defaultWorkspaceDir(),
+      dataDir: join18(homedir10(), ".zam"),
+      linkHealth: buildWorkspaceLinkHealth(workspaces)
     });
   });
 });
-function workspaceIdFromPath(dir) {
-  const base = basename5(dir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  const prefix = base || "workspace";
-  const existing = new Set(getConfiguredWorkspaces().map((item) => item.id));
-  if (!existing.has(prefix)) return prefix;
-  let index = 2;
-  while (existing.has(`${prefix}-${index}`)) index++;
-  return `${prefix}-${index}`;
-}
+bridgeCommand.command("workspace-repair-links").description(
+  "Relink ZAM skill junctions for a configured workspace, replacing broken links and outdated copies (JSON)"
+).requiredOption("--id <id>", "Workspace id").option(
+  "--agents <list>",
+  "comma-separated agents to wire: all, claude, copilot, codex, agent"
+).action(async (opts) => {
+  const id = String(opts.id ?? "").trim();
+  if (!id) jsonError("A non-empty --id is required");
+  const workspace = getConfiguredWorkspaces().find((item) => item.id === id);
+  if (!workspace) jsonError(`Workspace "${id}" is not configured`);
+  if (!existsSync17(workspace.path)) {
+    jsonError(`Workspace path does not exist: ${workspace.path}`);
+  }
+  const agents = parseSetupAgents(opts.agents);
+  const skillLinks = wireSkills(workspace.path, agents, {
+    force: true,
+    quiet: true
+  });
+  const links = inspectSkillLinks(workspace.path, agents);
+  jsonOut2({
+    ok: true,
+    workspace,
+    skillLinks,
+    linkHealth: {
+      health: summarizeSkillLinkHealth(links),
+      states: Object.fromEntries(
+        links.map((link) => [link.agents.join("+"), link.state])
+      )
+    }
+  });
+});
 function parseBridgeWorkspaceKind(value) {
   const kind = (value || "custom").toLowerCase();
   if (kind === "personal" || kind === "team" || kind === "family" || kind === "community" || kind === "organization" || kind === "custom") {
@@ -8081,25 +7614,25 @@ function parseBridgeWorkspaceKind(value) {
 bridgeCommand.command("workspace-add").description("Register an existing directory as a ZAM workspace (JSON)").requiredOption("--path <dir>", "Existing workspace/repository directory").option("--id <id>", "Workspace id").option("--label <label>", "Human-readable label").option("--kind <kind>", "Workspace kind", "custom").action(async (opts) => {
   const raw = String(opts.path ?? "").trim();
   if (!raw) jsonError("A non-empty --path is required");
-  const path = resolve5(raw);
+  const path = resolve4(raw);
   if (!existsSync17(path)) jsonError(`Workspace path does not exist: ${path}`);
-  const id = String(opts.id || workspaceIdFromPath(path)).trim();
-  if (!id) jsonError("A non-empty --id is required");
-  const workspace = {
-    id,
-    label: opts.label || basename5(path) || id,
-    kind: parseBridgeWorkspaceKind(opts.kind),
-    path
-  };
+  const id = opts.id ? String(opts.id).trim() : void 0;
+  if (opts.id && !id) jsonError("A non-empty --id is required");
+  const kind = parseBridgeWorkspaceKind(opts.kind);
   const skillLinks = wireSkills(path, parseSetupAgents(), { quiet: true });
   await withDb2(async (db) => {
-    await setSetting(db, "personal.workspace_dir", path);
-    upsertConfiguredWorkspace(workspace);
+    const workspace = await activateWorkspacePath(db, path, {
+      ...id ? { id } : {},
+      ...opts.label ? { label: opts.label } : {},
+      kind
+    });
     jsonOut2({
       ok: true,
       workspace,
       workspaces: getConfiguredWorkspaces(),
-      workspaceDir: path,
+      activeWorkspaceId: workspace.id,
+      activeWorkspace: workspace,
+      workspaceDir: workspace.path,
       skillLinks
     });
   });
@@ -8110,27 +7643,15 @@ bridgeCommand.command("workspace-remove").description("Unregister a ZAM workspac
   const workspace = getConfiguredWorkspaces().find((item) => item.id === id);
   if (!workspace) jsonError(`Workspace "${id}" is not configured`);
   await withDb2(async (db) => {
-    const activeWorkspaceDir = await getSetting(db, "personal.workspace_dir") || null;
-    const remaining = removeConfiguredWorkspace(id);
-    let workspaceDir = activeWorkspaceDir;
-    let skillLinks = [];
-    if (activeWorkspaceDir && sameWorkspacePath(activeWorkspaceDir, workspace.path)) {
-      if (remaining.length > 0) {
-        workspaceDir = remaining[0].path;
-        await setSetting(db, "personal.workspace_dir", workspaceDir);
-      } else {
-        workspaceDir = join17(homedir10(), "Documents", "zam");
-        await setSetting(db, "personal.workspace_dir", workspaceDir);
-        const ensured = await ensureDesktopWorkspace(db);
-        workspaceDir = ensured.workspaceDir;
-        skillLinks = ensured.skillLinks;
-      }
-    }
+    const { activeWorkspace, workspaces } = await removeWorkspaceAndResolveActive(db, id);
+    const skillLinks = provisionConfiguredWorkspaces();
     jsonOut2({
       ok: true,
       removed: workspace,
-      workspaces: getConfiguredWorkspaces(),
-      workspaceDir,
+      workspaces,
+      activeWorkspaceId: activeWorkspace.id,
+      activeWorkspace,
+      workspaceDir: activeWorkspace.path,
       skillLinks
     });
   });
@@ -8138,12 +7659,20 @@ bridgeCommand.command("workspace-remove").description("Unregister a ZAM workspac
 bridgeCommand.command("set-workspace-dir").description("Set the personal workspace directory (JSON)").requiredOption("--dir <path>", "Path to the workspace directory").action(async (opts) => {
   const raw = String(opts.dir ?? "").trim();
   if (!raw) jsonError("A non-empty --dir is required");
-  const dir = resolve5(raw);
+  const dir = resolve4(raw);
   if (!existsSync17(dir)) jsonError(`Workspace path does not exist: ${dir}`);
   const skillLinks = wireSkills(dir, parseSetupAgents(), { quiet: true });
   await withDb2(async (db) => {
-    await setSetting(db, "personal.workspace_dir", dir);
-    jsonOut2({ ok: true, workspaceDir: dir, skillLinks });
+    const workspace = await activateWorkspacePath(db, dir);
+    jsonOut2({
+      ok: true,
+      workspace,
+      workspaces: getConfiguredWorkspaces(),
+      activeWorkspaceId: workspace.id,
+      activeWorkspace: workspace,
+      workspaceDir: workspace.path,
+      skillLinks
+    });
   });
 });
 bridgeCommand.command("agent-list").description("List agent harnesses with detection state + the default (JSON)").action(async () => {
@@ -8193,8 +7722,8 @@ bridgeCommand.command("agent-open").description("Launch an agent harness in the
     if (opts.workspace && !configuredWorkspace) {
       jsonError(`Workspace is not configured: ${opts.workspace}`);
     }
-    let workspace = opts.dir || configuredWorkspace?.path || await getSetting(db, "personal.workspace_dir") || join17(homedir10(), "Documents", "zam");
-    if (!existsSync17(workspace)) workspace = homedir10();
+    const activeWorkspace = await ensureActiveWorkspace(db);
+    const workspace = opts.dir ? existsSync17(opts.dir) ? opts.dir : homedir10() : existingWorkspaceDirOrHome(configuredWorkspace ?? activeWorkspace);
     launchHarness(harness, {
       executable,
       workspace,
@@ -8574,10 +8103,10 @@ bridgeCommand.command("discover-skills").description(
   "20"
 ).action(async (opts) => {
   try {
-    const monitorDir = join17(homedir10(), ".zam", "monitor");
+    const monitorDir = join18(homedir10(), ".zam", "monitor");
     let files;
     try {
-      files = readdirSync3(monitorDir).filter((f) => f.endsWith(".jsonl"));
+      files = readdirSync2(monitorDir).filter((f) => f.endsWith(".jsonl"));
     } catch {
       jsonOut2({ proposals: [], message: "No monitor logs found." });
       return;
@@ -8587,7 +8116,7 @@ bridgeCommand.command("discover-skills").description(
       return;
     }
     const limit = Number(opts.limit);
-    const sorted = files.map((f) => ({ name: f, path: join17(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
+    const sorted = files.map((f) => ({ name: f, path: join18(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
     const sessionCommands = /* @__PURE__ */ new Map();
     for (const file of sorted) {
       const sessionId = file.name.replace(".jsonl", "");
@@ -8699,7 +8228,7 @@ bridgeCommand.command("observe-ui-snapshot").description(
 });
 function resolveWindowsPowerShell() {
   try {
-    execFileSync4("where.exe", ["pwsh.exe"], { stdio: "ignore" });
+    execFileSync3("where.exe", ["pwsh.exe"], { stdio: "ignore" });
     return "pwsh";
   } catch {
     return "powershell";
@@ -8714,7 +8243,7 @@ function captureScreenshot(outputPath, hwnd, processName) {
     throw new Error(`Invalid process name format: ${processName}`);
   }
   if (platform === "win32") {
-    const stdout = execFileSync4(
+    const stdout = execFileSync3(
       resolveWindowsPowerShell(),
       [
         "-NoProfile",
@@ -9027,13 +8556,13 @@ Write-CaptureResult "fullscreen" $hwndVal $matchedBy
   } else if (platform === "darwin") {
     if (hwnd) {
       const parsedHwnd = hwnd.startsWith("0x") ? parseInt(hwnd, 16) : parseInt(hwnd, 10);
-      execFileSync4("screencapture", ["-l", String(parsedHwnd), outputPath], {
+      execFileSync3("screencapture", ["-l", String(parsedHwnd), outputPath], {
         stdio: "pipe"
       });
       return { method: "screencapture-window", target: null };
     } else if (processName) {
       try {
-        const windowId = execFileSync4(
+        const windowId = execFileSync3(
           "osascript",
           [
             "-e",
@@ -9042,17 +8571,17 @@ Write-CaptureResult "fullscreen" $hwndVal $matchedBy
           { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }
         ).trim();
         if (windowId && /^\d+$/.test(windowId)) {
-          execFileSync4("screencapture", ["-l", windowId, outputPath], {
+          execFileSync3("screencapture", ["-l", windowId, outputPath], {
             stdio: "pipe"
           });
           return { method: "screencapture-window", target: null };
         }
       } catch {
       }
-      execFileSync4("screencapture", ["-x", outputPath], { stdio: "pipe" });
+      execFileSync3("screencapture", ["-x", outputPath], { stdio: "pipe" });
       return { method: "screencapture-full", target: null };
     } else {
-      execFileSync4("screencapture", ["-x", outputPath], { stdio: "pipe" });
+      execFileSync3("screencapture", ["-x", outputPath], { stdio: "pipe" });
       return { method: "screencapture-full", target: null };
     }
   } else {
@@ -9089,7 +8618,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
         return;
       }
     }
-    const outputPath = opts.image ?? opts.output ?? join17(tmpdir3(), `zam-capture-${randomBytes2(4).toString("hex")}.png`);
+    const outputPath = opts.image ?? opts.output ?? join18(tmpdir3(), `zam-capture-${randomBytes2(4).toString("hex")}.png`);
     const captureResult = isProvided ? { method: "provided", target: null } : captureScreenshot(outputPath, opts.hwnd, opts.processName);
     if (!isProvided) {
       const post = decidePostCapture(policy, {
@@ -9144,11 +8673,11 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     return;
   }
   const sessionId = opts.session;
-  const statePath = join17(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const statePath = join18(tmpdir3(), `zam-recording-${sessionId}.json`);
   const defaultExt = platform === "win32" ? ".mkv" : ".mov";
-  const outputPath = opts.output ?? join17(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
-  const { existsSync: existsSync25, writeFileSync: writeFileSync12, openSync, closeSync } = await import("fs");
-  if (existsSync25(statePath)) {
+  const outputPath = opts.output ?? join18(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
+  const { existsSync: existsSync26, writeFileSync: writeFileSync12, openSync, closeSync } = await import("fs");
+  if (existsSync26(statePath)) {
     jsonOut2({
       sessionId,
       started: false,
@@ -9156,7 +8685,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     });
     return;
   }
-  const logPath = join17(tmpdir3(), `zam-recording-${sessionId}.log`);
+  const logPath = join18(tmpdir3(), `zam-recording-${sessionId}.log`);
   let logFd;
   try {
     logFd = openSync(logPath, "w");
@@ -9238,9 +8767,9 @@ bridgeCommand.command("stop-recording").description(
     return;
   }
   const sessionId = opts.session;
-  const statePath = join17(tmpdir3(), `zam-recording-${sessionId}.json`);
-  const { existsSync: existsSync25, readFileSync: readFileSync16, rmSync: rmSync4 } = await import("fs");
-  if (!existsSync25(statePath)) {
+  const statePath = join18(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const { existsSync: existsSync26, readFileSync: readFileSync16, rmSync: rmSync4 } = await import("fs");
+  if (!existsSync26(statePath)) {
     jsonOut2({
       sessionId,
       stopped: false,
@@ -9264,7 +8793,7 @@ bridgeCommand.command("stop-recording").description(
   };
   let attempts = 0;
   while (isProcessRunning(pid) && attempts < 20) {
-    await new Promise((resolve9) => setTimeout(resolve9, 250));
+    await new Promise((resolve10) => setTimeout(resolve10, 250));
     attempts++;
   }
   if (isProcessRunning(pid)) {
@@ -9277,7 +8806,7 @@ bridgeCommand.command("stop-recording").description(
     rmSync4(statePath, { force: true });
   } catch {
   }
-  if (!existsSync25(outputPath)) {
+  if (!existsSync26(outputPath)) {
     jsonOut2({
       sessionId,
       stopped: false,
@@ -9657,11 +9186,12 @@ bridgeCommand.command("desktop-bootstrap").description("Initialize first-run des
   await withDb2(async (db) => {
     const userId = await ensureDefaultUser(db, opts.user);
     const { enabled, url, model, locale } = await getLlmConfig(db);
-    const { workspaceDir, skillLinks } = await ensureDesktopWorkspace(db);
+    const { workspaceDir, activeWorkspaceId, skillLinks } = await ensureDesktopWorkspace(db);
     jsonOut2({
       userId,
       locale,
       llm: { enabled, url, model },
+      activeWorkspaceId,
       workspaceDir,
       skillLinks
     });
@@ -9882,8 +9412,8 @@ bridgeCommand.command("serve").description("Start the persistent JSON-RPC stdin/
 });
 
 // src/cli/commands/card.ts
-import { Command as Command6 } from "commander";
-var cardCommand = new Command6("card").description(
+import { Command as Command3 } from "commander";
+var cardCommand = new Command3("card").description(
   "Manage spaced-repetition cards"
 );
 cardCommand.command("due").description("Show due tokens for a user").option("--user <id>", "User ID (default: whoami)").option("--domain <domain>", "Filter by knowledge domain").option("--json", "Output as JSON").option("--summary", "Show only counts per domain (no slugs or concepts)").action(async (opts) => {
@@ -10081,9 +9611,9 @@ cardCommand.command("delete").description("Delete one user's card for a token").
 });
 
 // src/cli/commands/connector.ts
-import { input as input2, password as password2 } from "@inquirer/prompts";
-import { Command as Command7 } from "commander";
-var connectorCommand = new Command7("connector").description(
+import { input, password } from "@inquirer/prompts";
+import { Command as Command4 } from "commander";
+var connectorCommand = new Command4("connector").description(
   "Manage external service connectors"
 );
 connectorCommand.command("setup").description("Configure a connector").argument("<type>", "Connector type (ado, turso)").option("--url <url>", "Turso database URL (non-interactive)").option("--token <token>", "Turso auth token (non-interactive)").option(
@@ -10102,13 +9632,13 @@ connectorCommand.command("setup").description("Configure a connector").argument(
     process.exit(1);
   }
   try {
-    const orgUrl = await input2({
+    const orgUrl = await input({
       message: "Organization URL (e.g. https://dev.azure.com/myorg):"
     });
-    const project = await input2({
+    const project = await input({
       message: "Project name:"
     });
-    const pat = await password2({
+    const pat = await password({
       message: "Personal Access Token:"
     });
     if (!orgUrl || !project || !pat) {
@@ -10195,23 +9725,31 @@ connectorCommand.command("sync").description("Verify the Turso cloud database co
 });
 async function setupTurso(urlArg, tokenArg, mode) {
   let db;
+  const arch = getSystemProfile().arch;
+  const isWindowsArm64 = process.platform === "win32" && arch === "arm64";
+  const effectiveMode = mode ?? (isWindowsArm64 ? "remote" : void 0);
+  if (!mode && isWindowsArm64) {
+    console.log(
+      "Detected Windows ARM64 \u2014 defaulting to remote (HTTP) mode.\n  The native libsql driver is not available on this architecture.\n  Remote mode uses the Turso HTTP API and works everywhere.\n"
+    );
+  }
   try {
-    const url = urlArg ?? await input2({
+    const url = urlArg ?? await input({
       message: "Turso database URL (e.g. libsql://my-db-user.turso.io):"
     });
-    const token = tokenArg ?? await password2({
+    const token = tokenArg ?? await password({
       message: "Auth token:"
     });
     if (!url || !token) {
       console.error("Both URL and token are required.");
       process.exit(1);
     }
-    setTursoCredentials(url, token, void 0, mode);
+    setTursoCredentials(url, token, void 0, effectiveMode);
     db = await openDatabaseWithSync({ initialize: true });
     await db.prepare("SELECT 1").get();
     await db.close();
     console.log(
-      `Turso cloud database configured and verified: ${url}` + (mode ? ` (mode: ${mode})` : "")
+      `Turso cloud database configured and verified: ${url}` + (effectiveMode ? ` (mode: ${effectiveMode})` : "")
     );
   } catch (err) {
     await db?.close();
@@ -10226,26 +9764,26 @@ async function setupTurso(urlArg, tokenArg, mode) {
 
 // src/cli/commands/git-sync.ts
 import { execSync as execSync5 } from "child_process";
-import { chmodSync as chmodSync2, existsSync as existsSync18, writeFileSync as writeFileSync9 } from "fs";
-import { join as join18 } from "path";
-import { Command as Command8 } from "commander";
+import { chmodSync as chmodSync2, existsSync as existsSync18, writeFileSync as writeFileSync8 } from "fs";
+import { join as join19 } from "path";
+import { Command as Command5 } from "commander";
 function installHook2() {
-  const gitDir = join18(process.cwd(), ".git");
+  const gitDir = join19(process.cwd(), ".git");
   if (!existsSync18(gitDir)) {
     console.error(
       "Error: Current directory is not the root of a Git repository."
     );
     process.exit(1);
   }
-  const hooksDir = join18(gitDir, "hooks");
-  const hookPath = join18(hooksDir, "post-commit");
+  const hooksDir = join19(gitDir, "hooks");
+  const hookPath = join19(hooksDir, "post-commit");
   const hookContent = `#!/bin/sh
 # ZAM Spaced Repetition Auto-Stale Hook
 # Triggered automatically on git commits to decay modified concept cards.
 zam git-sync --commit HEAD --quiet
 `;
   try {
-    writeFileSync9(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
+    writeFileSync8(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
     try {
       chmodSync2(hookPath, "755");
     } catch (_e) {
@@ -10258,7 +9796,7 @@ zam git-sync --commit HEAD --quiet
     process.exit(1);
   }
 }
-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) => {
+var gitSyncCommand = new Command5("git-sync").description("Sync learning cards with recent Git file modifications").option("--commit <hash>", "Git commit hash to check", "HEAD").option("--user <id>", "User ID (default: whoami)").option("--install", "Install git post-commit hook in current repo").option("--quiet", "Suppress verbose output").action(async (opts) => {
   if (opts.install) {
     installHook2();
     return;
@@ -10348,9 +9886,9 @@ ZAM Auto-Stale Complete: Scanned ${changedFiles.length} file(s).`
 
 // src/cli/commands/goal.ts
 import { existsSync as existsSync19, mkdirSync as mkdirSync11 } from "fs";
-import { resolve as resolve6 } from "path";
-import { input as input3 } from "@inquirer/prompts";
-import { Command as Command9 } from "commander";
+import { resolve as resolve5 } from "path";
+import { input as input2 } from "@inquirer/prompts";
+import { Command as Command6 } from "commander";
 async function resolveGoalsDir() {
   let goalsDir;
   let db;
@@ -10361,9 +9899,9 @@ async function resolveGoalsDir() {
   } finally {
     await db?.close();
   }
-  return goalsDir ? resolve6(goalsDir) : resolve6("goals");
+  return goalsDir ? resolve5(goalsDir) : resolve5("goals");
 }
-var goalCommand = new Command9("goal").description(
+var goalCommand = new Command6("goal").description(
   "Manage learning goals (markdown files)"
 );
 goalCommand.command("list").description("List all goals").option(
@@ -10482,11 +10020,11 @@ goalCommand.command("create").description("Create a new goal").option("--slug <s
   if (!slug || !title) {
     try {
       if (!title) {
-        title = await input3({ message: "Goal title:" });
+        title = await input2({ message: "Goal title:" });
       }
       if (!slug) {
         const suggested = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-        slug = await input3({
+        slug = await input2({
           message: "Goal slug (filename):",
           default: suggested
         });
@@ -10532,22 +10070,22 @@ goalCommand.command("status <slug> <status>").description("Update a goal's statu
 });
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync20, mkdirSync as mkdirSync12, writeFileSync as writeFileSync10 } from "fs";
+import { existsSync as existsSync20, mkdirSync as mkdirSync12, writeFileSync as writeFileSync9 } from "fs";
 import { homedir as homedir11 } from "os";
-import { join as join19, resolve as resolve7 } from "path";
-import { confirm as confirm2, input as input4 } from "@inquirer/prompts";
-import { Command as Command10 } from "commander";
+import { join as join20, resolve as resolve6 } from "path";
+import { confirm, input as input3 } from "@inquirer/prompts";
+import { Command as Command7 } from "commander";
 var HOME2 = homedir11();
 function printLine(char = "\u2550", len = 60, color = "\x1B[36m") {
   console.log(`${color}${char.repeat(len)}\x1B[0m`);
 }
 function bootstrapSandboxWorkspace(workspaceDir) {
-  mkdirSync12(join19(workspaceDir, "beliefs"), { recursive: true });
-  mkdirSync12(join19(workspaceDir, "goals"), { recursive: true });
-  mkdirSync12(join19(workspaceDir, "skills"), { recursive: true });
-  const worldviewFile = join19(workspaceDir, "beliefs", "worldview.md");
+  mkdirSync12(join20(workspaceDir, "beliefs"), { recursive: true });
+  mkdirSync12(join20(workspaceDir, "goals"), { recursive: true });
+  mkdirSync12(join20(workspaceDir, "skills"), { recursive: true });
+  const worldviewFile = join20(workspaceDir, "beliefs", "worldview.md");
   if (!existsSync20(worldviewFile)) {
-    writeFileSync10(
+    writeFileSync9(
       worldviewFile,
       `# Personal Worldview
 
@@ -10559,9 +10097,9 @@ Here, I declare the core concepts and principles I want to master.
       "utf8"
     );
   }
-  const goalsFile = join19(workspaceDir, "goals", "goals.md");
+  const goalsFile = join20(workspaceDir, "goals", "goals.md");
   if (!existsSync20(goalsFile)) {
-    writeFileSync10(
+    writeFileSync9(
       goalsFile,
       `# Personal Goals
 
@@ -10573,7 +10111,7 @@ Here, I declare the core concepts and principles I want to master.
     );
   }
 }
-var initCommand = new Command10("init").description("Launch the guided interactive onboarding wizard").action(async () => {
+var initCommand = new Command7("init").description("Launch the guided interactive onboarding wizard").action(async () => {
   printLine();
   console.log(
     "\x1B[1m\x1B[32m          ZAM \u2014 The Symbiotic Learning Agent Onboarding\x1B[0m"
@@ -10583,9 +10121,9 @@ var initCommand = new Command10("init").description("Launch the guided interacti
   );
   printLine();
   console.log("\n\x1B[1m[1/5] Setting up Local Workspace Sandbox\x1B[0m");
-  const defaultWorkspace = join19(HOME2, "Documents", "zam");
-  const workspacePath = resolve7(
-    await input4({
+  const defaultWorkspace = join20(HOME2, "Documents", "zam");
+  const workspacePath = resolve6(
+    await input3({
       message: "Choose your ZAM workspace directory:",
       default: defaultWorkspace
     })
@@ -10599,6 +10137,7 @@ var initCommand = new Command10("init").description("Launch the guided interacti
       kind: "personal",
       path: workspacePath
     });
+    setActiveWorkspaceId("personal");
     console.log(
       `\x1B[32m\u2713 Local Sandbox created at: ${workspacePath}\x1B[0m`
     );
@@ -10629,7 +10168,7 @@ var initCommand = new Command10("init").description("Launch the guided interacti
   \x1B[1mRecommendation:\x1B[0m ZAM suggests installing \x1B[32m${runnerLabel}\x1B[0m with \x1B[36m${profile.recommendedModel}\x1B[0m.`
   );
   console.log("\n\x1B[1m[3/5] Setting up Local LLM Runner\x1B[0m");
-  const proceedInstall = await confirm2({
+  const proceedInstall = await confirm({
     message: `Would you like ZAM to install and configure ${runnerLabel} automatically?`,
     default: true
   });
@@ -10666,7 +10205,7 @@ var initCommand = new Command10("init").description("Launch the guided interacti
   let db;
   try {
     db = await openDatabaseWithSync({ initialize: true });
-    await setSetting(db, "personal.workspace_dir", workspacePath);
+    await deleteSetting(db, "personal.workspace_dir");
     const detectedLocale = detectSystemLocale();
     await setSetting(db, "system.locale", detectedLocale);
     console.log(
@@ -10697,7 +10236,7 @@ var initCommand = new Command10("init").description("Launch the guided interacti
   console.log(
     "\n\x1B[1m[5/5] Wiring Developer Agents & Terminal Helpers\x1B[0m"
   );
-  const proceedHooks = await confirm2({
+  const proceedHooks = await confirm({
     message: "Distribute ZAM skills and install optional monitored-session shell helpers?",
     default: true
   });
@@ -10748,8 +10287,8 @@ var initCommand = new Command10("init").description("Launch the guided interacti
 });
 
 // src/cli/commands/learn.ts
-import { input as input6 } from "@inquirer/prompts";
-import { Command as Command11 } from "commander";
+import { input as input5 } from "@inquirer/prompts";
+import { Command as Command8 } from "commander";
 
 // src/cli/learn-format.ts
 var BLOOM_VERBS3 = {
@@ -10798,7 +10337,7 @@ function formatReveal(input8) {
 }
 
 // src/cli/review-actions.ts
-import { confirm as confirm3, input as input5, select } from "@inquirer/prompts";
+import { confirm as confirm2, input as input4, select } from "@inquirer/prompts";
 async function runInteractiveReviewAction(inputData) {
   let currentItem = { ...inputData.item };
   while (true) {
@@ -10913,7 +10452,7 @@ async function runInteractiveReviewAction(inputData) {
       continue;
     }
     if (choice === "deprecate-token") {
-      const approved = await confirm3({
+      const approved = await confirm2({
         message: `Deprecate ${currentItem.slug} so it stops appearing in review queues?`,
         default: false
       });
@@ -10944,7 +10483,7 @@ async function runInteractiveReviewAction(inputData) {
       console.log(`  Session steps:         ${impact.session_steps}`);
       console.log(`  Sessions touched:      ${impact.sessions_touched}`);
       console.log(`  Agent skills updated:  ${impact.agent_skills}`);
-      const approved = await confirm3({
+      const approved = await confirm2({
         message: "Permanently delete this token and its dependent learning data?",
         default: false
       });
@@ -10969,7 +10508,7 @@ async function runInteractiveReviewAction(inputData) {
       );
       console.log(`Delete your card for ${currentItem.slug}?`);
       console.log(`  Review logs removed: ${impact.review_logs}`);
-      const approved = await confirm3({
+      const approved = await confirm2({
         message: "Delete only your card for this token?",
         default: false
       });
@@ -11007,21 +10546,21 @@ async function promptTokenEdit(token) {
   }
   switch (field) {
     case "concept": {
-      const concept = await input5({
+      const concept = await input4({
         message: "Concept:",
         default: token.concept
       });
       return concept === token.concept ? null : { concept };
     }
     case "domain": {
-      const domain = await input5({
+      const domain = await input4({
         message: "Domain (blank allowed):",
         default: token.domain
       });
       return domain === token.domain ? null : { domain };
     }
     case "context": {
-      const context = await input5({
+      const context = await input4({
         message: "Context (blank allowed):",
         default: token.context
       });
@@ -11062,14 +10601,14 @@ async function promptTokenEdit(token) {
       return mode === token.symbiosis_mode ? null : { symbiosis_mode: mode };
     }
     case "source_link": {
-      const link = await input5({
+      const link = await input4({
         message: "Source link (blank allowed):",
         default: token.source_link ?? ""
       });
       return link === token.source_link ? null : { source_link: link || null };
     }
     case "question": {
-      const question = await input5({
+      const question = await input4({
         message: "Recall question (blank allowed):",
         default: token.question ?? ""
       });
@@ -11087,7 +10626,7 @@ var STOP_WORDS = /* @__PURE__ */ new Set(["q", ":q", "quit", "stop"]);
 function isExitPrompt(err) {
   return err instanceof Error && err.name === "ExitPromptError";
 }
-var learnCommand = new Command11("learn").description(
+var learnCommand = new Command8("learn").description(
   "Run a spoiler-free, in-process learning session (recall \u2192 reveal \u2192 self-rate)"
 ).option("--user <id>", "User ID (default: whoami)").option("--max-new <n>", "Maximum new cards", "10").option("--max-reviews <n>", "Maximum review cards", "50").option("--no-resolve", "Skip resolving source_link into the revealed answer").action(async (opts) => {
   let db;
@@ -11167,7 +10706,7 @@ ${"\u2500".repeat(50)}`);
   ${prompt.question}`);
       let answer;
       try {
-        answer = await input6({
+        answer = await input5({
           message: t(locale, "prompt_answer")
         });
       } catch (err) {
@@ -11332,8 +10871,8 @@ learnCommand.command("open").description("Open a new terminal window running zam
 });
 
 // src/cli/commands/monitor.ts
-import { Command as Command12 } from "commander";
-var monitorCommand = new Command12("monitor").description(
+import { Command as Command9 } from "commander";
+var monitorCommand = new Command9("monitor").description(
   "Shell observation for real-time task monitoring"
 );
 monitorCommand.command("start").description("Output shell hook code to install monitoring").requiredOption("--session <id>", "Session ID to monitor").option(
@@ -11515,8 +11054,8 @@ monitorCommand.command("open").description("Open a new monitored terminal window
 });
 
 // src/cli/commands/observer.ts
-import { Command as Command13 } from "commander";
-var observerCommand = new Command13("observer").description(
+import { Command as Command10 } from "commander";
+var observerCommand = new Command10("observer").description(
   "Configure what the UI observer may capture (Layer 2 policy)"
 );
 function applyObserverListChange(current, entry, op) {
@@ -11537,107 +11076,343 @@ observerCommand.command("status").description("Show the active observer policy")
     console.log(`  Consent:       ${policy.consent}`);
     console.log(`  Retention:     ${policy.retention}`);
     console.log(
-      `  Allowlist:     ${policy.allowlist.length ? policy.allowlist.join(", ") : "(any targeted window)"}`
+      `  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 { dirname as dirname6, resolve as resolve7 } from "path";
+import { Command as Command11 } from "commander";
+var C2 = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  cyan: "\x1B[36m",
+  dim: "\x1B[2m",
+  green: "\x1B[32m"
+};
+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 Command11("profile").description("Show or change this machine's ZAM install profile").option("--mode <mode>", "Set install mode: developer | default").option("--dir <path>", "Set the personal-content folder").option("--json", "Output as JSON").action(async (opts) => {
+  if (opts.mode && opts.mode !== "developer" && opts.mode !== "default") {
+    console.error(`Invalid --mode: ${opts.mode}. Use developer or default.`);
+    process.exit(1);
+  }
+  let db;
+  try {
+    if (opts.mode) setInstallMode(opts.mode);
+    db = await openDatabaseWithSync({ initialize: true });
+    if (opts.dir) {
+      await activateWorkspacePath(db, resolve7(opts.dir), {
+        kind: "personal",
+        label: "Personal"
+      });
+    }
+    const personalDir = (await ensureActiveWorkspace(db)).path;
+    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 Command12 } from "commander";
+var providerCommand = new Command12("provider").description(
+  "Configure role-based AI providers (url/model/flavor/key, per role)"
+);
+providerCommand.command("list").description("Show configured providers, role bindings, and key status").option("--json", "Output as JSON").option("--machine", "Read machine-local providers from ~/.zam/config.json").action(async (opts) => {
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const roles = await readScopedRoles(db, machine);
+    const rows = buildProviderListing(
+      providers,
+      (ref) => getProviderApiKey(ref) !== null
+    );
+    const orphans = findOrphanKeyRefs(listProviderApiKeyRefs(), providers);
+    if (opts.json) {
+      console.log(
+        JSON.stringify(
+          {
+            scope: machine ? "machine" : "shared",
+            providers: rows,
+            roles,
+            orphans
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    console.log(
+      `Providers (${opts.machine ? "~/.zam/config.json ai.providers" : "llm.providers"}):
+`
+    );
+    if (rows.length === 0) {
+      console.log(
+        "  (none) \u2014 add one: zam provider add <name> --url <url> --model <model>"
+      );
+    } else {
+      for (const row of rows) {
+        const key = row.keyState === "set" ? "\x1B[32mkey \u2713\x1B[0m" : row.keyState === "missing" ? `\x1B[31mkey \u2717 (set: zam provider set-key ${row.apiKeyRef})\x1B[0m` : "\x1B[90mno key\x1B[0m";
+        console.log(`  \x1B[36m${row.name.padEnd(12)}\x1B[0m ${key}`);
+        console.log(`      url:    ${row.url ?? "(inherits llm.url)"}`);
+        console.log(`      model:  ${row.model ?? "(inherits llm.model)"}`);
+        console.log(`      flavor: ${row.apiFlavor}`);
+        if (row.label) console.log(`      label:  ${row.label}`);
+        if (row.local !== void 0) {
+          console.log(`      local:  ${row.local ? "yes" : "no"}`);
+        }
+        if (row.runner) console.log(`      runner: ${row.runner}`);
+        if (row.apiKeyRef) console.log(`      key-ref: ${row.apiKeyRef}`);
+      }
+    }
+    console.log("\nRoles (llm.roles):\n");
+    for (const role of VALID_ROLES) {
+      const binding = roles[role];
+      if (!binding?.primary) {
+        console.log(`  ${role.padEnd(7)} \x1B[90m(unset)\x1B[0m`);
+      } else {
+        const fb = binding.fallback ? ` \u2192 fallback: ${binding.fallback}` : "";
+        console.log(`  ${role.padEnd(7)} primary: ${binding.primary}${fb}`);
+      }
+    }
+    if (orphans.length > 0) {
+      console.log(
+        `
+\x1B[33mOrphan keys (stored but unreferenced):\x1B[0m ${orphans.join(", ")}`
+      );
+    }
+  });
+});
+providerCommand.command("add <name>").description("Add or update a provider record in llm.providers").option("--label <label>", "Human-readable provider label").option("--url <url>", "Endpoint base URL (e.g. https://api.deepseek.com/v1)").option("--model <model>", "Model id (e.g. deepseek-v4-flash)").option("--local", "Mark this provider as a local/on-device endpoint").option(
+  "--runner <runner>",
+  "Local runner hint (flm, foundry-local, ollama, ...)"
+).option(
+  "--flavor <flavor>",
+  `Wire protocol: ${VALID_API_FLAVORS.join(" | ")} (default: inferred from URL)`
+).option(
+  "--key-ref <ref>",
+  "Credential reference for the API key (default: <name> when --key is given)"
+).option(
+  "--key <value>",
+  "Store this API key now (prefer `set-key` to keep it out of shell history)"
+).option("--machine", "Store this provider in ~/.zam/config.json").action(async (name, opts) => {
+  let apiFlavor;
+  if (opts.flavor) {
+    if (!VALID_API_FLAVORS.includes(opts.flavor)) {
+      console.error(
+        `Invalid --flavor: ${opts.flavor}. Use ${VALID_API_FLAVORS.join(" or ")}.`
+      );
+      process.exit(1);
+    }
+    apiFlavor = opts.flavor;
+  }
+  const apiKeyRef = opts.keyRef ?? (opts.key ? name : void 0);
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    const next = upsertProviderRecord(providers, name, {
+      label: opts.label,
+      url: opts.url,
+      model: opts.model,
+      apiFlavor,
+      apiKeyRef,
+      local: opts.local ? true : void 0,
+      runner: opts.runner
+    });
+    await writeScopedProviders(db, machine, next);
+    if (opts.key && apiKeyRef) setProviderApiKey(apiKeyRef, opts.key);
+    const rec = next[name];
+    console.log(
+      `Provider "${name}" saved (${machine ? "machine-local" : "shared"}):`
     );
+    console.log(`  url:     ${rec.url ?? "(inherits llm.url)"}`);
+    console.log(`  model:   ${rec.model ?? "(inherits llm.model)"}`);
+    if (rec.label) console.log(`  label:   ${rec.label}`);
+    if (rec.local !== void 0) {
+      console.log(`  local:   ${rec.local ? "yes" : "no"}`);
+    }
+    if (rec.runner) console.log(`  runner:  ${rec.runner}`);
     console.log(
-      `  Denylist:      ${policy.denylist.length ? policy.denylist.join(", ") : "(none)"}`
+      `  flavor:  ${rec.apiFlavor ?? `${rec.url ? inferApiFlavor(rec.url) : "chat-completions"} (inferred)`}`
     );
-    console.log(`  Redact titles: ${policy.redactWindowTitles}`);
+    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(
-      "\nBuilt-in sensitive surfaces (password managers, auth/UAC dialogs, banking) are always refused and cannot be allowlisted."
+      `
+Bind it to a role: zam provider use recall --primary ${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"
+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
     );
-    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"
+    if (!removed) {
+      console.log(`No such provider: ${name}`);
+      return;
+    }
+    await writeScopedProviders(db, machine, next);
+    console.log(
+      `Removed provider "${name}" (${machine ? "machine-local" : "shared"}).`
     );
-    await setSetting(db, "observer.allowlist", next);
-    await syncObserverSidecarPolicy(db);
-    console.log(`Revoked: ${processName.trim().toLowerCase()}`);
-    console.log(`observer.allowlist = ${next || "(empty)"}`);
+    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>`
+      );
+    }
   });
 });
-
-// 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.`);
+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);
   }
-  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));
+  if (!opts.primary) {
+    console.error("--primary is required.");
+    process.exit(1);
+  }
+  const machine = Boolean(opts.machine);
+  await withProviderScope(machine, async (db) => {
+    const providers = await readScopedProviders(db, machine);
+    await writeScopedRoles(
+      db,
+      machine,
+      bindRoleProviders(
+        await readScopedRoles(db, machine),
+        role,
+        opts.primary,
+        opts.fallback
+      )
+    );
+    const fb = opts.fallback ? `, fallback: ${opts.fallback}` : "";
+    console.log(
+      `Role "${role}" \u2192 primary: ${opts.primary}${fb} (${machine ? "machine-local" : "shared"})`
+    );
+    for (const [label, ref] of [
+      ["primary", opts.primary],
+      ["fallback", opts.fallback]
+    ]) {
+      if (ref && !(ref in providers)) {
+        console.log(
+          `  \u26A0 ${label} "${ref}" is not a defined provider yet. Add it: zam provider add ${ref} --url <url> --model <model>`
+        );
+      }
     }
-    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;
+  });
+});
+providerCommand.command("set-key <ref>").description(
+  "Store an API key for a provider reference (in credentials.json)"
+).option(
+  "--key <value>",
+  "The API key (omit to enter it interactively, hidden)"
+).action(async (ref, opts) => {
+  try {
+    const key = opts.key ?? await password2({ message: `API key for "${ref}":` });
+    if (!key || key.trim().length === 0) {
+      console.error("No key provided.");
+      process.exit(1);
     }
-    render(profile);
+    setProviderApiKey(ref, key.trim());
+    console.log(`Stored API key for "${ref}" (${maskSecret(key.trim())}).`);
   } catch (err) {
-    await db?.close();
+    if (err.name === "ExitPromptError") {
+      console.log("\nCancelled.");
+      process.exit(0);
+    }
     console.error("Error:", err.message);
     process.exit(1);
   }
 });
+providerCommand.command("clear-key <ref>").description("Remove a stored API key").action((ref) => {
+  clearProviderApiKey(ref);
+  console.log(`Cleared API key for "${ref}".`);
+});
 
 // src/cli/commands/review.ts
-import { Command as Command15 } from "commander";
-var reviewCommand = new Command15("review").description("Start an interactive review session").option("--user <id>", "User ID (default: whoami)").option("--max-new <n>", "Maximum new cards", "10").option("--max-reviews <n>", "Maximum review cards", "50").option("--no-resolve", "Skip resolving source_link into inline context").action(async (opts) => {
+import { Command as Command13 } from "commander";
+var reviewCommand = new Command13("review").description("Start an interactive review session").option("--user <id>", "User ID (default: whoami)").option("--max-new <n>", "Maximum new cards", "10").option("--max-reviews <n>", "Maximum review cards", "50").option("--no-resolve", "Skip resolving source_link into inline context").action(async (opts) => {
   let db;
   try {
     db = await openDatabase();
@@ -11751,9 +11526,9 @@ ${"\u2550".repeat(50)}`);
 
 // src/cli/commands/session.ts
 import { readFileSync as readFileSync12 } from "fs";
-import { input as input7, select as select2 } from "@inquirer/prompts";
-import { Command as Command16 } from "commander";
-var sessionCommand = new Command16("session").description(
+import { input as input6, select as select2 } from "@inquirer/prompts";
+import { Command as Command14 } from "commander";
+var sessionCommand = new Command14("session").description(
   "Manage learning sessions"
 );
 sessionCommand.command("start").description("Start a new learning session (review \u2192 task)").option("--user <id>", "User ID (default: whoami)").option("--task <description>", "Task description (interactive if omitted)").option(
@@ -11930,7 +11705,7 @@ async function selectTask() {
       console.log("No active work items found in Azure DevOps.");
     }
   }
-  return input7({ message: "Task description:" });
+  return input6({ message: "Task description:" });
 }
 var RATING_LABELS = {
   1: "Again",
@@ -12133,8 +11908,8 @@ sessionCommand.command("end").description("End a session and show summary").requ
 
 // src/cli/commands/settings.ts
 import { existsSync as existsSync21 } from "fs";
-import { Command as Command17 } from "commander";
-var settingsCommand = new Command17("settings").description(
+import { Command as Command15 } from "commander";
+var settingsCommand = new Command15("settings").description(
   "Manage user settings"
 );
 var BOOLEAN_SETTING_KEYS = /* @__PURE__ */ new Set(["llm.enabled", "llm.vision.enabled"]);
@@ -12305,12 +12080,108 @@ settingsCommand.command("repos").description("Show or set Personal, Team, and Or
         console.log(`  ${name.padEnd(9)}: \x1B[33m- Not Set\x1B[0m`);
       }
     }
-  });
-});
+  });
+});
+
+// src/cli/commands/setup.ts
+import { resolve as resolve8 } from "path";
+import { Command as Command16 } from "commander";
+function formatDatabaseInitTarget(target) {
+  switch (target.kind) {
+    case "local":
+      return `ZAM database at ${target.location} (local SQLite)`;
+    case "turso-remote":
+      return `ZAM database via Turso remote at ${target.location}`;
+    case "turso-native":
+      return `ZAM database via Turso native driver at ${target.location}`;
+    case "turso-replica":
+      return `ZAM database replica at ${target.location} syncing from ${target.syncUrl}`;
+  }
+}
+async function initDatabase(skipInit) {
+  if (skipInit) return;
+  try {
+    const target = getDatabaseTargetInfo();
+    const db = await openDatabaseWithSync({ initialize: true });
+    await activateMachineProviderConfig(db);
+    await db.close();
+    console.log(`  init  ${formatDatabaseInitTarget(target)}`);
+  } catch (err) {
+    const msg = err.message;
+    if (!msg.includes("already")) {
+      console.warn(`  warn  database init: ${msg}`);
+    } else {
+      console.log(`  skip  database already initialized`);
+    }
+  }
+}
+async function activateMachineProviderConfig(db) {
+  const machineAi = getMachineAiConfig();
+  const providerCount = Object.keys(machineAi.providers ?? {}).length;
+  const roleCount = Object.keys(machineAi.roles ?? {}).length;
+  if (providerCount === 0 && roleCount === 0) return;
+  if (await getSetting(db, "llm.enabled") !== void 0) return;
+  await setSetting(db, "llm.enabled", "true");
+  console.log(
+    `  activate  ${providerCount} machine-local provider(s) from ~/.zam/config.json`
+  );
+}
+var setupCommand = new Command16("setup").description(
+  "Link ZAM skill directories into this workspace and initialize the database"
+).option("--force", "replace an unmanaged existing ZAM skill directory", false).option("--skip-init", "skip database initialization", false).option("--skip-claude-md", "skip CLAUDE.md generation", false).option("--skip-agents-md", "skip AGENTS.md generation", false).option("--target <path>", "repository/workspace directory to set up").option(
+  "--agents <list>",
+  "comma-separated agents to wire: all, claude, copilot, codex, agent"
+).option(
+  "--dry-run",
+  "show what would be written without changing files",
+  false
+).action(
+  async (opts) => {
+    let agents;
+    try {
+      agents = parseSetupAgents(opts.agents);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    const target = resolve8(opts.target ?? process.cwd());
+    const updateExistingInstructions = Boolean(opts.target) || opts.force;
+    console.log(
+      `Setting up ZAM in ${target}${opts.dryRun ? " (dry run)" : ""}
+`
+    );
+    wireSkills(target, agents, {
+      force: opts.force,
+      dryRun: opts.dryRun
+    });
+    await initDatabase(opts.skipInit || opts.dryRun);
+    if (agents.has("claude")) {
+      writeClaudeMd(opts.skipClaudeMd, target, {
+        dryRun: opts.dryRun,
+        updateExisting: updateExistingInstructions
+      });
+    }
+    if (agents.has("codex") || agents.has("agent")) {
+      writeAgentsMd(opts.skipAgentsMd, target, {
+        dryRun: opts.dryRun,
+        updateExisting: updateExistingInstructions
+      });
+    }
+    if (agents.has("copilot") && (opts.target || opts.agents)) {
+      writeCopilotInstructions(target, {
+        dryRun: opts.dryRun,
+        updateExisting: updateExistingInstructions
+      });
+    }
+    console.log(
+      "\nDone. Run `zam whoami --set <your-id>` to set your identity. Start the `zam` skill with `/zam` in Claude/Copilot/Gemini-compatible clients or `$zam` (or `/skills`) in Codex."
+    );
+  }
+);
 
 // src/cli/commands/skill.ts
-import { Command as Command18 } from "commander";
-var skillCommand = new Command18("skill").description(
+import { Command as Command17 } from "commander";
+var skillCommand = new Command17("skill").description(
   "Manage agent skill entries (task recipes)"
 );
 skillCommand.command("list").description("List all agent skills").option("--json", "Output as JSON").action(async (opts) => {
@@ -12395,10 +12266,9 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
 });
 
 // src/cli/commands/snapshot.ts
-import { existsSync as existsSync22, mkdirSync as mkdirSync13, readFileSync as readFileSync13, writeFileSync as writeFileSync11 } from "fs";
-import { homedir as homedir13 } from "os";
+import { existsSync as existsSync22, mkdirSync as mkdirSync13, readFileSync as readFileSync13, writeFileSync as writeFileSync10 } from "fs";
 import { dirname as dirname7, join as join21 } from "path";
-import { Command as Command19 } from "commander";
+import { Command as Command18 } from "commander";
 function defaultOutName() {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
   return `zam-snapshot-${stamp}.sql`;
@@ -12412,12 +12282,12 @@ function summarize(tables) {
   }
   return { total, nonEmpty };
 }
-var exportCmd = new Command19("export").description("Write a portable SQL-text snapshot of the database").option("--out <file>", "Output file (use - for stdout)").action(async (opts) => {
+var exportCmd = new Command18("export").description("Write a portable SQL-text snapshot of the database").option("--out <file>", "Output file (use - for stdout)").action(async (opts) => {
   let db;
   try {
     db = await openDatabaseWithSync({ initialize: true });
     const snapshot = await exportSnapshot(db);
-    const personalDir = await getSetting(db, "personal.workspace_dir") || join21(homedir13(), "Documents", "zam");
+    const personalDir = (await ensureActiveWorkspace(db)).path;
     await db.close();
     db = void 0;
     const manifest = verifySnapshot(snapshot);
@@ -12431,7 +12301,7 @@ var exportCmd = new Command19("export").description("Write a portable SQL-text s
     if (dir && dir !== "." && !existsSync22(dir)) {
       mkdirSync13(dir, { recursive: true });
     }
-    writeFileSync11(out, snapshot, "utf-8");
+    writeFileSync10(out, snapshot, "utf-8");
     console.log(`Snapshot written: ${out}`);
     console.log(
       `  ${total} row(s)${nonEmpty.length ? ` \u2014 ${nonEmpty.join(", ")}` : ""}`
@@ -12442,7 +12312,7 @@ var exportCmd = new Command19("export").description("Write a portable SQL-text s
     process.exit(1);
   }
 });
-var importCmd = new Command19("import").description("Restore a snapshot into the database").argument("<file>", "Snapshot file to restore").option("--force", "Overwrite a non-empty database", false).action(async (file, opts) => {
+var importCmd = new Command18("import").description("Restore a snapshot into the database").argument("<file>", "Snapshot file to restore").option("--force", "Overwrite a non-empty database", false).action(async (file, opts) => {
   let db;
   try {
     if (!existsSync22(file)) {
@@ -12465,7 +12335,7 @@ var importCmd = new Command19("import").description("Restore a snapshot into the
     process.exit(1);
   }
 });
-var verifyCmd = new Command19("verify").description("Check a snapshot's manifest and checksum without importing").argument("<file>", "Snapshot file to verify").action((file) => {
+var verifyCmd = new Command18("verify").description("Check a snapshot's manifest and checksum without importing").argument("<file>", "Snapshot file to verify").action((file) => {
   try {
     if (!existsSync22(file)) {
       console.error(`Error: Snapshot file not found: ${file}`);
@@ -12483,11 +12353,11 @@ var verifyCmd = new Command19("verify").description("Check a snapshot's manifest
     process.exit(1);
   }
 });
-var snapshotCommand = new Command19("snapshot").description("Export, import, or verify a portable database snapshot").addCommand(exportCmd).addCommand(importCmd).addCommand(verifyCmd);
+var snapshotCommand = new Command18("snapshot").description("Export, import, or verify a portable database snapshot").addCommand(exportCmd).addCommand(importCmd).addCommand(verifyCmd);
 
 // src/cli/commands/stats.ts
-import { Command as Command20 } from "commander";
-var statsCommand = new Command20("stats").description("Show learning dashboard for a user").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").action(async (opts) => {
+import { Command as Command19 } from "commander";
+var statsCommand = new Command19("stats").description("Show learning dashboard for a user").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").action(async (opts) => {
   await withDb(async (db) => {
     const userId = await resolveUser(opts, db);
     const stats = await getUserStats(db, userId);
@@ -12523,8 +12393,8 @@ var statsCommand = new Command20("stats").description("Show learning dashboard f
 });
 
 // src/cli/commands/token.ts
-import { Command as Command21 } from "commander";
-var tokenCommand = new Command21("token").description(
+import { Command as Command20 } from "commander";
+var tokenCommand = new Command20("token").description(
   "Manage knowledge tokens"
 );
 tokenCommand.command("register").description("Register a new knowledge token").requiredOption("--slug <slug>", "Unique token slug").requiredOption("--concept <concept>", "Concept description").option("--domain <domain>", "Knowledge domain", "").option("--bloom <level>", "Bloom taxonomy level (1-5)", "1").option("--source-link <link>", "Source file path or reference URL", "").option("--question <question>", "Specific question prompt for recall", "").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
@@ -12812,10 +12682,10 @@ tokenCommand.command("status").description("Show full status of a token for a us
 // src/cli/commands/ui.ts
 import { spawn as spawn3, spawnSync } from "child_process";
 import { existsSync as existsSync23 } from "fs";
-import { homedir as homedir14 } from "os";
+import { homedir as homedir12 } from "os";
 import { dirname as dirname8, join as join22 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
-import { Command as Command22 } from "commander";
+import { Command as Command21 } from "commander";
 var C3 = {
   reset: "\x1B[0m",
   red: "\x1B[31m",
@@ -12862,7 +12732,7 @@ function findInstalledApp() {
     process.env.LOCALAPPDATA && join22(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
     process.env.ProgramFiles && join22(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
     process.env["ProgramFiles(x86)"] && join22(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
-  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join22(homedir14(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
+  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join22(homedir12(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
   return candidates.find((candidate) => candidate && existsSync23(candidate)) || null;
 }
 function runNpm(args, opts) {
@@ -12995,13 +12865,13 @@ function createShortcuts(appPath, repoRoot) {
     console.error(`${C3.red}\u2717 Could not create shortcuts.${C3.reset}`);
   }
 }
-var uiCommand = new Command22("ui").description("Launch the ZAM Desktop GUI (Active-Recall Studio)").option("--dev", "Run in hot-reload development mode (needs Rust)").option(
+var uiCommand = new Command21("ui").description("Launch the ZAM Desktop GUI (Active-Recall Studio)").option("--dev", "Run in hot-reload development mode (needs Rust)").option(
   "--build",
   "Build the native installer for your OS (needs Rust, one-time)"
 ).option("--shortcut", "Create Desktop + Start-menu shortcuts to the GUI").action((opts) => {
   const installedApp = findInstalledApp();
   if (!opts.dev && !opts.build && !opts.shortcut && installedApp) {
-    launchApp(installedApp, homedir14());
+    launchApp(installedApp, homedir12());
     return;
   }
   const desktopDir = findDesktopDir();
@@ -13102,8 +12972,8 @@ import { spawnSync as spawnSync2 } from "child_process";
 import { existsSync as existsSync24, readFileSync as readFileSync14, realpathSync as realpathSync2 } from "fs";
 import { dirname as dirname9, join as join23 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
-import { confirm as confirm4 } from "@inquirer/prompts";
-import { Command as Command23 } from "commander";
+import { confirm as confirm3 } from "@inquirer/prompts";
+import { Command as Command22 } from "commander";
 var GITHUB_REPO = "zam-os/zam";
 var CHANNELS = [
   "developer",
@@ -13131,273 +13001,647 @@ function currentVersion() {
     } catch {
     }
   }
-  return "0.0.0";
+  return "0.0.0";
+}
+function versionAt(dir) {
+  try {
+    const pkg2 = JSON.parse(
+      readFileSync14(join23(dir, "package.json"), "utf-8")
+    );
+    return pkg2.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function fetchLatestVersion(repo) {
+  const res = await fetch(
+    `https://api.github.com/repos/${repo}/releases/latest`,
+    {
+      headers: {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "zam-cli"
+      }
+    }
+  );
+  if (!res.ok) {
+    throw new Error(
+      `Could not reach the release server (HTTP ${res.status}). Pass --latest <version> to check offline.`
+    );
+  }
+  const data = await res.json();
+  if (!data.tag_name) throw new Error("No published release found yet.");
+  return data.tag_name;
+}
+function render2(decision) {
+  if (!decision.updateAvailable) {
+    console.log(
+      `${C4.green}\u2713${C4.reset} ZAM is up to date (${C4.cyan}${decision.currentVersion}${C4.reset}).`
+    );
+    return;
+  }
+  console.log(
+    `${C4.yellow}\u2191${C4.reset} ${C4.bold}Update available${C4.reset}: ${C4.dim}${decision.currentVersion}${C4.reset} \u2192 ${C4.cyan}${decision.latestVersion}${C4.reset}`
+  );
+  console.log(`  ${decision.reason}`);
+  if (decision.action === "run-command" || decision.action === "inform") {
+    console.log(`  Run: ${C4.cyan}${decision.command}${C4.reset}`);
+  } else if (decision.action === "self-update") {
+    console.log(
+      `  ${C4.dim}The desktop app can apply this update for you.${C4.reset}`
+    );
+  }
+}
+var checkCmd = new Command22("check").description("Check whether a newer ZAM has been released").option(
+  "--latest <version>",
+  "Compare against this version instead of fetching"
+).option("--channel <channel>", "Override the detected install channel").option("--json", "Output as JSON").action(
+  async (opts) => {
+    try {
+      if (opts.channel && !CHANNELS.includes(opts.channel)) {
+        console.error(
+          `Invalid --channel: ${opts.channel}. Use ${CHANNELS.join(", ")}.`
+        );
+        process.exit(1);
+      }
+      const current = currentVersion();
+      const latest = opts.latest ?? await fetchLatestVersion(GITHUB_REPO);
+      const channel = opts.channel ?? getInstallChannel();
+      const decision = decideUpdate({
+        currentVersion: current,
+        latestVersion: latest,
+        channel
+      });
+      if (opts.json) {
+        console.log(JSON.stringify(decision, null, 2));
+        return;
+      }
+      render2(decision);
+    } catch (err) {
+      console.error("Error:", err.message);
+      process.exit(1);
+    }
+  }
+);
+function findSourceRepo() {
+  let dir = realpathSync2(dirname9(fileURLToPath4(import.meta.url)));
+  let parent = dirname9(dir);
+  while (parent !== dir) {
+    if (existsSync24(join23(dir, ".git"))) return dir;
+    dir = parent;
+    parent = dirname9(dir);
+  }
+  return existsSync24(join23(dir, ".git")) ? dir : null;
+}
+function runGit(cwd, args, capture) {
+  const res = spawnSync2("git", args, {
+    cwd,
+    stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
+    encoding: "utf8"
+  });
+  return { ok: res.status === 0, out: (res.stdout ?? "").trim() };
+}
+function runNpm2(args, cwd) {
+  const res = spawnSync2("npm", args, {
+    cwd,
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+  return res.status ?? 1;
+}
+function runShell(command) {
+  const res = spawnSync2(command, { stdio: "inherit", shell: true });
+  return res.status === 0;
+}
+function applyDeveloperUpdate(force) {
+  if (!hasCommand("git")) {
+    console.error(`${C4.red}\u2717${C4.reset} git was not found on PATH.`);
+    process.exit(1);
+  }
+  const src = findSourceRepo();
+  if (!src) {
+    console.error(
+      `${C4.red}\u2717${C4.reset} Could not locate the ZAM source checkout to update.`
+    );
+    process.exit(1);
+  }
+  const status = runGit(src, ["status", "--porcelain"], true);
+  if (status.ok && status.out && !force) {
+    console.error(
+      `${C4.red}\u2717${C4.reset} The source checkout has uncommitted changes:
+${status.out}
+Commit or stash them, or re-run with ${C4.cyan}--force${C4.reset}.`
+    );
+    process.exit(1);
+  }
+  console.log(
+    `${C4.dim}\u2192 git pull --ff-only${C4.reset}  ${C4.dim}(${src})${C4.reset}`
+  );
+  if (!runGit(src, ["pull", "--ff-only"], false).ok) {
+    console.error(
+      `${C4.red}\u2717${C4.reset} git pull failed \u2014 the branch may have diverged or you are offline. Resolve it manually, then retry.`
+    );
+    process.exit(1);
+  }
+  console.log(`${C4.dim}\u2192 npm install${C4.reset}`);
+  if (runNpm2(["install"], src) !== 0) {
+    console.error(`${C4.red}\u2717${C4.reset} npm install failed.`);
+    process.exit(1);
+  }
+  console.log(`${C4.dim}\u2192 npm run build${C4.reset}`);
+  if (runNpm2(["run", "build"], src) !== 0) {
+    console.error(`${C4.red}\u2717${C4.reset} Build failed.`);
+    process.exit(1);
+  }
+  console.log(`${C4.dim}\u2192 zam setup --force${C4.reset}`);
+  const setup = spawnSync2(
+    process.execPath,
+    [join23(src, "dist", "cli", "index.js"), "setup", "--force"],
+    { cwd: process.cwd(), stdio: "inherit" }
+  );
+  if (setup.status !== 0) {
+    console.warn(
+      `${C4.yellow}\u26A0${C4.reset} Skill refresh reported a problem \u2014 run '${C4.cyan}zam setup --force${C4.reset}' here manually.`
+    );
+  }
+  console.log(
+    `
+${C4.green}\u2713${C4.reset} Updated to ${C4.cyan}${versionAt(src)}${C4.reset}. Restart your agent client (e.g. Claude Code) to load the refreshed ${C4.cyan}/zam${C4.reset} skill.`
+  );
+}
+async function applyUpdate(opts) {
+  try {
+    const current = currentVersion();
+    const latest = await fetchLatestVersion(GITHUB_REPO);
+    const channel = getInstallChannel();
+    const decision = decideUpdate({
+      currentVersion: current,
+      latestVersion: latest,
+      channel
+    });
+    if (!decision.updateAvailable) {
+      console.log(
+        `${C4.green}\u2713${C4.reset} ZAM is up to date (${C4.cyan}${current}${C4.reset}).`
+      );
+      return;
+    }
+    console.log(
+      `${C4.yellow}\u2191${C4.reset} ${C4.bold}Update available${C4.reset}: ${C4.dim}${current}${C4.reset} \u2192 ${C4.cyan}${latest}${C4.reset} ${C4.dim}(${channel} install)${C4.reset}`
+    );
+    for (const step of planUpdate(decision)) {
+      console.log(`  ${C4.dim}\u2022${C4.reset} ${step.label}`);
+    }
+    if (channel === "direct") {
+      console.log(
+        `
+${C4.dim}This install updates through the desktop app's signed updater \u2014 open ZAM Desktop to install ${latest}.${C4.reset}`
+      );
+      return;
+    }
+    if (!opts.yes) {
+      const ok = await confirm3({
+        message: "Apply this update?",
+        default: true
+      });
+      if (!ok) {
+        console.log("Aborted.");
+        return;
+      }
+    }
+    console.log();
+    if (channel === "winget" || channel === "homebrew") {
+      if (!decision.command || !runShell(decision.command)) process.exit(1);
+      return;
+    }
+    applyDeveloperUpdate(opts.force ?? false);
+  } catch (err) {
+    console.error("Error:", err.message);
+    process.exit(1);
+  }
+}
+var updateCommand = new Command22("update").description(
+  "Update ZAM to the latest release (use `update check` to only check)"
+).option("-y, --yes", "Apply without confirmation").option(
+  "--force",
+  "Update even if the source checkout has uncommitted changes"
+).action(async (opts) => {
+  await applyUpdate(opts);
+}).addCommand(checkCmd);
+
+// src/cli/commands/whoami.ts
+import { Command as Command23 } from "commander";
+var whoamiCommand = new Command23("whoami").description("Show or set the default user identity").option("--set <id>", "Set the default user ID").option("--clear", "Remove the default user ID").option("--json", "Output as JSON").action(async (opts) => {
+  await withDb(async (db) => {
+    if (opts.set) {
+      await setSetting(db, "user.id", opts.set);
+      if (opts.json) {
+        console.log(JSON.stringify({ userId: opts.set }));
+      } else {
+        console.log(`Default user set to: ${opts.set}`);
+      }
+      return;
+    }
+    if (opts.clear) {
+      const deleted = await deleteSetting(db, "user.id");
+      if (opts.json) {
+        console.log(JSON.stringify({ userId: null, cleared: deleted }));
+      } else if (deleted) {
+        console.log("Default user cleared.");
+      } else {
+        console.log("No default user was set.");
+      }
+      return;
+    }
+    const userId = await getSetting(db, "user.id");
+    if (opts.json) {
+      console.log(JSON.stringify({ userId: userId ?? null }));
+      return;
+    }
+    if (userId) {
+      console.log(userId);
+    } else {
+      console.log("No default user set. Use: zam whoami --set <id>");
+    }
+  });
+});
+
+// src/cli/commands/workspace.ts
+import { execFileSync as execFileSync4 } from "child_process";
+import { existsSync as existsSync25, writeFileSync as writeFileSync11 } from "fs";
+import { homedir as homedir13 } from "os";
+import { join as join24, resolve as resolve9 } from "path";
+import { confirm as confirm4, input as input7 } from "@inquirer/prompts";
+import { Command as Command24 } from "commander";
+function runGit2(cwd, args) {
+  try {
+    return execFileSync4("git", args, {
+      cwd,
+      stdio: "pipe",
+      encoding: "utf8"
+    }).trim();
+  } catch (err) {
+    throw new Error(`Git command failed: ${err.message}`);
+  }
 }
-function versionAt(dir) {
-  try {
-    const pkg2 = JSON.parse(
-      readFileSync14(join23(dir, "package.json"), "utf-8")
-    );
-    return pkg2.version ?? "unknown";
-  } catch {
-    return "unknown";
+function ghRepoCreateArgs(repoName, repoVisibility) {
+  return ["repo", "create", repoName, repoVisibility, "--source=.", "--push"];
+}
+function gitRemoteArgs(githubUrl, hasOrigin) {
+  return hasOrigin ? ["remote", "set-url", "origin", githubUrl] : ["remote", "add", "origin", githubUrl];
+}
+var workspaceCommand = new Command24("workspace").description(
+  "Manage your ZAM learning workspace"
+);
+var WORKSPACE_KINDS = [
+  "personal",
+  "team",
+  "family",
+  "community",
+  "organization",
+  "custom"
+];
+var WORKSPACE_SOURCE_CONTROLS = [
+  "github",
+  "azure-devops",
+  "git",
+  "none"
+];
+function parseWorkspaceKind(value) {
+  const kind = (value ?? "custom").toLowerCase();
+  if (WORKSPACE_KINDS.includes(kind)) {
+    return kind;
   }
+  throw new Error(
+    `Invalid workspace kind: ${value}. Use ${WORKSPACE_KINDS.join(", ")}.`
+  );
 }
-async function fetchLatestVersion(repo) {
-  const res = await fetch(
-    `https://api.github.com/repos/${repo}/releases/latest`,
-    {
-      headers: {
-        Accept: "application/vnd.github+json",
-        "User-Agent": "zam-cli"
-      }
-    }
+function parseWorkspaceSourceControl(value) {
+  if (!value) return void 0;
+  const source = value.toLowerCase();
+  if (WORKSPACE_SOURCE_CONTROLS.includes(source)) {
+    return source;
+  }
+  throw new Error(
+    `Invalid source control: ${value}. Use ${WORKSPACE_SOURCE_CONTROLS.join(", ")}.`
   );
-  if (!res.ok) {
+}
+function parseScopes(value) {
+  if (!value) return void 0;
+  const scopes = value.split(",").map((item) => item.trim()).filter(Boolean);
+  return scopes.length > 0 ? scopes : void 0;
+}
+function requireWorkspace(id) {
+  const workspace = getConfiguredWorkspaces().find((item) => item.id === id);
+  if (!workspace) {
     throw new Error(
-      `Could not reach the release server (HTTP ${res.status}). Pass --latest <version> to check offline.`
+      `Workspace "${id}" is not configured. Add it with: zam workspace add ${id} --path <dir>`
     );
   }
-  const data = await res.json();
-  if (!data.tag_name) throw new Error("No published release found yet.");
-  return data.tag_name;
+  return workspace;
 }
-function render2(decision) {
-  if (!decision.updateAvailable) {
-    console.log(
-      `${C4.green}\u2713${C4.reset} ZAM is up to date (${C4.cyan}${decision.currentVersion}${C4.reset}).`
-    );
-    return;
+function formatLinkHealth(id, health) {
+  switch (health) {
+    case "healthy":
+      return "ok";
+    case "needs-repair":
+      return `needs repair \u2014 run: zam workspace setup ${id}`;
+    case "unmanaged":
+      return `unmanaged skill dir \u2014 run: zam workspace setup ${id} --force`;
   }
-  console.log(
-    `${C4.yellow}\u2191${C4.reset} ${C4.bold}Update available${C4.reset}: ${C4.dim}${decision.currentVersion}${C4.reset} \u2192 ${C4.cyan}${decision.latestVersion}${C4.reset}`
+}
+workspaceCommand.command("list").description("List configured ZAM workspaces").option("--json", "Output as JSON").action((opts) => {
+  const workspaces = getConfiguredWorkspaces();
+  const agents = parseSetupAgents();
+  const linkHealth = Object.fromEntries(
+    workspaces.filter((workspace) => existsSync25(workspace.path)).map((workspace) => [
+      workspace.id,
+      summarizeSkillLinkHealth(inspectSkillLinks(workspace.path, agents))
+    ])
   );
-  console.log(`  ${decision.reason}`);
-  if (decision.action === "run-command" || decision.action === "inform") {
-    console.log(`  Run: ${C4.cyan}${decision.command}${C4.reset}`);
-  } else if (decision.action === "self-update") {
+  if (opts.json) {
+    console.log(JSON.stringify({ workspaces, linkHealth }, null, 2));
+    return;
+  }
+  console.log("Configured ZAM workspaces:\n");
+  if (workspaces.length === 0) {
     console.log(
-      `  ${C4.dim}The desktop app can apply this update for you.${C4.reset}`
+      "  (none) \u2014 add one: zam workspace add personal --path <dir>"
     );
+    return;
   }
-}
-var checkCmd = new Command23("check").description("Check whether a newer ZAM has been released").option(
-  "--latest <version>",
-  "Compare against this version instead of fetching"
-).option("--channel <channel>", "Override the detected install channel").option("--json", "Output as JSON").action(
-  async (opts) => {
-    try {
-      if (opts.channel && !CHANNELS.includes(opts.channel)) {
-        console.error(
-          `Invalid --channel: ${opts.channel}. Use ${CHANNELS.join(", ")}.`
-        );
-        process.exit(1);
-      }
-      const current = currentVersion();
-      const latest = opts.latest ?? await fetchLatestVersion(GITHUB_REPO);
-      const channel = opts.channel ?? getInstallChannel();
-      const decision = decideUpdate({
-        currentVersion: current,
-        latestVersion: latest,
-        channel
-      });
-      if (opts.json) {
-        console.log(JSON.stringify(decision, null, 2));
-        return;
-      }
-      render2(decision);
-    } catch (err) {
-      console.error("Error:", err.message);
+  for (const workspace of workspaces) {
+    const label = workspace.label ? ` (${workspace.label})` : "";
+    console.log(`  ${workspace.id}${label}`);
+    console.log(`      kind: ${workspace.kind}`);
+    console.log(`      path: ${workspace.path}`);
+    if (workspace.sourceControl) {
+      console.log(`      source: ${workspace.sourceControl}`);
+    }
+    if (workspace.knowledgeScopes?.length) {
+      console.log(`      scopes: ${workspace.knowledgeScopes.join(", ")}`);
+    }
+    const health = linkHealth[workspace.id];
+    if (health) {
+      console.log(`      links: ${formatLinkHealth(workspace.id, health)}`);
+    }
+  }
+});
+workspaceCommand.command("add <id>").description("Register an existing directory as a ZAM workspace").requiredOption("--path <dir>", "Existing workspace/repository directory").option(
+  "--kind <kind>",
+  `Workspace kind (${WORKSPACE_KINDS.join(" | ")})`,
+  "custom"
+).option("--label <label>", "Human-readable label").option(
+  "--source-control <provider>",
+  `Source-control provider (${WORKSPACE_SOURCE_CONTROLS.join(" | ")})`
+).option("--scopes <list>", "Comma-separated knowledge scopes").option("--default-agent <id>", "Default agent harness for this workspace").action((id, opts) => {
+  try {
+    const path = resolve9(String(opts.path));
+    if (!existsSync25(path)) {
+      console.error(`Workspace path does not exist: ${path}`);
       process.exit(1);
     }
+    const workspace = {
+      id,
+      kind: parseWorkspaceKind(opts.kind),
+      path,
+      ...opts.label ? { label: opts.label } : {},
+      ...opts.sourceControl ? { sourceControl: parseWorkspaceSourceControl(opts.sourceControl) } : {},
+      ...parseScopes(opts.scopes) ? { knowledgeScopes: parseScopes(opts.scopes) } : {},
+      ...opts.defaultAgent ? { defaultAgent: opts.defaultAgent } : {}
+    };
+    wireSkills(path, parseSetupAgents());
+    upsertConfiguredWorkspace(workspace);
+    console.log(`Registered and linked workspace "${id}" at ${path}.`);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
   }
-);
-function findSourceRepo() {
-  let dir = realpathSync2(dirname9(fileURLToPath4(import.meta.url)));
-  let parent = dirname9(dir);
-  while (parent !== dir) {
-    if (existsSync24(join23(dir, ".git"))) return dir;
-    dir = parent;
-    parent = dirname9(dir);
+});
+workspaceCommand.command("remove <id>").description("Unregister a ZAM workspace without deleting its files").action((id) => {
+  const existing = getConfiguredWorkspaces().find((item) => item.id === id);
+  if (!existing) {
+    console.error(`Workspace "${id}" is not configured.`);
+    process.exit(1);
   }
-  return existsSync24(join23(dir, ".git")) ? dir : null;
-}
-function runGit2(cwd, args, capture) {
-  const res = spawnSync2("git", args, {
-    cwd,
-    stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
-    encoding: "utf8"
-  });
-  return { ok: res.status === 0, out: (res.stdout ?? "").trim() };
-}
-function runNpm2(args, cwd) {
-  const res = spawnSync2("npm", args, {
-    cwd,
-    stdio: "inherit",
-    shell: process.platform === "win32"
-  });
-  return res.status ?? 1;
-}
-function runShell(command) {
-  const res = spawnSync2(command, { stdio: "inherit", shell: true });
-  return res.status === 0;
-}
-function applyDeveloperUpdate(force) {
-  if (!hasCommand("git")) {
-    console.error(`${C4.red}\u2717${C4.reset} git was not found on PATH.`);
+  removeConfiguredWorkspace(id);
+  console.log(
+    `Unregistered workspace "${id}". Files in ${existing.path} were not changed.`
+  );
+});
+workspaceCommand.command("setup <id>").description("Install ZAM skills into a configured workspace").option(
+  "--agents <list>",
+  "comma-separated agents to wire: all, claude, copilot, codex, agent"
+).option(
+  "--force",
+  "overwrite existing skill files and refresh ZAM blocks",
+  false
+).option(
+  "--dry-run",
+  "show what would be written without changing files",
+  false
+).action((id, opts) => {
+  try {
+    const workspace = requireWorkspace(id);
+    const agents = parseSetupAgents(opts.agents);
+    console.log(
+      `Setting up workspace "${workspace.id}" in ${workspace.path}${opts.dryRun ? " (dry run)" : ""}
+`
+    );
+    wireSkills(workspace.path, agents, {
+      force: Boolean(opts.force),
+      dryRun: Boolean(opts.dryRun)
+    });
+    if (agents.has("claude")) {
+      writeClaudeMd(false, workspace.path, {
+        dryRun: Boolean(opts.dryRun),
+        updateExisting: true
+      });
+    }
+    if (agents.has("codex") || agents.has("agent")) {
+      writeAgentsMd(false, workspace.path, {
+        dryRun: Boolean(opts.dryRun),
+        updateExisting: true
+      });
+    }
+    if (agents.has("copilot")) {
+      writeCopilotInstructions(workspace.path, {
+        dryRun: Boolean(opts.dryRun),
+        updateExisting: true
+      });
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
     process.exit(1);
   }
-  const src = findSourceRepo();
-  if (!src) {
+});
+workspaceCommand.command("publish").description("Publish your local workspace sandbox to GitHub").action(async () => {
+  let db;
+  let workspaceDir = "";
+  try {
+    db = await openDatabase();
+    workspaceDir = (await ensureActiveWorkspace(db)).path;
+    await db.close();
+  } catch {
+    await db?.close();
+  }
+  if (!workspaceDir) {
     console.error(
-      `${C4.red}\u2717${C4.reset} Could not locate the ZAM source checkout to update.`
+      "\x1B[31m\u2717 No active workspace configured. Please run `zam init` first.\x1B[0m"
     );
     process.exit(1);
   }
-  const status = runGit2(src, ["status", "--porcelain"], true);
-  if (status.ok && status.out && !force) {
+  if (!existsSync25(workspaceDir)) {
     console.error(
-      `${C4.red}\u2717${C4.reset} The source checkout has uncommitted changes:
-${status.out}
-Commit or stash them, or re-run with ${C4.cyan}--force${C4.reset}.`
+      `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
     );
     process.exit(1);
   }
-  console.log(
-    `${C4.dim}\u2192 git pull --ff-only${C4.reset}  ${C4.dim}(${src})${C4.reset}`
-  );
-  if (!runGit2(src, ["pull", "--ff-only"], false).ok) {
+  console.log(`
+Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
+  if (!hasCommand("git")) {
     console.error(
-      `${C4.red}\u2717${C4.reset} git pull failed \u2014 the branch may have diverged or you are offline. Resolve it manually, then retry.`
+      "\x1B[31m\u2717 Git command was not found on this system. Please install Git first.\x1B[0m"
     );
     process.exit(1);
   }
-  console.log(`${C4.dim}\u2192 npm install${C4.reset}`);
-  if (runNpm2(["install"], src) !== 0) {
-    console.error(`${C4.red}\u2717${C4.reset} npm install failed.`);
-    process.exit(1);
+  const gitignorePath = join24(workspaceDir, ".gitignore");
+  if (!existsSync25(gitignorePath)) {
+    writeFileSync11(
+      gitignorePath,
+      "node_modules/\n.agent/\n.agents/\n.claude/\n.gemini/\n.goose/\n*.log\n",
+      "utf8"
+    );
   }
-  console.log(`${C4.dim}\u2192 npm run build${C4.reset}`);
-  if (runNpm2(["run", "build"], src) !== 0) {
-    console.error(`${C4.red}\u2717${C4.reset} Build failed.`);
-    process.exit(1);
+  const hasGitRepo = existsSync25(join24(workspaceDir, ".git"));
+  if (!hasGitRepo) {
+    console.log("Initializing local Git repository...");
+    runGit2(workspaceDir, ["init", "-b", "main"]);
+    runGit2(workspaceDir, ["add", "."]);
+    runGit2(workspaceDir, [
+      "commit",
+      "-m",
+      "chore: initial workspace sandbox bootstrap"
+    ]);
+    console.log("\x1B[32m\u2713 Local Git repository initialized.\x1B[0m");
+  } else {
+    console.log("Git repository is already initialized.");
   }
-  console.log(`${C4.dim}\u2192 zam setup --force${C4.reset}`);
-  const setup = spawnSync2(
-    process.execPath,
-    [join23(src, "dist", "cli", "index.js"), "setup", "--force"],
-    { cwd: process.cwd(), stdio: "inherit" }
-  );
-  if (setup.status !== 0) {
-    console.warn(
-      `${C4.yellow}\u26A0${C4.reset} Skill refresh reported a problem \u2014 run '${C4.cyan}zam setup --force${C4.reset}' here manually.`
-    );
+  const repoName = await input7({
+    message: "Choose a name for your GitHub repository:",
+    default: "zam-personal"
+  });
+  const isPrivate = await confirm4({
+    message: "Should the repository be private?",
+    default: true
+  });
+  const repoVisibility = isPrivate ? "--private" : "--public";
+  if (hasCommand("gh")) {
+    console.log("GitHub CLI detected! Automating repository creation...");
+    const proceedGh = await confirm4({
+      message: "Would you like ZAM to create the repository using the GitHub CLI?",
+      default: true
+    });
+    if (proceedGh) {
+      try {
+        console.log(`Creating GitHub repository ${repoName}...`);
+        execFileSync4("gh", ghRepoCreateArgs(repoName, repoVisibility), {
+          cwd: workspaceDir,
+          stdio: "inherit"
+        });
+        console.log(
+          "\n\x1B[32m\u2713 Successfully published workspace to GitHub!\x1B[0m"
+        );
+        process.exit(0);
+      } catch (err) {
+        console.warn(
+          `\x1B[33m\u26A0 GitHub CLI creation failed: ${err.message}\x1B[0m`
+        );
+      }
+    }
   }
   console.log(
-    `
-${C4.green}\u2713${C4.reset} Updated to ${C4.cyan}${versionAt(src)}${C4.reset}. Restart your agent client (e.g. Claude Code) to load the refreshed ${C4.cyan}/zam${C4.reset} skill.`
+    "\n\x1B[1mPlease create the repository manually on GitHub:\x1B[0m"
   );
-}
-async function applyUpdate(opts) {
-  try {
-    const current = currentVersion();
-    const latest = await fetchLatestVersion(GITHUB_REPO);
-    const channel = getInstallChannel();
-    const decision = decideUpdate({
-      currentVersion: current,
-      latestVersion: latest,
-      channel
-    });
-    if (!decision.updateAvailable) {
+  console.log("  1. Go to https://github.com/new");
+  console.log(`  2. Name it exactly: \x1B[36m${repoName}\x1B[0m`);
+  console.log(
+    `  3. Choose \x1B[36m${isPrivate ? "Private" : "Public"}\x1B[0m`
+  );
+  console.log(
+    "  4. Do NOT initialize it with README, .gitignore, or license"
+  );
+  console.log("  5. Click 'Create repository'\n");
+  const githubUrl = await input7({
+    message: "Paste the repository Git URL (e.g. git@github.com:user/repo.git):"
+  });
+  if (githubUrl) {
+    try {
+      console.log("Linking remote repository and pushing...");
+      let hasOrigin = false;
+      try {
+        runGit2(workspaceDir, ["remote", "get-url", "origin"]);
+        hasOrigin = true;
+      } catch {
+      }
+      runGit2(workspaceDir, gitRemoteArgs(githubUrl, hasOrigin));
+      runGit2(workspaceDir, ["push", "-u", "origin", "main"]);
       console.log(
-        `${C4.green}\u2713${C4.reset} ZAM is up to date (${C4.cyan}${current}${C4.reset}).`
+        "\x1B[32m\u2713 Successfully linked and pushed to GitHub!\x1B[0m"
+      );
+    } catch (err) {
+      console.error(
+        `\x1B[31m\u2717 Push failed: ${err.message}\x1B[0m`
       );
-      return;
-    }
-    console.log(
-      `${C4.yellow}\u2191${C4.reset} ${C4.bold}Update available${C4.reset}: ${C4.dim}${current}${C4.reset} \u2192 ${C4.cyan}${latest}${C4.reset} ${C4.dim}(${channel} install)${C4.reset}`
-    );
-    for (const step of planUpdate(decision)) {
-      console.log(`  ${C4.dim}\u2022${C4.reset} ${step.label}`);
-    }
-    if (channel === "direct") {
       console.log(
-        `
-${C4.dim}This install updates through the desktop app's signed updater \u2014 open ZAM Desktop to install ${latest}.${C4.reset}`
+        "You can push manually later using: git push -u origin main"
       );
-      return;
-    }
-    if (!opts.yes) {
-      const ok = await confirm4({
-        message: "Apply this update?",
-        default: true
-      });
-      if (!ok) {
-        console.log("Aborted.");
-        return;
-      }
     }
-    console.log();
-    if (channel === "winget" || channel === "homebrew") {
-      if (!decision.command || !runShell(decision.command)) process.exit(1);
+  }
+});
+workspaceCommand.command("data-dir").description("Print the ZAM data directory (database, credentials, config)").option("--json", "Output as JSON").action((opts) => {
+  const dir = join24(homedir13(), ".zam");
+  console.log(opts.json ? JSON.stringify({ dataDir: dir }) : dir);
+});
+workspaceCommand.command("backup").description("Back up the local ZAM database into your workspace").option(
+  "--dir <path>",
+  "Target directory (default: workspace dir, else ~/Documents/zam)"
+).option("--json", "Output as JSON").action(async (opts) => {
+  const target = getDatabaseTargetInfo();
+  if (target.kind !== "local") {
+    const reason = `The database is ${target.kind} (${target.location}); file backup applies only to a local database \u2014 your Turso remote is already the cloud backup.`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, reason }));
       return;
     }
-    applyDeveloperUpdate(opts.force ?? false);
-  } catch (err) {
-    console.error("Error:", err.message);
+    console.error(`\x1B[33m\u26A0 ${reason}\x1B[0m`);
     process.exit(1);
   }
-}
-var updateCommand = new Command23("update").description(
-  "Update ZAM to the latest release (use `update check` to only check)"
-).option("-y, --yes", "Apply without confirmation").option(
-  "--force",
-  "Update even if the source checkout has uncommitted changes"
-).action(async (opts) => {
-  await applyUpdate(opts);
-}).addCommand(checkCmd);
-
-// src/cli/commands/whoami.ts
-import { Command as Command24 } from "commander";
-var whoamiCommand = new Command24("whoami").description("Show or set the default user identity").option("--set <id>", "Set the default user ID").option("--clear", "Remove the default user ID").option("--json", "Output as JSON").action(async (opts) => {
-  await withDb(async (db) => {
-    if (opts.set) {
-      await setSetting(db, "user.id", opts.set);
-      if (opts.json) {
-        console.log(JSON.stringify({ userId: opts.set }));
-      } else {
-        console.log(`Default user set to: ${opts.set}`);
-      }
-      return;
-    }
-    if (opts.clear) {
-      const deleted = await deleteSetting(db, "user.id");
-      if (opts.json) {
-        console.log(JSON.stringify({ userId: null, cleared: deleted }));
-      } else if (deleted) {
-        console.log("Default user cleared.");
-      } else {
-        console.log("No default user was set.");
-      }
-      return;
-    }
-    const userId = await getSetting(db, "user.id");
+  let db;
+  try {
+    db = await openDatabase();
+    const workspaceDir = opts.dir || (await ensureActiveWorkspace(db)).path;
+    const dest = await backupDatabaseTo(db, workspaceDir);
     if (opts.json) {
-      console.log(JSON.stringify({ userId: userId ?? null }));
-      return;
+      console.log(JSON.stringify({ ok: true, path: dest }));
+    } else {
+      console.log(`\x1B[32m\u2713 Database backed up to ${dest}\x1B[0m`);
     }
-    if (userId) {
-      console.log(userId);
+  } catch (err) {
+    const reason = err.message;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, reason }));
     } else {
-      console.log("No default user set. Use: zam whoami --set <id>");
+      console.error(`\x1B[31m\u2717 Backup failed: ${reason}\x1B[0m`);
     }
-  });
+    process.exit(1);
+  } finally {
+    await db?.close();
+  }
 });
 
 // src/cli/index.ts
 var __dirname = dirname10(fileURLToPath5(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync15(join24(__dirname, "..", "..", "package.json"), "utf-8")
+  readFileSync15(join25(__dirname, "..", "..", "package.json"), "utf-8")
 );
 var program = new Command25();
 program.name("zam").description(