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/CRITICAL_FIX_OPERATION_ORDER.md

@@ -0,0 +1,102 @@
+# CRITICAL FIX: GraphQL Operation Order
+
+## Problem
+
+The bot was only receiving ONE message then the WebSocket would die with "websocket: close 1006 (abnormal closure): unexpected EOF".
+
+## Root Cause
+
+We were subscribing to messages **BEFORE** joining the room, which is the opposite of what the browser does.
+
+## Browser's Actual Sequence (from HAR analysis)
+
+1. connection_init
+2. ExtendedCurrentUserQuery
+3. (various other queries)
+4. **[24] JoinRoom** ← Join FIRST
+5. (many subscriptions)
+6. [57] **RoomDisconnect** ← Subscribe to disconnect events
+7. [58] MemberJoins
+8. [59] MemberLeaves
+9. **[61] NewMessageSubscription** ← Subscribe to messages LAST
+
+## Our Previous (Broken) Sequence
+
+1. connection_init ✅
+2. ExtendedCurrentUserQuery ✅
+3. **NewMessageSubscription** ❌ TOO EARLY!
+4. JoinRoom ❌ TOO LATE!
+5. (start listening)
+
+## Fixed Sequence
+
+1. connection_init
+2. ExtendedCurrentUserQuery
+3. **JoinRoom** ← Now FIRST
+4. **RoomDisconnect subscription** ← NEW! Handles disconnect events
+5. **NewMessageSubscription** ← Now AFTER joining
+
+## Changes Made
+
+### 1. Reordered Operations
+- Moved `JoinRoom` to happen BEFORE `NewMessageSubscription`
+- This matches the browser's behavior
+
+### 2. Added RoomDisconnect Subscription
+```graphql
+subscription RoomDisconnect($roomId: String!) {
+  roomDisconnect(id: $roomId) {
+    ok
+    __typename
+  }
+}
+```
+
+This subscription is CRITICAL - it handles disconnect events from the server and prevents the socket from dying unexpectedly.
+
+### 3. Added Socket Identification
+- All Kosmi WebSocket logs now prefixed with `[KOSMI WEBSOCKET]`
+- All Jackbox WebSocket logs now prefixed with `[JACKBOX WEBSOCKET]`
+- Makes debugging much easier
+
+## Expected Behavior After Fix
+
+1. Bot joins room successfully
+2. Bot subscribes to disconnect events
+3. Bot subscribes to message feed
+4. Bot receives ALL messages continuously (not just one)
+5. WebSocket stays alive
+6. Bot can send messages
+
+## Testing
+
+Rebuild and run:
+```bash
+go build
+docker-compose build
+docker-compose up -d
+docker-compose logs -f matterbridge
+```
+
+Look for:
+- `✅ Successfully joined room`
+- `Subscribing to room disconnect events`
+- `Subscribing to message feed`
+- `🎧 [KOSMI WEBSOCKET] Message listener started`
+- Multiple `Received message from Kosmi` entries (not just one!)
+- NO `❌ [KOSMI WEBSOCKET] Error reading message` or `websocket: close 1006`
+
+## Why This Matters
+
+The server expects clients to:
+1. Join the room first
+2. Subscribe to disconnect events
+3. Then subscribe to messages
+
+If you subscribe to messages before joining, the server may:
+- Only send one message as a "test"
+- Then close the connection because you're not properly joined
+- Or ignore subsequent messages
+
+This is a common pattern in WebSocket APIs - you must establish your presence (join) before subscribing to events.
+