monomind 2.6.1 → 2.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monomind",
-  "version": "2.6.1",
+  "version": "2.7.1",
   "description": "Open-source CLI extension for Claude Code. Adds an MCP server with a codebase knowledge graph, persistent memory, multi-agent coordination, and reusable slash commands. MIT licensed, runs locally, no data leaves your machine.",
   "main": "dist/index.js",
   "type": "module",
@@ -62,8 +62,8 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.207",
-    "@monoes/monobrowse": "^1.0.3",
-    "@monoes/monograph": "^1.5.0",
+    "@monoes/monobrowse": "^1.0.6",
+    "@monoes/monograph": "^1.5.1",
     "@noble/ed25519": "^2.1.0",
     "mammoth": "^1.12.0",
     "pdf-parse": "^2.4.5",

package/packages/@monomind/cli/bin/cli.js

@@ -72,7 +72,22 @@ if (isMCPMode) {
   // (or a slow trickle without newlines) cannot OOM-kill the process.
   const MAX_BUFFER_BYTES = 10 * 1024 * 1024;
   let buffer = '';
+  // Tracks handleMessage() calls still in flight when stdin closes — without
+  // this, 'end' calling process.exit(0) unconditionally could kill the process
+  // mid-handler and silently drop the response a client is still waiting on
+  // (issue #39).
+  let inFlight = 0;
+  let stdinEnded = false;
   process.stdin.setEncoding('utf8');
+  // process.stdout.write() to a pipe is NOT guaranteed synchronous — for a
+  // large payload (e.g. a full tools/list response) the OS write can still be
+  // in flight when the call returns. console.log() doesn't expose that, so
+  // calling process.exit() right after it can truncate/drop the very response
+  // being protected. Wait for the actual flush callback before allowing exit.
+  function writeLine(str) {
+    return new Promise((resolve) => process.stdout.write(str + '\n', resolve));
+  }
+
   process.stdin.on('data', async (chunk) => {
     buffer += chunk;
     if (buffer.length > MAX_BUFFER_BYTES) {
@@ -81,38 +96,51 @@ if (isMCPMode) {
     }
     let lines = buffer.split('\n');
     buffer = lines.pop() || '';
+    const toProcess = lines.filter((line) => line.trim());
+    // Reserve the WHOLE batch synchronously, before any `await` yields control —
+    // otherwise 'end' can fire in the gap between two lines of the same chunk
+    // (inFlight transiently reads 0 after line 1 finishes but before line 2's
+    // own increment runs), exiting mid-batch and dropping the rest silently.
+    inFlight += toProcess.length;
 
-    for (const line of lines) {
-      if (line.trim()) {
-        let parsed;
-        try {
-          parsed = JSON.parse(line);
-        } catch {
-          console.log(JSON.stringify({
-            jsonrpc: '2.0',
-            id: null,
-            error: { code: -32700, message: 'Parse error' },
-          }));
-          continue;
-        }
-        try {
-          const response = await handleMessage(parsed);
-          if (response) {
-            console.log(JSON.stringify(response));
-          }
-        } catch (error) {
-          console.log(JSON.stringify({
-            jsonrpc: '2.0',
-            id: parsed.id ?? null,
-            error: { code: -32603, message: error instanceof Error ? error.message : 'Internal error' },
-          }));
+    for (const line of toProcess) {
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        await writeLine(JSON.stringify({
+          jsonrpc: '2.0',
+          id: null,
+          error: { code: -32700, message: 'Parse error' },
+        }));
+        inFlight--;
+        if (stdinEnded && inFlight === 0) process.exit(0);
+        continue;
+      }
+      try {
+        const response = await handleMessage(parsed);
+        if (response) {
+          await writeLine(JSON.stringify(response));
         }
+      } catch (error) {
+        await writeLine(JSON.stringify({
+          jsonrpc: '2.0',
+          id: parsed.id ?? null,
+          error: { code: -32603, message: error instanceof Error ? error.message : 'Internal error' },
+        }));
+      } finally {
+        inFlight--;
+        if (stdinEnded && inFlight === 0) process.exit(0);
       }
     }
   });
 
   process.stdin.on('end', () => {
-    process.exit(0);
+    stdinEnded = true;
+    if (inFlight === 0) { process.exit(0); return; }
+    // Bounded safety net: don't hang forever if a handler is genuinely stuck.
+    const EXIT_GRACE_MS = 30000;
+    setTimeout(() => process.exit(0), EXIT_GRACE_MS).unref();
   });
 
   async function handleMessage(message) {

package/packages/@monomind/cli/dist/src/init/mcp-generator.js

@@ -49,7 +49,15 @@ export function generateMCPConfig(options) {
             MONOMIND_TOPOLOGY: options.runtime.topology,
             MONOMIND_MAX_AGENTS: String(options.runtime.maxAgents),
             MONOMIND_MEMORY_BACKEND: options.runtime.memoryBackend,
-        }, { autoStart: config.autoStart });
+        }
+        // No `autoStart` here: Claude Code's .mcp.json schema for stdio servers
+        // is only command/args/env — `autoStart` isn't a field it reads, and
+        // nothing in monomind reads it back from this file either (it's a
+        // separate, monomind-internal setting stored in .monomind/config.yaml).
+        // Writing it here was pure dead-end noise in a file whose schema we
+        // don't own — worth removing even though Claude Code likely just
+        // ignores unknown fields, since "likely ignores" isn't "verified inert".
+        );
     }
     // Monograph knowledge graph — built into monomind MCP server since v1.8.0.
     // Available as mcp__monomind__monograph_build, monograph_query, monograph_suggest, monograph_health.

package/packages/@monomind/cli/dist/src/mcp-tools/monograph-tools.d.ts

@@ -5,6 +5,18 @@
  * All monograph_* tools are backed by @monoes/monograph package.
  */
 import type { MCPTool } from './types.js';
+/**
+ * BM25 ranks purely on literal keyword overlap, so a doc/concept node whose
+ * prose happens to mention task-related words (e.g. a report mentioning
+ * "retry" constants) can outrank the actual code symbol the task is really
+ * about, which is conceptually related but lexically different (issue #38).
+ * Prefer code-symbol hits (Function/Class/Method/...) over doc-type hits
+ * (Document/Concept/Section/...) when there are any, falling back to the
+ * full hit list so a genuinely doc-only task still gets results.
+ */
+export declare function preferSymbolHits<T extends {
+    label: string;
+}>(hits: T[], symbolLabels: ReadonlySet<string>): T[];
 /**
  * Full tool list regardless of gating — used by the graphify compat shims,
  * which must resolve targets (e.g. monograph_community) even when the

package/packages/@monomind/cli/dist/src/mcp-tools/monograph-tools.js

@@ -493,6 +493,19 @@ const monographSurprisesTool = {
     },
 };
 // ── monograph_suggest ─────────────────────────────────────────────────────────
+/**
+ * BM25 ranks purely on literal keyword overlap, so a doc/concept node whose
+ * prose happens to mention task-related words (e.g. a report mentioning
+ * "retry" constants) can outrank the actual code symbol the task is really
+ * about, which is conceptually related but lexically different (issue #38).
+ * Prefer code-symbol hits (Function/Class/Method/...) over doc-type hits
+ * (Document/Concept/Section/...) when there are any, falling back to the
+ * full hit list so a genuinely doc-only task still gets results.
+ */
+export function preferSymbolHits(hits, symbolLabels) {
+    const symbolHits = hits.filter(h => symbolLabels.has(h.label));
+    return symbolHits.length > 0 ? symbolHits : hits;
+}
 const monographSuggestTool = {
     name: 'monograph_suggest',
     description: 'Get graph-topology-derived questions to explore the codebase. Pass task= to score by task relevance via BM25/FTS5.',
@@ -554,7 +567,9 @@ const monographSuggestTool = {
             let hitIds = [];
             if (task) {
                 const hits = await hybridQuery(db, task, { limit: 20 });
-                hitIds = [...new Set(hits.map(h => h.id))];
+                const { SYMBOL_NODE_LABELS } = await import('@monoes/monograph');
+                const relevantHits = preferSymbolHits(hits, SYMBOL_NODE_LABELS);
+                hitIds = [...new Set(relevantHits.map(h => h.id))];
                 if (hitIds.length === 0) {
                     return text('No suggestions for this task. Run monograph_build first or try a different query.' + stalenessAnnotation);
                 }

package/packages/@monomind/cli/dist/src/orgrt/daemon.js

@@ -118,7 +118,7 @@ export class OrgDaemon {
             const runtime = { mailbox, policy, status: 'running', done: Promise.resolve() };
             const sessionOpts = {
                 org: name, role, bus, policy, mailbox, cwd, def,
-                maxTurns: def.run_config.max_turns_per_message,
+                maxTurns: role.max_turns_per_message ?? def.run_config.max_turns_per_message,
                 deliver: (from, to, subject, body) => this.deliver(name, from, to, subject, body),
                 askHuman: (r, question) => this.askHuman(name, r, question),
                 onComplete: role.id === bossRole.id

package/packages/@monomind/cli/dist/src/orgrt/types.d.ts

@@ -97,6 +97,10 @@ export declare const RoleSchema: z.ZodObject<{
         webAllow: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
         maxTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
     }, z.ZodTypeAny, "passthrough">>>;
+    /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+     *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+     *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+    max_turns_per_message: z.ZodOptional<z.ZodNumber>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     id: z.ZodString;
     title: z.ZodDefault<z.ZodString>;
@@ -154,6 +158,10 @@ export declare const RoleSchema: z.ZodObject<{
         webAllow: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
         maxTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
     }, z.ZodTypeAny, "passthrough">>>;
+    /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+     *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+     *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+    max_turns_per_message: z.ZodOptional<z.ZodNumber>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     id: z.ZodString;
     title: z.ZodDefault<z.ZodString>;
@@ -211,6 +219,10 @@ export declare const RoleSchema: z.ZodObject<{
         webAllow: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
         maxTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
     }, z.ZodTypeAny, "passthrough">>>;
+    /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+     *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+     *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+    max_turns_per_message: z.ZodOptional<z.ZodNumber>;
 }, z.ZodTypeAny, "passthrough">>;
 export declare const OrgDefSchema: z.ZodObject<{
     name: z.ZodString;
@@ -305,6 +317,10 @@ export declare const OrgDefSchema: z.ZodObject<{
             webAllow: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
             maxTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
         }, z.ZodTypeAny, "passthrough">>>;
+        /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+         *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+         *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+        max_turns_per_message: z.ZodOptional<z.ZodNumber>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         id: z.ZodString;
         title: z.ZodDefault<z.ZodString>;
@@ -362,6 +378,10 @@ export declare const OrgDefSchema: z.ZodObject<{
             webAllow: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
             maxTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
         }, z.ZodTypeAny, "passthrough">>>;
+        /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+         *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+         *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+        max_turns_per_message: z.ZodOptional<z.ZodNumber>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         id: z.ZodString;
         title: z.ZodDefault<z.ZodString>;
@@ -419,6 +439,10 @@ export declare const OrgDefSchema: z.ZodObject<{
             webAllow: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
             maxTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
         }, z.ZodTypeAny, "passthrough">>>;
+        /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+         *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+         *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+        max_turns_per_message: z.ZodOptional<z.ZodNumber>;
     }, z.ZodTypeAny, "passthrough">>, "many">;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     name: z.ZodString;
@@ -513,6 +537,10 @@ export declare const OrgDefSchema: z.ZodObject<{
             webAllow: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
             maxTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
         }, z.ZodTypeAny, "passthrough">>>;
+        /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+         *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+         *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+        max_turns_per_message: z.ZodOptional<z.ZodNumber>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         id: z.ZodString;
         title: z.ZodDefault<z.ZodString>;
@@ -570,6 +598,10 @@ export declare const OrgDefSchema: z.ZodObject<{
             webAllow: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
             maxTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
         }, z.ZodTypeAny, "passthrough">>>;
+        /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+         *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+         *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+        max_turns_per_message: z.ZodOptional<z.ZodNumber>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         id: z.ZodString;
         title: z.ZodDefault<z.ZodString>;
@@ -627,6 +659,10 @@ export declare const OrgDefSchema: z.ZodObject<{
             webAllow: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
             maxTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
         }, z.ZodTypeAny, "passthrough">>>;
+        /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+         *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+         *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+        max_turns_per_message: z.ZodOptional<z.ZodNumber>;
     }, z.ZodTypeAny, "passthrough">>, "many">;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     name: z.ZodString;
@@ -721,6 +757,10 @@ export declare const OrgDefSchema: z.ZodObject<{
             webAllow: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
             maxTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
         }, z.ZodTypeAny, "passthrough">>>;
+        /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+         *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+         *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+        max_turns_per_message: z.ZodOptional<z.ZodNumber>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         id: z.ZodString;
         title: z.ZodDefault<z.ZodString>;
@@ -778,6 +818,10 @@ export declare const OrgDefSchema: z.ZodObject<{
             webAllow: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
             maxTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
         }, z.ZodTypeAny, "passthrough">>>;
+        /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+         *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+         *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+        max_turns_per_message: z.ZodOptional<z.ZodNumber>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         id: z.ZodString;
         title: z.ZodDefault<z.ZodString>;
@@ -835,6 +879,10 @@ export declare const OrgDefSchema: z.ZodObject<{
             webAllow: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
             maxTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
         }, z.ZodTypeAny, "passthrough">>>;
+        /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+         *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+         *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+        max_turns_per_message: z.ZodOptional<z.ZodNumber>;
     }, z.ZodTypeAny, "passthrough">>, "many">;
 }, z.ZodTypeAny, "passthrough">>;
 export type OrgDef = z.infer<typeof OrgDefSchema>;

package/packages/@monomind/cli/dist/src/orgrt/types.js

@@ -32,6 +32,10 @@ export const RoleSchema = z.object({
     }).partial().optional(),
     provider: ProviderSchema.optional(),
     policy: RolePolicySchema.optional(),
+    /** Per-role override of run_config.max_turns_per_message — roles that legitimately
+     *  need many more turns per message (e.g. a developer doing sequential build/fix/verify
+     *  cycles) than others (e.g. docs, pm) shouldn't be forced onto one global budget. */
+    max_turns_per_message: z.number().int().positive().optional(),
 }).passthrough();
 export const OrgDefSchema = z.object({
     name: z.string().min(1),

package/packages/@monomind/cli/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@monoes/monomindcli",
-  "version": "2.6.1",
+  "version": "2.7.1",
   "type": "module",
-  "description": "CLI engine for Monomind \u2014 an open-source MCP server that extends Claude Code with a codebase knowledge graph (tree-sitter + SQLite), persistent memory, multi-agent task coordination, and session hooks. MIT licensed, fully local.",
+  "description": "CLI engine for Monomind — an open-source MCP server that extends Claude Code with a codebase knowledge graph (tree-sitter + SQLite), persistent memory, multi-agent task coordination, and session hooks. MIT licensed, fully local.",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "sideEffects": false,
@@ -95,9 +95,9 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.207",
-    "@monoes/monobrowse": "^1.0.3",
+    "@monoes/monobrowse": "^1.0.6",
     "@monoes/monodesign": "^1.2.0",
-    "@monoes/monograph": "^1.5.0",
+    "@monoes/monograph": "^1.5.1",
     "@noble/ed25519": "^2.1.0",
     "mammoth": "^1.12.0",
     "pdf-parse": "^2.4.5",
@@ -107,9 +107,9 @@
   },
   "optionalDependencies": {
     "@huggingface/transformers": "^3.8.1",
-    "@monoes/memory": "^1.0.10",
     "@monoes/hooks": "^1.0.0",
     "@monoes/mcp": "^1.0.0",
+    "@monoes/memory": "^1.0.10",
     "@monoes/routing": "^1.0.0",
     "monofence-ai": "*",
     "sql.js": "^1.14.1"

package/scripts/growth-content-calendar.mjs

@@ -30,17 +30,20 @@ function parseArticles(text, org) {
     const [, slug, title] = m;
     let heroImage = null;
     let supportingImages = [];
+    let diagrams = [];
     const bodyLines = [];
     for (const line of lines.slice(1)) {
       const heroMatch = line.match(/^HeroImage:\s*(.+?)\s*$/i);
       const suppMatch = line.match(/^SupportingImages:\s*(.+?)\s*$/i);
+      const diagMatch = line.match(/^Diagrams:\s*(.+?)\s*$/i);
       if (heroMatch) { heroImage = heroMatch[1]; continue; }
       if (suppMatch) { supportingImages = suppMatch[1].split(',').map((s) => s.trim()).filter(Boolean); continue; }
+      if (diagMatch) { diagrams = diagMatch[1].split(',').map((s) => s.trim()).filter(Boolean); continue; }
       bodyLines.push(line);
     }
     const body = bodyLines.join('\n').trim();
     if (!body) continue;
-    articles.push({ org, slug: slug.trim(), title: title.trim(), heroImage, supportingImages, body });
+    articles.push({ org, slug: slug.trim(), title: title.trim(), heroImage, supportingImages, diagrams, body });
   }
   return articles;
 }
@@ -80,15 +83,25 @@ function escapeHtml(s) {
   return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
 }
 
-function mdToHtml(md) {
-  // Minimal renderer: paragraphs, headings, code fences, bold/italic, links, tables.
-  return escapeHtml(md)
+function mdToHtml(md, copiedSet) {
+  // Minimal renderer: paragraphs, headings, code fences, bold/italic, inline images, tables.
+  const figures = [];
+  const placeholder = (i) => `[[[FIGURE-${i}]]]`;
+  const withPlaceholders = md.replace(/!\[(.*?)\]\((?:\.\/)?(.*?)\)/g, (_, alt, src) => {
+    const idx = figures.length;
+    const visible = copiedSet.has(src);
+    figures.push(visible ? `<figure class="inline-diagram"><img src="./${escapeHtml(src)}" alt="${escapeHtml(alt)}"><figcaption>${escapeHtml(alt)}</figcaption></figure>` : '');
+    return placeholder(idx);
+  });
+  let html = escapeHtml(withPlaceholders)
     .replace(/^### (.+)$/gm, '<h4>$1</h4>')
     .replace(/^## (.+)$/gm, '<h3>$1</h3>')
     .replace(/^# (.+)$/gm, '<h2>$1</h2>')
     .replace(/```([\s\S]*?)```/g, (_, code) => `<pre><code>${code}</code></pre>`)
     .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
     .replace(/\n\n/g, '</p><p>');
+  figures.forEach((fig, i) => { html = html.replace(placeholder(i), fig); });
+  return html;
 }
 
 function render() {
@@ -121,7 +134,7 @@ function render() {
   // copy every referenced image (article hero/supporting + post images) alongside html/md
   const copied = new Set();
   const allImageNames = new Set([
-    ...articles.flatMap((a) => [a.heroImage, ...a.supportingImages].filter(Boolean)),
+    ...articles.flatMap((a) => [a.heroImage, ...a.supportingImages, ...a.diagrams].filter(Boolean)),
     ...posts.map((p) => p.image).filter(Boolean),
   ]);
   for (const name of allImageNames) {
@@ -172,12 +185,14 @@ function render() {
   function articleCard(a) {
     const img = a.heroImage && copied.has(a.heroImage) ? `<img class="hero" src="./${escapeHtml(a.heroImage)}" alt="">` : '';
     const supp = a.supportingImages.filter((n) => copied.has(n)).map((n) => `<img class="supporting" src="./${escapeHtml(n)}" alt="">`).join('');
+    const missingDiagrams = a.diagrams.filter((n) => !copied.has(n));
     return `<div class="article">
       <div class="article-slug">${escapeHtml(a.slug)}</div>
       <h3 class="article-title">${escapeHtml(a.title)}</h3>
       ${img}
       ${supp ? `<div class="supporting-row">${supp}</div>` : ''}
-      <div class="article-body"><p>${mdToHtml(a.body)}</p></div>
+      <div class="article-body"><p>${mdToHtml(a.body, copied)}</p></div>
+      ${missingDiagrams.length ? `<div class="missing-note">Missing diagram file(s) referenced but not found: ${missingDiagrams.map(escapeHtml).join(', ')}</div>` : ''}
     </div>`;
   }
 
@@ -211,6 +226,11 @@ main { max-width:860px; margin:0 auto; padding:0 1.5rem 4rem; }
 .supporting-row img { width:100%; border-radius:8px; }
 .article-body { font-size:.92rem; color:var(--text); }
 .article-body p { white-space:pre-wrap; }
+.article-body h2, .article-body h3, .article-body h4 { white-space:normal; }
+.inline-diagram { margin:1.2rem 0; }
+.inline-diagram img { width:100%; border-radius:8px; background:var(--espresso); }
+.inline-diagram figcaption { font-size:.78rem; color:var(--muted); margin-top:.3rem; text-align:center; }
+.missing-note { margin-top:1rem; padding:.6rem .8rem; border:1px dashed var(--border); border-radius:8px; font-size:.78rem; color:var(--muted); }
 .card { background:var(--card); border:1px solid var(--border); border-radius:12px; padding:1.1rem 1.3rem; margin-bottom:1rem; }
 .channel { font-size:.72rem; font-weight:700; text-transform:uppercase; letter-spacing:.04em; color:var(--accent); margin-bottom:.6rem; }
 .based-on { font-weight:400; text-transform:none; letter-spacing:0; color:var(--muted); font-style:italic; }
@@ -231,7 +251,10 @@ ${!articles.length && !posts.length ? '<div class="empty">Nothing finalized yet
 </body></html>`;
   fs.writeFileSync(path.join(OUT_DIR, 'content-calendar.html'), html);
 
-  console.log(`Wrote ${articles.length} article(s), ${posts.length} post(s), ${copied.size} image(s) -> ${path.relative(ROOT, OUT_DIR)}`);
+  const totalDiagrams = articles.reduce((n, a) => n + a.diagrams.length, 0);
+  const underDiagrammed = articles.filter((a) => a.diagrams.length < 2).map((a) => a.slug);
+  console.log(`Wrote ${articles.length} article(s), ${posts.length} post(s), ${copied.size} image(s) (incl. ${totalDiagrams} diagram(s)) -> ${path.relative(ROOT, OUT_DIR)}`);
+  if (underDiagrammed.length) console.log(`Note: fewer than 2 diagrams on: ${underDiagrammed.join(', ')}`);
 }
 
 render();