mermaidlisted

# Mermaid Diagrams Mermaid is the workhorse for repo documentation: it renders natively on GitHub, lives in the markdown itself, and diffs like code. Default to Mermaid for any diagram destined for a `.md` file. ## HOUSE RULE — read before writing any node > **No parentheses or special characters in node labels — they break rendering.** This is a standing rule, not a suggestion. `(`, `)`, and other special characters (`{`, `}`, `[`, `]`, `#`, `;`, `"`, `<`, `>`, `&`) inside node labels cause silent or hard rendering failures depending on the renderer version. Rewrite the label instead: ```mermaid flowchart LR A[API Gateway] --> B[Auth Service JWT] ``` - WRONG: `B[Auth Service (JWT)]` - RIGHT: `B[Auth Service JWT]` or `B[Auth Service - JWT]` - Applies to edge labels and subgraph titles too. Plain words, hyphens, and spaces only. - Do not "fix" it with quoted labels or HTML entities — the rule is to avoid the characters entirely, so every renderer (GitHub, IDE previews, mermaid-cli) agrees. ## Scope Structural diagrams only. Data charts → the `dataviz` skill (do not use Mermaid `pie`/`xychart` for real data viz). Provider-icon cloud architecture → the `diagrams` skill. Tool selection guide → the `diagrams` skill. ## Diagram types and when to use them | Type | Use for | Opening line | |---|---|---| | Flowchart | Architecture, data flow, decision logic | `flowchart TD` or `flowchart LR` | | Sequence | Auth flows, API call chains, message passing | `sequenceDiagram`