kanbango 3.3.0 → 3.4.1

package/.ai/lessons.jsonl

@@ -5,3 +5,4 @@
 {"id":"260731-o6g","ts":"2026-07-31","scope":"proj","tags":["kanban","epics","mcp"],"rule":"DO Default list/list_epics hide done+archived; hard-delete cascades epic children; archive is reversible flag","when":"kanban cleanup context","sev":2,"hits":1}
 {"id":"260803-b27","ts":"2026-08-03","scope":"proj","tags":["tests","race","fs"],"rule":"DO Serialize board file mutations with an in-process lock and atomic write (temp+rename/link); race tests should assert…","when":"kanban concurrent IO","sev":2,"hits":1}
 {"id":"260813-9t0","ts":"2026-08-13","scope":"proj","tags":["mcp","errors","dx"],"rule":"DO MCP missing-field errors: put Valid list + Example JSON + sent keys in message so the agent can retry without guessi…","when":"MCP tool validation / agent-facing erro…","sev":2,"hits":1}
+{"id":"260819-ztl","ts":"2026-08-19","scope":"proj","tags":["config","kanban","validation"],"rule":"DO Field-policy config: skip only ENOENT; invalid JSON/shape must throw CONFIG_INVALID, never silently fall back to def…","when":"config load / required fields","sev":2,"hits":1}

package/.ai/retro/last-run.json

@@ -1 +1 @@
-{"ts":"2026-08-13T06:43:28.413Z","sessionID":"ses_038ddd435ffeginZz7W4t3X27v","added":["260813-9t0"],"bumped":[]}
+{"ts":"2026-08-19T20:04:53.425Z","sessionID":"ses_feb8269efffe9L33YfwuSnVUVa","added":["260819-ztl"],"bumped":[]}

package/.ait-quality.yml

