Reorganize project: move docs to docs/ and test scripts to tests/

Moved 9 documentation .md files from root into docs/.
Moved 4 test scripts from root into tests/.
Updated cross-references in README.md and docs to reflect new paths.

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

tests/test-session-end-websocket.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for session.ended WebSocket event
+ * 
+ * This script:
+ * 1. Connects to the WebSocket server
+ * 2. Authenticates with a JWT token
+ * 3. Subscribes to a session
+ * 4. Listens for session.ended events
+ * 
+ * Usage:
+ *   node test-session-end-websocket.js <session_id> <jwt_token>
+ * 
+ * Example:
+ *   node test-session-end-websocket.js 17 your-jwt-token-here
+ */
+
+const WebSocket = require('ws');
+
+// Configuration
+const WS_URL = process.env.WS_URL || 'ws://localhost:5000/api/sessions/live';
+const SESSION_ID = process.argv[2] || '17';
+const JWT_TOKEN = process.argv[3];
+
+if (!JWT_TOKEN) {
+  console.error('❌ Error: JWT token is required');
+  console.error('Usage: node test-session-end-websocket.js <session_id> <jwt_token>');
+  process.exit(1);
+}
+
+console.log('🚀 Testing session.ended WebSocket event');
+console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+console.log(`📡 Connecting to: ${WS_URL}`);
+console.log(`🎮 Session ID: ${SESSION_ID}`);
+console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+
+// Create WebSocket connection
+const ws = new WebSocket(WS_URL);
+
+ws.on('open', () => {
+  console.log('✅ Connected to WebSocket server\n');
+  
+  // Step 1: Authenticate
+  console.log('🔐 Authenticating...');
+  ws.send(JSON.stringify({
+    type: 'auth',
+    token: JWT_TOKEN
+  }));
+});
+
+ws.on('message', (data) => {
+  try {
+    const message = JSON.parse(data.toString());
+    
+    switch (message.type) {
+      case 'auth_success':
+        console.log('✅ Authentication successful\n');
+        
+        // Step 2: Subscribe to session
+        console.log(`📻 Subscribing to session ${SESSION_ID}...`);
+        ws.send(JSON.stringify({
+          type: 'subscribe',
+          sessionId: parseInt(SESSION_ID)
+        }));
+        break;
+        
+      case 'subscribed':
+        console.log(`✅ Subscribed to session ${message.sessionId}\n`);
+        console.log('👂 Listening for session.ended events...');
+        console.log('   (Close the session in the Picker to trigger the event)\n');
+        break;
+        
+      case 'session.ended':
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('🎉 SESSION.ENDED EVENT RECEIVED!');
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('\n📦 Event Data:');
+        console.log(JSON.stringify(message, null, 2));
+        console.log('\n✨ Event Details:');
+        console.log(`   Session ID: ${message.data.session.id}`);
+        console.log(`   Active: ${message.data.session.is_active === 1 ? 'Yes' : 'No'}`);
+        console.log(`   Games Played: ${message.data.session.games_played}`);
+        console.log(`   Timestamp: ${message.timestamp}`);
+        console.log('\n✅ Test successful! The bot should now announce the session end.\n');
+        
+        // Close connection after receiving the event
+        setTimeout(() => {
+          console.log('👋 Closing connection...');
+          ws.close();
+        }, 1000);
+        break;
+        
+      case 'auth_error':
+      case 'error':
+        console.error(`❌ Error: ${message.message}`);
+        ws.close();
+        process.exit(1);
+        break;
+        
+      case 'pong':
+        // Ignore pong messages
+        break;
+        
+      default:
+        console.log(`📨 Received message: ${message.type}`);
+        console.log(JSON.stringify(message, null, 2));
+    }
+  } catch (err) {
+    console.error('❌ Failed to parse message:', err);
+    console.error('Raw data:', data.toString());
+  }
+});
+
+ws.on('error', (err) => {
+  console.error('❌ WebSocket error:', err.message);
+  process.exit(1);
+});
+
+ws.on('close', (code, reason) => {
+  console.log(`\n🔌 Connection closed (code: ${code})`);
+  if (reason) {
+    console.log(`   Reason: ${reason}`);
+  }
+  process.exit(0);
+});
+
+// Handle Ctrl+C gracefully
+process.on('SIGINT', () => {
+  console.log('\n\n👋 Shutting down...');
+  ws.close();
+  process.exit(0);
+});
+
+// Send periodic pings to keep connection alive
+const pingInterval = setInterval(() => {
+  if (ws.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify({ type: 'ping' }));
+  }
+}, 30000);
+
+// Clean up interval on close
+ws.on('close', () => {
+  clearInterval(pingInterval);
+});
+