diff --git a/docs/faq.md b/docs/faq.md
index e6677e4be..975003c21 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -250,7 +250,7 @@ Clawdbot can run as:
 - **bun binary (macOS app)** — Single executable, easy distribution, auto-restarts via launchd
 - **Node runtime** (`clawdbot gateway`) — More stable for WhatsApp
 
-If you see WebSocket errors like `ws.WebSocket 'upgrade' event is not implemented`, use Node instead of the bun binary. Bun's WebSocket implementation has edge cases that can break WhatsApp (Baileys) and can corrupt memory on reconnect. Baileys: https://github.com/WhiskeySockets/Baileys
+If you see WebSocket errors like `ws.WebSocket 'upgrade' event is not implemented`, use Node instead of the bun binary. Bun's WebSocket implementation has edge cases that can break WhatsApp (Baileys) and can corrupt memory on reconnect. Baileys: https://github.com/WhiskeySockets/Baileys · Bun issue: https://github.com/oven-sh/bun/issues/5951
 
 **For stability:** Use launchd (macOS) or the Clawdbot.app — they handle process supervision (auto-restart on crash).
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 06d9ac0a5..a68b841e0 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -91,7 +91,8 @@ Dashboard (local loopback): `http://127.0.0.1:18789/`
 ⚠️ **WhatsApp + Bun warning:** Baileys (WhatsApp Web library) uses a WebSocket
 path that is currently incompatible with Bun and can cause memory corruption on
 reconnect. If you use WhatsApp, run the Gateway with **Node** until this is
-resolved. Baileys: https://github.com/WhiskeySockets/Baileys
+resolved. Baileys: https://github.com/WhiskeySockets/Baileys · Bun issue:
+https://github.com/oven-sh/bun/issues/5951
 
 ## 5) Pair + connect your first chat surface