@@ -0,0 +1,25 @@
+# kanbango quality policy
+# CLI/GUI entrypoints use console.log as user-facing output (not debug leftovers).
+version: 1
+include: []
+exclude:
+  - node_modules/**
+  - backlog/**
+  - examples/**
+languages:
+  - javascript
+  - markdown
+rules:
+  enabled: true
+  debug-leftover: off
+  swallowed-exception: error
+  hidden-fallback: error
+  unsafe-pattern: error
+  placeholder-todo: warning
+  dead-code: warning
+  cognitive-complexity: warning
+  function-length: warning
+  nesting-depth: warning
+  duplicate-blocks: warning
+gate:
+  fail_on: error

package/CHANGELOG.md

@@ -7,14 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [3.3.0] - 2026-08-13
+## [3.4.1] - 2026-08-20
+
+### Fixed
+- CLI `kanban mcp` / `npx kanbango mcp` starts the MCP server (was `Unknown command: mcp` → client `-32000 Connection closed`)
+
+## [3.4.0] - 2026-08-20
 
 ### Added
-- Task comments: append-only `comments[]` on tasks; MCP `comment_add` (`task_id` + `text`, optional `author`); CLI `kanban comment <ID> <text> [--author NAME]`
-- Comments included in `execution` / `full` task views (omitted from `summary`)
+- GUI renders fenced ` ```mermaid ` blocks in task Details and epic info panels (flowchart, sequence, gantt, pie, …)
+- Local Mermaid vendor served from `node_modules` (`/vendor/mermaid.min.js`); dual-export fence parser `fenced-text.js`
+- Soft-fail per diagram: broken Mermaid shows source and does not break the board
+- Dependency `mermaid`; tracked `package-lock.json`
+- Tests: `tests/fenced-text.test.js`, `tests/kanban-mermaid-vendor.test.js`
+- In-process lock + atomic writes for create/update/delete (race-safe board mutations)
+- `.ait-quality.yml` project quality policy (CLI `console.log` treated as UX output)
 
-### Fixed
-- MCP `kanban_manage` / `kanban_gui`: missing/empty/unknown `action` errors put a full retry recipe in `message` (Valid list + Example JSON + sent keys); missing/empty use `MISSING_REQUIRED_FIELD` instead of `Unknown action: undefined`
+### Changed
+- Edit mode still shows raw mermaid fences (no live preview)
+
+## [3.3.0] - 2026-08-19
+
+### Note
+- Version 3.3.0 was published on npm; this repo release for Mermaid GUI is **3.4.0**.
 
 ## [3.2.0] - 2026-07-31
 

package/README.md

@@ -152,7 +152,7 @@ Once connected, your agent gets access to these tools:
 | Tool | What it does |
 |------|-------------|
 | `kanban_read` | List/show tasks (`view=summary` by default — cheap) |
-| `kanban_manage` | Create, move, update, comment_add, plan_* workflow |
+| `kanban_manage` | Create, move, update, plan_* workflow |
 | `kanban_gui` | Start / status / stop (stop only kills GUI this MCP started) |
 
 **Token tip for agents:** rules ship inside MCP tool descriptions (`agent-playbook.js`). Optional: `kanban_read` → `operation: "help"`. Human setup notes: [LLM_AGENTS.md](./LLM_AGENTS.md).
@@ -169,8 +169,8 @@ Your agent stays in sync with your real board — every change is persisted as J
 | `kanban show <ID>` | Show task details |
 | `kanban add <TITLE>` | Add a new task |
 | `kanban move <ID> <COL>` | Move task |
+| `kanban mcp` | Start MCP server (stdio) |
 | `kanban mcp-init` | Generate MCP config files |
-| `kanban comment <ID> <text> [--author NAME]` | Append a comment to a task |
 | `kanban plan <action> --json '{...}'` | Accepted-plan workflow (create/advance/evidence/done/status) |
 
 ## Web GUI

package/agent-playbook.js

@@ -10,10 +10,10 @@ const DROP_IN_RULE = [
   '- list: col filter, view=summary; keep task_ids; no full-board re-list after writes',
   '- list_epics default = live only (hides done + archived); include_archived / status to widen',
   '- list tasks default hides tasks under done/archived epics; show/show_epic by id always works',
-  '- show: view=execution while coding (includes comments); full only if needed',
+  '- show: view=execution while coding; full only if needed',
   '- epic_create with description/goals; create tasks with epic=E001 (prefer id)',
   '- create once with description,specs,in_scope,out_of_scope,acceptance_criteria',
-  '- move/update/delete: return=none; subtasks=full array replace; comment_add: task_id+text',
+  '- move/update/delete: return=none; subtasks=full array replace',
   '- cleanup: delete (task), epic_delete (cascade tasks), epic_archive / epic_unarchive',
   '- non-trivial: plan_create → plan_advance → plan_evidence (real tests, truncated logs) → plan_done',
   '- gui: status before start; stop only owned; external_running = do not kill'
@@ -23,7 +23,7 @@ const TOOL_DESCRIPTIONS = {
   kanban_read: [
     'Read board. TOKEN RULES: list defaults to view=summary (id/title/col/progress only).',
     'Hierarchy: epic (container/context) → task (work) → subtasks (steps).',
-    'Always pass col when possible. Prefer show+view=execution over full (includes comments).',
+    'Always pass col when possible. Prefer show+view=execution over full.',
     'list_epics default live only (empty|planned|active; hides done+archived).',
     'Pass include_archived=true or status=done|archived to see closed initiatives.',
     'list hides tasks under done/archived epics unless include_archived/include_done; show/show_epic by id always works.',
@@ -36,13 +36,13 @@ const TOOL_DESCRIPTIONS = {
     'Write board / plan. TOKEN RULES: one create with all planning fields beats many updates;',
     'after write use return=none (or summary). Do not dump full task unless needed.',
     'Actions: create|move|update|delete (daily); epic_create|epic_update|epic_archive|epic_unarchive|epic_delete;',
-    'comment_add (append-only history); plan_create→plan_advance→plan_evidence→plan_done (non-trivial only).',
+    'plan_create→plan_advance→plan_evidence→plan_done (non-trivial only).',
     'epic_create: title + description/goals/in_scope/out_of_scope. Link tasks via epic=E001.',
     'delete: task_id (hard remove). epic_delete: epic_id, always cascades child tasks.',
     'epic_archive/epic_unarchive: epic_id — hide/restore initiative without deleting history.',
     'create/plan_create: title required; also send description,specs,in_scope,out_of_scope,acceptance_criteria',
     '(missing → warnings, not failure). move: task_id+column. update: task_id + fields or subtasks[] full list',
-    '(no toggle). comment_add: task_id+text, optional author. plan_evidence needs real test run: diff,test_command,stdout,stderr,exit_code — truncate logs.',
+    '(no toggle). plan_evidence needs real test run: diff,test_command,stdout,stderr,exit_code — truncate logs.',
     'Example create: {"action":"create","title":"Ship image","epic":"E001","description":"...","specs":"...",',
     '"in_scope":["CLI"],"out_of_scope":["GUI"],"acceptance_criteria":["npm test passes"],"col":"planned"}'
   ].join(' '),
@@ -63,8 +63,7 @@ const MUST_CONTAIN = [
   'subtasks',
   'epic_create',
   'epic_archive',
-  'epic_delete',
-  'comment_add'
+  'epic_delete'
 ];
 
 function playbookHelpPayload() {

package/bin/kanban.js

@@ -336,6 +336,46 @@ function injectProjectIntoHtml(html, project) {
     .replace(/<h1>Donna Kanban<\/h1>/, `<h1>${safe}</h1>`);
 }
 
+/** Allowlisted GUI vendor files only (no open node_modules). */
+const VENDOR_FILES = {
+  '/vendor/fenced-text.js': {
+    filePath: path.join(__dirname, '..', 'fenced-text.js'),
+    contentType: 'application/javascript; charset=utf-8'
+  },
+  '/vendor/mermaid.min.js': {
+    filePath: path.join(__dirname, '..', 'node_modules', 'mermaid', 'dist', 'mermaid.min.js'),
+    contentType: 'application/javascript; charset=utf-8'
+  }
+};
+
+function sendVendorFile(res, requestPath) {
+  const entry = VENDOR_FILES[requestPath];
+  if (!entry) return false;
+  if (!fs.existsSync(entry.filePath)) {
+    sendJson(res, 404, {
+      error: {
+        code: 'VENDOR_MISSING',
+        message: `Vendor file missing: ${requestPath}`,
+        hint: 'Run npm install in the kanbango package root'
+      }
+    });
+    return true;
+  }
+  res.writeHead(200, {
+    'Content-Type': entry.contentType,
+    'Cache-Control': 'public, max-age=3600'
+  });
+  fs.createReadStream(entry.filePath).pipe(res);
+  return true;
+}
+
+function logGuiPortCleanupError(err) {
+  // Port file may already be gone on shutdown — do not block exit.
+  if (err && err.code !== 'ENOENT') {
+    console.error('gui port cleanup:', err.message || err);
+  }
+}
+
 async function serveWeb(port) {
   const htmlTemplate = fs.readFileSync(path.join(__dirname, '..', 'index.html'), 'utf-8');
   const project = guiRegistry.projectLabel();
@@ -352,6 +392,10 @@ async function serveWeb(port) {
         return;
       }
 
+      if (req.method === 'GET' && sendVendorFile(res, requestPath)) {
+        return;
+      }
+
       if (requestPath === '/api/board') {
         await kanban.migrateEpicGroups();
         const includeArchived = url.searchParams.get('include_archived') === 'true';
@@ -579,8 +623,8 @@ async function serveWeb(port) {
   async function cleanupGuiPortFile() {
     try {
       await guiRegistry.clearGuiPortFile({ pid: process.pid });
-    } catch {
-      // best-effort cleanup
+    } catch (err) {
+      logGuiPortCleanupError(err);
     }
   }
 
@@ -705,6 +749,9 @@ async function main() {
     }
 
     await cliMcpInit({ useNpx, onlyClaude, onlyOpenCode, force });
+  } else if (cmd === 'mcp') {
+    const mcpServer = require('../mcp-server.js');
+    await mcpServer.main();
   } else if (cmd === 'migrate') {
     const dryRun = args.includes('--dry-run');
     await cliMigrate(dryRun);
@@ -789,18 +836,6 @@ async function main() {
     await cliAdd(args[1], column, epicGroup);
   } else if (cmd === 'plan' && args[1] && args[2] === '--json') {
     await cliPlan(args[1], parseJsonPayload(args[3]));
-  } else if (cmd === 'comment' && args[1] && args[2]) {
-    let author = 'user';
-    for (let i = 3; i < args.length; i++) {
-      if (args[i] === '--author' && args[i + 1]) author = args[++i];
-    }
-    try {
-      const added = await kanban.addComment(args[1], args[2], author);
-      console.log(JSON.stringify({ ok: true, task_id: added.task_id, comment_id: added.comment.id, count: added.comments.length }));
-    } catch (error) {
-      console.error(`✗ ${error.message}`);
-      process.exit(1);
-    }
   } else {
     console.error('Unknown command:', cmd);
     process.exit(1);

package/fenced-text.js

@@ -0,0 +1,62 @@
+/**
+ * Split plain text into text / mermaid fence segments.
+ * Dual export: CommonJS (Node tests) + browser global FencedText.
+ */
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.FencedText = factory();
+  }
+})(typeof self !== 'undefined' ? self : this, function () {
+  'use strict';
+
+  // ```mermaid ... ``` (language case-insensitive). CRLF ok. Other fences stay plain text.
+  var FENCE_RE = /^```([^\r\n`]*)\r?\n([\s\S]*?)^```[ \t]*\r?$/gm;
+
+  function parseFencedText(text) {
+    var source = text == null ? '' : String(text);
+    if (!source) {
+      return [];
+    }
+
+    var segments = [];
+    var lastIndex = 0;
+    var match;
+    FENCE_RE.lastIndex = 0;
+
+    while ((match = FENCE_RE.exec(source)) !== null) {
+      if (match.index > lastIndex) {
+        segments.push({ type: 'text', value: source.slice(lastIndex, match.index) });
+      }
+
+      var lang = String(match[1] || '').trim().toLowerCase();
+      // Strip optional info string after language (e.g. mermaid title="x")
+      if (lang.indexOf(' ') !== -1) {
+        lang = lang.split(/\s+/)[0];
+      }
+      var body = match[2];
+      if (lang === 'mermaid') {
+        segments.push({ type: 'mermaid', value: body.replace(/\s+$/, '') });
+      } else {
+        segments.push({ type: 'text', value: match[0] });
+      }
+
+      lastIndex = match.index + match[0].length;
+    }
+
+    if (lastIndex < source.length) {
+      segments.push({ type: 'text', value: source.slice(lastIndex) });
+    }
+
+    if (segments.length === 0) {
+      segments.push({ type: 'text', value: source });
+    }
+
+    return segments;
+  }
+
+  return {
+    parseFencedText: parseFencedText
+  };
+});

package/index.html

@@ -614,6 +614,45 @@ header h1 { font-size: 14px; font-weight: 700; letter-spacing: -0.2px; }
   color: var(--text);
   white-space: pre-wrap;
 }
+.detail-text .md-text {
+  white-space: pre-wrap;
+}
+.md-mermaid {
+  margin: 8px 0;
+  padding: 10px;
+  background: #f8fafc;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  overflow-x: auto;
+  text-align: center;
+}
+.md-mermaid svg { max-width: 100%; height: auto; }
+.md-mermaid-error {
+  margin: 8px 0;
+  padding: 8px 10px;
+  background: #fef2f2;
+  border: 1px solid #fecaca;
+  border-radius: var(--radius);
+  text-align: left;
+}
+.md-mermaid-error .md-err-label {
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  color: #b91c1c;
+  margin-bottom: 6px;
+}
+.md-mermaid-error pre {
+  margin: 0;
+  font-size: 11px;
+  line-height: 1.4;
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: var(--text);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+.sl-epic-text .md-mermaid { margin: 6px 0 0; }
 .detail-list {
   margin: 0;
   padding-left: 18px;
@@ -777,6 +816,8 @@ header h1 { font-size: 14px; font-weight: 700; letter-spacing: -0.2px; }
 
 <div class="toast" id="toast"></div>
 
+<script src="/vendor/fenced-text.js"></script>
+<script src="/vendor/mermaid.min.js"></script>
 <script>
 const COL_DEFS = [
   { id: "icebox",  label: "🧊 Icebox",  icon: "🧊" },
@@ -877,6 +918,7 @@ function render() {
   const sl = document.getElementById("swimlanes");
   sl.innerHTML = "";
   groupTasks(allTasks).forEach(g => sl.appendChild(renderSwimlane(g)));
+  queueMermaidRun();
 }
 
 function groupTasks(tasks) {
@@ -924,11 +966,14 @@ function renderEpicDetailView(entity) {
 
   const hero = el("div", "sl-epic-hero");
   const goals = el("div", "sl-epic-goals");
-  goals.innerHTML = `<div class="sl-epic-label">Goals</div>${
-    entity.goals
-      ? `<div class="sl-epic-text">${escHtml(entity.goals)}</div>`
-      : `<div class="sl-epic-text empty">No goals set</div>`
-  }`;
+  goals.appendChild(Object.assign(el("div", "sl-epic-label"), { textContent: "Goals" }));
+  if (entity.goals) {
+    const goalsText = el("div", "sl-epic-text");
+    fillRichText(goalsText, entity.goals);
+    goals.appendChild(goalsText);
+  } else {
+    goals.appendChild(Object.assign(el("div", "sl-epic-text empty"), { textContent: "No goals set" }));
+  }
   hero.appendChild(goals);
 
   const rollup = el("div", "sl-epic-rollup");
@@ -945,13 +990,35 @@ function renderEpicDetailView(entity) {
   const body = el("div", "sl-epic-body");
 
   const descCard = el("div", "sl-epic-card");
-  descCard.innerHTML = `<div class="sl-epic-label">Description</div>${
-    entity.description
-      ? `<div class="sl-epic-text">${escHtml(entity.description)}</div>`
-      : `<div class="sl-epic-text empty">No description yet — click Edit epic to add context for agents.</div>`
-  }`;
+  descCard.appendChild(Object.assign(el("div", "sl-epic-label"), { textContent: "What" }));
+  if (entity.description) {
+    const descText = el("div", "sl-epic-text");
+    fillRichText(descText, entity.description);
+    descCard.appendChild(descText);
+  } else {
+    descCard.appendChild(Object.assign(el("div", "sl-epic-text empty"), {
+      textContent: "No description yet — click Edit epic to add what this initiative does."
+    }));
+  }
   body.appendChild(descCard);
 
+  if (entity.rationale) {
+    const rationaleCard = el("div", "sl-epic-card");
+    rationaleCard.appendChild(Object.assign(el("div", "sl-epic-label"), { textContent: "Rationale" }));
+    const rationaleText = el("div", "sl-epic-text");
+    fillRichText(rationaleText, entity.rationale);
+    rationaleCard.appendChild(rationaleText);
+    body.appendChild(rationaleCard);
+  }
+  if (entity.outcome) {
+    const outcomeCard = el("div", "sl-epic-card");
+    outcomeCard.appendChild(Object.assign(el("div", "sl-epic-label"), { textContent: "Outcome" }));
+    const outcomeText = el("div", "sl-epic-text");
+    fillRichText(outcomeText, entity.outcome);
+    outcomeCard.appendChild(outcomeText);
+    body.appendChild(outcomeCard);
+  }
+
   const scopeCard = el("div", "sl-epic-card scope-pair");
   scopeCard.innerHTML = `
     <div>
@@ -968,7 +1035,10 @@ function renderEpicDetailView(entity) {
 
   if (entity.notes) {
     const notes = el("div", "sl-epic-card sl-epic-notes");
-    notes.innerHTML = `<div class="sl-epic-label">Notes</div><div class="sl-epic-text">${escHtml(entity.notes)}</div>`;
+    notes.appendChild(Object.assign(el("div", "sl-epic-label"), { textContent: "Notes" }));
+    const notesText = el("div", "sl-epic-text");
+    fillRichText(notesText, entity.notes);
+    notes.appendChild(notesText);
     panel.appendChild(notes);
   }
 
@@ -980,6 +1050,8 @@ function renderEpicDetailEdit(entity) {
   const dirty = dirtyEpicEdits[entity.id] || {
     title: entity.title || "",
     description: entity.description || "",
+    rationale: entity.rationale || "",
+    outcome: entity.outcome || "",
     goals: entity.goals || "",
     in_scope: (entity.in_scope || []).join("\n"),
     out_of_scope: (entity.out_of_scope || []).join("\n"),
@@ -1010,15 +1082,33 @@ function renderEpicDetailEdit(entity) {
   grid.appendChild(goalsWrap);
 
   const descWrap = el("div", "span2");
-  descWrap.innerHTML = `<label>Description</label>`;
+  descWrap.innerHTML = `<label>What</label>`;
   const descTa = document.createElement("textarea");
   descTa.value = dirty.description;
-  descTa.placeholder = "Context for agents…";
+  descTa.placeholder = "What this initiative does…";
   descTa.style.minHeight = "72px";
   descTa.oninput = () => { dirty.description = descTa.value; dirtyEpicEdits[entity.id] = dirty; };
   descWrap.appendChild(descTa);
   grid.appendChild(descWrap);
 
+  const rationaleWrap = el("div", "span2");
+  rationaleWrap.innerHTML = `<label>Rationale</label>`;
+  const rationaleTa = document.createElement("textarea");
+  rationaleTa.value = dirty.rationale;
+  rationaleTa.placeholder = "Why this approach, not alternatives…";
+  rationaleTa.oninput = () => { dirty.rationale = rationaleTa.value; dirtyEpicEdits[entity.id] = dirty; };
+  rationaleWrap.appendChild(rationaleTa);
+  grid.appendChild(rationaleWrap);
+
+  const outcomeWrap = el("div", "span2");
+  outcomeWrap.innerHTML = `<label>Outcome</label>`;
+  const outcomeTa = document.createElement("textarea");
+  outcomeTa.value = dirty.outcome;
+  outcomeTa.placeholder = "Intended effect / goal…";
+  outcomeTa.oninput = () => { dirty.outcome = outcomeTa.value; dirtyEpicEdits[entity.id] = dirty; };
+  outcomeWrap.appendChild(outcomeTa);
+  grid.appendChild(outcomeWrap);
+
   const inWrap = el("div", "");
   inWrap.innerHTML = `<label>In scope (one per line)</label>`;
   const inTa = document.createElement("textarea");
@@ -1074,6 +1164,8 @@ async function saveEpicEdit(epicId) {
     body: JSON.stringify({
       title: dirty.title.trim(),
       description: dirty.description,
+      rationale: dirty.rationale,
+      outcome: dirty.outcome,
       goals: dirty.goals,
       in_scope: splitLines(dirty.in_scope),
       out_of_scope: splitLines(dirty.out_of_scope),
@@ -1371,6 +1463,8 @@ function renderEditMode(card, epic, colId, shortId) {
   const dirty = dirtyEdits[epic.id] || {
     title: displayTitle,
     description: epic.description || "",
+    rationale: epic.rationale || "",
+    outcome: epic.outcome || "",
     specs: epic.specs || "",
     in_scope: (epic.in_scope || []).join("\n"),
     out_of_scope: (epic.out_of_scope || []).join("\n"),
@@ -1395,14 +1489,22 @@ function renderEditMode(card, epic, colId, shortId) {
   card.appendChild(titleInput);
 
   const meta = el("div", "edit-meta");
-  meta.appendChild(renderEditBlock("Description", dirty.description, value => {
+  meta.appendChild(renderEditBlock("What", dirty.description, value => {
     dirty.description = value;
     dirtyEdits[epic.id] = dirty;
-  }, "Context and implementation plan..."));
+  }, "What we are doing..."));
+  meta.appendChild(renderEditBlock("Rationale", dirty.rationale, value => {
+    dirty.rationale = value;
+    dirtyEdits[epic.id] = dirty;
+  }, "Why this approach, not alternatives..."));
+  meta.appendChild(renderEditBlock("Outcome", dirty.outcome, value => {
+    dirty.outcome = value;
+    dirtyEdits[epic.id] = dirty;
+  }, "Intended effect / goal..."));
   meta.appendChild(renderEditBlock("Specs", dirty.specs, value => {
     dirty.specs = value;
     dirtyEdits[epic.id] = dirty;
-  }, "APIs, constraints, edge cases..."));
+  }, "APIs, constraints, edge cases (how)..."));
   meta.appendChild(renderEditBlock("In Scope", dirty.in_scope, value => {
     dirty.in_scope = value;
     dirtyEdits[epic.id] = dirty;
@@ -1531,6 +1633,8 @@ async function saveEdit(epicId) {
     const origTitle = epic.title.replace(/^[\w.-]+:\s*/, "");
     if (dirty.title !== origTitle) body.title = dirty.title;
     body.description = dirty.description;
+    body.rationale = dirty.rationale;
+    body.outcome = dirty.outcome;
     body.specs = dirty.specs;
     body.in_scope = splitLines(dirty.in_scope);
     body.out_of_scope = splitLines(dirty.out_of_scope);
@@ -1728,7 +1832,13 @@ function splitLines(value) {
 }
 function appendDetailSections(card, epic) {
   if (epic.description) {
-    card.appendChild(renderDetailSection("Description", epic.description));
+    card.appendChild(renderDetailSection("What", epic.description));
+  }
+  if (epic.rationale) {
+    card.appendChild(renderDetailSection("Rationale", epic.rationale));
+  }
+  if (epic.outcome) {
+    card.appendChild(renderDetailSection("Outcome", epic.outcome));
   }
   if (epic.specs) {
     card.appendChild(renderDetailSection("Specs", epic.specs));
@@ -1754,11 +1864,130 @@ function renderDetailSection(label, text) {
   const labelEl = el("div", "detail-label");
   labelEl.textContent = label;
   const textEl = el("div", "detail-text");
-  textEl.textContent = text;
+  fillRichText(textEl, text);
   wrap.appendChild(labelEl);
   wrap.appendChild(textEl);
   return wrap;
 }
+
+// ── Mermaid in detail fields (view mode only) ─────────────────────────────────
+
+let mermaidReady = false;
+let mermaidRunTimer = null;
+let mermaidSeq = 0;
+
+function parseFencedSegments(text) {
+  if (window.FencedText && typeof window.FencedText.parseFencedText === "function") {
+    return window.FencedText.parseFencedText(text);
+  }
+  return text ? [{ type: "text", value: String(text) }] : [];
+}
+
+function fillRichText(container, text) {
+  container.textContent = "";
+  const segments = parseFencedSegments(text);
+  if (segments.length === 0) return;
+
+  segments.forEach(seg => {
+    if (seg.type === "mermaid") {
+      const box = el("div", "md-mermaid");
+      box.dataset.mermaidSource = seg.value;
+      const pre = document.createElement("pre");
+      pre.className = "mermaid";
+      pre.textContent = seg.value;
+      box.appendChild(pre);
+      container.appendChild(box);
+    } else if (seg.value) {
+      const span = el("div", "md-text");
+      span.textContent = seg.value;
+      container.appendChild(span);
+    }
+  });
+}
+
+function showMermaidFallback(box, source, err) {
+  box.className = "md-mermaid-error";
+  box.textContent = "";
+  const label = el("div", "md-err-label");
+  label.textContent = err && err.message
+    ? `Mermaid error: ${err.message}`
+    : "Mermaid render failed";
+  const pre = document.createElement("pre");
+  pre.textContent = source || box.dataset.mermaidSource || "";
+  box.appendChild(label);
+  box.appendChild(pre);
+}
+
+function ensureMermaidInit() {
+  if (mermaidReady) return true;
+  if (typeof mermaid === "undefined" || !mermaid) return false;
+  try {
+    mermaid.initialize({
+      startOnLoad: false,
+      securityLevel: "strict",
+      theme: "neutral"
+    });
+    mermaidReady = true;
+    return true;
+  } catch (err) {
+    console.error("mermaid.initialize failed", err);
+    return false;
+  }
+}
+
+async function runMermaidIn(root) {
+  const scope = root || document;
+  const nodes = [...scope.querySelectorAll("pre.mermaid")].filter(
+    n => !n.dataset.processed && n.textContent.trim()
+  );
+  if (nodes.length === 0) return;
+
+  if (!ensureMermaidInit()) {
+    nodes.forEach(pre => {
+      const box = pre.closest(".md-mermaid") || pre.parentElement;
+      if (box) showMermaidFallback(box, pre.textContent, new Error("mermaid library not loaded"));
+    });
+    return;
+  }
+
+  // Prefer per-node render so one bad diagram never blocks siblings.
+  for (const pre of nodes) {
+    const source = pre.textContent;
+    const box = pre.closest(".md-mermaid") || pre.parentElement;
+    const id = `mmd-${Date.now()}-${++mermaidSeq}`;
+    try {
+      const out = await mermaid.render(id, source);
+      // Board re-render may detach this node while await was in flight.
+      if (!pre.isConnected) continue;
+      const svg = typeof out === "string" ? out : (out && out.svg);
+      if (!svg) throw new Error("empty mermaid output");
+      if (box && box.isConnected) {
+        box.innerHTML = svg;
+        box.dataset.processed = "1";
+      } else if (pre.isConnected) {
+        pre.outerHTML = svg;
+      }
+    } catch (err) {
+      // Remove orphaned error SVG mermaid may leave in <body>
+      const stray = document.getElementById(id);
+      if (stray) stray.remove();
+      const strayD = document.getElementById("d" + id);
+      if (strayD) strayD.remove();
+      if (box) showMermaidFallback(box, source, err);
+      else {
+        pre.dataset.processed = "error";
+        pre.title = (err && err.message) || "mermaid error";
+      }
+    }
+  }
+}
+
+function queueMermaidRun(root) {
+  clearTimeout(mermaidRunTimer);
+  mermaidRunTimer = setTimeout(() => {
+    runMermaidIn(root).catch(err => console.error("mermaid run failed", err));
+  }, 0);
+}
 function renderDetailListSection(label, items, extraClass) {
   const wrap = el("div", extraClass ? `detail-section ${extraClass}` : "detail-section");
   const labelEl = el("div", "detail-label");

package/kanban.js

@@ -41,8 +41,7 @@ const VIEW_FIELDS = {
     'out_of_scope',
     'acceptance_criteria',
     'test_cases',
-    'subtasks',
-    'comments'
+    'subtasks'
   ],
   full: [
     'task_number',
@@ -59,8 +58,7 @@ const VIEW_FIELDS = {
     'acceptance_criteria',
     'test_cases',
     'subtasks',
-    'notes',
-    'comments'
+    'notes'
   ]
 };
 
@@ -255,28 +253,6 @@ function normalizeSubtasks(value) {
   })).filter((subtask) => subtask.text);
 }
 
-function nowIso() {
-  return new Date().toISOString();
-}
-
-function nextCommentId(comments) {
-  const max = comments.reduce((highest, comment) => {
-    const match = String(comment && comment.id || '').match(/^c-(\d+)$/i);
-    return match ? Math.max(highest, parseInt(match[1], 10)) : highest;
-  }, 0);
-  return `c-${max + 1}`;
-}
-
-function normalizeComments(value) {
-  if (!Array.isArray(value)) return [];
-  return value.map((item, idx) => ({
-    id: normalizeString(item && item.id, `c-${idx + 1}`),
-    created: normalizeString(item && item.created) || nowIso(),
-    author: normalizeString(item && item.author, 'user') || 'user',
-    text: normalizeString(item && item.text)
-  })).filter((item) => item.text);
-}
-
 function normalizeEvidence(value) {
   if (!Array.isArray(value)) return [];
   return value.map((item) => ({
@@ -316,7 +292,6 @@ function normalizeTask(task) {
     test_cases: normalizeStringArray(task.test_cases),
     subtasks: normalizeSubtasks(task.subtasks),
     notes: normalizeString(task.notes),
-    comments: normalizeComments(task.comments),
     plan: normalizePlan(task.plan),
     evidence: normalizeEvidence(task.evidence),
     task_number: extractTaskNumber(id)
@@ -342,7 +317,6 @@ function serializeTask(task) {
     test_cases: normalized.test_cases,
     subtasks: normalized.subtasks,
     notes: normalized.notes,
-    comments: normalized.comments,
     plan: normalized.plan,
     evidence: normalized.evidence,
     task_number: normalized.task_number
@@ -1341,7 +1315,6 @@ async function doCreate(title, column = 'planned', epicRef = '—', extra = {})
         test_cases: extra.test_cases,
         subtasks: extra.subtasks,
         notes: extra.notes,
-        comments: extra.comments,
         plan: extra.plan,
         evidence: extra.evidence
       });
@@ -1488,19 +1461,6 @@ async function updateTaskRecord(taskId, patch) {
     next.subtasks = patch.subtasks;
   }
   if (patch.notes !== undefined) next.notes = normalizeString(patch.notes);
-  if (patch.comments !== undefined) {
-    if (!Array.isArray(patch.comments)) {
-      throw createKanbanError(
-        'VALIDATION_ERROR',
-        'comments must be an array',
-        'Send comments as an array of comment objects',
-        { field: 'comments' },
-        false,
-        400
-      );
-    }
-    next.comments = patch.comments;
-  }
   if (patch.plan !== undefined) next.plan = patch.plan;
   if (patch.evidence !== undefined) {
     if (!Array.isArray(patch.evidence)) {
@@ -1524,44 +1484,6 @@ async function updateTask(taskId, patch) {
   return withBoardLock(() => updateTaskRecord(taskId, patch));
 }
 
-async function addComment(taskId, text, author = 'user') {
-  const body = normalizeString(text);
-  if (!body) {
-    throw createKanbanError(
-      'MISSING_REQUIRED_FIELD',
-      'text is required',
-      'Provide a non-empty comment text',
-      { field: 'text' },
-      false,
-      400
-    );
-  }
-  return withBoardLock(async () => {
-    const resolvedId = await resolveTaskId(taskId);
-    const previousFilePath = await findFile(resolvedId);
-    if (!previousFilePath) {
-      throw createKanbanError(
-        'TASK_NOT_FOUND',
-        `Task ${taskId} was not found`,
-        'Call kanban_read with operation=list to discover valid task ids',
-        { task_id: taskId },
-        false,
-        404
-      );
-    }
-    const current = await parseEpic(previousFilePath, path.basename(path.dirname(previousFilePath)));
-    const comments = normalizeComments(current.comments);
-    const comment = {
-      id: nextCommentId(comments),
-      created: nowIso(),
-      author: normalizeString(author, 'user') || 'user',
-      text: body
-    };
-    const saved = await writeTask({ ...current, comments: [...comments, comment] }, previousFilePath);
-    return { comment, comments: saved.comments, task_id: saved.id };
-  });
-}
-
 async function doMove(epicId, target) {
   try {
     await updateTask(epicId, { column: target });
@@ -1627,7 +1549,6 @@ module.exports = {
   shapeTask,
   shapeEpic,
   updateTask,
-  addComment,
   migrateAll,
   migrateEpicGroups,
   doMove,

package/mcp-server.js

@@ -76,101 +76,6 @@ function invalidRequest(message, hint, details) {
   return kanban.createKanbanError('VALIDATION_ERROR', message, hint, details, false, 400);
 }
 
-const MANAGE_ACTIONS = [
-  'create',
-  'move',
-  'update',
-  'delete',
-  'epic_create',
-  'epic_update',
-  'epic_archive',
-  'epic_unarchive',
-  'epic_delete',
-  'plan_create',
-  'plan_advance',
-  'plan_evidence',
-  'plan_done',
-  'plan_status',
-  'comment_add'
-];
-
-const GUI_ACTIONS = ['start', 'stop', 'status'];
-
-const ACTION_EXAMPLES = {
-  kanban_manage: '{"action":"create","title":"Ship image","col":"planned"}',
-  kanban_gui: '{"action":"status"}'
-};
-
-function receivedKeys(args) {
-  return Object.keys(args && typeof args === 'object' ? args : {});
-}
-
-function actionRecipeMessage(toolName, allowed, opts = {}) {
-  const keys = opts.received_keys || [];
-  const example = ACTION_EXAMPLES[toolName] || `{"action":"${allowed[0]}"}`;
-  const lines = [];
-
-  if (opts.kind === 'unknown') {
-    lines.push(`Unknown action "${opts.action}" on ${toolName}.`);
-  } else {
-    lines.push(`Missing required top-level field "action" on ${toolName}.`);
-  }
-
-  lines.push('Pass action next to other args (not nested under params).');
-  lines.push(`Valid: ${allowed.join(', ')}.`);
-  lines.push(`Example: ${example}`);
-  lines.push(keys.length > 0 ? `You sent keys: ${keys.join(', ')}` : 'You sent keys: (none)');
-  return lines.join(' ');
-}
-
-function actionRecipeHint() {
-  return [
-    'Retry the same tool with top-level action set to one Valid value.',
-    'Common mistake: omitting action, or putting it under params (jira/gitlab style) — kanban uses top-level action.'
-  ].join(' ');
-}
-
-function requireToolAction(args, allowed, toolName) {
-  const action = args && args.action;
-  const keys = receivedKeys(args);
-  if (action === undefined || action === null || action === '') {
-    throw kanban.createKanbanError(
-      'MISSING_REQUIRED_FIELD',
-      actionRecipeMessage(toolName, allowed, {
-        kind: 'missing',
-        received_keys: keys,
-        action: action === undefined ? null : action
-      }),
-      actionRecipeHint(),
-      {
-        field: 'action',
-        tool: toolName,
-        received_keys: keys,
-        allowed_actions: allowed,
-        action: action === undefined ? null : action
-      },
-      false,
-      400
-    );
-  }
-  return action;
-}
-
-function unknownToolAction(action, args, allowed, toolName) {
-  const keys = receivedKeys(args);
-  return invalidRequest(
-    actionRecipeMessage(toolName, allowed, { kind: 'unknown', action, received_keys: keys }),
-    actionRecipeHint(),
-    {
-      field: 'action',
-      tool: toolName,
-      action,
-      received_keys: keys,
-      allowed_actions: allowed
-    }
-  );
-}
-
 function serializeResult(result) {
   if (typeof result === 'string') return result;
 
@@ -465,8 +370,23 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             action: {
               type: 'string',
-              enum: MANAGE_ACTIONS,
-              description: 'create|move|update|delete daily; epic_*; plan_*; comment_add'
+              enum: [
+                'create',
+                'move',
+                'update',
+                'delete',
+                'epic_create',
+                'epic_update',
+                'epic_archive',
+                'epic_unarchive',
+                'epic_delete',
+                'plan_create',
+                'plan_advance',
+                'plan_evidence',
+                'plan_done',
+                'plan_status'
+              ],
+              description: 'create|move|update|delete daily; epic_create|epic_update|epic_archive|epic_unarchive|epic_delete; plan_* multi-step'
             },
             title: {
               type: 'string',
@@ -536,17 +456,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: 'string',
               description: 'Freeform notes'
             },
-            text: {
-              type: 'string',
-              description: 'Required for comment_add. Non-empty comment body.'
-            },
-            author: {
-              type: 'string',
-              description: 'Optional comment author (default user). e.g. kocur-reviewer, worker'
-            },
             task_id: {
               type: 'string',
-              description: "Required for move/update/delete/comment_add/plan_* except plan_create. '014' or '14'."
+              description: "Required for move/update/delete/plan_* except plan_create. '014' or '14'."
             },
             column: {
               type: 'string',
@@ -608,7 +520,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             action: {
               type: 'string',
-              enum: GUI_ACTIONS,
+              enum: ['start', 'stop', 'status'],
               description: 'start | stop (owned only) | status'
             },
             port: {
@@ -714,7 +626,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'kanban_manage': {
-        const action = requireToolAction(args, MANAGE_ACTIONS, 'kanban_manage');
+        const action = args.action;
         const returnShape = normalizeReturnShape(args.return);
 
         switch (action) {
@@ -912,38 +824,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             result = await plan.status(args.task_id);
             break;
 
-          case 'comment_add': {
-            if (!args.task_id) {
-              throw invalidRequest(
-                "task_id is required for 'comment_add'",
-                'Provide a task ID',
-                { action }
-              );
-            }
-            if (!args.text) {
-              throw invalidRequest(
-                "text is required for 'comment_add'",
-                'Provide a non-empty comment body',
-                { action }
-              );
-            }
-            const added = await kanban.addComment(args.task_id, args.text, args.author);
-            result = returnShape === 'none'
-              ? { ok: true, comment_id: added.comment.id }
-              : returnShape === 'full'
-                ? added
-                : { ok: true, task_id: added.task_id, comment_id: added.comment.id, count: added.comments.length };
-            break;
-          }
-
           default:
-            throw unknownToolAction(action, args, MANAGE_ACTIONS, 'kanban_manage');
+            throw invalidRequest(
+              `Unknown action: ${action}`,
+              'Use create, move, update, delete, epic_create, epic_update, epic_archive, epic_unarchive, epic_delete, plan_create, plan_advance, plan_evidence, plan_done, or plan_status',
+              { action }
+            );
         }
         break;
       }
 
       case 'kanban_gui': {
-        const action = requireToolAction(args, GUI_ACTIONS, 'kanban_gui');
+        const action = args.action;
 
         switch (action) {
           case 'start': {
@@ -959,7 +851,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             break;
           }
           default:
-            throw unknownToolAction(action, args, GUI_ACTIONS, 'kanban_gui');
+            throw invalidRequest(
+              `Unknown action: ${action}`,
+              'Use one of: start, stop, status',
+              { action }
+            );
         }
         break;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kanbango",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "description": "JSON-first local Kanban board with web GUI, CLI, and MCP server",
   "main": "index.js",
   "bin": {
@@ -36,6 +36,7 @@
     "node": ">=16.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4"
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "mermaid": "^11.17.0"
   }
 }

package/tests/run.js

@@ -15,10 +15,11 @@ function runNode(scriptPath, args, label) {
 
 runNode(path.join('bin', 'kanban.js'), ['list', '--json'], 'CLI list');
 runNode(path.join('tests', 'update-tasks.test.js'), [], 'Update tasks test');
-runNode(path.join('tests', 'comments.test.js'), [], 'Comments test');
 runNode(path.join('tests', 'read-views.test.js'), [], 'Read views test');
 runNode(path.join('tests', 'mcp-server.test.js'), [], 'MCP server test');
 runNode(path.join('tests', 'gui-port.test.js'), [], 'GUI port test');
+runNode(path.join('tests', 'fenced-text.test.js'), [], 'Fenced text test');
+runNode(path.join('tests', 'kanban-mermaid-vendor.test.js'), [], 'Kanban mermaid vendor route test');
 runNode(path.join('tests', 'plan-workflow.test.js'), [], 'Plan workflow test');
 runNode(path.join('tests', 'agent-playbook.test.js'), [], 'Agent playbook test');
 runNode(path.join('tests', 'epics.test.js'), [], 'Epics test');

package/.opencode/plans/action-error-recipe.md

@@ -1,121 +0,0 @@
-# Action error recipe (implement)
-
-Status: approved (user said go). Plan mode blocked code edits — switch to **build** and apply.
-
-## Goal
-Missing/empty/unknown `action` on `kanban_manage` / `kanban_gui`: **message** is a full retry recipe (Valid + Example JSON + sent keys).
-
-## Files
-1. `mcp-server.js` — replace `requireToolAction`; add helpers; unknown-action defaults
-2. `tests/mcp-server.test.js` — assert recipe content
-3. `CHANGELOG.md` — one-line unreleased note
-
-## mcp-server.js
-
-Replace current `requireToolAction` block (after `GUI_ACTIONS`) with:
-
-```js
-const ACTION_EXAMPLES = {
-  kanban_manage: '{"action":"create","title":"Ship image","col":"planned"}',
-  kanban_gui: '{"action":"status"}'
-};
-
-function receivedKeys(args) {
-  return Object.keys(args && typeof args === 'object' ? args : {});
-}
-
-function actionRecipeMessage(toolName, allowed, opts = {}) {
-  const keys = opts.received_keys || [];
-  const example = ACTION_EXAMPLES[toolName] || `{"action":"${allowed[0]}"}`;
-  const lines = [];
-  if (opts.kind === 'unknown') {
-    lines.push(`Unknown action "${opts.action}" on ${toolName}.`);
-  } else {
-    lines.push(`Missing required top-level field "action" on ${toolName}.`);
-  }
-  lines.push('Pass action next to other args (not nested under params).');
-  lines.push(`Valid: ${allowed.join(', ')}.`);
-  lines.push(`Example: ${example}`);
-  lines.push(keys.length > 0 ? `You sent keys: ${keys.join(', ')}` : 'You sent keys: (none)');
-  return lines.join(' ');
-}
-
-function actionRecipeHint() {
-  return [
-    'Retry the same tool with top-level action set to one Valid value.',
-    'Common mistake: omitting action, or putting it under params (jira/gitlab style) — kanban uses top-level action.'
-  ].join(' ');
-}
-
-function requireToolAction(args, allowed, toolName) {
-  const action = args && args.action;
-  const keys = receivedKeys(args);
-  if (action === undefined || action === null || action === '') {
-    throw kanban.createKanbanError(
-      'MISSING_REQUIRED_FIELD',
-      actionRecipeMessage(toolName, allowed, {
-        kind: 'missing',
-        received_keys: keys,
-        action: action === undefined ? null : action
-      }),
-      actionRecipeHint(),
-      {
-        field: 'action',
-        tool: toolName,
-        received_keys: keys,
-        allowed_actions: allowed,
-        action: action === undefined ? null : action
-      },
-      false,
-      400
-    );
-  }
-  return action;
-}
-
-function unknownToolAction(action, args, allowed, toolName) {
-  const keys = receivedKeys(args);
-  return invalidRequest(
-    actionRecipeMessage(toolName, allowed, { kind: 'unknown', action, received_keys: keys }),
-    actionRecipeHint(),
-    {
-      field: 'action',
-      tool: toolName,
-      action,
-      received_keys: keys,
-      allowed_actions: allowed
-    }
-  );
-}
-```
-
-Manage default: `throw unknownToolAction(action, args, MANAGE_ACTIONS, 'kanban_manage');`  
-GUI default: `throw unknownToolAction(action, args, GUI_ACTIONS, 'kanban_gui');`
-
-## tests/mcp-server.test.js
-
-Assert on missing/empty/unknown/gui:
-- message includes `Missing required top-level field "action"` (or `Unknown action "nope"`)
-- `Valid:` + key actions + `Example:` + `"action":`
-- sent keys line
-- `details.allowed_actions`
-- no `undefined` in message
-- codes unchanged: MISSING_REQUIRED_FIELD / VALIDATION_ERROR
-
-## CHANGELOG
-
-```md
-### Fixed
-- MCP `kanban_manage` / `kanban_gui`: missing/empty/unknown `action` errors put a full retry recipe in `message` (Valid list + Example JSON + sent keys); missing/empty use `MISSING_REQUIRED_FIELD` instead of `Unknown action: undefined`
-```
-
-## Verify
-```bash
-node tests/mcp-server.test.js
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"kanban_manage","arguments":{"title":"x"}}}' | node mcp-server.js
-```
-
-## Acceptance
-- [ ] Missing action message is copy-paste retry recipe
-- [ ] Unknown action same clarity
-- [ ] Tests green