viteboard 0.2.0 → 0.2.1

package/bin/pdf-export.mjs

@@ -16,9 +16,9 @@ export 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 resolveBrowserBinary();
   let browserProcess = null;
   try {
+    const browser = await resolveBrowserBinary();
     await fs.writeFile(htmlPath, html, "utf-8");
     await fs.mkdir(profileDir, { recursive: true });
     browserProcess = execFile(browser, [
@@ -28,12 +28,12 @@ export async function renderPdfFromHtml(html, fileName, pdf = {}) {
       `--user-data-dir=${profileDir}`,
       "--remote-debugging-port=0",
       "about:blank",
-    ], { windowsHide: true });
+    ], { windowsHide: true, detached: process.platform !== "win32" });
 
     const activePortPath = path.join(profileDir, "DevToolsActivePort");
     const port = await waitForDevToolsPort(activePortPath);
     const wsUrl = await openCdpPage(port);
-    return await printPdfViaCdp(wsUrl, pathToFileURL(htmlPath).href, {
+    return await withTimeout(printPdfViaCdp(wsUrl, pathToFileURL(htmlPath).href, {
       displayHeaderFooter: Boolean(pdf.displayHeaderFooter),
       headerTemplate: pdf.headerTemplate,
       footerTemplate: pdf.footerTemplate,
@@ -41,17 +41,72 @@ export async function renderPdfFromHtml(html, fileName, pdf = {}) {
       marginBottomMm: pdf.marginBottomMm,
       marginLeftMm: pdf.marginLeftMm,
       marginRightMm: pdf.marginRightMm,
-    });
+    }), 120_000, "PDF rendering timed out.");
   } 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, delay(500)]);
+    await stopBrowserProcess(browserProcess);
+    await removeTemporaryDirectory(tmpDir);
+  }
+}
+
+export async function evaluatePageFromUrl(url, expression) {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "viteboard-pdf-"));
+  const profileDir = path.join(tmpDir, "profile");
+  let browserProcess = null;
+  try {
+    const browser = await resolveBrowserBinary();
+    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, detached: process.platform !== "win32" });
+    const port = await waitForDevToolsPort(path.join(profileDir, "DevToolsActivePort"));
+    const wsUrl = await openCdpPage(port);
+    return await withTimeout(evaluatePageViaCdp(wsUrl, url, expression), 120_000, "PDF preparation timed out.");
+  } finally {
+    await stopBrowserProcess(browserProcess);
+    await removeTemporaryDirectory(tmpDir);
+  }
+}
+
+async function stopBrowserProcess(browserProcess) {
+  if (!browserProcess || !browserProcess.pid) return;
+  const exited = new Promise((resolve) => {
+    if (browserProcess.exitCode !== null || browserProcess.signalCode !== null) return resolve();
+    browserProcess.once("close", resolve);
+  });
+  try {
+    if (process.platform === "win32") {
+      await execFileAsync("taskkill", ["/pid", String(browserProcess.pid), "/t", "/f"]).catch(() => browserProcess.kill());
+    } else {
+      process.kill(-browserProcess.pid, "SIGTERM");
+    }
+  } catch {
+    try { browserProcess.kill(); } catch { /* already stopped */ }
+  }
+  if (await Promise.race([exited.then(() => true), delay(1000).then(() => false)])) return;
+  try {
+    if (process.platform !== "win32") process.kill(-browserProcess.pid, "SIGKILL");
+    else browserProcess.kill("SIGKILL");
+  } catch { /* already stopped */ }
+  await Promise.race([exited, delay(1000)]);
+}
+
+async function removeTemporaryDirectory(tmpDir) {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    try {
+      await fs.rm(tmpDir, { recursive: true, force: true, maxRetries: 2, retryDelay: 100 });
+      return;
+    } catch (error) {
+      if (attempt === 7) {
+        console.warn("ViteBoard could not remove a temporary PDF export directory:", error.message);
+        return;
+      }
+      await delay(100 * (attempt + 1));
     }
-    await fs.rm(tmpDir, { recursive: true, force: true });
   }
 }
 
@@ -205,6 +260,59 @@ async function printPdfViaCdp(wsUrl, url, pdf) {
   }
 }
 
