From 5a2eee40fb333843023811b4d57556cbf4a2f3e6 Mon Sep 17 00:00:00 2001
From: Claude <claude@firefrostgaming.com>
Date: Sun, 22 Mar 2026 13:28:57 +0000
Subject: [PATCH] docs: Create Discord Bot Admin Panel guide + update
 Subscription Automation Guide

CREATED: docs/guides/discord-bot-admin-panel.md (new comprehensive guide)
- Complete implementation guide for web-based admin panel
- Architecture section (credits Gemini for design decisions)
- Security-first approach (dedicated firefrost-bot user, Discord OAuth2)
- Zero-downtime config updates (in-memory + atomic disk writes)
- Holly's usage guide (how to update role IDs via web interface)
- Full troubleshooting section
- Maintenance procedures

Key Features Documented:
- Discord OAuth2 authentication (no passwords)
- Whitelist authorization (Holly + Michael only)
- Role ID validation (regex + Discord API verification)
- Atomic file writes with backup strategy
- In-memory config updates (no bot restart needed)
- Audit logging to Discord channel
- HTTPS via Nginx + Let's Encrypt

Status: Awaiting backend/frontend code from Gemini

UPDATED: docs/guides/subscription-automation-guide.md
- Task 9 rewritten to reference new admin panel guide
- Added Option A (admin panel) vs Option B (manual SSH) paths
- Removed SSH instructions for Holly (she won't have access)
- Removed bot token from credentials file (security)
- Updated Holly's tasks section with admin panel option
- Preserved manual method as fallback

Why These Changes:
- Admin panel gives Holly independence (no waiting for Michael)
- Cleaner separation of concerns (setup vs usage)
- Security improvement (no SSH access needed for Holly)
- Better documentation structure (1000+ line guide split logically)

Architecture Credit: Gemini (Google AI) consultation on March 23, 2026

Chronicler #40
---
 docs/guides/discord-bot-admin-panel.md       | 930 +++++++++++++++++++
 docs/guides/subscription-automation-guide.md |  80 +-
 2 files changed, 992 insertions(+), 18 deletions(-)
 create mode 100644 docs/guides/discord-bot-admin-panel.md

diff --git a/docs/guides/discord-bot-admin-panel.md b/docs/guides/discord-bot-admin-panel.md
new file mode 100644
index 0000000..4bf4ccb
--- /dev/null
+++ b/docs/guides/discord-bot-admin-panel.md
@@ -0,0 +1,930 @@
+# Discord Bot Admin Panel - Implementation Guide
+
+**Version:** 1.0  
+**Date:** March 23, 2026  
+**Author:** Chronicler #40 (with architecture by Gemini/Google AI)  
+**Audience:** Michael (setup) + Holly (usage)  
+**Purpose:** Web-based admin panel for managing Discord bot role mappings
+
+---
+
+## 📋 TABLE OF CONTENTS
+
+1. [Overview](#overview)
+2. [Architecture](#architecture)
+3. [Why We Built This](#why-we-built-this)
+4. [Part 1: Prerequisites](#part-1-prerequisites)
+5. [Part 2: Create Dedicated Bot User](#part-2-create-dedicated-bot-user)
+6. [Part 3: Set Up Discord OAuth2 Application](#part-3-set-up-discord-oauth2-application)
+7. [Part 4: Deploy Backend Code](#part-4-deploy-backend-code)
+8. [Part 5: Deploy Frontend Code](#part-5-deploy-frontend-code)
+9. [Part 6: Configure Nginx & SSL](#part-6-configure-nginx-ssl)
+10. [Part 7: Holly's Usage Guide](#part-7-hollys-usage-guide)
+11. [Testing & Verification](#testing-verification)
+12. [Troubleshooting](#troubleshooting)
+13. [Maintenance](#maintenance)
+
+---
+
+## 🎯 OVERVIEW
+
+### What Is This?
+
+A secure web-based admin panel at `https://discord-bot.firefrostgaming.com/admin` where Holly can:
+- Log in using her Discord account (no passwords to remember)
+- Update Discord role mappings for all 10 subscription tiers
+- View bot status and recent webhook events
+- Save changes instantly (no SSH access needed)
+
+### The Problem We Solved
+
+**Before:**
+- Discord bot role mappings were hardcoded in `bot.js`
+- Holly had to give Michael the role IDs via Discord/email
+- Michael had to SSH into Command Center to update the file
+- Michael had to restart the bot manually
+- Holly waited for Michael's availability
+
+**After:**
+- Holly logs into web panel with Discord OAuth
+- Holly updates role IDs in a simple form
+- Changes save instantly (in-memory update, no restart)
+- Config written atomically to disk with backup
+- Role IDs validated against Discord API before saving
+- Audit log posted to Discord channel
+
+**Result:** Holly is independent, Michael isn't the bottleneck.
+
+---
+
+## 🏗️ ARCHITECTURE
+
+### Design Principles (Thanks to Gemini)
+
+This architecture was designed in consultation with Gemini (Google AI) and follows production best practices:
+
+**1. Security First**
+- Dedicated Linux user (`firefrost-bot`) - NOT root
+- Discord OAuth2 authentication (no password management)
+- Whitelist authorization (only Holly + Michael's Discord IDs)
+- HTTPS via Nginx + Let's Encrypt
+- CSRF protection on admin forms
+
+**2. Zero Downtime**
+- Configuration loaded into memory on startup
+- Updates modify in-memory config immediately
+- No bot restart required
+- Atomic disk writes (no corruption)
+- Backup of last-known-good config
+
+**3. Simplicity**
+- Single Node.js/Express app (webhook + admin in one)
+- JSON config file (no database needed for 10 key-value pairs)
+- Validation: Regex check + Discord API verification
+- In-memory webhook logs (last 50 events, rotating)
+
+**4. Auditability**
+- Discord `#bot-audit-logs` channel for config changes
+- Backup config file for disaster recovery
+- Systemd journal logs everything
+
+### Tech Stack
+
+**Backend:**
+- Node.js 18+
+- Express.js (web server)
+- discord.js (Discord API)
+- Passport.js (Discord OAuth2)
+- write-file-atomic (safe config saves)
+
+**Frontend:**
+- Simple HTML/CSS/JavaScript
+- Vanilla JS with `fetch()` API
+- No frameworks (keep it simple for Holly)
+- Fire/Frost branding
+
+**Infrastructure:**
+- Command Center (63.143.34.217)
+- Nginx reverse proxy
+- Let's Encrypt SSL
+- Systemd service
+
+---
+
+## 🤔 WHY WE BUILT THIS
+
+### Holly's Perspective
+
+**Before:**
+- "I created Discord roles, now I need to wait for Michael to update the bot."
+- "I want to test if the role IDs work, but I can't update them myself."
+- "If I make a typo in the role ID I give Michael, we have to repeat the whole process."
+
+**After:**
+- "I created Discord roles, I'll paste the IDs into the admin panel."
+- "I can test immediately - if a role ID is wrong, the panel tells me before saving."
+- "I'm independent - I can iterate and test without waiting."
+
+### Michael's Perspective
+
+**Before:**
+- "Holly needs role IDs updated. I have to stop what I'm doing, SSH in, edit the file, restart the bot."
+- "If I make a typo, Holly has to tell me, and I have to repeat the process."
+- "I'm the single point of failure for a 5-minute task."
+
+**After:**
+- "Holly handles her own role mappings. I only get involved if something breaks."
+- "The admin panel validates role IDs before saving, so typos get caught automatically."
+- "I set this up once, Holly uses it forever."
+
+---
+
+## ✅ PART 1: PREREQUISITES
+
+### Before You Start
+
+**On Command Center (63.143.34.217):**
+- [ ] Discord bot already running (from Subscription Automation Guide Part 1)
+- [ ] Bot accessible at `https://webhook.firefrostgaming.com/webhook/paymenter`
+- [ ] Node.js 18+ installed
+- [ ] Nginx installed and configured
+- [ ] SSL certificate (Let's Encrypt)
+
+**Discord Requirements:**
+- [ ] Discord bot application exists
+- [ ] Bot is in Firefrost Gaming Discord server
+- [ ] You have bot token
+- [ ] You have Guild ID (server ID)
+- [ ] You have Holly's Discord user ID
+- [ ] You have Michael's Discord user ID
+
+**DNS Configuration:**
+- [ ] `discord-bot.firefrostgaming.com` A record → 63.143.34.217
+- [ ] Cloudflare proxy: OFF (orange cloud = OFF)
+
+---
+
+## 🔧 PART 2: CREATE DEDICATED BOT USER
+
+**CRITICAL SECURITY FIX: Do NOT run the bot as root.**
+
+Running Node.js as root is a major security risk. If any npm package has a vulnerability, an attacker gets full control of Command Center.
+
+### Step 1: Create System User
+
+SSH to Command Center:
+
+```bash
+ssh root@63.143.34.217
+```
+
+Create dedicated user:
+
+```bash
+# Create system user (no login shell, no home directory login)
+sudo useradd -r -s /bin/false firefrost-bot
+
+# Verify user was created
+id firefrost-bot
+# Should show: uid=... gid=... groups=...
+```
+
+### Step 2: Transfer Ownership
+
+Transfer bot directory to new user:
+
+```bash
+# Change ownership of bot directory
+sudo chown -R firefrost-bot:firefrost-bot /opt/firefrost-discord-bot
+
+# Verify permissions
+ls -la /opt/firefrost-discord-bot
+# Should show: drwxr-xr-x ... firefrost-bot firefrost-bot
+```
+
+### Step 3: Update Systemd Service
+
+Edit the service file:
+
+```bash
+sudo nano /etc/systemd/system/firefrost-discord-bot.service
+```
+
+Update these lines:
+
+```ini
+[Service]
+User=firefrost-bot
+Group=firefrost-bot
+WorkingDirectory=/opt/firefrost-discord-bot
+ExecStart=/usr/bin/node /opt/firefrost-discord-bot/bot.js
+Restart=always
+RestartSec=10
+
+# Environment
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Reload and restart:
+
+```bash
+# Reload systemd
+sudo systemctl daemon-reload
+
+# Restart bot with new user
+sudo systemctl restart firefrost-discord-bot
+
+# Verify it's running
+sudo systemctl status firefrost-discord-bot
+# Should show: Active: active (running)
+
+# Check logs
+sudo journalctl -u firefrost-discord-bot -n 50
+# Should show no permission errors
+```
+
+**If you see permission errors:** Fix file permissions and retry.
+
+---
+
+## 🔐 PART 3: SET UP DISCORD OAUTH2 APPLICATION
+
+### Step 1: Discord Developer Portal
+
+1. Go to: https://discord.com/developers/applications
+2. Select your **Firefrost Subscription Manager** bot application
+3. Click **OAuth2** in left sidebar
+
+### Step 2: Add Redirect URLs
+
+Under **Redirects**, add:
+
+**For local testing (optional):**
+```
+http://localhost:3100/auth/discord/callback
+```
+
+**For production (required):**
+```
+https://discord-bot.firefrostgaming.com/auth/discord/callback
+```
+
+Click **Save Changes**.
+
+### Step 3: Copy Credentials
+
+**Copy these values (you'll need them for .env file):**
+
+- **Client ID:** (18-digit number under OAuth2 General)
+- **Client Secret:** Click "Reset Secret" → Copy the new secret
+
+**⚠️ IMPORTANT:** The Client Secret only shows once. Copy it immediately and save to Vaultwarden.
+
+### Step 4: Get Discord User IDs
+
+**Holly's Discord ID:**
+1. In Discord, right-click Holly's username
+2. Click "Copy User ID"
+3. Paste somewhere safe (e.g., `123456789012345678`)
+
+**Michael's Discord ID:**
+1. Same process for Michael's account
+2. Paste somewhere safe
+
+**Note:** If "Copy User ID" doesn't appear, enable Developer Mode:
+- Discord Settings → Advanced → Developer Mode (toggle ON)
+
+---
+
+## 💻 PART 4: DEPLOY BACKEND CODE
+
+### Step 1: Install Dependencies
+
+SSH to Command Center:
+
+```bash
+ssh root@63.143.34.217
+cd /opt/firefrost-discord-bot
+```
+
+Install required npm packages:
+
+```bash
+npm install express express-session passport passport-discord write-file-atomic dotenv
+```
+
+### Step 2: Create .env File
+
+Create environment variables file:
+
+```bash
+nano /opt/firefrost-discord-bot/.env
+```
+
+Add these values (replace with your actual credentials):
+
+```env
+# Discord Bot
+DISCORD_TOKEN=your_bot_token_here
+DISCORD_CLIENT_ID=your_oauth_client_id_here
+DISCORD_CLIENT_SECRET=your_oauth_client_secret_here
+GUILD_ID=your_discord_server_id_here
+
+# OAuth2
+CALLBACK_URL=https://discord-bot.firefrostgaming.com/auth/discord/callback
+
+# Session
+SESSION_SECRET=generate_a_very_long_random_string_here
+
+# Authorization
+ALLOWED_ADMINS=HOLLYS_DISCORD_ID,MICHAELS_DISCORD_ID
+
+# Environment
+NODE_ENV=production
+```
+
+**Generate SESSION_SECRET:**
+
+```bash
+# Generate random 64-character string
+openssl rand -base64 48
+```
+
+Copy the output and use it for `SESSION_SECRET`.
+
+**Save and exit:** `Ctrl+X`, `Y`, `Enter`
+
+**Set file permissions:**
+
+```bash
+# .env file should only be readable by firefrost-bot user
+chmod 600 /opt/firefrost-discord-bot/.env
+chown firefrost-bot:firefrost-bot /opt/firefrost-discord-bot/.env
+```
+
+### Step 3: Backend Code Implementation
+
+**⚠️ WAITING ON GEMINI:** The complete backend code is being provided by Gemini (Google AI).
+
+**Once received, the backend code will include:**
+- Express server setup
+- Discord OAuth2 authentication
+- In-memory config management
+- Atomic file writes with backup
+- Role ID validation (regex + Discord API)
+- Admin API endpoints
+- Webhook logging
+
+**File will be:** `/opt/firefrost-discord-bot/bot.js` (replaces existing file)
+
+**Status:** Awaiting Gemini's response with complete backend implementation.
+
+---
+
+## 🎨 PART 5: DEPLOY FRONTEND CODE
+
+**⚠️ WAITING ON GEMINI:** The frontend HTML/CSS/JS is being written by Gemini (Google AI).
+
+**Once received, the frontend will include:**
+- Discord OAuth login flow
+- Role mapping management form (10 product → role ID pairs)
+- Save functionality with validation feedback
+- Bot status display
+- Recent webhook logs table
+- Logout button
+- Fire/Frost branding
+
+**Files will be created in:** `/opt/firefrost-discord-bot/public/`
+
+**Status:** Awaiting Gemini's response with complete frontend implementation.
+
+---
+
+## 🌐 PART 6: CONFIGURE NGINX & SSL
+
+### Step 1: Create Nginx Configuration
+
+Create new site config:
+
+```bash
+sudo nano /etc/nginx/sites-available/discord-bot-admin
+```
+
+Add this configuration:
+
+```nginx
+server {
+    listen 80;
+    server_name discord-bot.firefrostgaming.com;
+    
+    # Redirect HTTP to HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name discord-bot.firefrostgaming.com;
+    
+    # SSL Configuration (Let's Encrypt)
+    ssl_certificate /etc/letsencrypt/live/discord-bot.firefrostgaming.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/discord-bot.firefrostgaming.com/privkey.pem;
+    include /etc/letsencrypt/options-ssl-nginx.conf;
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+    
+    # Security Headers
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    
+    # Proxy to Node.js app
+    location / {
+        proxy_pass http://localhost:3100;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+        
+        # Timeouts
+        proxy_connect_timeout 60s;
+        proxy_send_timeout 60s;
+        proxy_read_timeout 60s;
+    }
+}
+```
+
+Save and exit.
+
+### Step 2: Enable Site
+
+```bash
+# Create symlink to enable site
+sudo ln -s /etc/nginx/sites-available/discord-bot-admin /etc/nginx/sites-enabled/
+
+# Test Nginx configuration
+sudo nginx -t
+# Should show: syntax is okay, test is successful
+
+# Reload Nginx
+sudo systemctl reload nginx
+```
+
+### Step 3: Obtain SSL Certificate
+
+```bash
+# Install certbot if not already installed
+sudo apt install certbot python3-certbot-nginx -y
+
+# Obtain certificate
+sudo certbot --nginx -d discord-bot.firefrostgaming.com
+
+# Follow prompts:
+# - Enter email address
+# - Agree to Terms of Service
+# - Choose: Redirect HTTP to HTTPS (option 2)
+```
+
+**Certbot will automatically:**
+- Obtain SSL certificate
+- Configure Nginx SSL settings
+- Set up auto-renewal
+
+### Step 4: Verify SSL
+
+Test in browser:
+
+```
+https://discord-bot.firefrostgaming.com
+```
+
+Should show valid SSL certificate (green lock icon).
+
+---
+
+## 👥 PART 7: HOLLY'S USAGE GUIDE
+
+**This section is for Holly - how to use the admin panel.**
+
+### When You Need This
+
+Use the admin panel when:
+- ✅ You've created new Discord roles
+- ✅ You need to update role IDs in the bot
+- ✅ You want to test if role IDs are correct
+- ✅ You need to change a role mapping
+
+### Step 1: Log In
+
+1. Open browser (Chrome, Firefox, Edge)
+2. Go to: `https://discord-bot.firefrostgaming.com/admin`
+3. Click **"Login with Discord"** button
+4. Discord OAuth page appears
+5. Click **"Authorize"**
+6. You're redirected back to admin panel
+
+**Note:** You only need to log in once - browser remembers you via session cookie.
+
+### Step 2: View Current Mappings
+
+Admin panel shows current role mappings:
+
+```
+Product 2 (The Awakened):      [123456789012345678]
+Product 3 (Fire Elemental):    [234567890123456789]
+Product 4 (Frost Elemental):   [345678901234567890]
+...
+```
+
+These are the Discord role IDs currently in use.
+
+### Step 3: Update Role IDs
+
+**When you create Discord roles:**
+
+1. In Discord, go to Server Settings → Roles
+2. Right-click a role → Copy ID
+3. Paste into appropriate field in admin panel
+4. Repeat for all 10 roles
+
+**Example:**
+
+You created "🔥 Fire Elemental" role in Discord:
+1. Right-click role → Copy ID → `987654321098765432`
+2. In admin panel, find "Product 3 (Fire Elemental)" field
+3. Paste: `987654321098765432`
+
+### Step 4: Save Changes
+
+1. Click **"Save All Changes"** button
+2. Panel validates each role ID:
+   - ✅ Checks format (must be 18-19 digit number)
+   - ✅ Verifies role exists in Discord server
+3. If validation passes:
+   - ✅ Config saved to disk
+   - ✅ In-memory config updated (instant effect)
+   - ✅ Audit log posted to Discord `#bot-audit-logs`
+   - ✅ Success message appears: "All role mappings updated!"
+4. If validation fails:
+   - ❌ Error message shows which role ID is invalid
+   - ❌ Config NOT saved (prevents bot from breaking)
+   - ❌ Fix the invalid role ID and try again
+
+### Step 5: Test Webhook
+
+After saving role mappings:
+
+1. Go to Paymenter test page (ask Michael for URL)
+2. Create test purchase for $5 Fire Elemental tier
+3. Check Discord - does bot assign "🔥 Fire Elemental" role?
+4. If yes: ✅ Role mapping works!
+5. If no: ❌ Check bot logs or ask Michael
+
+### Step 6: Logout (Optional)
+
+Click **"Logout"** button when done.
+
+**Note:** You can stay logged in - session expires after 24 hours.
+
+---
+
+## ✅ TESTING & VERIFICATION
+
+### Test Checklist
+
+After deployment, verify:
+
+#### 1. Bot User Running Correctly
+
+```bash
+# Check service status
+sudo systemctl status firefrost-discord-bot
+
+# Should show:
+# - Active: active (running)
+# - User: firefrost-bot (NOT root)
+```
+
+#### 2. OAuth Login Works
+
+1. Open `https://discord-bot.firefrostgaming.com/admin`
+2. Click "Login with Discord"
+3. Authorize
+4. Should redirect to admin panel
+5. Should see current role mappings
+
+#### 3. Role ID Validation Works
+
+**Test invalid role ID:**
+1. Enter `123` (too short) in any field
+2. Click "Save All Changes"
+3. Should show error: "Invalid Discord Role ID format"
+
+**Test non-existent role ID:**
+1. Enter `999999999999999999` (valid format, but role doesn't exist)
+2. Click "Save All Changes"
+3. Should show error: "Role does not exist in Discord server"
+
+**Test valid role ID:**
+1. Create test role in Discord
+2. Copy role ID
+3. Paste in admin panel
+4. Click "Save All Changes"
+5. Should show: "All role mappings updated successfully!"
+
+#### 4. Config Persists After Restart
+
+```bash
+# Restart bot
+sudo systemctl restart firefrost-discord-bot
+
+# Reload admin panel in browser
+# Should still show saved role mappings (loaded from config.json)
+```
+
+#### 5. Backup File Created
+
+```bash
+# Check for backup
+ls -la /opt/firefrost-discord-bot/config.json.backup
+
+# Should exist after first save
+```
+
+#### 6. Audit Logs Appear in Discord
+
+1. Make a config change in admin panel
+2. Check Discord `#bot-audit-logs` channel
+3. Should see embed with:
+   - Author: Holly (or Michael)
+   - Action: Updated Role Mappings
+   - Changes: Product X: old_id → new_id
+
+---
+
+## 🔧 TROUBLESHOOTING
+
+### Problem: "Unauthorized" Error When Accessing Admin Panel
+
+**Symptoms:** Can't access `/admin`, get 401 error.
+
+**Causes:**
+1. Not logged in via Discord OAuth
+2. Your Discord ID isn't in `ALLOWED_ADMINS` list
+
+**Solutions:**
+
+**Check if logged in:**
+- Clear browser cookies
+- Try logging in again via "Login with Discord"
+
+**Check whitelist:**
+
+```bash
+# On Command Center
+cat /opt/firefrost-discord-bot/.env | grep ALLOWED_ADMINS
+```
+
+Should show Holly's and Michael's Discord IDs separated by comma.
+
+**If your ID is missing:**
+
+```bash
+# Edit .env
+sudo nano /opt/firefrost-discord-bot/.env
+
+# Add your Discord ID to ALLOWED_ADMINS
+ALLOWED_ADMINS=HOLLYS_ID,MICHAELS_ID,YOUR_ID
+
+# Save and restart bot
+sudo systemctl restart firefrost-discord-bot
+```
+
+---
+
+### Problem: "Role does not exist in Discord server" Error
+
+**Symptoms:** Valid-looking role ID rejected during save.
+
+**Causes:**
+1. Role ID is from wrong Discord server
+2. Role was deleted after you copied ID
+3. Bot doesn't have permission to see roles
+
+**Solutions:**
+
+**Verify role exists:**
+1. Go to Discord Server Settings → Roles
+2. Find the role
+3. Right-click → Copy ID again
+4. Paste fresh ID into admin panel
+
+**Check bot permissions:**
+1. Discord Server Settings → Roles
+2. Find "Firefrost Subscription Manager" bot role
+3. Ensure it has "Manage Roles" permission
+4. Ensure bot role is ABOVE the roles it needs to assign
+
+---
+
+### Problem: Admin Panel Shows Old Role Mappings
+
+**Symptoms:** You saved new IDs, but admin panel shows old ones after refresh.
+
+**Causes:**
+1. Browser cache
+2. Config file didn't save
+3. In-memory config didn't update
+
+**Solutions:**
+
+**Hard refresh browser:**
+- Windows: `Ctrl + Shift + R`
+- Mac: `Cmd + Shift + R`
+
+**Check config file:**
+
+```bash
+# On Command Center
+cat /opt/firefrost-discord-bot/config.json
+```
+
+Should show your latest role IDs.
+
+**If config.json is outdated:**
+
+```bash
+# Restart bot
+sudo systemctl restart firefrost-discord-bot
+
+# Try saving again in admin panel
+```
+
+---
+
+### Problem: OAuth Login Redirects to "Cannot GET /auth/discord/callback"
+
+**Symptoms:** After clicking "Authorize" in Discord, get error page.
+
+**Causes:**
+1. Callback URL mismatch in Discord Developer Portal
+2. Backend route not set up correctly
+
+**Solutions:**
+
+**Check Discord Developer Portal:**
+1. Go to: https://discord.com/developers/applications
+2. Select your bot app → OAuth2
+3. Under Redirects, verify you have:
+   `https://discord-bot.firefrostgaming.com/auth/discord/callback`
+4. Save changes if missing
+
+**Check .env file:**
+
+```bash
+cat /opt/firefrost-discord-bot/.env | grep CALLBACK_URL
+```
+
+Should match Discord Developer Portal exactly.
+
+**Restart bot:**
+
+```bash
+sudo systemctl restart firefrost-discord-bot
+```
+
+---
+
+### Problem: Bot Assigns Wrong Role After Config Update
+
+**Symptoms:** Config saved successfully, but webhook assigns incorrect role.
+
+**Causes:**
+1. Product ID → Role ID mapping is wrong
+2. In-memory config didn't update
+
+**Solutions:**
+
+**Verify mapping in admin panel:**
+
+Product 3 should map to Fire Elemental role ID, not Frost Elemental.
+
+**Check config.json:**
+
+```bash
+cat /opt/firefrost-discord-bot/config.json
+```
+
+Should show correct mappings.
+
+**Restart bot (force reload):**
+
+```bash
+sudo systemctl restart firefrost-discord-bot
+```
+
+**Test webhook again.**
+
+---
+
+## 🔄 MAINTENANCE
+
+### Regular Tasks
+
+**Weekly:**
+- Check bot logs for errors: `sudo journalctl -u firefrost-discord-bot -n 100`
+- Verify SSL certificate is valid (auto-renewed by certbot)
+
+**Monthly:**
+- Review audit logs in Discord `#bot-audit-logs`
+- Verify backup config exists: `ls -la /opt/firefrost-discord-bot/config.json.backup`
+
+**As Needed:**
+- Update role mappings when creating new Discord roles
+- Add/remove admin users from `ALLOWED_ADMINS` in `.env`
+
+### Backup Strategy
+
+**Config is backed up automatically:**
+- Every save creates `config.json.backup`
+- Contains last-known-good configuration
+
+**To restore from backup:**
+
+```bash
+# SSH to Command Center
+cd /opt/firefrost-discord-bot
+
+# Copy backup to active config
+cp config.json.backup config.json
+
+# Restart bot
+sudo systemctl restart firefrost-discord-bot
+```
+
+### Updating Backend Code
+
+If Gemini provides code updates:
+
+```bash
+# SSH to Command Center
+cd /opt/firefrost-discord-bot
+
+# Backup current code
+cp bot.js bot.js.backup
+
+# Edit bot.js with new code
+sudo nano bot.js
+
+# Test syntax (optional)
+node --check bot.js
+
+# Restart bot
+sudo systemctl restart firefrost-discord-bot
+
+# Check logs
+sudo journalctl -u firefrost-discord-bot -n 50
+```
+
+---
+
+## 📚 RELATED DOCUMENTATION
+
+**See also:**
+- `docs/guides/subscription-automation-guide.md` - Full subscription workflow
+- `docs/guides/server-side-mod-deployment-guide.md` - LuckPerms configuration
+
+---
+
+## 🙏 CREDITS
+
+**Architecture Design:** Gemini (Google AI)  
+**Implementation:** Chronicler #40 (Claude) + Michael  
+**Testing:** Holly + Michael  
+**Consultation Date:** March 23, 2026
+
+**Key Architectural Decisions by Gemini:**
+- Run as dedicated `firefrost-bot` user (NOT root) - critical security fix
+- In-memory config updates (no restart needed) - zero downtime
+- Discord OAuth2 (no password management) - better security
+- Atomic file writes with backup (prevents corruption) - reliability
+- Discord API validation (verify roles exist) - prevents errors
+
+**Thank you, Gemini, for the excellent architectural guidance.** 🙏
+
+---
+
+**Fire + Frost + Foundation = Where Love Builds Legacy** 🔥❄️
+
+**Status:** Backend and Frontend code pending from Gemini  
+**Last Updated:** March 23, 2026  
+**Next Update:** When Gemini provides implementation code
+
+---
+
+**END OF GUIDE**
diff --git a/docs/guides/subscription-automation-guide.md b/docs/guides/subscription-automation-guide.md
index 06c3b10..cf4d23a 100644
--- a/docs/guides/subscription-automation-guide.md
+++ b/docs/guides/subscription-automation-guide.md
@@ -555,34 +555,70 @@ curl https://webhook.firefrostgaming.com/health
 {"status":"healthy","bot":"Firefrost Subscription Manager#1234","uptime":123.456}
 ```
 
-### Task 9: Prepare Information for Holly
+### Task 9: Set Up Discord Bot Admin Panel
 
-**Create a file with all the info Holly needs:**
+**PURPOSE:** Deploy web interface so Holly can manage Discord role mappings herself (no SSH access needed).
+
+**⚠️ IMPORTANT:** Complete admin panel setup is documented in a separate guide.
+
+**See:** `docs/guides/discord-bot-admin-panel.md`
+
+**Quick Overview:**
+
+The admin panel allows Holly to:
+- Log in via Discord OAuth (no passwords)
+- Update all 10 product → Discord role ID mappings
+- Save changes instantly (no bot restart needed)
+- View bot status and recent webhooks
+
+**Setup Steps (High-Level):**
+
+1. Create dedicated `firefrost-bot` Linux user (security - don't run as root)
+2. Set up Discord OAuth2 application
+3. Deploy backend code (provided by Gemini/Google AI)
+4. Deploy frontend code (provided by Gemini/Google AI)
+5. Configure Nginx reverse proxy + SSL
+6. Give Holly admin panel URL and walk through usage
+
+**Time Required:** 2-3 hours (one-time setup)
+
+**Once Complete:**
+
+Holly will access admin panel at:
+```
+https://discord-bot.firefrostgaming.com/admin
+```
+
+**Status:** Full implementation guide available at `docs/guides/discord-bot-admin-panel.md`
+
+**For now, continue with manual method below (Holly gives you role IDs, you update bot.js). We'll migrate to admin panel later.**
+
+---
+
+### Task 9 (ALTERNATIVE - MANUAL METHOD)
+
+**If admin panel isn't set up yet, use this manual approach:**
+
+Create a credentials file for Holly:
 
 ```bash
 cat > /root/holly-bot-credentials.txt << EOF
 Firefrost Discord Bot - Credentials for Holly
 
 Bot Name: Firefrost Subscription Manager
-Bot Token: $(grep "const DISCORD_TOKEN" /opt/firefrost-discord-bot/bot.js | cut -d"'" -f2)
 Guild ID: $(grep "const GUILD_ID" /opt/firefrost-discord-bot/bot.js | cut -d"'" -f2)
 
 Webhook URL: https://webhook.firefrostgaming.com/webhook/paymenter
 
-Bot is installed on: Command Center (63.143.34.217)
-Bot directory: /opt/firefrost-discord-bot/
-Service name: firefrost-discord-bot
-
-Commands for Holly:
-- View logs: journalctl -u firefrost-discord-bot -f
-- Restart bot: systemctl restart firefrost-discord-bot
-- Edit bot code: nano /opt/firefrost-discord-bot/bot.js
-
 Next Steps:
 1. Holly creates Discord roles (Part 2 of guide)
-2. Holly gets role IDs and updates bot.js PRODUCT_ROLE_MAP
-3. Holly restarts bot: systemctl restart firefrost-discord-bot
-4. Test webhook flow
+2. Holly gets role IDs and sends them to Michael
+3. Michael updates bot.js PRODUCT_ROLE_MAP with role IDs
+4. Michael restarts bot: systemctl restart firefrost-discord-bot
+5. Test webhook flow
+
+NOTE: Once admin panel is deployed, Holly can update role IDs herself.
+See: docs/guides/discord-bot-admin-panel.md
 
 ---
 Generated: $(date)
@@ -624,9 +660,17 @@ cat /root/holly-bot-credentials.txt
 
 **Holly, you now need to:**
 1. Create Discord roles (Part 2)
-2. Update bot code with role IDs
-3. Configure LuckPerms
-4. Test the complete flow
+2. **EITHER:**
+   - **Option A (Recommended):** Use Discord Bot Admin Panel at `discord-bot.firefrostgaming.com/admin` to update role IDs
+   - **Option B (Manual):** Give role IDs to Michael, he updates bot.js via SSH
+3. Configure LuckPerms groups and permissions (Part 3)
+4. Set up LuckPerms Discord integration (Part 4)
+5. Configure Paymenter webhooks (Part 5)
+6. Test the complete flow
+
+**Note:** If admin panel is set up (Option A), you can update role mappings yourself anytime. If not (Option B), you'll need Michael's help each time roles change.
+
+**Admin panel documentation:** `docs/guides/discord-bot-admin-panel.md`
 
 ---