docs(websockets): add infrastructure requirements and troubleshooting to guides

documentation/GUIDE__V3_FRONTEND_WEBSOCKETS.md

@@ -131,7 +131,32 @@ Keep the connection alive and refresh presence in the backend. Should be sent ev
 
 ---
 
-## 6. Migration Guide (V2 to V3)
+## 6. Infrastructure Requirements (Nginx)
+
+Unlike standard REST endpoints, WebSockets require explicit "Upgrade" handling in the Nginx gateway. If you are deploying to a new server, ensure the following block is present in your Nginx configuration:
+
+```nginx
+location /v3/ws {
+    proxy_pass http://fastapi_backend;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $http_host;
+    proxy_read_timeout 2100s; # Match your app's max heartbeat/session time
+}
+```
+
+---
+
+## 7. Common Pitfalls & Troubleshooting
+
+- **HTTP 404 Errors**: This almost always means Nginx is missing the `location /v3/ws` block and is trying to serve the request as a static file from the disk.
+- **HTTP 400 Errors**: Check your `Host` header. Nginx routes requests based on the `server_name` directive. If you connect to an IP or a non-standard hostname (like `localhost`), ensure it is explicitly listed in your Nginx config.
+- **Connection Drops**: If the connection drops exactly after 60 seconds, check your Nginx `proxy_read_timeout`. It should be set high (e.g., `2100s`) to allow for long-lived WebSocket sessions.
+
+---
+
+## 8. Migration Guide (V2 to V3)
 
 If you are upgrading from the legacy V2 WebSocket (`/ws/group/...`):