Use only when diagrams will display in Pi's terminal.
Browser Mermaid and exported HTML have different rendering contracts.
Authority
Routine validation uses the helper; reread renderer source/docs only after upgrades or unexpected results.
Resolve installed Pi from PI_CONTEXT_PACKAGE_JSON_PATH; do not assume global npm paths.
Pi 1.5.1 renders with lovely-mermaid (0.3.3 at inspection); Pi 1.5.0 and earlier used grok-mermaid.
Resolve whichever renderer the installed manifest provides with Node createRequire; the helper tries lovely-mermaid first, then grok-mermaid, and reports both when neither loads.
Pi's transformer lives beside that manifest at dist/modes/interactive/components/mermaid.js in the inspected installation.
Installed Pi docs are under PI_CONTEXT_DOCS_PATH; settings.md documents markdown.mermaid.
Paths and behavior can change with Pi upgrades; inspect again if validation disagrees with display.
Rendering contract
Pi uses lovely-mermaid Unicode terminal art, not browser Mermaid/SVG.
Gantt and other browser-only diagram types are not supported; the renderer returns null.
Browser styling, HTML labels, and theme directives are not a portable terminal contract; use plain labels and Pi's theme.
lovely-mermaid parses classDef and emits OSC 8 links behind Pi's terminal capability checks; treat these as Pi-owned display behavior, not authoring requirements.
Use a top-level fenced block tagged mermaid, outside lists and blockquotes.
Null render or width exceeding available message width → Pi silently retains source.
Nonempty renderer warnings → Pi rejects the diagram in final messages, retains source, and appends Mermaid diagram not rendered: <first warning>.
Streaming may show partial art that falls back to source once finalized.
markdown.mermaid: off disables rendering, final waits for completion, streaming renders during generation.
Thinking content is not transformed.
The renderer calls warnings advisory, but Pi rejects them in final messages.
Validate against Pi's final-message behavior, not merely whether partial art exists.
Layout
One claim, few nodes, short labels.
Try TD first for narrow screens, then measure; parallel vertical branches can be wider than LR.
Sequence participants also consume horizontal space.
Shorten labels or split diagrams rather than hoping Pi shrinks them; renderer computes its own width.
Terminal columns are not message columns: account for Pi padding and surrounding UI.
A tool subprocess's stdout.columns, COLUMNS, or absent TTY does not establish the live Pi viewport.
If viewport is unknown, use an explicit conservative budget (for example 40 columns), state that assumption, and report required width rather than guaranteed fit.
Passing validation does not prove semantic correctness; inspect the preview for missing edges, flattened structure, and misleading layout.
Validate without source files
Validate through stdin; never create temporary files solely for diagram validation.
Pass exact raw diagram contents, without Markdown fences, to validate-pi.mjs.
Resolve that script relative to this skill and use its absolute path when cwd differs.
No input-file option is provided.
The helper is cross-platform Node .mjs; only stdin plumbing depends on the caller's shell.
Programmatic callers can use spawnSync(process.execPath, [scriptPath, "--width", "40"], { input: source, encoding: "utf8", shell: false }) without shell quoting or temporary files.
--width is mandatory and means available message columns, not terminal columns.
Output JSON contains ok, requiredColumns, availableColumns, and, for rendered art, overflow, warnings, and preview lines.
Exit 0: fits the supplied budget with no warnings.
Exit 1: null render, warnings, or overflow; revise diagram.
Exit 2: invalid invocation or unavailable/broken Pi renderer; report blocker.
Missing PI_CONTEXT_PACKAGE_JSON_PATH or installed renderer → stop; never install a substitute or change dependencies.
Renderer resolves through createRequire(pathToFileURL(packagePath)), then imports a file URL; no hardcoded Unix paths or npm dependency declarations.
The skill's package.json is test metadata only; npm test uses Node's built-in test runner, without installation.
Renderer integration tests require Pi context; without it they explicitly skip, not claim renderer verification.
Verified examples
Human checked these in Pi after validator measurements against lovely-mermaid 0.3.3 under Pi 1.5.1; only A and B fit a small viewport.
Tests preserve the same inputs in validate-pi.test.mjs.
A: vertical Agent → Review flowchart, 10 columns, no warnings.
B: You/Agent sequence with Task/Patch messages, 18 columns, no warnings.
C: five long labels in a horizontal chain, 137 columns; too wide for the observed viewport.
D: Gantt source returned null; unsupported family.
E: flowchart TD followed by A[Start --> B drew partial art at 16 columns but warned about a missing closing bracket; rejected on final display.
Also verified renderable: timeline 22, mindmap 13, pie 33, gitGraph 15 columns for small sources.
Widths describe the inspected renderer version, not stable API guarantees.
Revalidate exact source after edits or renderer upgrades.
# Pi terminal Mermaid
Use only when diagrams will display in Pi's terminal.
Browser Mermaid and exported HTML have different rendering contracts.
## Authority
Routine validation uses the helper; reread renderer source/docs only after upgrades or unexpected results.
- Resolve installed Pi from `PI_CONTEXT_PACKAGE_JSON_PATH`; do not assume global npm paths.
- Pi 1.5.1 renders with `lovely-mermaid` (0.3.3 at inspection); Pi 1.5.0 and earlier used `grok-mermaid`.
- Resolve whichever renderer the installed manifest provides with Node `createRequire`; the helper tries `lovely-mermaid` first, then `grok-mermaid`, and reports both when neither loads.
- Pi's transformer lives beside that manifest at `dist/modes/interactive/components/mermaid.js` in the inspected installation.
- Installed Pi docs are under `PI_CONTEXT_DOCS_PATH`; `settings.md` documents `markdown.mermaid`.
- Paths and behavior can change with Pi upgrades; inspect again if validation disagrees with display.
## Rendering contract
- Pi uses `lovely-mermaid` Unicode terminal art, not browser Mermaid/SVG.
- Supported families: flowchart (incl. subgraph), state, class, ER, sequence, pie, mindmap, timeline, gitGraph.
- Gantt and other browser-only diagram types are not supported; the renderer returns null.
- Browser styling, HTML labels, and theme directives are not a portable terminal contract; use plain labels and Pi's theme.
- lovely-mermaid parses `classDef` and emits OSC 8 links behind Pi's terminal capability checks; treat these as Pi-owned display behavior, not authoring requirements.
- Use a top-level fenced block tagged `mermaid`, outside lists and blockquotes.
- Null render or width exceeding available message width → Pi silently retains source.
- Nonempty renderer warnings → Pi rejects the diagram in final messages, retains source, and appends `Mermaid diagram not rendered: <first warning>`.
- Streaming may show partial art that falls back to source once finalized.
- `markdown.mermaid`: `off` disables rendering, `final` waits for completion, `streaming` renders during generation.
- Thinking content is not transformed.
The renderer calls warnings advisory, but Pi rejects them in final messages.
Validate against Pi's final-message behavior, not merely whether partial art exists.
## Layout
- One claim, few nodes, short labels.
- Try `TD` first for narrow screens, then measure; parallel vertical branches can be wider than `LR`.
- Sequence participants also consume horizontal space.
- Shorten labels or split diagrams rather than hoping Pi shrinks them; renderer computes its own width.
- Terminal columns are not message columns: account for Pi padding and surrounding UI.
- A tool subprocess's `stdout.columns`, `COLUMNS`, or absent TTY does not establish the live Pi viewport.
- If viewport is unknown, use an explicit conservative budget (for example 40 columns), state that assumption, and report required width rather than guaranteed fit.
- Passing validation does not prove semantic correctness; inspect the preview for missing edges, flattened structure, and misleading layout.
## Validate without source files
Validate through stdin; never create temporary files solely for diagram validation.
Pass exact raw diagram contents, without Markdown fences, to [validate-pi.mjs](../scripts/validate-pi.mjs).
Resolve that script relative to this skill and use its absolute path when cwd differs.
No input-file option is provided.
Example from the skill directory, using Nushell:
```nu
'flowchart TD; A["Agent"] --> B["Review"]' | ^node scripts/validate-pi.mjs --width 40
```
The helper is cross-platform Node `.mjs`; only stdin plumbing depends on the caller's shell.
Programmatic callers can use `spawnSync(process.execPath, [scriptPath, "--width", "40"], { input: source, encoding: "utf8", shell: false })` without shell quoting or temporary files.
- `--width` is mandatory and means available message columns, not terminal columns.
- Output JSON contains `ok`, `requiredColumns`, `availableColumns`, and, for rendered art, `overflow`, `warnings`, and preview `lines`.
- Exit `0`: fits the supplied budget with no warnings.
- Exit `1`: null render, warnings, or overflow; revise diagram.
- Exit `2`: invalid invocation or unavailable/broken Pi renderer; report blocker.
- Missing `PI_CONTEXT_PACKAGE_JSON_PATH` or installed renderer → stop; never install a substitute or change dependencies.
- Renderer resolves through `createRequire(pathToFileURL(packagePath))`, then imports a file URL; no hardcoded Unix paths or npm dependency declarations.
- The skill's `package.json` is test metadata only; `npm test` uses Node's built-in test runner, without installation.
- Renderer integration tests require Pi context; without it they explicitly skip, not claim renderer verification.
## Verified examples
Human checked these in Pi after validator measurements against lovely-mermaid 0.3.3 under Pi 1.5.1; only A and B fit a small viewport.
Tests preserve the same inputs in [validate-pi.test.mjs](../scripts/validate-pi.test.mjs).
- A: vertical Agent → Review flowchart, 10 columns, no warnings.
- B: You/Agent sequence with Task/Patch messages, 18 columns, no warnings.
- C: five long labels in a horizontal chain, 137 columns; too wide for the observed viewport.
- D: Gantt source returned null; unsupported family.
- E: `flowchart TD` followed by `A[Start --> B` drew partial art at 16 columns but warned about a missing closing bracket; rejected on final display.
- Also verified renderable: timeline 22, mindmap 13, pie 33, gitGraph 15 columns for small sources.
Widths describe the inspected renderer version, not stable API guarantees.
Revalidate exact source after edits or renderer upgrades.