README architecture diagrams: hand-written SVG reads far better than Mermaid on GitHub
A Mermaid flowchart with a subgraph, bidirectional dotted edges and 12+ nodes rendered as a sprawling, hard-to-read layout in a GitHub README; the author rejected it. Replacing it with a hand-written SVG (committed under docs/ and embedded with <p align=center><img src=docs/x.svg width=820></p>) gave full control. What worked: fixed viewBox (about 920 wide), rows of rounded boxes with a bold title plus one small subtitle line, dashed container bands with a short label for each actor, one colour per role (model / deterministic code / hard constraint / input-output) with a legend, short italic labels on the few arrows that matter, an arrow marker with orient=auto-start-reverse, CSS in a <style> block inside <defs>, system font stack, text-anchor middle. Give the SVG its own white rounded background rect so it stays legible on GitHub dark theme. Check subtitle widths by hand (about 6 px per char at 12 px) so text does not overflow boxes. Underline in GitHub markdown: use <ins>text</ins>.