diff --git a/.ai/instructions/skills/mermaid.instructions.md b/.ai/instructions/skills/mermaid.instructions.md
index dafc7a0..174aaac 100644
--- a/.ai/instructions/skills/mermaid.instructions.md
+++ b/.ai/instructions/skills/mermaid.instructions.md
@@ -15,6 +15,20 @@ Use `-- "text" -->` syntax, **not** `-->|text|` syntax.
 
 ---
 
+## Line Breaks (Multiline Text)
+
+Do not use `\n` for line breaks inside Mermaid nodes or labels. It does not always render correctly.
+Instead, use actual line breaks (real newlines) inside quoted text.
+
+```
+✅ A["First line
+Second line"]
+
+❌ B["First line\nSecond line"]
+```
+
+---
+
 ## Color Contrast — CRITICAL
 
 All Mermaid diagrams MUST have sufficient color contrast. AI-generated diagrams often fail this.