zam-core 0.4.0 → 0.4.2

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 
 // src/cli/index.ts
 import { readFileSync as readFileSync14 } from "fs";
-import { dirname as dirname10, join as join22 } from "path";
+import { dirname as dirname10, join as join23 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 import { Command as Command24 } from "commander";
 
@@ -4847,6 +4847,37 @@ function decideUpdate(input8) {
       };
   }
 }
+function planUpdate(decision) {
+  if (!decision.updateAvailable) return [];
+  switch (decision.channel) {
+    case "developer":
+      return [
+        { kind: "git-pull", label: "Pull the latest source" },
+        { kind: "npm-install", label: "Install dependencies" },
+        { kind: "npm-build", label: "Rebuild the CLI" },
+        {
+          kind: "distribute-skills",
+          label: "Refresh skill files (zam setup --force)"
+        }
+      ];
+    case "winget":
+    case "homebrew":
+      return [
+        {
+          kind: "run-command",
+          label: `Update via ${decision.channel}`,
+          command: decision.command
+        }
+      ];
+    case "direct":
+      return [
+        {
+          kind: "self-update",
+          label: "Apply the signed update via the desktop app"
+        }
+      ];
+  }
+}
 
 // src/cli/commands/agent.ts
 var C = {
@@ -4901,10 +4932,10 @@ var agentCommand = new Command("agent").description("Provision and inspect the a
 
 // src/cli/commands/bridge.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import { randomBytes } from "crypto";
+import { randomBytes as randomBytes2 } from "crypto";
 import { readdirSync as readdirSync2, readFileSync as readFileSync10, rmSync as rmSync2 } from "fs";
-import { homedir as homedir8, tmpdir } from "os";
-import { join as join12 } from "path";
+import { homedir as homedir8, tmpdir as tmpdir2 } from "os";
+import { join as join13 } from "path";
 import { Command as Command2 } from "commander";
 
 // src/cli/llm/client.ts
@@ -5267,8 +5298,8 @@ async function startLocalRunner(url, model, locale) {
       process.stdout.write("\n");
       console.log(`\x1B[33m${t(locale, "wait_warning")}\x1B[0m`);
       console.log(`\x1B[2m${t(locale, "wait_info")}\x1B[0m`);
-      const { confirm: confirm4 } = await import("@inquirer/prompts");
-      const keepWaiting = await confirm4({
+      const { confirm: confirm5 } = await import("@inquirer/prompts");
+      const keepWaiting = await confirm5({
         message: t(locale, "keep_waiting_llm"),
         default: true
       }).catch(() => false);
@@ -5412,8 +5443,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
       }
       console.log(`
 \x1B[33m${t(locale, "local_ai_working")}\x1B[0m`);
-      const { confirm: confirm4 } = await import("@inquirer/prompts");
-      const keepWaiting = await confirm4({
+      const { confirm: confirm5 } = await import("@inquirer/prompts");
+      const keepWaiting = await confirm5({
         message: t(locale, "keep_waiting"),
         default: true
       }).catch(() => false);
@@ -5467,7 +5498,9 @@ async function ensureHighQualityQuestion(db, token) {
 
 // src/cli/llm/vision.ts
 import { readFileSync as readFileSync9 } from "fs";
-import { basename as basename2 } from "path";
+import { randomBytes } from "crypto";
+import { tmpdir } from "os";
+import { basename as basename2, join as join12 } from "path";
 var LANGUAGE_NAMES2 = {
   en: "English",
   de: "German",
@@ -5500,15 +5533,61 @@ async function observeUiSnapshotViaLLM(db, input8) {
       "Vision observation is disabled in settings (llm.vision.enabled)"
     );
   }
-  const imageBytes = readFileSync9(input8.imagePath);
-  const imageUrl = `data:image/png;base64,${imageBytes.toString("base64")}`;
+  const imageUrls = [];
+  const isVideo = /\.(mp4|mov|m4v|avi|mkv|webm)$/i.test(input8.imagePath);
+  if (isVideo) {
+    const { mkdirSync: mkdirSync12, readdirSync: readdirSync3, rmSync: rmSync3 } = await import("fs");
+    const { execSync: execSync7 } = await import("child_process");
+    const tempDir = join12(tmpdir(), `zam-frames-${randomBytes(4).toString("hex")}`);
+    mkdirSync12(tempDir, { recursive: true });
+    try {
+      execSync7(
+        `ffmpeg -i "${input8.imagePath}" -vf "fps=1/3,scale=1280:-1" -vsync vfr "${tempDir}/frame_%03d.png"`,
+        { stdio: "ignore" }
+      );
+      let files = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
+      if (files.length === 0) {
+        execSync7(
+          `ffmpeg -i "${input8.imagePath}" -vframes 1 "${tempDir}/frame_001.png"`,
+          { stdio: "ignore" }
+        );
+        files = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
+      }
+      let sampledFiles = files;
+      if (files.length > 12) {
+        const step = (files.length - 1) / 11;
+        sampledFiles = [];
+        for (let i = 0; i < 12; i++) {
+          const index = Math.round(i * step);
+          sampledFiles.push(files[index]);
+        }
+      }
+      for (const file of sampledFiles) {
+        const bytes = readFileSync9(join12(tempDir, file));
+        imageUrls.push(`data:image/png;base64,${bytes.toString("base64")}`);
+      }
+    } finally {
+      try {
+        rmSync3(tempDir, { recursive: true, force: true });
+      } catch {
+      }
+    }
+  } else {
+    const imageBytes = readFileSync9(input8.imagePath);
+    const ext = input8.imagePath.split(".").pop()?.toLowerCase();
+    const mime = ext === "jpg" || ext === "jpeg" ? "image/jpeg" : "image/png";
+    imageUrls.push(`data:${mime};base64,${imageBytes.toString("base64")}`);
+  }
+  if (imageUrls.length === 0) {
+    throw new Error("No image data available for vision analysis");
+  }
   const model = input8.model ?? cfg.model;
   const content = await requestVisionDraft({
     url: cfg.url,
     apiKey: cfg.apiKey || DEFAULT_LLM_API_KEY,
     model,
     locale: cfg.locale,
-    imageUrl,
+    imageUrls,
     input: input8
   });
   let draft;
@@ -5558,17 +5637,22 @@ async function requestVisionDraft(args) {
             content: [
               {
                 type: "text",
-                text: `Observe this Windows application snapshot for a learning session.
+                text: args.imageUrls.length > 1 ? `Observe this sequence of Windows/macOS application snapshots showing a task performed over time.
+Application process: ${args.input.application.processName}
+Window title: ${args.input.application.windowTitle ?? "(unknown)"}
+
+Return this JSON draft only:
+${schema}` : `Observe this Windows/macOS application snapshot for a learning session.
 Application process: ${args.input.application.processName}
 Window title: ${args.input.application.windowTitle ?? "(unknown)"}
 
 Return this JSON draft only:
 ${schema}`
               },
-              {
+              ...args.imageUrls.map((url) => ({
                 type: "image_url",
-                image_url: { url: args.imageUrl }
-              }
+                image_url: { url }
+              }))
             ]
           }
         ],
@@ -6208,7 +6292,7 @@ bridgeCommand.command("discover-skills").description(
   "20"
 ).action(async (opts) => {
   try {
-    const monitorDir = join12(homedir8(), ".zam", "monitor");
+    const monitorDir = join13(homedir8(), ".zam", "monitor");
     let files;
     try {
       files = readdirSync2(monitorDir).filter((f) => f.endsWith(".jsonl"));
@@ -6221,7 +6305,7 @@ bridgeCommand.command("discover-skills").description(
       return;
     }
     const limit = Number(opts.limit);
-    const sorted = files.map((f) => ({ name: f, path: join12(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
+    const sorted = files.map((f) => ({ name: f, path: join13(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", "");
@@ -6301,8 +6385,8 @@ bridgeCommand.command("get-observations").description("Read UI observer reports
   }
 });
 bridgeCommand.command("observe-ui-snapshot").description(
-  "Analyze a captured UI snapshot with the configured vision LLM (JSON)"
-).requiredOption("--session <id>", "Observer session ID").requiredOption("--sequence <n>", "Monotonic observation sequence number").requiredOption("--image <path>", "PNG snapshot path").requiredOption("--observed-from <iso>", "Observation window start time").requiredOption("--observed-to <iso>", "Observation window end time").requiredOption("--process-name <name>", "Observed application process name").option("--process-id <n>", "Observed application process ID").option("--window-title <title>", "Observed window title").option("--evidence-ref <ref>", "Evidence reference to put in the report").option("--model <model>", "Override configured LLM model for this request").option("--max-tokens <n>", "Model response token budget").option("--timeout <ms>", "Hard request timeout in milliseconds").option("--redacted", "Mark the snapshot evidence as redacted").option("--write-log", "Append the generated report to the session JSONL").action(async (opts) => {
+  "Analyze a captured UI snapshot or video recording with the configured vision LLM (JSON)"
+).requiredOption("--session <id>", "Observer session ID").requiredOption("--sequence <n>", "Monotonic observation sequence number").requiredOption("--image <path>", "PNG snapshot or video recording path").requiredOption("--observed-from <iso>", "Observation window start time").requiredOption("--observed-to <iso>", "Observation window end time").requiredOption("--process-name <name>", "Observed application process name").option("--process-id <n>", "Observed application process ID").option("--window-title <title>", "Observed window title").option("--evidence-ref <ref>", "Evidence reference to put in the report").option("--model <model>", "Override configured LLM model for this request").option("--max-tokens <n>", "Model response token budget").option("--timeout <ms>", "Hard request timeout in milliseconds").option("--redacted", "Mark the snapshot evidence as redacted").option("--write-log", "Append the generated report to the session JSONL").action(async (opts) => {
   const sequence = parseNonNegativeIntegerOption("sequence", opts.sequence);
   const processId = opts.processId === void 0 ? void 0 : parseNonNegativeIntegerOption("process-id", opts.processId);
   const maxTokens = opts.maxTokens === void 0 ? void 0 : parseNonNegativeIntegerOption("max-tokens", opts.maxTokens);
@@ -6723,7 +6807,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
         return;
       }
     }
-    const outputPath = opts.image ?? opts.output ?? join12(tmpdir(), `zam-capture-${randomBytes(4).toString("hex")}.png`);
+    const outputPath = opts.image ?? opts.output ?? join13(tmpdir2(), `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, {
@@ -6767,6 +6851,177 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
     });
   });
 });
+bridgeCommand.command("start-recording").description("Start screen recording in the background (macOS only) (JSON)").requiredOption("--session <id>", "ZAM session ID").option("--output <path>", "Video output path").action(async (opts) => {
+  const platform = process.platform;
+  if (platform !== "darwin") {
+    jsonOut2({
+      sessionId: opts.session,
+      started: false,
+      error: "Screen recording is only supported on macOS (darwin)"
+    });
+    return;
+  }
+  const sessionId = opts.session;
+  const statePath = join13(tmpdir2(), `zam-recording-${sessionId}.json`);
+  const outputPath = opts.output ?? join13(tmpdir2(), `zam-recording-${sessionId}.mov`);
+  const { existsSync: existsSync22, writeFileSync: writeFileSync12, openSync, closeSync } = await import("fs");
+  if (existsSync22(statePath)) {
+    jsonOut2({
+      sessionId,
+      started: false,
+      error: `Recording is already active for session ${sessionId}`
+    });
+    return;
+  }
+  const logPath = join13(tmpdir2(), `zam-recording-${sessionId}.log`);
+  let logFd;
+  try {
+    logFd = openSync(logPath, "w");
+  } catch (e) {
+    jsonOut2({
+      sessionId,
+      started: false,
+      error: `Failed to open log file at ${logPath}: ${e.message}`
+    });
+    return;
+  }
+  const { spawn: spawn3 } = await import("child_process");
+  const child = spawn3(
+    "ffmpeg",
+    [
+      "-y",
+      "-f",
+      "avfoundation",
+      "-r",
+      "5",
+      "-i",
+      "0",
+      "-pix_fmt",
+      "yuv420p",
+      outputPath
+    ],
+    {
+      detached: true,
+      stdio: ["pipe", logFd, logFd]
+    }
+  );
+  try {
+    closeSync(logFd);
+  } catch {
+  }
+  child.unref();
+  if (child.pid) {
+    writeFileSync12(
+      statePath,
+      JSON.stringify({
+        pid: child.pid,
+        outputPath,
+        startedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }),
+      "utf8"
+    );
+    jsonOut2({
+      sessionId,
+      started: true,
+      outputPath,
+      pid: child.pid
+    });
+  } else {
+    jsonOut2({
+      sessionId,
+      started: false,
+      error: "Failed to spawn ffmpeg process"
+    });
+  }
+});
+bridgeCommand.command("stop-recording").description(
+  "Stop active screen recording and apply idle-frame compression (macOS only) (JSON)"
+).requiredOption("--session <id>", "ZAM session ID").action(async (opts) => {
+  const platform = process.platform;
+  if (platform !== "darwin") {
+    jsonOut2({
+      sessionId: opts.session,
+      stopped: false,
+      error: "Screen recording is only supported on macOS (darwin)"
+    });
+    return;
+  }
+  const sessionId = opts.session;
+  const statePath = join13(tmpdir2(), `zam-recording-${sessionId}.json`);
+  const { existsSync: existsSync22, readFileSync: readFileSync15, rmSync: rmSync3 } = await import("fs");
+  if (!existsSync22(statePath)) {
+    jsonOut2({
+      sessionId,
+      stopped: false,
+      error: `No active recording found for session ${sessionId}`
+    });
+    return;
+  }
+  const state = JSON.parse(readFileSync15(statePath, "utf8"));
+  const { pid, outputPath } = state;
+  try {
+    process.kill(pid, "SIGINT");
+  } catch (e) {
+  }
+  const isProcessRunning = (pId) => {
+    try {
+      process.kill(pId, 0);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  };
+  let attempts = 0;
+  while (isProcessRunning(pid) && attempts < 20) {
+    await new Promise((resolve5) => setTimeout(resolve5, 250));
+    attempts++;
+  }
+  if (isProcessRunning(pid)) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch (e) {
+    }
+  }
+  try {
+    rmSync3(statePath, { force: true });
+  } catch {
+  }
+  if (!existsSync22(outputPath)) {
+    jsonOut2({
+      sessionId,
+      stopped: false,
+      error: `Recording file not found at ${outputPath}`
+    });
+    return;
+  }
+  const decimatedPath = outputPath.replace(/\.[^.]+$/, "-decimated.mp4");
+  const { execSync: execSync7 } = await import("child_process");
+  try {
+    execSync7(
+      `ffmpeg -y -i "${outputPath}" -vf "mpdecimate,setpts=N/FRAME_RATE/TB" -an -pix_fmt yuv420p "${decimatedPath}"`,
+      { stdio: "ignore" }
+    );
+  } catch (ffmpegErr) {
+    jsonOut2({
+      sessionId,
+      stopped: true,
+      videoPath: outputPath,
+      decimated: false,
+      warning: `mpdecimate post-processing failed: ${ffmpegErr.message}`
+    });
+    return;
+  }
+  try {
+    rmSync3(outputPath, { force: true });
+  } catch {
+  }
+  jsonOut2({
+    sessionId,
+    stopped: true,
+    videoPath: decimatedPath,
+    decimated: true
+  });
+});
 bridgeCommand.command("get-observer-policy").description(
   "Report the resolved observer policy so an agent can check before capturing (JSON)"
 ).action(async () => {
@@ -7475,18 +7730,18 @@ async function setupTurso(urlArg, tokenArg, mode) {
 // src/cli/commands/git-sync.ts
 import { execSync as execSync4 } from "child_process";
 import { chmodSync as chmodSync2, existsSync as existsSync13, writeFileSync as writeFileSync6 } from "fs";
-import { join as join13 } from "path";
+import { join as join14 } from "path";
 import { Command as Command5 } from "commander";
 function installHook2() {
-  const gitDir = join13(process.cwd(), ".git");
+  const gitDir = join14(process.cwd(), ".git");
   if (!existsSync13(gitDir)) {
     console.error(
       "Error: Current directory is not the root of a Git repository."
     );
     process.exit(1);
   }
-  const hooksDir = join13(gitDir, "hooks");
-  const hookPath = join13(hooksDir, "post-commit");
+  const hooksDir = join14(gitDir, "hooks");
+  const hookPath = join14(hooksDir, "post-commit");
   const hookContent = `#!/bin/sh
 # ZAM Spaced Repetition Auto-Stale Hook
 # Triggered automatically on git commits to decay modified concept cards.
@@ -7782,7 +8037,7 @@ goalCommand.command("status <slug> <status>").description("Update a goal's statu
 // src/cli/commands/init.ts
 import { existsSync as existsSync15, mkdirSync as mkdirSync9, writeFileSync as writeFileSync7 } from "fs";
 import { homedir as homedir9 } from "os";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 import { confirm, input as input3 } from "@inquirer/prompts";
 import { Command as Command7 } from "commander";
 var HOME2 = homedir9();
@@ -7790,10 +8045,10 @@ function printLine(char = "\u2550", len = 60, color = "\x1B[36m") {
   console.log(`${color}${char.repeat(len)}\x1B[0m`);
 }
 function bootstrapSandboxWorkspace(workspaceDir) {
-  mkdirSync9(join14(workspaceDir, "beliefs"), { recursive: true });
-  mkdirSync9(join14(workspaceDir, "goals"), { recursive: true });
-  mkdirSync9(join14(workspaceDir, "skills"), { recursive: true });
-  const worldviewFile = join14(workspaceDir, "beliefs", "worldview.md");
+  mkdirSync9(join15(workspaceDir, "beliefs"), { recursive: true });
+  mkdirSync9(join15(workspaceDir, "goals"), { recursive: true });
+  mkdirSync9(join15(workspaceDir, "skills"), { recursive: true });
+  const worldviewFile = join15(workspaceDir, "beliefs", "worldview.md");
   if (!existsSync15(worldviewFile)) {
     writeFileSync7(
       worldviewFile,
@@ -7807,7 +8062,7 @@ Here, I declare the core concepts and principles I want to master.
       "utf8"
     );
   }
-  const goalsFile = join14(workspaceDir, "goals", "goals.md");
+  const goalsFile = join15(workspaceDir, "goals", "goals.md");
   if (!existsSync15(goalsFile)) {
     writeFileSync7(
       goalsFile,
@@ -7831,7 +8086,7 @@ var initCommand = new Command7("init").description("Launch the guided interactiv
   );
   printLine();
   console.log("\n\x1B[1m[1/5] Setting up Local Workspace Sandbox\x1B[0m");
-  const defaultWorkspace = join14(HOME2, "Documents", "zam");
+  const defaultWorkspace = join15(HOME2, "Documents", "zam");
   const workspacePath = await input3({
     message: "Choose your ZAM workspace directory:",
     default: defaultWorkspace
@@ -8530,8 +8785,8 @@ ${"\u2550".repeat(50)}`);
 // src/cli/commands/monitor.ts
 import { execFileSync as execFileSync3, execSync as execSync5 } from "child_process";
 import { unlinkSync, writeFileSync as writeFileSync8 } from "fs";
-import { tmpdir as tmpdir2 } from "os";
-import { basename as basename3, join as join15 } from "path";
+import { tmpdir as tmpdir3 } from "os";
+import { basename as basename3, join as join16 } from "path";
 import { Command as Command9 } from "commander";
 function isPowerShellShell(shell) {
   return shell === "pwsh" || shell === "powershell";
@@ -8708,8 +8963,8 @@ function resolveZamInvocation(shell) {
   if (installed) {
     return isPowerShellShell(shell) ? `& ${psSingleQuoted2(installed)}` : installed;
   }
-  const projectRoot = join15(import.meta.dirname, "..", "..", "..");
-  const cliSource = join15(projectRoot, "src/cli/index.ts");
+  const projectRoot = join16(import.meta.dirname, "..", "..", "..");
+  const cliSource = join16(projectRoot, "src/cli/index.ts");
   if (isPowerShellShell(shell)) {
     return `& npx --prefix ${psSingleQuoted2(projectRoot)} tsx ${psSingleQuoted2(cliSource)}`;
   }
@@ -8799,7 +9054,7 @@ end tell` : `tell application "Terminal"
   activate
   do script "${escaped}"
 end tell`;
-  const tmpFile = join15(tmpdir2(), `zam-monitor-${sessionId}.scpt`);
+  const tmpFile = join16(tmpdir3(), `zam-monitor-${sessionId}.scpt`);
   try {
     writeFileSync8(tmpFile, appleScript);
     execSync5(`osascript ${JSON.stringify(tmpFile)}`, { stdio: "ignore" });
@@ -8915,7 +9170,7 @@ observerCommand.command("revoke <process>").description("Remove a process from o
 
 // src/cli/commands/profile.ts
 import { homedir as homedir10 } from "os";
-import { dirname as dirname5, join as join16, resolve as resolve4 } from "path";
+import { dirname as dirname5, join as join17, resolve as resolve4 } from "path";
 import { Command as Command11 } from "commander";
 var C2 = {
   reset: "\x1B[0m",
@@ -8925,7 +9180,7 @@ var C2 = {
   green: "\x1B[32m"
 };
 function defaultPersonalDir() {
-  return join16(homedir10(), "Documents", "zam");
+  return join17(homedir10(), "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}`;
@@ -9646,31 +9901,31 @@ settingsCommand.command("repos").description("Show or set Personal, Team, and Or
 
 // src/cli/commands/setup.ts
 import { copyFileSync as copyFileSync2, existsSync as existsSync17, mkdirSync as mkdirSync10, writeFileSync as writeFileSync9 } from "fs";
-import { basename as basename4, dirname as dirname6, join as join17 } from "path";
+import { basename as basename4, dirname as dirname6, join as join18 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command as Command15 } from "commander";
 var packageRoot = [
   fileURLToPath2(new URL("../..", import.meta.url)),
   fileURLToPath2(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync17(join17(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
+].find((candidate) => existsSync17(join18(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
 var SKILL_PAIRS = [
   {
-    from: join17(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
-    to: join17(".claude", "skills", "zam", "SKILL.md")
+    from: join18(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
+    to: join18(".claude", "skills", "zam", "SKILL.md")
   },
   {
-    from: join17(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
-    to: join17(".agent", "skills", "zam", "SKILL.md")
+    from: join18(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
+    to: join18(".agent", "skills", "zam", "SKILL.md")
   },
   {
-    from: join17(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
-    to: join17(".agents", "skills", "zam", "SKILL.md")
+    from: join18(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
+    to: join18(".agents", "skills", "zam", "SKILL.md")
   }
 ];
 function copySkills(force, cwd = process.cwd()) {
   let anyAction = false;
   for (const { from, to } of SKILL_PAIRS) {
-    const dest = join17(cwd, to);
+    const dest = join18(cwd, to);
     if (!existsSync17(from)) {
       console.warn(`  warn  source not found, skipping: ${from}`);
       continue;
@@ -9720,7 +9975,7 @@ async function initDatabase(skipInit) {
 }
 function writeClaudeMd(skipClaudeMd, cwd = process.cwd()) {
   if (skipClaudeMd) return;
-  const dest = join17(cwd, "CLAUDE.md");
+  const dest = join18(cwd, "CLAUDE.md");
   if (existsSync17(dest)) {
     console.log(`  skip  CLAUDE.md (already present)`);
     return;
@@ -9754,7 +10009,7 @@ Use \`zam connector setup turso\` to store cloud credentials in
 }
 function writeAgentsMd(skipAgentsMd, cwd = process.cwd()) {
   if (skipAgentsMd) return;
-  const dest = join17(cwd, "AGENTS.md");
+  const dest = join18(cwd, "AGENTS.md");
   if (existsSync17(dest)) {
     console.log(`  skip  AGENTS.md (already present)`);
     return;
@@ -9902,7 +10157,7 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
 // src/cli/commands/snapshot.ts
 import { existsSync as existsSync18, mkdirSync as mkdirSync11, readFileSync as readFileSync12, writeFileSync as writeFileSync10 } from "fs";
 import { homedir as homedir11 } from "os";
-import { dirname as dirname7, join as join18 } from "path";
+import { dirname as dirname7, join as join19 } from "path";
 import { Command as Command17 } from "commander";
 function defaultOutName() {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
@@ -9922,7 +10177,7 @@ var exportCmd = new Command17("export").description("Write a portable SQL-text s
   try {
     db = await openDatabaseWithSync({ initialize: true });
     const snapshot = await exportSnapshot(db);
-    const personalDir = await getSetting(db, "personal.workspace_dir") || join18(homedir11(), "Documents", "zam");
+    const personalDir = await getSetting(db, "personal.workspace_dir") || join19(homedir11(), "Documents", "zam");
     await db.close();
     db = void 0;
     const manifest = verifySnapshot(snapshot);
@@ -9931,7 +10186,7 @@ var exportCmd = new Command17("export").description("Write a portable SQL-text s
       process.stdout.write(snapshot);
       return;
     }
-    const out = opts.out ?? join18(personalDir, "snapshots", defaultOutName());
+    const out = opts.out ?? join19(personalDir, "snapshots", defaultOutName());
     const dir = dirname7(out);
     if (dir && dir !== "." && !existsSync18(dir)) {
       mkdirSync11(dir, { recursive: true });
@@ -10318,7 +10573,7 @@ tokenCommand.command("status").description("Show full status of a token for a us
 import { spawn as spawn2, spawnSync } from "child_process";
 import { existsSync as existsSync19 } from "fs";
 import { homedir as homedir12 } from "os";
-import { dirname as dirname8, join as join19 } from "path";
+import { dirname as dirname8, join as join20 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { Command as Command20 } from "commander";
 var C3 = {
@@ -10334,8 +10589,8 @@ function findDesktopDir() {
   for (const start of starts) {
     let dir = start;
     for (let i = 0; i < 10; i++) {
-      if (existsSync19(join19(dir, "desktop", "src-tauri", "tauri.conf.json"))) {
-        return join19(dir, "desktop");
+      if (existsSync19(join20(dir, "desktop", "src-tauri", "tauri.conf.json"))) {
+        return join20(dir, "desktop");
       }
       const parent = dirname8(dir);
       if (parent === dir) break;
@@ -10345,18 +10600,18 @@ function findDesktopDir() {
   return null;
 }
 function findBuiltApp(desktopDir) {
-  const releaseDir = join19(desktopDir, "src-tauri", "target", "release");
+  const releaseDir = join20(desktopDir, "src-tauri", "target", "release");
   if (process.platform === "win32") {
     for (const name of ["ZAM.exe", "zam.exe", "zam-desktop.exe"]) {
-      const p = join19(releaseDir, name);
+      const p = join20(releaseDir, name);
       if (existsSync19(p)) return p;
     }
   } else if (process.platform === "darwin") {
-    const app = join19(releaseDir, "bundle", "macos", "ZAM.app");
+    const app = join20(releaseDir, "bundle", "macos", "ZAM.app");
     if (existsSync19(app)) return app;
   } else {
     for (const name of ["zam", "ZAM", "zam-desktop"]) {
-      const p = join19(releaseDir, name);
+      const p = join20(releaseDir, name);
       if (existsSync19(p)) return p;
     }
   }
@@ -10364,10 +10619,10 @@ function findBuiltApp(desktopDir) {
 }
 function findInstalledApp() {
   const candidates = process.platform === "win32" ? [
-    process.env.LOCALAPPDATA && join19(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
-    process.env.ProgramFiles && join19(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
-    process.env["ProgramFiles(x86)"] && join19(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
-  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join19(homedir12(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
+    process.env.LOCALAPPDATA && join20(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
+    process.env.ProgramFiles && join20(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
+    process.env["ProgramFiles(x86)"] && join20(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
+  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join20(homedir12(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
   return candidates.find((candidate) => candidate && existsSync19(candidate)) || null;
 }
 function runNpm(args, opts) {
@@ -10379,7 +10634,7 @@ function runNpm(args, opts) {
   return res.status ?? 1;
 }
 function ensureDesktopDeps(desktopDir) {
-  if (existsSync19(join19(desktopDir, "node_modules"))) return true;
+  if (existsSync19(join20(desktopDir, "node_modules"))) return true;
   console.log(
     `${C3.cyan}Installing desktop dependencies (one-time)...${C3.reset}`
   );
@@ -10405,7 +10660,7 @@ function requireRust() {
 function hasMsvcBuildTools() {
   if (process.platform !== "win32") return true;
   const pf86 = process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)";
-  const vswhere = join19(
+  const vswhere = join20(
     pf86,
     "Microsoft Visual Studio",
     "Installer",
@@ -10443,7 +10698,7 @@ function requireMsvcOnWindows() {
   return false;
 }
 function warnIfCliMissing(repoRoot) {
-  if (!existsSync19(join19(repoRoot, "dist", "cli", "index.js"))) {
+  if (!existsSync19(join20(repoRoot, "dist", "cli", "index.js"))) {
     console.warn(
       `${C3.yellow}\u26A0 CLI build not found (dist/cli/index.js). The GUI bridge needs it \u2014 run 'npm run build' at the repo root.${C3.reset}`
     );
@@ -10527,7 +10782,7 @@ var uiCommand = new Command20("ui").description("Launch the ZAM Desktop GUI (Act
     );
     const code = runNpm(["run", "tauri", "build"], { cwd: desktopDir });
     if (code === 0) {
-      const bundle = join19(
+      const bundle = join20(
         desktopDir,
         "src-tauri",
         "target",
@@ -10603,9 +10858,11 @@ ${C3.dim}After that, 'zam ui' launches it directly.${C3.reset}`
 });
 
 // src/cli/commands/update.ts
-import { readFileSync as readFileSync13 } from "fs";
-import { dirname as dirname9, join as join20 } from "path";
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync20, readFileSync as readFileSync13, realpathSync } from "fs";
+import { dirname as dirname9, join as join21 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
+import { confirm as confirm3 } from "@inquirer/prompts";
 import { Command as Command21 } from "commander";
 var GITHUB_REPO = "zam-os/zam";
 var CHANNELS = [
@@ -10620,6 +10877,7 @@ var C4 = {
   cyan: "\x1B[36m",
   dim: "\x1B[2m",
   green: "\x1B[32m",
+  red: "\x1B[31m",
   yellow: "\x1B[33m"
 };
 function currentVersion() {
@@ -10627,7 +10885,7 @@ function currentVersion() {
   for (const up of ["..", "../..", "../../.."]) {
     try {
       const pkg2 = JSON.parse(
-        readFileSync13(join20(here, up, "package.json"), "utf-8")
+        readFileSync13(join21(here, up, "package.json"), "utf-8")
       );
       if (pkg2.version) return pkg2.version;
     } catch {
@@ -10635,6 +10893,16 @@ function currentVersion() {
   }
   return "0.0.0";
 }
+function versionAt(dir) {
+  try {
+    const pkg2 = JSON.parse(
+      readFileSync13(join21(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`,
@@ -10704,7 +10972,150 @@ var checkCmd = new Command21("check").description("Check whether a newer ZAM has
     }
   }
 );
-var updateCommand = new Command21("update").description("Check for ZAM updates").addCommand(checkCmd);
+function findSourceRepo() {
+  let dir = realpathSync(dirname9(fileURLToPath4(import.meta.url)));
+  let parent = dirname9(dir);
+  while (parent !== dir) {
+    if (existsSync20(join21(dir, ".git"))) return dir;
+    dir = parent;
+    parent = dirname9(dir);
+  }
+  return existsSync20(join21(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,
+    [join21(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 Command21("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 Command22 } from "commander";
@@ -10745,11 +11156,11 @@ var whoamiCommand = new Command22("whoami").description("Show or set the default
 
 // src/cli/commands/workspace.ts
 import { execSync as execSync6 } from "child_process";
-import { existsSync as existsSync20, writeFileSync as writeFileSync11 } from "fs";
-import { join as join21 } from "path";
-import { confirm as confirm3, input as input7 } from "@inquirer/prompts";
+import { existsSync as existsSync21, writeFileSync as writeFileSync11 } from "fs";
+import { join as join22 } from "path";
+import { confirm as confirm4, input as input7 } from "@inquirer/prompts";
 import { Command as Command23 } from "commander";
-function runGit(cwd, args) {
+function runGit2(cwd, args) {
   try {
     return execSync6(`git ${args}`, {
       cwd,
@@ -10779,7 +11190,7 @@ workspaceCommand.command("publish").description("Publish your local workspace sa
     );
     process.exit(1);
   }
-  if (!existsSync20(workspaceDir)) {
+  if (!existsSync21(workspaceDir)) {
     console.error(
       `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
     );
@@ -10793,20 +11204,20 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
     );
     process.exit(1);
   }
-  const gitignorePath = join21(workspaceDir, ".gitignore");
-  if (!existsSync20(gitignorePath)) {
+  const gitignorePath = join22(workspaceDir, ".gitignore");
+  if (!existsSync21(gitignorePath)) {
     writeFileSync11(
       gitignorePath,
       "node_modules/\n.agent/\n.agents/\n.claude/\n.gemini/\n.goose/\n*.log\n",
       "utf8"
     );
   }
-  const hasGitRepo = existsSync20(join21(workspaceDir, ".git"));
+  const hasGitRepo = existsSync21(join22(workspaceDir, ".git"));
   if (!hasGitRepo) {
     console.log("Initializing local Git repository...");
-    runGit(workspaceDir, "init -b main");
-    runGit(workspaceDir, "add .");
-    runGit(
+    runGit2(workspaceDir, "init -b main");
+    runGit2(workspaceDir, "add .");
+    runGit2(
       workspaceDir,
       'commit -m "chore: initial workspace sandbox bootstrap"'
     );
@@ -10818,14 +11229,14 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
     message: "Choose a name for your GitHub repository:",
     default: "zam-personal"
   });
-  const isPrivate = await confirm3({
+  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 confirm3({
+    const proceedGh = await confirm4({
       message: "Would you like ZAM to create the repository using the GitHub CLI?",
       default: true
     });
@@ -10870,16 +11281,16 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
       console.log("Linking remote repository and pushing...");
       let hasOrigin = false;
       try {
-        runGit(workspaceDir, "remote get-url origin");
+        runGit2(workspaceDir, "remote get-url origin");
         hasOrigin = true;
       } catch {
       }
       if (hasOrigin) {
-        runGit(workspaceDir, `remote set-url origin ${githubUrl}`);
+        runGit2(workspaceDir, `remote set-url origin ${githubUrl}`);
       } else {
-        runGit(workspaceDir, `remote add origin ${githubUrl}`);
+        runGit2(workspaceDir, `remote add origin ${githubUrl}`);
       }
-      runGit(workspaceDir, "push -u origin main");
+      runGit2(workspaceDir, "push -u origin main");
       console.log(
         "\x1B[32m\u2713 Successfully linked and pushed to GitHub!\x1B[0m"
       );
@@ -10897,7 +11308,7 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
 // src/cli/index.ts
 var __dirname = dirname10(fileURLToPath5(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync14(join22(__dirname, "..", "..", "package.json"), "utf-8")
+  readFileSync14(join23(__dirname, "..", "..", "package.json"), "utf-8")
 );
 var program = new Command24();
 program.name("zam").description(