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
• 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

All nodes and paths have CSS filter glow:

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

/* Paths */
filter: drop-shadow(0 0 2px rgba(0,255,255,0.4));

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.

That indirection is not laziness. 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.

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/check.png resize 900

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.