zam-core 0.3.11 → 0.3.13

package/dist/cli/index.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { readFileSync as readFileSync11 } from "fs";
-import { dirname as dirname10, join as join20 } from "path";
+import { readFileSync as readFileSync13 } from "fs";
+import { dirname as dirname10, join as join21 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 import { Command as Command23 } from "commander";
 
 // src/cli/commands/agent.ts
-import { existsSync as existsSync10 } from "fs";
-import { join as join9 } from "path";
+import { existsSync as existsSync11 } from "fs";
+import { join as join10 } from "path";
 import { Command } from "commander";
 
 // src/kernel/analytics/stats.ts
@@ -1360,8 +1360,17 @@ async function deleteCardForUser(db, tokenId, userId) {
   await db.prepare("DELETE FROM cards WHERE id = ?").run(card.id);
   return { card, impact };
 }
-async function getDueCards(db, userId, now) {
+async function getDueCards(db, userId, now, domain) {
   const cutoff = now ?? (/* @__PURE__ */ new Date()).toISOString();
+  if (domain) {
+    return await db.prepare(
+      `SELECT c.*, t.slug, t.concept, t.domain, t.bloom_level
+         FROM cards c
+         JOIN tokens t ON t.id = c.token_id
+         WHERE c.user_id = ? AND c.blocked = 0 AND c.due_at <= ? AND t.domain = ?
+         ORDER BY t.bloom_level ASC, c.due_at ASC`
+    ).all(userId, cutoff, domain);
+  }
   return await db.prepare(
     `SELECT c.*, t.slug, t.concept, t.domain, t.bloom_level
        FROM cards c
@@ -1891,11 +1900,11 @@ function analyzeObservation(commands, tokenPatterns) {
   const ratings = [];
   for (const tp of tokenPatterns) {
     const matchIndices = [];
-    const matchedTexts = [];
+    const matchedTexts2 = [];
     for (let i = 0; i < commands.length; i++) {
       if (matchesToken(commands[i].command, tp.patterns)) {
         matchIndices.push(i);
-        matchedTexts.push(commands[i].command);
+        matchedTexts2.push(commands[i].command);
         matchedSet.add(i);
       }
     }
@@ -1985,7 +1994,7 @@ function analyzeObservation(commands, tokenPatterns) {
         medianGapMs,
         thinkingGapMs
       },
-      matchedCommandTexts: matchedTexts
+      matchedCommandTexts: matchedTexts2
     });
   }
   const unmatchedCommands = [];
@@ -2347,6 +2356,240 @@ async function unblockReady(db, userId) {
   return { unblocked };
 }
 
+// src/kernel/observation/ui-observer-io.ts
+import { appendFileSync as appendFileSync2, existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync5 } from "fs";
+import { homedir as homedir4 } from "os";
+import { join as join5 } from "path";
+
+// src/kernel/observation/ui-observer.ts
+var UI_OBSERVATION_PROTOCOL_VERSION = 1;
+var OBSERVATION_KINDS = /* @__PURE__ */ new Set([
+  "progress",
+  "step-completed",
+  "error",
+  "help-seeking",
+  "uncertain",
+  "privacy-pause",
+  "heartbeat"
+]);
+var ACTION_TYPES = /* @__PURE__ */ new Set([
+  "click",
+  "shortcut",
+  "typing",
+  "scroll",
+  "window-change"
+]);
+var EVIDENCE_TYPES = /* @__PURE__ */ new Set([
+  "uia",
+  "keyframe",
+  "clip",
+  "window"
+]);
+function isUiObservationReport(value) {
+  if (!isRecord(value)) return false;
+  if (value.version !== UI_OBSERVATION_PROTOCOL_VERSION) return false;
+  if (!isNonEmptyString(value.sessionId)) return false;
+  if (!isNonNegativeInteger(value.sequence)) return false;
+  if (!isNonEmptyString(value.observedFrom)) return false;
+  if (!isNonEmptyString(value.observedTo)) return false;
+  if (typeof value.kind !== "string" || !OBSERVATION_KINDS.has(value.kind)) {
+    return false;
+  }
+  if (!isApplication(value.application)) return false;
+  if (!isNonEmptyString(value.summary)) return false;
+  if (!Array.isArray(value.actions) || !value.actions.every(isObservedAction)) {
+    return false;
+  }
+  if (!Array.isArray(value.evidence) || !value.evidence.every(isEvidenceRef)) {
+    return false;
+  }
+  if (!Array.isArray(value.candidateTokens) || !value.candidateTokens.every(isCandidateToken)) {
+    return false;
+  }
+  return isConfidence(value.confidence);
+}
+function parseUiObservationLog(jsonl) {
+  const reports = [];
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const value = JSON.parse(trimmed);
+      if (isUiObservationReport(value)) {
+        reports.push(value);
+      }
+    } catch {
+    }
+  }
+  return reports.sort((left, right) => left.sequence - right.sequence);
+}
+function isApplication(value) {
+  if (!isRecord(value) || !isNonEmptyString(value.processName)) return false;
+  if (value.processId !== void 0 && !isNonNegativeInteger(value.processId)) {
+    return false;
+  }
+  return value.windowTitle === void 0 || typeof value.windowTitle === "string";
+}
+function isObservedAction(value) {
+  if (!isRecord(value) || typeof value.type !== "string") return false;
+  if (!ACTION_TYPES.has(value.type)) return false;
+  if (value.target !== void 0 && typeof value.target !== "string") {
+    return false;
+  }
+  return value.result === void 0 || typeof value.result === "string";
+}
+function isEvidenceRef(value) {
+  if (!isRecord(value) || typeof value.type !== "string") return false;
+  return EVIDENCE_TYPES.has(value.type) && isNonEmptyString(value.ref) && typeof value.redacted === "boolean";
+}
+function isCandidateToken(value) {
+  return isRecord(value) && isNonEmptyString(value.slug) && isConfidence(value.confidence) && isNonEmptyString(value.rationale);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isNonNegativeInteger(value) {
+  return Number.isInteger(value) && Number(value) >= 0;
+}
+function isConfidence(value) {
+  return typeof value === "number" && value >= 0 && value <= 1;
+}
+
+// src/kernel/observation/ui-observer-io.ts
+var DEFAULT_UI_OBSERVER_DIR = join5(homedir4(), ".zam", "observer");
+function getUiObserverDir() {
+  return process.env.ZAM_OBSERVER_DIR || DEFAULT_UI_OBSERVER_DIR;
+}
+function getUiObservationPath(sessionId) {
+  if (!/^[A-Za-z0-9_-]+$/.test(sessionId)) {
+    throw new Error(`Invalid observer session ID: ${sessionId}`);
+  }
+  return join5(getUiObserverDir(), `${sessionId}.reports.jsonl`);
+}
+function ensureUiObserverDir() {
+  const dir = getUiObserverDir();
+  if (!existsSync5(dir)) {
+    mkdirSync4(dir, { recursive: true, mode: 448 });
+  }
+}
+function uiObservationLogExists(sessionId) {
+  return existsSync5(getUiObservationPath(sessionId));
+}
+function readUiObservationLog(sessionId) {
+  const path = getUiObservationPath(sessionId);
+  if (!existsSync5(path)) return [];
+  return parseUiObservationLog(readFileSync5(path, "utf8"));
+}
+function appendUiObservationReport(report) {
+  if (!isUiObservationReport(report)) {
+    throw new Error("Invalid UI observation report");
+  }
+  ensureUiObserverDir();
+  appendFileSync2(
+    getUiObservationPath(report.sessionId),
+    `${JSON.stringify(report)}
+`,
+    { encoding: "utf8", mode: 384 }
+  );
+}
+
+// src/kernel/observation/ui-observer-synthesis.ts
+var MIN_UI_CONFIDENCE = 0.6;
+function kindToRating(kind) {
+  switch (kind) {
+    case "step-completed":
+      return 4;
+    case "progress":
+      return 3;
+    case "error":
+    case "help-seeking":
+      return 2;
+    default:
+      return null;
+  }
+}
+function toSynthesisConfidence(confidence) {
+  return confidence >= 0.85 ? "high" : "medium";
+}
+function confidenceRank(confidence) {
+  return confidence === "high" ? 2 : 1;
+}
+function buildEvidence(report) {
+  return {
+    matchedCommands: report.actions.length,
+    helpSeeking: report.kind === "help-seeking",
+    errorCount: report.kind === "error" ? 1 : 0,
+    selfCorrections: 0,
+    medianGapMs: null,
+    thinkingGapMs: null
+  };
+}
+function matchedTexts(report) {
+  const texts = [report.summary];
+  for (const action of report.actions) {
+    const label = [action.type, action.target, action.result].filter(Boolean).join(" ");
+    if (label) texts.push(label);
+  }
+  return texts;
+}
+function buildUiSynthesisCandidates(reports, tokens, applied, minConfidence) {
+  const minRank = confidenceRank(minConfidence);
+  const bestBySlug = /* @__PURE__ */ new Map();
+  let skippedLowConfidence = 0;
+  for (const report of reports) {
+    if (report.confidence < MIN_UI_CONFIDENCE) continue;
+    const fallbackRating = kindToRating(report.kind);
+    const candidates2 = report.candidateTokens.length > 0 ? report.candidateTokens.map((candidate) => ({
+      slug: candidate.slug,
+      confidence: candidate.confidence,
+      rating: fallbackRating
+    })) : [];
+    for (const candidate of candidates2) {
+      const token = tokens.get(candidate.slug);
+      if (!token || applied.has(token.id)) continue;
+      const synthesisConfidence = toSynthesisConfidence(candidate.confidence);
+      if (confidenceRank(synthesisConfidence) < minRank) {
+        skippedLowConfidence++;
+        continue;
+      }
+      const inferredRating = candidate.rating ?? 3;
+      const existing = bestBySlug.get(candidate.slug);
+      if (existing && existing.reportConfidence >= candidate.confidence) {
+        continue;
+      }
+      bestBySlug.set(candidate.slug, {
+        token,
+        inferredRating,
+        confidence: synthesisConfidence,
+        evidence: buildEvidence(report),
+        matchedCommandTexts: matchedTexts(report),
+        reportConfidence: candidate.confidence
+      });
+    }
+  }
+  const candidates = [...bestBySlug.values()].sort((left, right) => right.reportConfidence - left.reportConfidence).map((entry) => ({
+    tokenId: entry.token.id,
+    tokenSlug: entry.token.slug,
+    concept: entry.token.concept,
+    domain: entry.token.domain,
+    inferredRating: entry.inferredRating,
+    confidence: entry.confidence,
+    evidence: entry.evidence,
+    matchedCommandTexts: entry.matchedCommandTexts
+  }));
+  return { candidates, skippedLowConfidence };
+}
+function uiObservationTimeSpan(reports) {
+  if (reports.length === 0) return null;
+  const start = reports[0].observedFrom;
+  const end = reports[reports.length - 1].observedTo;
+  const durationMs = Math.max(0, Date.parse(end) - Date.parse(start));
+  return { start, end, durationMs };
+}
+
 // src/kernel/observation/session-synthesis.ts
 function parseSynthesisRow(row) {
   return {
@@ -2354,7 +2597,7 @@ function parseSynthesisRow(row) {
     evidence: JSON.parse(row.evidence)
   };
 }
-function confidenceRank(confidence) {
+function confidenceRank2(confidence) {
   return confidence === "high" ? 2 : confidence === "medium" ? 1 : 0;
 }
 function normalizeSkillStep(step) {
@@ -2416,20 +2659,50 @@ async function prepareSessionSynthesis(db, input8) {
     validPatterns.push(pattern);
     tokens.set(pattern.slug, token);
   }
-  const commands = input8.commands ?? pairCommands(readMonitorLog(input8.sessionId));
-  const analysis = analyzeObservation(commands, validPatterns);
   const applied = new Set(
     (await getSessionSynthesisRecords(db, input8.sessionId)).map(
       (record) => record.token_id
     )
   );
-  const minRank = confidenceRank(input8.minConfidence ?? "medium");
+  const minConfidence = input8.minConfidence ?? "medium";
+  if (session.execution_context === "ui") {
+    const reports = readUiObservationLog(input8.sessionId);
+    for (const report of reports) {
+      for (const candidate of report.candidateTokens) {
+        if (tokens.has(candidate.slug)) continue;
+        const token = await getTokenBySlug(db, candidate.slug);
+        if (token && !token.deprecated_at) {
+          tokens.set(candidate.slug, token);
+        }
+      }
+    }
+    const { candidates: candidates2, skippedLowConfidence: skippedLowConfidence2 } = buildUiSynthesisCandidates(
+      reports,
+      tokens,
+      applied,
+      minConfidence
+    );
+    return {
+      sessionId: session.id,
+      userId: session.user_id,
+      patternCount: validPatterns.length,
+      commandCount: reports.length,
+      alreadyApplied: applied.size,
+      skippedLowConfidence: skippedLowConfidence2,
+      candidates: candidates2,
+      unmatchedCommands: [],
+      timeSpan: uiObservationTimeSpan(reports)
+    };
+  }
+  const commands = input8.commands ?? pairCommands(readMonitorLog(input8.sessionId));
+  const analysis = analyzeObservation(commands, validPatterns);
+  const minRank = confidenceRank2(minConfidence);
   let skippedLowConfidence = 0;
   const candidates = [];
   for (const rating of analysis.ratings) {
     const token = tokens.get(rating.tokenSlug);
     if (!token || rating.rating == null || applied.has(token.id)) continue;
-    if (confidenceRank(rating.confidence) < minRank) {
+    if (confidenceRank2(rating.confidence) < minRank) {
       skippedLowConfidence++;
       continue;
     }
@@ -3026,8 +3299,8 @@ function generatePrompt(input8) {
 }
 
 // src/kernel/recall/reference-resolver.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
-import { dirname as dirname3, join as join5, resolve } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
+import { dirname as dirname3, join as join6, resolve } from "path";
 var DEFAULT_REVIEW_CONTEXT_MAX_CHARS = 6e3;
 function htmlToText(html) {
   let content = html;
@@ -3088,11 +3361,11 @@ async function resolveReference(sourceLink) {
       const filePath = anchorIndex2 !== -1 ? fullPathWithAnchor.slice(0, anchorIndex2) : fullPathWithAnchor;
       const anchor2 = anchorIndex2 !== -1 ? fullPathWithAnchor.slice(anchorIndex2) : "";
       const parentDir = dirname3(process.cwd());
-      const localRepoPath = join5(parentDir, repo);
-      const localFilePath = join5(localRepoPath, filePath);
-      if (existsSync5(localFilePath)) {
+      const localRepoPath = join6(parentDir, repo);
+      const localFilePath = join6(localRepoPath, filePath);
+      if (existsSync6(localFilePath)) {
         try {
-          let fileContent = readFileSync5(localFilePath, "utf-8");
+          let fileContent = readFileSync6(localFilePath, "utf-8");
           if (anchor2) {
             fileContent = extractLines(fileContent, anchor2);
           }
@@ -3146,9 +3419,9 @@ Link: ${cleaned}`,
   const relativePath = anchorIndex !== -1 ? cleaned.slice(0, anchorIndex) : cleaned;
   const anchor = anchorIndex !== -1 ? cleaned.slice(anchorIndex) : "";
   const absolutePath = resolve(process.cwd(), relativePath);
-  if (existsSync5(absolutePath)) {
+  if (existsSync6(absolutePath)) {
     try {
-      let fileContent = readFileSync5(absolutePath, "utf-8");
+      let fileContent = readFileSync6(absolutePath, "utf-8");
       if (anchor) {
         fileContent = extractLines(fileContent, anchor);
       }
@@ -3400,44 +3673,44 @@ function intersperseNew(reviews, newCards, interval) {
 
 // src/kernel/system/hooks.ts
 import {
-  appendFileSync as appendFileSync2,
+  appendFileSync as appendFileSync3,
   copyFileSync,
-  existsSync as existsSync6,
-  mkdirSync as mkdirSync4,
-  readFileSync as readFileSync6,
+  existsSync as existsSync7,
+  mkdirSync as mkdirSync5,
+  readFileSync as readFileSync7,
   writeFileSync as writeFileSync3
 } from "fs";
-import { homedir as homedir4 } from "os";
-import { join as join6 } from "path";
+import { homedir as homedir5 } from "os";
+import { join as join7 } from "path";
 import { fileURLToPath } from "url";
-var HOME = homedir4();
+var HOME = homedir5();
 function getPackageSkillPath(agent = "default") {
   const packageRoot2 = [
     fileURLToPath(new URL("../../..", import.meta.url)),
     fileURLToPath(new URL("../..", import.meta.url)),
     fileURLToPath(new URL("..", import.meta.url))
-  ].find((candidate) => existsSync6(join6(candidate, "package.json"))) ?? "";
+  ].find((candidate) => existsSync7(join7(candidate, "package.json"))) ?? "";
   if (!packageRoot2) return "";
   if (agent === "codex") {
-    const codexPath = join6(packageRoot2, ".agents", "skills", "zam", "SKILL.md");
-    if (existsSync6(codexPath)) return codexPath;
+    const codexPath = join7(packageRoot2, ".agents", "skills", "zam", "SKILL.md");
+    if (existsSync7(codexPath)) return codexPath;
     return "";
   }
   if (agent === "claude") {
-    const claudePath = join6(
+    const claudePath = join7(
       packageRoot2,
       ".claude",
       "skills",
       "zam",
       "SKILL.md"
     );
-    if (existsSync6(claudePath)) return claudePath;
+    if (existsSync7(claudePath)) return claudePath;
     return "";
   }
-  let path = join6(packageRoot2, ".agent", "skills", "zam", "SKILL.md");
-  if (existsSync6(path)) return path;
-  path = join6(packageRoot2, ".claude", "skills", "zam", "SKILL.md");
-  if (existsSync6(path)) return path;
+  let path = join7(packageRoot2, ".agent", "skills", "zam", "SKILL.md");
+  if (existsSync7(path)) return path;
+  path = join7(packageRoot2, ".claude", "skills", "zam", "SKILL.md");
+  if (existsSync7(path)) return path;
   return "";
 }
 function distributeGlobalSkills(home = HOME) {
@@ -3449,16 +3722,16 @@ function distributeGlobalSkills(home = HOME) {
     console.warn("Could not find ZAM source SKILL.md in the package folder.");
     return results;
   }
-  const claudeSkillsDir = join6(home, ".claude", "skills", "zam");
+  const claudeSkillsDir = join7(home, ".claude", "skills", "zam");
   try {
     if (!claudeSourceSkill) {
       throw new Error("Claude skill source not found");
     }
-    mkdirSync4(claudeSkillsDir, { recursive: true });
-    copyFileSync(claudeSourceSkill, join6(claudeSkillsDir, "SKILL.md"));
+    mkdirSync5(claudeSkillsDir, { recursive: true });
+    copyFileSync(claudeSourceSkill, join7(claudeSkillsDir, "SKILL.md"));
     results.push({
       name: "Claude Code Global",
-      path: join6(claudeSkillsDir, "SKILL.md"),
+      path: join7(claudeSkillsDir, "SKILL.md"),
       success: true
     });
   } catch (_err) {
@@ -3468,13 +3741,13 @@ function distributeGlobalSkills(home = HOME) {
       success: false
     });
   }
-  const geminiSkillsDir = join6(home, ".gemini", "skills", "zam");
+  const geminiSkillsDir = join7(home, ".gemini", "skills", "zam");
   try {
-    mkdirSync4(geminiSkillsDir, { recursive: true });
-    copyFileSync(sourceSkill, join6(geminiSkillsDir, "SKILL.md"));
+    mkdirSync5(geminiSkillsDir, { recursive: true });
+    copyFileSync(sourceSkill, join7(geminiSkillsDir, "SKILL.md"));
     results.push({
       name: "Gemini CLI Global",
-      path: join6(geminiSkillsDir, "SKILL.md"),
+      path: join7(geminiSkillsDir, "SKILL.md"),
       success: true
     });
   } catch (_err) {
@@ -3484,16 +3757,16 @@ function distributeGlobalSkills(home = HOME) {
       success: false
     });
   }
-  const codexSkillsDir = join6(home, ".agents", "skills", "zam");
+  const codexSkillsDir = join7(home, ".agents", "skills", "zam");
   try {
     if (!codexSourceSkill) {
       throw new Error("Codex skill source not found");
     }
-    mkdirSync4(codexSkillsDir, { recursive: true });
-    copyFileSync(codexSourceSkill, join6(codexSkillsDir, "SKILL.md"));
+    mkdirSync5(codexSkillsDir, { recursive: true });
+    copyFileSync(codexSourceSkill, join7(codexSkillsDir, "SKILL.md"));
     results.push({
       name: "Codex Global",
-      path: join6(codexSkillsDir, "SKILL.md"),
+      path: join7(codexSkillsDir, "SKILL.md"),
       success: true
     });
   } catch (_err) {
@@ -3503,13 +3776,13 @@ function distributeGlobalSkills(home = HOME) {
       success: false
     });
   }
-  const gooseSkillsDir = join6(home, ".goose", "skills", "zam");
+  const gooseSkillsDir = join7(home, ".goose", "skills", "zam");
   try {
-    mkdirSync4(gooseSkillsDir, { recursive: true });
-    copyFileSync(sourceSkill, join6(gooseSkillsDir, "SKILL.md"));
+    mkdirSync5(gooseSkillsDir, { recursive: true });
+    copyFileSync(sourceSkill, join7(gooseSkillsDir, "SKILL.md"));
     results.push({
       name: "Goose Global",
-      path: join6(gooseSkillsDir, "SKILL.md"),
+      path: join7(gooseSkillsDir, "SKILL.md"),
       success: true
     });
   } catch (_err) {
@@ -3553,14 +3826,14 @@ function Start-ZamMonitor {
 `;
 function installHook(file, hook, oldHook) {
   try {
-    const content = existsSync6(file) ? readFileSync6(file, "utf8") : "";
+    const content = existsSync7(file) ? readFileSync7(file, "utf8") : "";
     if (content.includes(HOOK_MARKER)) {
       return { success: true, alreadyHooked: true };
     }
     if (content.includes(oldHook.trim())) {
       writeFileSync3(file, content.replace(oldHook.trim(), hook.trim()), "utf8");
     } else {
-      appendFileSync2(file, hook);
+      appendFileSync3(file, hook);
     }
     return { success: true, alreadyHooked: false };
   } catch {
@@ -3569,24 +3842,24 @@ function installHook(file, hook, oldHook) {
 }
 function injectShellHooks(home = HOME) {
   const results = [];
-  const zshrc = join6(home, ".zshrc");
-  if (existsSync6(zshrc)) {
+  const zshrc = join7(home, ".zshrc");
+  if (existsSync7(zshrc)) {
     const status = installHook(zshrc, posixHook("zsh"), POSIX_OLD_HOOK);
     results.push({ shell: "zsh", file: zshrc, ...status });
   }
-  const bashrc = join6(home, ".bashrc");
-  if (existsSync6(bashrc)) {
+  const bashrc = join7(home, ".bashrc");
+  if (existsSync7(bashrc)) {
     const status = installHook(bashrc, posixHook("bash"), POSIX_OLD_HOOK);
     results.push({ shell: "bash", file: bashrc, ...status });
   }
   const pwshDirs = [
-    join6(home, "Documents", "PowerShell"),
-    join6(home, "Documents", "WindowsPowerShell")
+    join7(home, "Documents", "PowerShell"),
+    join7(home, "Documents", "WindowsPowerShell")
   ];
   for (const dir of pwshDirs) {
-    const profileFile = join6(dir, "Microsoft.PowerShell_profile.ps1");
+    const profileFile = join7(dir, "Microsoft.PowerShell_profile.ps1");
     try {
-      mkdirSync4(dir, { recursive: true });
+      mkdirSync5(dir, { recursive: true });
       const status = installHook(
         profileFile,
         POWERSHELL_HOOK,
@@ -3818,21 +4091,21 @@ function t(locale, key, params = {}) {
 }
 
 // src/kernel/system/install-config.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
-import { homedir as homedir5 } from "os";
-import { dirname as dirname4, join as join7 } from "path";
-var DEFAULT_CONFIG_PATH = join7(homedir5(), ".zam", "config.json");
+import { existsSync as existsSync8, mkdirSync as mkdirSync6, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
+import { homedir as homedir6 } from "os";
+import { dirname as dirname4, join as join8 } from "path";
+var DEFAULT_CONFIG_PATH = join8(homedir6(), ".zam", "config.json");
 function loadInstallConfig(path = DEFAULT_CONFIG_PATH) {
-  if (!existsSync7(path)) return {};
+  if (!existsSync8(path)) return {};
   try {
-    return JSON.parse(readFileSync7(path, "utf-8"));
+    return JSON.parse(readFileSync8(path, "utf-8"));
   } catch {
     return {};
   }
 }
 function saveInstallConfig(config, path = DEFAULT_CONFIG_PATH) {
   const dir = dirname4(path);
-  if (!existsSync7(dir)) mkdirSync5(dir, { recursive: true });
+  if (!existsSync8(dir)) mkdirSync6(dir, { recursive: true });
   writeFileSync4(path, `${JSON.stringify(config, null, 2)}
 `, "utf-8");
 }
@@ -3864,9 +4137,9 @@ function detectSyncProvider(dir) {
 
 // src/kernel/system/installer.ts
 import { execFileSync, execSync } from "child_process";
-import { existsSync as existsSync8 } from "fs";
-import { homedir as homedir6 } from "os";
-import { join as join8 } from "path";
+import { existsSync as existsSync9 } from "fs";
+import { homedir as homedir7 } from "os";
+import { join as join9 } from "path";
 function hasCommand(cmd) {
   try {
     const checkCmd2 = process.platform === "win32" ? `where ${cmd}` : `which ${cmd}`;
@@ -3883,7 +4156,7 @@ function installFastFlowLM() {
       message: "FastFlowLM is only supported on Windows."
     };
   }
-  const hasFlm = hasCommand("flm") || existsSync8("C:\\Program Files\\flm\\flm.exe");
+  const hasFlm = hasCommand("flm") || existsSync9("C:\\Program Files\\flm\\flm.exe");
   if (hasFlm) {
     return { success: true, message: "FastFlowLM is already installed." };
   }
@@ -3910,8 +4183,8 @@ function installFastFlowLM() {
 function installOllama() {
   const isMac = process.platform === "darwin";
   const isWin = process.platform === "win32";
-  const hasOllama = hasCommand("ollama") || isMac && existsSync8("/Applications/Ollama.app") || isWin && existsSync8(
-    join8(homedir6(), "AppData", "Local", "Programs", "Ollama", "ollama.exe")
+  const hasOllama = hasCommand("ollama") || isMac && existsSync9("/Applications/Ollama.app") || isWin && existsSync9(
+    join9(homedir7(), "AppData", "Local", "Programs", "Ollama", "ollama.exe")
   );
   if (hasOllama) {
     return { success: true, message: "Ollama is already installed." };
@@ -3971,8 +4244,8 @@ function installOllama() {
 function resolveOllamaCommand() {
   if (hasCommand("ollama")) return "ollama";
   const candidates = process.platform === "win32" ? [
-    join8(
-      homedir6(),
+    join9(
+      homedir7(),
       "AppData",
       "Local",
       "Programs",
@@ -3980,7 +4253,7 @@ function resolveOllamaCommand() {
       "ollama.exe"
     )
   ] : process.platform === "darwin" ? ["/Applications/Ollama.app/Contents/Resources/ollama"] : [];
-  return candidates.find((candidate) => existsSync8(candidate));
+  return candidates.find((candidate) => existsSync9(candidate));
 }
 function prepareLocalModel(runner, model) {
   if (runner === "fastflowlm") {
@@ -4168,7 +4441,7 @@ function getSystemProfile() {
 }
 
 // src/kernel/system/repos.ts
-import { existsSync as existsSync9 } from "fs";
+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");
@@ -4277,7 +4550,7 @@ var C = {
 };
 var SUPPORTED_AGENTS = ["opencode"];
 function agentsMdPresent(cwd = process.cwd()) {
-  return existsSync10(join9(cwd, "AGENTS.md"));
+  return existsSync11(join10(cwd, "AGENTS.md"));
 }
 function printStatus() {
   const installed = hasCommand("opencode");
@@ -4319,13 +4592,13 @@ var agentCommand = new Command("agent").description("Provision and inspect the a
 
 // src/cli/commands/bridge.ts
 import { readdirSync as readdirSync2 } from "fs";
-import { homedir as homedir7 } from "os";
-import { join as join10 } from "path";
+import { homedir as homedir8 } from "os";
+import { join as join11 } from "path";
 import { Command as Command2 } from "commander";
 
 // src/cli/llm/client.ts
 import { spawn } from "child_process";
-import { existsSync as existsSync11 } from "fs";
+import { existsSync as existsSync12 } from "fs";
 var DEFAULT_LLM_URL = "http://localhost:8000/v1";
 var DEFAULT_LLM_MODEL = "qwen3.5:4b";
 var DEFAULT_LLM_API_KEY = "sk-none";
@@ -4338,6 +4611,16 @@ async function getLlmConfig(db) {
     locale: await getSetting(db, "system.locale") || "en"
   };
 }
+async function getVisionConfig(db) {
+  const base = await getLlmConfig(db);
+  return {
+    enabled: await getSetting(db, "llm.vision.enabled") === "true",
+    url: await getSetting(db, "llm.vision.url") || base.url,
+    model: await getSetting(db, "llm.vision.model") || base.model,
+    apiKey: await getSetting(db, "llm.vision.api_key") || base.apiKey,
+    locale: base.locale
+  };
+}
 var LANGUAGE_NAMES = {
   en: "English",
   de: "German",
@@ -4531,6 +4814,38 @@ async function getAvailableModels(url, apiKey = DEFAULT_LLM_API_KEY) {
     return [];
   }
 }
+async function checkVisionReadiness(db) {
+  const { enabled, url, model, apiKey } = await getVisionConfig(db);
+  const visionModelSetting = await getSetting(db, "llm.vision.model");
+  const visionModelExplicit = !!visionModelSetting;
+  let online = false;
+  let availableModels = [];
+  let modelAvailable = false;
+  if (enabled) {
+    online = await isLlmOnline(url);
+    if (online) {
+      availableModels = await getAvailableModels(url, apiKey);
+      modelAvailable = availableModels.length === 0 || availableModels.some(
+        (candidate) => candidate.toLowerCase() === model.toLowerCase()
+      );
+    }
+  }
+  let warning;
+  if (enabled && online && modelAvailable && !visionModelExplicit) {
+    warning = `No explicit vision model configured (llm.vision.model). Falling back to base model "${model}", which may not support image input. Set a multimodal model: zam settings set llm.vision.model <model>`;
+  }
+  return {
+    enabled,
+    online,
+    url,
+    model,
+    modelAvailable,
+    availableModels,
+    usable: enabled && online && modelAvailable,
+    visionModelExplicit,
+    warning
+  };
+}
 function detectRunner(url, model) {
   let runner = "unknown";
   let port = "8000";
@@ -4551,7 +4866,7 @@ function spawnLocalRunner(url, model) {
   const { runner, port } = detectRunner(url, model);
   try {
     if (runner === "fastflowlm") {
-      const flmExe = existsSync11("C:\\Program Files\\flm\\flm.exe") ? "C:\\Program Files\\flm\\flm.exe" : "flm";
+      const flmExe = existsSync12("C:\\Program Files\\flm\\flm.exe") ? "C:\\Program Files\\flm\\flm.exe" : "flm";
       if (!hasCommand("flm") && flmExe === "flm") return;
       spawn(flmExe, ["serve", model, "--port", port], {
         detached: true,
@@ -4572,7 +4887,7 @@ function spawnLocalRunner(url, model) {
 async function startLocalRunner(url, model, locale) {
   const { runner, port } = detectRunner(url, model);
   if (runner === "fastflowlm") {
-    const flmExe = existsSync11("C:\\Program Files\\flm\\flm.exe") ? "C:\\Program Files\\flm\\flm.exe" : "flm";
+    const flmExe = existsSync12("C:\\Program Files\\flm\\flm.exe") ? "C:\\Program Files\\flm\\flm.exe" : "flm";
     if (!hasCommand("flm") && flmExe === "flm") {
       console.warn(
         "\x1B[31m\u2717 FastFlowLM is configured but could not be found on the system.\x1B[0m"
@@ -4839,6 +5154,266 @@ async function ensureHighQualityQuestion(db, token) {
   return null;
 }
 
+// src/cli/llm/vision.ts
+import { readFileSync as readFileSync9 } from "fs";
+import { basename as basename2 } from "path";
+var LANGUAGE_NAMES2 = {
+  en: "English",
+  de: "German",
+  es: "Spanish",
+  fr: "French",
+  pt: "Portuguese",
+  zh: "Chinese",
+  ja: "Japanese"
+};
+var OBSERVATION_KINDS2 = /* @__PURE__ */ new Set([
+  "progress",
+  "step-completed",
+  "error",
+  "help-seeking",
+  "uncertain",
+  "privacy-pause",
+  "heartbeat"
+]);
+var ACTION_TYPES2 = /* @__PURE__ */ new Set([
+  "click",
+  "shortcut",
+  "typing",
+  "scroll",
+  "window-change"
+]);
+async function observeUiSnapshotViaLLM(db, input8) {
+  const cfg = await getVisionConfig(db);
+  if (!cfg.enabled) {
+    throw new Error(
+      "Vision observation is disabled in settings (llm.vision.enabled)"
+    );
+  }
+  const imageBytes = readFileSync9(input8.imagePath);
+  const imageUrl = `data:image/png;base64,${imageBytes.toString("base64")}`;
+  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,
+    input: input8
+  });
+  let draft;
+  try {
+    draft = extractDraft(content);
+  } catch {
+    return uncertainReport(
+      input8,
+      "Vision model returned output that could not be parsed as JSON."
+    );
+  }
+  const report = buildReport(input8, draft);
+  if (!isUiObservationReport(report)) {
+    return uncertainReport(
+      input8,
+      "Vision model returned an invalid UI report draft."
+    );
+  }
+  return report;
+}
+async function requestVisionDraft(args) {
+  const language = LANGUAGE_NAMES2[args.locale] ?? "English";
+  const schema = `{
+  "kind": "progress | step-completed | error | help-seeking | uncertain",
+  "summary": "short factual UI summary in ${language}",
+  "actions": [{"type": "click | shortcut | typing | scroll | window-change", "target": "optional UI target", "result": "optional visible result"}],
+  "candidateTokens": [{"slug": "optional-kebab-case-skill-token", "confidence": 0.0, "rationale": "why this token may matter"}],
+  "confidence": 0.0
+}`;
+  const res = await fetchWithInteractiveTimeout(
+    `${args.url}/chat/completions`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${args.apiKey}`
+      },
+      body: JSON.stringify({
+        model: args.model,
+        messages: [
+          {
+            role: "system",
+            content: "You are ZAM's UI observer. Return only strict JSON. Do not include markdown, prose, or fields outside the requested schema."
+          },
+          {
+            role: "user",
+            content: [
+              {
+                type: "text",
+                text: `Observe this Windows 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}`
+              },
+              {
+                type: "image_url",
+                image_url: { url: args.imageUrl }
+              }
+            ]
+          }
+        ],
+        temperature: 0,
+        max_tokens: args.input.maxTokens ?? 450
+      }),
+      locale: args.locale,
+      hardTimeoutMs: args.input.hardTimeoutMs ?? 18e4
+    }
+  );
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    if (errorText.includes("image") && (errorText.includes("not support") || errorText.includes("unsupported"))) {
+      throw new Error(
+        `Vision model "${args.model}" does not support image input. Set a multimodal model: zam settings set llm.vision.model <model>`
+      );
+    }
+    throw new Error(
+      `Vision LLM request failed: ${res.statusText} (${res.status}) - ${errorText}`
+    );
+  }
+  const data = await res.json();
+  if (data.error !== void 0) {
+    const errorMsg = formatModelError(data.error);
+    if (errorMsg.includes("image") && (errorMsg.includes("not support") || errorMsg.includes("unsupported"))) {
+      throw new Error(
+        `Vision model "${args.model}" does not support image input. Set a multimodal model: zam settings set llm.vision.model <model>`
+      );
+    }
+    throw new Error(`Vision model failed: ${errorMsg}`);
+  }
+  const content = data.choices?.[0]?.message?.content;
+  if (!content || typeof content !== "string") {
+    throw new Error("Empty response from vision model");
+  }
+  return content.trim();
+}
+function extractDraft(content) {
+  const fenced = content.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = (fenced?.[1] ?? content).trim();
+  try {
+    return JSON.parse(candidate);
+  } catch {
+    const start = candidate.indexOf("{");
+    const end = candidate.lastIndexOf("}");
+    if (start === -1 || end <= start) throw new Error("no JSON object found");
+    return JSON.parse(
+      candidate.slice(start, end + 1)
+    );
+  }
+}
+function buildReport(input8, draft) {
+  return {
+    version: UI_OBSERVATION_PROTOCOL_VERSION,
+    sessionId: input8.sessionId,
+    sequence: input8.sequence,
+    observedFrom: input8.observedFrom,
+    observedTo: input8.observedTo,
+    kind: parseKind(draft.kind),
+    application: input8.application,
+    summary: parseSummary(draft.summary),
+    actions: parseActions(draft.actions),
+    evidence: [
+      {
+        type: "keyframe",
+        ref: input8.evidenceRef ?? basename2(input8.imagePath),
+        redacted: input8.redacted ?? false
+      }
+    ],
+    candidateTokens: parseCandidateTokens(draft.candidateTokens),
+    confidence: parseConfidence(draft.confidence, 0.35)
+  };
+}
+function uncertainReport(input8, summary) {
+  return {
+    version: UI_OBSERVATION_PROTOCOL_VERSION,
+    sessionId: input8.sessionId,
+    sequence: input8.sequence,
+    observedFrom: input8.observedFrom,
+    observedTo: input8.observedTo,
+    kind: "uncertain",
+    application: input8.application,
+    summary,
+    actions: [],
+    evidence: [
+      {
+        type: "keyframe",
+        ref: input8.evidenceRef ?? basename2(input8.imagePath),
+        redacted: input8.redacted ?? false
+      }
+    ],
+    candidateTokens: [],
+    confidence: 0.1
+  };
+}
+function parseKind(value) {
+  if (typeof value === "string" && OBSERVATION_KINDS2.has(value)) {
+    return value;
+  }
+  return "uncertain";
+}
+function parseSummary(value) {
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value.trim();
+  }
+  return "Vision model did not provide a factual UI summary.";
+}
+function parseActions(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (!isRecord2(item) || typeof item.type !== "string") return [];
+    if (!ACTION_TYPES2.has(item.type)) return [];
+    const action = { type: item.type };
+    if (typeof item.target === "string" && item.target.trim()) {
+      action.target = item.target.trim();
+    }
+    if (typeof item.result === "string" && item.result.trim()) {
+      action.result = item.result.trim();
+    }
+    return [action];
+  });
+}
+function parseCandidateTokens(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (!isRecord2(item)) return [];
+    if (typeof item.slug !== "string" || !/^[A-Za-z0-9._-]+$/.test(item.slug)) {
+      return [];
+    }
+    if (typeof item.rationale !== "string" || !item.rationale.trim()) {
+      return [];
+    }
+    return [
+      {
+        slug: item.slug,
+        confidence: parseConfidence(item.confidence, 0.2),
+        rationale: item.rationale.trim()
+      }
+    ];
+  });
+}
+function parseConfidence(value, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.max(0, Math.min(1, value));
+}
+function formatModelError(error) {
+  if (typeof error === "string") return error;
+  if (isRecord2(error) && typeof error.message === "string") {
+    return error.message;
+  }
+  return JSON.stringify(error);
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/cli/commands/resolve-user.ts
 async function ensureDefaultUser(db, preferredUserId) {
   const stored = await getSetting(db, "user.id");
@@ -4892,6 +5467,13 @@ function jsonError(message) {
   console.log(JSON.stringify({ error: message }, null, 2));
   process.exit(1);
 }
+function parseNonNegativeIntegerOption(name, value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    jsonError(`${name} must be a non-negative integer`);
+  }
+  return parsed;
+}
 async function withDb2(fn) {
   await withDb(fn, jsonError);
 }
@@ -4932,15 +5514,16 @@ function parseTokenUpdates(opts) {
 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)").action(async (opts) => {
+bridgeCommand.command("check-due").description("Check due cards for a user (JSON)").option("--user <id>", "User ID (default: whoami)").option("--domain <domain>", "Filter by knowledge domain").action(async (opts) => {
   await withDb2(async (db) => {
     const userId = await resolveUser(opts, db, { json: true });
-    const dueCards = await getDueCards(db, userId);
+    const dueCards = await getDueCards(db, userId, void 0, opts.domain);
     const domains = [
       ...new Set(dueCards.map((c) => c.domain).filter(Boolean))
     ].sort();
     jsonOut2({
       userId,
+      domain: opts.domain ?? null,
       dueCount: dueCards.length,
       domains,
       cards: dueCards.map((c) => ({
@@ -5131,6 +5714,45 @@ bridgeCommand.command("get-skill").description("Get an agent skill by slug (JSON
     });
   });
 });
+bridgeCommand.command("start-session").description("Start a ZAM learning session (JSON)").requiredOption("--task <task>", "Session task description").option(
+  "--context <context>",
+  "Execution context: shell | ui | reallife",
+  "shell"
+).option("--user <id>", "User ID (default: whoami)").action(async (opts) => {
+  const context = opts.context;
+  if (!["shell", "ui", "reallife"].includes(context)) {
+    jsonError("context must be shell, ui, or reallife");
+  }
+  await withDb2(async (db) => {
+    const userId = await resolveUser(opts, db, { json: true });
+    const session = await startSession(db, {
+      user_id: userId,
+      task: opts.task,
+      execution_context: context
+    });
+    jsonOut2({
+      id: session.id,
+      userId: session.user_id,
+      task: session.task,
+      executionContext: session.execution_context,
+      startedAt: session.started_at,
+      completedAt: session.completed_at
+    });
+  });
+});
+bridgeCommand.command("end-session").description("Complete an active ZAM learning session (JSON)").requiredOption("--session <id>", "Session ID").action(async (opts) => {
+  await withDb2(async (db) => {
+    const session = await endSession(db, opts.session);
+    jsonOut2({
+      id: session.id,
+      userId: session.user_id,
+      task: session.task,
+      executionContext: session.execution_context,
+      startedAt: session.started_at,
+      completedAt: session.completed_at
+    });
+  });
+});
 bridgeCommand.command("get-monitor").description("Read monitor log for a session (JSON)").requiredOption("--session <id>", "Session ID").action((opts) => {
   if (!monitorLogExists(opts.session)) {
     jsonOut2({
@@ -5272,7 +5894,7 @@ bridgeCommand.command("discover-skills").description(
   "20"
 ).action(async (opts) => {
   try {
-    const monitorDir = join10(homedir7(), ".zam", "monitor");
+    const monitorDir = join11(homedir8(), ".zam", "monitor");
     let files;
     try {
       files = readdirSync2(monitorDir).filter((f) => f.endsWith(".jsonl"));
@@ -5285,7 +5907,7 @@ bridgeCommand.command("discover-skills").description(
       return;
     }
     const limit = Number(opts.limit);
-    const sorted = files.map((f) => ({ name: f, path: join10(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
+    const sorted = files.map((f) => ({ name: f, path: join11(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", "");
@@ -5320,6 +5942,81 @@ bridgeCommand.command("discover-skills").description(
     jsonError(err.message);
   }
 });
+bridgeCommand.command("observe-ui-watch").description(
+  "Poll live UI observer watch reports for a ZAM learning session (JSON)"
+).requiredOption(
+  "--session <id>",
+  "ZAM session ID (also the observer log key)"
+).option("--after <n>", "Only return observations after this sequence").option("--limit <n>", "Maximum observations to return", "100").action(async (opts) => {
+  await withDb2(async (db) => {
+    const session = await db.prepare("SELECT id, execution_context FROM sessions WHERE id = ?").get(opts.session);
+    if (!session) {
+      jsonError(`Session not found: ${opts.session}`);
+    }
+    const after = opts.after === void 0 ? void 0 : parseNonNegativeIntegerOption("after", opts.after);
+    const limit = parseNonNegativeIntegerOption("limit", opts.limit);
+    const observations = readUiObservationLog(opts.session).filter((report) => after === void 0 || report.sequence > after).slice(0, limit);
+    const last = observations[observations.length - 1];
+    jsonOut2({
+      sessionId: opts.session,
+      executionContext: session.execution_context,
+      observationSource: "ui",
+      logExists: uiObservationLogExists(opts.session),
+      after: after ?? null,
+      count: observations.length,
+      nextSequence: last?.sequence ?? after ?? null,
+      observations
+    });
+  });
+});
+bridgeCommand.command("get-observations").description("Read UI observer reports for a session (JSON)").requiredOption("--session <id>", "Observer session ID").option("--after <n>", "Only return observations after this sequence").option("--limit <n>", "Maximum observations to return", "100").action((opts) => {
+  try {
+    const after = opts.after === void 0 ? void 0 : parseNonNegativeIntegerOption("after", opts.after);
+    const limit = parseNonNegativeIntegerOption("limit", opts.limit);
+    const observations = readUiObservationLog(opts.session).filter((report) => after === void 0 || report.sequence > after).slice(0, limit);
+    const last = observations[observations.length - 1];
+    jsonOut2({
+      sessionId: opts.session,
+      after: after ?? null,
+      count: observations.length,
+      nextSequence: last?.sequence ?? after ?? null,
+      observations
+    });
+  } catch (err) {
+    jsonError(err.message);
+  }
+});
+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) => {
+  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);
+  const hardTimeoutMs = opts.timeout === void 0 ? void 0 : parseNonNegativeIntegerOption("timeout", opts.timeout);
+  await withDb2(async (db) => {
+    const report = await observeUiSnapshotViaLLM(db, {
+      sessionId: opts.session,
+      sequence,
+      observedFrom: opts.observedFrom,
+      observedTo: opts.observedTo,
+      imagePath: opts.image,
+      application: {
+        processName: opts.processName,
+        processId,
+        windowTitle: opts.windowTitle
+      },
+      evidenceRef: opts.evidenceRef,
+      redacted: opts.redacted === true,
+      model: opts.model,
+      maxTokens,
+      hardTimeoutMs
+    });
+    if (opts.writeLog === true) {
+      appendUiObservationReport(report);
+    }
+    jsonOut2(report);
+  });
+});
 bridgeCommand.command("check-llm").description("Check if LLM is enabled and online (JSON)").action(async () => {
   await withDb2(async (db) => {
     const { enabled, url, model, apiKey } = await getLlmConfig(db);
@@ -5345,6 +6042,13 @@ bridgeCommand.command("check-llm").description("Check if LLM is enabled and onli
     });
   });
 });
+bridgeCommand.command("check-vision").description(
+  "Check if UI observer vision analysis is enabled and ready (JSON)"
+).action(async () => {
+  await withDb2(async (db) => {
+    jsonOut2(await checkVisionReadiness(db));
+  });
+});
 bridgeCommand.command("ensure-llm").description(
   "Start the local LLM server if needed and report readiness (JSON)"
 ).option(
@@ -5532,7 +6236,7 @@ bridgeCommand.command("get-neighborhood").description(
 bridgeCommand.command("serve").description("Start the persistent JSON-RPC stdin/stdout server").option("--stdin", "Use stdin/stdout for communication").action(async (_opts) => {
   isServeMode = true;
   const {
-    appendFileSync: appendFileSync3,
+    appendFileSync: appendFileSync4,
     existsSync: fileExists,
     mkdirSync: makeDir
   } = await import("fs");
@@ -5543,7 +6247,7 @@ bridgeCommand.command("serve").description("Start the persistent JSON-RPC stdin/
   const logDiag = (msg) => {
     try {
       if (!fileExists(logDir)) makeDir(logDir, { recursive: true });
-      appendFileSync3(logPath, `[${(/* @__PURE__ */ new Date()).toISOString()}] ${msg}
+      appendFileSync4(logPath, `[${(/* @__PURE__ */ new Date()).toISOString()}] ${msg}
 `);
     } catch {
     }
@@ -5654,10 +6358,10 @@ 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("--json", "Output as JSON").option("--summary", "Show only counts per domain (no slugs or concepts)").action(async (opts) => {
+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) => {
   await withDb(async (db) => {
     const userId = await resolveUser(opts, db);
-    const dueCards = await getDueCards(db, userId);
+    const dueCards = await getDueCards(db, userId, void 0, opts.domain);
     if (opts.json) {
       console.log(JSON.stringify(dueCards, null, 2));
       return;
@@ -5994,19 +6698,19 @@ 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 existsSync12, writeFileSync as writeFileSync5 } from "fs";
-import { join as join11 } from "path";
+import { chmodSync as chmodSync2, existsSync as existsSync13, writeFileSync as writeFileSync5 } from "fs";
+import { join as join12 } from "path";
 import { Command as Command5 } from "commander";
 function installHook2() {
-  const gitDir = join11(process.cwd(), ".git");
-  if (!existsSync12(gitDir)) {
+  const gitDir = join12(process.cwd(), ".git");
+  if (!existsSync13(gitDir)) {
     console.error(
       "Error: Current directory is not the root of a Git repository."
     );
     process.exit(1);
   }
-  const hooksDir = join11(gitDir, "hooks");
-  const hookPath = join11(hooksDir, "post-commit");
+  const hooksDir = join12(gitDir, "hooks");
+  const hookPath = join12(hooksDir, "post-commit");
   const hookContent = `#!/bin/sh
 # ZAM Spaced Repetition Auto-Stale Hook
 # Triggered automatically on git commits to decay modified concept cards.
@@ -6115,7 +6819,7 @@ ZAM Auto-Stale Complete: Scanned ${changedFiles.length} file(s).`
 });
 
 // src/cli/commands/goal.ts
-import { existsSync as existsSync13, mkdirSync as mkdirSync6 } from "fs";
+import { existsSync as existsSync14, mkdirSync as mkdirSync7 } from "fs";
 import { resolve as resolve3 } from "path";
 import { input as input2 } from "@inquirer/prompts";
 import { Command as Command6 } from "commander";
@@ -6139,7 +6843,7 @@ goalCommand.command("list").description("List all goals").option(
   "Filter by status (active, completed, paused, abandoned)"
 ).option("--tree", "Show goals as a tree with parent/child relationships").option("--json", "Output as JSON").action(async (opts) => {
   const goalsDir = await resolveGoalsDir();
-  if (!existsSync13(goalsDir)) {
+  if (!existsSync14(goalsDir)) {
     console.error(`Goals directory not found: ${goalsDir}`);
     console.error(
       "Set it with: zam settings set personal.goals_dir /path/to/goals"
@@ -6240,8 +6944,8 @@ ${"\u2500".repeat(50)}`);
 });
 goalCommand.command("create").description("Create a new goal").option("--slug <slug>", "Goal slug (used as filename)").option("--title <title>", "Goal title").option("--parent <slug>", "Parent goal slug").option("--description <text>", "Goal description").option("--json", "Output as JSON").action(async (opts) => {
   const goalsDir = await resolveGoalsDir();
-  if (!existsSync13(goalsDir)) {
-    mkdirSync6(goalsDir, { recursive: true });
+  if (!existsSync14(goalsDir)) {
+    mkdirSync7(goalsDir, { recursive: true });
   }
   let slug = opts.slug;
   let title = opts.title;
@@ -6300,21 +7004,21 @@ goalCommand.command("status <slug> <status>").description("Update a goal's statu
 });
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync14, mkdirSync as mkdirSync7, writeFileSync as writeFileSync6 } from "fs";
-import { homedir as homedir8 } from "os";
-import { join as join12 } from "path";
+import { existsSync as existsSync15, mkdirSync as mkdirSync8, writeFileSync as writeFileSync6 } from "fs";
+import { homedir as homedir9 } from "os";
+import { join as join13 } from "path";
 import { confirm, input as input3 } from "@inquirer/prompts";
 import { Command as Command7 } from "commander";
-var HOME2 = homedir8();
+var HOME2 = homedir9();
 function printLine(char = "\u2550", len = 60, color = "\x1B[36m") {
   console.log(`${color}${char.repeat(len)}\x1B[0m`);
 }
 function bootstrapSandboxWorkspace(workspaceDir) {
-  mkdirSync7(join12(workspaceDir, "beliefs"), { recursive: true });
-  mkdirSync7(join12(workspaceDir, "goals"), { recursive: true });
-  mkdirSync7(join12(workspaceDir, "skills"), { recursive: true });
-  const worldviewFile = join12(workspaceDir, "beliefs", "worldview.md");
-  if (!existsSync14(worldviewFile)) {
+  mkdirSync8(join13(workspaceDir, "beliefs"), { recursive: true });
+  mkdirSync8(join13(workspaceDir, "goals"), { recursive: true });
+  mkdirSync8(join13(workspaceDir, "skills"), { recursive: true });
+  const worldviewFile = join13(workspaceDir, "beliefs", "worldview.md");
+  if (!existsSync15(worldviewFile)) {
     writeFileSync6(
       worldviewFile,
       `# Personal Worldview
@@ -6327,8 +7031,8 @@ Here, I declare the core concepts and principles I want to master.
       "utf8"
     );
   }
-  const goalsFile = join12(workspaceDir, "goals", "goals.md");
-  if (!existsSync14(goalsFile)) {
+  const goalsFile = join13(workspaceDir, "goals", "goals.md");
+  if (!existsSync15(goalsFile)) {
     writeFileSync6(
       goalsFile,
       `# Personal Goals
@@ -6351,7 +7055,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 = join12(HOME2, "Documents", "zam");
+  const defaultWorkspace = join13(HOME2, "Documents", "zam");
   const workspacePath = await input3({
     message: "Choose your ZAM workspace directory:",
     default: defaultWorkspace
@@ -7051,7 +7755,7 @@ ${"\u2550".repeat(50)}`);
 import { execFileSync as execFileSync2, execSync as execSync5 } from "child_process";
 import { unlinkSync, writeFileSync as writeFileSync7 } from "fs";
 import { tmpdir } from "os";
-import { basename as basename2, join as join13 } from "path";
+import { basename as basename3, join as join14 } from "path";
 import { Command as Command9 } from "commander";
 function isPowerShellShell(shell) {
   return shell === "pwsh" || shell === "powershell";
@@ -7073,7 +7777,7 @@ function detectShell() {
   if (process.platform === "win32")
     return findExecutable("pwsh.exe") ? "pwsh" : "powershell";
   const shell = process.env.SHELL ?? "";
-  return basename2(shell) === "bash" ? "bash" : "zsh";
+  return basename3(shell) === "bash" ? "bash" : "zsh";
 }
 var monitorCommand = new Command9("monitor").description(
   "Shell observation for real-time task monitoring"
@@ -7216,8 +7920,8 @@ function resolveZamInvocation(shell) {
   if (installed) {
     return isPowerShellShell(shell) ? `& ${psSingleQuoted2(installed)}` : installed;
   }
-  const projectRoot = join13(import.meta.dirname, "..", "..", "..");
-  const cliSource = join13(projectRoot, "src/cli/index.ts");
+  const projectRoot = join14(import.meta.dirname, "..", "..", "..");
+  const cliSource = join14(projectRoot, "src/cli/index.ts");
   if (isPowerShellShell(shell)) {
     return `& npx --prefix ${psSingleQuoted2(projectRoot)} tsx ${psSingleQuoted2(cliSource)}`;
   }
@@ -7307,7 +8011,7 @@ end tell` : `tell application "Terminal"
   activate
   do script "${escaped}"
 end tell`;
-  const tmpFile = join13(tmpdir(), `zam-monitor-${sessionId}.scpt`);
+  const tmpFile = join14(tmpdir(), `zam-monitor-${sessionId}.scpt`);
   try {
     writeFileSync7(tmpFile, appleScript);
     execSync5(`osascript ${JSON.stringify(tmpFile)}`, { stdio: "ignore" });
@@ -7358,8 +8062,8 @@ Run this manually in a new PowerShell terminal:
 }
 
 // src/cli/commands/profile.ts
-import { homedir as homedir9 } from "os";
-import { dirname as dirname5, join as join14, resolve as resolve4 } from "path";
+import { homedir as homedir10 } from "os";
+import { dirname as dirname5, join as join15, resolve as resolve4 } from "path";
 import { Command as Command10 } from "commander";
 var C2 = {
   reset: "\x1B[0m",
@@ -7369,7 +8073,7 @@ var C2 = {
   green: "\x1B[32m"
 };
 function defaultPersonalDir() {
-  return join14(homedir9(), "Documents", "zam");
+  return join15(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}`;
@@ -7530,7 +8234,7 @@ ${"\u2550".repeat(50)}`);
 });
 
 // src/cli/commands/session.ts
-import { readFileSync as readFileSync8 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 import { input as input6, select as select2 } from "@inquirer/prompts";
 import { Command as Command12 } from "commander";
 var sessionCommand = new Command12("session").description(
@@ -7711,7 +8415,7 @@ function loadPatternFile(path) {
   if (!path) return [];
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync8(path, "utf-8"));
+    parsed = JSON.parse(readFileSync10(path, "utf-8"));
   } catch (err) {
     throw new Error(
       `Cannot read synthesis patterns from ${path}: ${err.message}`
@@ -7901,11 +8605,23 @@ sessionCommand.command("end").description("End a session and show summary").requ
 });
 
 // src/cli/commands/settings.ts
-import { existsSync as existsSync15 } from "fs";
+import { existsSync as existsSync16 } from "fs";
 import { Command as Command13 } from "commander";
 var settingsCommand = new Command13("settings").description(
   "Manage user settings"
 );
+var BOOLEAN_SETTING_KEYS = /* @__PURE__ */ new Set(["llm.enabled", "llm.vision.enabled"]);
+function normalizeSettingValue(key, value) {
+  if (!BOOLEAN_SETTING_KEYS.has(key)) return value;
+  const lower = value.toLowerCase();
+  if (lower === "on" || lower === "enable" || lower === "enabled" || lower === "true") {
+    return "true";
+  }
+  if (lower === "off" || lower === "disable" || lower === "disabled" || lower === "false") {
+    return "false";
+  }
+  return value;
+}
 settingsCommand.command("show").description("Show all settings").option("--json", "Output as JSON").action(async (opts) => {
   await withDb(async (db) => {
     if (opts.json) {
@@ -7943,15 +8659,7 @@ settingsCommand.command("get <key>").description("Get a single setting").option(
 });
 settingsCommand.command("set <key> <value>").description("Set a setting").option("--quiet", "Suppress output").action(async (key, value, opts) => {
   await withDb(async (db) => {
-    let parsedVal = value;
-    if (key === "llm.enabled") {
-      const lower = value.toLowerCase();
-      if (lower === "on" || lower === "enable" || lower === "enabled" || lower === "true") {
-        parsedVal = "true";
-      } else if (lower === "off" || lower === "disable" || lower === "disabled" || lower === "false") {
-        parsedVal = "false";
-      }
-    }
+    const parsedVal = normalizeSettingValue(key, value);
     await setSetting(db, key, parsedVal);
     if (!opts.quiet) {
       console.log(`Set ${key} = ${parsedVal}`);
@@ -8056,7 +8764,7 @@ settingsCommand.command("repos").description("Show or set Personal, Team, and Or
     console.log("\nValidation:");
     for (const [name, path] of Object.entries(paths)) {
       if (path) {
-        const exists = existsSync15(path);
+        const exists = existsSync16(path);
         console.log(
           `  ${name.padEnd(9)}: ${exists ? "\x1B[32m\u2713 Valid folder\x1B[0m" : "\x1B[31m\u2717 Directory does not exist\x1B[0m"}`
         );
@@ -8068,41 +8776,41 @@ settingsCommand.command("repos").description("Show or set Personal, Team, and Or
 });
 
 // src/cli/commands/setup.ts
-import { copyFileSync as copyFileSync2, existsSync as existsSync16, mkdirSync as mkdirSync8, writeFileSync as writeFileSync8 } from "fs";
-import { basename as basename3, dirname as dirname6, join as join15 } from "path";
+import { copyFileSync as copyFileSync2, existsSync as existsSync17, mkdirSync as mkdirSync9, writeFileSync as writeFileSync8 } from "fs";
+import { basename as basename4, dirname as dirname6, join as join16 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command as Command14 } from "commander";
 var packageRoot = [
   fileURLToPath2(new URL("../..", import.meta.url)),
   fileURLToPath2(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync16(join15(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
+].find((candidate) => existsSync17(join16(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
 var SKILL_PAIRS = [
   {
-    from: join15(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
-    to: join15(".claude", "skills", "zam", "SKILL.md")
+    from: join16(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
+    to: join16(".claude", "skills", "zam", "SKILL.md")
   },
   {
-    from: join15(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
-    to: join15(".agent", "skills", "zam", "SKILL.md")
+    from: join16(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
+    to: join16(".agent", "skills", "zam", "SKILL.md")
   },
   {
-    from: join15(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
-    to: join15(".agents", "skills", "zam", "SKILL.md")
+    from: join16(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
+    to: join16(".agents", "skills", "zam", "SKILL.md")
   }
 ];
 function copySkills(force, cwd = process.cwd()) {
   let anyAction = false;
   for (const { from, to } of SKILL_PAIRS) {
-    const dest = join15(cwd, to);
-    if (!existsSync16(from)) {
+    const dest = join16(cwd, to);
+    if (!existsSync17(from)) {
       console.warn(`  warn  source not found, skipping: ${from}`);
       continue;
     }
-    if (existsSync16(dest) && !force) {
+    if (existsSync17(dest) && !force) {
       console.log(`  skip  ${to} (already present \xE2\u20AC\u201D use --force to update)`);
       continue;
     }
-    mkdirSync8(dirname6(dest), { recursive: true });
+    mkdirSync9(dirname6(dest), { recursive: true });
     copyFileSync2(from, dest);
     console.log(`  copy  ${to}`);
     anyAction = true;
@@ -8131,12 +8839,12 @@ async function initDatabase(skipInit) {
 }
 function writeClaudeMd(skipClaudeMd, cwd = process.cwd()) {
   if (skipClaudeMd) return;
-  const dest = join15(cwd, "CLAUDE.md");
-  if (existsSync16(dest)) {
+  const dest = join16(cwd, "CLAUDE.md");
+  if (existsSync17(dest)) {
     console.log(`  skip  CLAUDE.md (already present)`);
     return;
   }
-  const name = basename3(cwd);
+  const name = basename4(cwd);
   writeFileSync8(
     dest,
     `# ZAM Personal Kernel \xE2\u20AC\u201D ${name}
@@ -8165,12 +8873,12 @@ Use \`zam connector setup turso\` to store cloud credentials in
 }
 function writeAgentsMd(skipAgentsMd, cwd = process.cwd()) {
   if (skipAgentsMd) return;
-  const dest = join15(cwd, "AGENTS.md");
-  if (existsSync16(dest)) {
+  const dest = join16(cwd, "AGENTS.md");
+  if (existsSync17(dest)) {
     console.log(`  skip  AGENTS.md (already present)`);
     return;
   }
-  const name = basename3(cwd);
+  const name = basename4(cwd);
   writeFileSync8(
     dest,
     `# ZAM Personal Kernel - ${name}
@@ -8311,9 +9019,9 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
 });
 
 // src/cli/commands/snapshot.ts
-import { existsSync as existsSync17, mkdirSync as mkdirSync9, readFileSync as readFileSync9, writeFileSync as writeFileSync9 } from "fs";
-import { homedir as homedir10 } from "os";
-import { dirname as dirname7, join as join16 } from "path";
+import { existsSync as existsSync18, mkdirSync as mkdirSync10, readFileSync as readFileSync11, writeFileSync as writeFileSync9 } from "fs";
+import { homedir as homedir11 } from "os";
+import { dirname as dirname7, join as join17 } from "path";
 import { Command as Command16 } from "commander";
 function defaultOutName() {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
@@ -8333,7 +9041,7 @@ var exportCmd = new Command16("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") || join16(homedir10(), "Documents", "zam");
+    const personalDir = await getSetting(db, "personal.workspace_dir") || join17(homedir11(), "Documents", "zam");
     await db.close();
     db = void 0;
     const manifest = verifySnapshot(snapshot);
@@ -8342,10 +9050,10 @@ var exportCmd = new Command16("export").description("Write a portable SQL-text s
       process.stdout.write(snapshot);
       return;
     }
-    const out = opts.out ?? join16(personalDir, "snapshots", defaultOutName());
+    const out = opts.out ?? join17(personalDir, "snapshots", defaultOutName());
     const dir = dirname7(out);
-    if (dir && dir !== "." && !existsSync17(dir)) {
-      mkdirSync9(dir, { recursive: true });
+    if (dir && dir !== "." && !existsSync18(dir)) {
+      mkdirSync10(dir, { recursive: true });
     }
     writeFileSync9(out, snapshot, "utf-8");
     console.log(`Snapshot written: ${out}`);
@@ -8361,11 +9069,11 @@ var exportCmd = new Command16("export").description("Write a portable SQL-text s
 var importCmd = new Command16("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 (!existsSync17(file)) {
+    if (!existsSync18(file)) {
       console.error(`Error: Snapshot file not found: ${file}`);
       process.exit(1);
     }
-    const snapshot = readFileSync9(file, "utf-8");
+    const snapshot = readFileSync11(file, "utf-8");
     db = await openDatabaseWithSync({ initialize: true });
     const result = await importSnapshot(db, snapshot, { force: opts.force });
     await db.close();
@@ -8383,11 +9091,11 @@ var importCmd = new Command16("import").description("Restore a snapshot into the
 });
 var verifyCmd = new Command16("verify").description("Check a snapshot's manifest and checksum without importing").argument("<file>", "Snapshot file to verify").action((file) => {
   try {
-    if (!existsSync17(file)) {
+    if (!existsSync18(file)) {
       console.error(`Error: Snapshot file not found: ${file}`);
       process.exit(1);
     }
-    const manifest = verifySnapshot(readFileSync9(file, "utf-8"));
+    const manifest = verifySnapshot(readFileSync11(file, "utf-8"));
     const { total, nonEmpty } = summarize(manifest.tables);
     console.log(`Valid snapshot (format v${manifest.version})`);
     console.log(`  created: ${manifest.createdAt}`);
@@ -8443,7 +9151,7 @@ import { Command as Command18 } from "commander";
 var tokenCommand = new Command18("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").action(async (opts) => {
+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) => {
   await withDb(async (db) => {
     let question = opts.question || null;
     if (!question) {
@@ -8461,6 +9169,7 @@ tokenCommand.command("register").description("Register a new knowledge token").r
       source_link: opts.sourceLink || null,
       question
     });
+    if (opts.quiet) return;
     if (opts.json) {
       console.log(JSON.stringify(token, null, 2));
     } else {
@@ -8475,9 +9184,10 @@ tokenCommand.command("register").description("Register a new knowledge token").r
     }
   });
 });
-tokenCommand.command("find").description("Fuzzy search for tokens").requiredOption("--query <query>", "Search query").option("--json", "Output as JSON").action(async (opts) => {
+tokenCommand.command("find").description("Fuzzy search for tokens").requiredOption("--query <query>", "Search query").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
   await withDb(async (db) => {
     const results = await findTokens(db, opts.query);
+    if (opts.quiet) return;
     if (opts.json) {
       console.log(JSON.stringify(results, null, 2));
       return;
@@ -8499,12 +9209,13 @@ tokenCommand.command("find").description("Fuzzy search for tokens").requiredOpti
     }
   });
 });
-tokenCommand.command("list").description("List all tokens").option("--domain <domain>", "Filter by domain").option("--json", "Output as JSON").action(async (opts) => {
+tokenCommand.command("list").description("List all tokens").option("--domain <domain>", "Filter by domain").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
   await withDb(async (db) => {
     const tokens = await listTokens(
       db,
       opts.domain ? { domain: opts.domain } : void 0
     );
+    if (opts.quiet) return;
     if (opts.json) {
       console.log(JSON.stringify(tokens, null, 2));
       return;
@@ -8532,7 +9243,7 @@ tokenCommand.command("edit").description("Edit a token's mutable fields").requir
 ).option(
   "--source-link <link>",
   "Updated source file path or reference URL (blank allowed)"
-).option("--question <question>", "Updated question text (blank allowed)").option("--json", "Output as JSON").action(async (opts) => {
+).option("--question <question>", "Updated question text (blank allowed)").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
   await withDb(async (db) => {
     const updates = {};
     if (opts.concept !== void 0) updates.concept = opts.concept;
@@ -8555,6 +9266,7 @@ tokenCommand.command("edit").description("Edit a token's mutable fields").requir
       updates.symbiosis_mode = opts.mode === "none" ? null : opts.mode;
     }
     const token = await updateToken(db, opts.slug, updates);
+    if (opts.quiet) return;
     if (opts.json) {
       jsonOut(token);
       return;
@@ -8569,7 +9281,7 @@ tokenCommand.command("edit").description("Edit a token's mutable fields").requir
     console.log(`  Source:   ${token.source_link || "(none)"}`);
   });
 });
-tokenCommand.command("prereq").description("Add a prerequisite edge between tokens").requiredOption("--token <slug>", "Token that requires a prerequisite").requiredOption("--requires <slug>", "Required prerequisite token").option("--json", "Output as JSON").action(async (opts) => {
+tokenCommand.command("prereq").description("Add a prerequisite edge between tokens").requiredOption("--token <slug>", "Token that requires a prerequisite").requiredOption("--requires <slug>", "Required prerequisite token").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
   await withDb(async (db) => {
     const token = await getTokenBySlug(db, opts.token);
     if (!token) {
@@ -8582,6 +9294,7 @@ tokenCommand.command("prereq").description("Add a prerequisite edge between toke
       process.exit(1);
     }
     await addPrerequisite(db, token.id, requires.id);
+    if (opts.quiet) return;
     if (opts.json) {
       console.log(
         JSON.stringify(
@@ -8599,9 +9312,10 @@ tokenCommand.command("prereq").description("Add a prerequisite edge between toke
 });
 tokenCommand.command("deprecate").description(
   "Mark a token as deprecated (excluded from reviews, not deleted)"
-).requiredOption("--slug <slug>", "Token slug to deprecate").option("--json", "Output as JSON").action(async (opts) => {
+).requiredOption("--slug <slug>", "Token slug to deprecate").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
   await withDb(async (db) => {
     const token = await deprecateToken(db, opts.slug);
+    if (opts.quiet) return;
     if (opts.json) {
       console.log(JSON.stringify(token, null, 2));
     } else {
@@ -8611,7 +9325,7 @@ tokenCommand.command("deprecate").description(
     }
   });
 });
-tokenCommand.command("delete").description("Hard-delete a token and its dependent learning data").requiredOption("--slug <slug>", "Token slug to delete").option("--force", "Actually delete the token").option("--json", "Output as JSON").action(async (opts) => {
+tokenCommand.command("delete").description("Hard-delete a token and its dependent learning data").requiredOption("--slug <slug>", "Token slug to delete").option("--force", "Actually delete the token").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
   await withDb(async (db) => {
     const impact = await getTokenDeleteImpact(db, opts.slug);
     if (!opts.force) {
@@ -8621,6 +9335,7 @@ tokenCommand.command("delete").description("Hard-delete a token and its dependen
         requiresForce: true,
         impact
       };
+      if (opts.quiet) return;
       if (opts.json) {
         jsonOut(preview);
         return;
@@ -8641,6 +9356,7 @@ tokenCommand.command("delete").description("Hard-delete a token and its dependen
       return;
     }
     const result = await deleteToken(db, opts.slug);
+    if (opts.quiet) return;
     if (opts.json) {
       jsonOut({
         slug: result.token.slug,
@@ -8656,7 +9372,7 @@ tokenCommand.command("delete").description("Hard-delete a token and its dependen
     console.log(`  Agent skills updated:  ${result.impact.agent_skills}`);
   });
 });
-tokenCommand.command("status").description("Show full status of a token for a user").requiredOption("--token <slug>", "Token slug").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").action(async (opts) => {
+tokenCommand.command("status").description("Show full status of a token for a user").requiredOption("--token <slug>", "Token slug").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
   await withDb(async (db) => {
     const userId = await resolveUser(opts, db);
     const token = await getTokenBySlug(db, opts.token);
@@ -8673,6 +9389,7 @@ tokenCommand.command("status").description("Show full status of a token for a us
       prerequisites: prereqs,
       dependents
     };
+    if (opts.quiet) return;
     if (opts.json) {
       console.log(JSON.stringify(status, null, 2));
       return;
@@ -8718,9 +9435,9 @@ tokenCommand.command("status").description("Show full status of a token for a us
 
 // src/cli/commands/ui.ts
 import { spawn as spawn2, spawnSync } from "child_process";
-import { existsSync as existsSync18 } from "fs";
-import { homedir as homedir11 } from "os";
-import { dirname as dirname8, join as join17 } from "path";
+import { existsSync as existsSync19 } from "fs";
+import { homedir as homedir12 } from "os";
+import { dirname as dirname8, join as join18 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { Command as Command19 } from "commander";
 var C3 = {
@@ -8736,8 +9453,8 @@ function findDesktopDir() {
   for (const start of starts) {
     let dir = start;
     for (let i = 0; i < 10; i++) {
-      if (existsSync18(join17(dir, "desktop", "src-tauri", "tauri.conf.json"))) {
-        return join17(dir, "desktop");
+      if (existsSync19(join18(dir, "desktop", "src-tauri", "tauri.conf.json"))) {
+        return join18(dir, "desktop");
       }
       const parent = dirname8(dir);
       if (parent === dir) break;
@@ -8747,30 +9464,30 @@ function findDesktopDir() {
   return null;
 }
 function findBuiltApp(desktopDir) {
-  const releaseDir = join17(desktopDir, "src-tauri", "target", "release");
+  const releaseDir = join18(desktopDir, "src-tauri", "target", "release");
   if (process.platform === "win32") {
     for (const name of ["ZAM.exe", "zam.exe", "zam-desktop.exe"]) {
-      const p = join17(releaseDir, name);
-      if (existsSync18(p)) return p;
+      const p = join18(releaseDir, name);
+      if (existsSync19(p)) return p;
     }
   } else if (process.platform === "darwin") {
-    const app = join17(releaseDir, "bundle", "macos", "ZAM.app");
-    if (existsSync18(app)) return app;
+    const app = join18(releaseDir, "bundle", "macos", "ZAM.app");
+    if (existsSync19(app)) return app;
   } else {
     for (const name of ["zam", "ZAM", "zam-desktop"]) {
-      const p = join17(releaseDir, name);
-      if (existsSync18(p)) return p;
+      const p = join18(releaseDir, name);
+      if (existsSync19(p)) return p;
     }
   }
   return null;
 }
 function findInstalledApp() {
   const candidates = process.platform === "win32" ? [
-    process.env.LOCALAPPDATA && join17(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
-    process.env.ProgramFiles && join17(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
-    process.env["ProgramFiles(x86)"] && join17(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
-  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join17(homedir11(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
-  return candidates.find((candidate) => candidate && existsSync18(candidate)) || null;
+    process.env.LOCALAPPDATA && join18(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
+    process.env.ProgramFiles && join18(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
+    process.env["ProgramFiles(x86)"] && join18(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
+  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join18(homedir12(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
+  return candidates.find((candidate) => candidate && existsSync19(candidate)) || null;
 }
 function runNpm(args, opts) {
   const res = spawnSync("npm", args, {
@@ -8781,7 +9498,7 @@ function runNpm(args, opts) {
   return res.status ?? 1;
 }
 function ensureDesktopDeps(desktopDir) {
-  if (existsSync18(join17(desktopDir, "node_modules"))) return true;
+  if (existsSync19(join18(desktopDir, "node_modules"))) return true;
   console.log(
     `${C3.cyan}Installing desktop dependencies (one-time)...${C3.reset}`
   );
@@ -8807,13 +9524,13 @@ function requireRust() {
 function hasMsvcBuildTools() {
   if (process.platform !== "win32") return true;
   const pf86 = process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)";
-  const vswhere = join17(
+  const vswhere = join18(
     pf86,
     "Microsoft Visual Studio",
     "Installer",
     "vswhere.exe"
   );
-  if (!existsSync18(vswhere)) return false;
+  if (!existsSync19(vswhere)) return false;
   const res = spawnSync(
     vswhere,
     [
@@ -8845,7 +9562,7 @@ function requireMsvcOnWindows() {
   return false;
 }
 function warnIfCliMissing(repoRoot) {
-  if (!existsSync18(join17(repoRoot, "dist", "cli", "index.js"))) {
+  if (!existsSync19(join18(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}`
     );
@@ -8908,7 +9625,7 @@ var uiCommand = new Command19("ui").description("Launch the ZAM Desktop GUI (Act
 ).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, homedir11());
+    launchApp(installedApp, homedir12());
     return;
   }
   const desktopDir = findDesktopDir();
@@ -8929,7 +9646,7 @@ var uiCommand = new Command19("ui").description("Launch the ZAM Desktop GUI (Act
     );
     const code = runNpm(["run", "tauri", "build"], { cwd: desktopDir });
     if (code === 0) {
-      const bundle = join17(
+      const bundle = join18(
         desktopDir,
         "src-tauri",
         "target",
@@ -9005,8 +9722,8 @@ ${C3.dim}After that, 'zam ui' launches it directly.${C3.reset}`
 });
 
 // src/cli/commands/update.ts
-import { readFileSync as readFileSync10 } from "fs";
-import { dirname as dirname9, join as join18 } from "path";
+import { readFileSync as readFileSync12 } from "fs";
+import { dirname as dirname9, join as join19 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command as Command20 } from "commander";
 var GITHUB_REPO = "zam-os/zam";
@@ -9029,7 +9746,7 @@ function currentVersion() {
   for (const up of ["..", "../..", "../../.."]) {
     try {
       const pkg2 = JSON.parse(
-        readFileSync10(join18(here, up, "package.json"), "utf-8")
+        readFileSync12(join19(here, up, "package.json"), "utf-8")
       );
       if (pkg2.version) return pkg2.version;
     } catch {
@@ -9147,8 +9864,8 @@ var whoamiCommand = new Command21("whoami").description("Show or set the default
 
 // src/cli/commands/workspace.ts
 import { execSync as execSync6 } from "child_process";
-import { existsSync as existsSync19, writeFileSync as writeFileSync10 } from "fs";
-import { join as join19 } from "path";
+import { existsSync as existsSync20, writeFileSync as writeFileSync10 } from "fs";
+import { join as join20 } from "path";
 import { confirm as confirm3, input as input7 } from "@inquirer/prompts";
 import { Command as Command22 } from "commander";
 function runGit(cwd, args) {
@@ -9181,7 +9898,7 @@ workspaceCommand.command("publish").description("Publish your local workspace sa
     );
     process.exit(1);
   }
-  if (!existsSync19(workspaceDir)) {
+  if (!existsSync20(workspaceDir)) {
     console.error(
       `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
     );
@@ -9195,15 +9912,15 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
     );
     process.exit(1);
   }
-  const gitignorePath = join19(workspaceDir, ".gitignore");
-  if (!existsSync19(gitignorePath)) {
+  const gitignorePath = join20(workspaceDir, ".gitignore");
+  if (!existsSync20(gitignorePath)) {
     writeFileSync10(
       gitignorePath,
       "node_modules/\n.agent/\n.agents/\n.claude/\n.gemini/\n.goose/\n*.log\n",
       "utf8"
     );
   }
-  const hasGitRepo = existsSync19(join19(workspaceDir, ".git"));
+  const hasGitRepo = existsSync20(join20(workspaceDir, ".git"));
   if (!hasGitRepo) {
     console.log("Initializing local Git repository...");
     runGit(workspaceDir, "init -b main");
@@ -9299,7 +10016,7 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
 // src/cli/index.ts
 var __dirname = dirname10(fileURLToPath5(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync11(join20(__dirname, "..", "..", "package.json"), "utf-8")
+  readFileSync13(join21(__dirname, "..", "..", "package.json"), "utf-8")
 );
 var program = new Command23();
 program.name("zam").description(