zam-core 0.5.3 → 0.6.1

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { readFileSync as readFileSync15 } from "fs";
+import { readFileSync as readFileSync16 } from "fs";
 import { dirname as dirname10, join as join25 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 import { Command as Command25 } from "commander";
@@ -629,6 +629,24 @@ CREATE TABLE IF NOT EXISTS session_syntheses (
   PRIMARY KEY (session_id, token_id)
 );
 
+-- Sources: textbook files, web links, or scan paths
+CREATE TABLE IF NOT EXISTS sources (
+  id          TEXT PRIMARY KEY,
+  type        TEXT NOT NULL CHECK (type IN ('file', 'web', 'scan')),
+  uri         TEXT NOT NULL UNIQUE,
+  content     TEXT,
+  created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- Token sources: mapping between tokens and their sources
+CREATE TABLE IF NOT EXISTS token_sources (
+  token_id    TEXT NOT NULL REFERENCES tokens(id) ON DELETE CASCADE,
+  source_id   TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+  excerpt     TEXT NOT NULL DEFAULT '',
+  page_number TEXT,
+  PRIMARY KEY (token_id, source_id)
+);
+
 -- User configuration
 CREATE TABLE IF NOT EXISTS user_config (
   key         TEXT PRIMARY KEY,
@@ -956,6 +974,24 @@ async function runMigrations(db) {
       PRIMARY KEY (session_id, token_id)
     )
   `);
+  await db.exec(`
+    CREATE TABLE IF NOT EXISTS sources (
+      id          TEXT PRIMARY KEY,
+      type        TEXT NOT NULL CHECK (type IN ('file', 'web', 'scan')),
+      uri         TEXT NOT NULL UNIQUE,
+      content     TEXT,
+      created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+  await db.exec(`
+    CREATE TABLE IF NOT EXISTS token_sources (
+      token_id    TEXT NOT NULL REFERENCES tokens(id) ON DELETE CASCADE,
+      source_id   TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+      excerpt     TEXT NOT NULL DEFAULT '',
+      page_number TEXT,
+      PRIMARY KEY (token_id, source_id)
+    )
+  `);
 }
 
 // src/kernel/db/snapshot.ts
@@ -1650,6 +1686,425 @@ async function listTokens(db, options) {
     "SELECT * FROM tokens WHERE deprecated_at IS NULL ORDER BY bloom_level, domain, slug"
   ).all();
 }
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+async function generateTokenSlug(db, domain, concept, question) {
+  const baseText = question && question.trim().length > 0 ? question : concept;
+  const cleanDomain = slugify(domain || "");
+  const cleanBase = slugify(baseText);
+  let baseSlug = cleanDomain ? `${cleanDomain}-${cleanBase}` : cleanBase;
+  if (baseSlug.length > 60) {
+    baseSlug = baseSlug.slice(0, 60).replace(/-$/, "");
+  }
+  if (!baseSlug) {
+    baseSlug = "token";
+  }
+  let slug = baseSlug;
+  let counter = 1;
+  while (true) {
+    const existing = await db.prepare("SELECT id FROM tokens WHERE slug = ?").get(slug);
+    if (!existing) {
+      return slug;
+    }
+    const suffix = `-${counter}`;
+    slug = baseSlug.slice(0, 60 - suffix.length).replace(/-$/, "") + suffix;
+    counter++;
+  }
+}
+async function listPersonalCards(db, userId, options) {
+  let sql = `
+    SELECT 
+      t.id AS tokenId,
+      t.slug,
+      t.concept,
+      t.domain,
+      t.bloom_level AS bloomLevel,
+      t.context,
+      t.symbiosis_mode AS symbiosisMode,
+      COALESCE(
+        t.source_link,
+        (
+          SELECT s.uri
+          FROM token_sources ts
+          INNER JOIN sources s ON s.id = ts.source_id
+          WHERE ts.token_id = t.id
+          ORDER BY s.created_at DESC, s.id DESC
+          LIMIT 1
+        )
+      ) AS sourceLink,
+      t.question,
+      t.created_at AS createdAt,
+      t.updated_at AS updatedAt,
+      c.id AS cardId,
+      c.state,
+      c.due_at AS dueAt,
+      c.stability,
+      c.difficulty,
+      c.reps,
+      c.lapses,
+      c.elapsed_days AS elapsedDays,
+      c.scheduled_days AS scheduledDays,
+      c.blocked
+    FROM tokens t
+    INNER JOIN cards c ON c.token_id = t.id AND c.user_id = ?
+    WHERE t.deprecated_at IS NULL
+  `;
+  const values = [userId];
+  if (options?.domain) {
+    sql += " AND t.domain = ?";
+    values.push(options.domain);
+  }
+  if (options?.query) {
+    const terms = options.query.toLowerCase().split(/\s+/).filter(Boolean);
+    for (const term of terms) {
+      sql += ` AND (lower(t.slug) LIKE ? OR lower(t.concept) LIKE ? OR lower(t.domain) LIKE ? OR lower(t.question) LIKE ?)`;
+      const pattern = `%${term}%`;
+      values.push(pattern, pattern, pattern, pattern);
+    }
+  }
+  sql += " ORDER BY t.created_at DESC";
+  const rows = await db.prepare(sql).all(...values);
+  return rows;
+}
+async function importCurriculumCards(db, userId, cards) {
+  let createdCount = 0;
+  let ensuredCount = 0;
+  await db.transaction(async (tx) => {
+    for (const card of cards) {
+      const bloom = card.bloom_level !== void 0 ? card.bloom_level : 1;
+      if (bloom < 1 || bloom > 5) {
+        throw new Error(`bloom_level must be between 1 and 5, got ${bloom}`);
+      }
+      let symbiosisMode = null;
+      if (card.symbiosis_mode) {
+        if (!["shadowing", "copilot", "autonomy", "none"].includes(
+          card.symbiosis_mode
+        )) {
+          throw new Error(`Invalid symbiosis_mode: ${card.symbiosis_mode}`);
+        }
+        symbiosisMode = card.symbiosis_mode === "none" ? null : card.symbiosis_mode;
+      }
+      const baseText = card.question && card.question.trim().length > 0 ? card.question : card.concept;
+      const cleanDomain = slugify(card.domain || "");
+      const cleanBase = slugify(baseText);
+      let baseSlug = cleanDomain ? `${cleanDomain}-${cleanBase}` : cleanBase;
+      if (baseSlug.length > 60) {
+        baseSlug = baseSlug.slice(0, 60).replace(/-$/, "");
+      }
+      if (!baseSlug) {
+        baseSlug = "token";
+      }
+      let token = await getTokenBySlug(tx, baseSlug);
+      if (!token) {
+        const finalSlug = await generateTokenSlug(
+          tx,
+          card.domain,
+          card.concept,
+          card.question
+        );
+        token = await createToken(tx, {
+          slug: finalSlug,
+          concept: card.concept,
+          domain: card.domain,
+          bloom_level: bloom,
+          context: card.context || "",
+          symbiosis_mode: symbiosisMode,
+          source_link: card.source_link || null,
+          question: card.question || null
+        });
+        createdCount++;
+      }
+      const existingCard = await getCard(tx, token.id, userId);
+      if (!existingCard) {
+        await ensureCard(tx, token.id, userId);
+        ensuredCount++;
+      }
+    }
+  });
+  return { createdCount, ensuredCount };
+}
+async function confirmCardSplit(db, userId, originalSlug, action, originalQuestion, originalConcept, proposals) {
+  if (action !== "block" && action !== "remove") {
+    throw new Error(`Invalid split action: ${action}`);
+  }
+  if (proposals.length < 2 || proposals.length > 4) {
+    throw new Error("A card split requires between 2 and 4 proposals");
+  }
+  const originalToken = await getTokenBySlug(db, originalSlug);
+  if (!originalToken) {
+    throw new Error(`Original token not found: ${originalSlug}`);
+  }
+  let createdCount = 0;
+  let ensuredCount = 0;
+  await db.transaction(async (tx) => {
+    const originalCard = await getCard(tx, originalToken.id, userId);
+    if (!originalCard) {
+      throw new Error(
+        `Card not found for token ${originalSlug} and user ${userId}`
+      );
+    }
+    const proposalTokens = [];
+    for (const card of proposals) {
+      const bloom = card.bloom_level !== void 0 ? card.bloom_level : 1;
+      if (bloom < 1 || bloom > 5) {
+        throw new Error(`bloom_level must be between 1 and 5, got ${bloom}`);
+      }
+      let symbiosisMode = null;
+      if (card.symbiosis_mode) {
+        if (!["shadowing", "copilot", "autonomy", "none"].includes(
+          card.symbiosis_mode
+        )) {
+          throw new Error(`Invalid symbiosis_mode: ${card.symbiosis_mode}`);
+        }
+        symbiosisMode = card.symbiosis_mode === "none" ? null : card.symbiosis_mode;
+      }
+      const baseText = card.question && card.question.trim().length > 0 ? card.question : card.concept;
+      const cleanDomain = slugify(card.domain || "");
+      const cleanBase = slugify(baseText);
+      let baseSlug = cleanDomain ? `${cleanDomain}-${cleanBase}` : cleanBase;
+      if (baseSlug.length > 60) {
+        baseSlug = baseSlug.slice(0, 60).replace(/-$/, "");
+      }
+      if (!baseSlug) {
+        baseSlug = "token";
+      }
+      let token = await getTokenBySlug(tx, baseSlug);
+      if (!token) {
+        const finalSlug = await generateTokenSlug(
+          tx,
+          card.domain,
+          card.concept,
+          card.question
+        );
+        token = await createToken(tx, {
+          slug: finalSlug,
+          concept: card.concept,
+          domain: card.domain,
+          bloom_level: bloom,
+          context: card.context || "",
+          symbiosis_mode: symbiosisMode,
+          source_link: card.source_link || originalToken.source_link || null,
+          question: card.question || null
+        });
+        createdCount++;
+      }
+      if (token.id === originalToken.id) {
+        throw new Error("A token cannot be a prerequisite of itself");
+      }
+      await assertPrerequisiteDoesNotCreateCycle(
+        tx,
+        originalToken.id,
+        token.id
+      );
+      proposalTokens.push(token);
+      const existingCard = await getCard(tx, token.id, userId);
+      if (!existingCard) {
+        await ensureCard(tx, token.id, userId);
+        ensuredCount++;
+      }
+    }
+    if (action === "block") {
+      await tx.prepare(
+        "UPDATE tokens SET question = ?, concept = ?, updated_at = ? WHERE id = ?"
+      ).run(
+        originalQuestion || null,
+        originalConcept,
+        (/* @__PURE__ */ new Date()).toISOString(),
+        originalToken.id
+      );
+      for (const propToken of proposalTokens) {
+        await tx.prepare(
+          "INSERT OR IGNORE INTO prerequisites (token_id, requires_id) VALUES (?, ?)"
+        ).run(originalToken.id, propToken.id);
+      }
+      await tx.prepare(
+        "UPDATE cards SET blocked = 1 WHERE token_id = ? AND user_id = ?"
+      ).run(originalToken.id, userId);
+      for (const propToken of proposalTokens) {
+        const card = await ensureCard(tx, propToken.id, userId);
+        if (card.blocked === 1) {
+          const prereqOfPrereq = await tx.prepare(
+            "SELECT COUNT(*) as n FROM prerequisites WHERE token_id = ?"
+          ).get(propToken.id);
+          if (prereqOfPrereq.n === 0) {
+            const now = (/* @__PURE__ */ new Date()).toISOString();
+            await tx.prepare("UPDATE cards SET blocked = 0, due_at = ? WHERE id = ?").run(now, card.id);
+          }
+        }
+      }
+    } else if (action === "remove") {
+      await deleteCardForUser(tx, originalToken.id, userId);
+    }
+  });
+  return { createdCount, ensuredCount };
+}
+async function confirmFoundations(db, userId, originalSlug, proposals) {
+  const originalToken = await getTokenBySlug(db, originalSlug);
+  if (!originalToken) {
+    throw new Error(`Original token not found: ${originalSlug}`);
+  }
+  let createdCount = 0;
+  let linkedCount = 0;
+  await db.transaction(async (tx) => {
+    const originalCard = await getCard(tx, originalToken.id, userId);
+    if (!originalCard) {
+      throw new Error(
+        `Card not found for token ${originalSlug} and user ${userId}`
+      );
+    }
+    for (const card of proposals) {
+      let targetTokenId;
+      if (card.exists && card.slug) {
+        const existingToken = await getTokenBySlug(tx, card.slug);
+        if (!existingToken) {
+          throw new Error(`Prerequisite token not found by slug: ${card.slug}`);
+        }
+        targetTokenId = existingToken.id;
+        const existingCard = await getCard(tx, existingToken.id, userId);
+        if (!existingCard) {
+          await ensureCard(tx, existingToken.id, userId);
+        }
+        linkedCount++;
+      } else {
+        const bloom = card.bloom_level !== void 0 ? card.bloom_level : 1;
+        if (bloom < 1 || bloom > 5) {
+          throw new Error(`bloom_level must be between 1 and 5, got ${bloom}`);
+        }
+        let symbiosisMode = null;
+        if (card.symbiosis_mode) {
+          if (!["shadowing", "copilot", "autonomy", "none"].includes(
+            card.symbiosis_mode
+          )) {
+            throw new Error(`Invalid symbiosis_mode: ${card.symbiosis_mode}`);
+          }
+          symbiosisMode = card.symbiosis_mode === "none" ? null : card.symbiosis_mode;
+        }
+        const baseText = card.question && card.question.trim().length > 0 ? card.question : card.concept;
+        const cleanDomain = slugify(card.domain || "");
+        const cleanBase = slugify(baseText);
+        let baseSlug = cleanDomain ? `${cleanDomain}-${cleanBase}` : cleanBase;
+        if (baseSlug.length > 60) {
+          baseSlug = baseSlug.slice(0, 60).replace(/-$/, "");
+        }
+        if (!baseSlug) {
+          baseSlug = "token";
+        }
+        let token = await getTokenBySlug(tx, baseSlug);
+        if (!token) {
+          const finalSlug = await generateTokenSlug(
+            tx,
+            card.domain,
+            card.concept,
+            card.question
+          );
+          token = await createToken(tx, {
+            slug: finalSlug,
+            concept: card.concept,
+            domain: card.domain,
+            bloom_level: bloom,
+            context: card.context || "",
+            symbiosis_mode: symbiosisMode,
+            source_link: card.source_link || originalToken.source_link || null,
+            question: card.question || null
+          });
+          createdCount++;
+        }
+        targetTokenId = token.id;
+        const existingCard = await getCard(tx, token.id, userId);
+        if (!existingCard) {
+          await ensureCard(tx, token.id, userId);
+        }
+      }
+      if (targetTokenId === originalToken.id) {
+        throw new Error("A token cannot be a prerequisite of itself");
+      }
+      await assertPrerequisiteDoesNotCreateCycle(
+        tx,
+        originalToken.id,
+        targetTokenId
+      );
+      await tx.prepare(
+        "INSERT OR IGNORE INTO prerequisites (token_id, requires_id) VALUES (?, ?)"
+      ).run(originalToken.id, targetTokenId);
+    }
+  });
+  return { createdCount, linkedCount };
+}
+async function confirmSourceImport(db, userId, sourceId, proposals) {
+  let createdCount = 0;
+  let linkedCount = 0;
+  await db.transaction(async (tx) => {
+    const source = await tx.prepare("SELECT id FROM sources WHERE id = ?").get(sourceId);
+    if (!source) {
+      throw new Error(`Source not found: ${sourceId}`);
+    }
+    for (const card of proposals) {
+      const baseText = card.question && card.question.trim().length > 0 ? card.question : card.concept;
+      const cleanDomain = slugify(card.domain || "");
+      const cleanBase = slugify(baseText);
+      let baseSlug = cleanDomain ? `${cleanDomain}-${cleanBase}` : cleanBase;
+      if (baseSlug.length > 60) {
+        baseSlug = baseSlug.slice(0, 60).replace(/-$/, "");
+      }
+      if (!baseSlug) {
+        baseSlug = "token";
+      }
+      let token = await getTokenBySlug(tx, baseSlug);
+      if (!token) {
+        const finalSlug = await generateTokenSlug(
+          tx,
+          card.domain,
+          card.concept,
+          card.question
+        );
+        const bloom = card.bloom_level !== void 0 ? card.bloom_level : 1;
+        let symbiosisMode = null;
+        if (card.symbiosis_mode && card.symbiosis_mode !== "none") {
+          symbiosisMode = card.symbiosis_mode;
+        }
+        token = await createToken(tx, {
+          slug: finalSlug,
+          concept: card.concept,
+          domain: card.domain,
+          bloom_level: bloom,
+          context: card.excerpt || "",
+          symbiosis_mode: symbiosisMode,
+          question: card.question || null
+        });
+        createdCount++;
+      } else {
+        linkedCount++;
+      }
+      const existingCard = await getCard(tx, token.id, userId);
+      if (!existingCard) {
+        await ensureCard(tx, token.id, userId);
+      }
+      await tx.prepare(
+        `INSERT INTO token_sources (token_id, source_id, excerpt, page_number)
+           VALUES (?, ?, ?, ?)
+           ON CONFLICT(token_id, source_id) DO UPDATE SET
+             excerpt = excluded.excerpt,
+             page_number = excluded.page_number`
+      ).run(token.id, sourceId, card.excerpt || "", card.page_number || null);
+    }
+  });
+  return { createdCount, linkedCount };
+}
+async function assertPrerequisiteDoesNotCreateCycle(db, tokenId, prerequisiteId) {
+  const cycleCheck = await db.prepare(
+    `WITH RECURSIVE dependents(token_id) AS (
+         SELECT token_id FROM prerequisites WHERE requires_id = ?
+         UNION
+         SELECT p.token_id FROM prerequisites p
+         JOIN dependents d ON p.requires_id = d.token_id
+       )
+       SELECT COUNT(*) as n FROM dependents WHERE token_id = ?`
+  ).get(tokenId, prerequisiteId);
+  if (cycleCheck.n > 0) {
+    throw new Error("Cannot add prerequisite: would create a cycle");
+  }
+}
 
 // src/kernel/models/prerequisite.ts
 async function buildAncestorMap(db) {
@@ -4574,12 +5029,7 @@ function installFastFlowLM() {
   }
 }
 function installOllama() {
-  const isMac = process.platform === "darwin";
-  const isWin = process.platform === "win32";
-  const hasOllama = hasCommand("ollama") || isMac && existsSync9("/Applications/Ollama.app") || isWin && existsSync9(
-    join10(homedir7(), "AppData", "Local", "Programs", "Ollama", "ollama.exe")
-  );
-  if (hasOllama) {
+  if (isOllamaInstalled()) {
     return { success: true, message: "Ollama is already installed." };
   }
   if (process.platform === "darwin") {
@@ -4634,19 +5084,23 @@ function installOllama() {
     }
   }
 }
-function resolveOllamaCommand() {
-  if (hasCommand("ollama")) return "ollama";
-  const candidates = process.platform === "win32" ? [
-    join10(
-      homedir7(),
-      "AppData",
-      "Local",
-      "Programs",
-      "Ollama",
-      "ollama.exe"
-    )
-  ] : process.platform === "darwin" ? ["/Applications/Ollama.app/Contents/Resources/ollama"] : [];
-  return candidates.find((candidate) => existsSync9(candidate));
+function resolveOllamaCommand(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const homeDir = options.homeDir ?? homedir7();
+  const commandAvailable = options.commandAvailable ?? hasCommand;
+  const pathExists2 = options.pathExists ?? existsSync9;
+  if (commandAvailable("ollama")) return "ollama";
+  const candidates = platform === "win32" ? [join10(homeDir, "AppData", "Local", "Programs", "Ollama", "ollama.exe")] : platform === "darwin" ? [
+    "/opt/homebrew/bin/ollama",
+    "/usr/local/bin/ollama",
+    "/Applications/Ollama.app/Contents/Resources/ollama"
+  ] : ["/usr/local/bin/ollama", "/usr/bin/ollama"];
+  return candidates.find((candidate) => pathExists2(candidate));
+}
+function isOllamaInstalled(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const pathExists2 = options.pathExists ?? existsSync9;
+  return resolveOllamaCommand(options) !== void 0 || platform === "darwin" && pathExists2("/Applications/Ollama.app");
 }
 function prepareLocalModel(runner, model) {
   if (runner === "fastflowlm") {
@@ -5390,14 +5844,19 @@ var agentCommand = new Command("agent").description("Provision and inspect the a
 // src/cli/commands/bridge.ts
 import { execFileSync as execFileSync3 } from "child_process";
 import { randomBytes as randomBytes2 } from "crypto";
-import { existsSync as existsSync17, readdirSync as readdirSync2, readFileSync as readFileSync11, rmSync as rmSync3 } from "fs";
+import { existsSync as existsSync17, readdirSync as readdirSync2, readFileSync as readFileSync12, rmSync as rmSync3 } from "fs";
 import { homedir as homedir10, tmpdir as tmpdir3 } from "os";
 import { join as join18, resolve as resolve4 } from "path";
 import { Command as Command2 } from "commander";
+import { ulid as ulid8 } from "ulid";
+
+// src/cli/adapters/source-reader.ts
+import dns from "dns";
+import fs from "fs";
 
 // src/cli/llm/client.ts
 import { spawn as spawn2 } from "child_process";
-import { existsSync as existsSync14 } from "fs";
+import { existsSync as existsSync14, readFileSync as readFileSync9, statSync as statSync2 } from "fs";
 var DEFAULT_LLM_URL = "http://localhost:8000/v1";
 var DEFAULT_LLM_MAX_TOKENS = 1e4;
 var RECALL_QUESTION_MAX_OUTPUT_TOKENS = 400;
@@ -5570,10 +6029,21 @@ async function getLegacyRoleConfig(db, role, enabled) {
 function assertChatCompletions(cfg) {
   if (cfg.apiFlavor !== "chat-completions") {
     throw new Error(
-      `This role is configured for a "${cfg.apiFlavor}" provider, which is not supported here yet. Use a chat-completions provider for the recall role.`
+      `This role is configured for a "${cfg.apiFlavor}" provider, which is not supported here yet. Use a chat-completions provider for this role.`
     );
   }
 }
+async function getVisionConfig(db) {
+  const p = await getProviderForRole(db, "vision");
+  return {
+    enabled: p.enabled,
+    url: p.url,
+    model: p.model,
+    apiKey: p.apiKey,
+    locale: p.locale,
+    maxFrames: p.maxFrames
+  };
+}
 var LANGUAGE_NAMES = {
   en: "English",
   de: "German",
@@ -5721,6 +6191,317 @@ Evaluation:`;
     providerName: endpoint.providerName
   };
 }
+var MAX_IMPORT_TEXT_CHARS = 2e5;
+var VALID_GENERATED_MODES = /* @__PURE__ */ new Set(["shadowing", "copilot", "autonomy"]);
+function parseGeneratedCardArray(responseText, label, limits) {
+  const startIdx = responseText.indexOf("[");
+  const endIdx = responseText.lastIndexOf("]");
+  if (startIdx === -1 || endIdx === -1 || startIdx > endIdx) {
+    throw new Error(`Invalid ${label} response: JSON array brackets not found`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(responseText.substring(startIdx, endIdx + 1));
+  } catch {
+    throw new Error(`Invalid ${label} response: malformed JSON`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`Invalid ${label} response: expected a JSON array`);
+  }
+  if (parsed.length < limits.min || parsed.length > limits.max) {
+    throw new Error(
+      `Invalid ${label} response: expected ${limits.min}-${limits.max} cards, got ${parsed.length}`
+    );
+  }
+  return parsed.map((value, index) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error(
+        `Invalid ${label} card at index ${index}: expected an object`
+      );
+    }
+    const card = value;
+    for (const field of ["question", "concept", "domain", "context"]) {
+      if (typeof card[field] !== "string" || card[field].trim().length === 0) {
+        throw new Error(
+          `Invalid ${label} card at index ${index}: ${field} must be a non-empty string`
+        );
+      }
+    }
+    if (typeof card.bloom_level !== "number" || !Number.isInteger(card.bloom_level) || card.bloom_level < 1 || card.bloom_level > 5) {
+      throw new Error(
+        `Invalid ${label} card at index ${index}: bloom_level must be an integer from 1 to 5`
+      );
+    }
+    if (typeof card.symbiosis_mode !== "string" || !VALID_GENERATED_MODES.has(card.symbiosis_mode)) {
+      throw new Error(
+        `Invalid ${label} card at index ${index}: invalid symbiosis_mode`
+      );
+    }
+    return {
+      question: card.question,
+      concept: card.concept,
+      domain: card.domain,
+      context: card.context,
+      bloom_level: card.bloom_level,
+      symbiosis_mode: card.symbiosis_mode,
+      source_link: null
+    };
+  });
+}
+async function importCurriculumViaLLM(db, text, targetCategory, sourceUrl) {
+  if (text.length > MAX_IMPORT_TEXT_CHARS) {
+    throw new Error(
+      `Curriculum text exceeds the ${MAX_IMPORT_TEXT_CHARS.toLocaleString()} character limit`
+    );
+  }
+  const cfg = await getProviderForRole(db, "text");
+  const endpoint = await resolveUsableTextEndpoint(db);
+  const langName = LANGUAGE_NAMES[cfg.locale] || "English";
+  const systemPrompt = `You are ZAM, a highly precise agentic curriculum parser.
+Your task is to analyze curriculum objectives, syllabus requirements, or textbook notes, and extract atomic facts, concepts, or skills as structured learning cards in ${langName}.
+
+For each extracted learning card, you MUST generate:
+1. "question": A clear, concise active-recall question testing the concept. The question must not reveal the answer itself.
+2. "concept": The reference answer, core fact, or target conceptual explanation.
+3. "domain": The category of the card. Use "${targetCategory}" as the default, but you may refine it if a specific sub-topic is evident.
+4. "context": The exact sentence or short excerpt from the source text that this card is based on.
+5. "bloom_level": Initial Bloom cognitive level (1 = Remember, 2 = Understand, 3 = Apply, 4 = Analyze, 5 = Synthesize).
+6. "symbiosis_mode": ZAM agent symbiosis level: "shadowing" (reading/monitoring), "copilot" (interactive helper), or "autonomy" (autonomous tasks).
+
+Guidelines:
+- Break complex requirements into multiple separate, atomic cards.
+- Keep questions focused on one fact.
+- Do not repeat the same concept in multiple cards.
+- Test the subject matter directly. Never ask what learners "must know", what
+  a curriculum "requires", or merely restate a competency as a question.
+- Stay within the scope of the supplied curriculum. A reference answer may add
+  the definition, formula, or minimal worked example needed to answer a direct
+  subject-matter question, but it must not introduce named methods, terminology,
+  or adjacent topics that the curriculum passage does not mention.
+- Keep every reference answer concise, mathematically/factually correct, and
+  focused on the competency being tested.
+- Set "context" to the exact sentence or bullet that supports that specific
+  card. Never reuse an unrelated passage merely because it comes from the same
+  curriculum section.
+- Output ONLY a raw valid JSON array of objects. Do NOT wrap the JSON in markdown code blocks, HTML, or include any preamble, headers, or conversational filler.`;
+  const userPrompt = `Curriculum Text to Parse:
+${text}
+
+Target Category: ${targetCategory}
+${sourceUrl ? `Source Reference Link: ${sourceUrl}` : ""}
+
+JSON Array Output:`;
+  const res = await fetchWithInteractiveTimeout(
+    `${endpoint.url}/chat/completions`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${endpoint.apiKey}`
+      },
+      body: JSON.stringify({
+        model: endpoint.model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt }
+        ],
+        temperature: 0.1,
+        max_tokens: DEFAULT_LLM_MAX_TOKENS
+      }),
+      locale: cfg.locale
+    }
+  );
+  const responseText = await readChatContent(res, "LLM curriculum import");
+  return parseGeneratedCardArray(responseText, "curriculum import", {
+    min: 0,
+    max: 200
+  }).map((card) => ({ ...card, source_link: sourceUrl || null }));
+}
+async function generateSplitProposalsViaLLM(db, token) {
+  const cfg = await getProviderForRole(db, "text");
+  const endpoint = await resolveUsableTextEndpoint(db);
+  const langName = LANGUAGE_NAMES[cfg.locale] || "English";
+  const systemPrompt = `You are ZAM, a highly precise agentic learning assistant.
+Your task is to analyze a learning card that is too broad or covers multiple ideas, and split it into 2 to 4 atomic, focused proposal cards in ${langName}.
+
+The input card details are:
+- Question: ${token.question || "N/A"}
+- Core Concept: ${token.concept}
+- Domain: ${token.domain}
+- Excerpt Context: ${token.context || "N/A"}
+
+For each split proposal card, you MUST generate:
+1. "question": A clear, concise active-recall question testing a single focused fact or concept. The question must not reveal the answer itself.
+2. "concept": The reference answer or core fact.
+3. "domain": The category of the card (default to "${token.domain}").
+4. "context": The context excerpt from the original card's context or a derivation of it.
+5. "bloom_level": Bloom taxonomy level (1 to 5).
+6. "symbiosis_mode": Symbiosis mode ("shadowing", "copilot", or "autonomy").
+
+Guidelines:
+- Make sure each card is completely atomic (covers exactly one concept).
+- Do not repeat the same concept across cards.
+- Output ONLY a raw valid JSON array of objects. Do NOT wrap the JSON in markdown code blocks, HTML, or include any conversational filler.`;
+  const userPrompt = `Split the broad card details above into 2 to 4 atomic cards.
+
+JSON Array Output:`;
+  const res = await fetchWithInteractiveTimeout(
+    `${endpoint.url}/chat/completions`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${endpoint.apiKey}`
+      },
+      body: JSON.stringify({
+        model: endpoint.model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt }
+        ],
+        temperature: 0.2,
+        max_tokens: DEFAULT_LLM_MAX_TOKENS
+      }),
+      locale: cfg.locale
+    }
+  );
+  const responseText = await readChatContent(res, "LLM card split proposals");
+  return parseGeneratedCardArray(responseText, "card split", {
+    min: 2,
+    max: 4
+  }).map((card) => ({ ...card, source_link: token.source_link || null }));
+}
+async function generateFoundationsProposalsViaLLM(db, token) {
+  const cfg = await getProviderForRole(db, "text");
+  const endpoint = await resolveUsableTextEndpoint(db);
+  const langName = LANGUAGE_NAMES[cfg.locale] || "English";
+  const systemPrompt = `You are ZAM, a highly precise agentic learning assistant.
+Your task is to analyze a learning card and propose 2 to 4 atomic, foundational prerequisite concepts (foundations) that a learner must master *before* studying this card, in ${langName}.
+
+The current card details are:
+- Question: ${token.question || "N/A"}
+- Core Concept: ${token.concept}
+- Domain: ${token.domain}
+- Excerpt Context: ${token.context || "N/A"}
+
+For each proposed foundational card, you MUST generate:
+1. "question": A clear, concise active-recall question testing a single foundational fact or prerequisite concept.
+2. "concept": The reference answer or core fact.
+3. "domain": The category of the card (default to "${token.domain}").
+4. "context": The context excerpt explaining where this prerequisite fits in the learning hierarchy.
+5. "bloom_level": Bloom taxonomy level (typically 1 or 2 for foundational facts).
+6. "symbiosis_mode": Symbiosis mode ("shadowing", "copilot", or "autonomy").
+
+Guidelines:
+- Recommend only highly relevant and necessary prerequisites.
+- Keep each proposed card atomic and focused on one concept.
+- Output ONLY a raw valid JSON array of objects. Do NOT wrap the JSON in markdown code blocks, HTML, or include any conversational filler.`;
+  const userPrompt = `Suggest 2 to 4 foundational prerequisite cards for the card above.
+
+JSON Array Output:`;
+  const res = await fetchWithInteractiveTimeout(
+    `${endpoint.url}/chat/completions`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${endpoint.apiKey}`
+      },
+      body: JSON.stringify({
+        model: endpoint.model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt }
+        ],
+        temperature: 0.2,
+        max_tokens: DEFAULT_LLM_MAX_TOKENS
+      }),
+      locale: cfg.locale
+    }
+  );
+  const responseText = await readChatContent(
+    res,
+    "LLM card foundations proposals"
+  );
+  return parseGeneratedCardArray(responseText, "foundation proposal", {
+    min: 2,
+    max: 4
+  }).map((card) => ({ ...card, source_link: token.source_link || null }));
+}
+async function extractTextFromScanViaLLM(db, imagePath) {
+  const p = await getProviderForRole(db, "vision");
+  if (!p.enabled) {
+    throw new Error(
+      "Vision role is not enabled in settings (llm.vision.enabled)"
+    );
+  }
+  if (!existsSync14(imagePath)) {
+    throw new Error(`Scan file not found: ${imagePath}`);
+  }
+  const stat = statSync2(imagePath);
+  if (!stat.isFile()) {
+    throw new Error(`Scan path is not a file: ${imagePath}`);
+  }
+  if (stat.size > 10 * 1024 * 1024) {
+    throw new Error("Scan file exceeds 10MB limit");
+  }
+  const ext = imagePath.split(".").pop()?.toLowerCase();
+  const mimeByExtension = {
+    jpeg: "image/jpeg",
+    jpg: "image/jpeg",
+    png: "image/png",
+    webp: "image/webp"
+  };
+  const mime = ext ? mimeByExtension[ext] : void 0;
+  if (!mime) {
+    throw new Error("Unsupported scan format; use PNG, JPEG, or WebP");
+  }
+  const imageBytes = readFileSync9(imagePath);
+  const dataUrl = `data:${mime};base64,${imageBytes.toString("base64")}`;
+  const visionEndpoint = await getVisionConfig(db);
+  const langName = LANGUAGE_NAMES[p.locale] || "English";
+  const systemPrompt = "You are ZAM's OCR processor. Extract all visible text from the image exactly as written. Output only the extracted text without commentary, formatting, or prefixes.";
+  const res = await fetchWithInteractiveTimeout(
+    `${visionEndpoint.url}/chat/completions`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${visionEndpoint.apiKey || DEFAULT_LLM_API_KEY}`
+      },
+      body: JSON.stringify({
+        model: visionEndpoint.model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          {
+            role: "user",
+            content: [
+              {
+                type: "text",
+                text: `Extract all text from this scan in ${langName}:`
+              },
+              {
+                type: "image_url",
+                image_url: { url: dataUrl }
+              }
+            ]
+          }
+        ],
+        temperature: 0,
+        max_tokens: DEFAULT_LLM_MAX_TOKENS
+      }),
+      locale: p.locale
+    }
+  );
+  if (!res.ok) {
+    throw new Error(`LLM vision OCR request failed with status ${res.status}`);
+  }
+  const responseText = await readChatContent(
+    res,
+    "LLM scan OCR text extraction"
+  );
+  return responseText.trim();
+}
 async function translateQuestionViaLLM(db, question) {
   const cfg = await getProviderForRole(db, "recall");
   const endpoint = await resolveUsableRecallEndpoint(db);
@@ -5841,6 +6622,21 @@ async function resolveUsableRecallEndpoint(db) {
   };
   return selected.endpoint;
 }
+async function resolveUsableTextEndpoint(db) {
+  const cfg = await getProviderForRole(db, "text");
+  if (!cfg.enabled) {
+    throw new Error(
+      "Text LLM integration is disabled in settings (llm.enabled)"
+    );
+  }
+  assertChatCompletions(cfg);
+  const chain = await checkProviderChain(cfg);
+  const selected = chain.firstUsable;
+  if (!selected || !isEndpointUsable(selected)) {
+    throw new Error("No text LLM endpoint is online");
+  }
+  return selected.endpoint;
+}
 async function prepareRecallChain(db, opts) {
   const cfg = await getProviderForRole(db, "recall");
   const fail = (reason, partial = {}) => ({
@@ -6337,9 +7133,145 @@ async function ensureHighQualityQuestion(db, token) {
   return null;
 }
 
+// src/cli/adapters/source-reader.ts
+var MAX_SOURCE_BYTES = 2 * 1024 * 1024;
+var MAX_REDIRECTS = 5;
+function isPrivateOrReservedIp(address) {
+  const ip = address.toLowerCase().split("%", 1)[0];
+  const mappedV4 = ip.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)?.[1];
+  const ipv4 = mappedV4 ?? (ip.includes(".") ? ip : null);
+  if (ipv4) {
+    const parts = ipv4.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+      return true;
+    }
+    const [a, b] = parts;
+    return a === 0 || a === 10 || a === 127 || a === 100 && b >= 64 && b <= 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 192 && b === 0 || a === 192 && b === 0 && parts[2] === 2 || a === 198 && (b === 18 || b === 19 || b === 51) || a === 203 && b === 0 && parts[2] === 113 || a >= 224;
+  }
+  return ip === "::" || ip === "::1" || ip.startsWith("fc") || ip.startsWith("fd") || /^fe[89ab]/.test(ip) || ip.startsWith("ff") || ip.startsWith("2001:db8:");
+}
+function cleanHtml(html) {
+  let text = html.replace(
+    /<(head|script|style|svg)[^>]*>[\s\S]*?<\/\1>/gi,
+    " "
+  );
+  text = text.replace(/<[^>]+>/g, " ");
+  text = text.replace(/&nbsp;/g, " ").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+  return text.replace(/\s+/g, " ").trim();
+}
+async function isSafeUrl(urlString) {
+  try {
+    const url = new URL(urlString);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return false;
+    }
+    if (url.username || url.password) return false;
+    const hostname = url.hostname.toLowerCase().replace(/\.$/, "");
+    if (hostname === "localhost" || hostname.endsWith(".localhost"))
+      return false;
+    const results = await dns.promises.lookup(hostname, {
+      all: true,
+      verbatim: true
+    });
+    return results.length > 0 && results.every((result) => !isPrivateOrReservedIp(result.address));
+  } catch {
+    return false;
+  }
+}
+async function readLocalFile(filepath) {
+  if (!fs.existsSync(filepath)) {
+    throw new Error(`File not found: ${filepath}`);
+  }
+  const stat = fs.statSync(filepath);
+  if (!stat.isFile()) {
+    throw new Error(`Not a file: ${filepath}`);
+  }
+  if (stat.size > MAX_SOURCE_BYTES) {
+    throw new Error("File exceeds 2MB limit");
+  }
+  return fs.readFileSync(filepath, "utf-8");
+}
+async function readWebLink(url) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 1e4);
+  try {
+    let currentUrl = new URL(url);
+    for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects++) {
+      if (!await isSafeUrl(currentUrl.href)) {
+        throw new Error(
+          `Access denied to unsafe target URL: ${currentUrl.href}`
+        );
+      }
+      const res = await fetch(currentUrl, {
+        redirect: "manual",
+        signal: controller.signal,
+        headers: {
+          "User-Agent": "ZAM-Content-Studio/0.6.1"
+        }
+      });
+      if (res.status >= 300 && res.status < 400) {
+        const location = res.headers.get("location");
+        if (!location) {
+          throw new Error("Web server returned a redirect without a location");
+        }
+        if (redirects === MAX_REDIRECTS) {
+          throw new Error(`Web request exceeded ${MAX_REDIRECTS} redirects`);
+        }
+        currentUrl = new URL(location, currentUrl);
+        continue;
+      }
+      if (!res.ok) {
+        throw new Error(`Web server responded with status ${res.status}`);
+      }
+      const contentType = res.headers.get("content-type") || "";
+      if (!contentType.includes("text/html") && !contentType.includes("text/plain") && !contentType.includes("application/xhtml+xml") && !contentType.includes("text/xml")) {
+        throw new Error(`Unsupported content type: ${contentType}`);
+      }
+      const declaredLength = Number(res.headers.get("content-length"));
+      if (Number.isFinite(declaredLength) && declaredLength > MAX_SOURCE_BYTES) {
+        throw new Error("Response body exceeds 2MB limit");
+      }
+      const text = await readResponseBodyWithLimit(res, MAX_SOURCE_BYTES);
+      if (contentType.includes("text/html") || contentType.includes("application/xhtml+xml")) {
+        return cleanHtml(text);
+      }
+      return text;
+    }
+    throw new Error("Web request failed");
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new Error("Connection request timed out after 10 seconds");
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+async function readResponseBodyWithLimit(response, maxBytes) {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let totalBytes = 0;
+  let text = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    totalBytes += value.byteLength;
+    if (totalBytes > maxBytes) {
+      await reader.cancel();
+      throw new Error("Response body exceeds 2MB limit");
+    }
+    text += decoder.decode(value, { stream: true });
+  }
+  return text + decoder.decode();
+}
+async function readImageOCR(db, imagePath) {
+  return extractTextFromScanViaLLM(db, imagePath);
+}
+
 // src/cli/llm/vision.ts
 import { randomBytes } from "crypto";
-import { readFileSync as readFileSync9 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
 import { basename as basename3, join as join14 } from "path";
 var LANGUAGE_NAMES2 = {
@@ -6412,7 +7344,7 @@ async function observeUiSnapshotViaLLM(db, input8) {
         }
       }
       for (const file of sampledFiles) {
-        const bytes = readFileSync9(join14(tempDir, file));
+        const bytes = readFileSync10(join14(tempDir, file));
         imageUrls.push(`data:image/png;base64,${bytes.toString("base64")}`);
       }
     } finally {
@@ -6422,7 +7354,7 @@ async function observeUiSnapshotViaLLM(db, input8) {
       }
     }
   } else {
-    const imageBytes = readFileSync9(input8.imagePath);
+    const imageBytes = readFileSync10(input8.imagePath);
     const ext = input8.imagePath.split(".").pop()?.toLowerCase();
     const mime = ext === "jpg" || ext === "jpeg" ? "image/jpeg" : "image/png";
     imageUrls.push(`data:${mime};base64,${imageBytes.toString("base64")}`);
@@ -6890,7 +7822,7 @@ import {
   existsSync as existsSync15,
   lstatSync,
   mkdirSync as mkdirSync8,
-  readFileSync as readFileSync10,
+  readFileSync as readFileSync11,
   realpathSync,
   rmSync as rmSync2,
   symlinkSync,
@@ -6978,7 +7910,7 @@ function isZamSkillCopy(destinationDir) {
     if (!lstatSync(destinationDir).isDirectory()) return false;
     const skillFile = join15(destinationDir, "SKILL.md");
     if (!existsSync15(skillFile)) return false;
-    return /^name:\s*zam\s*$/m.test(readFileSync10(skillFile, "utf8"));
+    return /^name:\s*zam\s*$/m.test(readFileSync11(skillFile, "utf8"));
   } catch {
     return false;
   }
@@ -7111,7 +8043,7 @@ ${ZAM_BLOCK_END}`;
     }
     return "write";
   }
