docs: comprehensive API documentation from source code

Replace existing docs with fresh documentation built entirely from source
code analysis. OpenAPI 3.1 spec as source of truth, plus human-readable
Markdown with curl examples, response samples, and workflow guides.

- OpenAPI 3.1 spec covering all 42 endpoints (validated against source)
- 7 endpoint reference docs (auth, games, sessions, picker, stats, votes, webhooks)
- WebSocket protocol documentation (auth, subscriptions, 4 event types)
- 4 guide documents (getting started, session lifecycle, voting, webhooks)
- API README with overview, auth docs, and quick reference table
- Old docs archived to docs/archive/

Made-with: Cursor

docs/archive/SESSION_END_QUICK_START.md

@@ -0,0 +1,105 @@
+# Session End Event - Quick Start Guide
+
+## 🚀 Quick Start
+
+### Listen for Session End Events
+
+```javascript
+const WebSocket = require('ws');
+
+const ws = new WebSocket('ws://localhost:5000/api/sessions/live');
+
+ws.on('open', () => {
+  // 1. Authenticate
+  ws.send(JSON.stringify({
+    type: 'auth',
+    token: 'YOUR_JWT_TOKEN'
+  }));
+});
+
+ws.on('message', (data) => {
+  const msg = JSON.parse(data.toString());
+  
+  if (msg.type === 'auth_success') {
+    // 2. Subscribe to session
+    ws.send(JSON.stringify({
+      type: 'subscribe',
+      sessionId: 17
+    }));
+  }
+  
+  if (msg.type === 'session.ended') {
+    // 3. Handle session end
+    console.log('Session ended!');
+    console.log(`Games played: ${msg.data.session.games_played}`);
+    // Announce to your users here
+  }
+});
+```
+
+## 📦 Event Format
+
+```json
+{
+  "type": "session.ended",
+  "timestamp": "2025-11-01T02:30:45.123Z",
+  "data": {
+    "session": {
+      "id": 17,
+      "is_active": 0,
+      "games_played": 5
+    }
+  }
+}
+```
+
+## 🧪 Test It
+
+```bash
+# Get your JWT token first
+curl -X POST http://localhost:5000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"key":"YOUR_ADMIN_KEY"}'
+
+# Run the test script
+node ../tests/test-session-end-websocket.js 17 YOUR_JWT_TOKEN
+
+# In another terminal, close the session
+curl -X POST http://localhost:5000/api/sessions/17/close \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+```
+
+## 🤖 Bot Integration
+
+When your bot receives `session.ended`:
+
+```javascript
+if (msg.type === 'session.ended') {
+  const { id, games_played } = msg.data.session;
+  
+  // Announce to IRC/Discord/etc
+  bot.announce(`🌙 Game Night has ended! We played ${games_played} games.`);
+  bot.announce('Thanks for playing!');
+}
+```
+
+## 📚 Full Documentation
+
+See [SESSION_END_WEBSOCKET.md](SESSION_END_WEBSOCKET.md) for complete documentation.
+
+## ⚡ Key Points
+
+- ✅ **Instant** - No polling needed
+- ✅ **Reliable** - Broadcast to all subscribers
+- ✅ **Simple** - Same format as `game.added`
+- ✅ **Tested** - Test script included
+
+## 🔗 Related Events
+
+| Event | When |
+|-------|------|
+| `session.started` | Session created |
+| `game.added` | Game starts |
+| `session.ended` | Session closes |
+| `vote.received` | Vote cast |
+