zam-core 0.13.0 → 0.15.0

package/dist/cli/app.js

@@ -590,7 +590,13 @@ CREATE TABLE IF NOT EXISTS tokens (
   -- validated in code, not via CHECK. Column default is 'llm' so unlabeled
   -- writes (pre-M013 rows, old snapshot restores) count as LLM-era content;
   -- createToken() defaults to 'manual' for API callers instead.
-  question_source TEXT NOT NULL DEFAULT 'llm'
+  question_source TEXT NOT NULL DEFAULT 'llm',
+  -- Maintenance state (ADR 2026-07-18): when set, the token's binding to
+  -- its source is unclear (e.g. stale source_link after an article split,
+  -- or an ambiguous re-import). Cards of a token in maintenance are
+  -- excluded from scheduling until repaired; learning state is preserved.
+  maintenance_at     TEXT,
+  maintenance_reason TEXT
 );
 
 -- Prerequisite dependency graph: "to learn A, first know B"
@@ -1140,6 +1146,10 @@ async function runMigrations(db) {
       `ALTER TABLE tokens ADD COLUMN question_source TEXT NOT NULL DEFAULT 'llm'`
     );
   }
+  if (tokenCols.length > 0 && !tokenCols.some((c) => c.name === "maintenance_at")) {
+    await db.exec(`ALTER TABLE tokens ADD COLUMN maintenance_at TEXT`);
+    await db.exec(`ALTER TABLE tokens ADD COLUMN maintenance_reason TEXT`);
+  }
 }
 var DEFAULT_DB_DIR, DEFAULT_DB_PATH, nodeRequire, TRANSIENT_REMOTE_ERROR_PATTERNS;
 var init_connection = __esm({
@@ -1630,6 +1640,23 @@ async function updateCard(db, cardId, updates) {
   }
   return await db.prepare("SELECT * FROM cards WHERE id = ?").get(cardId);
 }
+async function resetCardsForToken(db, tokenId, now) {
+  const ts = now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const result = await db.prepare(
+    `UPDATE cards SET
+         stability = 0.0,
+         difficulty = 0.5,
+         elapsed_days = 0.0,
+         scheduled_days = 0.0,
+         reps = 0,
+         lapses = 0,
+         state = 'new',
+         due_at = ?,
+         last_review_at = NULL
+       WHERE token_id = ?`
+  ).run(ts, tokenId);
+  return result.changes;
+}
 async function getCardDeletionImpact(db, tokenId, userId) {
   const card = await getCard(db, tokenId, userId);
   if (!card) {
@@ -1652,7 +1679,8 @@ async function getDueCards(db, userId, now, domain, knowledgeContext) {
   let sql = `SELECT c.*, t.slug, t.concept, t.domain, t.bloom_level
     FROM cards c
     JOIN tokens t ON t.id = c.token_id
-    WHERE c.user_id = ? AND c.blocked = 0 AND c.due_at <= ?`;
+    WHERE c.user_id = ? AND c.blocked = 0 AND c.due_at <= ?
+      AND t.maintenance_at IS NULL`;
   const params = [userId, cutoff];
   if (domain) {
     sql += " AND t.domain = ?";
@@ -1953,6 +1981,38 @@ async function deprecateToken(db, slug) {
   ).run(now, now, slug);
   return await getTokenBySlug(db, slug);
 }
+async function getTokensBySourceLinkBase(db, base) {
+  return await db.prepare(
+    `SELECT * FROM tokens
+       WHERE (source_link = ? OR source_link LIKE ? || '#%' ESCAPE '\\')
+         AND deprecated_at IS NULL`
+  ).all(base, escapeLike(base));
+}
+function escapeLike(value) {
+  return value.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+async function setTokenMaintenance(db, slug, reason) {
+  const token = await getTokenBySlug(db, slug);
+  if (!token) {
+    throw new Error(`Token not found: ${slug}`);
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  await db.prepare(
+    "UPDATE tokens SET maintenance_at = ?, maintenance_reason = ?, updated_at = ? WHERE slug = ?"
+  ).run(now, reason, now, slug);
+  return await getTokenBySlug(db, slug);
+}
+async function clearTokenMaintenance(db, slug) {
+  const token = await getTokenBySlug(db, slug);
+  if (!token) {
+    throw new Error(`Token not found: ${slug}`);
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  await db.prepare(
+    "UPDATE tokens SET maintenance_at = NULL, maintenance_reason = NULL, updated_at = ? WHERE slug = ?"
+  ).run(now, slug);
+  return await getTokenBySlug(db, slug);
+}
 async function getTokenDeleteImpact(db, slug) {
   const token = await getTokenBySlug(db, slug);
   if (!token) {
@@ -2080,6 +2140,15 @@ async function listTokens(db, options) {
     )`);
     params.push(options.knowledgeContext);
   }
+  if (options?.sourceLinkBases) {
+    const clauses = options.sourceLinkBases.map(
+      () => `(source_link = ? OR source_link LIKE ? || '#%' ESCAPE '\\')`
+    );
+    whereClauses.push(clauses.length ? `(${clauses.join(" OR ")})` : "0 = 1");
+    for (const base of options.sourceLinkBases) {
+      params.push(base, escapeLike(base));
+    }
+  }
   const orderBy = options?.domain || options?.domainPrefix ? "ORDER BY bloom_level, slug" : "ORDER BY bloom_level, domain, slug";
   const sql = `SELECT * FROM tokens WHERE ${whereClauses.join(" AND ")} ${orderBy}`;
   const tokens = await db.prepare(sql).all(...params);
@@ -5268,7 +5337,8 @@ async function buildReviewQueue(db, options) {
          AND c.blocked = 0
          AND c.due_at <= ?
          AND c.state IN ('review', 'relearning', 'learning')
-         AND t.deprecated_at IS NULL`;
+         AND t.deprecated_at IS NULL
+         AND t.maintenance_at IS NULL`;
   const dueParams = [options.userId, nowISO];
   if (options.knowledgeContext) {
     dueSql += ` AND EXISTS (
@@ -5298,7 +5368,8 @@ async function buildReviewQueue(db, options) {
        WHERE c.user_id = ?
          AND c.blocked = 0
          AND c.state = 'new'
-         AND t.deprecated_at IS NULL`;
+         AND t.deprecated_at IS NULL
+         AND t.maintenance_at IS NULL`;
   const newParams = [options.userId];
   if (options.knowledgeContext) {
     newSql += ` AND EXISTS (
@@ -6992,6 +7063,7 @@ __export(kernel_exports, {
   clearADOCredentials: () => clearADOCredentials,
   clearProviderApiKey: () => clearProviderApiKey,
   clearReviewContextCache: () => clearReviewContextCache,
+  clearTokenMaintenance: () => clearTokenMaintenance,
   clearTursoCredentials: () => clearTursoCredentials,
   compareVersions: () => compareVersions,
   computeContentHash: () => computeContentHash,
@@ -7100,6 +7172,7 @@ __export(kernel_exports, {
   getTokenDeleteImpact: () => getTokenDeleteImpact,
   getTokenEmbedding: () => getTokenEmbedding,
   getTokenNeighborhood: () => getTokenNeighborhood,
+  getTokensBySourceLinkBase: () => getTokensBySourceLinkBase,
   getTursoCredentials: () => getTursoCredentials,
   getUiObservationPath: () => getUiObservationPath,
   getUiObserverDir: () => getUiObserverDir,
@@ -7154,6 +7227,7 @@ __export(kernel_exports, {
   readMonitorLog: () => readMonitorLog,
   readUiObservationLog: () => readUiObservationLog,
   removeConfiguredWorkspace: () => removeConfiguredWorkspace,
+  resetCardsForToken: () => resetCardsForToken,
   resolveAllBeliefPaths: () => resolveAllBeliefPaths,
   resolveAllGoalPaths: () => resolveAllGoalPaths,
   resolveObserverPolicy: () => resolveObserverPolicy,
@@ -7185,6 +7259,7 @@ __export(kernel_exports, {
   setLastRepairedVersion: () => setLastRepairedVersion,
   setProviderApiKey: () => setProviderApiKey,
   setSetting: () => setSetting,
+  setTokenMaintenance: () => setTokenMaintenance,
   setTursoCredentials: () => setTursoCredentials,
   slugify: () => slugify,
   startSession: () => startSession,
@@ -7259,10 +7334,337 @@ var init_kernel = __esm({
   }
 });
 
+// src/cli/okf/bundle.ts
+var bundle_exports = {};
+__export(bundle_exports, {
+  OKF_VERSION: () => OKF_VERSION,
+  RESERVED_FILES: () => RESERVED_FILES,
+  appendLog: () => appendLog,
+  buildCatalog: () => buildCatalog,
+  isReservedFile: () => isReservedFile,
+  parseFrontmatter: () => parseFrontmatter,
+  renderIndex: () => renderIndex,
+  toCatalogEntry: () => toCatalogEntry,
+  validateArticle: () => validateArticle
+});
+function isReservedFile(file) {
+  return RESERVED_FILES.includes(file);
+}
+function unquote(raw) {
+  const v = raw.trim();
+  if (v.length >= 2 && (v.startsWith('"') && v.endsWith('"') || v.startsWith("'") && v.endsWith("'"))) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+function parseFrontmatter(markdown) {
+  const lines = markdown.split("\n");
+  if (lines[0]?.trim() !== "---") {
+    throw new Error("frontmatter: file must start with a --- fence");
+  }
+  const fields = {};
+  let listKey = null;
+  let i = 1;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "---") break;
+    if (line.trim() === "") continue;
+    const listItem = /^\s+-\s+(.+)$/.exec(line);
+    if (listItem) {
+      if (!listKey) {
+        throw new Error(`frontmatter line ${i + 1}: list item without a key`);
+      }
+      fields[listKey].push(unquote(listItem[1]));
+      continue;
+    }
+    const pair = /^([A-Za-z0-9_-]+):(.*)$/.exec(line);
+    if (!pair) {
+      throw new Error(
+        `frontmatter line ${i + 1}: expected "key: value" or "- item"`
+      );
+    }
+    const key = pair[1];
+    const rest = pair[2].trim();
+    if (rest === "") {
+      fields[key] = [];
+      listKey = key;
+    } else {
+      fields[key] = unquote(rest);
+      listKey = null;
+    }
+  }
+  if (i >= lines.length) {
+    throw new Error("frontmatter: missing closing --- fence");
+  }
+  return { fields, body: lines.slice(i + 1).join("\n") };
+}
+function scalar(fields, key) {
+  const v = fields[key];
+  return typeof v === "string" && v.trim() !== "" ? v.trim() : void 0;
+}
+function validateArticle(file, markdown) {
+  const problems = [];
+  if (isReservedFile(file)) {
+    return { ok: false, problems: [`${file}: reserved OKF file name`] };
+  }
+  if (!FILE_NAME_RE.test(file)) {
+    problems.push(`${file}: file name must be kebab-case and end in .md`);
+  }
+  let parsed = null;
+  try {
+    parsed = parseFrontmatter(markdown);
+  } catch (err) {
+    problems.push(
+      `${file}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (parsed) {
+    if (!scalar(parsed.fields, "type")) {
+      problems.push(`${file}: frontmatter field "type" is required`);
+    }
+    if (!scalar(parsed.fields, "description")) {
+      problems.push(`${file}: frontmatter field "description" is required`);
+    }
+    if (parsed.body.trim() === "") {
+      problems.push(`${file}: article body is empty`);
+    }
+  }
+  return { ok: problems.length === 0, problems };
+}
+function toCatalogEntry(file, markdown) {
+  const { fields } = parseFrontmatter(markdown);
+  const tags = Array.isArray(fields.tags) ? fields.tags : [];
+  return {
+    file,
+    type: scalar(fields, "type") ?? "",
+    title: scalar(fields, "title") ?? file.replace(/\.md$/, ""),
+    description: scalar(fields, "description") ?? "",
+    tags,
+    resource: scalar(fields, "resource"),
+    timestamp: scalar(fields, "timestamp")
+  };
+}
+function buildCatalog(articles) {
+  return articles.map(({ file, markdown }) => toCatalogEntry(file, markdown)).sort((a, b) => a.file.localeCompare(b.file));
+}
+function renderIndex(catalog, okfVersion = OKF_VERSION) {
+  const types = [...new Set(catalog.map((e) => e.type))].sort();
+  const sections = types.map((type) => {
+    const rows = catalog.filter((e) => e.type === type).map((e) => `- [${e.title}](${e.file}) \u2014 ${e.description}`).join("\n");
+    return `## ${type}
+
+${rows}`;
+  });
+  return [
+    "---",
+    `okf_version: "${okfVersion}"`,
+    "---",
+    "",
+    "# ZAM Knowledge Base",
+    "",
+    "Living reference knowledge for this repository in",
+    "[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog).",
+    "Current truth only \u2014 the *why* behind it lives in [../adr/](../adr/)",
+    "(ADR 2026-07-17). Do not edit by hand: write through the",
+    "`zam_okf_upsert` MCP tool.",
+    "",
+    sections.join("\n\n"),
+    ""
+  ].join("\n");
+}
+function appendLog(existing, date, line) {
+  const header = `## ${date}`;
+  const entry = `- ${line}`;
+  const trimmed = existing.trim();
+  if (trimmed === "") {
+    return `# Log
+
+${header}
+
+${entry}
+`;
+  }
+  const lines = trimmed.split("\n");
+  const firstHeaderIdx = lines.findIndex((l) => l.startsWith("## "));
+  if (firstHeaderIdx !== -1 && lines[firstHeaderIdx].trim() === header) {
+    lines.splice(firstHeaderIdx + 2, 0, entry);
+    return `${lines.join("\n")}
+`;
+  }
+  const insertAt = firstHeaderIdx === -1 ? lines.length : firstHeaderIdx;
+  lines.splice(insertAt, 0, header, "", entry, "");
+  return `${lines.join("\n")}
+`;
+}
+var OKF_VERSION, RESERVED_FILES, FILE_NAME_RE;
+var init_bundle = __esm({
+  "src/cli/okf/bundle.ts"() {
+    "use strict";
+    OKF_VERSION = "0.1";
+    RESERVED_FILES = ["index.md", "log.md"];
+    FILE_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*\.md$/;
+  }
+});
+
+// src/cli/okf/io.ts
+var io_exports = {};
+__export(io_exports, {
+  DEFAULT_BUNDLE_DIR: () => DEFAULT_BUNDLE_DIR,
+  collectSourceLinkBases: () => collectSourceLinkBases,
+  findRepoRoot: () => findRepoRoot,
+  loadBundle: () => loadBundle,
+  resolveArticlePath: () => resolveArticlePath,
+  resolveBundleDirFromRoots: () => resolveBundleDirFromRoots,
+  resolveCitationPath: () => resolveCitationPath,
+  upsertArticle: () => upsertArticle
+});
+import {
+  existsSync as existsSync18,
+  mkdirSync as mkdirSync12,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync14,
+  realpathSync,
+  writeFileSync as writeFileSync10
+} from "fs";
+import { dirname as dirname9, isAbsolute as isAbsolute2, join as join18, relative, resolve as resolve5, sep } from "path";
+import { fileURLToPath as fileURLToPath5 } from "url";
+function resolveBundleDirFromRoots(rootUris, fallback) {
+  const dirs = [];
+  for (const uri of rootUris) {
+    if (!uri?.startsWith("file:")) continue;
+    try {
+      dirs.push(join18(fileURLToPath5(uri), DEFAULT_BUNDLE_DIR));
+    } catch {
+    }
+  }
+  return dirs.find((dir) => existsSync18(dir)) ?? dirs[0] ?? fallback;
+}
+function collectSourceLinkBases(dir) {
+  const bundle = loadBundle(dir);
+  return bundle.catalog.map(
+    (entry) => entry.resource ?? resolveArticlePath(dir, entry.file)
+  );
+}
+function resolveArticlePath(dir, file) {
+  if (file.includes("/") || file.includes("\\") || file.includes("..")) {
+    throw new Error(`invalid article file name: ${file}`);
+  }
+  if (isReservedFile(file)) {
+    throw new Error(`refusing to address reserved file: ${file}`);
+  }
+  return join18(resolve5(dir), file);
+}
+function findRepoRoot(startDir) {
+  let dir = resolve5(startDir);
+  for (; ; ) {
+    if (existsSync18(join18(dir, ".git"))) return dir;
+    const parent = dirname9(dir);
+    if (parent === dir) return resolve5(startDir, "..");
+    dir = parent;
+  }
+}
+function resolveCitationPath(bundleDir, target) {
+  if (isAbsolute2(target)) {
+    throw new Error(
+      `invalid citation target: absolute paths are not allowed (${target})`
+    );
+  }
+  if (!target.endsWith(".md")) {
+    throw new Error(
+      `invalid citation target: only .md files are readable (${target})`
+    );
+  }
+  const root = findRepoRoot(bundleDir);
+  const resolved = resolve5(bundleDir, target);
+  assertContained(root, resolved, target);
+  if (existsSync18(resolved)) {
+    assertContained(realpathSync(root), realpathSync(resolved), target);
+  }
+  return resolved;
+}
+function assertContained(root, candidate, target) {
+  const rel = relative(root, candidate);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute2(rel)) {
+    throw new Error(
+      `invalid citation target: resolves outside the repository root (${target})`
+    );
+  }
+}
+function loadBundle(dir) {
+  const root = resolve5(dir);
+  let entries;
+  try {
+    entries = readdirSync2(root).filter(
+      (name) => name.endsWith(".md") && !isReservedFile(name)
+    );
+  } catch {
+    throw new Error(`OKF bundle directory not found: ${root}`);
+  }
+  const articles = entries.sort().map((file) => ({
+    file,
+    markdown: readFileSync14(join18(root, file), "utf8")
+  }));
+  const problems = articles.flatMap(
+    ({ file, markdown }) => validateArticle(file, markdown).problems
+  );
+  const catalog = problems.length === 0 ? buildCatalog(articles) : safeCatalog(articles);
+  return { dir: root, articles, catalog, problems };
+}
+function safeCatalog(articles) {
+  const entries = [];
+  for (const { file, markdown } of articles) {
+    try {
+      entries.push(toCatalogEntry(file, markdown));
+    } catch {
+    }
+  }
+  return entries.sort((a, b) => a.file.localeCompare(b.file));
+}
+function upsertArticle(dir, file, markdown, today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)) {
+  const target = resolveArticlePath(dir, file);
+  const validation = validateArticle(file, markdown);
+  if (!validation.ok) return { validation };
+  const root = resolve5(dir);
+  mkdirSync12(root, { recursive: true });
+  let created = true;
+  try {
+    readFileSync14(target, "utf8");
+    created = false;
+  } catch {
+  }
+  writeFileSync10(target, markdown, "utf8");
+  const bundle = loadBundle(root);
+  writeFileSync10(join18(root, "index.md"), renderIndex(bundle.catalog), "utf8");
+  let log = "";
+  try {
+    log = readFileSync14(join18(root, "log.md"), "utf8");
+  } catch {
+  }
+  const entry = bundle.catalog.find((e) => e.file === file);
+  writeFileSync10(
+    join18(root, "log.md"),
+    appendLog(
+      log,
+      today,
+      `**${created ? "Creation" : "Update"}** \u2014 [${entry?.title ?? file}](${file})`
+    ),
+    "utf8"
+  );
+  return { validation, entry, created };
+}
+var DEFAULT_BUNDLE_DIR;
+var init_io = __esm({
+  "src/cli/okf/io.ts"() {
+    "use strict";
+    init_bundle();
+    DEFAULT_BUNDLE_DIR = "docs/okf";
+  }
+});
+
 // src/cli/app.ts
-import { readFileSync as readFileSync21 } from "fs";
-import { dirname as dirname14, join as join30 } from "path";
-import { fileURLToPath as fileURLToPath8 } from "url";
+import { readFileSync as readFileSync22 } from "fs";
+import { dirname as dirname15, join as join31 } from "path";
+import { fileURLToPath as fileURLToPath9 } from "url";
 import { Command as Command27 } from "commander";
 
 // src/cli/commands/agent.ts
@@ -8600,9 +9002,9 @@ var agentCommand = new Command("agent").description("Provision and inspect the a
 init_kernel();
 import { execFileSync as execFileSync5 } from "child_process";
 import { randomBytes as randomBytes2 } from "crypto";
-import { existsSync as existsSync21, readdirSync as readdirSync2, readFileSync as readFileSync17, rmSync as rmSync3 } from "fs";
+import { existsSync as existsSync22, readdirSync as readdirSync3, readFileSync as readFileSync18, rmSync as rmSync3 } from "fs";
 import { homedir as homedir14, tmpdir as tmpdir3 } from "os";
-import { join as join23, resolve as resolve6 } from "path";
+import { join as join24, resolve as resolve7 } from "path";
 import { Command as Command2 } from "commander";
 import { ulid as ulid10 } from "ulid";
 
@@ -9689,7 +10091,7 @@ async function prepareRecallChain(db, opts) {
       } else {
         spawnLocalRunner(endpoint.url, endpoint.model, endpoint.runner);
         while (Date.now() < deadline) {
-          await new Promise((resolve12) => setTimeout(resolve12, 1e3));
+          await new Promise((resolve13) => setTimeout(resolve13, 1e3));
           if (await isLlmOnline(endpoint.url)) {
             online = true;
             break;
@@ -9982,7 +10384,7 @@ async function startLocalRunner(url, model, locale, hint) {
   let attempts = 0;
   const dotsPerLine = 30;
   while (true) {
-    await new Promise((resolve12) => setTimeout(resolve12, 500));
+    await new Promise((resolve13) => setTimeout(resolve13, 500));
     if (await isLlmOnline(url)) {
       if (attempts > 0) process.stdout.write("\n");
       return true;
@@ -10071,8 +10473,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
   const dotsPerLine = 30;
   while (true) {
     let timeoutId;
-    const timeoutPromise = new Promise((resolve12) => {
-      timeoutId = setTimeout(() => resolve12("timeout"), timeoutMs);
+    const timeoutPromise = new Promise((resolve13) => {
+      timeoutId = setTimeout(() => resolve13("timeout"), timeoutMs);
     });
     const dotsInterval = setInterval(() => {
       process.stdout.write(".");
@@ -10339,7 +10741,7 @@ async function readWebLink(url) {
         redirect: "manual",
         signal: controller.signal,
         headers: {
-          "User-Agent": "ZAM-Content-Studio/0.13.0"
+          "User-Agent": "ZAM-Content-Studio/0.15.0"
         }
       });
       if (res.status >= 300 && res.status < 400) {
@@ -10404,8 +10806,8 @@ async function readImageOCR(db, imagePath) {
 
 // src/cli/bridge-handlers.ts
 init_kernel();
-import { mkdirSync as mkdirSync12, writeFileSync as writeFileSync10 } from "fs";
-import { join as join18 } from "path";
+import { mkdirSync as mkdirSync13, writeFileSync as writeFileSync11 } from "fs";
+import { join as join19 } from "path";
 
 // src/cli/knowledge-contexts.ts
 init_kernel();
@@ -11284,6 +11686,161 @@ async function addToken(db, params) {
     possible_duplicates: possibleDuplicates
   };
 }
+async function importOkfTokens(db, params) {
+  const userId = await resolveHandlerUser(db, params.user);
+  if (!params.file?.trim()) throw new Error("file must be non-empty");
+  if (!Array.isArray(params.tokens) || params.tokens.length === 0) {
+    throw new Error("tokens must be a non-empty array");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const input8 of params.tokens) {
+    const slug = input8.slug?.trim();
+    if (!slug || !input8.concept?.trim()) {
+      throw new Error("every token needs a non-empty slug and concept");
+    }
+    if (seen.has(slug)) throw new Error(`duplicate token slug: ${slug}`);
+    seen.add(slug);
+    if (input8.bloomLevel !== void 0 && (!Number.isInteger(input8.bloomLevel) || input8.bloomLevel < 1 || input8.bloomLevel > 5)) {
+      throw new Error(`bloomLevel must be 1-5 (token: ${slug})`);
+    }
+  }
+  const { DEFAULT_BUNDLE_DIR: DEFAULT_BUNDLE_DIR2, resolveArticlePath: resolveArticlePath2 } = await Promise.resolve().then(() => (init_io(), io_exports));
+  const { parseFrontmatter: parseFrontmatter2 } = await Promise.resolve().then(() => (init_bundle(), bundle_exports));
+  const { readFileSync: readFileSync23 } = await import("fs");
+  const bundleDir = params.bundleDir ?? DEFAULT_BUNDLE_DIR2;
+  const articlePath = resolveArticlePath2(bundleDir, params.file);
+  let markdown;
+  try {
+    markdown = readFileSync23(articlePath, "utf8");
+  } catch {
+    throw new Error(`Article not found: ${articlePath}`);
+  }
+  let resource;
+  try {
+    const { fields } = parseFrontmatter2(markdown);
+    resource = typeof fields.resource === "string" ? fields.resource : void 0;
+  } catch {
+    resource = void 0;
+  }
+  const sourceBase = resource ?? articlePath;
+  const sourceLinkFor = (anchor) => anchor?.trim() ? `${sourceBase}#${anchor.trim()}` : sourceBase;
+  const created = [];
+  const updated = [];
+  const replaced = [];
+  const maintenance = [];
+  let cardsEnsured = 0;
+  await db.transaction(async (tx) => {
+    const inImport = /* @__PURE__ */ new Map();
+    for (const input8 of params.tokens) {
+      const mode = input8.mode ?? "new";
+      const existing = await getTokenBySlug(tx, input8.slug);
+      if (mode === "new") {
+        if (existing) {
+          throw new Error(
+            `Token '${input8.slug}' already exists. Use mode "update" to refresh it (keeps learning state), "replace" if the concept changed (resets learning state), or choose a different slug.`
+          );
+        }
+        const token2 = await createToken(tx, {
+          slug: input8.slug,
+          title: input8.title,
+          concept: input8.concept,
+          domain: input8.domain,
+          bloom_level: input8.bloomLevel ?? 1,
+          source_link: sourceLinkFor(input8.anchor),
+          question: input8.question ?? null,
+          question_source: input8.question ? "llm" : void 0
+        });
+        inImport.set(input8.slug, token2);
+        created.push(input8.slug);
+      } else {
+        if (!existing) {
+          throw new Error(
+            `Token '${input8.slug}' does not exist \u2014 mode "${mode}" requires an existing token.`
+          );
+        }
+        const updates = {
+          concept: input8.concept,
+          source_link: sourceLinkFor(input8.anchor)
+        };
+        if (input8.title !== void 0) updates.title = input8.title;
+        if (input8.domain !== void 0) updates.domain = input8.domain;
+        if (input8.bloomLevel !== void 0) {
+          updates.bloom_level = input8.bloomLevel;
+        }
+        if (input8.question !== void 0) {
+          updates.question = input8.question;
+          updates.question_source = input8.question ? "llm" : void 0;
+        }
+        const token2 = await updateToken(tx, input8.slug, updates);
+        if (existing.maintenance_at) {
+          await clearTokenMaintenance(tx, input8.slug);
+        }
+        if (mode === "replace") {
+          await resetCardsForToken(tx, token2.id);
+          replaced.push(input8.slug);
+        } else {
+          updated.push(input8.slug);
+        }
+        inImport.set(input8.slug, token2);
+      }
+      const ctxNames = parseKnowledgeContextNames(input8.knowledgeContexts);
+      const assigned = await resolveKnowledgeContexts(tx, ctxNames);
+      const token = inImport.get(input8.slug);
+      if (token) {
+        for (const context of assigned) {
+          await assignTokenToContext(tx, token.id, context.id);
+        }
+      }
+    }
+    for (const input8 of params.tokens) {
+      const token = inImport.get(input8.slug);
+      if (!token) continue;
+      const prereqSlugs = [
+        ...new Set(
+          (input8.prerequisites ?? []).map((s) => s.trim()).filter(Boolean)
+        )
+      ];
+      for (const prereqSlug of prereqSlugs) {
+        const target = inImport.get(prereqSlug) ?? await getTokenBySlug(tx, prereqSlug);
+        if (!target) {
+          throw new Error(
+            `Prerequisite token not found: ${prereqSlug} (for '${input8.slug}')`
+          );
+        }
+        await addPrerequisite(tx, token.id, target.id);
+      }
+    }
+    for (const token of inImport.values()) {
+      await ensureCard(tx, token.id, userId);
+      cardsEnsured++;
+    }
+    const prior = await getTokensBySourceLinkBase(tx, sourceBase);
+    for (const token of prior) {
+      if (!inImport.has(token.slug)) {
+        await setTokenMaintenance(
+          tx,
+          token.slug,
+          `absent from re-import of ${params.file}`
+        );
+        maintenance.push(token.slug);
+      }
+    }
+  });
+  try {
+    await ensureTokenEmbeddings(db, { limit: 16 });
+  } catch {
+  }
+  return {
+    success: true,
+    user: userId,
+    article: { file: params.file, source_link: sourceBase },
+    created,
+    updated,
+    replaced,
+    maintenance,
+    cards: cardsEnsured
+  };
+}
 async function findTokens2(db, params) {
   const userId = await resolveHandlerUser(db, params.user);
   if (!params.context.trim()) {
@@ -11580,11 +12137,11 @@ async function backupCreate(db, params) {
   const targetDir = params.dir || (await ensureActiveWorkspace(db)).path;
   const snapshot = await exportSnapshot(db);
   const manifest = verifySnapshot(snapshot);
-  const backupDir = join18(targetDir, "zam-backups");
-  mkdirSync12(backupDir, { recursive: true });
+  const backupDir = join19(targetDir, "zam-backups");
+  mkdirSync13(backupDir, { recursive: true });
   const stamp = manifest.createdAt.replace(/[:.]/g, "-");
-  const path = join18(backupDir, `zam-snapshot-${stamp}.sql`);
-  writeFileSync10(path, snapshot, "utf-8");
+  const path = join19(backupDir, `zam-snapshot-${stamp}.sql`);
+  writeFileSync11(path, snapshot, "utf-8");
   return {
     ok: true,
     path,
@@ -11608,16 +12165,16 @@ async function updateCheck(params) {
 import { execFileSync as execFileSync4 } from "child_process";
 import {
   chmodSync as chmodSync2,
-  existsSync as existsSync18,
-  mkdirSync as mkdirSync13,
-  readFileSync as readFileSync14,
-  writeFileSync as writeFileSync11
+  existsSync as existsSync19,
+  mkdirSync as mkdirSync14,
+  readFileSync as readFileSync15,
+  writeFileSync as writeFileSync12
 } from "fs";
 import { homedir as homedir13 } from "os";
-import { delimiter as delimiter2, join as join19, resolve as resolve5 } from "path";
+import { delimiter as delimiter2, join as join20, resolve as resolve6 } from "path";
 var BUILT_CLI_PATTERN = /[\\/]dist[\\/]cli[\\/]index\.js$/;
 function normalizeForCompare(path, platform) {
-  const resolved = resolve5(path);
+  const resolved = resolve6(path);
   return platform === "win32" ? resolved.toLowerCase() : resolved;
 }
 function windowsShimContent(nodePath, cliPath) {
@@ -11657,14 +12214,14 @@ function ensureWindowsUserPath(binDir) {
   return output.endsWith("updated");
 }
 function ensureUnixUserPath(home, platform) {
-  const profile = join19(home, platform === "darwin" ? ".zprofile" : ".profile");
-  const existing = existsSync18(profile) ? readFileSync14(profile, "utf8") : "";
+  const profile = join20(home, platform === "darwin" ? ".zprofile" : ".profile");
+  const existing = existsSync19(profile) ? readFileSync15(profile, "utf8") : "";
   if (existing.includes(".zam/bin")) return false;
   const block = `
 # Added by ZAM: keep the zam CLI on PATH
 export PATH="$HOME/.zam/bin:$PATH"
 `;
-  writeFileSync11(profile, existing + block, "utf8");
+  writeFileSync12(profile, existing + block, "utf8");
   return true;
 }
 function installCliShim(options = {}) {
@@ -11672,10 +12229,10 @@ function installCliShim(options = {}) {
   const platform = options.platform ?? process.platform;
   const env = options.env ?? process.env;
   const find = options.find ?? findExecutable;
-  const nodePath = resolve5(options.nodePath ?? process.execPath);
-  const cliPath = resolve5(options.cliPath ?? process.argv[1] ?? "");
-  const binDir = join19(home, ".zam", "bin");
-  const shimPath = join19(binDir, platform === "win32" ? "zam.cmd" : "zam");
+  const nodePath = resolve6(options.nodePath ?? process.execPath);
+  const cliPath = resolve6(options.cliPath ?? process.argv[1] ?? "");
+  const binDir = join20(home, ".zam", "bin");
+  const shimPath = join20(binDir, platform === "win32" ? "zam.cmd" : "zam");
   const report = {
     status: "ok",
     binDir,
@@ -11686,7 +12243,7 @@ function installCliShim(options = {}) {
     pathUpdated: false,
     needsNewTerminal: false
   };
-  if (!BUILT_CLI_PATTERN.test(cliPath) || !existsSync18(cliPath)) {
+  if (!BUILT_CLI_PATTERN.test(cliPath) || !existsSync19(cliPath)) {
     report.status = "skipped";
     report.detail = `Not running from a built CLI entry (${cliPath}); nothing to link.`;
     return report;
@@ -11700,11 +12257,11 @@ function installCliShim(options = {}) {
       return report;
     }
     const content = platform === "win32" ? windowsShimContent(nodePath, cliPath) : unixShimContent(nodePath, cliPath);
-    const existed = existsSync18(shimPath);
-    const changed = !existed || readFileSync14(shimPath, "utf8") !== content;
+    const existed = existsSync19(shimPath);
+    const changed = !existed || readFileSync15(shimPath, "utf8") !== content;
     if (changed) {
-      mkdirSync13(binDir, { recursive: true });
-      writeFileSync11(shimPath, content, "utf8");
+      mkdirSync14(binDir, { recursive: true });
+      writeFileSync12(shimPath, content, "utf8");
       if (platform !== "win32") chmodSync2(shimPath, 493);
     }
     report.status = !existed ? "installed" : changed ? "refreshed" : "ok";
@@ -28413,40 +28970,40 @@ function getCurriculumProvider(id) {
 
 // src/cli/install-repair.ts
 init_kernel();
-import { existsSync as existsSync20 } from "fs";
+import { existsSync as existsSync21 } from "fs";
 
 // src/cli/provisioning/index.ts
 import {
-  existsSync as existsSync19,
+  existsSync as existsSync20,
   lstatSync as lstatSync2,
-  mkdirSync as mkdirSync14,
-  readFileSync as readFileSync15,
-  realpathSync,
+  mkdirSync as mkdirSync15,
+  readFileSync as readFileSync16,
+  realpathSync as realpathSync2,
   rmSync as rmSync2,
   symlinkSync,
-  writeFileSync as writeFileSync12
+  writeFileSync as writeFileSync13
 } from "fs";
-import { basename as basename4, dirname as dirname9, join as join20 } from "path";
-import { fileURLToPath as fileURLToPath5 } from "url";
+import { basename as basename4, dirname as dirname10, join as join21 } from "path";
+import { fileURLToPath as fileURLToPath6 } from "url";
 var packageRoot3 = [
-  fileURLToPath5(new URL("../..", import.meta.url)),
-  fileURLToPath5(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync19(join20(candidate, "package.json"))) ?? fileURLToPath5(new URL("../..", import.meta.url));
+  fileURLToPath6(new URL("../..", import.meta.url)),
+  fileURLToPath6(new URL("../../..", import.meta.url))
+].find((candidate) => existsSync20(join21(candidate, "package.json"))) ?? fileURLToPath6(new URL("../..", import.meta.url));
 var ALL_SETUP_AGENTS = ["claude", "copilot", "codex", "agent"];
 var SKILL_PAIRS = [
   {
-    from: join20(packageRoot3, ".claude", "skills", "zam", "SKILL.md"),
-    to: join20(".claude", "skills", "zam", "SKILL.md"),
+    from: join21(packageRoot3, ".claude", "skills", "zam", "SKILL.md"),
+    to: join21(".claude", "skills", "zam", "SKILL.md"),
     agents: ["claude", "copilot"]
   },
   {
-    from: join20(packageRoot3, ".agent", "skills", "zam", "SKILL.md"),
-    to: join20(".agent", "skills", "zam", "SKILL.md"),
+    from: join21(packageRoot3, ".agent", "skills", "zam", "SKILL.md"),
+    to: join21(".agent", "skills", "zam", "SKILL.md"),
     agents: ["agent"]
   },
   {
-    from: join20(packageRoot3, ".agents", "skills", "zam", "SKILL.md"),
-    to: join20(".agents", "skills", "zam", "SKILL.md"),
+    from: join21(packageRoot3, ".agents", "skills", "zam", "SKILL.md"),
+    to: join21(".agents", "skills", "zam", "SKILL.md"),
     agents: ["codex"]
   }
 ];
@@ -28490,7 +29047,7 @@ function isSymbolicLink(path) {
   }
 }
 function comparableRealPath(path) {
-  const real = realpathSync(path);
+  const real = realpathSync2(path);
   return process.platform === "win32" ? real.toLowerCase() : real;
 }
 function pathsResolveToSameDirectory(sourceDir, destinationDir) {
@@ -28506,15 +29063,15 @@ function linkPointsTo(sourceDir, destinationDir) {
 function isZamSkillCopy(destinationDir) {
   try {
     if (!lstatSync2(destinationDir).isDirectory()) return false;
-    const skillFile = join20(destinationDir, "SKILL.md");
-    if (!existsSync19(skillFile)) return false;
-    return /^name:\s*zam\s*$/m.test(readFileSync15(skillFile, "utf8"));
+    const skillFile = join21(destinationDir, "SKILL.md");
+    if (!existsSync20(skillFile)) return false;
+    return /^name:\s*zam\s*$/m.test(readFileSync16(skillFile, "utf8"));
   } catch {
     return false;
   }
 }
 function classifySkillDestination(sourceDir, destinationDir) {
-  if (!existsSync19(sourceDir)) return "source-missing";
+  if (!existsSync20(sourceDir)) return "source-missing";
   if (!isSymbolicLink(destinationDir) && pathsResolveToSameDirectory(sourceDir, destinationDir)) {
     return "source-directory";
   }
@@ -28531,9 +29088,9 @@ function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {})
   };
   for (const { from, to, agents: pairAgents } of SKILL_PAIRS) {
     if (!pairAgents.some((agent) => agents.has(agent))) continue;
-    const sourceDir = dirname9(from);
-    const destinationDir = dirname9(join20(cwd, to));
-    const label = dirname9(to);
+    const sourceDir = dirname10(from);
+    const destinationDir = dirname10(join21(cwd, to));
+    const label = dirname10(to);
     const state = classifySkillDestination(sourceDir, destinationDir);
     if (state === "source-missing") {
       if (!opts.quiet) {
@@ -28590,7 +29147,7 @@ function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {})
       if (destinationExists) {
         rmSync2(destinationDir, { recursive: true, force: true });
       }
-      mkdirSync14(dirname9(destinationDir), { recursive: true });
+      mkdirSync15(dirname10(destinationDir), { recursive: true });
       symlinkSync(
         sourceDir,
         destinationDir,
@@ -28606,8 +29163,8 @@ function inspectSkillLinks(cwd = process.cwd(), agents = parseSetupAgents()) {
   const results = [];
   for (const { from, to, agents: pairAgents } of SKILL_PAIRS) {
     if (!pairAgents.some((agent) => agents.has(agent))) continue;
-    const sourceDir = dirname9(from);
-    const destinationDir = dirname9(join20(cwd, to));
+    const sourceDir = dirname10(from);
+    const destinationDir = dirname10(join21(cwd, to));
     results.push({
       agents: pairAgents,
       source: sourceDir,
@@ -28633,15 +29190,15 @@ function upsertMarkedBlock(dest, blockBody, dryRun) {
   const block = `${ZAM_BLOCK_START}
 ${blockBody.trim()}
 ${ZAM_BLOCK_END}`;
-  if (!existsSync19(dest)) {
+  if (!existsSync20(dest)) {
     if (!dryRun) {
-      mkdirSync14(dirname9(dest), { recursive: true });
-      writeFileSync12(dest, `${block}
+      mkdirSync15(dirname10(dest), { recursive: true });
+      writeFileSync13(dest, `${block}
 `, "utf8");
     }
     return "write";
   }
-  const existing = readFileSync15(dest, "utf8");
+  const existing = readFileSync16(dest, "utf8");
   if (existing.includes(block)) return "skip";
   const start = existing.indexOf(ZAM_BLOCK_START);
   const end = existing.indexOf(ZAM_BLOCK_END);
@@ -28649,7 +29206,7 @@ ${ZAM_BLOCK_END}`;
 
 ${block}
 `;
-  if (!dryRun) writeFileSync12(dest, next, "utf8");
+  if (!dryRun) writeFileSync13(dest, next, "utf8");
   return start >= 0 && end > start ? "update" : "write";
 }
 function logInstructionAction(action, label, dryRun) {
@@ -28661,8 +29218,8 @@ function logInstructionAction(action, label, dryRun) {
 }
 function writeClaudeMd(skipClaudeMd, cwd = process.cwd(), opts = {}) {
   if (skipClaudeMd) return;
-  const dest = join20(cwd, "CLAUDE.md");
-  if (existsSync19(dest)) {
+  const dest = join21(cwd, "CLAUDE.md");
+  if (existsSync20(dest)) {
     if (!opts.updateExisting) {
       console.log(`  skip  CLAUDE.md (already present)`);
       return;
@@ -28705,14 +29262,14 @@ Use \`zam connector setup turso\` to store cloud credentials in
   if (opts.dryRun) {
     console.log(`  would write CLAUDE.md`);
   } else {
-    writeFileSync12(dest, content, "utf8");
+    writeFileSync13(dest, content, "utf8");
     console.log(`  write CLAUDE.md`);
   }
 }
 function writeAgentsMd(skipAgentsMd, cwd = process.cwd(), opts = {}) {
   if (skipAgentsMd) return;
-  const dest = join20(cwd, "AGENTS.md");
-  if (existsSync19(dest)) {
+  const dest = join21(cwd, "AGENTS.md");
+  if (existsSync20(dest)) {
     if (!opts.updateExisting) {
       console.log(`  skip  AGENTS.md (already present)`);
       return;
@@ -28762,12 +29319,12 @@ Codex discovers repository skills under \`.agents/skills/\`. Run
   if (opts.dryRun) {
     console.log(`  would write AGENTS.md`);
   } else {
-    writeFileSync12(dest, content, "utf8");
+    writeFileSync13(dest, content, "utf8");
     console.log(`  write AGENTS.md`);
   }
 }
 function writeCopilotInstructions(cwd = process.cwd(), opts = {}) {
-  const dest = join20(cwd, ".github", "copilot-instructions.md");
+  const dest = join21(cwd, ".github", "copilot-instructions.md");
   const action = upsertMarkedBlock(
     dest,
     `## ZAM learning sessions
@@ -28795,7 +29352,7 @@ function defaultRepairWorkspaces() {
   try {
     const agents = parseSetupAgents();
     for (const workspace of getConfiguredWorkspaces()) {
-      if (!existsSync20(workspace.path)) {
+      if (!existsSync21(workspace.path)) {
         summary.missing += 1;
         continue;
       }
@@ -28983,9 +29540,9 @@ function validateModelSave(entry, probe, now = () => (/* @__PURE__ */ new Date()
 // src/cli/llm/vision.ts
 init_kernel();
 import { randomBytes } from "crypto";
-import { readFileSync as readFileSync16 } from "fs";
+import { readFileSync as readFileSync17 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
-import { basename as basename5, join as join21 } from "path";
+import { basename as basename5, join as join22 } from "path";
 var LANGUAGE_NAMES2 = {
   en: "English",
   de: "German",
@@ -29021,25 +29578,25 @@ async function observeUiSnapshotViaLLM(db, input8) {
   const imageUrls = [];
   const isVideo = /\.(mp4|mov|m4v|avi|mkv|webm)$/i.test(input8.imagePath);
   if (isVideo) {
-    const { mkdirSync: mkdirSync19, readdirSync: readdirSync3, rmSync: rmSync4 } = await import("fs");
+    const { mkdirSync: mkdirSync20, readdirSync: readdirSync4, rmSync: rmSync4 } = await import("fs");
     const { execSync: execSync6 } = await import("child_process");
-    const tempDir = join21(
+    const tempDir = join22(
       tmpdir2(),
       `zam-frames-${randomBytes(4).toString("hex")}`
     );
-    mkdirSync19(tempDir, { recursive: true });
+    mkdirSync20(tempDir, { recursive: true });
     try {
       execSync6(
         `ffmpeg -i "${input8.imagePath}" -vf "fps=1/3,scale=1280:-1" -vsync vfr "${tempDir}/frame_%03d.png"`,
         { stdio: "ignore" }
       );
-      let files = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
+      let files = readdirSync4(tempDir).filter((f) => f.endsWith(".png")).sort();
       if (files.length === 0) {
         execSync6(
           `ffmpeg -i "${input8.imagePath}" -vframes 1 "${tempDir}/frame_001.png"`,
           { stdio: "ignore" }
         );
-        files = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
+        files = readdirSync4(tempDir).filter((f) => f.endsWith(".png")).sort();
       }
       const maxFrames = cfg.maxFrames ?? 100;
       let sampledFiles = files;
@@ -29056,7 +29613,7 @@ async function observeUiSnapshotViaLLM(db, input8) {
         }
       }
       for (const file of sampledFiles) {
-        const bytes = readFileSync16(join21(tempDir, file));
+        const bytes = readFileSync17(join22(tempDir, file));
         imageUrls.push(`data:image/png;base64,${bytes.toString("base64")}`);
       }
     } finally {
@@ -29066,7 +29623,7 @@ async function observeUiSnapshotViaLLM(db, input8) {
       }
     }
   } else {
-    const imageBytes = readFileSync16(input8.imagePath);
+    const imageBytes = readFileSync17(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")}`);
@@ -29577,13 +30134,13 @@ async function resolveUser(opts, db, resolveOpts) {
 }
 
 // src/cli/workspaces/backup.ts
-import { mkdirSync as mkdirSync15 } from "fs";
-import { join as join22 } from "path";
+import { mkdirSync as mkdirSync16 } from "fs";
+import { join as join23 } from "path";
 async function backupDatabaseTo(db, targetDir) {
-  const backupDir = join22(targetDir, "zam-backups");
-  mkdirSync15(backupDir, { recursive: true });
+  const backupDir = join23(targetDir, "zam-backups");
+  mkdirSync16(backupDir, { recursive: true });
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const dest = join22(backupDir, `zam-${stamp}.db`);
+  const dest = join23(backupDir, `zam-${stamp}.db`);
   await db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
   return dest;
 }
@@ -29717,20 +30274,20 @@ bridgeCommand.command("workspace-info").description("Report the workspace dir, i
       activeWorkspace,
       workspaceDir: activeWorkspace.path,
       defaultWorkspaceDir: defaultWorkspaceDir(),
-      dataDir: join23(homedir14(), ".zam")
+      dataDir: join24(homedir14(), ".zam")
     });
   });
 });
 function provisionConfiguredWorkspaces() {
   return getConfiguredWorkspaces().flatMap(
-    (workspace) => existsSync21(workspace.path) ? wireSkills(workspace.path, parseSetupAgents(), { quiet: true }) : []
+    (workspace) => existsSync22(workspace.path) ? wireSkills(workspace.path, parseSetupAgents(), { quiet: true }) : []
   );
 }
 function buildWorkspaceLinkHealth(workspaces) {
   const agents = parseSetupAgents();
   const map = {};
   for (const workspace of workspaces) {
-    if (!existsSync21(workspace.path)) continue;
+    if (!existsSync22(workspace.path)) continue;
     const links = inspectSkillLinks(workspace.path, agents);
     map[workspace.id] = {
       health: summarizeSkillLinkHealth(links),
@@ -29760,7 +30317,7 @@ bridgeCommand.command("workspace-list").description("List configured ZAM workspa
       activeWorkspace,
       workspaceDir: activeWorkspace.path,
       defaultWorkspaceDir: defaultWorkspaceDir(),
-      dataDir: join23(homedir14(), ".zam"),
+      dataDir: join24(homedir14(), ".zam"),
       linkHealth: buildWorkspaceLinkHealth(workspaces)
     });
   });
@@ -29775,7 +30332,7 @@ bridgeCommand.command("workspace-repair-links").description(
   if (!id) jsonError("A non-empty --id is required");
   const workspace = getConfiguredWorkspaces().find((item) => item.id === id);
   if (!workspace) jsonError(`Workspace "${id}" is not configured`);
-  if (!existsSync21(workspace.path)) {
+  if (!existsSync22(workspace.path)) {
     jsonError(`Workspace path does not exist: ${workspace.path}`);
   }
   const agents = parseSetupAgents(opts.agents);
@@ -29806,8 +30363,8 @@ function parseBridgeWorkspaceKind(value) {
 bridgeCommand.command("workspace-add").description("Register an existing directory as a ZAM workspace (JSON)").requiredOption("--path <dir>", "Existing workspace/repository directory").option("--id <id>", "Workspace id").option("--label <label>", "Human-readable label").option("--kind <kind>", "Workspace kind", "custom").action(async (opts) => {
   const raw = String(opts.path ?? "").trim();
   if (!raw) jsonError("A non-empty --path is required");
-  const path = resolve6(raw);
-  if (!existsSync21(path)) jsonError(`Workspace path does not exist: ${path}`);
+  const path = resolve7(raw);
+  if (!existsSync22(path)) jsonError(`Workspace path does not exist: ${path}`);
   const id = opts.id ? String(opts.id).trim() : void 0;
   if (opts.id && !id) jsonError("A non-empty --id is required");
   const kind = parseBridgeWorkspaceKind(opts.kind);
@@ -29851,8 +30408,8 @@ bridgeCommand.command("workspace-remove").description("Unregister a ZAM workspac
 bridgeCommand.command("set-workspace-dir").description("Set the personal workspace directory (JSON)").requiredOption("--dir <path>", "Path to the workspace directory").action(async (opts) => {
   const raw = String(opts.dir ?? "").trim();
   if (!raw) jsonError("A non-empty --dir is required");
-  const dir = resolve6(raw);
-  if (!existsSync21(dir)) jsonError(`Workspace path does not exist: ${dir}`);
+  const dir = resolve7(raw);
+  if (!existsSync22(dir)) jsonError(`Workspace path does not exist: ${dir}`);
   const skillLinks = wireSkills(dir, parseSetupAgents(), { quiet: true });
   await withOptionalDb2(async (db) => {
     const workspace = await activateWorkspacePath(db, dir);
@@ -29915,7 +30472,7 @@ bridgeCommand.command("agent-open").description("Launch an agent harness in the
       jsonError(`Workspace is not configured: ${opts.workspace}`);
     }
     const activeWorkspace = await ensureActiveWorkspace(db);
-    const workspace = opts.dir ? existsSync21(opts.dir) ? opts.dir : homedir14() : existingWorkspaceDirOrHome(configuredWorkspace ?? activeWorkspace);
+    const workspace = opts.dir ? existsSync22(opts.dir) ? opts.dir : homedir14() : existingWorkspaceDirOrHome(configuredWorkspace ?? activeWorkspace);
     launchHarness(harness, {
       executable,
       workspace,
@@ -30191,6 +30748,52 @@ bridgeCommand.command("add-token").description("Create a token + card from JSON
     jsonError(err.message);
   }
 });
+bridgeCommand.command("okf-import").description(
+  "Record an agent's decomposition of an OKF article as learning tokens (JSON stdin, ADR 2026-07-18)"
+).option("--user <id>", "User ID (default: whoami)").action(async (opts) => {
+  try {
+    let raw;
+    if (isServeMode) {
+      raw = serveStdinPayload ?? "";
+    } else {
+      const chunks = [];
+      for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+      }
+      raw = Buffer.concat(chunks).toString("utf-8").trim();
+    }
+    if (!raw) {
+      jsonError(
+        "No input received on stdin. Pipe JSON: { file, bundle_dir?, tokens: [...] }"
+      );
+    }
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      jsonError("Invalid JSON input");
+    }
+    if (!data?.file || !Array.isArray(data?.tokens)) {
+      jsonError("JSON must include 'file' and a 'tokens' array");
+    }
+    await withDb2(async (db) => {
+      try {
+        const userId = await resolveUser(opts, db, { json: true });
+        const result = await importOkfTokens(db, {
+          user: userId,
+          bundleDir: data.bundle_dir,
+          file: data.file,
+          tokens: data.tokens
+        });
+        jsonOut2(result);
+      } catch (err) {
+        jsonError(err.message);
+      }
+    });
+  } catch (err) {
+    jsonError(err.message);
+  }
+});
 bridgeCommand.command("relevant-tokens").description("Find tokens relevant to a given context").option("--user <id>", "User ID (default: whoami)").action(async (opts) => {
   try {
     let raw;
@@ -30287,10 +30890,10 @@ bridgeCommand.command("discover-skills").description(
   "20"
 ).action(async (opts) => {
   try {
-    const monitorDir = join23(homedir14(), ".zam", "monitor");
+    const monitorDir = join24(homedir14(), ".zam", "monitor");
     let files;
     try {
-      files = readdirSync2(monitorDir).filter((f) => f.endsWith(".jsonl"));
+      files = readdirSync3(monitorDir).filter((f) => f.endsWith(".jsonl"));
     } catch {
       jsonOut2({ proposals: [], message: "No monitor logs found." });
       return;
@@ -30300,7 +30903,7 @@ bridgeCommand.command("discover-skills").description(
       return;
     }
     const limit = Number(opts.limit);
-    const sorted = files.map((f) => ({ name: f, path: join23(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
+    const sorted = files.map((f) => ({ name: f, path: join24(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
     const sessionCommands = /* @__PURE__ */ new Map();
     for (const file of sorted) {
       const sessionId = file.name.replace(".jsonl", "");
@@ -30802,7 +31405,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
         return;
       }
     }
-    const outputPath = opts.image ?? opts.output ?? join23(tmpdir3(), `zam-capture-${randomBytes2(4).toString("hex")}.png`);
+    const outputPath = opts.image ?? opts.output ?? join24(tmpdir3(), `zam-capture-${randomBytes2(4).toString("hex")}.png`);
     const captureResult = isProvided ? { method: "provided", target: null } : captureScreenshot(outputPath, opts.hwnd, opts.processName);
     if (!isProvided) {
       const post = decidePostCapture(policy, {
@@ -30830,7 +31433,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
         return;
       }
     }
-    const imageBytes = readFileSync17(outputPath);
+    const imageBytes = readFileSync18(outputPath);
     const base64 = imageBytes.toString("base64");
     jsonOut2({
       sessionId: opts.session ?? null,
@@ -30857,11 +31460,11 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     return;
   }
   const sessionId = opts.session;
-  const statePath = join23(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const statePath = join24(tmpdir3(), `zam-recording-${sessionId}.json`);
   const defaultExt = platform === "win32" ? ".mkv" : ".mov";
-  const outputPath = opts.output ?? join23(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
-  const { existsSync: existsSync30, writeFileSync: writeFileSync17, openSync, closeSync } = await import("fs");
-  if (existsSync30(statePath)) {
+  const outputPath = opts.output ?? join24(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
+  const { existsSync: existsSync31, writeFileSync: writeFileSync18, openSync, closeSync } = await import("fs");
+  if (existsSync31(statePath)) {
     jsonOut2({
       sessionId,
       started: false,
@@ -30869,7 +31472,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     });
     return;
   }
-  const logPath = join23(tmpdir3(), `zam-recording-${sessionId}.log`);
+  const logPath = join24(tmpdir3(), `zam-recording-${sessionId}.log`);
   let logFd;
   try {
     logFd = openSync(logPath, "w");
@@ -30915,7 +31518,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
   }
   child.unref();
   if (child.pid) {
-    writeFileSync17(
+    writeFileSync18(
       statePath,
       JSON.stringify({
         pid: child.pid,
@@ -30951,9 +31554,9 @@ bridgeCommand.command("stop-recording").description(
     return;
   }
   const sessionId = opts.session;
-  const statePath = join23(tmpdir3(), `zam-recording-${sessionId}.json`);
-  const { existsSync: existsSync30, readFileSync: readFileSync22, rmSync: rmSync4 } = await import("fs");
-  if (!existsSync30(statePath)) {
+  const statePath = join24(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const { existsSync: existsSync31, readFileSync: readFileSync23, rmSync: rmSync4 } = await import("fs");
+  if (!existsSync31(statePath)) {
     jsonOut2({
       sessionId,
       stopped: false,
@@ -30961,7 +31564,7 @@ bridgeCommand.command("stop-recording").description(
     });
     return;
   }
-  const state = JSON.parse(readFileSync22(statePath, "utf8"));
+  const state = JSON.parse(readFileSync23(statePath, "utf8"));
   const { pid, outputPath } = state;
   try {
     process.kill(pid, "SIGINT");
@@ -30977,7 +31580,7 @@ bridgeCommand.command("stop-recording").description(
   };
   let attempts = 0;
   while (isProcessRunning(pid) && attempts < 20) {
-    await new Promise((resolve12) => setTimeout(resolve12, 250));
+    await new Promise((resolve13) => setTimeout(resolve13, 250));
     attempts++;
   }
   if (isProcessRunning(pid)) {
@@ -30990,7 +31593,7 @@ bridgeCommand.command("stop-recording").description(
     rmSync4(statePath, { force: true });
   } catch {
   }
-  if (!existsSync30(outputPath)) {
+  if (!existsSync31(outputPath)) {
     jsonOut2({
       sessionId,
       stopped: false,
@@ -31420,7 +32023,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") || existsSync21("C:\\Program Files\\flm\\flm.exe");
+  const flmInstalled = hasCommand("flm") || existsSync22("C:\\Program Files\\flm\\flm.exe");
   const ollamaInstalled = isOllamaInstalled();
   const runners = [
     { id: "flm", label: "FastFlowLM", installed: flmInstalled },
@@ -31794,7 +32397,12 @@ bridgeCommand.command("list-tokens").description(
 ).option("--domain <domain>", "Filter by exact domain").option(
   "--domain-prefix <prefix>",
   "Filter by domain prefix (e.g. company-team) \u2014 uses / separator for hierarchy"
-).option("--knowledge-context <context>", "Filter by knowledge context").action(async (opts) => {
+).option("--knowledge-context <context>", "Filter by knowledge context").option(
+  "--source-link-base <base>",
+  "Filter by source-link base (exact or '<base>#<anchor>', as written by OKF imports); repeatable",
+  (value, previous) => [...previous, value],
+  []
+).action(async (opts) => {
   await withDb2(async (db) => {
     const userId = opts.user ? await resolveUser(opts, db, { json: true }) : void 0;
     const listOpts = {};
@@ -31802,6 +32410,8 @@ bridgeCommand.command("list-tokens").description(
     if (opts.domainPrefix) listOpts.domainPrefix = opts.domainPrefix;
     if (opts.knowledgeContext)
       listOpts.knowledgeContext = opts.knowledgeContext;
+    if (opts.sourceLinkBase.length)
+      listOpts.sourceLinkBases = opts.sourceLinkBase;
     const tokens = await listTokens(
       db,
       Object.keys(listOpts).length ? listOpts : void 0
@@ -34645,26 +35255,26 @@ var doctorCommand = new Command5("doctor").description(
 // src/cli/commands/git-sync.ts
 init_kernel();
 import { execSync as execSync5 } from "child_process";
-import { chmodSync as chmodSync3, existsSync as existsSync22, writeFileSync as writeFileSync13 } from "fs";
-import { join as join24 } from "path";
+import { chmodSync as chmodSync3, existsSync as existsSync23, writeFileSync as writeFileSync14 } from "fs";
+import { join as join25 } from "path";
 import { Command as Command6 } from "commander";
 function installHook2() {
-  const gitDir = join24(process.cwd(), ".git");
-  if (!existsSync22(gitDir)) {
+  const gitDir = join25(process.cwd(), ".git");
+  if (!existsSync23(gitDir)) {
     console.error(
       "Error: Current directory is not the root of a Git repository."
     );
     process.exit(1);
   }
-  const hooksDir = join24(gitDir, "hooks");
-  const hookPath = join24(hooksDir, "post-commit");
+  const hooksDir = join25(gitDir, "hooks");
+  const hookPath = join25(hooksDir, "post-commit");
   const hookContent = `#!/bin/sh
 # ZAM Spaced Repetition Auto-Stale Hook
 # Triggered automatically on git commits to decay modified concept cards.
 zam git-sync --commit HEAD --quiet
 `;
   try {
-    writeFileSync13(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
+    writeFileSync14(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
     try {
       chmodSync3(hookPath, "755");
     } catch (_e) {
@@ -34767,8 +35377,8 @@ ZAM Auto-Stale Complete: Scanned ${changedFiles.length} file(s).`
 
 // src/cli/commands/goal.ts
 init_kernel();
-import { existsSync as existsSync23, mkdirSync as mkdirSync16 } from "fs";
-import { resolve as resolve7 } from "path";
+import { existsSync as existsSync24, mkdirSync as mkdirSync17 } from "fs";
+import { resolve as resolve8 } from "path";
 import { input as input2 } from "@inquirer/prompts";
 import { Command as Command7 } from "commander";
 async function resolveGoalsDir() {
@@ -34781,7 +35391,7 @@ async function resolveGoalsDir() {
   } finally {
     await db?.close();
   }
-  return goalsDir ? resolve7(goalsDir) : resolve7("goals");
+  return goalsDir ? resolve8(goalsDir) : resolve8("goals");
 }
 var goalCommand = new Command7("goal").description(
   "Manage learning goals (markdown files)"
@@ -34791,7 +35401,7 @@ goalCommand.command("list").description("List all goals").option(
   "Filter by status (active, completed, paused, abandoned)"
 ).option("--tree", "Show goals as a tree with parent/child relationships").option("--json", "Output as JSON").action(async (opts) => {
   const goalsDir = await resolveGoalsDir();
-  if (!existsSync23(goalsDir)) {
+  if (!existsSync24(goalsDir)) {
     console.error(`Goals directory not found: ${goalsDir}`);
     console.error(
       "Set it with: zam settings set personal.goals_dir /path/to/goals"
@@ -34892,8 +35502,8 @@ ${"\u2500".repeat(50)}`);
 });
 goalCommand.command("create").description("Create a new goal").option("--slug <slug>", "Goal slug (used as filename)").option("--title <title>", "Goal title").option("--parent <slug>", "Parent goal slug").option("--description <text>", "Goal description").option("--json", "Output as JSON").action(async (opts) => {
   const goalsDir = await resolveGoalsDir();
-  if (!existsSync23(goalsDir)) {
-    mkdirSync16(goalsDir, { recursive: true });
+  if (!existsSync24(goalsDir)) {
+    mkdirSync17(goalsDir, { recursive: true });
   }
   let slug = opts.slug;
   let title = opts.title;
@@ -34953,9 +35563,9 @@ goalCommand.command("status <slug> <status>").description("Update a goal's statu
 
 // src/cli/commands/init.ts
 init_kernel();
-import { existsSync as existsSync24, mkdirSync as mkdirSync17, writeFileSync as writeFileSync14 } from "fs";
+import { existsSync as existsSync25, mkdirSync as mkdirSync18, writeFileSync as writeFileSync15 } from "fs";
 import { homedir as homedir15 } from "os";
-import { join as join25, resolve as resolve8 } from "path";
+import { join as join26, resolve as resolve9 } from "path";
 import { confirm, input as input3 } from "@inquirer/prompts";
 import { Command as Command8 } from "commander";
 var HOME2 = homedir15();
@@ -34963,12 +35573,12 @@ function printLine(char = "\u2550", len = 60, color = "\x1B[36m") {
   console.log(`${color}${char.repeat(len)}\x1B[0m`);
 }
 function bootstrapSandboxWorkspace(workspaceDir) {
-  mkdirSync17(join25(workspaceDir, "beliefs"), { recursive: true });
-  mkdirSync17(join25(workspaceDir, "goals"), { recursive: true });
-  mkdirSync17(join25(workspaceDir, "skills"), { recursive: true });
-  const worldviewFile = join25(workspaceDir, "beliefs", "worldview.md");
-  if (!existsSync24(worldviewFile)) {
-    writeFileSync14(
+  mkdirSync18(join26(workspaceDir, "beliefs"), { recursive: true });
+  mkdirSync18(join26(workspaceDir, "goals"), { recursive: true });
+  mkdirSync18(join26(workspaceDir, "skills"), { recursive: true });
+  const worldviewFile = join26(workspaceDir, "beliefs", "worldview.md");
+  if (!existsSync25(worldviewFile)) {
+    writeFileSync15(
       worldviewFile,
       `# Personal Worldview
 
@@ -34980,9 +35590,9 @@ Here, I declare the core concepts and principles I want to master.
       "utf8"
     );
   }
-  const goalsFile = join25(workspaceDir, "goals", "goals.md");
-  if (!existsSync24(goalsFile)) {
-    writeFileSync14(
+  const goalsFile = join26(workspaceDir, "goals", "goals.md");
+  if (!existsSync25(goalsFile)) {
+    writeFileSync15(
       goalsFile,
       `# Personal Goals
 
@@ -35004,8 +35614,8 @@ var initCommand = new Command8("init").description("Launch the guided interactiv
   );
   printLine();
   console.log("\n\x1B[1m[1/5] Setting up Local Workspace Sandbox\x1B[0m");
-  const defaultWorkspace = join25(HOME2, "Documents", "zam");
-  const workspacePath = resolve8(
+  const defaultWorkspace = join26(HOME2, "Documents", "zam");
+  const workspacePath = resolve9(
     await input3({
       message: "Choose your ZAM workspace directory:",
       default: defaultWorkspace
@@ -36206,7 +36816,7 @@ observerCommand.command("revoke <process>").description("Remove a process from o
 
 // src/cli/commands/profile.ts
 init_kernel();
-import { dirname as dirname10, resolve as resolve9 } from "path";
+import { dirname as dirname11, resolve as resolve10 } from "path";
 import { Command as Command13 } from "commander";
 var C2 = {
   reset: "\x1B[0m",
@@ -36234,7 +36844,7 @@ var profileCommand = new Command13("profile").description("Show or change this m
     if (opts.mode) setInstallMode(opts.mode);
     db = await openDatabaseWithSync({ initialize: true });
     if (opts.dir) {
-      await activateWorkspacePath(db, resolve9(opts.dir), {
+      await activateWorkspacePath(db, resolve10(opts.dir), {
         kind: "personal",
         label: "Personal"
       });
@@ -36247,7 +36857,7 @@ var profileCommand = new Command13("profile").description("Show or change this m
       mode: getInstallMode(),
       personalDir,
       syncProvider: detectSyncProvider(personalDir),
-      dataDir: dirname10(dbPath),
+      dataDir: dirname11(dbPath),
       dbPath
     };
     if (opts.json) {
@@ -36636,7 +37246,7 @@ ${"\u2550".repeat(50)}`);
 
 // src/cli/commands/session.ts
 init_kernel();
-import { readFileSync as readFileSync18 } from "fs";
+import { readFileSync as readFileSync19 } from "fs";
 import { input as input6, select as select2 } from "@inquirer/prompts";
 import { Command as Command16 } from "commander";
 var sessionCommand = new Command16("session").description(
@@ -36827,7 +37437,7 @@ function loadPatternFile(path) {
   if (!path) return [];
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync18(path, "utf-8"));
+    parsed = JSON.parse(readFileSync19(path, "utf-8"));
   } catch (err) {
     throw new Error(
       `Cannot read synthesis patterns from ${path}: ${err.message}`
@@ -37018,7 +37628,7 @@ sessionCommand.command("end").description("End a session and show summary").requ
 
 // src/cli/commands/settings.ts
 init_kernel();
-import { existsSync as existsSync25 } from "fs";
+import { existsSync as existsSync26 } from "fs";
 import { Command as Command17 } from "commander";
 var settingsCommand = new Command17("settings").description(
   "Manage user settings"
@@ -37187,7 +37797,7 @@ settingsCommand.command("repos").description("Show or set Personal, Team, and Or
     console.log("\nValidation:");
     for (const [name, path] of Object.entries(paths)) {
       if (path) {
-        const exists = existsSync25(path);
+        const exists = existsSync26(path);
         console.log(
           `  ${name.padEnd(9)}: ${exists ? "\x1B[32m\u2713 Valid folder\x1B[0m" : "\x1B[31m\u2717 Directory does not exist\x1B[0m"}`
         );
@@ -37200,7 +37810,7 @@ settingsCommand.command("repos").description("Show or set Personal, Team, and Or
 
 // src/cli/commands/setup.ts
 init_kernel();
-import { resolve as resolve10 } from "path";
+import { resolve as resolve11 } from "path";
 import { Command as Command18 } from "commander";
 function formatDatabaseInitTarget(target) {
   switch (target.kind) {
@@ -37300,7 +37910,7 @@ var setupCommand = new Command18("setup").description(
       console.error(`Error: ${err.message}`);
       process.exit(1);
     }
-    const target = resolve10(opts.target ?? process.cwd());
+    const target = resolve11(opts.target ?? process.cwd());
     const updateExistingInstructions = Boolean(opts.target) || opts.force;
     console.log(
       `Setting up ZAM in ${target}${opts.dryRun ? " (dry run)" : ""}
@@ -37425,8 +38035,8 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
 
 // src/cli/commands/snapshot.ts
 init_kernel();
-import { existsSync as existsSync26, mkdirSync as mkdirSync18, readFileSync as readFileSync19, writeFileSync as writeFileSync15 } from "fs";
-import { dirname as dirname11, join as join26 } from "path";
+import { existsSync as existsSync27, mkdirSync as mkdirSync19, readFileSync as readFileSync20, writeFileSync as writeFileSync16 } from "fs";
+import { dirname as dirname12, join as join27 } from "path";
 import { Command as Command20 } from "commander";
 function defaultOutName() {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
@@ -37455,12 +38065,12 @@ var exportCmd = new Command20("export").description("Write a portable SQL-text s
       process.stdout.write(snapshot);
       return;
     }
-    const out = opts.out ?? join26(personalDir, "snapshots", defaultOutName());
-    const dir = dirname11(out);
-    if (dir && dir !== "." && !existsSync26(dir)) {
-      mkdirSync18(dir, { recursive: true });
+    const out = opts.out ?? join27(personalDir, "snapshots", defaultOutName());
+    const dir = dirname12(out);
+    if (dir && dir !== "." && !existsSync27(dir)) {
+      mkdirSync19(dir, { recursive: true });
     }
-    writeFileSync15(out, snapshot, "utf-8");
+    writeFileSync16(out, snapshot, "utf-8");
     console.log(`Snapshot written: ${out}`);
     console.log(
       `  ${total} row(s)${nonEmpty.length ? ` \u2014 ${nonEmpty.join(", ")}` : ""}`
@@ -37474,11 +38084,11 @@ var exportCmd = new Command20("export").description("Write a portable SQL-text s
 var importCmd = new Command20("import").description("Restore a snapshot into the database").argument("<file>", "Snapshot file to restore").option("--force", "Overwrite a non-empty database", false).action(async (file, opts) => {
   let db;
   try {
-    if (!existsSync26(file)) {
+    if (!existsSync27(file)) {
       console.error(`Error: Snapshot file not found: ${file}`);
       process.exit(1);
     }
-    const snapshot = readFileSync19(file, "utf-8");
+    const snapshot = readFileSync20(file, "utf-8");
     db = await openDatabaseWithSync({ initialize: true });
     const result = await importSnapshot(db, snapshot, { force: opts.force });
     await db.close();
@@ -37496,11 +38106,11 @@ var importCmd = new Command20("import").description("Restore a snapshot into the
 });
 var verifyCmd = new Command20("verify").description("Check a snapshot's manifest and checksum without importing").argument("<file>", "Snapshot file to verify").action((file) => {
   try {
-    if (!existsSync26(file)) {
+    if (!existsSync27(file)) {
       console.error(`Error: Snapshot file not found: ${file}`);
       process.exit(1);
     }
-    const manifest = verifySnapshot(readFileSync19(file, "utf-8"));
+    const manifest = verifySnapshot(readFileSync20(file, "utf-8"));
     const { total, nonEmpty } = summarize(manifest.tables);
     console.log(`Valid snapshot (format v${manifest.version})`);
     console.log(`  created: ${manifest.createdAt}`);
@@ -38049,10 +38659,10 @@ tokenCommand.command("reembed").description("Backfill or refresh semantic-search
 // src/cli/commands/ui.ts
 init_kernel();
 import { spawn as spawn3, spawnSync } from "child_process";
-import { existsSync as existsSync27 } from "fs";
+import { existsSync as existsSync28 } from "fs";
 import { homedir as homedir16 } from "os";
-import { dirname as dirname12, join as join27 } from "path";
-import { fileURLToPath as fileURLToPath6 } from "url";
+import { dirname as dirname13, join as join28 } from "path";
+import { fileURLToPath as fileURLToPath7 } from "url";
 import { Command as Command23 } from "commander";
 var C3 = {
   reset: "\x1B[0m",
@@ -38063,14 +38673,14 @@ var C3 = {
   dim: "\x1B[2m"
 };
 function findDesktopDir() {
-  const starts = [process.cwd(), dirname12(fileURLToPath6(import.meta.url))];
+  const starts = [process.cwd(), dirname13(fileURLToPath7(import.meta.url))];
   for (const start of starts) {
     let dir = start;
     for (let i = 0; i < 10; i++) {
-      if (existsSync27(join27(dir, "desktop", "src-tauri", "tauri.conf.json"))) {
-        return join27(dir, "desktop");
+      if (existsSync28(join28(dir, "desktop", "src-tauri", "tauri.conf.json"))) {
+        return join28(dir, "desktop");
       }
-      const parent = dirname12(dir);
+      const parent = dirname13(dir);
       if (parent === dir) break;
       dir = parent;
     }
@@ -38078,30 +38688,30 @@ function findDesktopDir() {
   return null;
 }
 function findBuiltApp(desktopDir) {
-  const releaseDir = join27(desktopDir, "src-tauri", "target", "release");
+  const releaseDir = join28(desktopDir, "src-tauri", "target", "release");
   if (process.platform === "win32") {
     for (const name of ["ZAM.exe", "zam.exe", "zam-desktop.exe"]) {
-      const p = join27(releaseDir, name);
-      if (existsSync27(p)) return p;
+      const p = join28(releaseDir, name);
+      if (existsSync28(p)) return p;
     }
   } else if (process.platform === "darwin") {
-    const app = join27(releaseDir, "bundle", "macos", "ZAM.app");
-    if (existsSync27(app)) return app;
+    const app = join28(releaseDir, "bundle", "macos", "ZAM.app");
+    if (existsSync28(app)) return app;
   } else {
     for (const name of ["zam", "ZAM", "zam-desktop"]) {
-      const p = join27(releaseDir, name);
-      if (existsSync27(p)) return p;
+      const p = join28(releaseDir, name);
+      if (existsSync28(p)) return p;
     }
   }
   return null;
 }
 function findInstalledApp() {
   const candidates = process.platform === "win32" ? [
-    process.env.LOCALAPPDATA && join27(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
-    process.env.ProgramFiles && join27(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
-    process.env["ProgramFiles(x86)"] && join27(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
-  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join27(homedir16(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
-  return candidates.find((candidate) => candidate && existsSync27(candidate)) || null;
+    process.env.LOCALAPPDATA && join28(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
+    process.env.ProgramFiles && join28(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
+    process.env["ProgramFiles(x86)"] && join28(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
+  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join28(homedir16(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
+  return candidates.find((candidate) => candidate && existsSync28(candidate)) || null;
 }
 function runNpm(args, opts) {
   const res = spawnSync("npm", args, {
@@ -38112,7 +38722,7 @@ function runNpm(args, opts) {
   return res.status ?? 1;
 }
 function ensureDesktopDeps(desktopDir) {
-  if (existsSync27(join27(desktopDir, "node_modules"))) return true;
+  if (existsSync28(join28(desktopDir, "node_modules"))) return true;
   console.log(
     `${C3.cyan}Installing desktop dependencies (one-time)...${C3.reset}`
   );
@@ -38138,13 +38748,13 @@ function requireRust() {
 function hasMsvcBuildTools() {
   if (process.platform !== "win32") return true;
   const pf86 = process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)";
-  const vswhere = join27(
+  const vswhere = join28(
     pf86,
     "Microsoft Visual Studio",
     "Installer",
     "vswhere.exe"
   );
-  if (!existsSync27(vswhere)) return false;
+  if (!existsSync28(vswhere)) return false;
   const res = spawnSync(
     vswhere,
     [
@@ -38176,7 +38786,7 @@ function requireMsvcOnWindows() {
   return false;
 }
 function warnIfCliMissing(repoRoot) {
-  if (!existsSync27(join27(repoRoot, "dist", "cli", "index.js"))) {
+  if (!existsSync28(join28(repoRoot, "dist", "cli", "index.js"))) {
     console.warn(
       `${C3.yellow}\u26A0 CLI build not found (dist/cli/index.js). The GUI bridge needs it \u2014 run 'npm run build' at the repo root.${C3.reset}`
     );
@@ -38249,7 +38859,7 @@ var uiCommand = new Command23("ui").description("Launch the ZAM Desktop GUI (Act
     );
     process.exit(1);
   }
-  const repoRoot = dirname12(desktopDir);
+  const repoRoot = dirname13(desktopDir);
   if (opts.build) {
     if (!requireRust()) process.exit(1);
     if (!requireMsvcOnWindows()) process.exit(1);
@@ -38260,7 +38870,7 @@ var uiCommand = new Command23("ui").description("Launch the ZAM Desktop GUI (Act
     );
     const code = runNpm(["run", "tauri", "build"], { cwd: desktopDir });
     if (code === 0) {
-      const bundle = join27(
+      const bundle = join28(
         desktopDir,
         "src-tauri",
         "target",
@@ -38300,7 +38910,7 @@ ${C3.green}\u2713 Done. Installer is in:${C3.reset}
       );
       process.exit(1);
     }
-    createShortcuts(shortcutTarget, dirname12(shortcutTarget));
+    createShortcuts(shortcutTarget, dirname13(shortcutTarget));
     return;
   }
   if (builtApp) {
@@ -38338,9 +38948,9 @@ ${C3.dim}After that, 'zam ui' launches it directly.${C3.reset}`
 // src/cli/commands/update.ts
 init_kernel();
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync28, readFileSync as readFileSync20, realpathSync as realpathSync2 } from "fs";
-import { dirname as dirname13, join as join28 } from "path";
-import { fileURLToPath as fileURLToPath7 } from "url";
+import { existsSync as existsSync29, readFileSync as readFileSync21, realpathSync as realpathSync3 } from "fs";
+import { dirname as dirname14, join as join29 } from "path";
+import { fileURLToPath as fileURLToPath8 } from "url";
 import { confirm as confirm3 } from "@inquirer/prompts";
 import { Command as Command24 } from "commander";
 var CHANNELS = [
@@ -38361,7 +38971,7 @@ var C4 = {
 function versionAt(dir) {
   try {
     const pkg2 = JSON.parse(
-      readFileSync20(join28(dir, "package.json"), "utf-8")
+      readFileSync21(join29(dir, "package.json"), "utf-8")
     );
     return pkg2.version ?? "unknown";
   } catch {
@@ -38419,14 +39029,14 @@ var checkCmd = new Command24("check").description("Check whether a newer ZAM has
   }
 );
 function findSourceRepo() {
-  let dir = realpathSync2(dirname13(fileURLToPath7(import.meta.url)));
-  let parent = dirname13(dir);
+  let dir = realpathSync3(dirname14(fileURLToPath8(import.meta.url)));
+  let parent = dirname14(dir);
   while (parent !== dir) {
-    if (existsSync28(join28(dir, ".git"))) return dir;
+    if (existsSync29(join29(dir, ".git"))) return dir;
     dir = parent;
-    parent = dirname13(dir);
+    parent = dirname14(dir);
   }
-  return existsSync28(join28(dir, ".git")) ? dir : null;
+  return existsSync29(join29(dir, ".git")) ? dir : null;
 }
 function runGit(cwd, args, capture) {
   const res = spawnSync2("git", args, {
@@ -38447,7 +39057,7 @@ function runNpm2(args, cwd) {
 function smokeTestBuild(src) {
   const res = spawnSync2(
     process.execPath,
-    [join28(src, "dist", "cli", "index.js"), "--version"],
+    [join29(src, "dist", "cli", "index.js"), "--version"],
     {
       cwd: src,
       encoding: "utf8",
@@ -38527,7 +39137,7 @@ Fix it manually in ${src} (try \`npm ci && npm run build\`, and check your Node
   console.log(`${C4.dim}\u2192 zam setup --force${C4.reset}`);
   const setup = spawnSync2(
     process.execPath,
-    [join28(src, "dist", "cli", "index.js"), "setup", "--force"],
+    [join29(src, "dist", "cli", "index.js"), "setup", "--force"],
     { cwd: process.cwd(), stdio: "inherit" }
   );
   if (setup.status !== 0) {
@@ -38640,9 +39250,9 @@ var whoamiCommand = new Command25("whoami").description("Show or set the default
 // src/cli/commands/workspace.ts
 init_kernel();
 import { execFileSync as execFileSync6 } from "child_process";
-import { existsSync as existsSync29, writeFileSync as writeFileSync16 } from "fs";
+import { existsSync as existsSync30, writeFileSync as writeFileSync17 } from "fs";
 import { homedir as homedir17 } from "os";
-import { join as join29, resolve as resolve11 } from "path";
+import { join as join30, resolve as resolve12 } from "path";
 import { confirm as confirm4, input as input7 } from "@inquirer/prompts";
 import { Command as Command26 } from "commander";
 function runGit2(cwd, args) {
@@ -38726,7 +39336,7 @@ workspaceCommand.command("list").description("List configured ZAM workspaces").o
   const workspaces = getConfiguredWorkspaces();
   const agents = parseSetupAgents();
   const linkHealth = Object.fromEntries(
-    workspaces.filter((workspace) => existsSync29(workspace.path)).map((workspace) => [
+    workspaces.filter((workspace) => existsSync30(workspace.path)).map((workspace) => [
       workspace.id,
       summarizeSkillLinkHealth(inspectSkillLinks(workspace.path, agents))
     ])
@@ -38768,8 +39378,8 @@ workspaceCommand.command("add <id>").description("Register an existing directory
   `Source-control provider (${WORKSPACE_SOURCE_CONTROLS.join(" | ")})`
 ).option("--scopes <list>", "Comma-separated knowledge scopes").option("--default-agent <id>", "Default agent harness for this workspace").action((id, opts) => {
   try {
-    const path = resolve11(String(opts.path));
-    if (!existsSync29(path)) {
+    const path = resolve12(String(opts.path));
+    if (!existsSync30(path)) {
       console.error(`Workspace path does not exist: ${path}`);
       process.exit(1);
     }
@@ -38863,7 +39473,7 @@ workspaceCommand.command("publish").description("Publish your local workspace sa
     );
     process.exit(1);
   }
-  if (!existsSync29(workspaceDir)) {
+  if (!existsSync30(workspaceDir)) {
     console.error(
       `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
     );
@@ -38877,15 +39487,15 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
     );
     process.exit(1);
   }
-  const gitignorePath = join29(workspaceDir, ".gitignore");
-  if (!existsSync29(gitignorePath)) {
-    writeFileSync16(
+  const gitignorePath = join30(workspaceDir, ".gitignore");
+  if (!existsSync30(gitignorePath)) {
+    writeFileSync17(
       gitignorePath,
       "node_modules/\n.agent/\n.agents/\n.claude/\n.gemini/\n.goose/\n*.log\n",
       "utf8"
     );
   }
-  const hasGitRepo = existsSync29(join29(workspaceDir, ".git"));
+  const hasGitRepo = existsSync30(join30(workspaceDir, ".git"));
   if (!hasGitRepo) {
     console.log("Initializing local Git repository...");
     runGit2(workspaceDir, ["init", "-b", "main"]);
@@ -38972,7 +39582,7 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
   }
 });
 workspaceCommand.command("data-dir").description("Print the ZAM data directory (database, credentials, config)").option("--json", "Output as JSON").action((opts) => {
-  const dir = join29(homedir17(), ".zam");
+  const dir = join30(homedir17(), ".zam");
   console.log(opts.json ? JSON.stringify({ dataDir: dir }) : dir);
 });
 workspaceCommand.command("backup").description("Back up the local ZAM database into your workspace").option(
@@ -39013,9 +39623,9 @@ workspaceCommand.command("backup").description("Back up the local ZAM database i
 });
 
 // src/cli/app.ts
-var __dirname = dirname14(fileURLToPath8(import.meta.url));
+var __dirname = dirname15(fileURLToPath9(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync21(join30(__dirname, "..", "..", "package.json"), "utf-8")
+  readFileSync22(join31(__dirname, "..", "..", "package.json"), "utf-8")
 );
 var program = new Command27();
 program.name("zam").description(