Update Workflow Diagram from Mermaid

Purpose

Regenerate the website/ai-workflow.svg file from the canonical mermaid diagram in docs/workflow.md. The website uses a hand-crafted blueprint-styled SVG that preserves the exact layout generated by mermaid but applies a custom visual style (technical drawing aesthetic with cyan/white on dark blue).

When to Use

• After changes to the mermaid diagram in docs/workflow.md
• When adding, removing, or renaming agents/artifacts
• When modifying the workflow connections

Hard Rules

Must

• Use mermaid-cli (mmdc) to render the mermaid diagram to SVG
• Parse the generated SVG to extract node positions and path definitions
• Preserve exact node positions and path routing from mermaid output
• Keep each workflow in its own numbered sequence; use plain labels rather than HTML bold or italic tags
• Preserve subgraph headings and nested transforms, and omit invisible links used only to order the layout
• Apply blueprint styling consistently per node type
• Keep the SVG self-contained (all styles inline or in <style> block)

Must Not

• Manually calculate node positions (extract from rendered mermaid SVG)
• Manually recreate path curves (copy exact d attributes from mermaid paths)
• Change the visual styling without updating this skill documentation

Blueprint Style Reference

Colors

Node Classes (from mermaid)

Glow Effects

Nodes have CSS filter glow. Edge paths have no filters: zero-width bounding boxes on perfectly vertical paths cause some SVG renderers to hide filtered arrows.

/* Nodes */
filter: drop-shadow(0 0 4px rgba(0,255,255,0.6));

Actions

One command. It extracts the mermaid block from docs/workflow.md, renders it with mmdc for layout, and restyles the result:

scripts/render-workflow-diagram.py

--check verifies the committed SVG was generated from the diagram as it stands now, by comparing a source-sha256 stamp written into the file. It does not re-render, so it needs no browser and runs in milliseconds — this is the CI check.

Mermaid lays out text by measuring it in a browser, so node coordinates depend on which fonts the machine has; a byte-for-byte comparison passes locally and fails in CI for no reason a reader could act on. The stamp catches the failure that matters — editing the diagram and forgetting to regenerate.

--check-render does the strict byte comparison against a fresh render. Use it on the machine that generated the file, not in CI.

The stamp covers the diagram source, not this script: change the styling logic without regenerating and --check still passes. If you edit the script, re-run it and commit the SVG.

The script exists because this was a ten-step manual parse, and doing it by hand loses things quietly. Two failures found the first time it ran, neither visible in the output text:

• The Maintainer node vanished. It is a stadium, drawn as a free <path> inside an outer-path group — matching neither the <rect> nor the <polygon> pattern, so the node was skipped without an error.
• The gate hexagons rendered ~100px from their own labels, because a mermaid <polygon> carries its own inner transform in addition to the node group's.
• Workflow lanes lost their headings and overlapped when nested subgraph transforms were ignored. The parser composes those translations for nodes, paths and labels.
• Invisible links used to order the workflows became visible arrows. They affect the Mermaid layout but must be omitted from the website SVG.

Always look at the rendered image before committing. A grep for the node names passes in both broken cases above.

npx --yes sharp-cli -i website/src/media-root/ai-workflow.svg -o .tmp/workflow-diagram.png resize 1400

Node styling

Adding a new classDef to the diagram means adding it to NODE_CLASS and STYLE in the script; an unmapped class falls back to the human style, which will look wrong.