docs: Add Task #90 - Arbiter 2.x Unified Access Manager

WHAT WAS DONE:
- Added Task #90 to tasks.md (Tier 1, Soft Launch Blocker)
- Documented complete architecture from Gemini consultation
- 5-phase implementation plan with detailed checklists
- Critical gotchas and technical specifications captured

WHY:
Tonight's Gemini consultation revealed current Whitelist Manager is
architecturally broken (hardcoded server names, unreliable WebSocket
status detection, no subscription integration). Solution: merge Arbiter
+ Whitelist Manager into single Node.js app with PostgreSQL backend.

GEMINI ARCHITECTURAL DECISIONS (validated March 31, 2026):
- Single unified app instead of separate microservices
- PostgreSQL for concurrent write safety at 500-user scale
- Discord /link slash command with Mojang API validation
- Pterodactyl File Management API (replace WebSocket console)
- Hybrid sync: event-driven push + hourly cron reconciliation
- Master whitelist = database, all servers sync from it

IMPLEMENTATION PHASES:
1. Database Migration (PostgreSQL setup, schema, indexes)
2. Core Functions (Mojang validation, Panel API clients)
3. Discord Integration (/link command, auto-DM subscribers)
4. Sync System (event-driven + cron, sequential processing)
5. Admin Panel (sync monitoring, manual triggers)

CRITICAL GOTCHAS CAPTURED:
- Content-Type: text/plain for Panel file write (not application/json)
- Mojang UUIDs without dashes, Minecraft needs WITH dashes
- HTTP 412 = server offline, NOT error (file saved for boot)
- Sequential processing prevents Panel API rate limiting

CONTEXT:
Discovered issues during attempt to fix Task #86 (Whitelist Manager
v1.12.1 compatibility). Realized entire architecture needs rewrite
for subscription-driven access control. Gemini provided complete
technical specification with code examples ready to implement.

BLOCKS:
- Soft launch (subscribers need automatic whitelist access)

RETIRES:
- Old Whitelist Manager (Python Flask on Billing VPS)
- Old Arbiter 1.x (if not already migrated)

