docs: update websocket event reference with new shard monitor events

Add room.connected, lobby.player-joined, lobby.updated, game.started,
game.ended, room.disconnected events. Clarify player-count.updated as
manual-override only. Update complete example with new event handlers.

Made-with: Cursor

docs/api/websocket.md

@@ -5,7 +5,8 @@
 The WebSocket API provides real-time updates for Jackbox gaming sessions. Use it to:
 
 - Receive notifications when sessions start, end, or when games are added
-- Track player counts as they are updated
+- Monitor Jackbox room state in real-time (lobby, player joins, game start/end)
+- Track player counts automatically via shard connection
 - Receive live vote updates (upvotes/downvotes) as viewers vote
 - Avoid polling REST endpoints for session state changes
 
@@ -129,7 +130,13 @@ Must be authenticated.
 | `session.started` | New session created (broadcast to all authenticated clients) |
 | `game.added`  | Game added to a session (broadcast to subscribers) |
 | `session.ended` | Session closed (broadcast to subscribers) |
-| `player-count.updated` | Player count changed (broadcast to subscribers) |
+| `room.connected` | Shard connected to Jackbox room (broadcast to subscribers) |
+| `lobby.player-joined` | Player joined the Jackbox lobby (broadcast to subscribers) |
+| `lobby.updated` | Lobby state changed (broadcast to subscribers) |
+| `game.started` | Game transitioned to Gameplay (broadcast to subscribers) |
+| `game.ended` | Game finished (broadcast to subscribers) |
+| `room.disconnected` | Shard lost connection to Jackbox room (broadcast to subscribers) |
+| `player-count.updated` | Manual player count override (broadcast to subscribers) |
 | `vote.received`        | Live vote recorded (broadcast to subscribers)   |
 
 ---
@@ -204,10 +211,117 @@ All server-sent events use this envelope:
 }
 ```
 
+### room.connected
+
+- **Broadcast to:** Clients subscribed to the session
+- **Triggered by:** Shard WebSocket successfully connecting to a Jackbox room (after `POST .../start-player-check` or adding a game with a room code)
+
+**Data:**
+```json
+{
+  "sessionId": 1,
+  "gameId": 5,
+  "roomCode": "LSBN",
+  "appTag": "drawful2international",
+  "maxPlayers": 8,
+  "playerCount": 2,
+  "players": ["Alice", "Bob"],
+  "lobbyState": "CanStart",
+  "gameState": "Lobby"
+}
+```
+
+### lobby.player-joined
+
+- **Broadcast to:** Clients subscribed to the session
+- **Triggered by:** A new player joining the Jackbox room lobby (detected via `textDescriptions` entity updates or `client/connected` messages)
+
+**Data:**
+```json
+{
+  "sessionId": 1,
+  "gameId": 5,
+  "roomCode": "LSBN",
+  "playerName": "Charlie",
+  "playerCount": 3,
+  "players": ["Alice", "Bob", "Charlie"],
+  "maxPlayers": 8
+}
+```
+
+### lobby.updated
+
+- **Broadcast to:** Clients subscribed to the session
+- **Triggered by:** Lobby state change in the Jackbox room (e.g., enough players to start, countdown started)
+
+**Data:**
+```json
+{
+  "sessionId": 1,
+  "gameId": 5,
+  "roomCode": "LSBN",
+  "lobbyState": "Countdown",
+  "gameCanStart": true,
+  "gameIsStarting": true,
+  "playerCount": 4
+}
+```
+
+### game.started
+
+- **Broadcast to:** Clients subscribed to the session
+- **Triggered by:** Jackbox game transitioning from Lobby to Gameplay state
+
+**Data:**
+```json
+{
+  "sessionId": 1,
+  "gameId": 5,
+  "roomCode": "LSBN",
+  "playerCount": 4,
+  "players": ["Alice", "Bob", "Charlie", "Diana"],
+  "maxPlayers": 8
+}
+```
+
+### game.ended
+
+- **Broadcast to:** Clients subscribed to the session
+- **Triggered by:** Jackbox game finishing (`gameFinished: true`) or room closing
+
+**Data:**
+```json
+{
+  "sessionId": 1,
+  "gameId": 5,
+  "roomCode": "LSBN",
+  "playerCount": 4,
+  "players": ["Alice", "Bob", "Charlie", "Diana"]
+}
+```
+
+### room.disconnected
+
+- **Broadcast to:** Clients subscribed to the session
+- **Triggered by:** Shard losing connection to the Jackbox room (room closed, connection failed, manually stopped)
+
+**Data:**
+```json
+{
+  "sessionId": 1,
+  "gameId": 5,
+  "roomCode": "LSBN",
+  "reason": "room_closed",
+  "finalPlayerCount": 4
+}
+```
+
+Possible `reason` values: `room_closed`, `room_not_found`, `connection_failed`, `role_rejected`, `manually_stopped`.
+
 ### player-count.updated
 
 - **Broadcast to:** Clients subscribed to the session
-- **Triggered by:** `PATCH /api/sessions/{sessionId}/games/{sessionGameId}/player-count`
+- **Triggered by:** `PATCH /api/sessions/{sessionId}/games/{sessionGameId}/player-count` (manual override only)
 
 **Data:**
 ```json
@@ -398,6 +512,30 @@ ws.onmessage = (event) => {
       subscribedSessions.delete(msg.data.session.id);
       break;
 
+    case 'room.connected':
+      console.log('Room connected:', msg.data.roomCode, '- players:', msg.data.players.join(', '));
+      break;
+
+    case 'lobby.player-joined':
+      console.log('Player joined:', msg.data.playerName, '- count:', msg.data.playerCount);
+      break;
+
+    case 'lobby.updated':
+      console.log('Lobby:', msg.data.lobbyState);
+      break;
+
+    case 'game.started':
+      console.log('Game started with', msg.data.playerCount, 'players');
+      break;
+
+    case 'game.ended':
+      console.log('Game ended with', msg.data.playerCount, 'players');
+      break;
+
+    case 'room.disconnected':
+      console.log('Room disconnected:', msg.data.reason);
+      break;
+
     case 'player-count.updated':
       console.log('Player count:', msg.data.playerCount, 'for game', msg.data.gameId);
       break;