---
name: ADR-0008 Mermaid + Eraser Tool Fit by Diagram Type
description: Defines which tool (Mermaid via mmdc, Eraser via MCP) is the right fit for which diagram-shape category. Mermaid stays source-of-truth for vertical-stack, state-machine, and flow diagrams. Eraser earns its place for cycle visualizations and complex graph hierarchies where its layout and label clarity beats Mermaid's.
type: adr
---

# ADR-0008: Use Mermaid as default; use Eraser for cycle + graph-hierarchy diagrams

- **Date:** 2026-05-04
- **Status:** accepted
- **Reversibility:** high (tool selection is per-diagram; can be re-decided per future diagram without retroactive cost)
- **Deciders:** kit operator
- **Scope:** kit (default policy for all kit diagrams; deployed instances may diverge with their own ADR)

## Context

The kit produces conceptual diagrams to make the operating model legible. Two tool families are now wired in this environment:

1. **Mermaid via mermaid-cli (mmdc).** Text-source DSL; renders to PNG/SVG; runs offline; full control via theme JSON. The kit ships 31 Mermaid blocks in `OPERATING-MODEL.md` + `OPERATING-MODEL-PATTERNS.md`; 9 are polished + 22 are default-rendered into `diagrams/`.
2. **Eraser via MCP (https://app.eraser.io/api/mcp).** AI-assisted diagram generation + a flowchart DSL with auto-layout. OAuth-authenticated; produces PNG via export; cleaner labels and group containers than Mermaid for some shapes.

A test pass during the 2026-05-04 session produced four Eraser samples (test-A layered architecture, test-A v2/v3 forced-single-column attempts, test-B continuous cycle, test-C pod composition recursion) for direct comparison against Mermaid renders of the same content.

The findings were unambiguous: Mermaid and Eraser have non-overlapping sweet spots. Mermaid does single-vertical-stack `graph TD` natively; Eraser's auto-layout fights vertical compression and prefers wide layouts (test-A v3 still split into a horizontal row even with `direction: down` directives at every level). Eraser's `flowchart-diagram` produces visibly cleaner cycle visualizations (test-B) and graph hierarchies with multiple labeled edge types (test-C) than the Mermaid equivalents. Forcing one tool to do the other's work produced visible artifacts (auto-routed arrows passing through node bodies; flat horizontal layouts where vertical was wanted).

This ADR codifies the per-diagram-type allocation so future diagram work doesn't re-debate per batch.

## Decision

Use Mermaid (via `mmdc` and the kit's `diagrams/render-script.py`) as the default for all conceptual diagrams. Use Eraser (via the eraser MCP) for two specific categories where it demonstrably outperforms Mermaid: cycle / state-machine visualizations with prominent loop semantics, and graph hierarchies with three or more labeled edge types. Mermaid remains source-of-truth in the markdown files; Eraser-rendered diagrams are saved as exported PNGs under `diagrams/eraser/` (path created when first Eraser-rendered diagram is promoted from `brainstorming/eraser-renders/`).

## Options considered

### Option A: Mermaid as default; Eraser for cycle + graph hierarchy [CHOSEN]

- **Summary:** Per-diagram-type tool fit. Mermaid handles A, B (state machine), C (flowcharts), D (subgraph reference cards), E (flow), F (graph). Eraser handles future cycle visualizations where Mermaid's default state-machine layout is inadequate and graph-hierarchy diagrams with many edge types where Mermaid's auto-routing produces visual clutter.
- **Pros:** Plays each tool to its strength; Mermaid stays source-of-truth (text-source, version-controlled, diff-able); Eraser earns its keep only where it demonstrably beats Mermaid.
- **Cons:** Two-tool workflow per diagram batch; future operators must know which tool to reach for; Eraser exports are not text-source so they cannot be diff-reviewed.

### Option B: Mermaid only; ignore Eraser

- **Summary:** Stick with Mermaid for everything; accept the layout limitations on cycle and complex hierarchy diagrams.
- **Pros:** Single tool; text-source-only; lowest cognitive load.
- **Cons:** Cycle visualizations (B1, future cycle slides) read as linear-with-loop rather than as actual cycles; complex hierarchies (A2, F-series) accumulate visual clutter at scale.

### Option C: Eraser only; deprecate Mermaid

- **Summary:** Move all 31 source diagrams to Eraser; abandon Mermaid + mmdc.
- **Pros:** Single tool; Eraser's labels and groups are cleaner per-diagram.
- **Cons:** Vertical stacks (A1 layers, D1 layer-by-substrate) cannot be cleanly rendered without hacks (test-A demonstrated this across three iterations); loses text-source-of-truth and git-diff-able sources; introduces external dependency on Eraser's MCP for every diagram operation; subscription cost scales with diagram count.

### Option D: Tool per polish batch; let each batch operator pick

- **Summary:** No locked policy; per-batch judgment.
- **Pros:** Maximum flexibility.
- **Cons:** Re-debate per batch; visual inconsistency across batches; new operators have no guidance.

## Rationale

Option A wins because the test data is unambiguous. The 2026-05-04 session's four Eraser samples directly compared against the equivalent Mermaid renders (`diagrams/polished/` and `diagrams/default/`) showed Mermaid winning vertical stacks (test-A failed three Eraser iterations vs. Mermaid `graph TD` working first try) and Eraser winning cycles (test-B reads as a clear closed loop with explicit phase labels; Mermaid's B1 reads as a state machine diagram with the loop semantics buried) and graph hierarchies (test-C handles four labeled edge types with less visual clutter than Mermaid's equivalent).

Options B and C are single-tool simplifications that ignore the test evidence. Option D guarantees inconsistency. Option A is the only one that respects what the tools actually do well.

The text-source-of-truth concern (Mermaid being diff-able while Eraser exports are not) is mitigated by keeping Mermaid as the default. Eraser-rendered diagrams are limited to the small subset where they genuinely beat Mermaid; the loss of diff-ability for those few diagrams is acceptable in exchange for the visual quality gain.

## Consequences

### Positive

- Per-diagram tool selection is now mechanical; new operators don't have to re-decide.
- The kit ships with both rendering pipelines documented (`diagrams/render-script.py` for Mermaid; future `diagrams/eraser-export-script.py` if scripted, or the Eraser MCP for ad-hoc).
- Visual quality per diagram is maximized within each tool's sweet spot.

### Negative

- Two-tool workflow; operators must know which tool to invoke per diagram-type.
- Eraser exports are PNG-only; no text-source-of-truth in the kit for those specific diagrams. Mitigation: the Eraser file IDs and DSL code are captured in session logs so the diagram can be re-generated if lost.
- Eraser MCP requires OAuth + active subscription; offline / disconnected work cannot produce new Eraser diagrams.

### Followups

- Future cycle and complex-hierarchy diagrams default to Eraser; document the file ID + DSL in the session log when produced.
- If a fourth tool category emerges (e.g., a sequence-diagram tool that beats Mermaid's sequence syntax), this ADR may need supersession.
- The Airtable fork inherits this tool-fit by default; if Airtable's substrate decision rules out Eraser's MCP (e.g., security review fails), the fork supersedes with Mermaid-only and accepts the cycle-visualization tradeoff.

## Reproducibility note

- **Model version:** N/A for Mermaid (deterministic CLI); Eraser uses its own internal AI for `generate` (model version not exposed via MCP)
- **Tool set version:** mermaid-cli 11.14.0; eraser MCP at `https://app.eraser.io/api/mcp`
- **Test artifacts:** `brainstorming/eraser-renders/` (test-A through test-C samples); compared against `diagrams/polished/` and `diagrams/default/`

## Cross-references

- Layer this decision affects: cross-cutting; tooling decision, not a layer decision per se
- Related ADRs: ADR-0007 (visual vocabulary) — together these two define the kit's diagramming posture
- Session log: `sessions/2026-05-04-recompile-prep-eraser-tests-and-batch-render.md` (the session that produced the test evidence)
- Test samples: `brainstorming/eraser-renders/test-A-layered-architecture.png`, `test-A-v2-single-column.png`, `test-A-v3-single-column.png`, `test-B-cycle.png`, `test-C-pod-recursion.png`
- Comparison Mermaid renders: `diagrams/polished/A1.png` (equivalent of test-A), `diagrams/polished/B1.png` (equivalent of test-B), `diagrams/polished/A2.png` (equivalent of test-C)