-  const existing = readFileSync10(dest, "utf8");
+  const existing = readFileSync11(dest, "utf8");
   if (existing.includes(block)) return "skip";
   const start = existing.indexOf(ZAM_BLOCK_START);
   const end = existing.indexOf(ZAM_BLOCK_END);
@@ -8646,7 +9578,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
         return;
       }
     }
-    const imageBytes = readFileSync11(outputPath);
+    const imageBytes = readFileSync12(outputPath);
     const base64 = imageBytes.toString("base64");
     jsonOut2({
       sessionId: opts.session ?? null,
@@ -8768,7 +9700,7 @@ bridgeCommand.command("stop-recording").description(
   }
   const sessionId = opts.session;
   const statePath = join18(tmpdir3(), `zam-recording-${sessionId}.json`);
-  const { existsSync: existsSync26, readFileSync: readFileSync16, rmSync: rmSync4 } = await import("fs");
+  const { existsSync: existsSync26, readFileSync: readFileSync17, rmSync: rmSync4 } = await import("fs");
   if (!existsSync26(statePath)) {
     jsonOut2({
       sessionId,
@@ -8777,7 +9709,7 @@ bridgeCommand.command("stop-recording").description(
     });
     return;
   }
-  const state = JSON.parse(readFileSync16(statePath, "utf8"));
+  const state = JSON.parse(readFileSync17(statePath, "utf8"));
   const { pid, outputPath } = state;
   try {
     process.kill(pid, "SIGINT");
@@ -9043,7 +9975,7 @@ bridgeCommand.command("cloud-model-hint").description("Suggest a cloud model for
 bridgeCommand.command("local-llm-hints").description("Detect installed local LLM servers and suggest defaults (JSON)").action(() => {
   const profile = getSystemProfile();
   const flmInstalled = hasCommand("flm") || existsSync17("C:\\Program Files\\flm\\flm.exe");
-  const ollamaInstalled = hasCommand("ollama");
+  const ollamaInstalled = isOllamaInstalled();
   const runners = [
     { id: "flm", label: "FastFlowLM", installed: flmInstalled },
     { id: "ollama", label: "Ollama", installed: ollamaInstalled },
@@ -9291,6 +10223,388 @@ bridgeCommand.command("get-neighborhood").description(
     });
   });
 });
+bridgeCommand.command("personal-card-list").description("List and search personal learning cards (JSON)").option("--user <id>", "User ID (default: whoami)").option("--query <query>", "Text search query").option("--domain <domain>", "Filter by category/domain").action(async (opts) => {
+  await withDb2(async (db) => {
+    const userId = await resolveUser(opts, db, { json: true });
+    const cards = await listPersonalCards(db, userId, {
+      query: opts.query,
+      domain: opts.domain
+    });
+    jsonOut2({ cards });
+  });
+});
+bridgeCommand.command("personal-card-create").description("Atomically create a token and its personal card (JSON)").option("--user <id>", "User ID (default: whoami)").requiredOption("--concept <concept>", "Concept description / answer").option("--domain <domain>", "Knowledge category / domain", "").option("--question <question>", "Question prompt for recall").option("--source-link <link>", "Source file path or reference URL").option("--bloom <level>", "Bloom taxonomy level (1-5)", "1").option(
+  "--mode <mode>",
+  "Symbiosis mode: shadowing | copilot | autonomy | none",
+  "none"
+).option("--context <context>", "Context description", "").action(async (opts) => {
+  await withDb2(async (db) => {
+    const userId = await resolveUser(opts, db, { json: true });
+    const bloom = Number(opts.bloom);
+    if (bloom < 1 || bloom > 5) {
+      jsonError("bloom must be between 1 and 5");
+    }
+    const mode = opts.mode === "none" ? null : opts.mode;
+    if (mode && !["shadowing", "copilot", "autonomy"].includes(mode)) {
+      jsonError(`Invalid mode: ${opts.mode}`);
+    }
+    const slug = await generateTokenSlug(
+      db,
+      opts.domain,
+      opts.concept,
+      opts.question
+    );
+    let question = opts.question || null;
+    if (!question) {
+      question = generateConceptFreeCue(bloom, slug, opts.domain);
+    }
+    const { token, card } = await db.transaction(async (tx) => {
+      const createdToken = await createToken(tx, {
+        slug,
+        concept: opts.concept,
+        domain: opts.domain,
+        bloom_level: bloom,
+        context: opts.context,
+        symbiosis_mode: mode,
+        source_link: opts.sourceLink || null,
+        question
+      });
+      const createdCard = await ensureCard(tx, createdToken.id, userId);
+      return { token: createdToken, card: createdCard };
+    });
+    jsonOut2({
+      success: true,
+      token: {
+        id: token.id,
+        slug: token.slug,
+        concept: token.concept,
+        domain: token.domain,
+        bloomLevel: token.bloom_level,
+        context: token.context,
+        symbiosisMode: token.symbiosis_mode,
+        sourceLink: token.source_link,
+        question: token.question,
+        createdAt: token.created_at,
+        updatedAt: token.updated_at
+      },
+      card: {
+        id: card.id,
+        tokenId: card.token_id,
+        userId: card.user_id,
+        state: card.state,
+        dueAt: card.due_at,
+        blocked: card.blocked
+      }
+    });
+  });
+});
+bridgeCommand.command("personal-card-update").description("Update the mutable token fields of a personal card (JSON)").option("--user <id>", "User ID (default: whoami)").requiredOption("--slug <slug>", "Token slug to update").option("--concept <concept>", "Updated concept text").option("--domain <domain>", "Updated domain / category").option("--bloom <level>", "Updated Bloom taxonomy level (1-5)").option("--context <context>", "Updated context").option(
+  "--mode <mode>",
+  "Updated symbiosis mode: shadowing | copilot | autonomy | none"
+).option("--source-link <link>", "Updated source link").option("--question <question>", "Updated question text").action(async (opts) => {
+  await withDb2(async (db) => {
+    const userId = await resolveUser(opts, db, { json: true });
+    const updates = {};
+    if (opts.concept !== void 0) updates.concept = opts.concept;
+    if (opts.domain !== void 0) updates.domain = opts.domain;
+    if (opts.bloom !== void 0) {
+      const bloom = Number(opts.bloom);
+      if (bloom < 1 || bloom > 5) {
+        jsonError("bloom must be between 1 and 5");
+      }
+      updates.bloom_level = bloom;
+    }
+    if (opts.context !== void 0) updates.context = opts.context;
+    if (opts.sourceLink !== void 0) {
+      updates.source_link = opts.sourceLink === "" ? null : opts.sourceLink;
+    }
+    if (opts.question !== void 0) {
+      updates.question = opts.question === "" ? null : opts.question;
+    }
+    if (opts.mode !== void 0) {
+      const validModes = ["shadowing", "copilot", "autonomy", "none"];
+      if (!validModes.includes(opts.mode)) {
+        jsonError(`Invalid mode: ${opts.mode}`);
+      }
+      updates.symbiosis_mode = opts.mode === "none" ? null : opts.mode;
+    }
+    const token = await db.transaction(async (tx) => {
+      const existingToken = await getTokenBySlug(tx, opts.slug);
+      if (!existingToken) {
+        throw new Error(`Token not found: ${opts.slug}`);
+      }
+      const card = await getCard(tx, existingToken.id, userId);
+      if (!card) {
+        throw new Error(
+          `Card not found for token ${opts.slug} and user ${userId}`
+        );
+      }
+      return updateToken(tx, opts.slug, updates);
+    });
+    jsonOut2({
+      success: true,
+      token: {
+        id: token.id,
+        slug: token.slug,
+        concept: token.concept,
+        domain: token.domain,
+        bloomLevel: token.bloom_level,
+        context: token.context,
+        symbiosisMode: token.symbiosis_mode,
+        sourceLink: token.source_link,
+        question: token.question,
+        createdAt: token.created_at,
+        updatedAt: token.updated_at
+      }
+    });
+  });
+});
+bridgeCommand.command("personal-card-remove").description(
+  "Remove a personal card (optionally previewing the effects) (JSON)"
+).option("--user <id>", "User ID (default: whoami)").requiredOption("--slug <slug>", "Token slug").option("--confirm", "Perform the deletion instead of a preview").action(async (opts) => {
+  await withDb2(async (db) => {
+    const userId = await resolveUser(opts, db, { json: true });
+    const token = await getTokenBySlug(db, opts.slug);
+    if (!token) {
+      jsonError(`Token not found: ${opts.slug}`);
+    }
+    const card = await getCard(db, token.id, userId);
+    if (!card) {
+      jsonError(`Card not found for token ${opts.slug} and user ${userId}`);
+    }
+    if (!opts.confirm) {
+      const impact = await getCardDeletionImpact(db, token.id, userId);
+      jsonOut2({
+        success: true,
+        preview: true,
+        requiresConfirmation: true,
+        token: { id: token.id, slug: token.slug },
+        impact
+      });
+      return;
+    }
+    const result = await deleteCardForUser(db, token.id, userId);
+    jsonOut2({
+      success: true,
+      deletedCard: {
+        id: result.card.id,
+        tokenId: result.card.token_id,
+        userId: result.card.user_id
+      },
+      impact: result.impact
+    });
+  });
+});
+bridgeCommand.command("personal-card-delete").description("Hard-delete a token and all its dependencies (JSON)").requiredOption("--slug <slug>", "Token slug").option("--confirm", "Perform the deletion instead of a preview").action(async (opts) => {
+  await withDb2(async (db) => {
+    const token = await getTokenBySlug(db, opts.slug);
+    if (!token) {
+      jsonError(`Token not found: ${opts.slug}`);
+    }
+    if (!opts.confirm) {
+      const impact = await getTokenDeleteImpact(db, opts.slug);
+      jsonOut2({
+        success: true,
+        preview: true,
+        requiresConfirmation: true,
+        token: { id: token.id, slug: token.slug },
+        impact
+      });
+      return;
+    }
+    const result = await deleteToken(db, opts.slug);
+    jsonOut2({
+      success: true,
+      deletedToken: {
+        id: result.token.id,
+        slug: result.token.slug
+      },
+      impact: result.impact
+    });
+  });
+});
+bridgeCommand.command("personal-card-import-curriculum").description("Parse curriculum text using LLM and import cards (JSON)").option("--user <id>", "User ID (default: whoami)").requiredOption("--text <text>", "Curriculum syllabus/content text").requiredOption(
+  "--domain <domain>",
+  "Default category/domain for imported cards"
+).option("--source <url>", "Provenance source link or URL").option("--preview", "Return parsed cards without saving them").action(async (opts) => {
+  await withDb2(async (db) => {
+    const userId = await resolveUser(opts, db, { json: true });
+    const cards = await importCurriculumViaLLM(
+      db,
+      opts.text,
+      opts.domain,
+      opts.source || null
+    );
+    if (opts.preview) {
+      jsonOut2({
+        success: true,
+        proposals: cards
+      });
+      return;
+    }
+    const result = await importCurriculumCards(db, userId, cards);
+    jsonOut2({
+      success: true,
+      createdCount: result.createdCount,
+      ensuredCount: result.ensuredCount
+    });
+  });
+});
+bridgeCommand.command("personal-card-split-proposals").description("Generate atomic proposals for splitting a card (JSON)").requiredOption("--slug <slug>", "Original token slug").action(async (opts) => {
+  await withDb2(async (db) => {
+    const token = await getTokenBySlug(db, opts.slug);
+    if (!token) {
+      jsonError(`Token not found: ${opts.slug}`);
+    }
+    const proposals = await generateSplitProposalsViaLLM(db, token);
+    jsonOut2({
+      success: true,
+      proposals
+    });
+  });
+});
+bridgeCommand.command("personal-card-confirm-split").description("Save confirmed card split and modify original card (JSON)").option("--user <id>", "User ID (default: whoami)").requiredOption("--slug <slug>", "Original token slug").requiredOption(
+  "--action <action>",
+  "Original card action: 'block' or 'remove'"
+).requiredOption(
+  "--original-question <question>",
+  "Rewritten question of the original card"
+).requiredOption(
+  "--original-concept <concept>",
+  "Rewritten concept of the original card"
+).requiredOption(
+  "--proposals <json>",
+  "JSON string representing proposals array"
+).action(async (opts) => {
+  await withDb2(async (db) => {
+    const userId = await resolveUser(opts, db, { json: true });
+    const proposals = JSON.parse(opts.proposals);
+    const result = await confirmCardSplit(
+      db,
+      userId,
+      opts.slug,
+      opts.action,
+      opts.originalQuestion,
+      opts.originalConcept,
+      proposals
+    );
+    jsonOut2({
+      success: true,
+      createdCount: result.createdCount,
+      ensuredCount: result.ensuredCount
+    });
+  });
+});
+bridgeCommand.command("personal-card-foundations-proposals").description("Generate prerequisite suggestions for a card (JSON)").requiredOption("--slug <slug>", "Original token slug").action(async (opts) => {
+  await withDb2(async (db) => {
+    const token = await getTokenBySlug(db, opts.slug);
+    if (!token) {
+      jsonError(`Token not found: ${opts.slug}`);
+    }
+    const proposals = await generateFoundationsProposalsViaLLM(db, token);
+    const resolvedProposals = [];
+    for (const prop of proposals) {
+      const baseText = prop.question && prop.question.trim().length > 0 ? prop.question : prop.concept;
+      const cleanDomain = slugify(prop.domain || "");
+      const cleanBase = slugify(baseText);
+      let baseSlug = cleanDomain ? `${cleanDomain}-${cleanBase}` : cleanBase;
+      if (baseSlug.length > 60) {
+        baseSlug = baseSlug.slice(0, 60).replace(/-$/, "");
+      }
+      if (!baseSlug) {
+        baseSlug = "token";
+      }
+      const existingToken = await getTokenBySlug(db, baseSlug);
+      if (existingToken) {
+        resolvedProposals.push({
+          ...prop,
+          exists: true,
+          slug: existingToken.slug,
+          question: existingToken.question || prop.question,
+          concept: existingToken.concept,
+          domain: existingToken.domain
+        });
+      } else {
+        resolvedProposals.push({
+          ...prop,
+          exists: false,
+          slug: null
+        });
+      }
+    }
+    jsonOut2({
+      success: true,
+      proposals: resolvedProposals
+    });
+  });
+});
+bridgeCommand.command("personal-card-confirm-foundations").description("Save confirmed foundational prerequisites (JSON)").option("--user <id>", "User ID (default: whoami)").requiredOption("--slug <slug>", "Original token slug").requiredOption(
+  "--proposals <json>",
+  "JSON string representing proposals array"
+).action(async (opts) => {
+  await withDb2(async (db) => {
+    const userId = await resolveUser(opts, db, { json: true });
+    const proposals = JSON.parse(opts.proposals);
+    const result = await confirmFoundations(db, userId, opts.slug, proposals);
+    jsonOut2({
+      success: true,
+      createdCount: result.createdCount,
+      linkedCount: result.linkedCount
+    });
+  });
+});
+bridgeCommand.command("personal-source-import").description(
+  "Fetch and clean plain text from local file, web link, or vision scan (JSON)"
+).requiredOption("--type <file|web|scan>", "Source type").requiredOption("--uri <uri>", "Source path or URL").action(async (opts) => {
+  await withDb2(async (db) => {
+    let content = "";
+    if (opts.type === "file") {
+      content = await readLocalFile(opts.uri);
+    } else if (opts.type === "web") {
+      content = await readWebLink(opts.uri);
+    } else if (opts.type === "scan") {
+      content = await readImageOCR(db, opts.uri);
+    } else {
+      throw new Error(`Invalid source type: ${opts.type}`);
+    }
+    const sourceId = ulid8();
+    await db.prepare(
+      `INSERT INTO sources (id, type, uri, content)
+           VALUES (?, ?, ?, ?)
+           ON CONFLICT(uri) DO UPDATE SET
+             type = excluded.type,
+             content = excluded.content`
+    ).run(sourceId, opts.type, opts.uri, content);
+    const record = await db.prepare("SELECT id, content FROM sources WHERE uri = ?").get(opts.uri);
+    jsonOut2({
+      success: true,
+      sourceId: record.id,
+      content: record.content
+    });
+  });
+});
+bridgeCommand.command("personal-source-confirm-import").description(
+  "Confirm and save cards generated from a source reference (JSON)"
+).option("--user <id>", "User ID (default: whoami)").requiredOption("--sourceId <id>", "Source database ID").requiredOption(
+  "--proposals <json>",
+  "JSON string representing proposals array"
+).action(async (opts) => {
+  await withDb2(async (db) => {
+    const userId = await resolveUser(opts, db, { json: true });
+    const proposals = JSON.parse(opts.proposals);
+    const result = await confirmSourceImport(
+      db,
+      userId,
+      opts.sourceId,
+      proposals
+    );
+    jsonOut2({
+      success: true,
+      createdCount: result.createdCount,
+      ensuredCount: result.linkedCount
+    });
+  });
+});
 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 {
@@ -11525,7 +12839,7 @@ ${"\u2550".repeat(50)}`);
 });
 
 // src/cli/commands/session.ts
-import { readFileSync as readFileSync12 } from "fs";
+import { readFileSync as readFileSync13 } from "fs";
 import { input as input6, select as select2 } from "@inquirer/prompts";
 import { Command as Command14 } from "commander";
 var sessionCommand = new Command14("session").description(
@@ -11717,7 +13031,7 @@ function loadPatternFile(path) {
   if (!path) return [];
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync12(path, "utf-8"));
+    parsed = JSON.parse(readFileSync13(path, "utf-8"));
   } catch (err) {
     throw new Error(
       `Cannot read synthesis patterns from ${path}: ${err.message}`
@@ -12266,7 +13580,7 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
 });
 
 // src/cli/commands/snapshot.ts
-import { existsSync as existsSync22, mkdirSync as mkdirSync13, readFileSync as readFileSync13, writeFileSync as writeFileSync10 } from "fs";
+import { existsSync as existsSync22, mkdirSync as mkdirSync13, readFileSync as readFileSync14, writeFileSync as writeFileSync10 } from "fs";
 import { dirname as dirname7, join as join21 } from "path";
 import { Command as Command18 } from "commander";
 function defaultOutName() {
@@ -12319,7 +13633,7 @@ var importCmd = new Command18("import").description("Restore a snapshot into the
       console.error(`Error: Snapshot file not found: ${file}`);
       process.exit(1);
     }
-    const snapshot = readFileSync13(file, "utf-8");
+    const snapshot = readFileSync14(file, "utf-8");
     db = await openDatabaseWithSync({ initialize: true });
     const result = await importSnapshot(db, snapshot, { force: opts.force });
     await db.close();
@@ -12341,7 +13655,7 @@ var verifyCmd = new Command18("verify").description("Check a snapshot's manifest
       console.error(`Error: Snapshot file not found: ${file}`);
       process.exit(1);
     }
-    const manifest = verifySnapshot(readFileSync13(file, "utf-8"));
+    const manifest = verifySnapshot(readFileSync14(file, "utf-8"));
     const { total, nonEmpty } = summarize(manifest.tables);
     console.log(`Valid snapshot (format v${manifest.version})`);
     console.log(`  created: ${manifest.createdAt}`);
@@ -12969,7 +14283,7 @@ ${C3.dim}After that, 'zam ui' launches it directly.${C3.reset}`
 
 // src/cli/commands/update.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync24, readFileSync as readFileSync14, realpathSync as realpathSync2 } from "fs";
+import { existsSync as existsSync24, readFileSync as readFileSync15, realpathSync as realpathSync2 } from "fs";
 import { dirname as dirname9, join as join23 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { confirm as confirm3 } from "@inquirer/prompts";
@@ -12995,7 +14309,7 @@ function currentVersion() {
   for (const up of ["..", "../..", "../../.."]) {
     try {
       const pkg2 = JSON.parse(
-        readFileSync14(join23(here, up, "package.json"), "utf-8")
+        readFileSync15(join23(here, up, "package.json"), "utf-8")
       );
       if (pkg2.version) return pkg2.version;
     } catch {
@@ -13006,7 +14320,7 @@ function currentVersion() {
 function versionAt(dir) {
   try {
     const pkg2 = JSON.parse(
-      readFileSync14(join23(dir, "package.json"), "utf-8")
+      readFileSync15(join23(dir, "package.json"), "utf-8")
     );
     return pkg2.version ?? "unknown";
   } catch {
@@ -13641,7 +14955,7 @@ workspaceCommand.command("backup").description("Back up the local ZAM database i
 // src/cli/index.ts
 var __dirname = dirname10(fileURLToPath5(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync15(join25(__dirname, "..", "..", "package.json"), "utf-8")
+  readFileSync16(join25(__dirname, "..", "..", "package.json"), "utf-8")
 );
 var program = new Command25();
 program.name("zam").description(