+async function evaluatePageViaCdp(wsUrl, url, expression) {
+  const ws = await connectWebSocket(wsUrl);
+  let nextId = 0;
+  const pending = new Map();
+  let loadResolve = null;
+  const loaded = new Promise((resolve) => { loadResolve = resolve; });
+
+  ws.onMessage = (text) => {
+    const message = JSON.parse(text);
+    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 send = (method, params = {}) => new Promise((resolve, reject) => {
+    const id = ++nextId;
+    pending.set(id, { resolve, reject });
+    ws.send(JSON.stringify({ id, method, params }));
+  });
+
+  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("Runtime.evaluate", {
+      expression,
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    if (result.exceptionDetails) {
+      throw new Error(result.exceptionDetails.exception?.description || result.exceptionDetails.text || "Could not prepare ViteBoard PDF export.");
+    }
+    if (result.result?.type === "undefined") return null;
+    return result.result?.value ?? null;
+  } finally {
+    ws.close();
+  }
+}
+
 function mmToInches(mm) {
   return Number(mm ?? 0) / 25.4;
 }
@@ -335,3 +443,15 @@ function decodeFrame(buffer) {
 function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+async function withTimeout(promise, ms, message) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(message)), ms); }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/content/docs/guide/boards-in-markdown.md

@@ -32,10 +32,11 @@ The easiest way to create an embed:
 
 1. Open the board in the editor
 2. Navigate to the region you want to embed
-3. Click **Copy embed** in the toolbar
-4. Paste the snippet into your markdown document
+3. Click **Select region to embed or export** in the toolbar and drag over the area
+4. Choose **Embed in a document** from the popup
+5. Paste the copied snippet into your markdown document
 
-The copied snippet includes the exact viewport coordinates for the current view.
+The copied snippet includes the exact board coordinates for the selected region. Region selection also offers PDF, JPEG, and SVG export; SVG contains the rendered board as an image rather than editable vector shapes.
 
 ## How It Works
 

package/content/docs/guide/boards.md

@@ -52,3 +52,11 @@ These files are small, diffable, and work naturally with git.
 ## Exiting the Board Editor
 
 Click the back arrow in the top-left corner to return to the documentation view. Your board is saved automatically.
+
+## Exporting
+
+Open **Export / Import** in the board toolbar to export the current view or full board as PNG, or to export the board JSON or a JSON-plus-images bundle.
+
+To export or embed a specific region, choose **Select region to embed or export** and drag over the board. Then choose **Embed in a document**, **Export as PDF**, **Export as JPEG**, or **Export as SVG**. SVG preserves the canvas appearance by embedding a PNG image; its shapes are not editable vector paths. PDF export uses a Chromium-compatible browser installed on the machine running ViteBoard.
+
+From a Markdown document, use its **Export to PDF** action to create a PDF. Before exporting, choose the page format and any optional sections or publication details. ViteBoard returns the PDF for download and does not select a save path on your behalf.

package/content/machine/guide.md

@@ -54,6 +54,19 @@ Important discovery endpoints:
 - `GET /__api/project-tree?projectId={projectId}`
 - `GET /__api/tree?rootId={rootId}`
 
+### Live change notifications
+
+The UI subscribes to `GET /__api/events` as a Server-Sent Events (SSE) stream. API clients can use the same endpoint with the browser `EventSource` API or another SSE client. It is a one-way notification channel; after receiving an event, fetch the authoritative workspace, tree, file, or board again rather than treating the event as the content itself. Native SSE clients reconnect automatically, and a newly opened stream should trigger a fresh snapshot fetch to cover any events missed while disconnected.
+
+Mutations made through the HTTP API publish these named events after writing:
+
+- `workspace-changed`: project or docs-root registration changes (`action`, optional `projectId`).
+- `file-changed`: file/directory writes, renames, and deletes (`rootId`, `path`, `action`; rename includes `oldPath`).
+- `board-changed`: board create, write, or delete (`rootId`, `boardId`, `action`).
+- `asset-changed`: asset write or cleanup (`rootId`, optional `path`, `action`).
+
+Events include `actorId` when the caller sends `X-ViteBoard-Actor-Id`; the UI uses this to ignore its own write notifications while keeping other tabs current. Notifications refresh views and flag revision conflicts—they do not merge live drafts or replace revision-checked writes. Direct filesystem changes that bypass the API do not emit events.
+
 The machine can navigate the same app surfaces a human uses:
 
 - workspace home: `#/`
@@ -144,6 +157,33 @@ automation/docs-refresh
 
 Machines should treat the whole branch as the capability context and use `llms.txt` as the first machine-facing file when it exists.
 
