zam-core 0.11.0 → 0.12.0

package/dist/cli/commands/mcp.js

@@ -6178,9 +6178,18 @@ function getMachineCompanionConfig(path = defaultConfigPath()) {
   if (typeof raw.selectedEvaluatorId === "string") {
     result.selectedEvaluatorId = raw.selectedEvaluatorId;
   }
+  if (typeof raw.selectedVscodeEvaluatorId === "string") {
+    result.selectedVscodeEvaluatorId = raw.selectedVscodeEvaluatorId;
+  }
+  if (typeof raw.selectedAntigravityEvaluatorId === "string") {
+    result.selectedAntigravityEvaluatorId = raw.selectedAntigravityEvaluatorId;
+  }
   if (typeof raw.selectedVscodeModelId === "string") {
     result.selectedVscodeModelId = raw.selectedVscodeModelId;
   }
+  if (typeof raw.selectedAntigravityModelId === "string") {
+    result.selectedAntigravityModelId = raw.selectedAntigravityModelId;
+  }
   if (raw.collapsed && typeof raw.collapsed === "object" && !Array.isArray(raw.collapsed)) {
     const collapsed = {};
     for (const [surface, value] of Object.entries(raw.collapsed)) {
@@ -6211,6 +6220,34 @@ function updateMachineCompanionConfig(update, path = defaultConfigPath()) {
       delete companion.selectedEvaluatorId;
     }
   }
+  if ("selectedVscodeEvaluatorId" in update) {
+    if (update.selectedVscodeEvaluatorId) {
+      companion.selectedVscodeEvaluatorId = update.selectedVscodeEvaluatorId;
+    } else {
+      delete companion.selectedVscodeEvaluatorId;
+    }
+  }
+  if ("selectedAntigravityEvaluatorId" in update) {
+    if (update.selectedAntigravityEvaluatorId) {
+      companion.selectedAntigravityEvaluatorId = update.selectedAntigravityEvaluatorId;
+    } else {
+      delete companion.selectedAntigravityEvaluatorId;
+    }
+  }
+  if ("selectedVscodeModelId" in update) {
+    if (update.selectedVscodeModelId) {
+      companion.selectedVscodeModelId = update.selectedVscodeModelId;
+    } else {
+      delete companion.selectedVscodeModelId;
+    }
+  }
+  if ("selectedAntigravityModelId" in update) {
+    if (update.selectedAntigravityModelId) {
+      companion.selectedAntigravityModelId = update.selectedAntigravityModelId;
+    } else {
+      delete companion.selectedAntigravityModelId;
+    }
+  }
   if (update.collapsed) {
     companion.collapsed = {
       ...companion.collapsed ?? {},
@@ -6244,6 +6281,30 @@ function setCompanionSelectedEvaluatorId(evaluatorId, path = defaultConfigPath()
   }
   saveMachineCompanionConfig(companion, path);
 }
+function getCompanionSelectedVscodeEvaluatorId(path = defaultConfigPath()) {
+  return getMachineCompanionConfig(path).selectedVscodeEvaluatorId;
+}
+function setCompanionSelectedVscodeEvaluatorId(evaluatorId, path = defaultConfigPath()) {
+  const companion = getMachineCompanionConfig(path);
+  if (evaluatorId) {
+    companion.selectedVscodeEvaluatorId = evaluatorId;
+  } else {
+    delete companion.selectedVscodeEvaluatorId;
+  }
+  saveMachineCompanionConfig(companion, path);
+}
+function getCompanionSelectedAntigravityEvaluatorId(path = defaultConfigPath()) {
+  return getMachineCompanionConfig(path).selectedAntigravityEvaluatorId;
+}
+function setCompanionSelectedAntigravityEvaluatorId(evaluatorId, path = defaultConfigPath()) {
+  const companion = getMachineCompanionConfig(path);
+  if (evaluatorId) {
+    companion.selectedAntigravityEvaluatorId = evaluatorId;
+  } else {
+    delete companion.selectedAntigravityEvaluatorId;
+  }
+  saveMachineCompanionConfig(companion, path);
+}
 function getCompanionSelectedVscodeModelId(path = defaultConfigPath()) {
   return getMachineCompanionConfig(path).selectedVscodeModelId;
 }
@@ -6256,6 +6317,18 @@ function setCompanionSelectedVscodeModelId(modelId, path = defaultConfigPath())
   }
   saveMachineCompanionConfig(companion, path);
 }
+function getCompanionSelectedAntigravityModelId(path = defaultConfigPath()) {
+  return getMachineCompanionConfig(path).selectedAntigravityModelId;
+}
+function setCompanionSelectedAntigravityModelId(modelId, path = defaultConfigPath()) {
+  const companion = getMachineCompanionConfig(path);
+  if (modelId) {
+    companion.selectedAntigravityModelId = modelId;
+  } else {
+    delete companion.selectedAntigravityModelId;
+  }
+  saveMachineCompanionConfig(companion, path);
+}
 function getCompanionCollapsed(path = defaultConfigPath()) {
   return getMachineCompanionConfig(path).collapsed ?? {};
 }
@@ -6984,8 +7057,11 @@ __export(kernel_exports, {
   getCardById: () => getCardById,
   getCardDeletionImpact: () => getCardDeletionImpact,
   getCompanionCollapsed: () => getCompanionCollapsed,
+  getCompanionSelectedAntigravityEvaluatorId: () => getCompanionSelectedAntigravityEvaluatorId,
+  getCompanionSelectedAntigravityModelId: () => getCompanionSelectedAntigravityModelId,
   getCompanionSelectedEvaluatorId: () => getCompanionSelectedEvaluatorId,
   getCompanionSelectedUserId: () => getCompanionSelectedUserId,
+  getCompanionSelectedVscodeEvaluatorId: () => getCompanionSelectedVscodeEvaluatorId,
   getCompanionSelectedVscodeModelId: () => getCompanionSelectedVscodeModelId,
   getConfiguredWorkspaces: () => getConfiguredWorkspaces,
   getDatabaseTargetInfo: () => getDatabaseTargetInfo,
@@ -7098,8 +7174,11 @@ __export(kernel_exports, {
   setActiveWorkspaceId: () => setActiveWorkspaceId,
   setAgentConnectAutoDone: () => setAgentConnectAutoDone,
   setCompanionCollapsed: () => setCompanionCollapsed,
+  setCompanionSelectedAntigravityEvaluatorId: () => setCompanionSelectedAntigravityEvaluatorId,
+  setCompanionSelectedAntigravityModelId: () => setCompanionSelectedAntigravityModelId,
   setCompanionSelectedEvaluatorId: () => setCompanionSelectedEvaluatorId,
   setCompanionSelectedUserId: () => setCompanionSelectedUserId,
+  setCompanionSelectedVscodeEvaluatorId: () => setCompanionSelectedVscodeEvaluatorId,
   setCompanionSelectedVscodeModelId: () => setCompanionSelectedVscodeModelId,
   setInstallChannel: () => setInstallChannel,
   setInstallMode: () => setInstallMode,
@@ -7180,330 +7259,119 @@ var init_kernel = __esm({
   }
 });
 
-// src/cli/commands/mcp.ts
-init_kernel();
-import { existsSync as existsSync21, readFileSync as readFileSync18 } from "fs";
-import { dirname as dirname11, join as join24 } from "path";
-import { fileURLToPath as fileURLToPath6 } from "url";
-import {
-  RESOURCE_MIME_TYPE,
-  registerAppResource,
-  registerAppTool
-} from "@modelcontextprotocol/ext-apps/server";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-
-// src/vscode-extension/companion-evaluator.ts
-var ROUTABLE_EVALUATOR_IDS = [
-  "native-mcp-host",
-  "vscode-lm",
-  "quick-mode"
-];
-var DETACHED_HARNESS_EVALUATOR_IDS = [
-  "claude-code",
-  "codex",
-  "opencode",
-  "goose"
-];
-function isEvaluatorId(value) {
-  return typeof value === "string" && (ROUTABLE_EVALUATOR_IDS.includes(value) || DETACHED_HARNESS_EVALUATOR_IDS.includes(value));
+// src/cli/llm/client.ts
+var client_exports = {};
+__export(client_exports, {
+  DEFAULT_LLM_API_KEY: () => DEFAULT_LLM_API_KEY,
+  DEFAULT_LLM_MAX_TOKENS: () => DEFAULT_LLM_MAX_TOKENS,
+  DEFAULT_LLM_MODEL: () => DEFAULT_LLM_MODEL,
+  DEFAULT_LLM_URL: () => DEFAULT_LLM_URL,
+  LlmResponseTruncatedError: () => LlmResponseTruncatedError,
+  RECALL_DISCUSSION_MAX_OUTPUT_TOKENS: () => RECALL_DISCUSSION_MAX_OUTPUT_TOKENS,
+  RECALL_EVALUATION_MAX_OUTPUT_TOKENS: () => RECALL_EVALUATION_MAX_OUTPUT_TOKENS,
+  RECALL_QUESTION_MAX_OUTPUT_TOKENS: () => RECALL_QUESTION_MAX_OUTPUT_TOKENS,
+  checkVisionReadiness: () => checkVisionReadiness,
+  clearRecallEndpointCache: () => clearRecallEndpointCache,
+  discussReviewViaLLM: () => discussReviewViaLLM,
+  ensureHighQualityQuestion: () => ensureHighQualityQuestion,
+  ensureLlmReadyHeadless: () => ensureLlmReadyHeadless,
+  ensureLocalLlmRunning: () => ensureLocalLlmRunning,
+  evaluateAnswerViaLLM: () => evaluateAnswerViaLLM,
+  extractTextFromScanViaLLM: () => extractTextFromScanViaLLM,
+  fetchWithInteractiveTimeout: () => fetchWithInteractiveTimeout,
+  generateFoundationsProposalsViaLLM: () => generateFoundationsProposalsViaLLM,
+  generateQuestionViaLLM: () => generateQuestionViaLLM,
+  generateSplitProposalsViaLLM: () => generateSplitProposalsViaLLM,
+  generateTitleViaLLM: () => generateTitleViaLLM,
+  getAvailableModels: () => getAvailableModels,
+  getCloudModelRecommendation: () => getCloudModelRecommendation,
+  getLlmConfig: () => getLlmConfig,
+  getProviderForRole: () => getProviderForRole,
+  getProviderRoleStatus: () => getProviderRoleStatus,
+  getVisionConfig: () => getVisionConfig,
+  importCurriculumViaLLM: () => importCurriculumViaLLM,
+  inferApiFlavor: () => inferApiFlavor,
+  isLlmOnline: () => isLlmOnline,
+  repairUmlautsViaLLM: () => repairUmlautsViaLLM,
+  resolveCapability: () => resolveCapability,
+  resolveUsableRecallEndpoint: () => resolveUsableRecallEndpoint,
+  sampleViaLocalLLM: () => sampleViaLocalLLM,
+  translateQuestionViaLLM: () => translateQuestionViaLLM
+});
+import { spawn } from "child_process";
+import { existsSync as existsSync11, readFileSync as readFileSync9, statSync as statSync2 } from "fs";
+function clearRecallEndpointCache() {
+  cachedRecallEndpoint = null;
 }
-function buildEvaluatorRoutes(inputs, selectedId) {
-  return inputs.map((input) => {
-    if (!input.routable && !input.reason) {
-      throw new Error(
-        `Unroutable evaluator "${input.id}" must carry an availability reason`
-      );
-    }
-    return { ...input, selected: input.id === selectedId, active: false };
-  });
+function recallEndpointSignature(cfg) {
+  return [
+    cfg.enabled ? "on" : "off",
+    cfg.providerName ?? "",
+    cfg.url,
+    cfg.model,
+    cfg.apiFlavor,
+    cfg.fallback?.url ?? "",
+    cfg.fallback?.model ?? ""
+  ].join("|");
 }
-var EvaluatorUnavailableError = class extends Error {
-  evaluatorId;
-  constructor(evaluatorId, reason) {
-    super(`Evaluator "${evaluatorId}" is unavailable: ${reason}`);
-    this.name = "EvaluatorUnavailableError";
-    this.evaluatorId = evaluatorId;
+async function getLlmConfig(db) {
+  return {
+    enabled: await getSetting(db, "llm.enabled") === "true",
+    url: await getSetting(db, "llm.url") || DEFAULT_LLM_URL,
+    model: await getSetting(db, "llm.model") || DEFAULT_LLM_MODEL,
+    apiKey: await getSetting(db, "llm.api_key") || DEFAULT_LLM_API_KEY,
+    locale: await getSetting(db, "system.locale") || "en"
+  };
+}
+function getCloudModelRecommendation(url) {
+  const lowercase = url.toLowerCase();
+  if (lowercase.includes("openrouter.ai")) {
+    return { model: "openrouter/free", flavor: "chat-completions" };
   }
-};
-function activateSelectedEvaluator(routes, selectedId) {
-  const route = routes.find((candidate) => candidate.id === selectedId);
-  if (!route) {
-    throw new EvaluatorUnavailableError(selectedId, "not configured");
+  if (lowercase.includes("openai.com") || lowercase.includes("api.openai")) {
+    return { model: "gpt-5-mini", flavor: "chat-completions" };
   }
-  if (!route.routable) {
-    throw new EvaluatorUnavailableError(
-      selectedId,
-      route.reason ?? "not routable on this surface"
-    );
+  if (lowercase.includes("googleapis.com") || lowercase.includes("google")) {
+    return { model: "gemini-3.5-flash", flavor: "chat-completions" };
   }
-  return { ...route, active: true };
-}
-
-// src/vscode-extension/companion-selection.ts
-function resolveSelection(candidates) {
-  if (candidates.invocation !== void 0) {
-    return {
-      value: candidates.invocation,
-      source: "invocation",
-      sessionScoped: true
-    };
+  if (lowercase.includes("deepseek.com")) {
+    return { model: "deepseek-v4-flash", flavor: "chat-completions" };
   }
-  if (candidates.manual !== void 0) {
-    return { value: candidates.manual, source: "manual", sessionScoped: false };
+  if (lowercase.includes("mimo")) {
+    return { model: "mimo-v2.5", flavor: "chat-completions" };
   }
-  if (candidates.persisted !== void 0) {
+  if (lowercase.includes("anthropic.com")) {
     return {
-      value: candidates.persisted,
-      source: "persisted",
-      sessionScoped: false
+      model: "claude-haiku-4-5-20251001",
+      flavor: "anthropic-messages"
     };
   }
-  return {
-    value: candidates.fallback,
-    source: "default",
-    sessionScoped: false
-  };
-}
-function isPersistableSelection(result) {
-  return result.source === "manual";
-}
-
-// src/vscode-extension/companion-context.ts
-var COMPANION_SURFACES = [
-  "recall",
-  "graph",
-  "settings",
-  "studio"
-];
-function isCompanionSurface(value) {
-  return typeof value === "string" && COMPANION_SURFACES.includes(value);
-}
-function isRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+  return null;
 }
-var KNOWN_NATIVE_HOSTS = {
-  "vscode-zam-companion": {
-    normalizedId: "vscode-companion",
-    label: "VS Code Companion"
-  }
-};
-function normalizeNativeHostIdentity(clientInfo, harnessOverride) {
-  if (harnessOverride) {
-    const known2 = KNOWN_NATIVE_HOSTS[harnessOverride];
-    return {
-      rawName: clientInfo?.name ?? harnessOverride,
-      version: clientInfo?.version,
-      normalizedId: known2?.normalizedId,
-      label: known2?.label ?? harnessOverride
-    };
+function inferApiFlavor(url) {
+  try {
+    return new URL(url).hostname.toLowerCase().endsWith("anthropic.com") ? "anthropic-messages" : "chat-completions";
+  } catch {
+    return "chat-completions";
   }
-  if (!clientInfo) return void 0;
-  const known = KNOWN_NATIVE_HOSTS[clientInfo.name];
-  return {
-    rawName: clientInfo.name,
-    version: clientInfo.version,
-    normalizedId: known?.normalizedId,
-    label: known?.label ?? clientInfo.name
-  };
-}
-function resolveCollapsedForSurface(state, surface) {
-  return state?.[surface] ?? false;
 }
-function parseCompanionContextReadRequest(value) {
-  if (!isRecord2(value) || !isCompanionSurface(value.surface)) {
-    throw new Error("Invalid companion context read request");
+async function readJsonSetting(db, key) {
+  const raw = await getSetting(db, key);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
   }
-  const rawClientInfo = value.clientInfo;
-  const clientInfo = isRecord2(rawClientInfo) && typeof rawClientInfo.name === "string" ? {
-    name: rawClientInfo.name,
-    version: typeof rawClientInfo.version === "string" ? rawClientInfo.version : void 0
-  } : void 0;
-  const harnessOverride = typeof value.harnessOverride === "string" ? value.harnessOverride : void 0;
-  return { surface: value.surface, clientInfo, harnessOverride };
 }
-function parseCompanionContextWriteRequest(value) {
-  if (!isRecord2(value) || !isCompanionSurface(value.surface)) {
-    throw new Error("Invalid companion context write request");
-  }
-  const userId = typeof value.userId === "string" ? value.userId : void 0;
-  let evaluatorId;
-  if (value.evaluatorId !== void 0) {
-    if (!isEvaluatorId(value.evaluatorId)) {
-      throw new Error(
-        `Unknown evaluator id in companion context write request: ${String(value.evaluatorId)}`
-      );
-    }
-    evaluatorId = value.evaluatorId;
-  }
-  const collapsed = typeof value.collapsed === "boolean" ? value.collapsed : void 0;
-  if (userId === void 0 && evaluatorId === void 0 && collapsed === void 0) {
-    throw new Error(
-      "Companion context write request must set userId, evaluatorId, and/or collapsed"
-    );
+function resolveProviderApiKey(rec) {
+  if (rec.apiKey) return rec.apiKey;
+  if (rec.apiKeyRef) {
+    const key = getProviderApiKey(rec.apiKeyRef);
+    if (key) return key;
   }
-  return { surface: value.surface, userId, evaluatorId, collapsed };
+  return DEFAULT_LLM_API_KEY;
 }
-function buildCompanionContext(input) {
-  const userSelection = resolveSelection(input.userSelection);
-  const evaluatorSelection = resolveSelection(input.evaluatorSelection);
-  const routes = buildEvaluatorRoutes(
-    input.evaluatorRouteInputs,
-    evaluatorSelection.value
-  );
-  let activeEvaluatorId;
-  let activeEvaluatorError;
-  try {
-    activateSelectedEvaluator(routes, evaluatorSelection.value);
-    activeEvaluatorId = evaluatorSelection.value;
-  } catch (error) {
-    if (error instanceof EvaluatorUnavailableError) {
-      activeEvaluatorError = error;
-    } else {
-      throw error;
-    }
-  }
-  const evaluators = activeEvaluatorId ? routes.map(
-    (route) => route.id === activeEvaluatorId ? { ...route, active: true } : route
-  ) : routes;
-  return {
-    read: {
-      surface: input.surface,
-      nativeHost: input.nativeHost,
-      user: {
-        currentId: userSelection.value,
-        persistedId: input.userSelection.persisted,
-        source: userSelection.source
-      },
-      profiles: input.profiles ?? [],
-      harnesses: input.harnesses,
-      evaluators,
-      selectedEvaluatorId: evaluatorSelection.value,
-      activeEvaluatorId,
-      collapsed: resolveCollapsedForSurface(input.collapsed, input.surface)
-    },
-    userSelection,
-    evaluatorSelection,
-    activeEvaluatorError
-  };
-}
-
-// src/cli/bridge-handlers.ts
-init_kernel();
-import { mkdirSync as mkdirSync9, writeFileSync as writeFileSync6 } from "fs";
-import { join as join13 } from "path";
-
-// src/cli/knowledge-contexts.ts
-init_kernel();
-async function resolveOperationKnowledgeContexts(db, requestedNames) {
-  const explicitNames = [
-    ...new Set(requestedNames.map((name) => name.trim()).filter(Boolean))
-  ];
-  const activeDefault = getActiveWorkspaceContext();
-  const selectedNames = explicitNames.length > 0 ? explicitNames : activeDefault ? [activeDefault] : [];
-  const contexts = [];
-  for (const name of selectedNames) {
-    const context = await getKnowledgeContextByName(db, name);
-    if (!context) {
-      const subject = explicitNames.length > 0 ? "Knowledge" : "Active knowledge";
-      throw new Error(`${subject} context not found: ${name}`);
-    }
-    contexts.push(context);
-  }
-  return contexts;
-}
-
-// src/cli/llm/client.ts
-init_kernel();
-import { spawn } from "child_process";
-import { existsSync as existsSync11, readFileSync as readFileSync9, statSync as statSync2 } from "fs";
-var DEFAULT_LLM_URL = "http://localhost:8000/v1";
-var DEFAULT_LLM_MAX_TOKENS = 1e4;
-var LOCAL_CURRICULUM_IMPORT_HARD_TIMEOUT_MS = 6e5;
-var CLOUD_CURRICULUM_IMPORT_HARD_TIMEOUT_MS = 18e4;
-var RECALL_QUESTION_MAX_OUTPUT_TOKENS = 400;
-var RECALL_EVALUATION_MAX_OUTPUT_TOKENS = 1200;
-var RECALL_DISCUSSION_MAX_OUTPUT_TOKENS = 1200;
-var RECALL_ENDPOINT_CACHE_MS = 6e4;
-var cachedRecallEndpoint = null;
-function recallEndpointSignature(cfg) {
-  return [
-    cfg.enabled ? "on" : "off",
-    cfg.providerName ?? "",
-    cfg.url,
-    cfg.model,
-    cfg.apiFlavor,
-    cfg.fallback?.url ?? "",
-    cfg.fallback?.model ?? ""
-  ].join("|");
-}
-var DEFAULT_LLM_MODEL = "qwen3.5:4b";
-var DEFAULT_LLM_API_KEY = "sk-none";
-async function getLlmConfig(db) {
-  return {
-    enabled: await getSetting(db, "llm.enabled") === "true",
-    url: await getSetting(db, "llm.url") || DEFAULT_LLM_URL,
-    model: await getSetting(db, "llm.model") || DEFAULT_LLM_MODEL,
-    apiKey: await getSetting(db, "llm.api_key") || DEFAULT_LLM_API_KEY,
-    locale: await getSetting(db, "system.locale") || "en"
-  };
-}
-function getCloudModelRecommendation(url) {
-  const lowercase = url.toLowerCase();
-  if (lowercase.includes("openrouter.ai")) {
-    return { model: "openrouter/free", flavor: "chat-completions" };
-  }
-  if (lowercase.includes("openai.com") || lowercase.includes("api.openai")) {
-    return { model: "gpt-5-mini", flavor: "chat-completions" };
-  }
-  if (lowercase.includes("googleapis.com") || lowercase.includes("google")) {
-    return { model: "gemini-3.5-flash", flavor: "chat-completions" };
-  }
-  if (lowercase.includes("deepseek.com")) {
-    return { model: "deepseek-v4-flash", flavor: "chat-completions" };
-  }
-  if (lowercase.includes("mimo")) {
-    return { model: "mimo-v2.5", flavor: "chat-completions" };
-  }
-  if (lowercase.includes("anthropic.com")) {
-    return {
-      model: "claude-haiku-4-5-20251001",
-      flavor: "anthropic-messages"
-    };
-  }
-  return null;
-}
-function inferApiFlavor(url) {
-  try {
-    return new URL(url).hostname.toLowerCase().endsWith("anthropic.com") ? "anthropic-messages" : "chat-completions";
-  } catch {
-    return "chat-completions";
-  }
-}
-async function readJsonSetting(db, key) {
-  const raw = await getSetting(db, key);
-  if (!raw) return null;
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-function resolveProviderApiKey(rec) {
-  if (rec.apiKey) return rec.apiKey;
-  if (rec.apiKeyRef) {
-    const key = getProviderApiKey(rec.apiKeyRef);
-    if (key) return key;
-  }
-  return DEFAULT_LLM_API_KEY;
-}
-var ROLE_TO_CAPABILITY2 = {
-  recall: "text",
-  text: "text",
-  vision: "image",
-  embedding: "embedding"
-};
 function materializeModelEntry(entry, base, enabled, maxFrames) {
   const url = entry.url || base.url;
   const cfg = {
@@ -7677,39 +7545,6 @@ async function getVisionConfig(db) {
     maxFrames: p.maxFrames
   };
 }
-var LANGUAGE_NAMES = {
-  en: "English",
-  de: "German",
-  es: "Spanish",
-  fr: "French",
-  pt: "Portuguese",
-  zh: "Chinese",
-  ja: "Japanese"
-};
-var LOCALIZED_RATING_PREFIX = {
-  en: "Suggested rating",
-  de: "Empfohlene Bewertung",
-  es: "Calificaci\xF3n sugerida",
-  fr: "Note sugg\xE9r\xE9e",
-  pt: "Avalia\xE7\xE3o sugerida",
-  zh: "\u5EFA\u8BAE\u8BC4\u5206",
-  ja: "\u63A8\u5968\u8A55\u4FA1"
-};
-var BLOOM_VERBS2 = {
-  1: "Remember",
-  2: "Understand",
-  3: "Apply",
-  4: "Analyze",
-  5: "Synthesize"
-};
-var LlmResponseTruncatedError = class extends Error {
-  constructor(label) {
-    super(
-      `${label}: the model's response was cut off before producing usable output (finish_reason=length). The prompt likely left no room in the model's context window for a reply.`
-    );
-    this.name = "LlmResponseTruncatedError";
-  }
-};
 async function readChatContent(res, label) {
   if (!res.ok) {
     const errorText = await res.text().catch(() => "");
@@ -7899,8 +7734,6 @@ ${input.sourceLinkContent}` : ""}`;
     providerName: endpoint.providerName
   };
 }
-var MAX_IMPORT_TEXT_CHARS = 2e5;
-var VALID_GENERATED_MODES = /* @__PURE__ */ new Set(["shadowing", "copilot", "autonomy"]);
 function parseGeneratedCardArray(responseText, label, limits) {
   const startIdx = responseText.indexOf("[");
   const endIdx = responseText.lastIndexOf("]");
@@ -7962,7 +7795,6 @@ function parseGeneratedCardArray(responseText, label, limits) {
     };
   });
 }
-var CURRICULUM_CHUNK_TEXT_CHARS = 3e3;
 function splitCurriculumText(text, maxChars) {
   if (text.length <= maxChars) return [text];
   const chunks = [];
@@ -8438,6 +8270,33 @@ async function resolveUsableRecallEndpoint(db) {
   };
   return selected.endpoint;
 }
+async function sampleViaLocalLLM(db, messages) {
+  const cfg = await getProviderForRole(db, "recall");
+  const endpoint = await resolveUsableRecallEndpoint(db);
+  const res = await fetchWithInteractiveTimeout(
+    `${endpoint.url}/chat/completions`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${endpoint.apiKey}`
+      },
+      body: JSON.stringify({
+        model: endpoint.model,
+        messages,
+        temperature: 0.3,
+        max_tokens: RECALL_DISCUSSION_MAX_OUTPUT_TOKENS
+      }),
+      locale: cfg.locale
+    }
+  );
+  const text = await readChatContent(res, "LLM sampling");
+  return {
+    text,
+    model: endpoint.model,
+    providerName: endpoint.providerName
+  };
+}
 async function resolveUsableTextEndpoint(db) {
   const cfg = await getProviderForRole(db, "text");
   if (!cfg.enabled) {
@@ -8493,7 +8352,7 @@ async function prepareRecallChain(db, opts) {
       } else {
         spawnLocalRunner(endpoint.url, endpoint.model, endpoint.runner);
         while (Date.now() < deadline) {
-          await new Promise((resolve7) => setTimeout(resolve7, 1e3));
+          await new Promise((resolve8) => setTimeout(resolve8, 1e3));
           if (await isLlmOnline(endpoint.url)) {
             online = true;
             break;
@@ -8786,7 +8645,7 @@ async function startLocalRunner(url, model, locale, hint) {
   let attempts = 0;
   const dotsPerLine = 30;
   while (true) {
-    await new Promise((resolve7) => setTimeout(resolve7, 500));
+    await new Promise((resolve8) => setTimeout(resolve8, 500));
     if (await isLlmOnline(url)) {
       if (attempts > 0) process.stdout.write("\n");
       return true;
@@ -8810,123 +8669,833 @@ async function startLocalRunner(url, model, locale, hint) {
     }
   }
 }
+async function ensureLocalLlmRunning(db) {
+  const result = await prepareRecallChain(db, {
+    timeoutMs: 25e3,
+    interactive: true
+  });
+  if (result.usable) {
+    const location = result.local ? "local" : "cloud";
+    console.log(
+      `\x1B[32m\u2713 Recall LLM ready (${location}: ${result.model}).\x1B[0m`
+    );
+    return { usable: true };
+  }
+  if (result.reason === "unsupported-provider") {
+    console.warn(
+      `\x1B[31m\u2717 Recall provider is not supported for active recall.\x1B[0m`
+    );
+  } else if (result.reason === "model-not-found") {
+    console.warn(
+      `\x1B[31m\u2717 Configured model "${result.model}" is not available on the server.\x1B[0m`
+    );
+    console.warn(`  Available models: ${result.availableModels.join(", ")}`);
+  } else if (result.reason === "offline") {
+    console.warn(
+      `\x1B[33m\u26A0 No recall LLM endpoint is reachable. Continuing without AI coaching.\x1B[0m
+`
+    );
+  }
+  return { usable: false, reason: result.reason };
+}
 async function ensureLlmReadyHeadless(db, opts = {}) {
   return prepareRecallChain(db, {
     timeoutMs: opts.timeoutMs ?? 25e3,
     interactive: false
   });
 }
-async function fetchWithInteractiveTimeout(url, options = {}) {
-  const {
-    timeoutMs = 2e4,
-    hardTimeoutMs = 12e4,
-    locale = "en",
-    ...fetchOptions
-  } = options;
-  const controller = new AbortController();
-  const fetchPromise = fetch(url, {
-    ...fetchOptions,
-    signal: controller.signal
-  });
-  if (!process.stdout.isTTY || process.env.ZAM_BRIDGE === "true") {
-    let timeoutId;
-    const hardTimeout = new Promise((_resolve, reject) => {
-      timeoutId = setTimeout(() => {
-        reject(new Error(`LLM request timed out after ${hardTimeoutMs}ms`));
-        controller.abort();
-      }, hardTimeoutMs);
-    });
-    try {
-      return await Promise.race([fetchPromise, hardTimeout]);
-    } finally {
-      clearTimeout(timeoutId);
-    }
+async function fetchWithInteractiveTimeout(url, options = {}) {
+  const {
+    timeoutMs = 2e4,
+    hardTimeoutMs = 12e4,
+    locale = "en",
+    ...fetchOptions
+  } = options;
+  const controller = new AbortController();
+  const fetchPromise = fetch(url, {
+    ...fetchOptions,
+    signal: controller.signal
+  });
+  if (!process.stdout.isTTY || process.env.ZAM_BRIDGE === "true") {
+    let timeoutId;
+    const hardTimeout = new Promise((_resolve, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(new Error(`LLM request timed out after ${hardTimeoutMs}ms`));
+        controller.abort();
+      }, hardTimeoutMs);
+    });
+    try {
+      return await Promise.race([fetchPromise, hardTimeout]);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  let attempts = 0;
+  const dotsPerLine = 30;
+  while (true) {
+    let timeoutId;
+    const timeoutPromise = new Promise((resolve8) => {
+      timeoutId = setTimeout(() => resolve8("timeout"), timeoutMs);
+    });
+    const dotsInterval = setInterval(() => {
+      process.stdout.write(".");
+      attempts++;
+      if (attempts % dotsPerLine === 0) process.stdout.write("\n");
+    }, 500);
+    try {
+      const result = await Promise.race([fetchPromise, timeoutPromise]);
+      clearInterval(dotsInterval);
+      clearTimeout(timeoutId);
+      if (result !== "timeout") {
+        if (attempts > 0) process.stdout.write("\n");
+        return result;
+      }
+      console.log(`
+\x1B[33m${t(locale, "local_ai_working")}\x1B[0m`);
+      const { confirm } = await import("@inquirer/prompts");
+      const keepWaiting = await confirm({
+        message: t(locale, "keep_waiting"),
+        default: true
+      }).catch(() => false);
+      if (!keepWaiting) {
+        controller.abort();
+        console.log(`\x1B[33m${t(locale, "proceeding_offline")}\x1B[0m
+`);
+        throw new Error("User cancelled waiting for slow LLM response");
+      }
+      attempts = 0;
+    } catch (err) {
+      clearInterval(dotsInterval);
+      clearTimeout(timeoutId);
+      if (attempts > 0) process.stdout.write("\n");
+      throw err;
+    }
+  }
+}
+async function ensureHighQualityQuestion(db, token) {
+  const { enabled } = await getLlmConfig(db);
+  const variationEnabled = await getSetting(db, "llm.dynamic_questions") !== "false";
+  if (enabled && variationEnabled) {
+    try {
+      let sourceLinkContent = null;
+      if (token.sourceLink) {
+        const resolved = await resolveReviewContext(token.sourceLink).catch(
+          () => null
+        );
+        if (resolved) {
+          sourceLinkContent = resolved.content;
+        }
+      }
+      const generated = await generateQuestionViaLLM(db, {
+        slug: token.slug,
+        concept: token.concept,
+        domain: token.domain,
+        bloomLevel: token.bloomLevel,
+        sourceLinkContent,
+        existingQuestion: token.question
+      });
+      if (generated.text.trim().length > 0) {
+        return {
+          question: generated.text,
+          source: "llm",
+          model: generated.model
+        };
+      }
+    } catch {
+    }
+  }
+  if (token.question && token.question.trim().length > 0) {
+    return {
+      question: token.question.trim(),
+      source: "original"
+    };
+  }
+  return null;
+}
+async function generateTitleViaLLM(db, input, opts = {}) {
+  const cfg = await getProviderForRole(db, "text");
+  let locale = cfg.locale;
+  const contextName = opts.knowledgeContext || getActiveWorkspaceContext();
+  if (contextName) {
+    const context = await getKnowledgeContextByName(db, contextName);
+    if (context?.language) {
+      locale = normalizeLocale(context.language);
+    }
+  }
+  const endpoint = await resolveUsableTextEndpoint(db);
+  const systemPrompt = `You are an expert at naming knowledge items for a personal knowledge graph.
+Your task: given a knowledge token's concept (the full reference answer), question, domain, and optional context, produce a short, descriptive, human-friendly TITLE.
+
+Strict rules from the project ADR:
+- Concise name for the concept (\u2264 80 chars ideal).
+- Thoughtful, memorable name \u2014 NOT a definition or the first sentence of the concept.
+- NEVER echo the domain name (e.g. do not say "Workflow Engine Node Drain" if domain is "workflow-engine"; just "Node Drain Protection").
+- Prefer a name over spoiling the full concept.
+- Support Unicode (umlauts, etc.).
+- Output the title in the same language as the concept/content (e.g., German if the concept is German, English if the concept is English).
+- Output ONLY the raw title text. No preamble, quotes, explanations, or markdown.
+
+Example good titles:
+- "RAG Retrieval Quality Evaluation" (for RAG failure modes focused on retrieval)
+- "Pythagorean Theorem Converse Proof"
+- "macOS Applications Directory Layout"
+- "Chronotype Sleep Preference"`;
+  const userPrompt = `Domain: ${input.domain}
+Slug: ${input.slug}
+Question: ${input.question || "(none)"}
+Concept: ${input.concept}
+Context: ${input.context || "(none)"}
+
+Title:`;
+  const url = `${endpoint.url}/chat/completions`;
+  const apiKey = endpoint.apiKey;
+  const model = endpoint.model;
+  try {
+    const res = await fetchWithInteractiveTimeout(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`
+      },
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt }
+        ],
+        temperature: 0.2,
+        max_tokens: 100
+      }),
+      locale,
+      timeoutMs: opts.timeoutMs,
+      hardTimeoutMs: opts.timeoutMs
+    });
+    const text = await readChatContent(res, "title generation");
+    return {
+      text: text.trim(),
+      model,
+      providerName: endpoint.providerName
+    };
+  } catch (_e) {
+    return {
+      text: input.concept.split(/[.;]/)[0].trim().substring(0, 80),
+      model: "fallback",
+      providerName: "heuristic"
+    };
+  }
+}
+async function repairUmlautsViaLLM(db, input, opts = {}) {
+  const cfg = await getProviderForRole(db, "text");
+  const endpoint = await resolveUsableTextEndpoint(db);
+  const systemPrompt = `You are an expert editor specializing in German language orthography.
+Your task: given a text that may contain legacy ASCII-folded German umlauts (like 'ue' instead of '\xFC', 'ae' instead of '\xE4', 'oe' instead of '\xF6', 'Ue' instead of '\xDC', etc.), repair them back to proper German umlauts (\xE4, \xF6, \xFC, \xC4, \xD6, \xDC, \xDF) where appropriate.
+
+Strict rules:
+- ONLY change character sequences that are clearly meant to be German umlauts (e.g. change "Ueber" to "\xDCber", "fuer" to "f\xFCr", "moeglich" to "m\xF6glich").
+- DO NOT change words that are correct in their current form (e.g. do NOT change "nahe" to "n\xE4he", do NOT change English words or technical terms, do NOT change names like "Ueda").
+- Output ONLY the repaired text. No preamble, no explanation, no markdown formatting.`;
+  const userPrompt = `Text to repair:
+"""
+${input.text}
+"""
+
+Repaired text:`;
+  const url = `${endpoint.url}/chat/completions`;
+  const apiKey = endpoint.apiKey;
+  const model = endpoint.model;
+  try {
+    const res = await fetchWithInteractiveTimeout(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`
+      },
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt }
+        ],
+        temperature: 0.1
+      }),
+      locale: cfg.locale,
+      timeoutMs: opts.timeoutMs,
+      hardTimeoutMs: opts.timeoutMs
+    });
+    const text = await readChatContent(res, "umlaut repair");
+    return text.trim();
+  } catch (_e) {
+    return input.text;
+  }
+}
+var DEFAULT_LLM_URL, DEFAULT_LLM_MAX_TOKENS, LOCAL_CURRICULUM_IMPORT_HARD_TIMEOUT_MS, CLOUD_CURRICULUM_IMPORT_HARD_TIMEOUT_MS, RECALL_QUESTION_MAX_OUTPUT_TOKENS, RECALL_EVALUATION_MAX_OUTPUT_TOKENS, RECALL_DISCUSSION_MAX_OUTPUT_TOKENS, RECALL_ENDPOINT_CACHE_MS, cachedRecallEndpoint, DEFAULT_LLM_MODEL, DEFAULT_LLM_API_KEY, ROLE_TO_CAPABILITY2, LANGUAGE_NAMES, LOCALIZED_RATING_PREFIX, BLOOM_VERBS2, LlmResponseTruncatedError, MAX_IMPORT_TEXT_CHARS, VALID_GENERATED_MODES, CURRICULUM_CHUNK_TEXT_CHARS;
+var init_client = __esm({
+  "src/cli/llm/client.ts"() {
+    "use strict";
+    init_kernel();
+    DEFAULT_LLM_URL = "http://localhost:8000/v1";
+    DEFAULT_LLM_MAX_TOKENS = 1e4;
+    LOCAL_CURRICULUM_IMPORT_HARD_TIMEOUT_MS = 6e5;
+    CLOUD_CURRICULUM_IMPORT_HARD_TIMEOUT_MS = 18e4;
+    RECALL_QUESTION_MAX_OUTPUT_TOKENS = 400;
+    RECALL_EVALUATION_MAX_OUTPUT_TOKENS = 1200;
+    RECALL_DISCUSSION_MAX_OUTPUT_TOKENS = 1200;
+    RECALL_ENDPOINT_CACHE_MS = 6e4;
+    cachedRecallEndpoint = null;
+    DEFAULT_LLM_MODEL = "qwen3.5:4b";
+    DEFAULT_LLM_API_KEY = "sk-none";
+    ROLE_TO_CAPABILITY2 = {
+      recall: "text",
+      text: "text",
+      vision: "image",
+      embedding: "embedding"
+    };
+    LANGUAGE_NAMES = {
+      en: "English",
+      de: "German",
+      es: "Spanish",
+      fr: "French",
+      pt: "Portuguese",
+      zh: "Chinese",
+      ja: "Japanese"
+    };
+    LOCALIZED_RATING_PREFIX = {
+      en: "Suggested rating",
+      de: "Empfohlene Bewertung",
+      es: "Calificaci\xF3n sugerida",
+      fr: "Note sugg\xE9r\xE9e",
+      pt: "Avalia\xE7\xE3o sugerida",
+      zh: "\u5EFA\u8BAE\u8BC4\u5206",
+      ja: "\u63A8\u5968\u8A55\u4FA1"
+    };
+    BLOOM_VERBS2 = {
+      1: "Remember",
+      2: "Understand",
+      3: "Apply",
+      4: "Analyze",
+      5: "Synthesize"
+    };
+    LlmResponseTruncatedError = class extends Error {
+      constructor(label) {
+        super(
+          `${label}: the model's response was cut off before producing usable output (finish_reason=length). The prompt likely left no room in the model's context window for a reply.`
+        );
+        this.name = "LlmResponseTruncatedError";
+      }
+    };
+    MAX_IMPORT_TEXT_CHARS = 2e5;
+    VALID_GENERATED_MODES = /* @__PURE__ */ new Set(["shadowing", "copilot", "autonomy"]);
+    CURRICULUM_CHUNK_TEXT_CHARS = 3e3;
+  }
+});
+
+// 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,
+  loadBundle: () => loadBundle,
+  resolveArticlePath: () => resolveArticlePath,
+  upsertArticle: () => upsertArticle
+});
+import { mkdirSync as mkdirSync16, readdirSync as readdirSync3, readFileSync as readFileSync18, writeFileSync as writeFileSync13 } from "fs";
+import { join as join24, resolve as resolve7 } from "path";
+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 join24(resolve7(dir), file);
+}
+function loadBundle(dir) {
+  const root = resolve7(dir);
+  let entries;
+  try {
+    entries = readdirSync3(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: readFileSync18(join24(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 = resolve7(dir);
+  mkdirSync16(root, { recursive: true });
+  let created = true;
+  try {
+    readFileSync18(target, "utf8");
+    created = false;
+  } catch {
+  }
+  writeFileSync13(target, markdown, "utf8");
+  const bundle = loadBundle(root);
+  writeFileSync13(join24(root, "index.md"), renderIndex(bundle.catalog), "utf8");
+  let log = "";
+  try {
+    log = readFileSync18(join24(root, "log.md"), "utf8");
+  } catch {
+  }
+  const entry = bundle.catalog.find((e) => e.file === file);
+  writeFileSync13(
+    join24(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/commands/mcp.ts
+init_kernel();
+import { existsSync as existsSync21, readFileSync as readFileSync19 } from "fs";
+import { dirname as dirname11, join as join25 } from "path";
+import { fileURLToPath as fileURLToPath6 } from "url";
+import {
+  RESOURCE_MIME_TYPE,
+  registerAppResource,
+  registerAppTool
+} from "@modelcontextprotocol/ext-apps/server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// src/vscode-extension/companion-evaluator.ts
+var ROUTABLE_EVALUATOR_IDS = [
+  "native-mcp-host",
+  "vscode-lm",
+  "zam-text-model",
+  "quick-mode"
+];
+var DETACHED_HARNESS_EVALUATOR_IDS = [
+  "claude-code",
+  "codex",
+  "opencode",
+  "goose"
+];
+function isEvaluatorId(value) {
+  return typeof value === "string" && (ROUTABLE_EVALUATOR_IDS.includes(value) || DETACHED_HARNESS_EVALUATOR_IDS.includes(value));
+}
+function buildEvaluatorRoutes(inputs, selectedId) {
+  return inputs.map((input) => {
+    if (!input.routable && !input.reason) {
+      throw new Error(
+        `Unroutable evaluator "${input.id}" must carry an availability reason`
+      );
+    }
+    return { ...input, selected: input.id === selectedId, active: false };
+  });
+}
+var EvaluatorUnavailableError = class extends Error {
+  evaluatorId;
+  constructor(evaluatorId, reason) {
+    super(`Evaluator "${evaluatorId}" is unavailable: ${reason}`);
+    this.name = "EvaluatorUnavailableError";
+    this.evaluatorId = evaluatorId;
+  }
+};
+function activateSelectedEvaluator(routes, selectedId) {
+  const route = routes.find((candidate) => candidate.id === selectedId);
+  if (!route) {
+    throw new EvaluatorUnavailableError(selectedId, "not configured");
+  }
+  if (!route.routable) {
+    throw new EvaluatorUnavailableError(
+      selectedId,
+      route.reason ?? "not routable on this surface"
+    );
+  }
+  return { ...route, active: true };
+}
+
+// src/vscode-extension/companion-selection.ts
+function resolveSelection(candidates) {
+  if (candidates.invocation !== void 0) {
+    return {
+      value: candidates.invocation,
+      source: "invocation",
+      sessionScoped: true
+    };
+  }
+  if (candidates.manual !== void 0) {
+    return { value: candidates.manual, source: "manual", sessionScoped: false };
+  }
+  if (candidates.persisted !== void 0) {
+    return {
+      value: candidates.persisted,
+      source: "persisted",
+      sessionScoped: false
+    };
+  }
+  return {
+    value: candidates.fallback,
+    source: "default",
+    sessionScoped: false
+  };
+}
+function isPersistableSelection(result) {
+  return result.source === "manual";
+}
+
+// src/vscode-extension/companion-context.ts
+var COMPANION_SURFACES = [
+  "recall",
+  "graph",
+  "settings",
+  "studio"
+];
+function isCompanionSurface(value) {
+  return typeof value === "string" && COMPANION_SURFACES.includes(value);
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var KNOWN_NATIVE_HOSTS = {
+  "vscode-zam-companion": {
+    normalizedId: "vscode-companion",
+    label: "VS Code Companion"
+  },
+  "antigravity-zam-companion": {
+    normalizedId: "antigravity-companion",
+    label: "Antigravity Companion"
+  }
+};
+function normalizeNativeHostIdentity(clientInfo, harnessOverride) {
+  if (harnessOverride) {
+    const known2 = KNOWN_NATIVE_HOSTS[harnessOverride];
+    return {
+      rawName: clientInfo?.name ?? harnessOverride,
+      version: clientInfo?.version,
+      normalizedId: known2?.normalizedId,
+      label: known2?.label ?? harnessOverride
+    };
+  }
+  if (!clientInfo) return void 0;
+  const known = KNOWN_NATIVE_HOSTS[clientInfo.name];
+  return {
+    rawName: clientInfo.name,
+    version: clientInfo.version,
+    normalizedId: known?.normalizedId,
+    label: known?.label ?? clientInfo.name
+  };
+}
+function resolveCollapsedForSurface(state, surface) {
+  return state?.[surface] ?? false;
+}
+function parseCompanionContextReadRequest(value) {
+  if (!isRecord2(value) || !isCompanionSurface(value.surface)) {
+    throw new Error("Invalid companion context read request");
+  }
+  const rawClientInfo = value.clientInfo;
+  const clientInfo = isRecord2(rawClientInfo) && typeof rawClientInfo.name === "string" ? {
+    name: rawClientInfo.name,
+    version: typeof rawClientInfo.version === "string" ? rawClientInfo.version : void 0
+  } : void 0;
+  const harnessOverride = typeof value.harnessOverride === "string" ? value.harnessOverride : void 0;
+  return { surface: value.surface, clientInfo, harnessOverride };
+}
+function parseCompanionContextWriteRequest(value) {
+  if (!isRecord2(value) || !isCompanionSurface(value.surface)) {
+    throw new Error("Invalid companion context write request");
   }
-  let attempts = 0;
-  const dotsPerLine = 30;
-  while (true) {
-    let timeoutId;
-    const timeoutPromise = new Promise((resolve7) => {
-      timeoutId = setTimeout(() => resolve7("timeout"), timeoutMs);
-    });
-    const dotsInterval = setInterval(() => {
-      process.stdout.write(".");
-      attempts++;
-      if (attempts % dotsPerLine === 0) process.stdout.write("\n");
-    }, 500);
-    try {
-      const result = await Promise.race([fetchPromise, timeoutPromise]);
-      clearInterval(dotsInterval);
-      clearTimeout(timeoutId);
-      if (result !== "timeout") {
-        if (attempts > 0) process.stdout.write("\n");
-        return result;
-      }
-      console.log(`
-\x1B[33m${t(locale, "local_ai_working")}\x1B[0m`);
-      const { confirm } = await import("@inquirer/prompts");
-      const keepWaiting = await confirm({
-        message: t(locale, "keep_waiting"),
-        default: true
-      }).catch(() => false);
-      if (!keepWaiting) {
-        controller.abort();
-        console.log(`\x1B[33m${t(locale, "proceeding_offline")}\x1B[0m
-`);
-        throw new Error("User cancelled waiting for slow LLM response");
-      }
-      attempts = 0;
-    } catch (err) {
-      clearInterval(dotsInterval);
-      clearTimeout(timeoutId);
-      if (attempts > 0) process.stdout.write("\n");
-      throw err;
+  const userId = typeof value.userId === "string" ? value.userId : void 0;
+  let evaluatorId;
+  if (value.evaluatorId !== void 0) {
+    if (!isEvaluatorId(value.evaluatorId)) {
+      throw new Error(
+        `Unknown evaluator id in companion context write request: ${String(value.evaluatorId)}`
+      );
     }
+    evaluatorId = value.evaluatorId;
+  }
+  const collapsed = typeof value.collapsed === "boolean" ? value.collapsed : void 0;
+  if (userId === void 0 && evaluatorId === void 0 && collapsed === void 0) {
+    throw new Error(
+      "Companion context write request must set userId, evaluatorId, and/or collapsed"
+    );
   }
+  return { surface: value.surface, userId, evaluatorId, collapsed };
 }
-async function ensureHighQualityQuestion(db, token) {
-  const { enabled } = await getLlmConfig(db);
-  const variationEnabled = await getSetting(db, "llm.dynamic_questions") !== "false";
-  if (enabled && variationEnabled) {
-    try {
-      let sourceLinkContent = null;
-      if (token.sourceLink) {
-        const resolved = await resolveReviewContext(token.sourceLink).catch(
-          () => null
-        );
-        if (resolved) {
-          sourceLinkContent = resolved.content;
-        }
-      }
-      const generated = await generateQuestionViaLLM(db, {
-        slug: token.slug,
-        concept: token.concept,
-        domain: token.domain,
-        bloomLevel: token.bloomLevel,
-        sourceLinkContent,
-        existingQuestion: token.question
-      });
-      if (generated.text.trim().length > 0) {
-        return {
-          question: generated.text,
-          source: "llm",
-          model: generated.model
-        };
-      }
-    } catch {
+function buildCompanionContext(input) {
+  const userSelection = resolveSelection(input.userSelection);
+  const evaluatorSelection = resolveSelection(input.evaluatorSelection);
+  const routes = buildEvaluatorRoutes(
+    input.evaluatorRouteInputs,
+    evaluatorSelection.value
+  );
+  let activeEvaluatorId;
+  let activeEvaluatorError;
+  try {
+    activateSelectedEvaluator(routes, evaluatorSelection.value);
+    activeEvaluatorId = evaluatorSelection.value;
+  } catch (error) {
+    if (error instanceof EvaluatorUnavailableError) {
+      activeEvaluatorError = error;
+    } else {
+      throw error;
     }
   }
-  if (token.question && token.question.trim().length > 0) {
-    return {
-      question: token.question.trim(),
-      source: "original"
-    };
+  const evaluators = activeEvaluatorId ? routes.map(
+    (route) => route.id === activeEvaluatorId ? { ...route, active: true } : route
+  ) : routes;
+  return {
+    read: {
+      surface: input.surface,
+      nativeHost: input.nativeHost,
+      user: {
+        currentId: userSelection.value,
+        persistedId: input.userSelection.persisted,
+        source: userSelection.source
+      },
+      profiles: input.profiles ?? [],
+      harnesses: input.harnesses,
+      evaluators,
+      selectedEvaluatorId: evaluatorSelection.value,
+      activeEvaluatorId,
+      collapsed: resolveCollapsedForSurface(input.collapsed, input.surface)
+    },
+    userSelection,
+    evaluatorSelection,
+    activeEvaluatorError
+  };
+}
+
+// src/cli/bridge-handlers.ts
+init_kernel();
+import { mkdirSync as mkdirSync9, writeFileSync as writeFileSync6 } from "fs";
+import { join as join13 } from "path";
+
+// src/cli/knowledge-contexts.ts
+init_kernel();
+async function resolveOperationKnowledgeContexts(db, requestedNames) {
+  const explicitNames = [
+    ...new Set(requestedNames.map((name) => name.trim()).filter(Boolean))
+  ];
+  const activeDefault = getActiveWorkspaceContext();
+  const selectedNames = explicitNames.length > 0 ? explicitNames : activeDefault ? [activeDefault] : [];
+  const contexts = [];
+  for (const name of selectedNames) {
+    const context = await getKnowledgeContextByName(db, name);
+    if (!context) {
+      const subject = explicitNames.length > 0 ? "Knowledge" : "Active knowledge";
+      throw new Error(`${subject} context not found: ${name}`);
+    }
+    contexts.push(context);
   }
-  return null;
+  return contexts;
 }
 
+// src/cli/bridge-handlers.ts
+init_client();
+
 // src/cli/llm/embedder.ts
 init_kernel();
+init_client();
 var CANONICAL_EMBEDDING_MODEL_ID = "embeddinggemma-300m";
 var EMBEDDINGGEMMA_ALIASES = /* @__PURE__ */ new Set([
   "embeddinggemma",
@@ -11254,6 +11823,7 @@ import { Command } from "commander";
 import { ulid as ulid10 } from "ulid";
 
 // src/cli/adapters/source-reader.ts
+init_client();
 import dns from "dns";
 import fs from "fs";
 var MAX_SOURCE_BYTES = 2 * 1024 * 1024;
@@ -11328,7 +11898,7 @@ async function readWebLink(url) {
         redirect: "manual",
         signal: controller.signal,
         headers: {
-          "User-Agent": "ZAM-Content-Studio/0.10.11"
+          "User-Agent": "ZAM-Content-Studio/0.12.0"
         }
       });
       if (res.status >= 300 && res.status < 400) {
@@ -28491,6 +29061,7 @@ function performInstallRepair(opts = {}, deps = {}) {
 
 // src/cli/llm/capability-probe.ts
 init_kernel();
+init_client();
 var EMBEDDING_MODEL_HINTS = [
   "embed",
   "text-embedding",
@@ -28610,8 +29181,12 @@ function validateModelSave(entry, probe, now = () => (/* @__PURE__ */ new Date()
   };
 }
 
+// src/cli/commands/bridge.ts
+init_client();
+
 // src/cli/llm/vision.ts
 init_kernel();
+init_client();
 import { randomBytes } from "crypto";
 import { readFileSync as readFileSync16 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
@@ -28651,25 +29226,25 @@ async function observeUiSnapshotViaLLM(db, input) {
   const imageUrls = [];
   const isVideo = /\.(mp4|mov|m4v|avi|mkv|webm)$/i.test(input.imagePath);
   if (isVideo) {
-    const { mkdirSync: mkdirSync16, readdirSync: readdirSync3, rmSync: rmSync4 } = await import("fs");
+    const { mkdirSync: mkdirSync17, readdirSync: readdirSync4, rmSync: rmSync4 } = await import("fs");
     const { execSync: execSync5 } = await import("child_process");
     const tempDir = join20(
       tmpdir2(),
       `zam-frames-${randomBytes(4).toString("hex")}`
     );
-    mkdirSync16(tempDir, { recursive: true });
+    mkdirSync17(tempDir, { recursive: true });
     try {
       execSync5(
         `ffmpeg -i "${input.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) {
         execSync5(
           `ffmpeg -i "${input.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;
@@ -29062,6 +29637,7 @@ async function withOptionalDb(fn, onError = defaultErrorHandler) {
 }
 
 // src/cli/providers/config.ts
+init_client();
 var VALID_API_FLAVORS = [
   "chat-completions",
   "anthropic-messages"
@@ -30487,7 +31063,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
   const statePath = join22(tmpdir3(), `zam-recording-${sessionId}.json`);
   const defaultExt = platform === "win32" ? ".mkv" : ".mov";
   const outputPath = opts.output ?? join22(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
-  const { existsSync: existsSync22, writeFileSync: writeFileSync13, openSync, closeSync } = await import("fs");
+  const { existsSync: existsSync22, writeFileSync: writeFileSync14, openSync, closeSync } = await import("fs");
   if (existsSync22(statePath)) {
     jsonOut({
       sessionId,
@@ -30542,7 +31118,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
   }
   child.unref();
   if (child.pid) {
-    writeFileSync13(
+    writeFileSync14(
       statePath,
       JSON.stringify({
         pid: child.pid,
@@ -30579,7 +31155,7 @@ bridgeCommand.command("stop-recording").description(
   }
   const sessionId = opts.session;
   const statePath = join22(tmpdir3(), `zam-recording-${sessionId}.json`);
-  const { existsSync: existsSync22, readFileSync: readFileSync19, rmSync: rmSync4 } = await import("fs");
+  const { existsSync: existsSync22, readFileSync: readFileSync20, rmSync: rmSync4 } = await import("fs");
   if (!existsSync22(statePath)) {
     jsonOut({
       sessionId,
@@ -30588,7 +31164,7 @@ bridgeCommand.command("stop-recording").description(
     });
     return;
   }
-  const state = JSON.parse(readFileSync19(statePath, "utf8"));
+  const state = JSON.parse(readFileSync20(statePath, "utf8"));
   const { pid, outputPath } = state;
   try {
     process.kill(pid, "SIGINT");
@@ -30604,7 +31180,7 @@ bridgeCommand.command("stop-recording").description(
   };
   let attempts = 0;
   while (isProcessRunning(pid) && attempts < 20) {
-    await new Promise((resolve7) => setTimeout(resolve7, 250));
+    await new Promise((resolve8) => setTimeout(resolve8, 250));
     attempts++;
   }
   if (isProcessRunning(pid)) {
@@ -33020,7 +33596,7 @@ function buildEvaluatorRouteInputs(harnessReport, nativeHost, clientSamplingCapa
   const detachedStatusById = new Map(
     harnessReport.harnesses.map((harness) => [harness.harness, harness])
   );
-  const isVscodeCompanion = nativeHost?.normalizedId === "vscode-companion";
+  const isVscodeCompanion = nativeHost?.normalizedId === "vscode-companion" || nativeHost?.normalizedId === "antigravity-companion";
   const nativeHostRoutable = !isVscodeCompanion && clientSamplingCapable;
   const inputs = [
     {
@@ -33040,8 +33616,14 @@ function buildEvaluatorRouteInputs(harnessReport, nativeHost, clientSamplingCapa
       id: "vscode-lm",
       displayIdentity: { provider: "VS Code language models" },
       configured: true,
-      routable: isVscodeCompanion,
-      reason: isVscodeCompanion ? void 0 : "VS Code language-model routing is only available from the VS Code Companion extension."
+      routable: nativeHost?.normalizedId === "vscode-companion",
+      reason: nativeHost?.normalizedId === "vscode-companion" ? void 0 : nativeHost?.normalizedId === "antigravity-companion" ? "Antigravity IDE does not support the VS Code language model API (vscode.lm)." : "VS Code language-model routing is only available from the VS Code Companion extension."
+    },
+    {
+      id: "zam-text-model",
+      displayIdentity: { provider: "ZAM text model" },
+      configured: true,
+      routable: true
     }
   ];
   for (const id of DETACHED_HARNESS_EVALUATOR_IDS) {
@@ -33067,9 +33649,11 @@ function toCompanionCollapsedState(raw) {
 async function assembleCompanionContext(db, input) {
   const companionConfig = getMachineCompanionConfig(input.configPath);
   const persistedUserId = companionConfig.selectedUserId;
+  const isAntigravity = input.nativeHost?.normalizedId === "antigravity-companion";
+  const persistedEvaluatorIdRaw = isAntigravity ? companionConfig.selectedAntigravityEvaluatorId ?? companionConfig.selectedEvaluatorId : companionConfig.selectedVscodeEvaluatorId ?? companionConfig.selectedEvaluatorId;
   const persistedEvaluatorId = isEvaluatorId(
-    companionConfig.selectedEvaluatorId
-  ) ? companionConfig.selectedEvaluatorId : void 0;
+    persistedEvaluatorIdRaw
+  ) ? persistedEvaluatorIdRaw : void 0;
   const collapsedRaw = companionConfig.collapsed ?? {};
   const harnessReport = getHarnessReportCached();
   const clientSamplingCapable = input.clientSamplingCapable ?? false;
@@ -33081,7 +33665,7 @@ async function assembleCompanionContext(db, input) {
   ]);
   const fallbackUserId = fallbackUserIdRaw ?? void 0;
   const quickModeSettingIsOn = quickModeRaw === "true";
-  const defaultEvaluatorId = quickModeSettingIsOn ? "quick-mode" : isVscodeCompanion ? "vscode-lm" : clientSamplingCapable ? "native-mcp-host" : "quick-mode";
+  const defaultEvaluatorId = quickModeSettingIsOn ? "quick-mode" : isAntigravity ? "zam-text-model" : isVscodeCompanion ? "vscode-lm" : clientSamplingCapable ? "native-mcp-host" : "quick-mode";
   const { read } = buildCompanionContext({
     surface: input.surface,
     nativeHost: input.nativeHost,
@@ -33146,7 +33730,13 @@ async function writeCompanionContext(db, request, options = {}) {
       fallback: void 0
     });
     if (isPersistableSelection(selection) && selection.value) {
-      update.selectedEvaluatorId = selection.value;
+      const nativeHost = normalizeNativeHostIdentity(options.clientInfo);
+      const isAntigravity = nativeHost?.normalizedId === "antigravity-companion";
+      if (isAntigravity) {
+        update.selectedAntigravityEvaluatorId = selection.value;
+      } else {
+        update.selectedVscodeEvaluatorId = selection.value;
+      }
       reloadRequired = true;
     }
   }
@@ -33228,11 +33818,11 @@ async function publishUiIntent(app, input = {}, opts = {}) {
 
 // src/cli/commands/mcp.ts
 var __dirname = dirname11(fileURLToPath6(import.meta.url));
-var pkgPath = join24(__dirname, "..", "..", "package.json");
+var pkgPath = join25(__dirname, "..", "..", "package.json");
 if (!existsSync21(pkgPath)) {
-  pkgPath = join24(__dirname, "..", "..", "..", "package.json");
+  pkgPath = join25(__dirname, "..", "..", "..", "package.json");
 }
-var pkg = JSON.parse(readFileSync18(pkgPath, "utf-8"));
+var pkg = JSON.parse(readFileSync19(pkgPath, "utf-8"));
 var STUDIO_RESOURCE_URI = "ui://zam/studio";
 var RECALL_RESOURCE_URI = "ui://zam/recall";
 var GRAPH_RESOURCE_URI = "ui://zam/graph";
@@ -33259,13 +33849,13 @@ var STUDIO_BRIDGE_ALLOWED_COMMANDS = /* @__PURE__ */ new Set([
 function loadPanelHtml(fileName, placeholderTitle) {
   const candidates = [
     // dist/cli/commands/mcp.js → dist/ui/
-    join24(__dirname, "..", "..", "ui", fileName),
+    join25(__dirname, "..", "..", "ui", fileName),
     // src/cli/commands/mcp.ts via tsx → <repo>/dist/ui/
-    join24(__dirname, "..", "..", "..", "dist", "ui", fileName)
+    join25(__dirname, "..", "..", "..", "dist", "ui", fileName)
   ];
   for (const candidate of candidates) {
     if (existsSync21(candidate)) {
-      return readFileSync18(candidate, "utf-8");
+      return readFileSync19(candidate, "utf-8");
     }
   }
   return `<!doctype html>
@@ -34000,6 +34590,117 @@ function createMcpServer(db) {
       });
     })
   );
+  server.registerTool(
+    "zam_companion_sample",
+    {
+      description: "Perform LLM sampling via the server's configured LLM (fallback for companion when vscode-lm is empty)",
+      inputSchema: {
+        messages: z.array(
+          z.object({
+            role: z.enum(["user", "assistant"]),
+            text: z.string()
+          })
+        )
+      },
+      annotations: {
+        ...commonAnnotations
+      },
+      _meta: {
+        ui: { visibility: ["app"] }
+      }
+    },
+    wrapHandler(
+      async (params) => {
+        const { sampleViaLocalLLM: sampleViaLocalLLM2 } = await Promise.resolve().then(() => (init_client(), client_exports));
+        const messages = params.messages.map((m) => ({
+          role: m.role,
+          content: m.text
+        }));
+        return await sampleViaLocalLLM2(db, messages);
+      }
+    )
+  );
+  const okfBundleDirSchema = z.string().optional().describe("Bundle directory (default docs/okf under the server cwd)");
+  server.registerTool(
+    "zam_okf_catalog",
+    {
+      description: "List the OKF knowledge-base articles (type, title, description, tags, resource URL) plus conformance problems, if any",
+      inputSchema: {
+        bundle_dir: okfBundleDirSchema
+      },
+      annotations: {
+        ...commonAnnotations,
+        readOnlyHint: true
+      }
+    },
+    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);
+      return {
+        dir: bundle.dir,
+        articles: bundle.catalog,
+        problems: bundle.problems
+      };
+    })
+  );
+  server.registerTool(
+    "zam_okf_read",
+    {
+      description: "Read one OKF knowledge-base article: raw markdown plus parsed frontmatter",
+      inputSchema: {
+        bundle_dir: okfBundleDirSchema,
+        file: z.string().describe("Article file name, e.g. fsrs-scheduling.md")
+      },
+      annotations: {
+        ...commonAnnotations,
+        readOnlyHint: true
+      }
+    },
+    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 { parseFrontmatter: parseFrontmatter2 } = await Promise.resolve().then(() => (init_bundle(), bundle_exports));
+      const path = resolveArticlePath2(
+        params.bundle_dir ?? DEFAULT_BUNDLE_DIR2,
+        params.file
+      );
+      const markdown = readFileSync20(path, "utf8");
+      const { fields } = parseFrontmatter2(markdown);
+      return { file: params.file, frontmatter: fields, markdown };
+    })
+  );
+  server.registerTool(
+    "zam_okf_upsert",
+    {
+      description: "Create or update an OKF knowledge-base article through the validated write path: checks the frontmatter contract, regenerates index.md, and appends the log.md entry. Never edit bundle files directly.",
+      inputSchema: {
+        bundle_dir: okfBundleDirSchema,
+        file: z.string().describe(
+          "Kebab-case article file name ending in .md (permanent ID)"
+        ),
+        markdown: z.string().describe(
+          "Full article: --- frontmatter (type, title, description, tags, resource, timestamp) then the body"
+        )
+      },
+      annotations: {
+        ...commonAnnotations
+      }
+    },
+    wrapHandler(
+      async (params) => {
+        const { DEFAULT_BUNDLE_DIR: DEFAULT_BUNDLE_DIR2, upsertArticle: upsertArticle2 } = await Promise.resolve().then(() => (init_io(), io_exports));
+        const result = upsertArticle2(
+          params.bundle_dir ?? DEFAULT_BUNDLE_DIR2,
+          params.file,
+          params.markdown
+        );
+        if (!result.validation.ok) {
+          return { ok: false, problems: result.validation.problems };
+        }
+        return { ok: true, created: result.created, entry: result.entry };
+      }
+    )
+  );
   return server;
 }
 async function runMcpServer() {