ma-agents 3.15.4 → 3.16.0

package/lib/bmad-extension-plugin/.claude-plugin/marketplace.json

@@ -37,7 +37,7 @@
       "name": "ma-skills",
       "source": "./",
       "description": "ma-agents extension module providing enterprise SDLC personas and operational workflow skills.",
-      "version": "3.15.4",
+      "version": "3.16.0",
       "author": {
         "name": "Alon Mayaffit"
       },

package/lib/knowledge-atlas/dist/atlas.cjs

@@ -2005,11 +2005,11 @@ var require_lunr = __commonJS({
 });
 
 // lib/knowledge-atlas/src/cli.ts
-var path12 = __toESM(require("path"));
+var path13 = __toESM(require("path"));
 
 // lib/knowledge-atlas/src/generate.ts
-var fs11 = __toESM(require("fs"));
-var path11 = __toESM(require("path"));
+var fs12 = __toESM(require("fs"));
+var path12 = __toESM(require("path"));
 
 // lib/knowledge-atlas/src/scan/scanner.ts
 var fs2 = __toESM(require("fs"));
@@ -5636,8 +5636,8 @@ function mergeRecords(unchanged, reprocessed, removed) {
 }
 
 // lib/knowledge-atlas/src/render/site.ts
-var fs7 = __toESM(require("fs"));
-var path7 = __toESM(require("path"));
+var fs8 = __toESM(require("fs"));
+var path8 = __toESM(require("path"));
 
 // lib/knowledge-atlas/src/render/design-system.ts
 var DESIGN_SYSTEM_CSS = `/* Knowledge Atlas \u2014 design system (Story 29.3) */
@@ -12098,8 +12098,7 @@ function processMermaidFences(html) {
     hasMermaid = true;
     return [
       '<figure class="mermaid-block" aria-label="Mermaid diagram">',
-      '<figcaption class="mermaid-note">Mermaid diagram (source)</figcaption>',
-      `<div class="mermaid"><pre class="mermaid-fallback">${codeContent.trim()}</pre></div>`,
+      `<pre class="mermaid">${codeContent.trim()}</pre>`,
       "</figure>"
     ].join("\n");
   });
@@ -12119,6 +12118,9 @@ function getFileNodes(fileId, nodes) {
 function renderDocumentPage(fileRec, manifest, projectRoot, navFlags, resolveAbsPath) {
   const absPath = resolveAbsPath?.(fileRec.path) ?? path6.join(projectRoot, fileRec.path);
   const title = fileTitle(fileRec.path);
+  if (/\.drawio(\.xml)?$/i.test(fileRec.path)) {
+    return renderDrawioPage(fileRec, absPath, title, manifest, navFlags);
+  }
   let rawContent = "";
   try {
     rawContent = fs6.readFileSync(absPath, "utf-8");
@@ -12139,7 +12141,7 @@ function renderDocumentPage(fileRec, manifest, projectRoot, navFlags, resolveAbs
   const tocEntries = extractToc(markdownContent);
   let renderedHtml = md.render(markdownContent);
   renderedHtml = addHeadingAnchors(renderedHtml);
-  const { html: mermaidHtml } = processMermaidFences(renderedHtml);
+  const { html: mermaidHtml, hasMermaid } = processMermaidFences(renderedHtml);
   renderedHtml = mermaidHtml;
   renderedHtml = rewriteAuthoredLinks(renderedHtml, manifest, fileRec.path);
   renderedHtml = linkifyHtml(renderedHtml, manifest, fileRec.path);
@@ -12163,7 +12165,9 @@ function renderDocumentPage(fileRec, manifest, projectRoot, navFlags, resolveAbs
     const a = node.anchor;
     if (!a || existingIds.has(a)) continue;
     existingIds.add(a);
-    const m = new RegExp('<a\\b[^>]*href="[^"]*#' + escRe(a) + '"', "i").exec(renderedHtml);
+    const ra = escRe(a);
+    let m = new RegExp('<a\\b[^>]*href="[^"]*#' + ra + '"[^>]*>[^<]*</a>\\s*:', "i").exec(renderedHtml);
+    if (!m) m = new RegExp('<a\\b[^>]*href="[^"]*#' + ra + '"', "i").exec(renderedHtml);
     if (m) inlinePlacements.push({ idx: m.index, anchor: a });
     else fallbackAnchors.push(a);
   }
@@ -12186,16 +12190,83 @@ function renderDocumentPage(fileRec, manifest, projectRoot, navFlags, resolveAbs
     "</article>",
     "</div>"
   ].filter(Boolean).join("\n");
+  const scripts = [];
+  if (hasMermaid) {
+    scripts.push('<script src="../assets/mermaid.min.js"></script>');
+    scripts.push(
+      '<script>try{mermaid.initialize({startOnLoad:true,securityLevel:"strict",theme:"neutral"});}catch(e){}</script>'
+    );
+  }
   const html = pageShell({
     title,
     body: pageBody,
     manifest,
     pageType: "document",
     baseHref: "../",
-    navFlags
+    navFlags,
+    scripts
   });
   const articleText = `${title} ${renderedHtml}`.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
-  return { html, articleText };
+  return { html, articleText, usedMermaid: hasMermaid, usedDrawio: false };
+}
+function renderDrawioPage(fileRec, absPath, title, manifest, navFlags) {
+  let xml = "";
+  try {
+    xml = fs6.readFileSync(absPath, "utf-8").replace(/\r\n/g, "\n");
+  } catch {
+    xml = "";
+  }
+  const config2 = { highlight: "#3572b0", nav: true, resize: true, "toolbar-nohide": true, toolbar: "zoom layers", xml };
+  const dataAttr = esc4(JSON.stringify(config2));
+  const body = [
+    '<div class="content-wrap">',
+    '<a class="back-link" href="../index.html">&larr; Back to Home</a>',
+    '<article class="doc-body">',
+    `<h1>${esc4(title)}</h1>`,
+    '<figure class="drawio-block" aria-label="draw.io diagram">',
+    xml ? `<div class="mxgraph" style="max-width:100%;border:1px solid var(--border,#ddd);border-radius:6px" data-mxgraph="${dataAttr}"></div>` : "<p><em>(draw.io file could not be read.)</em></p>",
+    '<noscript><p class="mermaid-note">This is a draw.io diagram; enable JavaScript to render it.</p></noscript>',
+    "</figure>",
+    "</article>",
+    "</div>"
+  ].filter(Boolean).join("\n");
+  const scripts = [
+    '<script>window.DRAWIO_BASE_URL=".";window.PROXY_URL=".";window.STYLE_PATH=".";window.RESOURCE_BASE=".";window.SHAPES_PATH=".";window.STENCIL_PATH=".";window.IMAGE_PATH=".";</script>',
+    '<script src="../assets/drawio-viewer.min.js"></script>'
+  ];
+  const html = pageShell({
+    title,
+    body,
+    manifest,
+    pageType: "document",
+    baseHref: "../",
+    navFlags,
+    scripts
+  });
+  return { html, articleText: title, usedMermaid: false, usedDrawio: true };
+}
+
+// lib/knowledge-atlas/src/render/vendor.ts
+var fs7 = __toESM(require("fs"));
+var path7 = __toESM(require("path"));
+function vendorDir() {
+  return path7.join(__dirname, "..", "vendor");
+}
+function readVendorAsset(name) {
+  const p = path7.join(vendorDir(), name);
+  try {
+    return fs7.readFileSync(p, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function writeVendorAsset(outDir, name) {
+  const content = readVendorAsset(name);
+  if (content == null) return null;
+  const assetsDir = path7.join(outDir, "assets");
+  fs7.mkdirSync(assetsDir, { recursive: true });
+  fs7.writeFileSync(path7.join(assetsDir, name), content.replace(/\r\n/g, "\n"), { encoding: "utf-8" });
+  return `assets/${name}`;
 }
 
 // lib/knowledge-atlas/src/render/search.ts
@@ -12408,8 +12479,8 @@ function esc6(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 function writeHtml(filePath, content) {
-  fs7.mkdirSync(path7.dirname(filePath), { recursive: true });
-  fs7.writeFileSync(filePath, content.replace(/\r\n/g, "\n"), { encoding: "utf-8" });
+  fs8.mkdirSync(path8.dirname(filePath), { recursive: true });
+  fs8.writeFileSync(filePath, content.replace(/\r\n/g, "\n"), { encoding: "utf-8" });
 }
 function renderHomePage(manifest, navFlags) {
   const { projectTitle, generatedAt, counts, nodes, edges } = manifest;
@@ -12546,35 +12617,47 @@ function renderHomePage(manifest, navFlags) {
 function renderSite(manifest, outDir, resolveAbsPath) {
   const written = [];
   const docBodies = /* @__PURE__ */ new Map();
-  fs7.mkdirSync(outDir, { recursive: true });
-  fs7.mkdirSync(path7.join(outDir, "docs"), { recursive: true });
+  fs8.mkdirSync(outDir, { recursive: true });
+  fs8.mkdirSync(path8.join(outDir, "docs"), { recursive: true });
   const fileIds = manifest.files.map((f) => f.path);
   const slugMap = buildSlugMap(fileIds);
   const navFlags = {
-    hasGraphPage: fs7.existsSync(path7.join(outDir, "graph.html")),
-    hasDiagramsPage: fs7.existsSync(path7.join(outDir, "diagrams.html")),
-    hasOrphansPage: fs7.existsSync(path7.join(outDir, "orphans.html"))
+    hasGraphPage: fs8.existsSync(path8.join(outDir, "graph.html")),
+    hasDiagramsPage: fs8.existsSync(path8.join(outDir, "diagrams.html")),
+    hasOrphansPage: fs8.existsSync(path8.join(outDir, "orphans.html"))
   };
+  let anyMermaid = false;
+  let anyDrawio = false;
   for (const file of manifest.files) {
     const slug = slugMap.get(file.path) ?? filePathToSlug(file.path);
-    const { html, articleText } = renderDocumentPage(file, manifest, manifest.projectRoot, navFlags, resolveAbsPath);
+    const { html, articleText, usedMermaid, usedDrawio } = renderDocumentPage(file, manifest, manifest.projectRoot, navFlags, resolveAbsPath);
     const relPath = `docs/${slug}.html`;
-    writeHtml(path7.join(outDir, relPath), html);
+    writeHtml(path8.join(outDir, relPath), html);
     written.push(relPath);
+    if (usedMermaid) anyMermaid = true;
+    if (usedDrawio) anyDrawio = true;
     docBodies.set(file.path, articleText);
   }
+  if (anyMermaid) {
+    const rel = writeVendorAsset(outDir, "mermaid.min.js");
+    if (rel) written.push(rel);
+  }
+  if (anyDrawio) {
+    const rel = writeVendorAsset(outDir, "drawio-viewer.min.js");
+    if (rel) written.push(rel);
+  }
   const searchHtml = renderSearchPageHtml(manifest, docBodies, navFlags);
-  writeHtml(path7.join(outDir, "search.html"), searchHtml);
+  writeHtml(path8.join(outDir, "search.html"), searchHtml);
   written.push("search.html");
   const indexHtml = renderHomePage(manifest, navFlags);
-  writeHtml(path7.join(outDir, "index.html"), indexHtml);
+  writeHtml(path8.join(outDir, "index.html"), indexHtml);
   written.push("index.html");
   return written.sort();
 }
 
 // lib/knowledge-atlas/src/render/graph.ts
-var fs8 = __toESM(require("fs"));
-var path8 = __toESM(require("path"));
+var fs9 = __toESM(require("fs"));
+var path9 = __toESM(require("path"));
 
 // lib/knowledge-atlas/src/render/force-graph-umd.ts
 var FORCE_GRAPH_UMD = `// Version 1.51.4 force-graph - https://github.com/vasturiano/force-graph
