viteboard 0.2.0 → 0.2.1

package/bin/content-api-plugin.mjs

@@ -1,11 +1,10 @@
 import { promises as fs } from "node:fs";
 import * as path from "node:path";
-import os from "node:os";
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { renderPdfFromHtml as renderPdfFromHtmlPortable, sanitizePdfFileName as sanitizePdfFileNamePortable } from "./pdf-export.mjs";
+import { fileURLToPath } from "node:url";
+import { evaluatePageFromUrl as evaluatePageFromUrlPortable, renderPdfFromHtml as renderPdfFromHtmlPortable, sanitizePdfFileName as sanitizePdfFileNamePortable } from "./pdf-export.mjs";
 
 const WORKSPACE_DIR = ".workspace";
 const WORKSPACE_FILE = "workspace.json";
@@ -30,18 +29,80 @@ const MIME_EXT = {
 const MANAGED_ASSET_RE = /^assets\/[a-f0-9]{64}\.(png|jpe?g|webp|gif|svg)$/i;
 const ACTOR_TTL_MS = 30000;
 const LOCK_TTL_MS = 30000;
+const CAPABILITY_CACHE_MS = 1000;
+const WORKSPACE_CACHE_MS = 500;
+const SKILL_BUNDLE_MAX_BYTES = 16 * 1024 * 1024;
+const SKILL_SUPPORT_EXTENSIONS = new Set([
+  ".md", ".txt", ".json", ".yaml", ".yml", ".toml", ".csv", ".xml",
+  ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".sh", ".py", ".sql",
+  ".html", ".css",
+]);
+const SKILL_ASSET_TYPES = {
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".pdf": "application/pdf",
+};
 const ROOT_LINK_HEADER = '</llms.txt>; rel="describedby"; type="text/plain", </.well-known/viteboard.json>; rel="alternate"; type="application/json"';
 const execFileAsync = promisify(execFile);
 
-export function createContentApiPlugin() {
-  const cwd = process.cwd();
+function boardExportFileName(title, format) {
+  const extension = format === "jpeg" ? "jpg" : format;
+  const base = String(title ?? "board")
+    .trim()
+    .replace(/[\\/:*?"<>|]+/g, "-")
+    .replace(/[\u0000-\u001f\u007f]/g, "")
+    .replace(/\s+/g, " ")
+    .replace(/\.(pdf|jpe?g|svg)$/i, "")
+    .slice(0, 120) || "board";
+  return `${base}.${extension}`;
+}
+
+function decodeExportDataUrl(dataUrl, expectedMimeType) {
+  if (typeof dataUrl !== "string" || !dataUrl.startsWith("data:")) throw new Error("Board renderer returned invalid image data.");
+  const comma = dataUrl.indexOf(",");
+  if (comma < 0) throw new Error("Board renderer returned invalid image data.");
+  const metadata = dataUrl.slice(5, comma);
+  const mimeType = metadata.split(";")[0];
+  if (mimeType !== expectedMimeType) throw new Error("Board renderer returned an unexpected image format.");
+  const payload = dataUrl.slice(comma + 1);
+  if (metadata.split(";").includes("base64")) return Buffer.from(payload, "base64");
+  return Buffer.from(decodeURIComponent(payload), "utf-8");
+}
+
+export function createContentApiPlugin(options = {}) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
   const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
   const workspaceDir = path.resolve(cwd, WORKSPACE_DIR);
   const workspaceFile = path.join(workspaceDir, WORKSPACE_FILE);
   const machineDir = path.join(packageRoot, "content", "machine");
   const actorSessions = new Map();
   const locks = new Map();
+  const mutationQueues = new Map();
   const sseClients = new Set();
+  const capabilityCaches = new Map();
+  const capabilityCachePromises = new Map();
+  let capabilityGeneration = 0;
+  let workspaceCache = null;
+  let workspaceCacheExpiresAt = 0;
+  let workspaceCachePromise = null;
+  let workspaceGeneration = 0;
+
+  function invalidateCapabilityCache() {
+    capabilityGeneration++;
+    capabilityCaches.clear();
+    capabilityCachePromises.clear();
+  }
+
+  function invalidateWorkspaceCache() {
+    workspaceGeneration++;
+    workspaceCache = null;
+    workspaceCacheExpiresAt = 0;
+    workspaceCachePromise = null;
+  }
 
   function send(res, status, body) {
     res.statusCode = status;
@@ -58,7 +119,12 @@ export function createContentApiPlugin() {
   function sendBinary(res, status, body, type, fileName) {
     res.statusCode = status;
     res.setHeader("Content-Type", type);
-    if (fileName) res.setHeader("Content-Disposition", `attachment; filename="${String(fileName).replace(/[\r\n\"]/g, "-")}"`);
+    if (fileName) {
+      const value = String(fileName).replace(/[\r\n\\"]/g, "-");
+      const asciiName = value.replace(/[^\x20-\x7e]/g, "_");
+      const encodedName = encodeURIComponent(value).replace(/['()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+      res.setHeader("Content-Disposition", `attachment; filename="${asciiName}"; filename*=UTF-8''${encodedName}`);
+    }
     res.end(body);
   }
 
@@ -68,6 +134,12 @@ export function createContentApiPlugin() {
   }
 
   function broadcast(event, body) {
+    if (event === "workspace-changed") {
+      invalidateCapabilityCache();
+      invalidateWorkspaceCache();
+    } else if (event === "file-changed" && [body?.path, body?.oldPath].some((filePath) => filePath?.startsWith("capabilities/"))) {
+      invalidateCapabilityCache();
+    }
     for (const client of sseClients) {
       try { sendSse(client, event, body); } catch { sseClients.delete(client); }
     }
@@ -86,6 +158,34 @@ export function createContentApiPlugin() {
     return `${target.targetType}:${target.rootId}:${suffix}`;
   }
 
+  function fileMutationKey(absPath) {
+    const normalized = path.normalize(absPath);
+    return `file:${process.platform === "win32" ? normalized.toLowerCase() : normalized}`;
+  }
+
+  async function withMutationLock(key, operation) {
+    const previous = mutationQueues.get(key) ?? Promise.resolve();
+    let release;
+    const gate = new Promise((resolve) => { release = resolve; });
+    const queued = previous.then(() => gate);
+    mutationQueues.set(key, queued);
+    await previous;
+    try {
+      return await operation();
+    } finally {
+      release();
+      if (mutationQueues.get(key) === queued) mutationQueues.delete(key);
+    }
+  }
+
+  async function withMutationLocks(keys, operation) {
+    const uniqueKeys = [...new Set(keys)].sort();
+    const acquire = (index) => index >= uniqueKeys.length
+      ? operation()
+      : withMutationLock(uniqueKeys[index], () => acquire(index + 1));
+    return acquire(0);
+  }
+
   function activeActors() { return [...actorSessions.values()].sort((a, b) => a.label.localeCompare(b.label)); }
   function activeLocks() { return [...locks.values()].sort((a, b) => a.acquiredAt - b.acquiredAt); }
   function broadcastPresence() { broadcast("presence", { actors: activeActors(), locks: activeLocks() }); }
@@ -112,135 +212,17 @@ export function createContentApiPlugin() {
   }
 
   setInterval(pruneEphemeral, 10000).unref?.();
-
-  function revisionForText(content) { return createHash("sha1").update(content).digest("hex"); }
-  let chromiumBinaryPromise = null;
-  async function resolveChromiumBinary() {
-    if (chromiumBinaryPromise) return chromiumBinaryPromise;
-    chromiumBinaryPromise = (async () => {
-      for (const candidate of ["chromium-browser", "chromium", "google-chrome", "google-chrome-stable"]) {
-        try {
-          await execFileAsync("which", [candidate]);
-          return candidate;
-        } catch {
-          /* continue */
-        }
-      }
-      throw new Error("No Chromium-compatible browser is available for PDF export.");
-    })();
-    return chromiumBinaryPromise;
-  }
-  function sanitizePdfFileName(input) {
-    const cleaned = String(input ?? "").trim().replace(/[\\/:*?"<>|]+/g, "-").replace(/\s+/g, " ").slice(0, 120) || "export";
-    return cleaned.toLowerCase().endsWith(".pdf") ? cleaned : `${cleaned}.pdf`;
-  }
-  function mmToInches(mm) {
-    return Number(mm ?? 0) / 25.4;
-  }
-  async function openCdpPage(port) {
-    const res = await fetch(`http://127.0.0.1:${port}/json/new?about:blank`, { method: "PUT" });
-    const target = await res.json();
-    if (!target.webSocketDebuggerUrl) throw new Error("Could not open Chromium page target for PDF export.");
-    return target.webSocketDebuggerUrl;
-  }
-  async function printPdfViaCdp(wsUrl, url, pdf) {
-    const ws = new WebSocket(wsUrl);
-    let nextId = 0;
-    const pending = new Map();
-    let loadResolve = null;
-    const loaded = new Promise((resolve) => { loadResolve = resolve; });
-    ws.onmessage = (event) => {
-      const message = JSON.parse(String(event.data));
-      if (message.method === "Page.loadEventFired") {
-        if (loadResolve) loadResolve();
-        loadResolve = null;
-        return;
-      }
-      if (!message.id) return;
-      const entry = pending.get(message.id);
-      if (!entry) return;
-      pending.delete(message.id);
-      if (message.error) entry.reject(new Error(message.error.message || "CDP error"));
-      else entry.resolve(message.result);
-    };
-    const opened = new Promise((resolve, reject) => {
-      ws.onopen = resolve;
-      ws.onerror = () => reject(new Error("Could not connect to Chromium PDF export session."));
-    });
-    const send = (method, params = {}) => new Promise((resolve, reject) => {
-      const id = ++nextId;
-      pending.set(id, { resolve, reject });
-      ws.send(JSON.stringify({ id, method, params }));
-    });
-    await opened;
-    try {
-      await send("Page.enable");
-      await send("Runtime.enable");
-      await send("Page.navigate", { url });
-      await loaded;
-      await send("Runtime.evaluate", {
-        expression: "document.fonts ? document.fonts.ready.then(() => true) : true",
-        awaitPromise: true,
-        returnByValue: true,
-      });
-      const result = await send("Page.printToPDF", {
-        printBackground: true,
-        preferCSSPageSize: true,
-        displayHeaderFooter: Boolean(pdf.displayHeaderFooter),
-        headerTemplate: pdf.headerTemplate || "<div></div>",
-        footerTemplate: pdf.footerTemplate || "<div></div>",
-        marginTop: mmToInches(pdf.marginTopMm ?? 12),
-        marginBottom: mmToInches(pdf.marginBottomMm ?? 12),
-        marginLeft: mmToInches(pdf.marginLeftMm ?? 12),
-        marginRight: mmToInches(pdf.marginRightMm ?? 12),
-      });
-      return Buffer.from(result.data, "base64");
-    } finally {
-      try { ws.close(); } catch { /* ignore */ }
-    }
-  }
-  async function renderPdfFromHtml(html, fileName, pdf = {}) {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "viteboard-pdf-"));
-    const htmlPath = path.join(tmpDir, "publication.html");
-    const profileDir = path.join(tmpDir, "profile");
-    const browser = await resolveChromiumBinary();
-    let browserProcess = null;
-    try {
-      await fs.writeFile(htmlPath, html, "utf-8");
-      await fs.mkdir(profileDir, { recursive: true });
-      browserProcess = execFile(browser, [
-        "--headless",
-        "--disable-gpu",
-        "--no-sandbox",
-        `--user-data-dir=${profileDir}`,
-        "--remote-debugging-port=0",
-        "about:blank",
-      ], { windowsHide: true });
-      const activePortPath = path.join(profileDir, "DevToolsActivePort");
-      for (let attempt = 0; attempt < 100; attempt += 1) {
-        try {
-          const raw = await fs.readFile(activePortPath, "utf-8");
-          const port = raw.split(/\r?\n/)[0]?.trim();
-          if (!port) throw new Error("Chromium debugging port missing.");
-          const wsUrl = await openCdpPage(port);
-          return await printPdfViaCdp(wsUrl, pathToFileURL(htmlPath).href, pdf);
-        } catch {
-          await new Promise((resolve) => setTimeout(resolve, 100));
-        }
-      }
-      throw new Error("Timed out starting Chromium PDF export session.");
-    } finally {
-      if (browserProcess) {
-        const exited = new Promise((resolve) => {
-          browserProcess?.once("exit", resolve);
-          browserProcess?.once("close", resolve);
-        });
-        try { browserProcess.kill(); } catch { /* ignore */ }
-        await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 500))]);
+  setInterval(() => {
+    for (const client of sseClients) {
+      if (client.destroyed || client.writableEnded) {
+        sseClients.delete(client);
+        continue;
       }
-      await fs.rm(tmpDir, { recursive: true, force: true });
+      try { client.write(": keep-alive\n\n"); } catch { sseClients.delete(client); }
     }
-  }
+  }, 20000).unref?.();
+
+  function revisionForText(content) { return createHash("sha1").update(content).digest("hex"); }
   function hashPath(value) {
     let hash = 2166136261;
     for (let i = 0; i < value.length; i++) {
@@ -272,6 +254,10 @@ export function createContentApiPlugin() {
     try { return path.resolve(await fs.realpath(resolved)); } catch { return resolved; }
   }
 
+  async function isDirectory(absPath) {
+    try { return (await fs.stat(absPath)).isDirectory(); } catch { return false; }
+  }
+
   function normalizeRelativePath(relPath) {
     return relPath.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
   }
@@ -382,9 +368,25 @@ export function createContentApiPlugin() {
       const raw = await fs.readFile(workspaceFile, "utf-8");
       const parsed = JSON.parse(raw);
       const rawProjects = Array.isArray(parsed.projects) ? parsed.projects : [];
+      const projects = [];
+      const seenIds = new Set();
+      const seenPaths = new Set();
+      for (const item of rawProjects) {
+        if (typeof item?.rootPath !== "string") continue;
+        const rootPath = await canonicalizeProjectRoot(item.rootPath);
+        const id = typeof item.id === "string" && item.id.trim() ? item.id.trim() : projectIdFor(rootPath);
+        if (seenIds.has(id) || seenPaths.has(rootPath)) continue;
+        seenIds.add(id);
+        seenPaths.add(rootPath);
+        projects.push({
+          id,
+          label: typeof item.label === "string" && item.label.trim() ? item.label.trim() : path.basename(rootPath),
+          rootPath,
+        });
+      }
       return {
         version: 1,
-        projects: rawProjects.filter((project) => typeof project?.id === "string" && typeof project?.label === "string" && typeof project?.rootPath === "string"),
+        projects,
       };
     } catch { return { version: 1, projects: [] }; }
   }
@@ -399,11 +401,22 @@ export function createContentApiPlugin() {
     return rel === "" ? "docs" : rel;
   }
 
-  function docsRootId(projectId, absPath) { return `root-${hashPath(`${projectId}:${absPath}`)}`; }
+  // Preserve the path-only IDs used by earlier versions so saved routes and API references remain valid.
+  function docsRootId(absPath) { return `root-${hashPath(absPath)}`; }
   function projectIdFor(absRoot) { return `project-${hashPath(absRoot)}`; }
 
   async function discoverDocsRoots(project) {
     const roots = [];
+    if (path.basename(project.rootPath) === "docs") {
+      roots.push({
+        id: docsRootId(project.rootPath),
+        projectId: project.id,
+        projectLabel: project.label,
+        absPath: project.rootPath,
+        relativePath: "docs",
+        displayPath: "docs",
+      });
+    }
     const walk = async (dir) => {
       let entries;
       try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
@@ -414,7 +427,7 @@ export function createContentApiPlugin() {
         if (entry.name === "docs") {
           const relativePath = normalizeRelativePath(path.relative(project.rootPath, abs));
           roots.push({
-            id: docsRootId(project.id, abs),
+            id: docsRootId(abs),
             projectId: project.id,
             projectLabel: project.label,
             absPath: abs,
@@ -429,13 +442,37 @@ export function createContentApiPlugin() {
     return roots.sort((a, b) => a.displayPath.localeCompare(b.displayPath));
   }
 
-  async function getWorkspace() {
+  async function loadWorkspace() {
     const manifest = await loadManifest();
     const projects = [];
     for (const project of manifest.projects) projects.push({ ...project, docsRoots: await discoverDocsRoots(project) });
     return projects;
   }
 
+  async function getWorkspace() {
+    if (workspaceCache && Date.now() < workspaceCacheExpiresAt) return workspaceCache;
+    if (workspaceCachePromise) return workspaceCachePromise;
+    const generation = workspaceGeneration;
+    const pending = loadWorkspace();
+    workspaceCachePromise = pending;
+    try {
+      const projects = await pending;
+      if (generation !== workspaceGeneration) return getWorkspace();
+      workspaceCache = projects;
+      workspaceCacheExpiresAt = Date.now() + WORKSPACE_CACHE_MS;
+      const expiresAt = workspaceCacheExpiresAt;
+      setTimeout(() => {
+        if (workspaceCache === projects && workspaceCacheExpiresAt === expiresAt) {
+          workspaceCache = null;
+          workspaceCacheExpiresAt = 0;
+        }
+      }, WORKSPACE_CACHE_MS).unref?.();
+      return projects;
+    } finally {
+      if (workspaceCachePromise === pending) workspaceCachePromise = null;
+    }
+  }
+
   function toWorkspaceResponse(projects) {
     return {
       projects: projects.map((project) => ({
@@ -459,6 +496,34 @@ export function createContentApiPlugin() {
     return abs;
   }
 
+  function isWithinPath(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+  }
+
+  async function resolveSafeFilesystemPath(root, rel) {
+    const abs = safeResolve(root, rel);
+    if (!abs) return null;
+    let realRoot;
+    try { realRoot = await fs.realpath(root); } catch { return null; }
+
+    let existing = abs;
+    while (true) {
+      try {
+        const stat = await fs.lstat(existing);
+        if (stat.isSymbolicLink()) return null;
+        const realExisting = await fs.realpath(existing);
+        if (!isWithinPath(realRoot, realExisting)) return null;
+        return abs;
+      } catch (error) {
+        if (error.code !== "ENOENT") return null;
+        const parent = path.dirname(existing);
+        if (parent === existing) return null;
+        existing = parent;
+      }
+    }
+  }
+
   async function resolveRoot(rootId) {
     const projects = await getWorkspace();
     for (const project of projects) {
@@ -491,6 +556,363 @@ export function createContentApiPlugin() {
     return nodes;
   }
 
+  function capabilityBranches(tree) {
+    const capabilityRoot = tree.find((node) => node.type === "dir" && node.name === "capabilities");
+    if (!capabilityRoot || capabilityRoot.type !== "dir") return [];
+
+    const branches = [];
+    const walk = (nodes) => {
+      for (const node of nodes) {
+        if (node.type === "file") {
+          const relative = node.path.slice("capabilities/".length);
+          if (node.path.startsWith("capabilities/") && node.name.endsWith(".md") && !relative.includes("/")) {
+            branches.push({ branchPath: node.path, entryPath: node.path, node });
+          }
+          continue;
+        }
+
+        const entry = node.children
+          .filter((child) => child.type === "file" && child.name.toLowerCase().endsWith(".md"))
+          .sort((a, b) => (a.name === "index.md" ? -1 : b.name === "index.md" ? 1 : a.name.localeCompare(b.name)))[0];
+        if (entry) branches.push({ branchPath: node.path, entryPath: entry.path, node });
+        walk(node.children);
+      }
+    };
+    walk(capabilityRoot.children);
+    return branches.sort((a, b) => a.branchPath.localeCompare(b.branchPath));
+  }
+
+  function flattenTreeFiles(nodes) {
+    const files = [];
+    for (const node of nodes) {
+      if (node.type === "file") files.push(node);
+      else files.push(...flattenTreeFiles(node.children));
+    }
+    return files;
+  }
+
+  function skillFrontmatter(content) {
+    const match = String(content ?? "").match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    const fields = {};
+    if (!match) return { fields, body: String(content ?? "") };
+    for (const line of match[1].split(/\r?\n/)) {
+      const field = line.match(/^([a-zA-Z][\w-]*):\s*(.*)$/);
+      if (!field) continue;
+      let value = field[2].trim();
+      if ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      fields[field[1]] = value;
+    }
+    return { fields, body: String(content ?? "").slice(match[0].length).trim() };
+  }
+
+  function simpleMarkdownMetadata(content) {
+    const frontmatter = String(content ?? "").match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] ?? "";
+    const fields = {};
+    for (const line of frontmatter.split(/\r?\n/)) {
+      const field = line.match(/^([a-zA-Z][\w-]*):\s*(.*)$/);
+      if (!field) continue;
+      fields[field[1]] = field[2].trim().replace(/^(?:"(.*)"|'(.*)')$/, (_, doubleQuoted, singleQuoted) => doubleQuoted ?? singleQuoted);
+    }
+    return fields;
+  }
+
+  function firstCapabilityParagraph(content) {
+    const body = String(content ?? "").replace(/^---\r?\n[\s\S]*?\r?\n---\s*/m, "");
+    const purpose = body.match(/^#{1,6}\s+purpose\s*\r?\n+([\s\S]*?)(?=\r?\n#{1,6}\s|$)/im)?.[1];
+    const source = purpose ?? body;
+    return source
+      .split(/\r?\n\s*\r?\n/)
+      .map((part) => part.trim().replace(/^#{1,6}\s+/, "").replace(/^>\s?/, ""))
+      .find((part) => part && !part.startsWith("-") && !part.startsWith("```"))
+      ?.replace(/\s+/g, " ") ?? "";
+  }
+
+  function firstCapabilityHeading(content) {
+    const body = String(content ?? "").replace(/^---\r?\n[\s\S]*?\r?\n---\s*/m, "");
+    return body.match(/^#\s+(.+?)\s*#*\s*$/m)?.[1]?.trim() ?? "";
+  }
+
+  function prettifyCapabilityName(value) {
+    const base = String(value ?? "Capability").replace(/\.md$/i, "").split(/[\\/]/).pop() ?? "Capability";
+    const title = base.replace(/[-_]+/g, " ").trim();
+    return title ? title.charAt(0).toUpperCase() + title.slice(1) : "Capability";
+  }
+
+  function portableSkillId(project, root, branchPath) {
+    const routePath = branchPath.replace(/^capabilities\//, "").replace(/\.md$/i, "");
+    const slug = `${project.label}-${root.displayPath}-${routePath}`
+      .normalize("NFKD")
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "capability";
+    const suffix = createHash("sha1").update(`${root.id}:${branchPath}`).digest("hex").slice(0, 8);
+    return `${slug.slice(0, 55).replace(/-+$/g, "")}-${suffix}`;
+  }
+
+  function renderAgentSkill(capability) {
+    const sourceSkill = capability.files.find((file) => file.relativePath === "SKILL.md")?.content ?? "";
+    const sourceBody = skillFrontmatter(sourceSkill).body;
+    const machineRules = capability.machineInstructions.trim();
+    const supportingFiles = capability.files
+      .filter((file) => file.relativePath !== "SKILL.md")
+      .map((file) => `- \`${file.relativePath}\` (source: \`${file.sourcePath}\`)`);
+    const omittedFiles = capability.omittedFiles.map((file) => `- \`${file}\``);
+    const body = [
+      `# ${capability.title}`,
+      capability.summary,
+      "",
+      "## ViteBoard source",
+      "",
+      `- Project: ${capability.projectLabel}`,
+      `- Docs root: ${capability.docsRoot} (${capability.rootId})`,
+      `- Branch: \`${capability.branchPath}\``,
+      `- Detail API: \`/__api/capability?rootId=${encodeURIComponent(capability.rootId)}&path=${encodeURIComponent(capability.branchPath)}\``,
+      "",
+      ...(sourceBody ? ["## Capability-specific skill instructions", "", sourceBody, ""] : []),
+      "## Capability rules",
+      "",
+      machineRules || `No llms.txt is present. Read ${capability.entryPath} and inspect the relevant supporting files before acting.`,
+      "",
+      "## Supporting files",
+      "",
+      ...(supportingFiles.length ? supportingFiles : ["No additional files are listed."]),
+      ...(omittedFiles.length ? ["", "Files not included in this skill bundle (for example, unsupported types or files over the size limit):", "", ...omittedFiles] : []),
+      "",
+      "The capability source of truth is the ViteBoard branch listed above. Preserve its rules and use the ViteBoard capability API or the project files to read current supporting material.",
+    ].join("\n").trim();
+    return `---\nname: ${capability.id}\ndescription: ${JSON.stringify(capability.description)}\n---\n\n${body}\n`;
+  }
+
+  async function buildCapabilityIndex(scope = {}) {
+    const projects = await getWorkspace();
+    const capabilities = [];
+    for (const project of projects) {
+      if (scope.projectId && project.id !== scope.projectId) continue;
+      for (const root of project.docsRoots) {
+        if (scope.rootId && root.id !== scope.rootId) continue;
+        const nestedRoots = new Set(project.docsRoots
+          .filter((item) => item.id !== root.id && item.absPath.startsWith(root.absPath + path.sep))
+          .map((item) => item.relativePath));
+        const tree = await buildTree(root.absPath, nestedRoots);
+        for (const branch of capabilityBranches(tree)) {
+          const sourceNodes = branch.node.type === "file" ? [branch.node] : flattenTreeFiles(branch.node.children);
+          const preferredPaths = new Set([
+            branch.entryPath,
+            branch.node.type === "dir" ? `${branch.branchPath}/llms.txt` : "",
+            branch.node.type === "dir" ? `${branch.branchPath}/SKILL.md` : "",
+          ]);
+          sourceNodes.sort((a, b) => Number(preferredPaths.has(b.path)) - Number(preferredPaths.has(a.path)) || a.path.localeCompare(b.path));
+          const files = [];
+          let bundleBytes = 0;
+          for (const node of sourceNodes) {
+            const extension = path.extname(node.name).toLowerCase();
+            const isText = SKILL_SUPPORT_EXTENSIONS.has(extension);
+            const contentType = isText
+              ? extension === ".md"
+                ? "text/markdown; charset=utf-8"
+                : extension === ".json"
+                ? "application/json; charset=utf-8"
+                : extension === ".js" || extension === ".mjs" || extension === ".cjs"
+                ? "text/javascript; charset=utf-8"
+                : extension === ".css"
+                ? "text/css; charset=utf-8"
+                : "text/plain; charset=utf-8"
+              : SKILL_ASSET_TYPES[extension];
+            if (!contentType) continue;
+            const absolutePath = await resolveSafeFilesystemPath(root.absPath, node.path);
+            if (!absolutePath) continue;
+            try {
+              const stat = await fs.lstat(absolutePath);
+              const fileLimit = isText ? 1024 * 1024 : 5 * 1024 * 1024;
+              if (!stat.isFile() || stat.isSymbolicLink() || stat.size > fileLimit || bundleBytes + stat.size > SKILL_BUNDLE_MAX_BYTES) continue;
+              const bytes = await fs.readFile(absolutePath);
+              const content = isText ? bytes.toString("utf-8") : bytes;
+              bundleBytes += stat.size;
+              const isSingleFile = branch.node.type === "file";
+              let relativePath = isSingleFile
+                ? `references/${path.basename(node.path)}`
+                : node.path.slice(branch.branchPath.length + 1);
+              if (relativePath === "SKILL.md") relativePath = "SKILL.md";
+              files.push({
+                sourcePath: node.path,
+                relativePath,
+                catalogPath: relativePath === "SKILL.md" ? "references/source-SKILL.md" : relativePath,
+                content,
+                contentType,
+                size: stat.size,
+                isText,
+              });
+              if (files.length >= 200) break;
+            } catch {
+              /* Ignore unreadable, binary, or concurrently removed support files. */
+            }
+          }
+          const includedSourcePaths = new Set(files.map((file) => file.sourcePath));
+          const omittedFiles = sourceNodes.filter((node) => !includedSourcePaths.has(node.path)).map((node) => node.path);
+
+          const entryFile = files.find((file) => file.sourcePath === branch.entryPath);
+          const sourceSkill = files.find((file) => file.relativePath === "SKILL.md");
+          const machinePath = branch.node.type === "dir" ? `${branch.branchPath}/llms.txt` : null;
+          const machineFile = files.find((file) => file.sourcePath === machinePath);
+          const metadata = simpleMarkdownMetadata(entryFile?.content ?? "");
+          const authoredSkillMetadata = simpleMarkdownMetadata(sourceSkill?.content ?? "");
+          const title = metadata.title || firstCapabilityHeading(entryFile?.content) || prettifyCapabilityName(branch.entryPath);
+          const summary = metadata.summary || firstCapabilityParagraph(machineFile?.content) || firstCapabilityParagraph(entryFile?.content);
+          const description = (authoredSkillMetadata.description || summary || `Reusable instructions and resources for ${title}.`)
+            .replace(/\s+/g, " ")
+            .slice(0, 900);
+          const id = portableSkillId(project, root, branch.branchPath);
+          const routePath = branch.branchPath.replace(/^capabilities\//, "");
+          const record = {
+            id,
+            skillId: id,
+            title,
+            name: title,
+            description,
+            summary,
+            kind: metadata.kind || undefined,
+            tags: String(metadata.tags ?? "").replace(/^\[|\]$/g, "").split(",").map((tag) => tag.trim().replace(/^['\"]|['\"]$/g, "")).filter(Boolean),
+            rootId: root.id,
+            projectId: project.id,
+            projectLabel: project.label,
+            docsRoot: root.displayPath,
+            branchPath: branch.branchPath,
+            entryPath: branch.entryPath,
+            routePath,
+            machinePath,
+            machineInstructions: machineFile?.content ?? "",
+            files,
+            omittedFiles,
+          };
+          record.skillMarkdown = renderAgentSkill(record);
+          const versionHash = createHash("sha256").update(record.skillMarkdown);
+          for (const file of files) versionHash.update(file.catalogPath).update("\0").update(file.content).update("\0");
+          record.skillVersion = versionHash.digest("hex");
+          record.files = files.map(({ content, ...file }) => file);
+          delete record.machineInstructions;
+          delete record.skillMarkdown;
+          capabilities.push(record);
+        }
+      }
+    }
+    return capabilities.sort((a, b) => `${a.projectLabel}/${a.docsRoot}/${a.branchPath}`.localeCompare(`${b.projectLabel}/${b.docsRoot}/${b.branchPath}`));
+  }
+
+  async function getCapabilityIndex(scope = {}) {
+    const projects = await getWorkspace();
+    if (scope.projectId && !projects.some((project) => project.id === scope.projectId)) return [];
+    if (scope.rootId && !projects.some((project) => project.docsRoots.some((root) => root.id === scope.rootId))) return [];
+    if (scope.rootId && scope.projectId && !projects.some((project) =>
+      project.id === scope.projectId && project.docsRoots.some((root) => root.id === scope.rootId)
+    )) return [];
+    const cacheKey = `${scope.rootId ?? ""}\0${scope.projectId ?? ""}`;
+    const cached = capabilityCaches.get(cacheKey);
+    if (cached && Date.now() < cached.expiresAt) return cached.records;
+    const existing = capabilityCachePromises.get(cacheKey);
+    if (existing) return existing;
+    const generation = capabilityGeneration;
+    const pending = buildCapabilityIndex(scope);
+    capabilityCachePromises.set(cacheKey, pending);
+    try {
+      const records = await pending;
+      if (generation !== capabilityGeneration) return getCapabilityIndex(scope);
+      const cacheEntry = { records, expiresAt: Date.now() + CAPABILITY_CACHE_MS };
+      capabilityCaches.set(cacheKey, cacheEntry);
+      setTimeout(() => {
+        if (capabilityCaches.get(cacheKey) === cacheEntry) capabilityCaches.delete(cacheKey);
+      }, CAPABILITY_CACHE_MS).unref?.();
+      return records;
+    } finally {
+      if (capabilityCachePromises.get(cacheKey) === pending) capabilityCachePromises.delete(cacheKey);
+    }
+  }
+
+  async function readCapabilityFile(record, file) {
+    const resolved = await resolveRoot(record.rootId);
+    if (!resolved) return null;
+    const absolutePath = await resolveSafeFilesystemPath(resolved.root.absPath, file.sourcePath);
+    if (!absolutePath) return null;
+    try {
+      const stat = await fs.lstat(absolutePath);
+      const fileLimit = file.isText ? 1024 * 1024 : 5 * 1024 * 1024;
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > fileLimit) return null;
+      const bytes = await fs.readFile(absolutePath);
+      return file.isText ? bytes.toString("utf-8") : bytes;
+    } catch {
+      return null;
+    }
+  }
+
+  async function generateCapabilitySkill(record, machineInstructions) {
+    const sourceSkill = record.files.find((file) => file.relativePath === "SKILL.md");
+    const sourceSkillContent = sourceSkill ? await readCapabilityFile(record, sourceSkill) : "";
+    const files = sourceSkill
+      ? record.files.map((file) => file === sourceSkill ? { ...file, content: sourceSkillContent ?? "" } : file)
+      : record.files;
+    return renderAgentSkill({ ...record, files, machineInstructions });
+  }
+
+  function capabilitySummary(record) {
+    return {
+      id: record.id,
+      skillId: record.skillId,
+      name: record.name,
+      title: record.title,
+      description: record.description,
+      summary: record.summary,
+      kind: record.kind,
+      tags: record.tags,
+      rootId: record.rootId,
+      projectId: record.projectId,
+      projectLabel: record.projectLabel,
+      docsRoot: record.docsRoot,
+      branchPath: record.branchPath,
+      entryPath: record.entryPath,
+      routePath: record.routePath,
+      machinePath: record.machinePath,
+      fileCount: record.files.length,
+      omittedFileCount: record.omittedFiles.length,
+      version: record.skillVersion,
+      route: `#/root/${encodeURIComponent(record.rootId)}/capabilities/${encodeURIComponent(record.routePath)}`,
+      skillUrl: `/__api/skills/catalog/${record.id}/SKILL.md`,
+    };
+  }
+
+  async function capabilityDetail(record) {
+    const machineFile = record.machinePath ? record.files.find((file) => file.sourcePath === record.machinePath) : null;
+    const machineInstructions = machineFile ? await readCapabilityFile(record, machineFile) : "";
+    return {
+      ...capabilitySummary(record),
+      entrypoints: {
+        human: { path: record.entryPath, url: `/__api/file?rootId=${encodeURIComponent(record.rootId)}&path=${encodeURIComponent(record.entryPath)}` },
+        machine: record.machinePath
+          ? { path: record.machinePath, url: `/__api/file?rootId=${encodeURIComponent(record.rootId)}&path=${encodeURIComponent(record.machinePath)}` }
+          : null,
+        skill: { format: "Agent Skills", path: "SKILL.md", url: capabilitySummary(record).skillUrl },
+      },
+      rules: { path: record.machinePath, content: typeof machineInstructions === "string" ? machineInstructions : "" },
+      skillMarkdown: await generateCapabilitySkill(record, typeof machineInstructions === "string" ? machineInstructions : ""),
+      files: record.files.map((file) => ({
+        path: file.sourcePath,
+        relativePath: file.relativePath,
+        catalogPath: file.catalogPath,
+        url: `/__api/skills/catalog/${record.id}/${file.catalogPath.split("/").map(encodeURIComponent).join("/")}`,
+        sourceUrl: `${file.isText ? "/__api/file" : "/__api/asset"}?rootId=${encodeURIComponent(record.rootId)}&path=${encodeURIComponent(file.sourcePath)}`,
+        contentType: file.contentType,
+        size: file.size,
+      })),
+      omittedFiles: record.omittedFiles,
+      skillLocations: {
+        opencode: `.opencode/skills/${record.id}/SKILL.md or .agents/skills/${record.id}/SKILL.md`,
+        codex: `.agents/skills/${record.id}/SKILL.md`,
+        claudeCode: `.claude/skills/${record.id}/SKILL.md`,
+      },
+      openCodeCatalog: "/__api/skills/catalog/",
+    };
+  }
+
   function firstMarkdownPath(nodes) {
     for (const node of nodes) {
       if (node.type === "file" && node.name.endsWith(".md")) return node.path;
@@ -579,10 +1001,11 @@ export function createContentApiPlugin() {
     if (!project) return null;
     const existing = (await discoverDocsRoots(project))[0];
     if (existing) return existing;
-    const abs = path.join(project.rootPath, "docs");
+    const abs = await resolveSafeFilesystemPath(project.rootPath, "docs");
+    if (!abs) return null;
     await fs.mkdir(abs, { recursive: true });
     return {
-      id: docsRootId(project.id, abs),
+      id: docsRootId(abs),
       projectId: project.id,
       projectLabel: project.label,
       absPath: abs,
@@ -594,12 +1017,13 @@ export function createContentApiPlugin() {
   async function createDocsFolder(projectId, parentPath) {
     const project = await resolveWorkspaceProject(projectId);
     if (!project) return null;
-    const parentAbs = safeResolve(project.rootPath, parentPath || ".");
+    const parentAbs = await resolveSafeFilesystemPath(project.rootPath, parentPath || ".");
     if (!parentAbs) return null;
-    const abs = path.join(parentAbs, "docs");
+    const abs = await resolveSafeFilesystemPath(project.rootPath, path.relative(project.rootPath, path.join(parentAbs, "docs")));
+    if (!abs) return null;
     await fs.mkdir(abs, { recursive: true });
     return {
-      id: docsRootId(project.id, abs),
+      id: docsRootId(abs),
       projectId: project.id,
       projectLabel: project.label,
       absPath: abs,
@@ -621,8 +1045,8 @@ export function createContentApiPlugin() {
   }
 
   async function renamePath(rootAbsPath, oldPath, newPath, ignoreMissing = false) {
-    const oldAbs = safeResolve(rootAbsPath, oldPath);
-    const newAbs = safeResolve(rootAbsPath, newPath);
+    const oldAbs = await resolveSafeFilesystemPath(rootAbsPath, oldPath);
+    const newAbs = await resolveSafeFilesystemPath(rootAbsPath, newPath);
     if (!oldAbs || !newAbs) throw new Error("Invalid path");
     try { await fs.access(oldAbs); } catch (err) {
       if (ignoreMissing && err.code === "ENOENT") return;
@@ -642,6 +1066,7 @@ export function createContentApiPlugin() {
     const method = req.method || "GET";
     if (route === "/llms.txt" && method === "GET") return void (await sendMachineFile(res, "llms.txt", "text/plain; charset=utf-8"));
     if (route === "/viteboard-guide.md" && method === "GET") return void (await sendMachineFile(res, "guide.md", "text/markdown; charset=utf-8"));
+    if (route === "/viteboard-skill.md" && method === "GET") return void (await sendMachineFile(res, "viteboard-skill.md", "text/markdown; charset=utf-8"));
     if (route === "/board-v1.schema.json" && method === "GET") return void (await sendMachineFile(res, "board-v1.schema.json", "application/schema+json; charset=utf-8"));
     if (route === "/viteboard-example.board.json" && method === "GET") return void (await sendMachineFile(res, "example.board.json", "application/json; charset=utf-8"));
     if (route === "/.well-known/viteboard.json" && method === "GET") return void (await sendMachineFile(res, "viteboard.json", "application/json; charset=utf-8"));
@@ -654,6 +1079,7 @@ export function createContentApiPlugin() {
         res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
         res.setHeader("Cache-Control", "no-cache, no-transform");
         res.setHeader("Connection", "keep-alive");
+        res.setHeader("X-Accel-Buffering", "no");
         res.flushHeaders?.();
         sseClients.add(res);
         sendSse(res, "hello", { actors: activeActors(), locks: activeLocks() });
@@ -661,6 +1087,82 @@ export function createContentApiPlugin() {
         return;
       }
 
+      if (route === "/__api/capabilities" && method === "GET") {
+        const rootId = parsed.searchParams.get("rootId");
+        const projectId = parsed.searchParams.get("projectId");
+        const capabilities = await getCapabilityIndex({ rootId, projectId });
+        return send(res, 200, {
+          version: 1,
+          skillFormat: "Agent Skills",
+          catalog: { openCode: "/__api/skills/catalog/", index: "/__api/skills/catalog/index.json" },
+          locations: {
+            openCode: ".opencode/skills/<skill-id>/SKILL.md or .agents/skills/<skill-id>/SKILL.md",
+            codex: ".agents/skills/<skill-id>/SKILL.md",
+            claudeCode: ".claude/skills/<skill-id>/SKILL.md",
+          },
+          total: capabilities.length,
+          capabilities: capabilities.map(capabilitySummary),
+        });
+      }
+
+      if (route === "/__api/capability" && method === "GET") {
+        const rootId = parsed.searchParams.get("rootId") ?? "";
+        const requestedPath = parsed.searchParams.get("path") ?? "";
+        if (!rootId || !requestedPath) return send(res, 400, { error: "Expected rootId and capability path" });
+        const normalizedPath = normalizeRelativePath(requestedPath);
+        const branchPath = normalizedPath.startsWith("capabilities/") ? normalizedPath : `capabilities/${normalizedPath}`;
+        const capability = (await getCapabilityIndex({ rootId })).find((record) =>
+          record.rootId === rootId && (record.branchPath === branchPath || record.routePath === normalizedPath)
+        );
+        if (!capability) return send(res, 404, { error: "Capability not found" });
+        return send(res, 200, await capabilityDetail(capability));
+      }
+
+      if (route === "/__api/skills/catalog/index.json" && method === "GET") {
+        const records = await getCapabilityIndex();
+        const catalog = {
+          skills: records.map((record) => ({
+            name: record.id,
+            version: record.skillVersion,
+            files: ["SKILL.md", ...new Set(record.files.map((file) => file.catalogPath))],
+          })),
+        };
+        res.setHeader("Cache-Control", "no-cache");
+        return sendText(res, 200, JSON.stringify(catalog, null, 2) + "\n", "application/json; charset=utf-8");
+      }
+
+      const skillCatalogPrefix = "/__api/skills/catalog/";
+      if (route.startsWith(skillCatalogPrefix) && method === "GET") {
+        const segments = route.slice(skillCatalogPrefix.length).split("/");
+        let decoded;
+        try {
+          decoded = segments.map((segment) => decodeURIComponent(segment));
+        } catch {
+          return send(res, 400, { error: "Invalid skill path" });
+        }
+        const [skillId, ...fileParts] = decoded;
+        const filePath = fileParts.join("/");
+        if (!skillId || !filePath || fileParts.some((part) => !part || part === "." || part === ".." || part.includes("/") || part.includes("\\") || part.startsWith("."))) {
+          return send(res, 400, { error: "Invalid skill path" });
+        }
+        const capability = (await getCapabilityIndex()).find((record) => record.id === skillId);
+        if (!capability) return send(res, 404, { error: "Skill not found" });
+        if (filePath === "SKILL.md") {
+          res.setHeader("Cache-Control", "no-cache");
+          const machineFile = capability.machinePath ? capability.files.find((file) => file.sourcePath === capability.machinePath) : null;
+          const machineInstructions = machineFile ? await readCapabilityFile(capability, machineFile) : "";
+          const skillMarkdown = await generateCapabilitySkill(capability, typeof machineInstructions === "string" ? machineInstructions : "");
+          return sendText(res, 200, skillMarkdown, "text/markdown; charset=utf-8");
+        }
+        const file = capability.files.find((item) => item.catalogPath === filePath);
+        if (!file) return send(res, 404, { error: "Skill file not found" });
+        const content = await readCapabilityFile(capability, file);
+        if (content === null) return send(res, 404, { error: "Skill file is unavailable" });
+        res.setHeader("Cache-Control", "no-cache");
+        if (Buffer.isBuffer(content)) return sendBinary(res, 200, content, file.contentType);
+        return sendText(res, 200, content, file.contentType);
+      }
+
       if (route === "/__api/workspace" && method === "GET") return send(res, 200, await toWorkspaceResponse(await getWorkspace()));
       if (route === "/__api/project-tree" && method === "GET") {
         const projectId = parsed.searchParams.get("projectId") ?? "";
@@ -679,7 +1181,7 @@ export function createContentApiPlugin() {
         const rel = parsed.searchParams.get("path") ?? "";
         const resolved = await resolveRoot(rootId);
         if (!resolved) return send(res, 404, { error: "Docs root not found" });
-        const abs = safeResolve(resolved.root.absPath, rel);
+        const abs = await resolveSafeFilesystemPath(resolved.root.absPath, rel);
         if (!abs) return send(res, 400, { error: "Invalid path" });
         try {
           const content = await fs.readFile(abs, "utf-8");
@@ -690,44 +1192,61 @@ export function createContentApiPlugin() {
         const { rootId, path: rel, content, expectedRevision } = JSON.parse(await readBody(req));
         const resolved = await resolveRoot(String(rootId ?? ""));
         if (!resolved) return send(res, 404, { error: "Docs root not found" });
-        const abs = safeResolve(resolved.root.absPath, String(rel ?? ""));
+        const abs = await resolveSafeFilesystemPath(resolved.root.absPath, String(rel ?? ""));
         if (!abs) return send(res, 400, { error: "Invalid path" });
-        try {
-          const current = await fs.readFile(abs, "utf-8").catch((err) => err.code === "ENOENT" ? null : Promise.reject(err));
-          if (expectedRevision && current !== null && revisionForText(current) !== expectedRevision) return send(res, 409, { error: "File changed on disk", currentRevision: revisionForText(current) });
-          await fs.mkdir(path.dirname(abs), { recursive: true });
-          const nextContent = String(content ?? "");
-          await fs.writeFile(abs, nextContent, "utf-8");
-          const revision = revisionForText(nextContent);
-          broadcast("file-changed", { rootId: resolved.root.id, path: String(rel), action: "write", actorId: actor?.actorId ?? null });
-          return send(res, 200, { ok: true, path: rel, revision });
-        } catch (err) { return send(res, 500, { error: err.message }); }
+        return withMutationLock(fileMutationKey(abs), async () => {
+          try {
+            const safeAbs = await resolveSafeFilesystemPath(resolved.root.absPath, String(rel ?? ""));
+            if (!safeAbs) return send(res, 400, { error: "Invalid path" });
+            const current = await fs.readFile(safeAbs, "utf-8").catch((err) => err.code === "ENOENT" ? null : Promise.reject(err));
+            if (expectedRevision !== undefined) {
+              if (expectedRevision !== null && typeof expectedRevision !== "string") return send(res, 400, { error: "expectedRevision must be a string or null" });
+              const currentRevision = current === null ? null : revisionForText(current);
+              if (expectedRevision !== currentRevision) return send(res, 409, { error: "File changed on disk", currentRevision });
+            }
+            await fs.mkdir(path.dirname(safeAbs), { recursive: true });
+            const nextContent = String(content ?? "");
+            await fs.writeFile(safeAbs, nextContent, "utf-8");
+            const revision = revisionForText(nextContent);
+            broadcast("file-changed", { rootId: resolved.root.id, path: String(rel), action: "write", created: current === null, actorId: actor?.actorId ?? null });
+            return send(res, 200, { ok: true, path: rel, revision });
+          } catch (err) { return send(res, 500, { error: err.message }); }
+        });
       }
       if (route === "/__api/file" && method === "PATCH") {
         const { rootId, oldPath, newPath, ignoreMissing } = JSON.parse(await readBody(req));
         const resolved = await resolveRoot(String(rootId ?? ""));
         if (!resolved) return send(res, 404, { error: "Docs root not found" });
-        await renamePath(resolved.root.absPath, String(oldPath ?? ""), String(newPath ?? ""), !!ignoreMissing);
-        broadcast("file-changed", { rootId: resolved.root.id, path: String(newPath), action: "rename", actorId: actor?.actorId ?? null });
-        return send(res, 200, { ok: true });
+        const oldAbs = await resolveSafeFilesystemPath(resolved.root.absPath, String(oldPath ?? ""));
+        const newAbs = await resolveSafeFilesystemPath(resolved.root.absPath, String(newPath ?? ""));
+        if (!oldAbs || !newAbs) return send(res, 400, { error: "Invalid path" });
+        return withMutationLocks([fileMutationKey(oldAbs), fileMutationKey(newAbs)], async () => {
+          await renamePath(resolved.root.absPath, String(oldPath ?? ""), String(newPath ?? ""), !!ignoreMissing);
+          broadcast("file-changed", { rootId: resolved.root.id, path: String(newPath), oldPath: String(oldPath), action: "rename", actorId: actor?.actorId ?? null });
+          return send(res, 200, { ok: true });
+        });
       }
       if (route === "/__api/file" && method === "DELETE") {
         const rootId = parsed.searchParams.get("rootId") ?? "";
         const rel = parsed.searchParams.get("path") ?? "";
         const resolved = await resolveRoot(rootId);
         if (!resolved) return send(res, 404, { error: "Docs root not found" });
-        const abs = safeResolve(resolved.root.absPath, rel);
+        const abs = await resolveSafeFilesystemPath(resolved.root.absPath, rel);
         if (!abs) return send(res, 400, { error: "Invalid path" });
-        try { await fs.unlink(abs); } catch (err) { if (err.code !== "ENOENT") throw err; }
-        await deleteEmptyParentDirs(path.dirname(abs), resolved.root.absPath);
-        broadcast("file-changed", { rootId: resolved.root.id, path: rel, action: "delete", actorId: actor?.actorId ?? null });
-        return send(res, 200, { ok: true });
+        return withMutationLock(fileMutationKey(abs), async () => {
+          const safeAbs = await resolveSafeFilesystemPath(resolved.root.absPath, rel);
+          if (!safeAbs) return send(res, 400, { error: "Invalid path" });
+          try { await fs.unlink(safeAbs); } catch (err) { if (err.code !== "ENOENT") throw err; }
+          await deleteEmptyParentDirs(path.dirname(safeAbs), resolved.root.absPath);
+          broadcast("file-changed", { rootId: resolved.root.id, path: rel, action: "delete", actorId: actor?.actorId ?? null });
+          return send(res, 200, { ok: true });
+        });
       }
       if (route === "/__api/directory" && method === "PUT") {
         const { rootId, path: rel } = JSON.parse(await readBody(req));
         const resolved = await resolveRoot(String(rootId ?? ""));
         if (!resolved) return send(res, 404, { error: "Docs root not found" });
-        const abs = safeResolve(resolved.root.absPath, String(rel ?? ""));
+        const abs = await resolveSafeFilesystemPath(resolved.root.absPath, String(rel ?? ""));
         if (!abs) return send(res, 400, { error: "Invalid path" });
         await fs.mkdir(abs, { recursive: true });
         broadcast("file-changed", { rootId: resolved.root.id, path: String(rel), action: "mkdir", actorId: actor?.actorId ?? null });
@@ -738,7 +1257,7 @@ export function createContentApiPlugin() {
         const id = parsed.searchParams.get("id") ?? "";
         const resolved = await resolveRoot(rootId);
         if (!resolved) return send(res, 404, { error: "Docs root not found" });
-        const abs = safeResolve(resolved.root.absPath, `${id}.board.json`);
+        const abs = await resolveSafeFilesystemPath(resolved.root.absPath, `${id}.board.json`);
         if (!abs) return send(res, 400, { error: "Invalid id" });
         try {
           const content = await fs.readFile(abs, "utf-8");
@@ -749,34 +1268,111 @@ export function createContentApiPlugin() {
         const { rootId, id, doc, expectedRevision } = JSON.parse(await readBody(req));
         const resolved = await resolveRoot(String(rootId ?? ""));
         if (!resolved) return send(res, 404, { error: "Docs root not found" });
-        const abs = safeResolve(resolved.root.absPath, `${id}.board.json`);
+        const abs = await resolveSafeFilesystemPath(resolved.root.absPath, `${id}.board.json`);
         if (!abs) return send(res, 400, { error: "Invalid id" });
-        const current = await fs.readFile(abs, "utf-8").catch((err) => err.code === "ENOENT" ? null : Promise.reject(err));
-        if (expectedRevision && current !== null && revisionForText(current) !== expectedRevision) return send(res, 409, { error: "Board changed on disk", currentRevision: revisionForText(current) });
-        await fs.mkdir(path.dirname(abs), { recursive: true });
-        const nextContent = JSON.stringify(doc, null, 2) + "\n";
-        await fs.writeFile(abs, nextContent, "utf-8");
-        const revision = revisionForText(nextContent);
-        broadcast("board-changed", { rootId: resolved.root.id, boardId: String(id), action: "write", actorId: actor?.actorId ?? null });
-        return send(res, 200, { ok: true, id, revision });
+        return withMutationLock(fileMutationKey(abs), async () => {
+          const safeAbs = await resolveSafeFilesystemPath(resolved.root.absPath, `${id}.board.json`);
+          if (!safeAbs) return send(res, 400, { error: "Invalid id" });
+          const current = await fs.readFile(safeAbs, "utf-8").catch((err) => err.code === "ENOENT" ? null : Promise.reject(err));
+          if (expectedRevision !== undefined) {
+            if (expectedRevision !== null && typeof expectedRevision !== "string") return send(res, 400, { error: "expectedRevision must be a string or null" });
+            const currentRevision = current === null ? null : revisionForText(current);
+            if (expectedRevision !== currentRevision) return send(res, 409, { error: "Board changed on disk", currentRevision });
+          }
+          await fs.mkdir(path.dirname(safeAbs), { recursive: true });
+          const nextContent = JSON.stringify(doc, null, 2) + "\n";
+          await fs.writeFile(safeAbs, nextContent, "utf-8");
+          const revision = revisionForText(nextContent);
+          broadcast("board-changed", { rootId: resolved.root.id, boardId: String(id), action: current === null ? "create" : "write", created: current === null, actorId: actor?.actorId ?? null });
+          return send(res, 200, { ok: true, id, revision });
+        });
       }
       if (route === "/__api/board" && method === "DELETE") {
         const rootId = parsed.searchParams.get("rootId") ?? "";
         const id = parsed.searchParams.get("id") ?? "";
         const resolved = await resolveRoot(rootId);
         if (!resolved) return send(res, 404, { error: "Docs root not found" });
-        const abs = safeResolve(resolved.root.absPath, `${id}.board.json`);
+        const abs = await resolveSafeFilesystemPath(resolved.root.absPath, `${id}.board.json`);
         if (!abs) return send(res, 400, { error: "Invalid id" });
-        try { await fs.unlink(abs); } catch (err) { if (err.code !== "ENOENT") throw err; }
-        broadcast("board-changed", { rootId: resolved.root.id, boardId: id, action: "delete", actorId: actor?.actorId ?? null });
-        return send(res, 200, { ok: true, id });
+        return withMutationLock(fileMutationKey(abs), async () => {
+          const safeAbs = await resolveSafeFilesystemPath(resolved.root.absPath, `${id}.board.json`);
+          if (!safeAbs) return send(res, 400, { error: "Invalid id" });
+          try { await fs.unlink(safeAbs); } catch (err) { if (err.code !== "ENOENT") throw err; }
+          broadcast("board-changed", { rootId: resolved.root.id, boardId: id, action: "delete", actorId: actor?.actorId ?? null });
+          return send(res, 200, { ok: true, id });
+        });
+      }
+      if (route === "/__api/export/board" && method === "POST") {
+        const request = JSON.parse(await readBody(req));
+        if (typeof request.rootId !== "string" || typeof request.boardId !== "string" || !request.boardId.trim()) {
+          return send(res, 400, { error: "Expected rootId and boardId" });
+        }
+        if (!["pdf", "jpeg", "svg"].includes(request.format)) {
+          return send(res, 400, { error: "format must be pdf, jpeg, or svg" });
+        }
+        if (request.region !== undefined && (!Array.isArray(request.region) || request.region.length !== 4 || request.region.some((value) => typeof value !== "number" || !Number.isFinite(value)) || request.region[2] <= 0 || request.region[3] <= 0 || request.region[2] > 10_000_000 || request.region[3] > 10_000_000)) {
+          return send(res, 400, { error: "region must be [x, y, width, height] in board world units" });
+        }
+        if (request.padding !== undefined && (typeof request.padding !== "number" || !Number.isFinite(request.padding) || request.padding < 0 || request.padding > 100_000)) {
+          return send(res, 400, { error: "padding must be a non-negative number of board world units" });
+        }
+        if (request.scale !== undefined && (typeof request.scale !== "number" || !Number.isFinite(request.scale) || request.scale < 0.1 || request.scale > 16)) {
+          return send(res, 400, { error: "scale must be between 0.1 and 16 pixels per board unit" });
+        }
+        if (request.quality !== undefined && (typeof request.quality !== "number" || !Number.isFinite(request.quality) || request.quality < 0.1 || request.quality > 1)) {
+          return send(res, 400, { error: "quality must be between 0.1 and 1" });
+        }
+        if (request.paper !== undefined && !["A4", "Letter"].includes(request.paper)) {
+          return send(res, 400, { error: "paper must be A4 or Letter" });
+        }
+
+        const resolved = await resolveRoot(request.rootId);
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        const boardId = request.boardId.trim().replace(/^\/+/, "").replace(/\.board\.json$/i, "");
+        const boardAbs = await resolveSafeFilesystemPath(resolved.root.absPath, `${boardId}.board.json`);
+        if (!boardAbs) return send(res, 400, { error: "Invalid boardId" });
+        let boardDoc;
+        try {
+          boardDoc = JSON.parse(await fs.readFile(boardAbs, "utf-8"));
+        } catch (err) {
+          if (err.code === "ENOENT") return send(res, 404, { error: "Board not found" });
+          if (err instanceof SyntaxError) return send(res, 400, { error: "Board JSON is invalid" });
+          throw err;
+        }
+        if (boardDoc?.version !== 1 || !Array.isArray(boardDoc.elements)) return send(res, 400, { error: "Board document is invalid" });
+        if (request.region === undefined && !boardDoc.elements.some((element) => element && element.hidden !== true && [element.x, element.y, element.width, element.height].every(Number.isFinite))) {
+          return send(res, 400, { error: "Board has no visible content; provide an explicit region to export" });
+        }
+
+        const port = req.socket?.localPort;
+        let host = String(req.socket?.localAddress ?? "").replace(/^::ffff:/i, "");
+        if (!port || !host) return send(res, 500, { error: "Could not determine the ViteBoard server address" });
+        if (host.includes(":")) host = `[${host}]`;
+        const apiRequest = { ...request, boardId };
+        const expression = `window.__viteboardPrepareBoardExport ? window.__viteboardPrepareBoardExport(${JSON.stringify(apiRequest)}) : Promise.reject(new Error("ViteBoard board exporter did not load"))`;
+        const prepared = await evaluatePageFromUrlPortable(`http://${host}:${port}/`, expression);
+        if (prepared?.error) return send(res, 400, { error: prepared.error });
+        const fileName = boardExportFileName(prepared?.fileName ?? boardDoc.title, request.format);
+
+        if (request.format === "pdf") {
+          if (prepared?.format !== "pdf" || typeof prepared.html !== "string" || !prepared.html.trim()) {
+            return send(res, 500, { error: "Board renderer returned no PDF document" });
+          }
+          const pdfBuffer = await renderPdfFromHtmlPortable(prepared.html, fileName, typeof prepared.pdf === "object" && prepared.pdf ? prepared.pdf : {});
+          return sendBinary(res, 200, pdfBuffer, "application/pdf", fileName);
+        }
+
+        const expectedMimeType = request.format === "jpeg" ? "image/jpeg" : "image/svg+xml";
+        if (prepared?.format !== request.format) return send(res, 500, { error: "Board renderer returned an unexpected export format" });
+        const imageBuffer = decodeExportDataUrl(prepared.dataUrl, expectedMimeType);
+        return sendBinary(res, 200, imageBuffer, expectedMimeType, fileName);
       }
       if (route === "/__api/asset" && method === "GET") {
         const rootId = parsed.searchParams.get("rootId") ?? "";
         const rel = parsed.searchParams.get("path") ?? "";
         const resolved = await resolveRoot(rootId);
         if (!resolved) return send(res, 404, { error: "Docs root not found" });
-        const abs = safeResolve(resolved.root.absPath, rel);
+        const abs = await resolveSafeFilesystemPath(resolved.root.absPath, rel);
         if (!abs) return send(res, 400, { error: "Invalid path" });
         try {
           const buf = await fs.readFile(abs);
@@ -794,7 +1390,7 @@ export function createContentApiPlugin() {
         const ext = MIME_EXT[String(mimeType ?? "")] ?? (path.extname(String(name ?? "")) || ".png").toLowerCase();
         const digest = createHash("sha256").update(bytes).digest("hex");
         const rel = `assets/${digest}${ext}`;
-        const abs = safeResolve(resolved.root.absPath, rel);
+        const abs = await resolveSafeFilesystemPath(resolved.root.absPath, rel);
         if (!abs) return send(res, 400, { error: "Invalid path" });
         await fs.mkdir(path.dirname(abs), { recursive: true });
         try { await fs.access(abs); } catch { await fs.writeFile(abs, bytes); }
@@ -809,6 +1405,45 @@ export function createContentApiPlugin() {
         if (removed > 0) broadcast("asset-changed", { rootId: resolved.root.id, action: "cleanup", removed, actorId: actor?.actorId ?? null });
         return send(res, 200, { ok: true, removed });
       }
+      if (route === "/__api/export/document/pdf" && method === "POST") {
+        const request = JSON.parse(await readBody(req));
+        if (typeof request.rootId !== "string" || !request.rootId || !["doc", "dir"].includes(request.kind) || typeof request.path !== "string") {
+          return send(res, 400, { error: "Expected rootId, kind (doc or dir), and path" });
+        }
+        if (request.selectedPaths !== undefined && (!Array.isArray(request.selectedPaths) || request.selectedPaths.some((item) => typeof item !== "string"))) {
+          return send(res, 400, { error: "selectedPaths must be an array of document paths" });
+        }
+        const resolved = await resolveRoot(request.rootId);
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        const targetAbs = await resolveSafeFilesystemPath(resolved.root.absPath, request.path);
+        if (!targetAbs) return send(res, 400, { error: "Invalid export path" });
+        if (request.kind === "doc" && !request.path.toLowerCase().endsWith(".md")) {
+          return send(res, 400, { error: "Document PDF export requires a Markdown file" });
+        }
+        try {
+          const targetStat = await fs.stat(targetAbs);
+          if (request.kind === "doc" ? !targetStat.isFile() : !targetStat.isDirectory()) {
+            return send(res, 404, { error: request.kind === "doc" ? "Markdown document not found" : "Directory not found" });
+          }
+        } catch (err) {
+          if (err.code === "ENOENT") return send(res, 404, { error: request.kind === "doc" ? "Markdown document not found" : "Directory not found" });
+          throw err;
+        }
+        const port = req.socket?.localPort;
+        let host = String(req.socket?.localAddress ?? "").replace(/^::ffff:/i, "");
+        if (!port || !host) return send(res, 500, { error: "Could not determine the ViteBoard server address" });
+        if (host.includes(":")) host = `[${host}]`;
+        const expression = `window.__viteboardPreparePdf ? window.__viteboardPreparePdf(${JSON.stringify(request)}) : Promise.reject(new Error("ViteBoard PDF renderer did not load"))`;
+        const fallbackTitle = (request.path.split(/[\\/]/).pop() ?? "export").replace(/\.md$/i, "");
+        const prepared = await evaluatePageFromUrlPortable(`http://${host}:${port}/`, expression);
+        if (prepared?.error) return send(res, 400, { error: prepared.error });
+        if (typeof prepared?.html !== "string" || !prepared.html.trim()) {
+          return send(res, 500, { error: "The publication renderer returned no HTML" });
+        }
+        const fileName = sanitizePdfFileNamePortable(prepared.fileName ?? request.options?.title ?? fallbackTitle);
+        const pdfBuffer = await renderPdfFromHtmlPortable(prepared.html, fileName, typeof prepared.pdf === "object" && prepared.pdf ? prepared.pdf : {});
+        return sendBinary(res, 200, pdfBuffer, "application/pdf", fileName);
+      }
       if (route === "/__api/export/pdf" && method === "POST") {
         const { html, fileName, pdf } = JSON.parse(await readBody(req));
         if (typeof html !== "string" || !html.trim()) return send(res, 400, { error: "Missing HTML payload" });
@@ -822,28 +1457,41 @@ export function createContentApiPlugin() {
       }
       if (route === "/__api/workspace/project" && method === "POST") {
         const { rootPath, label } = JSON.parse(await readBody(req));
-        const absRoot = await canonicalizeProjectRoot(String(rootPath ?? ""));
+        if (typeof rootPath !== "string" || !rootPath.trim()) return send(res, 400, { error: "Expected a project root path" });
+        const absRoot = await canonicalizeProjectRoot(rootPath.trim());
+        if (!(await isDirectory(absRoot))) return send(res, 400, { error: "Project root not found" });
         const manifest = await loadManifest();
-        const projectId = projectIdFor(absRoot);
+        const existingProject = manifest.projects.find((project) => project.rootPath === absRoot);
+        const projectId = existingProject?.id ?? projectIdFor(absRoot);
         const overlap = manifest.projects.find((project) => project.id !== projectId && (isNestedPath(project.rootPath, absRoot) || isNestedPath(absRoot, project.rootPath)));
         if (overlap) return send(res, 409, { error: overlapError(overlap, absRoot) });
-        if (!manifest.projects.some((project) => project.id === projectId)) {
-          manifest.projects.push({ id: projectId, label: String(label ?? (path.basename(absRoot) || "Project")), rootPath: absRoot });
+        const project = { id: projectId, label: String(label ?? "").trim() || path.basename(absRoot) || "Project", rootPath: absRoot };
+        const projectIndex = manifest.projects.findIndex((item) => item.id === projectId);
+        const changed = projectIndex < 0 || manifest.projects[projectIndex].label !== project.label || manifest.projects[projectIndex].rootPath !== project.rootPath;
+        if (changed) {
+          if (projectIndex < 0) manifest.projects.push(project);
+          else manifest.projects.splice(projectIndex, 1, project);
           await saveManifest(manifest);
+          broadcast("workspace-changed", { action: existingProject ? "project-updated" : "project-added", projectId, actorId: actor?.actorId ?? null });
         }
         return send(res, 200, await toWorkspaceResponse(await getWorkspace()));
       }
       if (route === "/__api/workspace/project" && method === "DELETE") {
         const projectId = parsed.searchParams.get("id") ?? "";
         const manifest = await loadManifest();
+        const previousCount = manifest.projects.length;
         manifest.projects = manifest.projects.filter((project) => project.id !== projectId);
-        await saveManifest(manifest);
+        if (manifest.projects.length !== previousCount) {
+          await saveManifest(manifest);
+          broadcast("workspace-changed", { action: "project-removed", projectId, actorId: actor?.actorId ?? null });
+        }
         return send(res, 200, { ok: true, workspace: await toWorkspaceResponse(await getWorkspace()) });
       }
       if (route === "/__api/workspace/pick-project" && method === "POST") {
         const picked = await pickProjectFromSystemDialog();
         if (!picked) return send(res, 200, { cancelled: true, workspace: await toWorkspaceResponse(await getWorkspace()) });
         const absRoot = await canonicalizeProjectRoot(picked);
+        if (!(await isDirectory(absRoot))) return send(res, 400, { error: "Project root not found" });
         const manifest = await loadManifest();
         const projectId = projectIdFor(absRoot);
         const overlap = manifest.projects.find((project) => project.id !== projectId && (isNestedPath(project.rootPath, absRoot) || isNestedPath(absRoot, project.rootPath)));
@@ -851,21 +1499,44 @@ export function createContentApiPlugin() {
         if (!manifest.projects.some((project) => project.id === projectId)) {
           manifest.projects.push({ id: projectId, label: path.basename(absRoot) || "Project", rootPath: absRoot });
           await saveManifest(manifest);
+          broadcast("workspace-changed", { action: "project-added", projectId, actorId: actor?.actorId ?? null });
         }
         const workspace = await getWorkspace();
         return send(res, 200, { cancelled: false, workspace: await toWorkspaceResponse(workspace), addedProjectId: projectId });
       }
       if (route === "/__api/workspace/project/docs-root" && method === "POST") {
         const { projectId } = JSON.parse(await readBody(req));
-        const root = await ensureProjectDocsRoot(String(projectId ?? ""));
-        if (!root) return send(res, 404, { error: "Project not found" });
+        const projectKey = String(projectId ?? "");
+        if (!(await resolveWorkspaceProject(projectKey))) return send(res, 404, { error: "Project not found" });
+        const root = await ensureProjectDocsRoot(projectKey);
+        if (!root) return send(res, 400, { error: "Invalid docs root path" });
+        broadcast("workspace-changed", { action: "docs-root-ready", projectId: String(projectId), actorId: actor?.actorId ?? null });
+        const workspace = await getWorkspace();
+        return send(res, 200, { root: { id: root.id, projectId: root.projectId, projectLabel: root.projectLabel, relativePath: root.relativePath, displayPath: root.displayPath }, workspace: await toWorkspaceResponse(workspace) });
+      }
+      if (route === "/__api/workspace/project/docs-area" && method === "POST") {
+        const { projectId, folderName } = JSON.parse(await readBody(req));
+        const project = await resolveWorkspaceProject(String(projectId ?? ""));
+        if (!project) return send(res, 404, { error: "Project not found" });
+        const folderAbs = await resolveSafeFilesystemPath(project.rootPath, String(folderName ?? ""));
+        if (!folderAbs) return send(res, 400, { error: "Invalid docs area path" });
+        const docsAbs = await resolveSafeFilesystemPath(project.rootPath, path.relative(project.rootPath, path.join(folderAbs, "docs")));
+        if (!docsAbs) return send(res, 400, { error: "Invalid docs root path" });
+        await fs.mkdir(docsAbs, { recursive: true });
+        broadcast("workspace-changed", { action: "docs-area-ready", projectId: project.id, actorId: actor?.actorId ?? null });
         const workspace = await getWorkspace();
+        const refreshedProject = workspace.find((item) => item.id === project.id);
+        const root = refreshedProject?.docsRoots.find((item) => item.absPath === docsAbs);
+        if (!root) return send(res, 500, { error: "Could not create docs area" });
         return send(res, 200, { root: { id: root.id, projectId: root.projectId, projectLabel: root.projectLabel, relativePath: root.relativePath, displayPath: root.displayPath }, workspace: await toWorkspaceResponse(workspace) });
       }
       if (route === "/__api/workspace/project/create-docs-folder" && method === "POST") {
         const { projectId, parentPath } = JSON.parse(await readBody(req));
-        const root = await createDocsFolder(String(projectId ?? ""), String(parentPath ?? ""));
-        if (!root) return send(res, 404, { error: "Project not found" });
+        const projectKey = String(projectId ?? "");
+        if (!(await resolveWorkspaceProject(projectKey))) return send(res, 404, { error: "Project not found" });
+        const root = await createDocsFolder(projectKey, String(parentPath ?? ""));
+        if (!root) return send(res, 400, { error: "Invalid docs folder path" });
+        broadcast("workspace-changed", { action: "docs-folder-ready", projectId: String(projectId), actorId: actor?.actorId ?? null });
         const workspace = await getWorkspace();
         return send(res, 200, { root: { id: root.id, projectId: root.projectId, projectLabel: root.projectLabel, relativePath: root.relativePath, displayPath: root.displayPath }, workspace: await toWorkspaceResponse(workspace) });
       }