Move troubleshooting and implementation docs to docs/

Relocate 30 non-essential .md files (investigation notes, fix summaries,
implementation details, status reports) from the project root into docs/
to reduce clutter. Core operational docs (README, quickstart guides,
configuration references) remain in the root.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/WEBSOCKET_EVENT_FLOW.md

@@ -0,0 +1,192 @@
+# WebSocket Event Flow - Jackbox Integration
+
+## Event Broadcasting Behavior
+
+| Event | Broadcast To | Requires Subscription? |
+|-------|--------------|------------------------|
+| `session.started` | **All authenticated clients** | ❌ NO |
+| `game.added` | Session subscribers only | ✅ YES |
+| `session.ended` | Session subscribers only | ✅ YES |
+
+## Bot Connection Flow
+
+```
+1. Connect to WebSocket
+   ↓
+2. Send auth message with JWT token
+   ↓
+3. Receive auth_success
+   ↓
+4. Wait for session.started (automatic broadcast)
+   ↓
+5. When session.started received:
+   - Subscribe to that specific session ID
+   - Announce "Game Night is starting!"
+   ↓
+6. Receive game.added events (for subscribed session)
+   - Announce new games
+   ↓
+7. Receive session.ended event (for subscribed session)
+   - Announce final votes + goodnight
+```
+
+## Message Formats
+
+### 1. Authentication
+**Bot → Server:**
+```json
+{
+  "type": "auth",
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+}
+```
+
+**Server → Bot:**
+```json
+{
+  "type": "auth_success",
+  "message": "Authenticated successfully"
+}
+```
+
+### 2. Session Started (Automatic Broadcast)
+**Server → Bot:**
+```json
+{
+  "type": "session.started",
+  "timestamp": "2025-11-01T03:24:30Z",
+  "data": {
+    "session": {
+      "id": 21,
+      "is_active": 1,
+      "created_at": "2025-11-01 07:24:30",
+      "notes": null
+    }
+  }
+}
+```
+
+**Bot Action:**
+- Automatically subscribe to this session
+- Announce "🎮 Game Night is starting! Session #21"
+
+### 3. Subscribe to Session
+**Bot → Server:**
+```json
+{
+  "type": "subscribe",
+  "sessionId": 21
+}
+```
+
+**Server → Bot:**
+```json
+{
+  "type": "subscribed",
+  "message": "Subscribed to session 21"
+}
+```
+
+### 4. Game Added (Requires Subscription)
+**Server → Bot:**
+```json
+{
+  "type": "game.added",
+  "timestamp": "2025-11-01T03:25:00Z",
+  "data": {
+    "session": {
+      "id": 21,
+      "is_active": true,
+      "games_played": 1
+    },
+    "game": {
+      "id": 42,
+      "title": "Drawful 2",
+      "pack_name": "Drawful 2",
+      "min_players": 3,
+      "max_players": 8,
+      "manually_added": false
+    }
+  }
+}
+```
+
+**Bot Action:**
+- Announce previous game's votes (if any)
+- Announce "🎮 Coming up next: Drawful 2!"
+
+### 5. Session Ended (Requires Subscription)
+**Server → Bot:**
+```json
+{
+  "type": "session.ended",
+  "timestamp": "2025-11-01T04:30:00Z",
+  "data": {
+    "session": {
+      "id": 21,
+      "is_active": 0,
+      "games_played": 5
+    }
+  }
+}
+```
+
+**Bot Action:**
+- Announce final game's votes (if any)
+- Announce "🌙 Game Night has ended! Thanks for playing!"
+- Clear active session (reset to time-based vote debouncing)
+
+## Fallback Polling
+
+If WebSocket events are missed, the bot has a fallback polling mechanism (every 30 seconds):
+
+- **Detects new sessions** via HTTP GET `/api/sessions/active`
+- **Detects ended sessions** when active session becomes null/inactive
+- **Logs warnings** when polling detects changes (indicates missed WebSocket events)
+
+Example warning logs:
+```
+WARN Found active session 21 via polling (session.started event may have been missed)
+WARN Active session ended (detected via polling, session.ended event may have been missed)
+```
+
+## Testing
+
+### Expected Logs (Happy Path)
+```
+INFO Authentication successful
+INFO Session started: ID=21
+INFO Subscribed to session 21
+INFO Active session set to 21
+INFO Broadcasting Jackbox message: 🎮 Game Night is starting! Session #21
+INFO Subscription confirmed: Subscribed to session 21
+INFO Game added: Drawful 2 from Drawful 2
+INFO Broadcasting Jackbox message: 🎮 Coming up next: Drawful 2!
+INFO Session ended event received
+INFO Broadcasting Jackbox message: 🌙 Game Night has ended! Thanks for playing!
+```
+
+### Expected Logs (Fallback Polling)
+```
+INFO Authentication successful
+WARN Found active session 21 via polling (session.started event may have been missed), subscribing...
+INFO Subscribed to session 21
+```
+
+## Troubleshooting
+
+### Bot doesn't receive `session.started`
+- Check backend logs: Should say "Broadcasted session.started to X client(s)"
+- Check bot is authenticated: Look for "Authentication successful" in logs
+- Check WebSocket connection: Should say "WebSocket connected"
+
+### Bot doesn't receive `game.added` or `session.ended`
+- Check bot subscribed to session: Look for "Subscribed to session X" in logs
+- Check backend logs: Should say "Broadcasted game.added to X client(s) for session Y"
+- If X = 0, bot didn't subscribe properly
+
+### Polling warnings appear
+- This means WebSocket events aren't being received
+- Check your backend is calling `broadcastToAll()` for `session.started`
+- Check your backend is calling `broadcastEvent(sessionId)` for `game.added` and `session.ended`
+