@@ -13037,9 +13120,9 @@ function renderGraphPage(manifest, outDir) {
     ""
     // trailing newline
   ].join("\n");
-  const outPath = path8.join(outDir, "graph.html");
-  fs8.mkdirSync(outDir, { recursive: true });
-  fs8.writeFileSync(outPath, html.replace(/\r\n/g, "\n"), { encoding: "utf-8" });
+  const outPath = path9.join(outDir, "graph.html");
+  fs9.mkdirSync(outDir, { recursive: true });
+  fs9.writeFileSync(outPath, html.replace(/\r\n/g, "\n"), { encoding: "utf-8" });
   return ["graph.html"];
 }
 function buildAppScript() {
@@ -13349,8 +13432,8 @@ function buildAppScript() {
 }
 
 // lib/knowledge-atlas/src/render/diagrams.ts
-var fs9 = __toESM(require("fs"));
-var path9 = __toESM(require("path"));
+var fs10 = __toESM(require("fs"));
+var path10 = __toESM(require("path"));
 function esc8(s) {
   return (s ?? "").toString().replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
@@ -13917,15 +14000,15 @@ function renderDiagrams(manifest, outDir) {
     ""
     // trailing newline
   ].join("\n");
-  const outPath = path9.join(outDir, "diagrams.html");
-  fs9.mkdirSync(outDir, { recursive: true });
-  fs9.writeFileSync(outPath, html.replace(/\r\n/g, "\n"), { encoding: "utf-8" });
+  const outPath = path10.join(outDir, "diagrams.html");
+  fs10.mkdirSync(outDir, { recursive: true });
+  fs10.writeFileSync(outPath, html.replace(/\r\n/g, "\n"), { encoding: "utf-8" });
   return ["diagrams.html"];
 }
 
 // lib/knowledge-atlas/src/render/orphan.ts
-var fs10 = __toESM(require("fs"));
-var path10 = __toESM(require("path"));
+var fs11 = __toESM(require("fs"));
+var path11 = __toESM(require("path"));
 function esc9(s) {
   return (s ?? "").toString().replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
@@ -14287,16 +14370,16 @@ function renderOrphanPage(manifest, outDir) {
     ""
     // trailing newline
   ].join("\n");
-  const outPath = path10.join(outDir, "orphans.html");
-  fs10.mkdirSync(outDir, { recursive: true });
-  fs10.writeFileSync(outPath, html.replace(/\r\n/g, "\n"), { encoding: "utf-8" });
+  const outPath = path11.join(outDir, "orphans.html");
+  fs11.mkdirSync(outDir, { recursive: true });
+  fs11.writeFileSync(outPath, html.replace(/\r\n/g, "\n"), { encoding: "utf-8" });
   return ["orphans.html"];
 }
 
 // lib/knowledge-atlas/src/generate.ts
 var MANIFEST_VERSION = 3;
 function normPath(p) {
-  return path11.resolve(p).replace(/[\\/]+$/, "");
+  return path12.resolve(p).replace(/[\\/]+$/, "");
 }
 function pathsEqual(a, b) {
   return normPath(a) === normPath(b);
@@ -14304,7 +14387,7 @@ function pathsEqual(a, b) {
 function isUnder(parent, child) {
   const p = normPath(parent);
   const c = normPath(child);
-  return c.startsWith(p + path11.sep);
+  return c.startsWith(p + path12.sep);
 }
 var MAX_TIME_VALUE_MS = 864e13;
 function resolveTimestamp(now) {
@@ -14345,10 +14428,10 @@ function isoSecond(d) {
   return d.toISOString().replace(/\.\d{3}Z$/, "Z");
 }
 function deriveProjectTitle(projectRoot) {
-  const pkgPath = path11.join(projectRoot, "package.json");
+  const pkgPath = path12.join(projectRoot, "package.json");
   try {
-    if (fs11.existsSync(pkgPath)) {
-      const raw = fs11.readFileSync(pkgPath, "utf-8");
+    if (fs12.existsSync(pkgPath)) {
+      const raw = fs12.readFileSync(pkgPath, "utf-8");
       const pkg = JSON.parse(raw);
       if (typeof pkg["name"] === "string" && pkg["name"].trim()) {
         return pkg["name"].trim();
@@ -14356,13 +14439,13 @@ function deriveProjectTitle(projectRoot) {
     }
   } catch {
   }
-  const base = path11.basename(projectRoot).trim();
+  const base = path12.basename(projectRoot).trim();
   return base.length > 0 ? base : "Unknown Project";
 }
 function extractFileRecord(absPath, fileId, docType, contentHash2) {
   let content = "";
   try {
-    content = fs11.readFileSync(absPath, "utf-8");
+    content = fs12.readFileSync(absPath, "utf-8");
   } catch {
     return { path: fileId, contentHash: contentHash2, type: docType, entities: [], statuses: [], edges: [] };
   }
@@ -14418,19 +14501,19 @@ function generate(opts) {
   if (!projectRoot || typeof projectRoot !== "string") {
     throw new Error("generate: projectRoot is required and must be a non-empty string");
   }
-  if (!path11.isAbsolute(projectRoot)) {
+  if (!path12.isAbsolute(projectRoot)) {
     throw new Error(`generate: projectRoot must be an absolute path (got: ${projectRoot})`);
   }
-  const rootStat = fs11.statSync(projectRoot, { throwIfNoEntry: false });
+  const rootStat = fs12.statSync(projectRoot, { throwIfNoEntry: false });
   if (!rootStat || !rootStat.isDirectory()) {
     throw new Error(`generate: projectRoot does not exist or is not a directory: ${projectRoot}`);
   }
   const { sources, outputFolder, outputOverlap } = resolveKnowledgeSources(projectRoot);
-  const bmadOutputDir = path11.join(projectRoot, outputFolder);
-  const defaultOutDir = path11.join(bmadOutputDir, "knowledge-site");
+  const bmadOutputDir = path12.join(projectRoot, outputFolder);
+  const defaultOutDir = path12.join(bmadOutputDir, "knowledge-site");
   const outDir = outDirOverride ?? defaultOutDir;
-  const rel = path11.relative(projectRoot, outDir);
-  if (rel.startsWith("..") || path11.isAbsolute(rel)) {
+  const rel = path12.relative(projectRoot, outDir);
+  if (rel.startsWith("..") || path12.isAbsolute(rel)) {
     throw new Error(`generate: outDir escapes projectRoot: ${outDir}`);
   }
   const generatedAt = resolveTimestamp(opts.now);
@@ -14441,14 +14524,14 @@ function generate(opts) {
   const isDefaultOut = pathsEqual(outDir, defaultOutDir);
   const sourceAtOrUnderOut = sources.some((s) => pathsEqual(s.absPath, outDir) || isUnder(outDir, s.absPath));
   if (isDefaultOut && !outputOverlap && !sourceAtOrUnderOut) {
-    fs11.rmSync(outDir, { recursive: true, force: true });
+    fs12.rmSync(outDir, { recursive: true, force: true });
   } else if (isDefaultOut && (outputOverlap || sourceAtOrUnderOut)) {
     process.stderr.write(
       `[atlas] WARN: refusing to purge ${outDir} \u2014 a knowledge source resolves at or under it (data-loss guard)
 `
     );
   }
-  fs11.mkdirSync(outDir, { recursive: true });
+  fs12.mkdirSync(outDir, { recursive: true });
   const safeRender = (label, fn) => {
     try {
       return fn();
@@ -14465,7 +14548,7 @@ function generate(opts) {
   const extraFileCount = graphFiles.length + diagramFiles.length + orphanFiles.length;
   const written = renderSite(manifest, outDir, resolveAbsPath);
   writeManifest(outDir, manifest);
-  const indexPath = path11.join(outDir, "index.html");
+  const indexPath = path12.join(outDir, "index.html");
   return {
     outDir,
     indexPath,
@@ -14486,7 +14569,7 @@ function main() {
     usage();
     process.exit(args.length === 0 ? 1 : 0);
   }
-  const projectRoot = path12.resolve(args[0]);
+  const projectRoot = path13.resolve(args[0]);
   let outDir;
   const outIdx = args.indexOf("--out");
   if (outIdx !== -1) {
@@ -14494,7 +14577,7 @@ function main() {
       process.stderr.write("[atlas] ERROR: --out requires a directory argument\n");
       process.exit(1);
     }
-    outDir = path12.resolve(args[outIdx + 1]);
+    outDir = path13.resolve(args[outIdx + 1]);
   }
   try {
     const result = generate({ projectRoot, outDir });

package/lib/knowledge-atlas/src/render/document.ts

@@ -151,12 +151,16 @@ function processMermaidFences(html: string): { html: string; hasMermaid: boolean
   const fenceRe = /<pre><code class="language-mermaid">([\s\S]*?)<\/code><\/pre>/gi;
   const result = html.replace(fenceRe, (_match, codeContent: string) => {
     hasMermaid = true;
-    // codeContent is already HTML-entity-encoded by markdown-it; keep it encoded
-    // (safe) and present it verbatim inside a labelled figure.
+    // `<pre class="mermaid">` is mermaid's default render target: the vendored
+    // runtime (assets/mermaid.min.js, injected by the shell when hasMermaid) reads
+    // the element's textContent — the HTML entities markdown-it emitted decode
+    // back to the literal diagram source — and replaces it with rendered SVG.
+    // With no JS the source stays legible (the plain-text degradation fallback).
+    // linkify skips <pre>, and sanitize preserves `<pre class="…">`, so the
+    // diagram source reaches the browser uncorrupted (no injected <a> tags).
     return [
       '<figure class="mermaid-block" aria-label="Mermaid diagram">',
-      '<figcaption class="mermaid-note">Mermaid diagram (source)</figcaption>',
-      `<div class="mermaid"><pre class="mermaid-fallback">${codeContent.trim()}</pre></div>`,
+      `<pre class="mermaid">${codeContent.trim()}</pre>`,
       '</figure>',
     ].join('\n');
   });
@@ -218,6 +222,10 @@ export interface RenderedDocument {
   html: string;
   /** Plain-text of the rendered article body only (for the search index). */
   articleText: string;
+  /** True if this page contains a mermaid diagram (needs the vendored runtime). */
+  usedMermaid: boolean;
+  /** True if this page is a rendered .drawio diagram (needs the vendored viewer). */
+  usedDrawio: boolean;
 }
 
 export function renderDocumentPage(
@@ -230,6 +238,12 @@ export function renderDocumentPage(
   const absPath = resolveAbsPath?.(fileRec.path) ?? path.join(projectRoot, fileRec.path);
   const title = fileTitle(fileRec.path);
 
+  // draw.io files are mxGraph XML, not markdown — render them via the vendored
+  // GraphViewer instead of the markdown pipeline (which would strip the XML).
+  if (/\.drawio(\.xml)?$/i.test(fileRec.path)) {
+    return renderDrawioPage(fileRec, absPath, title, manifest, navFlags);
+  }
+
   // Read markdown content
   let rawContent = '';
   try {
@@ -258,8 +272,8 @@ export function renderDocumentPage(
   // Add heading anchors for in-page navigation
   renderedHtml = addHeadingAnchors(renderedHtml);
 
-  // Process mermaid fences (rendered as a self-contained plain-text figure)
-  const { html: mermaidHtml } = processMermaidFences(renderedHtml);
+  // Process mermaid fences → live `<pre class="mermaid">` render targets.
+  const { html: mermaidHtml, hasMermaid } = processMermaidFences(renderedHtml);
   renderedHtml = mermaidHtml;
 
   // Rewrite AUTHORED relative markdown cross-links (e.g. `[x](roadmap.md)`)
@@ -314,8 +328,15 @@ export function renderDocumentPage(
     const a = node.anchor;
     if (!a || existingIds.has(a)) continue;
     existingIds.add(a);
-    // First <a> tag whose href ends with this exact anchor fragment.
-    const m = new RegExp('<a\\b[^>]*href="[^"]*#' + escRe(a) + '"', 'i').exec(renderedHtml);
+    const ra = escRe(a);
+    // Prefer the DEFINITION occurrence — a linkified mention immediately followed
+    // by a colon (the BMAD "**FRn:** description" / "## FRn: …" pattern) — over an
+    // earlier passing mention. Without this, an FR that a revision-history /
+    // changelog row lists near the top of the PRD ("…update FR21, FR91…") anchored
+    // there, so clicking the FR jumped to the changelog instead of its definition.
+    let m = new RegExp('<a\\b[^>]*href="[^"]*#' + ra + '"[^>]*>[^<]*</a>\\s*:', 'i').exec(renderedHtml);
+    // Otherwise fall back to the first linkified mention anywhere on the page.
+    if (!m) m = new RegExp('<a\\b[^>]*href="[^"]*#' + ra + '"', 'i').exec(renderedHtml);
     if (m) inlinePlacements.push({ idx: m.index, anchor: a });
     else fallbackAnchors.push(a);
   }
@@ -347,9 +368,19 @@ export function renderDocumentPage(
     '</div>',
   ].filter(Boolean).join('\n');
 
-  // Reading views require zero JS — mermaid is rendered as a plain-text figure
-  // and all links are static HTML (progressive-enhancement baseline, AC 7).
-  // Doc pages live under docs/, so nav/search links need a "../" baseHref.
+  // Reading content is legible with zero JS (progressive-enhancement baseline,
+  // AC 7): all links are static HTML and a mermaid figure degrades to its
+  // legible source. When the page HAS a mermaid diagram we additionally inject
+  // the vendored runtime so it renders to SVG — this is the only script on a
+  // doc page, and only on pages that need it. Doc pages live under docs/, so
+  // nav/search/asset links need a "../" baseHref.
+  const scripts: string[] = [];
+  if (hasMermaid) {
+    scripts.push('<script src="../assets/mermaid.min.js"></script>');
+    scripts.push(
+      '<script>try{mermaid.initialize({startOnLoad:true,securityLevel:"strict",theme:"neutral"});}catch(e){}</script>',
+    );
+  }
   const html = pageShell({
     title,
     body: pageBody,
@@ -357,6 +388,7 @@ export function renderDocumentPage(
     pageType: 'document',
     baseHref: '../',
     navFlags,
+    scripts,
   });
 
   // Article-only plain text for the search index (SF-1): strip tags from the
@@ -367,5 +399,70 @@ export function renderDocumentPage(
     .replace(/\s+/g, ' ')
     .trim();
 
-  return { html, articleText };
+  return { html, articleText, usedMermaid: hasMermaid, usedDrawio: false };
+}
+
+/**
+ * Render a draw.io (`.drawio`) file as a live diagram. draw.io files are
+ * mxGraph XML, not markdown — running them through the markdown/sanitize
+ * pipeline strips every mxGraph tag and yields a blank page. Instead we embed
+ * the raw XML in a draw.io GraphViewer element (`<div class="mxgraph">`) and
+ * load the vendored, URL-neutralized viewer, which renders it to SVG entirely
+ * offline. With no JS the page shows a short note + a link to the source file.
+ */
+function renderDrawioPage(
+  fileRec: FileRecord,
+  absPath: string,
+  title: string,
+  manifest: KnowledgeManifest,
+  navFlags?: NavFlags,
+): RenderedDocument {
+  let xml = '';
+  try {
+    xml = fs.readFileSync(absPath, 'utf-8').replace(/\r\n/g, '\n');
+  } catch {
+    xml = '';
+  }
+
+  // GraphViewer reads a JSON config from data-mxgraph; `xml` carries the source.
+  // esc() HTML-escapes the JSON so the attribute is well-formed; the viewer
+  // HTML-decodes then JSON-parses it back to the original XML.
+  const config = { highlight: '#3572b0', nav: true, resize: true, 'toolbar-nohide': true, toolbar: 'zoom layers', xml };
+  const dataAttr = esc(JSON.stringify(config));
+
+  const body = [
+    '<div class="content-wrap">',
+    '<a class="back-link" href="../index.html">&larr; Back to Home</a>',
+    '<article class="doc-body">',
+    `<h1>${esc(title)}</h1>`,
+    '<figure class="drawio-block" aria-label="draw.io diagram">',
+    xml
+      ? `<div class="mxgraph" style="max-width:100%;border:1px solid var(--border,#ddd);border-radius:6px" data-mxgraph="${dataAttr}"></div>`
+      : '<p><em>(draw.io file could not be read.)</em></p>',
+    '<noscript><p class="mermaid-note">This is a draw.io diagram; enable JavaScript to render it.</p></noscript>',
+    '</figure>',
+    '</article>',
+    '</div>',
+  ].filter(Boolean).join('\n');
+
+  // Predefine the viewer's config globals to inert local values so it never
+  // reaches for a network endpoint (the vendored file's diagrams.net/font/icon
+  // URLs are already neutralized; this belt-and-suspenders covers the `||`
+  // fallbacks, which need a TRUTHY value — "" would fall through to the URL).
+  const scripts = [
+    '<script>window.DRAWIO_BASE_URL=".";window.PROXY_URL=".";window.STYLE_PATH=".";window.RESOURCE_BASE=".";window.SHAPES_PATH=".";window.STENCIL_PATH=".";window.IMAGE_PATH=".";</script>',
+    '<script src="../assets/drawio-viewer.min.js"></script>',
+  ];
+
+  const html = pageShell({
+    title,
+    body,
+    manifest,
+    pageType: 'document',
+    baseHref: '../',
+    navFlags,
+    scripts,
+  });
+
+  return { html, articleText: title, usedMermaid: false, usedDrawio: true };
 }

package/lib/knowledge-atlas/src/render/site.ts

@@ -28,6 +28,7 @@ import * as path from 'path';
 import { pageShell } from './layout.js';
 import type { NavFlags } from './layout.js';
 import { renderDocumentPage } from './document.js';
+import { writeVendorAsset } from './vendor.js';
 import { renderSearchPageHtml } from './search.js';
 import { filePathToSlug, buildSlugMap } from './paths.js';
 import type { KnowledgeManifest, FileRecord } from '../types.js';
@@ -289,19 +290,36 @@ export function renderSite(
     hasOrphansPage: fs.existsSync(path.join(outDir, 'orphans.html')),
   };
 
-  // Step 1: Render document pages (reading views). Zero JS required.
+  // Step 1: Render document pages (reading views). Legible with zero JS; pages
+  // that contain a mermaid diagram additionally load the vendored runtime.
+  let anyMermaid = false;
+  let anyDrawio = false;
   for (const file of manifest.files) {
     const slug = slugMap.get(file.path) ?? filePathToSlug(file.path);
-    const { html, articleText } = renderDocumentPage(file, manifest, manifest.projectRoot, navFlags, resolveAbsPath);
+    const { html, articleText, usedMermaid, usedDrawio } = renderDocumentPage(file, manifest, manifest.projectRoot, navFlags, resolveAbsPath);
     const relPath = `docs/${slug}.html`;
     writeHtml(path.join(outDir, relPath), html);
     written.push(relPath);
+    if (usedMermaid) anyMermaid = true;
+    if (usedDrawio) anyDrawio = true;
 
     // Index ONLY the article text (no nav/footer/TOC/status chrome), so search
     // hits reflect document content rather than shell boilerplate.
     docBodies.set(file.path, articleText);
   }
 
+  // Step 1b: Copy the vendored browser runtimes into assets/ — but only the ones
+  // a page actually references (mermaid runtime / draw.io viewer), so a site with
+  // no such diagrams carries no extra weight.
+  if (anyMermaid) {
+    const rel = writeVendorAsset(outDir, 'mermaid.min.js');
+    if (rel) written.push(rel);
+  }
+  if (anyDrawio) {
+    const rel = writeVendorAsset(outDir, 'drawio-viewer.min.js');
+    if (rel) written.push(rel);
+  }
+
   // Step 2: Render search.html (offline lunr search; PE fallback).
   const searchHtml = renderSearchPageHtml(manifest, docBodies, navFlags);
   writeHtml(path.join(outDir, 'search.html'), searchHtml);