zam-core 0.13.0 → 0.15.0

package/dist/cli/commands/mcp.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,
@@ -9165,21 +9240,41 @@ var init_bundle = __esm({
 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 existsSync21,
-  mkdirSync as mkdirSync16,
-  readdirSync as readdirSync3,
-  readFileSync as readFileSync18,
-  realpathSync as realpathSync2,
-  writeFileSync as writeFileSync13
+  existsSync as existsSync13,
+  mkdirSync as mkdirSync9,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync11,
+  realpathSync,
+  writeFileSync as writeFileSync6
 } from "fs";
-import { dirname as dirname11, isAbsolute as isAbsolute2, join as join24, relative, resolve as resolve7, sep } from "path";
+import { dirname as dirname6, isAbsolute, join as join13, relative, resolve as resolve4, sep } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+function resolveBundleDirFromRoots(rootUris, fallback) {
+  const dirs = [];
+  for (const uri of rootUris) {
+    if (!uri?.startsWith("file:")) continue;
+    try {
+      dirs.push(join13(fileURLToPath3(uri), DEFAULT_BUNDLE_DIR));
+    } catch {
+    }
+  }
+  return dirs.find((dir) => existsSync13(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}`);
@@ -9187,19 +9282,19 @@ function resolveArticlePath(dir, file) {
   if (isReservedFile(file)) {
     throw new Error(`refusing to address reserved file: ${file}`);
   }
-  return join24(resolve7(dir), file);
+  return join13(resolve4(dir), file);
 }
 function findRepoRoot(startDir) {
-  let dir = resolve7(startDir);
+  let dir = resolve4(startDir);
   for (; ; ) {
-    if (existsSync21(join24(dir, ".git"))) return dir;
-    const parent = dirname11(dir);
-    if (parent === dir) return resolve7(startDir, "..");
+    if (existsSync13(join13(dir, ".git"))) return dir;
+    const parent = dirname6(dir);
+    if (parent === dir) return resolve4(startDir, "..");
     dir = parent;
   }
 }
 function resolveCitationPath(bundleDir, target) {
-  if (isAbsolute2(target)) {
+  if (isAbsolute(target)) {
     throw new Error(
       `invalid citation target: absolute paths are not allowed (${target})`
     );
@@ -9210,26 +9305,26 @@ function resolveCitationPath(bundleDir, target) {
     );
   }
   const root = findRepoRoot(bundleDir);
-  const resolved = resolve7(bundleDir, target);
+  const resolved = resolve4(bundleDir, target);
   assertContained(root, resolved, target);
-  if (existsSync21(resolved)) {
-    assertContained(realpathSync2(root), realpathSync2(resolved), target);
+  if (existsSync13(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)) {
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
     throw new Error(
       `invalid citation target: resolves outside the repository root (${target})`
     );
   }
 }
 function loadBundle(dir) {
-  const root = resolve7(dir);
+  const root = resolve4(dir);
   let entries;
   try {
-    entries = readdirSync3(root).filter(
+    entries = readdirSync2(root).filter(
       (name) => name.endsWith(".md") && !isReservedFile(name)
     );
   } catch {
@@ -9237,7 +9332,7 @@ function loadBundle(dir) {
   }
   const articles = entries.sort().map((file) => ({
     file,
-    markdown: readFileSync18(join24(root, file), "utf8")
+    markdown: readFileSync11(join13(root, file), "utf8")
   }));
   const problems = articles.flatMap(
     ({ file, markdown }) => validateArticle(file, markdown).problems
@@ -9259,25 +9354,25 @@ function upsertArticle(dir, file, markdown, today = (/* @__PURE__ */ new Date())
   const target = resolveArticlePath(dir, file);
   const validation = validateArticle(file, markdown);
   if (!validation.ok) return { validation };
-  const root = resolve7(dir);
-  mkdirSync16(root, { recursive: true });
+  const root = resolve4(dir);
+  mkdirSync9(root, { recursive: true });
   let created = true;
   try {
-    readFileSync18(target, "utf8");
+    readFileSync11(target, "utf8");
     created = false;
   } catch {
   }
-  writeFileSync13(target, markdown, "utf8");
+  writeFileSync6(target, markdown, "utf8");
   const bundle = loadBundle(root);
-  writeFileSync13(join24(root, "index.md"), renderIndex(bundle.catalog), "utf8");
+  writeFileSync6(join13(root, "index.md"), renderIndex(bundle.catalog), "utf8");
   let log = "";
   try {
-    log = readFileSync18(join24(root, "log.md"), "utf8");
+    log = readFileSync11(join13(root, "log.md"), "utf8");
   } catch {
   }
   const entry = bundle.catalog.find((e) => e.file === file);
-  writeFileSync13(
-    join24(root, "log.md"),
+  writeFileSync6(
+    join13(root, "log.md"),
     appendLog(
       log,
       today,
@@ -9296,11 +9391,68 @@ var init_io = __esm({
   }
 });
 
+// src/cli/okf-focus.ts
+var okf_focus_exports = {};
+__export(okf_focus_exports, {
+  getOkfFocusPath: () => getOkfFocusPath,
+  readOkfFocus: () => readOkfFocus,
+  writeOkfFocus: () => writeOkfFocus
+});
+import { mkdir as mkdir2, readFile as readFile2, rename as rename2, writeFile as writeFile2 } from "fs/promises";
+import { homedir as homedir16 } from "os";
+import { dirname as dirname12, join as join25 } from "path";
+function getOkfFocusPath(home = homedir16()) {
+  return join25(home, ".zam", "okf-focus.json");
+}
+function resolvePath(explicit) {
+  return explicit ?? process.env.ZAM_OKF_FOCUS_PATH ?? getOkfFocusPath();
+}
+async function writeOkfFocus(file, bundleDir, opts = {}) {
+  if (file.includes("/") || file.includes("\\") || !file.endsWith(".md")) {
+    throw new Error(`invalid article file name: ${file}`);
+  }
+  const path = resolvePath(opts.path);
+  const focus = {
+    version: 1,
+    file,
+    ...bundleDir ? { bundleDir } : {},
+    updatedAt: (opts.now?.() ?? /* @__PURE__ */ new Date()).toISOString()
+  };
+  await mkdir2(dirname12(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  await writeFile2(tmp, `${JSON.stringify(focus, null, 2)}
+`, "utf8");
+  await rename2(tmp, path);
+  return focus;
+}
+async function readOkfFocus(opts = {}) {
+  try {
+    const raw = await readFile2(resolvePath(opts.path), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== 1 || typeof parsed.file !== "string" || typeof parsed.updatedAt !== "string") {
+      return null;
+    }
+    return {
+      version: 1,
+      file: parsed.file,
+      ...typeof parsed.bundleDir === "string" ? { bundleDir: parsed.bundleDir } : {},
+      updatedAt: parsed.updatedAt
+    };
+  } catch {
+    return null;
+  }
+}
+var init_okf_focus = __esm({
+  "src/cli/okf-focus.ts"() {
+    "use strict";
+  }
+});
+
 // src/cli/commands/mcp.ts
 init_kernel();
 import { existsSync as existsSync22, readFileSync as readFileSync19 } from "fs";
-import { dirname as dirname12, join as join25 } from "path";
-import { fileURLToPath as fileURLToPath6 } from "url";
+import { basename as basename6, dirname as dirname13, join as join26 } from "path";
+import { fileURLToPath as fileURLToPath7 } from "url";
 import {
   RESOURCE_MIME_TYPE,
   registerAppResource,
@@ -9513,8 +9665,8 @@ function buildCompanionContext(input) {
 
 // src/cli/bridge-handlers.ts
 init_kernel();
-import { mkdirSync as mkdirSync9, writeFileSync as writeFileSync6 } from "fs";
-import { join as join13 } from "path";
+import { mkdirSync as mkdirSync10, writeFileSync as writeFileSync7 } from "fs";
+import { join as join14 } from "path";
 
 // src/cli/knowledge-contexts.ts
 init_kernel();
@@ -10397,6 +10549,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 input of params.tokens) {
+    const slug = input.slug?.trim();
+    if (!slug || !input.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 (input.bloomLevel !== void 0 && (!Number.isInteger(input.bloomLevel) || input.bloomLevel < 1 || input.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: readFileSync20 } = await import("fs");
+  const bundleDir = params.bundleDir ?? DEFAULT_BUNDLE_DIR2;
+  const articlePath = resolveArticlePath2(bundleDir, params.file);
+  let markdown;
+  try {
+    markdown = readFileSync20(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 input of params.tokens) {
+      const mode = input.mode ?? "new";
+      const existing = await getTokenBySlug(tx, input.slug);
+      if (mode === "new") {
+        if (existing) {
+          throw new Error(
+            `Token '${input.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: input.slug,
+          title: input.title,
+          concept: input.concept,
+          domain: input.domain,
+          bloom_level: input.bloomLevel ?? 1,
+          source_link: sourceLinkFor(input.anchor),
+          question: input.question ?? null,
+          question_source: input.question ? "llm" : void 0
+        });
+        inImport.set(input.slug, token2);
+        created.push(input.slug);
+      } else {
+        if (!existing) {
+          throw new Error(
+            `Token '${input.slug}' does not exist \u2014 mode "${mode}" requires an existing token.`
+          );
+        }
+        const updates = {
+          concept: input.concept,
+          source_link: sourceLinkFor(input.anchor)
+        };
+        if (input.title !== void 0) updates.title = input.title;
+        if (input.domain !== void 0) updates.domain = input.domain;
+        if (input.bloomLevel !== void 0) {
+          updates.bloom_level = input.bloomLevel;
+        }
+        if (input.question !== void 0) {
+          updates.question = input.question;
+          updates.question_source = input.question ? "llm" : void 0;
+        }
+        const token2 = await updateToken(tx, input.slug, updates);
+        if (existing.maintenance_at) {
+          await clearTokenMaintenance(tx, input.slug);
+        }
+        if (mode === "replace") {
+          await resetCardsForToken(tx, token2.id);
+          replaced.push(input.slug);
+        } else {
+          updated.push(input.slug);
+        }
+        inImport.set(input.slug, token2);
+      }
+      const ctxNames = parseKnowledgeContextNames(input.knowledgeContexts);
+      const assigned = await resolveKnowledgeContexts(tx, ctxNames);
+      const token = inImport.get(input.slug);
+      if (token) {
+        for (const context of assigned) {
+          await assignTokenToContext(tx, token.id, context.id);
+        }
+      }
+    }
+    for (const input of params.tokens) {
+      const token = inImport.get(input.slug);
+      if (!token) continue;
+      const prereqSlugs = [
+        ...new Set(
+          (input.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 '${input.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()) {
@@ -10721,11 +11028,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 = join13(targetDir, "zam-backups");
-  mkdirSync9(backupDir, { recursive: true });
+  const backupDir = join14(targetDir, "zam-backups");
+  mkdirSync10(backupDir, { recursive: true });
   const stamp = manifest.createdAt.replace(/[:.]/g, "-");
-  const path = join13(backupDir, `zam-snapshot-${stamp}.sql`);
-  writeFileSync6(path, snapshot, "utf-8");
+  const path = join14(backupDir, `zam-snapshot-${stamp}.sql`);
+  writeFileSync7(path, snapshot, "utf-8");
   return {
     ok: true,
     path,
@@ -10750,27 +11057,27 @@ init_kernel();
 
 // src/cli/agent-connect.ts
 init_kernel();
-import { mkdirSync as mkdirSync12, writeFileSync as writeFileSync10 } from "fs";
+import { mkdirSync as mkdirSync13, writeFileSync as writeFileSync11 } from "fs";
 import { homedir as homedir12 } from "os";
-import { dirname as dirname8 } from "path";
+import { dirname as dirname9 } from "path";
 
 // src/cli/agent-harness.ts
 import { spawn as spawn2 } from "child_process";
-import { existsSync as existsSync14, readFileSync as readFileSync11 } from "fs";
+import { existsSync as existsSync15, readFileSync as readFileSync12 } from "fs";
 import { homedir as homedir9 } from "os";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 
 // src/cli/terminal-open.ts
 import { execFileSync as execFileSync2, execSync as execSync4 } from "child_process";
 import {
   accessSync,
   constants,
-  existsSync as existsSync13,
+  existsSync as existsSync14,
   unlinkSync as unlinkSync2,
-  writeFileSync as writeFileSync7
+  writeFileSync as writeFileSync8
 } from "fs";
 import { tmpdir } from "os";
-import { basename as basename3, delimiter, extname, isAbsolute, join as join14 } from "path";
+import { basename as basename3, delimiter, extname, isAbsolute as isAbsolute2, join as join15 } from "path";
 function isPowerShellShell(shell) {
   return shell === "pwsh" || shell === "powershell";
 }
@@ -10812,7 +11119,7 @@ function stripSurroundingQuotes(command) {
   return trimmed;
 }
 function executableExists(path) {
-  if (!existsSync13(path)) return false;
+  if (!existsSync14(path)) return false;
   if (process.platform === "win32") return true;
   try {
     accessSync(path, constants.X_OK);
@@ -10828,7 +11135,7 @@ function windowsExecutableNames(command) {
   return extensions.map((ext) => `${command}${ext}`);
 }
 function hasDirectoryPart(command) {
-  return isAbsolute(command) || command.includes("/") || command.includes("\\");
+  return isAbsolute2(command) || command.includes("/") || command.includes("\\");
 }
 function findExecutable(command) {
   const normalized = stripSurroundingQuotes(command);
@@ -10843,7 +11150,7 @@ function findExecutable(command) {
   const pathEntries = (process.env.PATH ?? "").split(delimiter).map((entry) => entry.trim()).filter(Boolean);
   for (const entry of pathEntries) {
     for (const name of windowsExecutableNames(normalized)) {
-      const candidate = join14(entry, name);
+      const candidate = join15(entry, name);
       if (executableExists(candidate)) matches.push(candidate);
     }
   }
@@ -10881,9 +11188,9 @@ end tell` : `tell application "Terminal"
   activate
   do script "${escaped}"
 end tell`;
-  const tmpFile = join14(tmpdir(), `zam-terminal-${label}.scpt`);
+  const tmpFile = join15(tmpdir(), `zam-terminal-${label}.scpt`);
   try {
-    writeFileSync7(tmpFile, appleScript);
+    writeFileSync8(tmpFile, appleScript);
     execSync4(`osascript ${JSON.stringify(tmpFile)}`, { stdio: "ignore" });
     if (!silent) {
       console.log(
@@ -10964,7 +11271,7 @@ function openTerminalWindow(opts) {
 // src/cli/agent-harness.ts
 var ANTIGRAVITY_IDE_CANDIDATE_PATHS = {
   darwin: [
-    join15(
+    join16(
       homedir9(),
       ".antigravity-ide",
       "antigravity-ide",
@@ -10985,7 +11292,7 @@ var AGENT_HARNESSES = [
     command: "cursor",
     candidatePaths: {
       win32: [
-        join15(homedir9(), "AppData", "Local", "Programs", "cursor", "Cursor.exe")
+        join16(homedir9(), "AppData", "Local", "Programs", "cursor", "Cursor.exe")
       ],
       darwin: ["/Applications/Cursor.app/Contents/MacOS/Cursor"]
     }
@@ -11010,7 +11317,7 @@ function getHarness(id) {
 }
 function resolveAntigravityIdeExecutable(deps = {}) {
   const find = deps.find ?? findExecutable;
-  const exists = deps.exists ?? existsSync14;
+  const exists = deps.exists ?? existsSync15;
   const platform = deps.platform ?? process.platform;
   const found = find("antigravity-ide");
   if (found) return found;
@@ -11018,7 +11325,7 @@ function resolveAntigravityIdeExecutable(deps = {}) {
 }
 function resolveHarnessExecutable(harness, overrideCommand, deps = {}) {
   const find = deps.find ?? findExecutable;
-  const exists = deps.exists ?? existsSync14;
+  const exists = deps.exists ?? existsSync15;
   const platform = deps.platform ?? process.platform;
   const found = find(overrideCommand || harness.command);
   if (found) return found;
@@ -11078,18 +11385,18 @@ function detectInstalledConnectHarnesses(options = {}) {
   const home = options.home ?? homedir9();
   const platform = options.platform ?? process.platform;
   const find = options.find ?? findExecutable;
-  const exists = options.exists ?? existsSync14;
+  const exists = options.exists ?? existsSync15;
   const detected = [];
   const hasCommandOrPath = (command, paths = []) => Boolean(find(command)) || paths.some((path) => exists(path));
   if (hasCommandOrPath("codex", [
-    join15(home, ".codex"),
-    ...platform === "darwin" ? ["/Applications/Codex.app"] : platform === "win32" ? [join15(home, "AppData", "Local", "Programs", "Codex")] : []
+    join16(home, ".codex"),
+    ...platform === "darwin" ? ["/Applications/Codex.app"] : platform === "win32" ? [join16(home, "AppData", "Local", "Programs", "Codex")] : []
   ])) {
     detected.push("codex");
   }
   const vscodePaths = platform === "darwin" ? [
     "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code",
-    join15(
+    join16(
       home,
       "Applications",
       "Visual Studio Code.app",
@@ -11100,7 +11407,7 @@ function detectInstalledConnectHarnesses(options = {}) {
       "code"
     )
   ] : platform === "win32" ? [
-    join15(
+    join16(
       home,
       "AppData",
       "Local",
@@ -11111,23 +11418,23 @@ function detectInstalledConnectHarnesses(options = {}) {
     )
   ] : ["/usr/bin/code", "/usr/local/bin/code", "/snap/bin/code"];
   if (hasCommandOrPath("code", vscodePaths)) detected.push("vscode");
-  const copilotHome = options.copilotHome ?? join15(home, ".copilot");
+  const copilotHome = options.copilotHome ?? join16(home, ".copilot");
   if (hasCommandOrPath("copilot", [
     copilotHome,
     ...platform === "darwin" ? ["/Applications/GitHub Copilot.app"] : []
   ])) {
     detected.push("copilot");
   }
-  if (hasCommandOrPath("opencode", [join15(home, ".config", "opencode")])) {
+  if (hasCommandOrPath("opencode", [join16(home, ".config", "opencode")])) {
     detected.push("opencode");
   }
-  if (hasCommandOrPath("goose", [join15(home, ".config", "goose")])) {
+  if (hasCommandOrPath("goose", [join16(home, ".config", "goose")])) {
     detected.push("goose");
   }
   if (hasCommandOrPath("antigravity", [
-    join15(home, ".gemini", "config"),
+    join16(home, ".gemini", "config"),
     ...platform === "darwin" ? [
-      join15(
+      join16(
         home,
         ".antigravity-ide",
         "antigravity-ide",
@@ -11140,7 +11447,7 @@ function detectInstalledConnectHarnesses(options = {}) {
   ]) || find("antigravity-ide")) {
     detected.push("antigravity");
   }
-  const claudeDesktopPath = platform === "darwin" ? "/Applications/Claude.app" : platform === "win32" ? exists(join15(home, "AppData", "Local", "AnthropicClaude")) ? join15(home, "AppData", "Local", "AnthropicClaude") : exists(join15(home, "AppData", "Local", "Claude")) ? join15(home, "AppData", "Local", "Claude") : join15(home, "AppData", "Roaming", "Claude") : join15(home, ".config", "Claude");
+  const claudeDesktopPath = platform === "darwin" ? "/Applications/Claude.app" : platform === "win32" ? exists(join16(home, "AppData", "Local", "AnthropicClaude")) ? join16(home, "AppData", "Local", "AnthropicClaude") : exists(join16(home, "AppData", "Local", "Claude")) ? join16(home, "AppData", "Local", "Claude") : join16(home, "AppData", "Roaming", "Claude") : join16(home, ".config", "Claude");
   if (exists(claudeDesktopPath)) detected.push("claude-desktop");
   return detected;
 }
@@ -11173,11 +11480,11 @@ function connectHarnessMcp(harnessId, opts) {
         return false;
       }
     }
-    return existsSync14(p);
+    return existsSync15(p);
   };
   const read = (p) => {
     if (opts.readFile) return opts.readFile(p);
-    return readFileSync11(p, "utf-8");
+    return readFileSync12(p, "utf-8");
   };
   let targetPath = "";
   let content = "";
@@ -11209,32 +11516,32 @@ function connectHarnessMcp(harnessId, opts) {
     return JSON.stringify(existing, null, 2);
   };
   if (harnessId === "claude-code") {
-    targetPath = join15(opts.cwd, ".mcp.json");
+    targetPath = join16(opts.cwd, ".mcp.json");
     hint = "Claude Code will prompt you to approve the 'zam' MCP server on next launch.";
     content = mergeMcpServersJson(targetPath);
   } else if (harnessId === "claude-desktop") {
     const platform = opts.platform ?? process.platform;
-    targetPath = platform === "win32" ? join15(
+    targetPath = platform === "win32" ? join16(
       opts.home,
       "AppData",
       "Roaming",
       "Claude",
       "claude_desktop_config.json"
-    ) : platform === "darwin" ? join15(
+    ) : platform === "darwin" ? join16(
       opts.home,
       "Library",
       "Application Support",
       "Claude",
       "claude_desktop_config.json"
-    ) : join15(opts.home, ".config", "Claude", "claude_desktop_config.json");
+    ) : join16(opts.home, ".config", "Claude", "claude_desktop_config.json");
     hint = "Restart Claude Desktop to load the 'zam' MCP server; MCP Apps panels render inline in the chat.";
     content = mergeMcpServersJson(targetPath);
   } else if (harnessId === "antigravity") {
-    targetPath = join15(opts.home, ".gemini", "config", "mcp_config.json");
+    targetPath = join16(opts.home, ".gemini", "config", "mcp_config.json");
     hint = "Shared config read by Antigravity CLI and IDE (2.0+); older IDE builds read ~/.gemini/antigravity/mcp_config.json instead. Refresh Installed MCP Servers; the first tool call may still require approval.";
     content = mergeMcpServersJson(targetPath);
   } else if (harnessId === "opencode") {
-    targetPath = join15(opts.home, ".config", "opencode", "opencode.json");
+    targetPath = join16(opts.home, ".config", "opencode", "opencode.json");
     hint = "OpenCode will load the enabled 'zam' MCP server on next launch.";
     let existing = {};
     if (exists(targetPath)) {
@@ -11262,7 +11569,7 @@ function connectHarnessMcp(harnessId, opts) {
     existing.mcp = servers;
     content = JSON.stringify(existing, null, 2);
   } else if (harnessId === "codex") {
-    targetPath = join15(opts.home, ".codex", "config.toml");
+    targetPath = join16(opts.home, ".codex", "config.toml");
     hint = "Codex will prompt for tool execution approvals or respect the TOML approval modes.";
     let existingStr = "";
     if (exists(targetPath)) {
@@ -11289,14 +11596,14 @@ ${block}` : block;
     }
   } else if (harnessId === "vscode") {
     const platform = opts.platform ?? process.platform;
-    targetPath = platform === "win32" ? join15(opts.home, "AppData", "Roaming", "Code", "User", "mcp.json") : platform === "darwin" ? join15(
+    targetPath = platform === "win32" ? join16(opts.home, "AppData", "Roaming", "Code", "User", "mcp.json") : platform === "darwin" ? join16(
       opts.home,
       "Library",
       "Application Support",
       "Code",
       "User",
       "mcp.json"
-    ) : join15(opts.home, ".config", "Code", "User", "mcp.json");
+    ) : join16(opts.home, ".config", "Code", "User", "mcp.json");
     hint = "Reload VS Code after setup. ZAM Companion stays separate from the Codex chat and can be moved to any panel or sidebar.";
     let existing = {};
     if (exists(targetPath)) {
@@ -11318,7 +11625,7 @@ ${block}` : block;
     if (!existing.inputs) existing.inputs = [];
     content = JSON.stringify(existing, null, 2);
   } else if (harnessId === "goose") {
-    targetPath = join15(opts.home, ".config", "goose", "config.yaml");
+    targetPath = join16(opts.home, ".config", "goose", "config.yaml");
     hint = "goose will load the 'zam' extension on next session start. Run 'goose configure' to manage extensions.";
     const isJs = opts.zamPath.endsWith(".js");
     const cmdStr = isJs ? process.execPath : opts.zamPath;
@@ -11357,8 +11664,8 @@ ${zamExtension}
 `;
     }
   } else if (harnessId === "copilot") {
-    targetPath = join15(
-      opts.copilotHome ?? join15(opts.home, ".copilot"),
+    targetPath = join16(
+      opts.copilotHome ?? join16(opts.home, ".copilot"),
       "mcp-config.json"
     );
     hint = "Restart GitHub Copilot or start a new session to load the 'zam' MCP server and its focused Recall, Graph, and Settings canvases.";
@@ -11400,15 +11707,15 @@ ${zamExtension}
 
 // src/cli/copilot-extension.ts
 import {
-  existsSync as existsSync15,
+  existsSync as existsSync16,
   lstatSync,
-  mkdirSync as mkdirSync10,
-  readFileSync as readFileSync12,
-  writeFileSync as writeFileSync8
+  mkdirSync as mkdirSync11,
+  readFileSync as readFileSync13,
+  writeFileSync as writeFileSync9
 } from "fs";
 import { homedir as homedir10 } from "os";
-import { dirname as dirname6, join as join16, resolve as resolve4 } from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
+import { dirname as dirname7, join as join17, resolve as resolve5 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
 var EXTENSION_NAME = "zam-mcp-apps";
 var EXTENSION_FILES = [
   "extension.mjs",
@@ -11417,18 +11724,18 @@ var EXTENSION_FILES = [
   "manifest.json"
 ];
 var packageRoot = [
-  fileURLToPath3(new URL("../..", import.meta.url)),
-  fileURLToPath3(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync15(join16(candidate, "package.json"))) ?? fileURLToPath3(new URL("../..", import.meta.url));
+  fileURLToPath4(new URL("../..", import.meta.url)),
+  fileURLToPath4(new URL("../../..", import.meta.url))
+].find((candidate) => existsSync16(join17(candidate, "package.json"))) ?? fileURLToPath4(new URL("../..", import.meta.url));
 function defaultCliEntry() {
-  return join16(dirname6(fileURLToPath3(import.meta.url)), "index.js");
+  return join17(dirname7(fileURLToPath4(import.meta.url)), "index.js");
 }
 function resolveCopilotHome(home = homedir10(), configuredHome = process.env.COPILOT_HOME) {
-  return configuredHome?.trim() ? resolve4(configuredHome) : join16(home, ".copilot");
+  return configuredHome?.trim() ? resolve5(configuredHome) : join17(home, ".copilot");
 }
 function resolveCopilotZamLaunch(zamPath, options = {}) {
   const cliEntry = options.cliEntry ?? defaultCliEntry();
-  if (existsSync15(cliEntry)) {
+  if (existsSync16(cliEntry)) {
     return {
       command: options.nodePath ?? process.execPath,
       args: [cliEntry, "mcp"]
@@ -11440,20 +11747,20 @@ function resolveCopilotZamLaunch(zamPath, options = {}) {
   };
 }
 function planCopilotExtensionInstall(options) {
-  const sourceDir = options.assetsDir ?? join16(packageRoot, "dist", "copilot-extension");
+  const sourceDir = options.assetsDir ?? join17(packageRoot, "dist", "copilot-extension");
   for (const file of EXTENSION_FILES) {
-    if (!existsSync15(join16(sourceDir, file))) {
+    if (!existsSync16(join17(sourceDir, file))) {
       throw new Error(
-        `Copilot MCP Apps asset is missing: ${join16(sourceDir, file)}. Run \`npm run build\` and retry.`
+        `Copilot MCP Apps asset is missing: ${join17(sourceDir, file)}. Run \`npm run build\` and retry.`
       );
     }
   }
   const manifest = JSON.parse(
-    readFileSync12(join16(sourceDir, "manifest.json"), "utf8")
+    readFileSync13(join17(sourceDir, "manifest.json"), "utf8")
   );
   if (manifest.name !== EXTENSION_NAME || typeof manifest.version !== "string" || !manifest.version) {
     throw new Error(
-      `Invalid Copilot MCP Apps manifest: ${join16(sourceDir, "manifest.json")}`
+      `Invalid Copilot MCP Apps manifest: ${join17(sourceDir, "manifest.json")}`
     );
   }
   const copilotHome = resolveCopilotHome(
@@ -11462,15 +11769,15 @@ function planCopilotExtensionInstall(options) {
   );
   return {
     sourceDir,
-    destinationDir: join16(copilotHome, "extensions", EXTENSION_NAME),
+    destinationDir: join17(copilotHome, "extensions", EXTENSION_NAME),
     launch: resolveCopilotZamLaunch(options.zamPath, options),
     files: EXTENSION_FILES
   };
 }
 function writeIfChanged(path, content) {
   const next = Buffer.isBuffer(content) ? content : Buffer.from(content);
-  if (existsSync15(path) && readFileSync12(path).equals(next)) return false;
-  writeFileSync8(path, next);
+  if (existsSync16(path) && readFileSync13(path).equals(next)) return false;
+  writeFileSync9(path, next);
   return true;
 }
 function installCopilotExtension(options) {
@@ -11478,18 +11785,18 @@ function installCopilotExtension(options) {
   if (options.dryRun) {
     return { ...plan, action: "planned", changedFiles: [] };
   }
-  const destinationExisted = existsSync15(plan.destinationDir);
+  const destinationExisted = existsSync16(plan.destinationDir);
   if (destinationExisted && lstatSync(plan.destinationDir).isSymbolicLink()) {
     throw new Error(
       `Refusing to replace symlinked Copilot extension directory: ${plan.destinationDir}`
     );
   }
-  mkdirSync10(plan.destinationDir, { recursive: true });
+  mkdirSync11(plan.destinationDir, { recursive: true });
   const changedFiles = [];
   for (const file of plan.files) {
-    const source = join16(plan.sourceDir, file);
-    const destination = join16(plan.destinationDir, file);
-    if (writeIfChanged(destination, readFileSync12(source))) {
+    const source = join17(plan.sourceDir, file);
+    const destination = join17(plan.destinationDir, file);
+    if (writeIfChanged(destination, readFileSync13(source))) {
       changedFiles.push(file);
     }
   }
@@ -11503,7 +11810,7 @@ function installCopilotExtension(options) {
     2
   )}
 `;
-  if (writeIfChanged(join16(plan.destinationDir, "launch.json"), launchContent)) {
+  if (writeIfChanged(join17(plan.destinationDir, "launch.json"), launchContent)) {
     changedFiles.push("launch.json");
   }
   return {
@@ -11515,24 +11822,24 @@ function installCopilotExtension(options) {
 
 // src/cli/vscode-extension.ts
 import { execFileSync as execFileSync3 } from "child_process";
-import { existsSync as existsSync16, mkdirSync as mkdirSync11, readFileSync as readFileSync13, writeFileSync as writeFileSync9 } from "fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync12, readFileSync as readFileSync14, writeFileSync as writeFileSync10 } from "fs";
 import { homedir as homedir11 } from "os";
-import { dirname as dirname7, join as join17 } from "path";
-import { fileURLToPath as fileURLToPath4 } from "url";
+import { dirname as dirname8, join as join18 } from "path";
+import { fileURLToPath as fileURLToPath5 } from "url";
 var packageRoot2 = [
-  fileURLToPath4(new URL("../..", import.meta.url)),
-  fileURLToPath4(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync16(join17(candidate, "package.json"))) ?? fileURLToPath4(new URL("../..", import.meta.url));
+  fileURLToPath5(new URL("../..", import.meta.url)),
+  fileURLToPath5(new URL("../../..", import.meta.url))
+].find((candidate) => existsSync17(join18(candidate, "package.json"))) ?? fileURLToPath5(new URL("../..", import.meta.url));
 function resolveVscodeExecutable(options = {}) {
   const home = options.home ?? homedir11();
   const platform = options.platform ?? process.platform;
   const find = options.find ?? findExecutable;
-  const exists = options.exists ?? existsSync16;
+  const exists = options.exists ?? existsSync17;
   const found = find("code");
   if (found) return found;
   const candidates = platform === "darwin" ? [
     "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code",
-    join17(
+    join18(
       home,
       "Applications",
       "Visual Studio Code.app",
@@ -11543,7 +11850,7 @@ function resolveVscodeExecutable(options = {}) {
       "code"
     )
   ] : platform === "win32" ? [
-    join17(
+    join18(
       home,
       "AppData",
       "Local",
@@ -11563,7 +11870,7 @@ function buildVscodeCliInvocation(command, args, platform = process.platform) {
 }
 function packageVersion() {
   const parsed = JSON.parse(
-    readFileSync13(join17(packageRoot2, "package.json"), "utf8")
+    readFileSync14(join18(packageRoot2, "package.json"), "utf8")
   );
   if (typeof parsed.version !== "string" || !parsed.version) {
     throw new Error("Cannot determine the ZAM package version");
@@ -11573,9 +11880,9 @@ function packageVersion() {
 function planVscodeExtensionInstall(options) {
   const home = options.home ?? homedir11();
   const version = options.version ?? packageVersion();
-  const assetsDir = options.assetsDir ?? join17(packageRoot2, "dist", "vscode-extension");
-  const vsixPath = join17(assetsDir, `ZAM_Companion_${version}.vsix`);
-  if (!existsSync16(vsixPath)) {
+  const assetsDir = options.assetsDir ?? join18(packageRoot2, "dist", "vscode-extension");
+  const vsixPath = join18(assetsDir, `ZAM_Companion_${version}.vsix`);
+  if (!existsSync17(vsixPath)) {
     throw new Error(
       `ZAM Companion VSIX asset is missing: ${vsixPath}. Run \`npm run build\` and retry.`
     );
@@ -11595,7 +11902,7 @@ function planVscodeExtensionInstall(options) {
     version,
     vsixPath,
     codePath,
-    launchConfigPath: join17(home, ".zam", "vscode-launch.json"),
+    launchConfigPath: join18(home, ".zam", "vscode-launch.json"),
     launch: { command: options.zamPath, args: ["mcp"] }
   };
 }
@@ -11631,8 +11938,8 @@ function installVscodeExtension(options) {
     2
   )}
 `;
-  const existed = existsSync16(plan.launchConfigPath);
-  const changed = !existed || readFileSync13(plan.launchConfigPath, "utf8") !== launchContent;
+  const existed = existsSync17(plan.launchConfigPath);
+  const changed = !existed || readFileSync14(plan.launchConfigPath, "utf8") !== launchContent;
   const run = options.run ?? ((command, args) => {
     const invocation = buildVscodeCliInvocation(command, args);
     execFileSync3(invocation.command, invocation.args, {
@@ -11654,8 +11961,8 @@ function installVscodeExtension(options) {
   }
   run(plan.codePath, ["--install-extension", plan.vsixPath, "--force"]);
   if (changed) {
-    mkdirSync11(dirname7(plan.launchConfigPath), { recursive: true });
-    writeFileSync9(plan.launchConfigPath, launchContent, "utf8");
+    mkdirSync12(dirname8(plan.launchConfigPath), { recursive: true });
+    writeFileSync10(plan.launchConfigPath, launchContent, "utf8");
   }
   return {
     ...plan,
@@ -11715,8 +12022,8 @@ function resolveDeps(deps) {
     detect: deps.detect ?? (() => detectInstalledConnectHarnesses({ home, copilotHome })),
     connectMcp: deps.connectMcp ?? connectHarnessMcp,
     writeConfig: deps.writeConfig ?? ((path, content) => {
-      mkdirSync12(dirname8(path), { recursive: true });
-      writeFileSync10(path, content, "utf-8");
+      mkdirSync13(dirname9(path), { recursive: true });
+      writeFileSync11(path, content, "utf-8");
     }),
     installCopilot: deps.installCopilot ?? installCopilotExtension,
     installVscode: deps.installVscode ?? installVscodeExtension,
@@ -11862,9 +12169,9 @@ function inspectConnectHarnesses(deps = {}) {
 init_kernel();
 import { execFileSync as execFileSync5 } from "child_process";
 import { randomBytes as randomBytes2 } from "crypto";
-import { existsSync as existsSync20, readdirSync as readdirSync2, readFileSync as readFileSync17, rmSync as rmSync3 } from "fs";
+import { existsSync as existsSync21, readdirSync as readdirSync3, readFileSync as readFileSync18, rmSync as rmSync3 } from "fs";
 import { homedir as homedir14, tmpdir as tmpdir3 } from "os";
-import { join as join22, resolve as resolve6 } from "path";
+import { join as join23, resolve as resolve7 } from "path";
 import { Command } from "commander";
 import { ulid as ulid10 } from "ulid";
 
@@ -11944,7 +12251,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) {
@@ -12011,16 +12318,16 @@ async function readImageOCR(db, imagePath) {
 import { execFileSync as execFileSync4 } from "child_process";
 import {
   chmodSync as chmodSync2,
-  existsSync as existsSync17,
-  mkdirSync as mkdirSync13,
-  readFileSync as readFileSync14,
-  writeFileSync as writeFileSync11
+  existsSync as existsSync18,
+  mkdirSync as mkdirSync14,
+  readFileSync as readFileSync15,
+  writeFileSync as writeFileSync12
 } from "fs";
 import { homedir as homedir13 } from "os";
-import { delimiter as delimiter2, join as join18, resolve as resolve5 } from "path";
+import { delimiter as delimiter2, join as join19, 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) {
@@ -12060,14 +12367,14 @@ function ensureWindowsUserPath(binDir) {
   return output.endsWith("updated");
 }
 function ensureUnixUserPath(home, platform) {
-  const profile = join18(home, platform === "darwin" ? ".zprofile" : ".profile");
-  const existing = existsSync17(profile) ? readFileSync14(profile, "utf8") : "";
+  const profile = join19(home, platform === "darwin" ? ".zprofile" : ".profile");
+  const existing = existsSync18(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 = {}) {
@@ -12075,10 +12382,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 = join18(home, ".zam", "bin");
-  const shimPath = join18(binDir, platform === "win32" ? "zam.cmd" : "zam");
+  const nodePath = resolve6(options.nodePath ?? process.execPath);
+  const cliPath = resolve6(options.cliPath ?? process.argv[1] ?? "");
+  const binDir = join19(home, ".zam", "bin");
+  const shimPath = join19(binDir, platform === "win32" ? "zam.cmd" : "zam");
   const report = {
     status: "ok",
     binDir,
@@ -12089,7 +12396,7 @@ function installCliShim(options = {}) {
     pathUpdated: false,
     needsNewTerminal: false
   };
-  if (!BUILT_CLI_PATTERN.test(cliPath) || !existsSync17(cliPath)) {
+  if (!BUILT_CLI_PATTERN.test(cliPath) || !existsSync18(cliPath)) {
     report.status = "skipped";
     report.detail = `Not running from a built CLI entry (${cliPath}); nothing to link.`;
     return report;
@@ -12103,11 +12410,11 @@ function installCliShim(options = {}) {
       return report;
     }
     const content = platform === "win32" ? windowsShimContent(nodePath, cliPath) : unixShimContent(nodePath, cliPath);
-    const existed = existsSync17(shimPath);
-    const changed = !existed || readFileSync14(shimPath, "utf8") !== content;
+    const existed = existsSync18(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";
@@ -28816,40 +29123,40 @@ function getCurriculumProvider(id) {
 
 // src/cli/install-repair.ts
 init_kernel();
-import { existsSync as existsSync19 } from "fs";
+import { existsSync as existsSync20 } from "fs";
 
 // src/cli/provisioning/index.ts
 import {
-  existsSync as existsSync18,
+  existsSync as existsSync19,
   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 join19 } from "path";
-import { fileURLToPath as fileURLToPath5 } from "url";
+import { basename as basename4, dirname as dirname10, join as join20 } from "path";
+import { fileURLToPath as fileURLToPath6 } from "url";
 var packageRoot3 = [
-  fileURLToPath5(new URL("../..", import.meta.url)),
-  fileURLToPath5(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync18(join19(candidate, "package.json"))) ?? fileURLToPath5(new URL("../..", import.meta.url));
+  fileURLToPath6(new URL("../..", import.meta.url)),
+  fileURLToPath6(new URL("../../..", import.meta.url))
+].find((candidate) => existsSync19(join20(candidate, "package.json"))) ?? fileURLToPath6(new URL("../..", import.meta.url));
 var ALL_SETUP_AGENTS = ["claude", "copilot", "codex", "agent"];
 var SKILL_PAIRS = [
   {
-    from: join19(packageRoot3, ".claude", "skills", "zam", "SKILL.md"),
-    to: join19(".claude", "skills", "zam", "SKILL.md"),
+    from: join20(packageRoot3, ".claude", "skills", "zam", "SKILL.md"),
+    to: join20(".claude", "skills", "zam", "SKILL.md"),
     agents: ["claude", "copilot"]
   },
   {
-    from: join19(packageRoot3, ".agent", "skills", "zam", "SKILL.md"),
-    to: join19(".agent", "skills", "zam", "SKILL.md"),
+    from: join20(packageRoot3, ".agent", "skills", "zam", "SKILL.md"),
+    to: join20(".agent", "skills", "zam", "SKILL.md"),
     agents: ["agent"]
   },
   {
-    from: join19(packageRoot3, ".agents", "skills", "zam", "SKILL.md"),
-    to: join19(".agents", "skills", "zam", "SKILL.md"),
+    from: join20(packageRoot3, ".agents", "skills", "zam", "SKILL.md"),
+    to: join20(".agents", "skills", "zam", "SKILL.md"),
     agents: ["codex"]
   }
 ];
@@ -28893,7 +29200,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) {
@@ -28909,15 +29216,15 @@ function linkPointsTo(sourceDir, destinationDir) {
 function isZamSkillCopy(destinationDir) {
   try {
     if (!lstatSync2(destinationDir).isDirectory()) return false;
-    const skillFile = join19(destinationDir, "SKILL.md");
-    if (!existsSync18(skillFile)) return false;
-    return /^name:\s*zam\s*$/m.test(readFileSync15(skillFile, "utf8"));
+    const skillFile = join20(destinationDir, "SKILL.md");
+    if (!existsSync19(skillFile)) return false;
+    return /^name:\s*zam\s*$/m.test(readFileSync16(skillFile, "utf8"));
   } catch {
     return false;
   }
 }
 function classifySkillDestination(sourceDir, destinationDir) {
-  if (!existsSync18(sourceDir)) return "source-missing";
+  if (!existsSync19(sourceDir)) return "source-missing";
   if (!isSymbolicLink(destinationDir) && pathsResolveToSameDirectory(sourceDir, destinationDir)) {
     return "source-directory";
   }
@@ -28934,9 +29241,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(join19(cwd, to));
-    const label = dirname9(to);
+    const sourceDir = dirname10(from);
+    const destinationDir = dirname10(join20(cwd, to));
+    const label = dirname10(to);
     const state = classifySkillDestination(sourceDir, destinationDir);
     if (state === "source-missing") {
       if (!opts.quiet) {
@@ -28993,7 +29300,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,
@@ -29009,8 +29316,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(join19(cwd, to));
+    const sourceDir = dirname10(from);
+    const destinationDir = dirname10(join20(cwd, to));
     results.push({
       agents: pairAgents,
       source: sourceDir,
@@ -29041,7 +29348,7 @@ function defaultRepairWorkspaces() {
   try {
     const agents = parseSetupAgents();
     for (const workspace of getConfiguredWorkspaces()) {
-      if (!existsSync19(workspace.path)) {
+      if (!existsSync20(workspace.path)) {
         summary.missing += 1;
         continue;
       }
@@ -29234,9 +29541,9 @@ init_client();
 init_kernel();
 init_client();
 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 join20 } from "path";
+import { basename as basename5, join as join21 } from "path";
 var LANGUAGE_NAMES2 = {
   en: "English",
   de: "German",
@@ -29274,7 +29581,7 @@ async function observeUiSnapshotViaLLM(db, input) {
   if (isVideo) {
     const { mkdirSync: mkdirSync17, readdirSync: readdirSync4, rmSync: rmSync4 } = await import("fs");
     const { execSync: execSync5 } = await import("child_process");
-    const tempDir = join20(
+    const tempDir = join21(
       tmpdir2(),
       `zam-frames-${randomBytes(4).toString("hex")}`
     );
@@ -29307,7 +29614,7 @@ async function observeUiSnapshotViaLLM(db, input) {
         }
       }
       for (const file of sampledFiles) {
-        const bytes = readFileSync16(join20(tempDir, file));
+        const bytes = readFileSync17(join21(tempDir, file));
         imageUrls.push(`data:image/png;base64,${bytes.toString("base64")}`);
       }
     } finally {
@@ -29317,7 +29624,7 @@ async function observeUiSnapshotViaLLM(db, input) {
       }
     }
   } else {
-    const imageBytes = readFileSync16(input.imagePath);
+    const imageBytes = readFileSync17(input.imagePath);
     const ext = input.imagePath.split(".").pop()?.toLowerCase();
     const mime = ext === "jpg" || ext === "jpeg" ? "image/jpeg" : "image/png";
     imageUrls.push(`data:${mime};base64,${imageBytes.toString("base64")}`);
@@ -29826,13 +30133,13 @@ async function resolveUser(opts, db, resolveOpts) {
 }
 
 // src/cli/workspaces/backup.ts
-import { mkdirSync as mkdirSync15 } from "fs";
-import { join as join21 } from "path";
+import { mkdirSync as mkdirSync16 } from "fs";
+import { join as join22 } from "path";
 async function backupDatabaseTo(db, targetDir) {
-  const backupDir = join21(targetDir, "zam-backups");
-  mkdirSync15(backupDir, { recursive: true });
+  const backupDir = join22(targetDir, "zam-backups");
+  mkdirSync16(backupDir, { recursive: true });
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const dest = join21(backupDir, `zam-${stamp}.db`);
+  const dest = join22(backupDir, `zam-${stamp}.db`);
   await db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
   return dest;
 }
@@ -29966,20 +30273,20 @@ bridgeCommand.command("workspace-info").description("Report the workspace dir, i
       activeWorkspace,
       workspaceDir: activeWorkspace.path,
       defaultWorkspaceDir: defaultWorkspaceDir(),
-      dataDir: join22(homedir14(), ".zam")
+      dataDir: join23(homedir14(), ".zam")
     });
   });
 });
 function provisionConfiguredWorkspaces() {
   return getConfiguredWorkspaces().flatMap(
-    (workspace) => existsSync20(workspace.path) ? wireSkills(workspace.path, parseSetupAgents(), { quiet: true }) : []
+    (workspace) => existsSync21(workspace.path) ? wireSkills(workspace.path, parseSetupAgents(), { quiet: true }) : []
   );
 }
 function buildWorkspaceLinkHealth(workspaces) {
   const agents = parseSetupAgents();
   const map = {};
   for (const workspace of workspaces) {
-    if (!existsSync20(workspace.path)) continue;
+    if (!existsSync21(workspace.path)) continue;
     const links = inspectSkillLinks(workspace.path, agents);
     map[workspace.id] = {
       health: summarizeSkillLinkHealth(links),
@@ -30009,7 +30316,7 @@ bridgeCommand.command("workspace-list").description("List configured ZAM workspa
       activeWorkspace,
       workspaceDir: activeWorkspace.path,
       defaultWorkspaceDir: defaultWorkspaceDir(),
-      dataDir: join22(homedir14(), ".zam"),
+      dataDir: join23(homedir14(), ".zam"),
       linkHealth: buildWorkspaceLinkHealth(workspaces)
     });
   });
@@ -30024,7 +30331,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 (!existsSync20(workspace.path)) {
+  if (!existsSync21(workspace.path)) {
     jsonError(`Workspace path does not exist: ${workspace.path}`);
   }
   const agents = parseSetupAgents(opts.agents);
@@ -30055,8 +30362,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 (!existsSync20(path)) jsonError(`Workspace path does not exist: ${path}`);
+  const path = resolve7(raw);
+  if (!existsSync21(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);
@@ -30100,8 +30407,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 (!existsSync20(dir)) jsonError(`Workspace path does not exist: ${dir}`);
+  const dir = resolve7(raw);
+  if (!existsSync21(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);
@@ -30164,7 +30471,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 ? existsSync20(opts.dir) ? opts.dir : homedir14() : existingWorkspaceDirOrHome(configuredWorkspace ?? activeWorkspace);
+    const workspace = opts.dir ? existsSync21(opts.dir) ? opts.dir : homedir14() : existingWorkspaceDirOrHome(configuredWorkspace ?? activeWorkspace);
     launchHarness(harness, {
       executable,
       workspace,
@@ -30440,6 +30747,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
+        });
+        jsonOut(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;
@@ -30536,10 +30889,10 @@ bridgeCommand.command("discover-skills").description(
   "20"
 ).action(async (opts) => {
   try {
-    const monitorDir = join22(homedir14(), ".zam", "monitor");
+    const monitorDir = join23(homedir14(), ".zam", "monitor");
     let files;
     try {
-      files = readdirSync2(monitorDir).filter((f) => f.endsWith(".jsonl"));
+      files = readdirSync3(monitorDir).filter((f) => f.endsWith(".jsonl"));
     } catch {
       jsonOut({ proposals: [], message: "No monitor logs found." });
       return;
@@ -30549,7 +30902,7 @@ bridgeCommand.command("discover-skills").description(
       return;
     }
     const limit = Number(opts.limit);
-    const sorted = files.map((f) => ({ name: f, path: join22(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
+    const sorted = files.map((f) => ({ name: f, path: join23(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", "");
@@ -31051,7 +31404,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
         return;
       }
     }
-    const outputPath = opts.image ?? opts.output ?? join22(tmpdir3(), `zam-capture-${randomBytes2(4).toString("hex")}.png`);
+    const outputPath = opts.image ?? opts.output ?? join23(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, {
@@ -31079,7 +31432,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");
     jsonOut({
       sessionId: opts.session ?? null,
@@ -31106,9 +31459,9 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     return;
   }
   const sessionId = opts.session;
-  const statePath = join22(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const statePath = join23(tmpdir3(), `zam-recording-${sessionId}.json`);
   const defaultExt = platform === "win32" ? ".mkv" : ".mov";
-  const outputPath = opts.output ?? join22(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
+  const outputPath = opts.output ?? join23(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
   const { existsSync: existsSync23, writeFileSync: writeFileSync14, openSync, closeSync } = await import("fs");
   if (existsSync23(statePath)) {
     jsonOut({
@@ -31118,7 +31471,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     });
     return;
   }
-  const logPath = join22(tmpdir3(), `zam-recording-${sessionId}.log`);
+  const logPath = join23(tmpdir3(), `zam-recording-${sessionId}.log`);
   let logFd;
   try {
     logFd = openSync(logPath, "w");
@@ -31200,7 +31553,7 @@ bridgeCommand.command("stop-recording").description(
     return;
   }
   const sessionId = opts.session;
-  const statePath = join22(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const statePath = join23(tmpdir3(), `zam-recording-${sessionId}.json`);
   const { existsSync: existsSync23, readFileSync: readFileSync20, rmSync: rmSync4 } = await import("fs");
   if (!existsSync23(statePath)) {
     jsonOut({
@@ -31669,7 +32022,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") || existsSync20("C:\\Program Files\\flm\\flm.exe");
+  const flmInstalled = hasCommand("flm") || existsSync21("C:\\Program Files\\flm\\flm.exe");
   const ollamaInstalled = isOllamaInstalled();
   const runners = [
     { id: "flm", label: "FastFlowLM", installed: flmInstalled },
@@ -32043,7 +32396,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 = {};
@@ -32051,6 +32409,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
@@ -33804,13 +34164,13 @@ async function writeCompanionContext(db, request, options = {}) {
 // src/cli/ui-intent.ts
 import { mkdir, readFile, rename, writeFile } from "fs/promises";
 import { homedir as homedir15 } from "os";
-import { dirname as dirname10, join as join23 } from "path";
+import { dirname as dirname11, join as join24 } from "path";
 import { ulid as ulid11 } from "ulid";
 function getUiIntentPath(home = homedir15()) {
-  return join23(home, ".zam", "ui-intent.json");
+  return join24(home, ".zam", "ui-intent.json");
 }
 function getUiHostRegistrationPath(home = homedir15()) {
-  return join23(home, ".zam", "vscode-host.json");
+  return join24(home, ".zam", "vscode-host.json");
 }
 function compactStringInput(input) {
   return Object.fromEntries(
@@ -33829,8 +34189,8 @@ async function writeUiIntent(app, input = {}, opts = {}) {
     input: compactStringInput(input),
     createdAt: (opts.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
   };
-  const tempPath = join23(dirname10(path), `.ui-intent-${process.pid}-${id}.tmp`);
-  await mkdir(dirname10(path), { recursive: true });
+  const tempPath = join24(dirname11(path), `.ui-intent-${process.pid}-${id}.tmp`);
+  await mkdir(dirname11(path), { recursive: true });
   await writeFile(tempPath, `${JSON.stringify(intent, null, 2)}
 `, "utf8");
   await rename(tempPath, path);
@@ -33863,10 +34223,10 @@ async function publishUiIntent(app, input = {}, opts = {}) {
 }
 
 // src/cli/commands/mcp.ts
-var __dirname = dirname12(fileURLToPath6(import.meta.url));
-var pkgPath = join25(__dirname, "..", "..", "package.json");
+var __dirname = dirname13(fileURLToPath7(import.meta.url));
+var pkgPath = join26(__dirname, "..", "..", "package.json");
 if (!existsSync22(pkgPath)) {
-  pkgPath = join25(__dirname, "..", "..", "..", "package.json");
+  pkgPath = join26(__dirname, "..", "..", "..", "package.json");
 }
 var pkg = JSON.parse(readFileSync19(pkgPath, "utf-8"));
 var STUDIO_RESOURCE_URI = "ui://zam/studio";
@@ -33896,9 +34256,9 @@ var STUDIO_BRIDGE_ALLOWED_COMMANDS = /* @__PURE__ */ new Set([
 function loadPanelHtml(fileName, placeholderTitle) {
   const candidates = [
     // dist/cli/commands/mcp.js → dist/ui/
-    join25(__dirname, "..", "..", "ui", fileName),
+    join26(__dirname, "..", "..", "ui", fileName),
     // src/cli/commands/mcp.ts via tsx → <repo>/dist/ui/
-    join25(__dirname, "..", "..", "..", "dist", "ui", fileName)
+    join26(__dirname, "..", "..", "..", "dist", "ui", fileName)
   ];
   for (const candidate of candidates) {
     if (existsSync22(candidate)) {
@@ -34467,7 +34827,7 @@ function createMcpServer(db) {
     "zam_show_graph",
     {
       title: "Open ZAM knowledge graph",
-      description: "Open the ZAM 2D knowledge-graph card, centered on a token's direct prerequisites and dependents. Pass `focus` (a token slug) when the conversation already names one; otherwise the card shows a hint to supply one.",
+      description: "Open the ZAM 2D knowledge-graph card, centered on a token's direct prerequisites and dependents. Pass `focus` (a token slug) when the conversation already names one; without it the card offers scope selectors and defaults to tokens anchored in the current repo's OKF knowledge base.",
       inputSchema: {
         focus: z.string().optional().describe("Token slug to center the graph on"),
         user: z.string().optional().describe("User ID")
@@ -34489,6 +34849,16 @@ function createMcpServer(db) {
         { clientSamplingCapable: getClientSamplingCapable() }
       );
       const userId = opening.context.user.currentId ?? null;
+      let repoScope;
+      try {
+        const { collectSourceLinkBases: collectSourceLinkBases2, findRepoRoot: findRepoRoot2 } = await Promise.resolve().then(() => (init_io(), io_exports));
+        const bundleDir = await resolveOkfBundleDir();
+        const bases = collectSourceLinkBases2(bundleDir);
+        if (bases.length > 0) {
+          repoScope = { label: basename6(findRepoRoot2(bundleDir)), bases };
+        }
+      } catch {
+      }
       await publishUiIntent("graph", { user, focus });
       return {
         graph: "zam",
@@ -34496,6 +34866,7 @@ function createMcpServer(db) {
         version: pkg.version,
         user: userId,
         companionContext: opening.context,
+        ...repoScope ? { repoScope } : {},
         ...opening.degraded ? { companionContextDegraded: true } : {}
       };
     })
@@ -34667,7 +35038,24 @@ function createMcpServer(db) {
       }
     )
   );
-  const okfBundleDirSchema = z.string().optional().describe("Bundle directory (default docs/okf under the server cwd)");
+  const okfBundleDirSchema = z.string().optional().describe(
+    "Bundle directory (default: docs/okf under the client's workspace root, falling back to the server cwd)"
+  );
+  async function resolveOkfBundleDir(explicit) {
+    const { DEFAULT_BUNDLE_DIR: DEFAULT_BUNDLE_DIR2, resolveBundleDirFromRoots: resolveBundleDirFromRoots2 } = await Promise.resolve().then(() => (init_io(), io_exports));
+    if (explicit) return explicit;
+    try {
+      if (server.server.getClientCapabilities()?.roots) {
+        const { roots } = await server.server.listRoots();
+        return resolveBundleDirFromRoots2(
+          (roots ?? []).map((root) => root.uri),
+          DEFAULT_BUNDLE_DIR2
+        );
+      }
+    } catch {
+    }
+    return DEFAULT_BUNDLE_DIR2;
+  }
   server.registerTool(
     "zam_okf_catalog",
     {
@@ -34685,13 +35073,13 @@ function createMcpServer(db) {
     },
     wrapHandler(
       async (params) => {
-        const { DEFAULT_BUNDLE_DIR: DEFAULT_BUNDLE_DIR2, loadBundle: loadBundle2 } = await Promise.resolve().then(() => (init_io(), io_exports));
-        const bundle = loadBundle2(params.bundle_dir ?? DEFAULT_BUNDLE_DIR2);
+        const { loadBundle: loadBundle2 } = await Promise.resolve().then(() => (init_io(), io_exports));
+        const bundle = loadBundle2(await resolveOkfBundleDir(params.bundle_dir));
         let log;
         if (params.include_log) {
           const { readFileSync: readFileSync20 } = await import("fs");
           try {
-            log = readFileSync20(join25(bundle.dir, "log.md"), "utf8");
+            log = readFileSync20(join26(bundle.dir, "log.md"), "utf8");
           } catch {
             log = "";
           }
@@ -34720,10 +35108,10 @@ function createMcpServer(db) {
     },
     wrapHandler(async (params) => {
       const { readFileSync: readFileSync20 } = await import("fs");
-      const { DEFAULT_BUNDLE_DIR: DEFAULT_BUNDLE_DIR2, resolveArticlePath: resolveArticlePath2 } = await Promise.resolve().then(() => (init_io(), io_exports));
+      const { resolveArticlePath: resolveArticlePath2 } = await Promise.resolve().then(() => (init_io(), io_exports));
       const { parseFrontmatter: parseFrontmatter2 } = await Promise.resolve().then(() => (init_bundle(), bundle_exports));
       const path = resolveArticlePath2(
-        params.bundle_dir ?? DEFAULT_BUNDLE_DIR2,
+        await resolveOkfBundleDir(params.bundle_dir),
         params.file
       );
       const markdown = readFileSync20(path, "utf8");
@@ -34750,9 +35138,9 @@ function createMcpServer(db) {
     },
     wrapHandler(
       async (params) => {
-        const { DEFAULT_BUNDLE_DIR: DEFAULT_BUNDLE_DIR2, upsertArticle: upsertArticle2 } = await Promise.resolve().then(() => (init_io(), io_exports));
+        const { upsertArticle: upsertArticle2 } = await Promise.resolve().then(() => (init_io(), io_exports));
         const result = upsertArticle2(
-          params.bundle_dir ?? DEFAULT_BUNDLE_DIR2,
+          await resolveOkfBundleDir(params.bundle_dir),
           params.file,
           params.markdown
         );
@@ -34763,6 +35151,96 @@ function createMcpServer(db) {
       }
     )
   );
+  server.registerTool(
+    "zam_okf_import",
+    {
+      description: "Record YOUR finished decomposition of one OKF article as learning tokens + cards (ADR 2026-07-18). Decomposition is your job, not this tool's \u2014 before calling: (1) read the FULL article (zam_okf_read); (2) extract the concepts a practitioner must produce FROM MEMORY \u2014 recall-speed knowledge only; facts one would look up stay in the article; (3) one atomic concept per token, with a JUDGED bloom level and a JUDGED domain per token (reuse existing domains where they fit); (4) arrange a prerequisite DAG from foundational to dependent (in-import slugs and existing tokens both allowed); (5) check for existing tokens first (zam_find_tokens) and link them as prerequisites instead of duplicating. Multiple tokens are the expected outcome for real articles. On RE-import classify each token via mode: 'new' adds, 'update' refreshes content and KEEPS learning state, 'replace' means the concept changed \u2014 content refreshed and learning state RESET to the beginning. Previously imported tokens you do not confirm are moved to maintenance (kept, unscheduled) \u2014 never deleted. The write is atomic; every token gets a card for the importing user.",
+      inputSchema: {
+        user: z.string().optional().describe("User ID to create cards for"),
+        bundle_dir: okfBundleDirSchema,
+        file: z.string().describe("Article file name inside the bundle (kebab-case .md)"),
+        tokens: z.array(
+          z.object({
+            slug: z.string().describe("Unique kebab-case token slug"),
+            title: z.string().optional().describe("Display title"),
+            concept: z.string().describe("The memorable concept, stated precisely"),
+            bloomLevel: z.number().int().min(1).max(5).optional().describe("Judged Bloom level (1-5)"),
+            domain: z.string().optional().describe("Judged domain (reuse existing domains)"),
+            anchor: z.string().optional().describe(
+              "Heading anchor in the article; appended to the source link"
+            ),
+            prerequisites: z.array(z.string()).optional().describe(
+              "Slugs this token requires \u2014 in-import or existing tokens"
+            ),
+            knowledgeContexts: z.array(z.string()).optional().describe("Knowledge contexts to assign"),
+            question: z.string().nullable().optional().describe("Optional pre-defined review question"),
+            mode: z.enum(["new", "update", "replace"]).optional().describe(
+              "Re-import classification: new (default) | update (keep learning state) | replace (concept changed, reset learning state)"
+            )
+          })
+        ).min(1).describe("Your finished decomposition")
+      },
+      annotations: {
+        ...commonAnnotations
+      }
+    },
+    wrapHandler(
+      async (params) => {
+        return await importOkfTokens(db, {
+          user: await getUserId(params.user),
+          bundleDir: await resolveOkfBundleDir(params.bundle_dir),
+          file: params.file,
+          tokens: params.tokens
+        });
+      }
+    )
+  );
+  registerAppTool(
+    server,
+    "zam_okf_focus",
+    {
+      description: "App-only: record which OKF article the visualizer panel currently shows, so chat agents can resolve 'the currently focused article'. Not intended for direct model use.",
+      inputSchema: {
+        file: z.string().describe("Article file name inside the bundle (kebab-case .md)"),
+        bundle_dir: z.string().optional().describe("Absolute bundle directory the panel is browsing")
+      },
+      annotations: {
+        ...commonAnnotations,
+        destructiveHint: false,
+        idempotentHint: true
+      },
+      _meta: {
+        ui: { visibility: ["app"] }
+      }
+    },
+    wrapHandler(async (params) => {
+      const { writeOkfFocus: writeOkfFocus2 } = await Promise.resolve().then(() => (init_okf_focus(), okf_focus_exports));
+      const focus = await writeOkfFocus2(params.file, params.bundle_dir);
+      return { recorded: { file: focus.file, updatedAt: focus.updatedAt } };
+    })
+  );
+  server.registerTool(
+    "zam_okf_focused",
+    {
+      description: "The OKF article currently focused in the user's visualizer panel \u2014 resolve requests like 'import this okf', 'import the currently focused article', or 'the open article'. Returns {focused: {file, bundle_dir?, updatedAt} | null}; check updatedAt and confirm the article by name with the user if it looks stale. To import, read the article (zam_okf_read) and follow the zam_okf_import contract.",
+      inputSchema: {},
+      annotations: {
+        ...commonAnnotations,
+        readOnlyHint: true
+      }
+    },
+    wrapHandler(async () => {
+      const { readOkfFocus: readOkfFocus2 } = await Promise.resolve().then(() => (init_okf_focus(), okf_focus_exports));
+      const focus = await readOkfFocus2();
+      return {
+        focused: focus ? {
+          file: focus.file,
+          ...focus.bundleDir ? { bundle_dir: focus.bundleDir } : {},
+          updatedAt: focus.updatedAt
+        } : null
+      };
+    })
+  );
   server.registerTool(
     "zam_okf_read_citation",
     {
@@ -34781,8 +35259,8 @@ function createMcpServer(db) {
     wrapHandler(async (params) => {
       const { readFileSync: readFileSync20 } = await import("fs");
       const { relative: relative2, sep: sep2 } = await import("path");
-      const { DEFAULT_BUNDLE_DIR: DEFAULT_BUNDLE_DIR2, findRepoRoot: findRepoRoot2, resolveCitationPath: resolveCitationPath2 } = await Promise.resolve().then(() => (init_io(), io_exports));
-      const bundleDir = params.bundle_dir ?? DEFAULT_BUNDLE_DIR2;
+      const { findRepoRoot: findRepoRoot2, resolveCitationPath: resolveCitationPath2 } = await Promise.resolve().then(() => (init_io(), io_exports));
+      const bundleDir = await resolveOkfBundleDir(params.bundle_dir);
       const path = resolveCitationPath2(bundleDir, params.target);
       const content = readFileSync20(path, "utf8");
       const root = findRepoRoot2(bundleDir);
@@ -34815,11 +35293,11 @@ function createMcpServer(db) {
         getNativeClientInfo(),
         { clientSamplingCapable: getClientSamplingCapable() }
       );
-      await publishUiIntent("okf", { bundle_dir });
-      const { DEFAULT_BUNDLE_DIR: DEFAULT_BUNDLE_DIR2, loadBundle: loadBundle2 } = await Promise.resolve().then(() => (init_io(), io_exports));
+      const { loadBundle: loadBundle2 } = await Promise.resolve().then(() => (init_io(), io_exports));
       const { resolve: resolve8 } = await import("path");
-      const requestedDir = bundle_dir ?? DEFAULT_BUNDLE_DIR2;
+      const requestedDir = await resolveOkfBundleDir(bundle_dir);
       let resolvedBundleDir = resolve8(requestedDir);
+      await publishUiIntent("okf", { bundle_dir: resolvedBundleDir });
       let catalog = [];
       let problems = [];
       let log = "";
@@ -34831,13 +35309,13 @@ function createMcpServer(db) {
         problems = bundle.problems;
         const { readFileSync: readFileSync20 } = await import("fs");
         try {
-          log = readFileSync20(join25(bundle.dir, "log.md"), "utf8");
+          log = readFileSync20(join26(bundle.dir, "log.md"), "utf8");
         } catch {
           log = "";
         }
         try {
           const { parseFrontmatter: parseFrontmatter2 } = await Promise.resolve().then(() => (init_bundle(), bundle_exports));
-          const indexRaw = readFileSync20(join25(bundle.dir, "index.md"), "utf8");
+          const indexRaw = readFileSync20(join26(bundle.dir, "index.md"), "utf8");
           const { fields } = parseFrontmatter2(indexRaw);
           okfVersion = typeof fields.okf_version === "string" ? fields.okf_version : null;
         } catch {