FILES:
- docs/core/tasks.md (modified, +112 lines for Task #90)

NEXT STEPS:
- Create task directory: docs/tasks/arbiter-2x/
- Copy Gemini implementation guide to task directory
- Begin Phase 1: PostgreSQL database setup

Signed-off-by: The Golden Chronicler <claude@firefrostgaming.com>

docs/core/tasks.md

@@ -3003,6 +3003,114 @@ DERP (Disaster Emergency Recovery Protocol) was established as backup when Claud
 
 ---
 
+### 90. Arbiter 2.x - Unified Access Manager (Subscription → Whitelist Integration)
+**Time:** 20-30 hours (5 phases)  
+**Status:** OPEN — Architecture validated by Gemini, ready to build  
+**Priority:** Tier 1 — SOFT LAUNCH BLOCKER  
+**Documentation:** `docs/tasks/arbiter-2x/` + `/home/claude/arbiter-2x-implementation-guide.md`
+
+**WHAT THIS IS:**
+Complete rewrite of subscription → server access flow. Merges Arbiter (Discord roles) + Whitelist Manager (server access) into single Node.js application with PostgreSQL backend. Subscription-driven whitelist with master list synced to all Minecraft servers.
+
+**THE FLOW:**
+1. User subscribes (any tier, even $1 Awakened)
+2. Paymenter webhook → Arbiter assigns Discord role
+3. User links Minecraft account: `/link <username>` (Discord slash command)
+4. Arbiter validates via Mojang API, gets UUID
+5. Stores in PostgreSQL: discord_id, minecraft_username, minecraft_uuid
+6. Master whitelist auto-syncs to all whitelisted servers
+7. User can now join any Minecraft server
+
+**WHY REWRITE:**
+Current Whitelist Manager is broken:
+- Hardcoded server name keywords (fails when servers change)
+- WebSocket console commands (unreliable, returns "UNKNOWN")
+- No subscription integration
+- No master whitelist concept
+- Manual-only operation
+
+**ARCHITECTURE DECISIONS (Gemini validated March 31, 2026):**
+- ✅ Single Node.js app (Arbiter 2.x) instead of separate services
+- ✅ PostgreSQL instead of SQLite (concurrent write safety at scale)
+- ✅ Discord `/link` slash command (Mojang API validation)
+- ✅ Pterodactyl File Management API (not WebSocket console)
+- ✅ Hybrid sync: Event-driven push + hourly cron reconciliation
+- ✅ UUIDs WITH DASHES in whitelist.json (Minecraft 1.8+ requirement)
+
+**IMPLEMENTATION PHASES:**
+
+**Phase 1: Database Migration**
+- [ ] Provision PostgreSQL 15+ database
+- [ ] Execute schema creation (users, subscriptions, server_sync_log)
+- [ ] Apply indexes for 500-user scale optimization
+- [ ] Migrate legacy data from SQLite
+
+**Phase 2: Core Functions**
+- [ ] Initialize `pg` connection pool
+- [ ] Implement Mojang API validation + UUID formatting
+- [ ] Build Application API client for auto-discovery
+- [ ] Build Client API file write (`Content-Type: text/plain`)
+- [ ] Build Client API reload command (safe-fail on HTTP 412)
+
+**Phase 3: Discord Integration**
+- [ ] Register `/link <minecraft_username>` slash command
+- [ ] UUID validation flow on linking
+- [ ] Auto-DM new subscribers with link instructions
+- [ ] Update Paymenter webhook handler for role assignment
+
+**Phase 4: Sync System**
+- [ ] Event-driven immediate sync (on /link, on subscribe)
+- [ ] node-cron hourly reconciliation (0 * * * *)
+- [ ] Sequential batch processing (prevent rate limits)
+- [ ] Sync logging to server_sync_log table
+
+**Phase 5: Admin Panel & Testing**
+- [ ] Dashboard view for server_sync_log status
+- [ ] Manual "Force Sync" trigger button
+- [ ] View linked Minecraft accounts vs Discord IDs
+- [ ] Final testing and production deployment
+
+**CRITICAL GOTCHAS (from Gemini):**
+- `Content-Type: text/plain` for file write (NOT application/json)
+- Mojang returns UUIDs without dashes, Minecraft needs WITH dashes
+- HTTP 412 = server offline, NOT an error (file saved for next boot)
+- Sequential processing prevents Panel API rate limiting
+- Use Application API for discovery, Client API for file ops
+
+**DELIVERABLES:**
+- Arbiter 2.x Node.js application
+- PostgreSQL database with proper schema + indexes
+- `/link` Discord slash command with Mojang validation
+- Pterodactyl auto-discovery (by node allocation, not name)
+- Master whitelist sync system (event-driven + hourly cron)
+- Admin panel for sync monitoring + manual triggers
+- Complete migration from broken Whitelist Manager
+
+**DEPENDENCIES:**
+- PostgreSQL 15+
+- Node.js 20 LTS
+- Pterodactyl Panel v1.12.1 (Client + Application API keys)
+- Mojang API (public, no auth required)
+- Discord Bot with slash command permissions
+
+**SUCCESS CRITERIA:**
+- User subscribes → links Minecraft account → auto-whitelisted within 5 minutes
+- Master whitelist = single source of truth (database)
+- All servers sync from master list (hourly reconciliation)
+- Server discovery is automatic (no hardcoded names)
+- Works reliably for remote RV operations (no manual intervention)
+- Handles 500 subscribers by September 2027
+
+**RETIREMENT:**
+Once Arbiter 2.x deployed:
+- Retire old Whitelist Manager (Python Flask app on Billing VPS)
+- Retire old Arbiter 1.x (if not already migrated)
+- Update all documentation to reference new unified system
+
+**See implementation guide for complete technical specification with code examples.**
+
+---
+
 
 ---