zam-core 0.3.5 → 0.3.7

package/dist/cli/index.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
+import { readFileSync as readFileSync7 } from "fs";
+import { dirname as dirname6, join as join15 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command as Command19 } from "commander";
 
 // src/cli/commands/bridge.ts
@@ -230,9 +233,10 @@ async function fetchActiveWorkItems(config) {
 
 // src/kernel/db/connection.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync } from "fs";
+import { createRequire } from "module";
 import { homedir as homedir2 } from "os";
 import { dirname as dirname2, join as join2 } from "path";
-import Database from "libsql";
+import BetterSqlite3 from "better-sqlite3";
 
 // src/kernel/db/schema.ts
 var SCHEMA = `
@@ -348,9 +352,24 @@ CREATE INDEX IF NOT EXISTS idx_session_steps_session ON session_steps(session_id
 // src/kernel/db/connection.ts
 var DEFAULT_DB_DIR = join2(homedir2(), ".zam");
 var DEFAULT_DB_PATH = join2(DEFAULT_DB_DIR, "zam.db");
+var require2 = createRequire(import.meta.url);
 function isRemoteDatabasePath(dbPath) {
   return /^(libsql|https?):\/\//i.test(dbPath);
 }
+function openLocalSqlite(dbPath) {
+  return new BetterSqlite3(dbPath);
+}
+function loadLibsql() {
+  try {
+    const module = require2("libsql");
+    return "default" in module ? module.default : module;
+  } catch (err) {
+    const detail = err instanceof Error ? ` ${err.message}` : "";
+    throw new Error(
+      `Turso sync requires the optional native libsql backend, which is not available for ${process.platform}/${process.arch}.${detail}`
+    );
+  }
+}
 function openDatabase(options = {}) {
   const configuredCloud = options.useConfiguredCloud !== false && !options.dbPath && !options.syncUrl ? getTursoCredentials() : null;
   let requiresTurso = false;
@@ -398,19 +417,24 @@ function openDatabase(options = {}) {
     dbOpts.authToken = authToken;
   }
   let db;
-  try {
-    db = new Database(dbPath, dbOpts);
-  } catch (err) {
-    const msg = err.message;
-    if (msg.includes("InvalidLocalState") && options.syncUrl) {
-      const metaPath = `${dbPath}.meta`;
-      const infoPath = `${dbPath}-info`;
-      if (existsSync2(metaPath)) rmSync(metaPath);
-      if (existsSync2(infoPath)) rmSync(infoPath);
-      db = new Database(dbPath, dbOpts);
-    } else {
-      throw err;
+  if (isRemote || isEmbeddedReplica) {
+    const LibsqlDatabase = loadLibsql();
+    try {
+      db = new LibsqlDatabase(dbPath, dbOpts);
+    } catch (err) {
+      const msg = err.message;
+      if (msg.includes("InvalidLocalState") && options.syncUrl) {
+        const metaPath = `${dbPath}.meta`;
+        const infoPath = `${dbPath}-info`;
+        if (existsSync2(metaPath)) rmSync(metaPath);
+        if (existsSync2(infoPath)) rmSync(infoPath);
+        db = new LibsqlDatabase(dbPath, dbOpts);
+      } else {
+        throw err;
+      }
     }
+  } else {
+    db = openLocalSqlite(dbPath);
   }
   if (!isRemote && !isEmbeddedReplica) {
     db.pragma("journal_mode = WAL");
@@ -420,7 +444,7 @@ function openDatabase(options = {}) {
     db.pragma("busy_timeout = 5000");
   }
   if (isEmbeddedReplica) {
-    db.sync();
+    db.sync?.();
   }
   if (options.initialize) {
     db.exec(SCHEMA);
@@ -794,10 +818,47 @@ function getDueCards(db, userId, now) {
 }
 
 // src/kernel/models/prerequisite.ts
+function buildAncestorMap(db) {
+  const rows = db.prepare("SELECT token_id, requires_id FROM prerequisites").all();
+  const map = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    let ancestors = map.get(row.token_id);
+    if (!ancestors) {
+      ancestors = /* @__PURE__ */ new Set();
+      map.set(row.token_id, ancestors);
+    }
+    ancestors.add(row.requires_id);
+  }
+  return map;
+}
+function wouldCreateCycle(db, tokenId, requiresId) {
+  if (tokenId === requiresId) return true;
+  const ancestors = buildAncestorMap(db);
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [requiresId];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === tokenId) return true;
+    if (visited.has(current)) continue;
+    visited.add(current);
+    const parents = ancestors.get(current);
+    if (parents) {
+      for (const parent of parents) {
+        if (!visited.has(parent)) queue.push(parent);
+      }
+    }
+  }
+  return false;
+}
 function addPrerequisite(db, tokenId, requiresId) {
   if (tokenId === requiresId) {
     throw new Error("A token cannot be a prerequisite of itself");
   }
+  if (wouldCreateCycle(db, tokenId, requiresId)) {
+    throw new Error(
+      `Cannot add prerequisite: would create a cycle. ${requiresId} already depends on ${tokenId} (directly or transitively).`
+    );
+  }
   db.prepare(
     "INSERT OR IGNORE INTO prerequisites (token_id, requires_id) VALUES (?, ?)"
   ).run(tokenId, requiresId);
@@ -1080,23 +1141,51 @@ function deleteToken(db, slug) {
 }
 function findTokens(db, query) {
   const normalised = query.toLowerCase();
-  const qTokens = new Set(
-    normalised.split(/[\s,.\-_/\\:;!?()[\]{}]+/).filter((t2) => t2.length > 2)
-  );
-  const tokens = db.prepare("SELECT * FROM tokens WHERE deprecated_at IS NULL").all();
-  const scored = [];
-  for (const t2 of tokens) {
-    const words = `${t2.slug} ${t2.concept} ${t2.domain}`.toLowerCase().split(/[\s,.\-_/\\:;!?()[\]{}]+/).filter(Boolean);
-    let score = 0;
-    for (const w of words) {
-      if (qTokens.has(w)) score++;
+  const searchTokens = normalised.split(/[\s,.\-_/\\:;!?()[\]{}]+/).filter((t2) => t2.length > 0);
+  if (searchTokens.length === 0) return [];
+  const shortTerms = searchTokens.filter((t2) => t2.length <= 2);
+  const longTerms = searchTokens.filter((t2) => t2.length > 2);
+  const scoreMap = /* @__PURE__ */ new Map();
+  const likeSQL = `SELECT * FROM tokens WHERE deprecated_at IS NULL AND (lower(slug) LIKE ? OR lower(concept) LIKE ? OR lower(domain) LIKE ?)`;
+  for (const term of longTerms) {
+    const pattern = `%${term}%`;
+    const rows = db.prepare(likeSQL).all(pattern, pattern, pattern);
+    for (const row of rows) {
+      const entry = scoreMap.get(row.id);
+      if (entry) {
+        entry.score++;
+      } else {
+        scoreMap.set(row.id, { token: row, score: 1 });
+      }
     }
-    if (t2.concept.toLowerCase().includes(normalised.slice(0, 25))) {
-      score += 3;
+  }
+  if (shortTerms.length > 0 || longTerms.length === 0) {
+    const allTokens = db.prepare("SELECT * FROM tokens WHERE deprecated_at IS NULL").all();
+    for (const token of allTokens) {
+      const words = `${token.slug} ${token.concept} ${token.domain}`.toLowerCase().split(/[\s,.\-_/\\:;!?()[\]{}]+/).filter(Boolean);
+      let matchCount = 0;
+      for (const term of shortTerms.length > 0 ? shortTerms : searchTokens) {
+        for (const w of words) {
+          if (w === term) matchCount++;
+        }
+      }
+      if (matchCount > 0) {
+        const entry = scoreMap.get(token.id);
+        if (entry) {
+          entry.score += matchCount;
+        } else {
+          scoreMap.set(token.id, { token, score: matchCount });
+        }
+      }
     }
-    if (score > 0) {
-      scored.push({ score, ...t2 });
+  }
+  const scored = [];
+  for (const { token, score } of scoreMap.values()) {
+    let finalScore = score;
+    if (token.concept.toLowerCase().includes(normalised.slice(0, 25))) {
+      finalScore += 3;
     }
+    scored.push({ score: finalScore, ...token });
   }
   scored.sort((a, b) => b.score - a.score);
   return scored;
@@ -2510,7 +2599,8 @@ import {
   copyFileSync,
   existsSync as existsSync6,
   mkdirSync as mkdirSync4,
-  readFileSync as readFileSync6
+  readFileSync as readFileSync6,
+  writeFileSync as writeFileSync3
 } from "fs";
 import { homedir as homedir4 } from "os";
 import { join as join6 } from "path";
@@ -2626,102 +2716,82 @@ function distributeGlobalSkills(home = HOME) {
   }
   return results;
 }
-function injectShellHooks() {
-  const results = [];
-  const hookLine = `
+var POSIX_OLD_HOOK = `
 # ZAM Shell Observation Hooks
 if (command -v zam >/dev/null 2>&1); then eval "$(zam monitor start --quiet)"; fi
 `;
-  const pwshHookLine = `
+var POWERSHELL_OLD_HOOK = `
 # ZAM Shell Observation Hooks
 if (Get-Command zam -ErrorAction SilentlyContinue) { Invoke-Expression (& zam monitor start --quiet pwsh) }
 `;
-  const zshrc = join6(HOME, ".zshrc");
-  if (existsSync6(zshrc)) {
-    try {
-      const content = readFileSync6(zshrc, "utf8");
-      if (content.includes("zam monitor start")) {
-        results.push({
-          shell: "zsh",
-          file: zshrc,
-          success: true,
-          alreadyHooked: true
-        });
-      } else {
-        appendFileSync2(zshrc, hookLine);
-        results.push({
-          shell: "zsh",
-          file: zshrc,
-          success: true,
-          alreadyHooked: false
-        });
-      }
-    } catch {
-      results.push({
-        shell: "zsh",
-        file: zshrc,
-        success: false,
-        alreadyHooked: false
-      });
+var HOOK_MARKER = "# ZAM Monitor Session Helper";
+function posixHook(shell) {
+  return `
+${HOOK_MARKER}
+zam-monitor-session() {
+  local session_id="\${1:-}"
+  if [ -z "$session_id" ]; then
+    printf 'Usage: zam-monitor-session <session-id>
+' >&2
+    return 2
+  fi
+  eval "$(command zam monitor start --session "$session_id" --shell ${shell})"
+}
+`;
+}
+var POWERSHELL_HOOK = `
+${HOOK_MARKER}
+function Start-ZamMonitor {
+  param([Parameter(Mandatory = $true)][string]$Session)
+  Invoke-Expression (& zam monitor start --session $Session --shell pwsh)
+}
+`;
+function installHook(file, hook, oldHook) {
+  try {
+    const content = existsSync6(file) ? readFileSync6(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);
+    }
+    return { success: true, alreadyHooked: false };
+  } catch {
+    return { success: false, alreadyHooked: false };
   }
-  const bashrc = join6(HOME, ".bashrc");
+}
+function injectShellHooks(home = HOME) {
+  const results = [];
+  const zshrc = join6(home, ".zshrc");
+  if (existsSync6(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)) {
-    try {
-      const content = readFileSync6(bashrc, "utf8");
-      if (content.includes("zam monitor start")) {
-        results.push({
-          shell: "bash",
-          file: bashrc,
-          success: true,
-          alreadyHooked: true
-        });
-      } else {
-        appendFileSync2(bashrc, hookLine);
-        results.push({
-          shell: "bash",
-          file: bashrc,
-          success: true,
-          alreadyHooked: false
-        });
-      }
-    } catch {
-      results.push({
-        shell: "bash",
-        file: bashrc,
-        success: false,
-        alreadyHooked: false
-      });
-    }
+    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")
+    join6(home, "Documents", "PowerShell"),
+    join6(home, "Documents", "WindowsPowerShell")
   ];
   for (const dir of pwshDirs) {
     const profileFile = join6(dir, "Microsoft.PowerShell_profile.ps1");
     try {
       mkdirSync4(dir, { recursive: true });
-      let content = "";
-      if (existsSync6(profileFile)) {
-        content = readFileSync6(profileFile, "utf8");
-      }
-      if (content.includes("zam monitor start")) {
-        results.push({
-          shell: "powershell",
-          file: profileFile,
-          success: true,
-          alreadyHooked: true
-        });
-      } else {
-        appendFileSync2(profileFile, pwshHookLine);
-        results.push({
-          shell: "powershell",
-          file: profileFile,
-          success: true,
-          alreadyHooked: false
-        });
-      }
+      const status = installHook(
+        profileFile,
+        POWERSHELL_HOOK,
+        POWERSHELL_OLD_HOOK
+      );
+      results.push({
+        shell: "powershell",
+        file: profileFile,
+        ...status
+      });
     } catch {
       results.push({
         shell: "powershell",
@@ -2943,7 +3013,7 @@ function t(locale, key, params = {}) {
 }
 
 // src/kernel/system/installer.ts
-import { execSync } from "child_process";
+import { execFileSync, execSync } from "child_process";
 import { existsSync as existsSync7 } from "fs";
 import { homedir as homedir5 } from "os";
 import { join as join7 } from "path";
@@ -3048,6 +3118,51 @@ function installOllama() {
     }
   }
 }
+function resolveOllamaCommand() {
+  if (hasCommand("ollama")) return "ollama";
+  const candidates = process.platform === "win32" ? [
+    join7(
+      homedir5(),
+      "AppData",
+      "Local",
+      "Programs",
+      "Ollama",
+      "ollama.exe"
+    )
+  ] : process.platform === "darwin" ? ["/Applications/Ollama.app/Contents/Resources/ollama"] : [];
+  return candidates.find((candidate) => existsSync7(candidate));
+}
+function prepareLocalModel(runner, model) {
+  if (runner === "fastflowlm") {
+    return {
+      success: true,
+      message: `${model} will be downloaded by FastFlowLM on first use.`
+    };
+  }
+  if (runner !== "ollama") {
+    return {
+      success: false,
+      message: "No supported local LLM runner was selected."
+    };
+  }
+  const ollamaCommand = resolveOllamaCommand();
+  if (!ollamaCommand) {
+    return {
+      success: false,
+      message: `Ollama was installed but its command is not available yet. Restart the terminal, then run ollama pull ${model}.`
+    };
+  }
+  console.log(`Downloading ${model} with Ollama...`);
+  try {
+    execFileSync(ollamaCommand, ["pull", model], { stdio: "inherit" });
+    return { success: true, message: `${model} is ready in Ollama.` };
+  } catch (err) {
+    return {
+      success: false,
+      message: `Could not prepare ${model}: ${err.message}. Start Ollama and run: ollama pull ${model}`
+    };
+  }
+}
 
 // src/kernel/system/locale.ts
 import { execSync as execSync2 } from "child_process";
@@ -3163,7 +3278,7 @@ function getRepoPaths(db) {
 import { spawn } from "child_process";
 import { existsSync as existsSync9 } from "fs";
 var DEFAULT_LLM_URL = "http://localhost:8000/v1";
-var DEFAULT_LLM_MODEL = "gemma4-it:e4b";
+var DEFAULT_LLM_MODEL = "qwen3.5:4b";
 var DEFAULT_LLM_API_KEY = "sk-none";
 function getLlmConfig(db) {
   return {
@@ -3673,38 +3788,51 @@ function resolveUser(opts, db, resolveOpts) {
   process.exit(1);
 }
 
-// src/cli/commands/bridge.ts
-function jsonOut(data) {
-  console.log(JSON.stringify(data, null, 2));
-}
-function jsonError(message) {
-  console.log(JSON.stringify({ error: message }, null, 2));
+// src/cli/commands/shared/db.ts
+function defaultErrorHandler(message) {
+  console.error("Error:", message);
   process.exit(1);
 }
-function withDb(fn) {
+function withDb(fn, onError = defaultErrorHandler) {
   let db;
   try {
     db = openDatabase();
     fn(db);
   } catch (err) {
-    db?.close();
-    jsonError(err.message);
+    onError(err.message);
   } finally {
     db?.close();
   }
 }
-async function withDbAsync(fn) {
+async function withDbAsync(fn, onError = defaultErrorHandler) {
   let db;
   try {
     db = openDatabase();
     await fn(db);
   } catch (err) {
-    db?.close();
-    jsonError(err.message);
+    onError(err.message);
   } finally {
     db?.close();
   }
 }
+function jsonOut(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// src/cli/commands/bridge.ts
+function jsonOut2(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function jsonError(message) {
+  console.log(JSON.stringify({ error: message }, null, 2));
+  process.exit(1);
+}
+function withDb2(fn) {
+  withDb(fn, jsonError);
+}
+async function withDbAsync2(fn) {
+  await withDbAsync(fn, jsonError);
+}
 function getReviewTarget2(db, cardId, userId) {
   const target = db.prepare(
     `SELECT c.id AS card_id, c.token_id, c.user_id, t.slug
@@ -3743,13 +3871,13 @@ var bridgeCommand = new Command("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((opts) => {
-  withDb((db) => {
+  withDb2((db) => {
     const userId = resolveUser(opts, db, { json: true });
     const dueCards = getDueCards(db, userId);
     const domains = [
       ...new Set(dueCards.map((c) => c.domain).filter(Boolean))
     ].sort();
-    jsonOut({
+    jsonOut2({
       userId,
       dueCount: dueCards.length,
       domains,
@@ -3767,11 +3895,11 @@ bridgeCommand.command("check-due").description("Check due cards for a user (JSON
   });
 });
 bridgeCommand.command("get-review").description("Get next review card with prompt (JSON)").option("--user <id>", "User ID (default: whoami)").option("--no-resolve", "Skip resolving the token's source_link into context").action(async (opts) => {
-  await withDbAsync(async (db) => {
+  await withDbAsync2(async (db) => {
     const userId = resolveUser(opts, db, { json: true });
     const queue = buildReviewQueue(db, { userId, maxReviews: 1, maxNew: 1 });
     if (queue.items.length === 0) {
-      jsonOut({
+      jsonOut2({
         userId,
         hasReview: false,
         card: null,
@@ -3820,7 +3948,7 @@ bridgeCommand.command("get-review").description("Get next review card with promp
       }
     }
     const fullQueue = buildReviewQueue(db, { userId });
-    jsonOut({
+    jsonOut2({
       userId,
       hasReview: true,
       card: item,
@@ -3831,7 +3959,7 @@ bridgeCommand.command("get-review").description("Get next review card with promp
   });
 });
 bridgeCommand.command("submit").description("Submit a rating for a card (JSON)").option("--user <id>", "User ID (default: whoami)").requiredOption("--card-id <id>", "Card ID").requiredOption("--rating <n>", "Rating (1-4)").action((opts) => {
-  withDb((db) => {
+  withDb2((db) => {
     const userId = resolveUser(opts, db, { json: true });
     const rating = Number(opts.rating);
     if (rating < 1 || rating > 4) {
@@ -3843,7 +3971,7 @@ bridgeCommand.command("submit").description("Submit a rating for a card (JSON)")
       userId,
       rating
     });
-    jsonOut({
+    jsonOut2({
       success: true,
       rating,
       evaluation: result.evaluation,
@@ -3855,7 +3983,7 @@ bridgeCommand.command("review-action").description("Apply a review action (JSON)
   "--action <action>",
   "Action: rate | skip | edit-token | deprecate-token | delete-token | delete-card | stop"
 ).option("--rating <n>", "Rating (1-4) for action=rate").option("--concept <concept>", "Updated concept text for action=edit-token").option("--domain <domain>", "Updated domain for action=edit-token").option("--bloom <level>", "Updated Bloom level for action=edit-token").option("--context <context>", "Updated context for action=edit-token").option("--mode <mode>", "Updated symbiosis mode for action=edit-token").option("--source-link <link>", "Updated source link for action=edit-token").option("--confirm", "Confirm destructive delete actions").action((opts) => {
-  withDb((db) => {
+  withDb2((db) => {
     const userId = resolveUser(opts, db, { json: true });
     const action = opts.action;
     const validActions = [
@@ -3873,7 +4001,7 @@ bridgeCommand.command("review-action").description("Apply a review action (JSON)
     const target = getReviewTarget2(db, opts.cardId, userId);
     if ((action === "delete-token" || action === "delete-card") && !opts.confirm) {
       if (action === "delete-token") {
-        jsonOut({
+        jsonOut2({
           success: true,
           action,
           preview: true,
@@ -3883,7 +4011,7 @@ bridgeCommand.command("review-action").description("Apply a review action (JSON)
         });
         return;
       }
-      jsonOut({
+      jsonOut2({
         success: true,
         action,
         preview: true,
@@ -3904,7 +4032,7 @@ bridgeCommand.command("review-action").description("Apply a review action (JSON)
       rating,
       tokenUpdates: action === "edit-token" ? parseTokenUpdates(opts) : void 0
     });
-    jsonOut({
+    jsonOut2({
       success: true,
       action,
       token: {
@@ -3923,12 +4051,12 @@ bridgeCommand.command("review-action").description("Apply a review action (JSON)
   });
 });
 bridgeCommand.command("get-skill").description("Get an agent skill by slug (JSON)").requiredOption("--slug <slug>", "Skill slug").action((opts) => {
-  withDb((db) => {
+  withDb2((db) => {
     const skill = getAgentSkill(db, opts.slug);
     if (!skill) {
       jsonError(`Skill not found: ${opts.slug}`);
     }
-    jsonOut({
+    jsonOut2({
       slug: skill?.slug,
       description: skill?.description,
       steps: skill?.steps,
@@ -3939,7 +4067,7 @@ bridgeCommand.command("get-skill").description("Get an agent skill by slug (JSON
 });
 bridgeCommand.command("get-monitor").description("Read monitor log for a session (JSON)").requiredOption("--session <id>", "Session ID").action((opts) => {
   if (!monitorLogExists(opts.session)) {
-    jsonOut({
+    jsonOut2({
       sessionId: opts.session,
       exists: false,
       commands: [],
@@ -3960,7 +4088,7 @@ bridgeCommand.command("get-monitor").description("Read monitor log for a session
       durationMs: new Date(endTs).getTime() - new Date(first.startedAt).getTime()
     };
   }
-  jsonOut({
+  jsonOut2({
     sessionId: opts.session,
     exists: true,
     commands: commands.map((c) => ({
@@ -3978,7 +4106,7 @@ bridgeCommand.command("get-monitor").description("Read monitor log for a session
 bridgeCommand.command("analyze-monitor").description("Analyze monitor log with token patterns from stdin (JSON)").requiredOption("--session <id>", "Session ID").action(async (opts) => {
   try {
     if (!monitorLogExists(opts.session)) {
-      jsonOut({
+      jsonOut2({
         sessionId: opts.session,
         ratings: [],
         unmatchedCommands: [],
@@ -4006,7 +4134,7 @@ bridgeCommand.command("analyze-monitor").description("Analyze monitor log with t
     const events = readMonitorLog(opts.session);
     const commands = pairCommands(events);
     const result = analyzeObservation(commands, data?.patterns);
-    jsonOut({
+    jsonOut2({
       sessionId: opts.session,
       ...result
     });
@@ -4046,7 +4174,7 @@ bridgeCommand.command("add-token").description("Create a token + card from JSON
       source_link: data?.source_link ?? null
     });
     const card = ensureCard(db, token.id, userId);
-    jsonOut({
+    jsonOut2({
       success: true,
       token,
       card: {
@@ -4083,11 +4211,11 @@ bridgeCommand.command("discover-skills").description(
     try {
       files = readdirSync2(monitorDir).filter((f) => f.endsWith(".jsonl"));
     } catch {
-      jsonOut({ proposals: [], message: "No monitor logs found." });
+      jsonOut2({ proposals: [], message: "No monitor logs found." });
       return;
     }
     if (files.length === 0) {
-      jsonOut({ proposals: [], message: "No monitor logs found." });
+      jsonOut2({ proposals: [], message: "No monitor logs found." });
       return;
     }
     const limit = Number(opts.limit);
@@ -4102,7 +4230,7 @@ bridgeCommand.command("discover-skills").description(
       }
     }
     if (sessionCommands.size === 0) {
-      jsonOut({ proposals: [], message: "No command data in monitor logs." });
+      jsonOut2({ proposals: [], message: "No command data in monitor logs." });
       return;
     }
     let existingSkillSlugs = [];
@@ -4118,7 +4246,7 @@ bridgeCommand.command("discover-skills").description(
       minSessions: Number(opts.minSessions),
       existingSkillSlugs
     });
-    jsonOut({
+    jsonOut2({
       sessionsAnalyzed: sessionCommands.size,
       proposals
     });
@@ -4127,7 +4255,7 @@ bridgeCommand.command("discover-skills").description(
   }
 });
 bridgeCommand.command("check-llm").description("Check if LLM is enabled and online (JSON)").action(async () => {
-  await withDbAsync(async (db) => {
+  await withDbAsync2(async (db) => {
     const { enabled, url, model, apiKey } = getLlmConfig(db);
     let online = false;
     let availableModels = [];
@@ -4141,7 +4269,7 @@ bridgeCommand.command("check-llm").description("Check if LLM is enabled and onli
         );
       }
     }
-    jsonOut({
+    jsonOut2({
       enabled,
       online,
       url,
@@ -4158,18 +4286,18 @@ bridgeCommand.command("ensure-llm").description(
   "Max time to wait for the server to come online",
   "25000"
 ).action(async (opts) => {
-  await withDbAsync(async (db) => {
+  await withDbAsync2(async (db) => {
     const result = await ensureLlmReadyHeadless(db, {
       timeoutMs: Number(opts.timeout)
     });
-    jsonOut(result);
+    jsonOut2(result);
   });
 });
 bridgeCommand.command("translate-question").description("Translate a question dynamically using the local LLM (JSON)").requiredOption("--question <text>", "Question in English to translate").action(async (opts) => {
-  await withDbAsync(async (db) => {
+  await withDbAsync2(async (db) => {
     const isEnabled = getSetting(db, "llm.enabled") === "true";
     if (!isEnabled) {
-      jsonOut({
+      jsonOut2({
         success: false,
         error: "LLM integration is disabled",
         translation: opts.question
@@ -4178,9 +4306,9 @@ bridgeCommand.command("translate-question").description("Translate a question dy
     }
     try {
       const translation = await translateQuestionViaLLM(db, opts.question);
-      jsonOut({ success: true, translation });
+      jsonOut2({ success: true, translation });
     } catch (err) {
-      jsonOut({
+      jsonOut2({
         success: false,
         error: err.message,
         translation: opts.question
@@ -4191,10 +4319,10 @@ bridgeCommand.command("translate-question").description("Translate a question dy
 bridgeCommand.command("evaluate-answer").description(
   "Evaluate the learner's active-recall answer using the local LLM (JSON)"
 ).requiredOption("--slug <slug>", "Token slug").requiredOption("--concept <concept>", "Target concept text").requiredOption("--domain <domain>", "Token domain").requiredOption("--bloom-level <level>", "Bloom taxonomy level").requiredOption("--question <question>", "Question prompt presented").requiredOption("--user-answer <answer>", "User's typed answer").option("--context <context>", "Optional token context details").option("--source-link <link>", "Optional source link").action(async (opts) => {
-  await withDbAsync(async (db) => {
+  await withDbAsync2(async (db) => {
     const isEnabled = getSetting(db, "llm.enabled") === "true";
     if (!isEnabled) {
-      jsonOut({
+      jsonOut2({
         success: false,
         error: "LLM integration is disabled",
         evaluation: ""
@@ -4220,9 +4348,9 @@ bridgeCommand.command("evaluate-answer").description(
         userAnswer: opts.userAnswer,
         sourceLinkContent: resolvedContextContent
       });
-      jsonOut({ success: true, evaluation });
+      jsonOut2({ success: true, evaluation });
     } catch (err) {
-      jsonOut({
+      jsonOut2({
         success: false,
         error: err.message,
         evaluation: ""
@@ -4231,9 +4359,9 @@ bridgeCommand.command("evaluate-answer").description(
   });
 });
 bridgeCommand.command("get-settings").description("Get active ZAM settings (JSON)").action(() => {
-  withDb((db) => {
+  withDb2((db) => {
     const { enabled, url, model, locale } = getLlmConfig(db);
-    jsonOut({
+    jsonOut2({
       locale,
       llm: {
         enabled,
@@ -4246,23 +4374,11 @@ bridgeCommand.command("get-settings").description("Get active ZAM settings (JSON
 
 // src/cli/commands/card.ts
 import { Command as Command2 } from "commander";
-function withDb2(fn) {
-  let db;
-  try {
-    db = openDatabase();
-    fn(db);
-  } catch (err) {
-    console.error("Error:", err.message);
-    process.exit(1);
-  } finally {
-    db?.close();
-  }
-}
 var cardCommand = new Command2("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((opts) => {
-  withDb2((db) => {
+  withDb((db) => {
     const userId = resolveUser(opts, db);
     const dueCards = getDueCards(db, userId);
     if (opts.json) {
@@ -4310,7 +4426,7 @@ cardCommand.command("due").description("Show due tokens for a user").option("--u
   });
 });
 cardCommand.command("update").description("Apply a rating to a card").option("--user <id>", "User ID (default: whoami)").requiredOption("--token <slug>", "Token slug").requiredOption("--rating <n>", "Rating (1=Again, 2=Hard, 3=Good, 4=Easy)").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action((opts) => {
-  withDb2((db) => {
+  withDb((db) => {
     const userId = resolveUser(opts, db);
     const token = getTokenBySlug(db, opts.token);
     if (!token) {
@@ -4377,7 +4493,7 @@ cardCommand.command("update").description("Apply a rating to a card").option("--
   });
 });
 cardCommand.command("unblock").description("Unblock cards whose prerequisites are met").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action((opts) => {
-  withDb2((db) => {
+  withDb((db) => {
     const userId = resolveUser(opts, db);
     const result = unblockReady(db, userId);
     if (opts.quiet) return;
@@ -4396,7 +4512,7 @@ cardCommand.command("unblock").description("Unblock cards whose prerequisites ar
   });
 });
 cardCommand.command("delete").description("Delete one user's card for a token").option("--user <id>", "User ID (default: whoami)").requiredOption("--token <slug>", "Token slug").option("--json", "Output as JSON").action((opts) => {
-  withDb2((db) => {
+  withDb((db) => {
     const userId = resolveUser(opts, db);
     const token = getTokenBySlug(db, opts.token);
     if (!token) {
@@ -4565,22 +4681,10 @@ async function setupTurso(urlArg, tokenArg) {
 
 // src/cli/commands/git-sync.ts
 import { execSync as execSync4 } from "child_process";
-import { chmodSync, existsSync as existsSync10, writeFileSync as writeFileSync3 } from "fs";
+import { chmodSync, existsSync as existsSync10, writeFileSync as writeFileSync4 } from "fs";
 import { join as join9 } from "path";
 import { Command as Command4 } from "commander";
-function withDb3(fn) {
-  let db;
-  try {
-    db = openDatabase();
-    fn(db);
-  } catch (err) {
-    console.error("Error:", err.message);
-    process.exit(1);
-  } finally {
-    db?.close();
-  }
-}
-function installHook() {
+function installHook2() {
   const gitDir = join9(process.cwd(), ".git");
   if (!existsSync10(gitDir)) {
     console.error(
@@ -4596,7 +4700,7 @@ function installHook() {
 zam git-sync --commit HEAD --quiet
 `;
   try {
-    writeFileSync3(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
+    writeFileSync4(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
     try {
       chmodSync(hookPath, "755");
     } catch (_e) {
@@ -4611,10 +4715,10 @@ zam git-sync --commit HEAD --quiet
 }
 var gitSyncCommand = new Command4("git-sync").description("Sync learning cards with recent Git file modifications").option("--commit <hash>", "Git commit hash to check", "HEAD").option("--user <id>", "User ID (default: whoami)").option("--install", "Install git post-commit hook in current repo").option("--quiet", "Suppress verbose output").action((opts) => {
   if (opts.install) {
-    installHook();
+    installHook2();
     return;
   }
-  withDb3((db) => {
+  withDb((db) => {
     const userId = resolveUser(opts, db);
     let changedFiles = [];
     try {
@@ -4883,7 +4987,7 @@ goalCommand.command("status <slug> <status>").description("Update a goal's statu
 });
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync12, mkdirSync as mkdirSync6, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync12, mkdirSync as mkdirSync6, writeFileSync as writeFileSync5 } from "fs";
 import { homedir as homedir7 } from "os";
 import { join as join10 } from "path";
 import { confirm, input as input3 } from "@inquirer/prompts";
@@ -4898,7 +5002,7 @@ function bootstrapSandboxWorkspace(workspaceDir) {
   mkdirSync6(join10(workspaceDir, "skills"), { recursive: true });
   const worldviewFile = join10(workspaceDir, "beliefs", "worldview.md");
   if (!existsSync12(worldviewFile)) {
-    writeFileSync4(
+    writeFileSync5(
       worldviewFile,
       `# Personal Worldview
 
@@ -4912,7 +5016,7 @@ Here, I declare the core concepts and principles I want to master.
   }
   const goalsFile = join10(workspaceDir, "goals", "goals.md");
   if (!existsSync12(goalsFile)) {
-    writeFileSync4(
+    writeFileSync5(
       goalsFile,
       `# Personal Goals
 
@@ -4975,7 +5079,7 @@ var initCommand = new Command6("init").description("Launch the guided interactiv
     message: `Would you like ZAM to install and configure ${runnerLabel} automatically?`,
     default: true
   });
-  let installSuccess = false;
+  let llmReady = false;
   if (proceedInstall) {
     let result;
     if (profile.recommendedRunner === "fastflowlm") {
@@ -4985,7 +5089,18 @@ var initCommand = new Command6("init").description("Launch the guided interactiv
     }
     if (result.success) {
       console.log(`\x1B[32m\u2713 ${result.message}\x1B[0m`);
-      installSuccess = true;
+      const modelResult = prepareLocalModel(
+        profile.recommendedRunner,
+        profile.recommendedModel
+      );
+      if (modelResult.success) {
+        console.log(`\x1B[32m\u2713 ${modelResult.message}\x1B[0m`);
+        llmReady = true;
+      } else {
+        console.warn(
+          `\x1B[33m\u26A0 Model setup incomplete: ${modelResult.message}\x1B[0m`
+        );
+      }
     } else {
       console.warn(`\x1B[33m\u26A0 Installation failed: ${result.message}\x1B[0m`);
       console.log(
@@ -5003,15 +5118,14 @@ var initCommand = new Command6("init").description("Launch the guided interactiv
     console.log(
       `\x1B[32m\u2713 Detected and set system language to: ${detectedLocale}\x1B[0m`
     );
-    if (installSuccess) {
+    if (llmReady) {
       setSetting(db, "llm.enabled", "true");
       if (profile.recommendedRunner === "fastflowlm") {
         setSetting(db, "llm.url", "http://localhost:8000/v1");
-        setSetting(db, "llm.model", "gemma4-it:e4b");
       } else {
         setSetting(db, "llm.url", "http://localhost:11434/v1");
-        setSetting(db, "llm.model", "llama3.2:3b");
       }
+      setSetting(db, "llm.model", profile.recommendedModel);
       console.log(
         "\x1B[32m\u2713 Configured LLM runner settings in database.\x1B[0m"
       );
@@ -5027,10 +5141,10 @@ var initCommand = new Command6("init").description("Launch the guided interactiv
     db?.close();
   }
   console.log(
-    "\n\x1B[1m[5/5] Wiring Developer Agents & Terminal Hooks\x1B[0m"
+    "\n\x1B[1m[5/5] Wiring Developer Agents & Terminal Helpers\x1B[0m"
   );
   const proceedHooks = await confirm({
-    message: "Distribute ZAM active-recall skills and enable automatic terminal command observation?",
+    message: "Distribute ZAM skills and install optional monitored-session shell helpers?",
     default: true
   });
   if (proceedHooks) {
@@ -5043,18 +5157,21 @@ var initCommand = new Command6("init").description("Launch the guided interactiv
         console.log(`  \x1B[31m\u2717 Failed to install in ${res.name}\x1B[0m`);
       }
     }
-    console.log("Injecting observation hooks into shell profiles...");
+    console.log("Installing monitored-session helpers in shell profiles...");
     const hookResults = injectShellHooks();
     for (const res of hookResults) {
       if (res.success) {
-        const action = res.alreadyHooked ? "already up-to-date" : "injected successfully";
-        console.log(`  \x1B[32m\u2713 ${res.shell} hook: ${action}\x1B[0m`);
+        const action = res.alreadyHooked ? "already up-to-date" : "installed successfully";
+        console.log(`  \x1B[32m\u2713 ${res.shell} helper: ${action}\x1B[0m`);
       } else {
         console.log(
-          `  \x1B[31m\u2717 Failed to inject hook in ${res.shell} (${res.file})\x1B[0m`
+          `  \x1B[31m\u2717 Failed to install helper in ${res.shell} (${res.file})\x1B[0m`
         );
       }
     }
+    console.log(
+      "  Start monitoring with zam-monitor-session <id> (bash/zsh) or Start-ZamMonitor <id> (PowerShell)."
+    );
   }
   printLine();
   console.log(
@@ -5327,6 +5444,7 @@ async function promptTokenEdit(token) {
       { name: "Context", value: "context" },
       { name: "Symbiosis mode", value: "symbiosis_mode" },
       { name: "Source link", value: "source_link" },
+      { name: "Question", value: "question" },
       { name: "Cancel", value: "cancel" }
     ]
   });
@@ -5396,6 +5514,17 @@ async function promptTokenEdit(token) {
       });
       return link === token.source_link ? null : { source_link: link || null };
     }
+    case "question": {
+      const question = await input4({
+        message: "Recall question (blank allowed):",
+        default: token.question ?? ""
+      });
+      return question === token.question ? null : { question: question || null };
+    }
+    default: {
+      const exhaustive = field;
+      throw new Error(`Unsupported token field: ${exhaustive}`);
+    }
   }
 }
 
@@ -5606,8 +5735,8 @@ ${"\u2550".repeat(50)}`);
 });
 
 // src/cli/commands/monitor.ts
-import { execFileSync, execSync as execSync5 } from "child_process";
-import { unlinkSync, writeFileSync as writeFileSync5 } from "fs";
+import { execFileSync as execFileSync2, execSync as execSync5 } from "child_process";
+import { unlinkSync, writeFileSync as writeFileSync6 } from "fs";
 import { tmpdir } from "os";
 import { basename as basename2, join as join11 } from "path";
 import { Command as Command8 } from "commander";
@@ -5867,7 +5996,7 @@ end tell` : `tell application "Terminal"
 end tell`;
   const tmpFile = join11(tmpdir(), `zam-monitor-${sessionId}.scpt`);
   try {
-    writeFileSync5(tmpFile, appleScript);
+    writeFileSync6(tmpFile, appleScript);
     execSync5(`osascript ${JSON.stringify(tmpFile)}`, { stdio: "ignore" });
     console.log(
       `Opened ${useIterm ? "iTerm2" : "Terminal.app"} window with monitoring for session ${sessionId}`
@@ -5895,7 +6024,7 @@ function openWindowsPowerShell(shellSetup, sessionId, dir, requestedShell) {
     `-ArgumentList @('-NoExit','-NoProfile','-Command',${psSingleQuoted2(shellSetup)})`
   ].join(" ");
   try {
-    execFileSync(
+    execFileSync2(
       "powershell.exe",
       ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", startCommand],
       {
@@ -6032,18 +6161,6 @@ ${"\u2550".repeat(50)}`);
 // src/cli/commands/session.ts
 import { input as input6, select as select2 } from "@inquirer/prompts";
 import { Command as Command10 } from "commander";
-function withDb4(fn) {
-  let db;
-  try {
-    db = openDatabase();
-    fn(db);
-  } catch (err) {
-    console.error("Error:", err.message);
-    process.exit(1);
-  } finally {
-    db?.close();
-  }
-}
 var sessionCommand = new Command10("session").description(
   "Manage learning sessions"
 );
@@ -6083,7 +6200,7 @@ sessionCommand.command("start").description("Start a new learning session (revie
     }
     let task = opts.task;
     if (!task && !opts.quiet && !opts.json) {
-      task = await selectTask(db);
+      task = await selectTask();
     }
     if (!task) {
       console.error(
@@ -6188,11 +6305,11 @@ Time limit reached (${maxMinutes} min). Moving to task selection.`
   }
   return { reviewed, maintained, skipped: false };
 }
-async function selectTask(db) {
+async function selectTask() {
   console.log("\u2550".repeat(50));
   console.log("Phase 2: Task Selection");
   console.log("\u2550".repeat(50));
-  const adoConfig = loadADOConfig(db);
+  const adoConfig = loadADOConfig();
   if (adoConfig) {
     const items = await fetchActiveWorkItems(adoConfig);
     if (items.length > 0) {
@@ -6213,7 +6330,7 @@ async function selectTask(db) {
   return input6({ message: "Task description:" });
 }
 sessionCommand.command("log").description("Log a step within a session").requiredOption("--session <id>", "Session ID").requiredOption("--token <slug>", "Token slug").requiredOption("--done-by <who>", "Who performed the step (user or agent)").option("--rating <n>", "Rating (1-4)").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action((opts) => {
-  withDb4((db) => {
+  withDb((db) => {
     const token = getTokenBySlug(db, opts.token);
     if (!token) {
       console.error(`Token not found: ${opts.token}`);
@@ -6239,7 +6356,7 @@ sessionCommand.command("log").description("Log a step within a session").require
   });
 });
 sessionCommand.command("end").description("End a session and show summary").requiredOption("--session <id>", "Session ID").option("--json", "Output as JSON").action((opts) => {
-  withDb4((db) => {
+  withDb((db) => {
     endSession(db, opts.session);
     const summary = getSessionSummary(db, opts.session);
     if (opts.json) {
@@ -6267,23 +6384,11 @@ sessionCommand.command("end").description("End a session and show summary").requ
 // src/cli/commands/settings.ts
 import { existsSync as existsSync13 } from "fs";
 import { Command as Command11 } from "commander";
-function withDb5(fn) {
-  let db;
-  try {
-    db = openDatabase();
-    fn(db);
-  } catch (err) {
-    console.error("Error:", err.message);
-    process.exit(1);
-  } finally {
-    db?.close();
-  }
-}
 var settingsCommand = new Command11("settings").description(
   "Manage user settings"
 );
 settingsCommand.command("show").description("Show all settings").option("--json", "Output as JSON").action((opts) => {
-  withDb5((db) => {
+  withDb((db) => {
     if (opts.json) {
       console.log(JSON.stringify(getAllSettings(db), null, 2));
       return;
@@ -6304,7 +6409,7 @@ settingsCommand.command("show").description("Show all settings").option("--json"
   });
 });
 settingsCommand.command("get <key>").description("Get a single setting").option("--json", "Output as JSON").action((key, opts) => {
-  withDb5((db) => {
+  withDb((db) => {
     const value = getSetting(db, key);
     if (opts.json) {
       console.log(JSON.stringify({ key, value: value ?? null }));
@@ -6318,7 +6423,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((key, value, opts) => {
-  withDb5((db) => {
+  withDb((db) => {
     let parsedVal = value;
     if (key === "llm.enabled") {
       const lower = value.toLowerCase();
@@ -6335,7 +6440,7 @@ settingsCommand.command("set <key> <value>").description("Set a setting").option
   });
 });
 settingsCommand.command("delete <key>").description("Delete a setting").option("--quiet", "Suppress output").action((key, opts) => {
-  withDb5((db) => {
+  withDb((db) => {
     const deleted = deleteSetting(db, key);
     if (!opts.quiet) {
       if (deleted) {
@@ -6349,7 +6454,7 @@ settingsCommand.command("delete <key>").description("Delete a setting").option("
 settingsCommand.command("llm [state]").description(
   "Quickly enable/disable or check local LLM integration (on/off/enable/disable)"
 ).action((state) => {
-  withDb5((db) => {
+  withDb((db) => {
     if (!state) {
       const enabled = getSetting(db, "llm.enabled") || "false";
       console.log(
@@ -6378,7 +6483,7 @@ settingsCommand.command("llm [state]").description(
 settingsCommand.command("locale [lang]").description(
   "Quickly set or check manual ZAM language override (en/de/es/fr/pt/zh/ja)"
 ).action((lang) => {
-  withDb5((db) => {
+  withDb((db) => {
     if (!lang) {
       const locale = getSetting(db, "system.locale") || "en";
       console.log(`Active language (locale): \x1B[36m${locale}\x1B[0m`);
@@ -6397,7 +6502,7 @@ settingsCommand.command("locale [lang]").description(
   });
 });
 settingsCommand.command("repos").description("Show or set Personal, Team, and Organization repository paths").option("--personal <path>", "Set the Personal Repository path").option("--team <path>", "Set the Team Repository path").option("--org <path>", "Set the Organization Repository path").action((opts) => {
-  withDb5((db) => {
+  withDb((db) => {
     let changed = false;
     if (opts.personal !== void 0) {
       setSetting(db, "repo.personal", opts.personal);
@@ -6444,7 +6549,7 @@ settingsCommand.command("repos").description("Show or set Personal, Team, and Or
 });
 
 // src/cli/commands/setup.ts
-import { copyFileSync as copyFileSync2, existsSync as existsSync14, mkdirSync as mkdirSync7, writeFileSync as writeFileSync6 } from "fs";
+import { copyFileSync as copyFileSync2, existsSync as existsSync14, mkdirSync as mkdirSync7, writeFileSync as writeFileSync7 } from "fs";
 import { basename as basename3, dirname as dirname4, join as join12 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command as Command12 } from "commander";
@@ -6513,7 +6618,7 @@ function writeClaudeMd(skipClaudeMd, cwd = process.cwd()) {
     return;
   }
   const name = basename3(cwd);
-  writeFileSync6(
+  writeFileSync7(
     dest,
     `# ZAM Personal Kernel \xE2\u20AC\u201D ${name}
 
@@ -6547,7 +6652,7 @@ function writeAgentsMd(skipAgentsMd, cwd = process.cwd()) {
     return;
   }
   const name = basename3(cwd);
-  writeFileSync6(
+  writeFileSync7(
     dest,
     `# ZAM Personal Kernel - ${name}
 
@@ -6602,23 +6707,11 @@ var setupCommand = new Command12("setup").description(
 
 // src/cli/commands/skill.ts
 import { Command as Command13 } from "commander";
-function withDb6(fn) {
-  let db;
-  try {
-    db = openDatabase();
-    fn(db);
-  } catch (err) {
-    console.error("Error:", err.message);
-    process.exit(1);
-  } finally {
-    db?.close();
-  }
-}
 var skillCommand = new Command13("skill").description(
   "Manage agent skill entries (task recipes)"
 );
 skillCommand.command("list").description("List all agent skills").option("--json", "Output as JSON").action((opts) => {
-  withDb6((db) => {
+  withDb((db) => {
     const skills = listAgentSkills(db);
     if (opts.json) {
       console.log(JSON.stringify(skills, null, 2));
@@ -6641,7 +6734,7 @@ skillCommand.command("list").description("List all agent skills").option("--json
   });
 });
 skillCommand.command("show").description("Show a specific agent skill").requiredOption("--slug <slug>", "Skill slug").option("--json", "Output as JSON").action((opts) => {
-  withDb6((db) => {
+  withDb((db) => {
     const skill = getAgentSkill(db, opts.slug);
     if (!skill) {
       console.error(`Skill not found: ${opts.slug}`);
@@ -6671,7 +6764,7 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
   "Source: learned | builtin (default: learned)",
   "learned"
 ).option("--json", "Output as JSON").action((opts) => {
-  withDb6((db) => {
+  withDb((db) => {
     let steps;
     try {
       steps = JSON.parse(opts.steps);
@@ -6700,20 +6793,8 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
 
 // src/cli/commands/stats.ts
 import { Command as Command14 } from "commander";
-function withDb7(fn) {
-  let db;
-  try {
-    db = openDatabase();
-    fn(db);
-  } catch (err) {
-    console.error("Error:", err.message);
-    process.exit(1);
-  } finally {
-    db?.close();
-  }
-}
 var statsCommand = new Command14("stats").description("Show learning dashboard for a user").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").action((opts) => {
-  withDb7((db) => {
+  withDb((db) => {
     const userId = resolveUser(opts, db);
     const stats = getUserStats(db, userId);
     const domains = getDomainCompetence(db, userId);
@@ -6749,65 +6830,18 @@ var statsCommand = new Command14("stats").description("Show learning dashboard f
 
 // src/cli/commands/token.ts
 import { Command as Command15 } from "commander";
-async function withDb8(fn) {
-  let db;
-  try {
-    db = openDatabase();
-    await fn(db);
-  } catch (err) {
-    console.error("Error:", err.message);
-    process.exit(1);
-  } finally {
-    db?.close();
-  }
-}
-function jsonOut2(data) {
-  console.log(JSON.stringify(data, null, 2));
-}
 var tokenCommand = new Command15("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) => {
-  await withDb8(async (db) => {
+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((opts) => {
+  withDb((db) => {
     let question = opts.question || null;
     if (!question) {
-      const isLlmEnabled = getSetting(db, "llm.enabled") === "true";
-      if (isLlmEnabled) {
-        console.log(
-          "Generating high-quality active-recall question via local LLM..."
-        );
-        try {
-          let sourceLinkContent = null;
-          if (opts.sourceLink) {
-            const resolved = await resolveReviewContext(
-              opts.sourceLink
-            ).catch(() => null);
-            if (resolved) {
-              sourceLinkContent = resolved.content;
-            }
-          }
-          question = await generateQuestionViaLLM(db, {
-            slug: opts.slug,
-            concept: opts.concept,
-            domain: opts.domain,
-            bloomLevel: Number(opts.bloom),
-            context: "",
-            sourceLinkContent
-          });
-          console.log(`Generated: "${question}"`);
-        } catch (err) {
-          console.warn(
-            `LLM question generation failed: ${err.message}. Falling back to template.`
-          );
-        }
-      }
-      if (!question) {
-        question = generateConceptFreeCue(
-          Number(opts.bloom),
-          opts.slug,
-          opts.domain
-        );
-      }
+      question = generateConceptFreeCue(
+        Number(opts.bloom),
+        opts.slug,
+        opts.domain
+      );
     }
     const token = createToken(db, {
       slug: opts.slug,
@@ -6832,7 +6866,7 @@ 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((opts) => {
-  withDb8((db) => {
+  withDb((db) => {
     const results = findTokens(db, opts.query);
     if (opts.json) {
       console.log(JSON.stringify(results, null, 2));
@@ -6856,7 +6890,7 @@ 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((opts) => {
-  withDb8((db) => {
+  withDb((db) => {
     const tokens = listTokens(
       db,
       opts.domain ? { domain: opts.domain } : void 0
@@ -6888,8 +6922,8 @@ 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) => {
-  await withDb8(async (db) => {
+).option("--question <question>", "Updated question text (blank allowed)").option("--json", "Output as JSON").action((opts) => {
+  withDb((db) => {
     const updates = {};
     if (opts.concept !== void 0) updates.concept = opts.concept;
     if (opts.domain !== void 0) updates.domain = opts.domain;
@@ -6912,7 +6946,7 @@ tokenCommand.command("edit").description("Edit a token's mutable fields").requir
     }
     const token = updateToken(db, opts.slug, updates);
     if (opts.json) {
-      jsonOut2(token);
+      jsonOut(token);
       return;
     }
     console.log(`Updated token: ${token.slug}`);
@@ -6926,7 +6960,7 @@ tokenCommand.command("edit").description("Edit a token's mutable fields").requir
   });
 });
 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((opts) => {
-  withDb8((db) => {
+  withDb((db) => {
     const token = getTokenBySlug(db, opts.token);
     if (!token) {
       console.error(`Token not found: ${opts.token}`);
@@ -6956,7 +6990,7 @@ 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((opts) => {
-  withDb8((db) => {
+  withDb((db) => {
     const token = deprecateToken(db, opts.slug);
     if (opts.json) {
       console.log(JSON.stringify(token, null, 2));
@@ -6968,7 +7002,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((opts) => {
-  withDb8((db) => {
+  withDb((db) => {
     const impact = getTokenDeleteImpact(db, opts.slug);
     if (!opts.force) {
       const preview = {
@@ -6978,7 +7012,7 @@ tokenCommand.command("delete").description("Hard-delete a token and its dependen
         impact
       };
       if (opts.json) {
-        jsonOut2(preview);
+        jsonOut(preview);
         return;
       }
       console.log(`Delete preview for ${opts.slug}:`);
@@ -6998,7 +7032,7 @@ tokenCommand.command("delete").description("Hard-delete a token and its dependen
     }
     const result = deleteToken(db, opts.slug);
     if (opts.json) {
-      jsonOut2({
+      jsonOut({
         slug: result.token.slug,
         deleted: true,
         impact: result.impact
@@ -7013,7 +7047,7 @@ tokenCommand.command("delete").description("Hard-delete a token and its dependen
   });
 });
 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((opts) => {
-  withDb8((db) => {
+  withDb((db) => {
     const userId = resolveUser(opts, db);
     const token = getTokenBySlug(db, opts.token);
     if (!token) {
@@ -7074,7 +7108,7 @@ 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 existsSync15, mkdirSync as mkdirSync8, writeFileSync as writeFileSync7 } from "fs";
+import { existsSync as existsSync15 } from "fs";
 import { homedir as homedir8 } from "os";
 import { dirname as dirname5, join as join13 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
@@ -7120,6 +7154,14 @@ function findBuiltApp(desktopDir) {
   }
   return null;
 }
+function findInstalledApp() {
+  const candidates = process.platform === "win32" ? [
+    process.env.LOCALAPPDATA && join13(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
+    process.env.ProgramFiles && join13(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
+    process.env["ProgramFiles(x86)"] && join13(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
+  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join13(homedir8(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
+  return candidates.find((candidate) => candidate && existsSync15(candidate)) || null;
+}
 function runNpm(args, opts) {
   const res = spawnSync("npm", args, {
     stdio: "inherit",
@@ -7135,6 +7177,12 @@ function ensureDesktopDeps(desktopDir) {
   );
   return runNpm(["install"], { cwd: desktopDir }) === 0;
 }
+function prepareDesktopBridge(repoRoot) {
+  console.log(`${C.cyan}Preparing self-contained desktop bridge...${C.reset}`);
+  return runNpm(["run", "desktop:prepare", "--", "--bundle-node"], {
+    cwd: repoRoot
+  }) === 0;
+}
 function requireRust() {
   if (hasCommand("cargo")) return true;
   console.error(
@@ -7193,25 +7241,17 @@ function warnIfCliMissing(repoRoot) {
     );
   }
 }
-function recordCliHome(repoRoot) {
-  try {
-    const zamDir = join13(homedir8(), ".zam");
-    if (!existsSync15(zamDir)) mkdirSync8(zamDir, { recursive: true });
-    writeFileSync7(join13(zamDir, "cli_path"), repoRoot, "utf8");
-  } catch {
-  }
-}
-function launchApp(appPath, repoRoot) {
+function launchApp(appPath, workingDir) {
   console.log(`${C.green}\u2713 Launching ZAM Desktop...${C.reset}`);
   if (process.platform === "darwin" && appPath.endsWith(".app")) {
     spawn2("open", [appPath], {
-      cwd: repoRoot,
+      cwd: workingDir,
       detached: true,
       stdio: "ignore"
     }).unref();
   } else {
     spawn2(appPath, [], {
-      cwd: repoRoot,
+      cwd: workingDir,
       detached: true,
       stdio: "ignore",
       windowsHide: true
@@ -7256,6 +7296,11 @@ var uiCommand = new Command16("ui").description("Launch the ZAM Desktop GUI (Act
   "--build",
   "Build the native installer for your OS (needs Rust, one-time)"
 ).option("--shortcut", "Create Desktop + Start-menu shortcuts to the GUI").action((opts) => {
+  const installedApp = findInstalledApp();
+  if (!opts.dev && !opts.build && !opts.shortcut && installedApp) {
+    launchApp(installedApp, homedir8());
+    return;
+  }
   const desktopDir = findDesktopDir();
   if (!desktopDir) {
     console.error(
@@ -7264,11 +7309,11 @@ var uiCommand = new Command16("ui").description("Launch the ZAM Desktop GUI (Act
     process.exit(1);
   }
   const repoRoot = dirname5(desktopDir);
-  recordCliHome(repoRoot);
   if (opts.build) {
     if (!requireRust()) process.exit(1);
     if (!requireMsvcOnWindows()) process.exit(1);
     if (!ensureDesktopDeps(desktopDir)) process.exit(1);
+    if (!prepareDesktopBridge(repoRoot)) process.exit(1);
     console.log(
       `${C.cyan}Building the native ZAM installer (this takes a few minutes)...${C.reset}`
     );
@@ -7290,7 +7335,7 @@ ${C.green}\u2713 Done. Installer is in:${C.reset}
         `${C.dim}Run that installer once \u2014 it adds ZAM to the Start menu and Desktop automatically.${C.reset}`
       );
       console.log(
-        `${C.dim}Recorded this repo (${repoRoot}) in ~/.zam/cli_path so the installed app finds the CLI.${C.reset}`
+        `${C.dim}The installer includes the CLI bridge and Node runtime.${C.reset}`
       );
     }
     process.exit(code);
@@ -7307,17 +7352,17 @@ ${C.green}\u2713 Done. Installer is in:${C.reset}
   }
   const builtApp = findBuiltApp(desktopDir);
   if (opts.shortcut) {
-    if (!builtApp) {
+    const shortcutTarget = installedApp || builtApp;
+    if (!shortcutTarget) {
       console.error(
         `${C.red}\u2717 No built app yet. Build it first:${C.reset} ${C.cyan}zam ui --build${C.reset}`
       );
       process.exit(1);
     }
-    createShortcuts(builtApp, repoRoot);
+    createShortcuts(shortcutTarget, dirname5(shortcutTarget));
     return;
   }
   if (builtApp) {
-    warnIfCliMissing(repoRoot);
     launchApp(builtApp, repoRoot);
     return;
   }
@@ -7351,20 +7396,8 @@ ${C.dim}After that, 'zam ui' launches it directly.${C.reset}`
 
 // src/cli/commands/whoami.ts
 import { Command as Command17 } from "commander";
-function withDb9(fn) {
-  let db;
-  try {
-    db = openDatabase();
-    fn(db);
-  } catch (err) {
-    console.error("Error:", err.message);
-    process.exit(1);
-  } finally {
-    db?.close();
-  }
-}
 var whoamiCommand = new Command17("whoami").description("Show or set the default user identity").option("--set <id>", "Set the default user ID").option("--clear", "Remove the default user ID").option("--json", "Output as JSON").action((opts) => {
-  withDb9((db) => {
+  withDb((db) => {
     if (opts.set) {
       setSetting(db, "user.id", opts.set);
       if (opts.json) {
@@ -7550,10 +7583,14 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
 });
 
 // src/cli/index.ts
+var __dirname = dirname6(fileURLToPath4(import.meta.url));
+var pkg = JSON.parse(
+  readFileSync7(join15(__dirname, "..", "..", "package.json"), "utf-8")
+);
 var program = new Command19();
 program.name("zam").description(
   "The Symbiotic Learning Kernel: Elevating Human Intelligence through AI Collaboration."
-).version("0.3.5");
+).version(pkg.version);
 program.addCommand(initCommand);
 program.addCommand(setupCommand);
 program.addCommand(tokenCommand);