docs: comprehensive documentation overhaul

Rewrite README.md and all setup guides to reflect the current native
GraphQL WebSocket architecture (replacing stale headless Chrome/WebSocket
interception descriptions). Add new docs/IRC.md with complete IRC command
reference, vote syntax, and ticker symbol table.

Archive pre-edit docs to docs/archive/setup-backup-2026-05-10/ and move
historical development notes from docs/ root into docs/archive/.

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

docs/setup/QUICK_START_AUTH.md

@@ -1,4 +1,4 @@
-# Quick Start: Testing Authentication
+# Quick Start: Authenticated Kosmi Access
 
 ## Step 1: Create Bot Account
 
@@ -7,88 +7,72 @@
 3. Choose a display name (e.g., "HSO Relay Bot")
 4. Save the credentials securely
 
-## Step 2: Test with Monitor Script
-
-```bash
-cd /Users/erikfredericks/dev-ai/HSO/irc-kosmi-relay
-
-# Run monitor in login mode
-./bin/monitor-auth -login
-
-# In the browser that opens:
-# 1. Log in with your bot credentials
-# 2. Navigate to a room
-# 3. Press Ctrl+C to stop
-
-# Review the captured data
-cat auth-monitor.log | grep -A 5 "login"
-```
-
-## Step 3: Configure Matterbridge
+## Step 2: Configure Matterbridge
 
 Edit `matterbridge.toml`:
 
 ```toml
 [kosmi.hyperspaceout]
-RoomURL="https://app.kosmi.io/room/@hyperspaceout"
+RoomURL="https://app.kosmi.io/room/@yourroom"
 Email="your-bot@example.com"
 Password="your-secure-password"
 ```
 
-## Step 4: Test Connection
+## Step 3: Run and Verify
 
 ```bash
-# Build the bridge
-go build
-
-# Run with your config
 ./matterbridge -conf matterbridge.toml
-
-# Watch the logs for:
-# - "Using authenticated connection"
-# - "Logged in as: HSO Relay Bot"
-# - "Successfully connected to Kosmi"
 ```
 
+Watch the logs for:
+- `"Authenticating with email/password..."` -- browser login starting
+- `"✅ Authentication successful"` -- login completed
+- `"💾 Token cached"` -- token saved for reuse
+- `"Successfully connected to Kosmi"` -- connected to room
+
+On subsequent runs with a cached token:
+- `"✅ Using cached token"` -- no browser needed
+
+## Step 4: Test
+
+1. Send a message in the Kosmi room from a browser
+2. Verify it appears in your IRC channel
+3. Send a message from IRC
+4. Verify it appears in Kosmi with the bot's display name
+
 ## Verification Checklist
 
-- [ ] Bot account created manually
-- [ ] Credentials documented securely
-- [ ] Monitor script captured login flow
-- [ ] Config file updated with credentials
+- [ ] Bot account created at app.kosmi.io
+- [ ] Credentials added to `matterbridge.toml`
 - [ ] Bridge logs show authenticated connection
 - [ ] Bot display name appears correctly in chat
-- [ ] Messages relay successfully
+- [ ] Messages relay bidirectionally
+- [ ] Token cache file exists (`data/kosmi_token_cache.json` or `~/.matterbridge/kosmi_token_cache.json`)
 
 ## Troubleshooting
 
-### Wrong account logged in
-
-Check the log for "Logged in as: {name}". If it doesn't match your bot:
-- Verify email/password in config
-- Check for typos
-- Ensure you're using the correct credentials
-
 ### Anonymous connection despite credentials
 
-Check that both Email AND Password are set:
+Check that both `Email` and `Password` are set and non-empty:
 ```bash
-grep -A 2 "Email=" matterbridge.toml
+grep -E "Email|Password" matterbridge.toml
 ```
 
+### Authentication fails
+
+- Verify Chrome/Chromium is installed
+- Test credentials by logging in manually at app.kosmi.io
+- Delete cached token to force fresh auth: `rm data/kosmi_token_cache.json`
+- Enable debug logging: `-debug`
+
 ### Token expired
 
-The bridge should auto-refresh. If not:
-- Check logs for "Token refresh failed"
+The bridge automatically refreshes tokens expiring within 7 days. If refresh fails:
+- Check logs for authentication errors
 - Verify credentials are still valid
-- Try manual login at app.kosmi.io
+- Delete the token cache and restart
 
 ## Next Steps
 
-Once authenticated connection works:
-- Test reconnection (simulate network failure)
-- Monitor for token refresh (wait 24 hours)
-- Test with multiple rooms
-- Set up as systemd service
-
-See the monitoring script output and logs for detailed information about Kosmi's authentication behavior.
+- See [BROWSER_AUTH_GUIDE.md](BROWSER_AUTH_GUIDE.md) for full authentication details
+- See [TOKEN_PERSISTENCE.md](TOKEN_PERSISTENCE.md) for token caching behavior