zam-core 0.11.1 → 0.13.0

package/dist/cli/commands/mcp.js

@@ -8352,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;
@@ -8645,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;
@@ -8734,8 +8734,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
   const dotsPerLine = 30;
   while (true) {
     let timeoutId;
-    const timeoutPromise = new Promise((resolve7) => {
-      timeoutId = setTimeout(() => resolve7("timeout"), timeoutMs);
+    const timeoutPromise = new Promise((resolve8) => {
+      timeoutId = setTimeout(() => resolve8("timeout"), timeoutMs);
     });
     const dotsInterval = setInterval(() => {
       process.stdout.write(".");
@@ -8989,10 +8989,317 @@ var init_client = __esm({
   }
 });
 
+// src/cli/okf/bundle.ts
+var bundle_exports = {};
+__export(bundle_exports, {
+  OKF_VERSION: () => OKF_VERSION,
+  RESERVED_FILES: () => RESERVED_FILES,
+  appendLog: () => appendLog,
+  buildCatalog: () => buildCatalog,
+  isReservedFile: () => isReservedFile,
+  parseFrontmatter: () => parseFrontmatter,
+  renderIndex: () => renderIndex,
+  toCatalogEntry: () => toCatalogEntry,
+  validateArticle: () => validateArticle
+});
+function isReservedFile(file) {
+  return RESERVED_FILES.includes(file);
+}
+function unquote(raw) {
+  const v = raw.trim();
+  if (v.length >= 2 && (v.startsWith('"') && v.endsWith('"') || v.startsWith("'") && v.endsWith("'"))) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+function parseFrontmatter(markdown) {
+  const lines = markdown.split("\n");
+  if (lines[0]?.trim() !== "---") {
+    throw new Error("frontmatter: file must start with a --- fence");
+  }
+  const fields = {};
+  let listKey = null;
+  let i = 1;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "---") break;
+    if (line.trim() === "") continue;
+    const listItem = /^\s+-\s+(.+)$/.exec(line);
+    if (listItem) {
+      if (!listKey) {
+        throw new Error(`frontmatter line ${i + 1}: list item without a key`);
+      }
+      fields[listKey].push(unquote(listItem[1]));
+      continue;
+    }
+    const pair = /^([A-Za-z0-9_-]+):(.*)$/.exec(line);
+    if (!pair) {
+      throw new Error(
+        `frontmatter line ${i + 1}: expected "key: value" or "- item"`
+      );
+    }
+    const key = pair[1];
+    const rest = pair[2].trim();
+    if (rest === "") {
+      fields[key] = [];
+      listKey = key;
+    } else {
+      fields[key] = unquote(rest);
+      listKey = null;
+    }
+  }
+  if (i >= lines.length) {
+    throw new Error("frontmatter: missing closing --- fence");
+  }
+  return { fields, body: lines.slice(i + 1).join("\n") };
+}
+function scalar(fields, key) {
+  const v = fields[key];
+  return typeof v === "string" && v.trim() !== "" ? v.trim() : void 0;
+}
+function validateArticle(file, markdown) {
+  const problems = [];
+  if (isReservedFile(file)) {
+    return { ok: false, problems: [`${file}: reserved OKF file name`] };
+  }
+  if (!FILE_NAME_RE.test(file)) {
+    problems.push(`${file}: file name must be kebab-case and end in .md`);
+  }
+  let parsed = null;
+  try {
+    parsed = parseFrontmatter(markdown);
+  } catch (err) {
+    problems.push(
+      `${file}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (parsed) {
+    if (!scalar(parsed.fields, "type")) {
+      problems.push(`${file}: frontmatter field "type" is required`);
+    }
+    if (!scalar(parsed.fields, "description")) {
+      problems.push(`${file}: frontmatter field "description" is required`);
+    }
+    if (parsed.body.trim() === "") {
+      problems.push(`${file}: article body is empty`);
+    }
+  }
+  return { ok: problems.length === 0, problems };
+}
+function toCatalogEntry(file, markdown) {
+  const { fields } = parseFrontmatter(markdown);
+  const tags = Array.isArray(fields.tags) ? fields.tags : [];
+  return {
+    file,
+    type: scalar(fields, "type") ?? "",
+    title: scalar(fields, "title") ?? file.replace(/\.md$/, ""),
+    description: scalar(fields, "description") ?? "",
+    tags,
+    resource: scalar(fields, "resource"),
+    timestamp: scalar(fields, "timestamp")
+  };
+}
+function buildCatalog(articles) {
+  return articles.map(({ file, markdown }) => toCatalogEntry(file, markdown)).sort((a, b) => a.file.localeCompare(b.file));
+}
+function renderIndex(catalog, okfVersion = OKF_VERSION) {
+  const types = [...new Set(catalog.map((e) => e.type))].sort();
+  const sections = types.map((type) => {
+    const rows = catalog.filter((e) => e.type === type).map((e) => `- [${e.title}](${e.file}) \u2014 ${e.description}`).join("\n");
+    return `## ${type}
+
+${rows}`;
+  });
+  return [
+    "---",
+    `okf_version: "${okfVersion}"`,
+    "---",
+    "",
+    "# ZAM Knowledge Base",
+    "",
+    "Living reference knowledge for this repository in",
+    "[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog).",
+    "Current truth only \u2014 the *why* behind it lives in [../adr/](../adr/)",
+    "(ADR 2026-07-17). Do not edit by hand: write through the",
+    "`zam_okf_upsert` MCP tool.",
+    "",
+    sections.join("\n\n"),
+    ""
+  ].join("\n");
+}
+function appendLog(existing, date, line) {
+  const header = `## ${date}`;
+  const entry = `- ${line}`;
+  const trimmed = existing.trim();
+  if (trimmed === "") {
+    return `# Log
+
+${header}
+
+${entry}
+`;
+  }
+  const lines = trimmed.split("\n");
+  const firstHeaderIdx = lines.findIndex((l) => l.startsWith("## "));
+  if (firstHeaderIdx !== -1 && lines[firstHeaderIdx].trim() === header) {
+    lines.splice(firstHeaderIdx + 2, 0, entry);
+    return `${lines.join("\n")}
+`;
+  }
+  const insertAt = firstHeaderIdx === -1 ? lines.length : firstHeaderIdx;
+  lines.splice(insertAt, 0, header, "", entry, "");
+  return `${lines.join("\n")}
+`;
+}
+var OKF_VERSION, RESERVED_FILES, FILE_NAME_RE;
+var init_bundle = __esm({
+  "src/cli/okf/bundle.ts"() {
+    "use strict";
+    OKF_VERSION = "0.1";
+    RESERVED_FILES = ["index.md", "log.md"];
+    FILE_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*\.md$/;
+  }
+});
+
+// src/cli/okf/io.ts
+var io_exports = {};
+__export(io_exports, {
+  DEFAULT_BUNDLE_DIR: () => DEFAULT_BUNDLE_DIR,
+  findRepoRoot: () => findRepoRoot,
+  loadBundle: () => loadBundle,
+  resolveArticlePath: () => resolveArticlePath,
+  resolveCitationPath: () => resolveCitationPath,
+  upsertArticle: () => upsertArticle
+});
+import {
+  existsSync as existsSync21,
+  mkdirSync as mkdirSync16,
+  readdirSync as readdirSync3,
+  readFileSync as readFileSync18,
+  realpathSync as realpathSync2,
+  writeFileSync as writeFileSync13
+} from "fs";
+import { dirname as dirname11, isAbsolute as isAbsolute2, join as join24, relative, resolve as resolve7, sep } 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 findRepoRoot(startDir) {
+  let dir = resolve7(startDir);
+  for (; ; ) {
+    if (existsSync21(join24(dir, ".git"))) return dir;
+    const parent = dirname11(dir);
+    if (parent === dir) return resolve7(startDir, "..");
+    dir = parent;
+  }
+}
+function resolveCitationPath(bundleDir, target) {
+  if (isAbsolute2(target)) {
+    throw new Error(
+      `invalid citation target: absolute paths are not allowed (${target})`
+    );
+  }
+  if (!target.endsWith(".md")) {
+    throw new Error(
+      `invalid citation target: only .md files are readable (${target})`
+    );
+  }
+  const root = findRepoRoot(bundleDir);
+  const resolved = resolve7(bundleDir, target);
+  assertContained(root, resolved, target);
+  if (existsSync21(resolved)) {
+    assertContained(realpathSync2(root), realpathSync2(resolved), target);
+  }
+  return resolved;
+}
+function assertContained(root, candidate, target) {
+  const rel = relative(root, candidate);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute2(rel)) {
+    throw new Error(
+      `invalid citation target: resolves outside the repository root (${target})`
+    );
+  }
+}
+function loadBundle(dir) {
+  const root = 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 readFileSync18 } from "fs";
-import { dirname as dirname11, join as join24 } from "path";
+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 {
   RESOURCE_MIME_TYPE,
@@ -9085,7 +9392,8 @@ var COMPANION_SURFACES = [
   "recall",
   "graph",
   "settings",
-  "studio"
+  "studio",
+  "okf"
 ];
 function isCompanionSurface(value) {
   return typeof value === "string" && COMPANION_SURFACES.includes(value);
@@ -11636,7 +11944,7 @@ async function readWebLink(url) {
         redirect: "manual",
         signal: controller.signal,
         headers: {
-          "User-Agent": "ZAM-Content-Studio/0.11.1"
+          "User-Agent": "ZAM-Content-Studio/0.13.0"
         }
       });
       if (res.status >= 300 && res.status < 400) {
@@ -28964,25 +29272,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;
@@ -30801,8 +31109,8 @@ 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");
-  if (existsSync22(statePath)) {
+  const { existsSync: existsSync23, writeFileSync: writeFileSync14, openSync, closeSync } = await import("fs");
+  if (existsSync23(statePath)) {
     jsonOut({
       sessionId,
       started: false,
@@ -30856,7 +31164,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
   }
   child.unref();
   if (child.pid) {
-    writeFileSync13(
+    writeFileSync14(
       statePath,
       JSON.stringify({
         pid: child.pid,
@@ -30893,8 +31201,8 @@ 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");
-  if (!existsSync22(statePath)) {
+  const { existsSync: existsSync23, readFileSync: readFileSync20, rmSync: rmSync4 } = await import("fs");
+  if (!existsSync23(statePath)) {
     jsonOut({
       sessionId,
       stopped: false,
@@ -30902,7 +31210,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");
@@ -30918,7 +31226,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)) {
@@ -30931,7 +31239,7 @@ bridgeCommand.command("stop-recording").description(
     rmSync4(statePath, { force: true });
   } catch {
   }
-  if (!existsSync22(outputPath)) {
+  if (!existsSync23(outputPath)) {
     jsonOut({
       sessionId,
       stopped: false,
@@ -33555,16 +33863,17 @@ async function publishUiIntent(app, input = {}, opts = {}) {
 }
 
 // src/cli/commands/mcp.ts
-var __dirname = dirname11(fileURLToPath6(import.meta.url));
-var pkgPath = join24(__dirname, "..", "..", "package.json");
-if (!existsSync21(pkgPath)) {
-  pkgPath = join24(__dirname, "..", "..", "..", "package.json");
+var __dirname = dirname12(fileURLToPath6(import.meta.url));
+var pkgPath = join25(__dirname, "..", "..", "package.json");
+if (!existsSync22(pkgPath)) {
+  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";
 var SETTINGS_RESOURCE_URI = "ui://zam/settings";
+var OKF_RESOURCE_URI = "ui://zam/okf";
 var STUDIO_BRIDGE_ALLOWED_COMMANDS = /* @__PURE__ */ new Set([
   "list-tokens",
   "personal-card-list",
@@ -33587,13 +33896,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");
+    if (existsSync22(candidate)) {
+      return readFileSync19(candidate, "utf-8");
     }
   }
   return `<!doctype html>
@@ -34358,6 +34667,214 @@ function createMcpServer(db) {
       }
     )
   );
+  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,
+        include_log: z.boolean().optional().describe(
+          "Also return the raw log.md text (empty string if missing)"
+        )
+      },
+      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);
+        let log;
+        if (params.include_log) {
+          const { readFileSync: readFileSync20 } = await import("fs");
+          try {
+            log = readFileSync20(join25(bundle.dir, "log.md"), "utf8");
+          } catch {
+            log = "";
+          }
+        }
+        return {
+          dir: bundle.dir,
+          articles: bundle.catalog,
+          problems: bundle.problems,
+          ...params.include_log ? { log } : {}
+        };
+      }
+    )
+  );
+  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 };
+      }
+    )
+  );
+  server.registerTool(
+    "zam_okf_read_citation",
+    {
+      description: "Read a citation target referenced by an OKF article (e.g. an ADR): read-only, restricted to .md files that resolve inside the repository root \u2014 the target may be outside the bundle but never outside the repo",
+      inputSchema: {
+        bundle_dir: okfBundleDirSchema,
+        target: z.string().describe(
+          "Path to the citation target relative to bundle_dir, e.g. ../adr/2026-07-17-x.md"
+        )
+      },
+      annotations: {
+        ...commonAnnotations,
+        readOnlyHint: true
+      }
+    },
+    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 path = resolveCitationPath2(bundleDir, params.target);
+      const content = readFileSync20(path, "utf8");
+      const root = findRepoRoot2(bundleDir);
+      const repoRelativePath = relative2(root, path).split(sep2).join("/");
+      return { target: params.target, path: repoRelativePath, content };
+    })
+  );
+  registerAppTool(
+    server,
+    "zam_okf_visualize",
+    {
+      title: "Open ZAM OKF visualizer",
+      description: "Open the ZAM OKF knowledge-base visualizer: articles by type with search, a markdown reader with inline-expandable cited ADRs, a link graph, and the log. Pass `bundle_dir` to browse a bundle other than the default (docs/okf under the server cwd).",
+      inputSchema: {
+        bundle_dir: okfBundleDirSchema
+      },
+      annotations: {
+        ...commonAnnotations,
+        readOnlyHint: true
+      },
+      _meta: {
+        ui: { resourceUri: OKF_RESOURCE_URI }
+      }
+    },
+    wrapHandler(async ({ bundle_dir }) => {
+      const opening = await resolveOpeningCompanionContextSafely(
+        db,
+        "okf",
+        void 0,
+        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 { resolve: resolve8 } = await import("path");
+      const requestedDir = bundle_dir ?? DEFAULT_BUNDLE_DIR2;
+      let resolvedBundleDir = resolve8(requestedDir);
+      let catalog = [];
+      let problems = [];
+      let log = "";
+      let okfVersion = null;
+      try {
+        const bundle = loadBundle2(requestedDir);
+        resolvedBundleDir = bundle.dir;
+        catalog = bundle.catalog;
+        problems = bundle.problems;
+        const { readFileSync: readFileSync20 } = await import("fs");
+        try {
+          log = readFileSync20(join25(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 { fields } = parseFrontmatter2(indexRaw);
+          okfVersion = typeof fields.okf_version === "string" ? fields.okf_version : null;
+        } catch {
+          okfVersion = null;
+        }
+      } catch (error) {
+        problems = [error instanceof Error ? error.message : String(error)];
+      }
+      return {
+        okf: "zam",
+        version: pkg.version,
+        user: opening.context.user.currentId ?? null,
+        bundleDir: resolvedBundleDir,
+        okfVersion,
+        catalog,
+        problems,
+        log,
+        companionContext: opening.context,
+        ...opening.degraded ? { companionContextDegraded: true } : {}
+      };
+    })
+  );
+  registerAppResource(
+    server,
+    "zam-okf",
+    OKF_RESOURCE_URI,
+    { mimeType: RESOURCE_MIME_TYPE },
+    async () => ({
+      contents: [
+        {
+          uri: OKF_RESOURCE_URI,
+          mimeType: RESOURCE_MIME_TYPE,
+          text: loadPanelHtml("okf-panel.html", "ZAM OKF")
+        }
+      ]
+    })
+  );
   return server;
 }
 async function runMcpServer() {