initial actual player count implementation

README.md

@@ -341,6 +341,42 @@ For integrating external bots (e.g., for live voting and game notifications), se
 - Example implementations in Node.js and Go
 - Security best practices
 
+## Jackbox Player Count Fetcher
+
+The `scripts/` directory contains utilities for inspecting Jackbox game lobbies:
+
+- **[get-player-count.go](scripts/get-player-count.go)** - Go + chromedp script (recommended, most reliable)
+- **[get-player-count.html](scripts/get-player-count.html)** - Browser-based tool (no installation required!)
+- **[get-jackbox-player-count.js](scripts/get-jackbox-player-count.js)** - Node.js script (limited, may not work)
+
+See **[scripts/README.md](scripts/README.md)** for detailed usage instructions.
+
+### Quick Start
+
+**Go version (recommended for automation):**
+```bash
+cd scripts
+go run get-player-count.go JYET
+```
+
+**Browser version (easiest for manual testing):**
+1. Open `scripts/get-player-count.html` in any browser
+2. Enter a 4-letter room code
+3. View real-time player count and lobby status
+
+**How it works:**
+- Automates joining jackbox.tv through Chrome/Chromium
+- Captures WebSocket messages containing player data
+- Extracts actual player count from lobby state
+
+These tools retrieve:
+- ✅ Actual player count (not just max capacity)
+- ✅ List of current players and their roles (host/player)
+- ✅ Game state and lobby status  
+- ✅ Audience count
+
+**Note:** Direct WebSocket connection is not possible without authentication, so the tools join through jackbox.tv to capture the data.
+
 ## Database Schema
 
 ### games