+### Agent Skills compatibility
+
+Every capability is also exposed as a portable [Agent Skills](https://agentskills.io) skill. ViteBoard generates `SKILL.md` from the branch metadata, optional branch-local `SKILL.md`, `llms.txt` rules, and the supporting-file list; `index.md`, `llms.txt`, and the rest of the capability branch remain the source of truth.
+
+Discover and inspect capabilities through the HTTP API:
+
+- `GET /__api/capabilities` lists capabilities across registered docs roots. Add `?rootId={rootId}` or `?projectId={projectId}` to scope the result.
+- `GET /__api/capability?rootId={rootId}&path={branchPath}` returns one capability, including its rules, generated `skillMarkdown`, and supporting-file URLs. `path` is the capability branch path, for example `capabilities/automation/docs-refresh`. `omittedFiles` lists items too large or unsupported for the skill bundle; they remain in the source branch.
+- `GET /__api/skills/catalog/index.json` returns an OpenCode-compatible HTTP skill catalog. Skill files are served under `/__api/skills/catalog/{skillId}/{filePath}`; the catalog version changes when included skill/source content changes.
+
+For OpenCode, add the live catalog URL to `skills` in the project's `opencode.json` or `opencode.jsonc` (merge this into existing config):
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "skills": ["http://localhost:5173/__api/skills/catalog/"]
+}
+```
+
+Use the exact ViteBoard origin instead of the example URL. This keeps OpenCode skills live; the catalog includes every registered docs root. For local Agent Skills consumers, save the API's `skillMarkdown` as `SKILL.md` and preserve the returned `catalogPath` files beside it:
+
+- Codex: `.agents/skills/{skillId}/`
+- Claude Code: `.claude/skills/{skillId}/`
+- OpenCode: `.opencode/skills/{skillId}/` or `.agents/skills/{skillId}/`
+
+The `SKILL.md` uses portable `name` and `description` frontmatter. Up to 200 text/support files (1 MiB each) and common image/PDF assets (5 MiB each) are bundled, with a 16 MiB aggregate content limit; see `omittedFiles` for anything excluded. Catalog metadata is cached briefly, while skill file contents are read on demand. Local copies are snapshots; fetch them again after the capability changes. ViteBoard does not write into agent configuration directories automatically.
+
 ## 3. Markdown board embeds
 
 Use fenced `board` blocks inside Markdown:
@@ -272,11 +312,14 @@ When deciding how much to change:
 
 ## 8. Concurrent edits
 
-ViteBoard keeps autosave, but it does not coordinate live writers.
+ViteBoard keeps autosave, but it does not coordinate live writers with locks.
+
+1. Read `GET /__api/file?rootId={rootId}&path={path}` or `GET /__api/board?rootId={rootId}&id={boardId}` and retain its `revision`.
+2. Send that value as `expectedRevision` in the matching `PUT /__api/file` or `PUT /__api/board` request.
+3. For a create-only write, send `"expectedRevision": null`; this succeeds only if the target does not already exist.
+4. If the write returns `409`, reload the latest version and re-apply your change.
 
-1. Read the current file or board revision before editing.
-2. Write changes with the expected revision.
-3. If the write returns a conflict, reload the latest version and re-apply your change.
+The API serializes writes and deletes for each target, so simultaneous revision-checked requests cannot both pass against the same old state. Omitting `expectedRevision` remains available for compatibility but permits unconditional overwrites; machine clients should always send it.
 
 This keeps the runtime simple and fast. The UI does not lock files or boards while an agent writes.
 
@@ -296,3 +339,57 @@ Avoid these anti-patterns:
 - Embeds resolve by relative path.
 - Embed crops stay inside the intended frame.
 - The resulting layout is readable to a human.
+
+## 10. HTTP PDF export
+
+Use `POST /__api/export/document/pdf` to export a document or a directory of Markdown documents. The server renders Markdown and board embeds with ViteBoard's renderer, then returns PDF bytes with `Content-Type: application/pdf` and a suggested filename in `Content-Disposition`. Save those bytes with the agent's own file tools. The server does not write to a path on the agent's machine.
+
+Example request:
+
+```http
+POST /__api/export/document/pdf
+Content-Type: application/json
+
+{
+  "rootId": "root-...",
+  "kind": "doc",
+  "path": "guide/getting-started.md",
+  "options": {
+    "paper": "A4",
+    "style": "clean",
+    "scale": "100",
+    "showHeaderChrome": false,
+    "showFooterChrome": false,
+    "includeCoverPage": false,
+    "includeTableOfContents": false,
+    "includeFilePaths": false,
+    "pageBreakBetweenDocs": false
+  }
+}
+```
+
+Set `kind` to `dir` and `path` to a docs-root-relative directory to export its Markdown files. Optional `selectedPaths` limits that set. The `options` object supports the same publication settings as the UI: `title`, `subtitle`, `style` (`clean` or `report`), `paper` (`A4` or `Letter`), `scale` (`90`, `100`, or `110`), `includeCoverPage`, `includeTableOfContents`, `includeFilePaths`, `pageBreakBetweenDocs`, `showHeaderChrome`, `showFooterChrome`, `author`, `organization`, `publicationDate`, `classification`, `legalNotice`, and `logoDataUrl`.
+
+Optional features and metadata default to off or blank. Before every export, ask the human to choose the options. Explain each option and do not silently enable one. For agent workflows, see `/viteboard-skill.md`.
+
+## 11. HTTP board-region export
+
+Use `POST /__api/export/board` to export a saved board as PDF, JPEG, or SVG bytes. Provide a docs `rootId`, `boardId` (board ID without `.board.json`), and `format`. An optional `region` is `[x, y, width, height]` in board world units; it must have positive width and height. If omitted, ViteBoard exports the visible board content with 48 world units of padding. `padding` can override that inferred-content padding; for an explicit region it defaults to zero.
+
+```http
+POST /__api/export/board
+Content-Type: application/json
+
+{
+  "rootId": "root-...",
+  "boardId": "product-roadmap",
+  "format": "jpeg",
+  "region": [-400, 0, 1800, 900],
+  "scale": 2,
+  "quality": 0.92
+}
+```
+
+The optional `scale` sets output pixels per world unit (default `2`, accepted range `0.1`–`16`); dimensions are safely capped. `quality` sets JPEG quality from `0.1` to `1` (default `0.92`). For PDF, `paper` may be `A4` or `Letter` (default `A4`); page orientation follows the selected region. The endpoint returns bytes with the matching `Content-Type` and a suggested `Content-Disposition` filename. Save the response on the agent's machine.
+
+SVG exports are standards-compliant SVG containers with the rendered board embedded as a PNG image. This preserves ViteBoard's canvas rendering accurately, but the shapes inside are not editable vector paths; use `scale` to choose raster resolution.

package/content/machine/llms.txt

@@ -71,6 +71,7 @@ When helpful, tell the human which of these are relevant in the current workspac
 ## Core machine docs
 
 - [ViteBoard authoring guide](/viteboard-guide.md): Workspace model, routes, boards, embeds, capabilities, and revision-checked editing.
+- [ViteBoard agent skill](/viteboard-skill.md): HTTP workflows, safe edits, and user-selected PDF export settings.
 - [Board schema v1](/board-v1.schema.json): JSON Schema for `.board.json` files.
 - [Example board](/viteboard-example.board.json): One complete valid ViteBoard board.
 
@@ -79,8 +80,11 @@ When helpful, tell the human which of these are relevant in the current workspac
 - Capabilities are managed directory branches under `capabilities/` inside a docs root.
 - Human entrypoint: `index.md`
 - Machine entrypoint: `llms.txt`
+- Agent Skills entrypoint: generated standard `SKILL.md`, including branch rules from `llms.txt`.
 - The rest of the branch may contain markdown, scripts, helpers, assets, examples, and nested directories.
 
+Discover skills with `GET /__api/capabilities`; read a capability's rules, generated skill, and file URLs with `GET /__api/capability?rootId={rootId}&path={branchPath}`. OpenCode can consume the live catalog at `/__api/skills/catalog/`. See `/viteboard-guide.md` for setup and portable local skill locations.
+
 ## App discovery
 
 - [Workspace listing](/__api/workspace): Registered projects and docs roots.

package/content/machine/viteboard-skill.md

@@ -0,0 +1,102 @@
+---
+name: viteboard-http
+description: Use ViteBoard's HTTP API to inspect and edit docs, boards, capabilities, assets, and export board or document PDFs.
+---
+
+# ViteBoard HTTP Skill
+
+Use the exact ViteBoard origin supplied by the user. Start at `/.well-known/viteboard.json` and `/llms.txt`. Read `/viteboard-guide.md` for the API and content rules. Do not assume a JavaScript SDK or direct server filesystem access.
+
+## Install this skill
+
+When the user asks to install the ViteBoard skill, use the agent's local file tools to save this skill in that agent's native skill location. The skill URL is `/viteboard-skill.md`. Ask which agent environment to target if you cannot identify it. Do not send a filesystem path to ViteBoard; installation happens on the agent's machine. Do not install or overwrite a skill without the user's request.
+
+## Safe editing
+
+1. Discover the workspace and relevant docs root with `GET /__api/workspace` and `GET /__api/tree?rootId=...`.
+2. Read the current document or board and its revision before editing.
+3. Send the read revision as `expectedRevision` when updating. For create-only writes, send `expectedRevision: null`. If the API returns `409`, read the latest version and re-apply only the requested change.
+4. Ask before deleting, replacing, or making broad changes.
+
+## Capability skills
+
+Discover workspace capabilities with `GET /__api/capabilities`. Read one capability with `GET /__api/capability?rootId={rootId}&path={branchPath}`; its response includes the current `llms.txt` rules, a portable `skillMarkdown`, and supporting-file URLs. Treat the capability branch as the source of truth and follow its rules. OpenCode can load the live catalog from `/__api/skills/catalog/`; Codex and Claude Code can use the same `SKILL.md` plus the returned support files in their native skill directories. Do not overwrite an existing agent config to install a skill.
+
+## PDF export
+
+Before **every** PDF export, present the user with structured question blocks. Do not start the export until the user answers. Do not infer preferences from a previous export. Explain each option in the question text. Ask again on every export, even if the user exported the same document before.
+
+Use separate blocks for these settings:
+
+1. **Optional sections** — multi-select, with nothing selected by default:
+   - Cover page: adds a title page.
+   - Table of contents: lists included documents; only applies to multiple documents.
+   - File paths: prints each document's path.
+   - Page break between documents: starts each document on a new page.
+   - Page header: adds publication metadata at the top of pages.
+   - Page footer: adds a label and page numbers.
+2. **Page format** — ask for paper (`A4` or `Letter`), style (`clean` or `report`), and scale (`90`, `100`, or `110`). Explain that these change page size, visual treatment, and content scale.
+3. **Publication details** — ask whether to override the generated title and whether to add a subtitle, author, organization, publication date, classification, legal notice, or logo. Leave each optional field blank unless the user supplies it.
+4. **Directory exports only** — ask whether to include all Markdown documents or select specific paths.
+5. **Save location** — if the user has not given an output path, ask where to save the PDF. This path is on the agent's machine.
+
+For agents with a question-block tool, use these blocks in one interaction where possible:
+
+```text
+Question: Which optional sections should I include? Select none to keep the PDF plain.
+Type: multi-select; no options selected by default
+Options: Cover page; Table of contents; File paths; Page breaks between documents; Page header; Page footer
+
+Question: Which paper size should I use?
+Type: single-select
+Options: A4; Letter
+
+Question: Which visual style should I use?
+Type: single-select
+Options: Clean; Report
+
+Question: Which content scale should I use?
+Type: single-select
+Options: 90%; 100%; 110%
+
+Question: Which publication details should I add? Leave values blank to omit them.
+Type: text
+Fields: Title override; Subtitle; Author; Organization; Publication date; Classification; Legal notice; Logo image
+
+For a directory export, ask which Markdown paths to include. List the paths and explain that selecting none cancels the export.
+
+If the task already names an output path, use it. Do not ask the user to repeat it.
+```
+
+Use the agent environment's native structured-question feature. If it has no question-block feature, ask the same questions as a short grouped prompt. Do not silently fall back to non-default features.
+
+Send the selected settings to `POST /__api/export/document/pdf`:
+
+```json
+{
+  "rootId": "root-id",
+  "kind": "doc",
+  "path": "guide/getting-started.md",
+  "options": {
+    "paper": "A4",
+    "style": "clean",
+    "scale": "100",
+    "includeCoverPage": false,
+    "includeTableOfContents": false,
+    "includeFilePaths": false,
+    "pageBreakBetweenDocs": false,
+    "showHeaderChrome": false,
+    "showFooterChrome": false
+  }
+}
+```
+
+The endpoint returns PDF bytes. Save the response to the path the user requests with the agent's own file/download tools. The path is on the agent's machine, not the ViteBoard server. Confirm the saved file and report its path. Never send a local output path to ViteBoard; the server cannot safely write to the agent's filesystem.
+
+If the user supplies a logo image, read it with the agent's local tools and send a PNG, JPEG, or WebP data URL in `options.logoDataUrl`. Do not send a server-local path.
+
+## Board-region export
+
+For a board export, ask the user which region to export (a world-space `[x, y, width, height]` or the whole board), which format they want (PDF, JPEG, or SVG), and the output path if they have not already named one. Explain that SVG currently contains a raster image inside an SVG wrapper rather than editable vector shapes. For PDF, ask whether to use A4 or Letter. Scale defaults to 2 output pixels per board unit; JPEG quality defaults to 92%. Before every export, ask again rather than reusing prior preferences.
+
+Send `POST /__api/export/board` with `rootId`, `boardId`, and `format`, plus `region` when the user specified one. Optional `scale`, `quality`, `paper`, and `padding` are documented in `/viteboard-guide.md`. The response is binary PDF, JPEG, or SVG data; save it to the agent's requested local path. Never send a local output path to ViteBoard.

package/content/machine/viteboard.json

@@ -1,6 +1,6 @@
 {
   "name": "ViteBoard",
-  "appVersion": "0.2.0",
+  "appVersion": "0.2.1",
   "machineVersion": 1,
   "summary": "Local-first documentation and infinite-canvas boards stored as plain files.",
   "interactionModel": "human-directed-via-agent",
@@ -29,6 +29,8 @@
   "discovery": {
     "llms": "/llms.txt",
     "guide": "/viteboard-guide.md",
+    "skill": "/viteboard-skill.md",
+    "skillInstall": "/viteboard-skill.md",
     "boardSchema": "/board-v1.schema.json",
     "exampleBoard": "/viteboard-example.board.json"
   },
@@ -36,12 +38,34 @@
     "branchModel": "directory",
     "entrypoints": {
       "human": "index.md",
-      "machine": "llms.txt"
+      "machine": "llms.txt",
+      "agentSkill": "generated SKILL.md"
     },
     "notes": [
       "A capability is a managed directory branch beneath capabilities/ inside a docs root.",
       "The branch, not a single file, is the capability unit.",
-      "Machines should prefer llms.txt as the first machine-facing entrypoint when present."
+      "Machines should prefer llms.txt as the first machine-facing entrypoint when present.",
+      "Agent Skills are generated from branch metadata, llms.txt rules, and supporting files; those files remain the source of truth.",
+      "OpenCode can load the live HTTP catalog; other Agent Skills consumers use portable local SKILL.md files."
+    ]
+  },
+  "agentSkills": {
+    "format": "Agent Skills",
+    "api": {
+      "list": "/__api/capabilities",
+      "detail": "/__api/capability?rootId={rootId}&path={branchPath}",
+      "openCodeCatalog": "/__api/skills/catalog/",
+      "openCodeCatalogIndex": "/__api/skills/catalog/index.json"
+    },
+    "locations": {
+      "openCode": ".opencode/skills/{skillId}/ or .agents/skills/{skillId}/",
+      "codex": ".agents/skills/{skillId}/",
+      "claudeCode": ".claude/skills/{skillId}/"
+    },
+    "notes": [
+      "Generated SKILL.md uses portable name and description frontmatter.",
+      "Capability rules and included supporting files are available in the detail API and OpenCode catalog.",
+      "Local skill installations are snapshots; OpenCode's HTTP catalog stays live."
     ]
   },
   "routes": {
@@ -57,10 +81,16 @@
   },
   "api": {
     "workspace": "/__api/workspace",
+    "events": "/__api/events",
+    "capabilities": "/__api/capabilities",
+    "capability": "/__api/capability?rootId={rootId}&path={branchPath}",
+    "openCodeSkillCatalog": "/__api/skills/catalog/",
     "projectTree": "/__api/project-tree?projectId={projectId}",
     "tree": "/__api/tree?rootId={rootId}",
     "file": "/__api/file?rootId={rootId}&path={path}",
     "board": "/__api/board?rootId={rootId}&id={boardId}",
+    "exportDocumentPdf": "/__api/export/document/pdf",
+    "exportBoard": "/__api/export/board",
     "registerProject": "/__api/workspace/project",
     "ensureDocsRoot": "/__api/workspace/project/docs-root",
     "createDocsFolder": "/__api/workspace/project/create-docs-folder"
@@ -68,10 +98,10 @@
   "coordination": {
     "mode": "revision-checked",
     "notes": [
-      "The app uses autosave plus revision checks instead of live locks.",
+      "SSE change notifications refresh connected views; they do not sync live drafts or merge edits.",
       "Always send the expected revision when writing a Markdown document or board.",
       "If a write conflicts, reload the latest version and re-apply the change.",
-      "Do not add your own background coordination layer."
+      "Do not add a second polling or background coordination mechanism."
     ]
   }
 }