diff --git a/src/swarms/doc/spec/build.sh b/src/swarms/doc/spec/build.sh
index 4b95a71..c4bd109 100755
--- a/src/swarms/doc/spec/build.sh
+++ b/src/swarms/doc/spec/build.sh
@@ -98,7 +98,7 @@ mkdir -p "$IMG_DIR"
 "$MMDC" \
   -i "$INPUT" \
   -o "$RENDERED" \
-  -e png \
+  -e svg \
   -b white \
   -c "$MERMAID_CFG" \
   -a "$IMG_DIR" \
diff --git a/src/swarms/doc/spec/mermaid-config.json b/src/swarms/doc/spec/mermaid-config.json
index f914666..f989cde 100644
--- a/src/swarms/doc/spec/mermaid-config.json
+++ b/src/swarms/doc/spec/mermaid-config.json
@@ -7,14 +7,17 @@
     "lineColor": "#666",
     "secondaryColor": "#f0f4f8",
     "tertiaryColor": "#e8f4e8",
-    "fontSize": "14px"
+    "fontSize": "16px"
   },
   "flowchart": {
     "curve": "basis",
-    "useMaxWidth": true
+    "useMaxWidth": false,
+    "htmlLabels": true
   },
   "sequence": {
-    "useMaxWidth": true,
-    "wrap": true
+    "useMaxWidth": false,
+    "wrap": true,
+    "width": 200,
+    "noteMargin": 15
   }
 }
diff --git a/src/swarms/doc/spec/pdf-style.css b/src/swarms/doc/spec/pdf-style.css
index 6b8c362..6d4eee4 100644
--- a/src/swarms/doc/spec/pdf-style.css
+++ b/src/swarms/doc/spec/pdf-style.css
@@ -176,7 +176,7 @@ pre code {
   font-size: inherit;
 }
 
-/* ---------- Images (Mermaid diagrams) ---------- */
+/* ---------- Images & SVG Diagrams (Mermaid) ---------- */
 
 img {
   max-width: 100%;
@@ -186,6 +186,13 @@ img {
   page-break-inside: avoid;
 }
 
+/* Scale SVG diagrams to use full page width for readability */
+img[src$=".svg"] {
+  width: 100%;
+  max-height: 80vh;
+  object-fit: contain;
+}
+
 /* Center mermaid diagrams */
 p > img {
   margin: 16pt auto;