firefrost-operations-manual/docs/tasks/firefrost-codex/README.md

# Firefrost Codex - AI Assistant Deployment

**Status:** Ready to Deploy  
**Priority:** Tier 2 - Major Infrastructure  
**Time Estimate:** 8-12 hours (4-6 active, rest downloads)  
**Location:** TX1 Dallas (38.68.14.26)  
**Domain:** codex.firefrostgaming.com (or ai.firefrostgaming.com)  
**Last Updated:** February 20, 2026  
**Created By:** The Chronicler

---

## Executive Summary

**Firefrost Codex** is a self-hosted AI assistant that provides 24/7 support to all levels of the Firefrost Gaming community. Built on AnythingLLM with local LLM models, Codex serves as "Claude for everyone" - giving subscribers, staff, and founders intelligent assistance trained on Firefrost-specific knowledge.

**The Vision:** Most Minecraft servers have Discord. We have an AI.

**Monthly Cost:** $0 (self-hosted on existing TX1 infrastructure)

---

## What is Firefrost Codex?

### The Three Names Strategy

1. **Codex** (Casual) - Discord mentions, daily use, friendly interactions
2. **The Codex** (Formal) - Official docs, announcements, system references
3. **Firefrost Codex** (Full Brand) - Marketing, external communications, press

### The Core Concept

**Codex = A comprehensive collection of knowledge preserved for future generations**

Firefrost Codex is the living knowledge base that grows with every lesson learned, every problem solved, every discovery made. It's the legacy we're building for children not yet born.

---

## Architecture Overview

### Technology Stack

**Platform:** AnythingLLM (self-hosted)  
**Vector Database:** LanceDB (built-in, efficient)  
**LLM Server:** Ollama  
**Models:**
- Qwen 2.5 Coder 72B (coding/infrastructure)
- Llama 3.3 70B (general reasoning)
- Llama 3.2 Vision 11B (image analysis)

**Integrations:**
- Discord Bot (role-based access)
- Web Interface (multi-user with RBAC)
- Embedded Chat Widgets (public + subscriber sites)
- mclo.gs API (Minecraft log analysis)

---

## Five-Tier Access Architecture

### 1. Public (No Authentication)
**Access:** Embedded widget on firefrostgaming.com  
**Workspace:** Public KB  
**Content:** Marketing, server info, how to join, Fire vs Frost philosophy  
**Delivery:** Chat bubble on main website (unauthenticated)  

**Purpose:** Convert visitors into subscribers

---

### 2. Subscribers (Awakened $1+)
**Access:** Discord bot + Web interface + Subscriber website widget  
**Role:** Default  
**Workspace:** Subscriber KB  
**Content:**
- Gameplay guides and tutorials
- Commands per tier
- Modpack-specific guides
- Troubleshooting (including mclo.gs analysis)
- Chunk claiming, homes, permissions
- Path-specific content (Fire vs Frost)

**Example Use Cases:**
- "How do I claim chunks on ATM10?"
- "Analyze this crash: https://mclo.gs/abc123"
- "What commands do I have as Elemental tier?"
- "Teach me Create mod basics"

---

### 3. Staff (Future Hires)
**Access:** Discord bot + Web interface  
**Role:** Manager  
**Workspaces:** Operations, Brainstorming, Subscriber KB  
**Content:**
- Infrastructure procedures
- Server management guides
- Whitelist Manager usage
- Support protocols
- Emergency procedures (DERP)
- How to answer subscriber questions

**Example Use Cases:**
- "How do I use the Whitelist Manager?"
- "What's the procedure for server restarts?"
- "How do I handle a billing issue?"

---

### 4. Michael + Meg (Founders)
**Access:** Everything  
**Role:** Admin  
**Workspaces:** All 5 (Public KB, Subscriber KB, Operations, Brainstorming, Relationship)  
**Content:** Complete access to all knowledge  

**Additional Capabilities:**
- User management
- System settings (LLM configuration)
- Analytics and logs
- API key management
- Embedded widget creation
- Full administration

---

### 5. Potential Subscribers (Tier 0: Wanderers)
**Access:** Embedded widget on firefrostgaming.com  
**Same as Public tier** - designed to educate and convert

---

## The Five Workspaces

### Workspace 1: Public KB
**Access:** Anyone (unauthenticated)  
**Delivery:** Embedded widget only  
**Purpose:** Marketing and conversion  

**Content:**
- What is Firefrost Gaming?
- Server list and modpack descriptions
- Fire vs Frost philosophy
- Subscription tier comparison
- Getting started guide
- Community values and rules
- FAQ
- How to join Discord

**Rate Limiting:** Yes (prevent abuse)  
**Query Mode:** Query-only (answers must relate to documents)

---

### Workspace 2: Subscriber KB
**Access:** Awakened ($1+) and above  
**Delivery:** Discord bot, web interface, embedded widget  
**Purpose:** Subscriber support and education  

**Content:**
- Server connection details
- Modpack guides and tutorials
- Commands and permissions per tier
- Chunk claiming and homes guides
- Path-specific content
- Technical troubleshooting
- mclo.gs log analysis database
- Performance optimization
- Mod-specific tutorials

**Special Features:**
- mclo.gs integration (automatic log analysis)
- Tier-aware responses (knows what commands each tier has)
- Path-aware (Fire vs Frost specific content)

---

### Workspace 3: Operations
**Access:** Staff and Admin only  
**Delivery:** Discord bot, web interface  
**Purpose:** Running the business  

**Content:**
- Infrastructure documentation
- Server management procedures
- Whitelist Manager usage
- Support procedures and scripts
- Emergency protocols
- DERP documentation
- Billing procedures
- Staff onboarding

---

### Workspace 4: Brainstorming
**Access:** Admin and Staff  
**Delivery:** Web interface  
**Purpose:** Planning and strategy  

**Content:**
- Planning documents
- Future roadmaps
- Design discussions
- Community initiatives
- Expansion planning

---

### Workspace 5: Relationship
**Access:** Admin only (Michael + Meg)  
**Delivery:** Web interface  
**Purpose:** Claude partnership continuity  

**Content:**
- The Essence Patch
- Session handoff protocols
- Partnership context
- The Chronicler lineage
- Private strategic discussions

---

## Access Methods Comparison

| Method | Public | Subscribers | Staff | Admins |
|--------|--------|-------------|-------|--------|
| **Main Website Widget** | ✅ Public KB | - | - | - |
| **Subscriber Website Widget** | - | ✅ Subscriber KB | - | - |
| **Discord Bot** | ❌ | ✅ Subscriber KB | ✅ Operations | ✅ All |
| **Web Interface (codex.firefrostgaming.com)** | ❌ | ✅ Subscriber KB | ✅ Ops + Brain + Sub | ✅ All 5 |

---

## Discord Bot Features

### Commands

**For Subscribers:**
- `/ask [question]` - Query Subscriber KB workspace
- `/analyze [mclo.gs URL]` - Automatic log analysis
- `/help` - Show available commands

**For Staff:**
- `/ask [question]` - Query Operations workspace
- `/operations [question]` - Explicit operations query
- `/subscriber-help [question]` - Query Subscriber KB to help answer user questions
- `/analyze [mclo.gs URL]` - Log analysis

**For Admins:**
- All staff commands plus:
- `/workspace [name]` - Switch workspaces
- `/brainstorm [question]` - Query brainstorming workspace

### Role-Based Routing

```python
def get_workspace(user_role):
    if user_role == 'subscriber':
        return 'subscriber-kb'
    elif user_role == 'staff':
        return 'operations'
    elif user_role == 'admin':
        return 'all'  # Can switch
    else:
        return None  # No access
```

---

## mclo.gs Integration

### What is mclo.gs?

mclo.gs is a Minecraft log sharing and analysis service. Players upload server/client logs and get a shareable URL with automatic problem detection.

### How Codex Uses It

**User Flow:**
1. Subscriber runs `/mclogs` command in-game → generates mclo.gs link
2. Subscriber shares link with Codex: `@Codex analyze https://mclo.gs/abc123`
3. Codex fetches log via API
4. Codex analyzes with AI + knowledge base
5. Codex provides diagnosis + solutions + relevant docs

**Example Interaction:**
```
User: @Codex https://mclo.gs/xyz789 - my server keeps crashing

Codex: 🔍 Analyzing your log...

📊 **Log Analysis Results:**

**Problem Detected:** OutOfMemoryError in All The Mods 10
- Server allocated 20GB RAM, used 20GB
- Crash during chunk generation in the Nether

**Root Cause:**
ATM10 requires more memory than allocated, especially during chunk generation in modded dimensions.

**Solutions:**
1. **Increase RAM allocation to 24GB** (recommended for stable ATM10)
   - In your launcher, change `-Xmx20G` to `-Xmx24G`
   
2. **Reduce render distance** (temporary fix)
   - Edit server.properties: `view-distance=8` (currently 10)
   
3. **Pre-generate chunks** (prevents future crashes)
   - Use Chunky mod to pre-generate Nether chunks

**Related Docs:**
📚 [ATM10 Memory Requirements](link)
📚 [Chunk Pre-generation Guide](link)
📚 [Launcher RAM Settings](link)

Need help with any of these steps? Just ask!
```

### Technical Implementation

**API Call:**
```python
# Fetch log from mclo.gs
response = requests.get(f"https://api.mclo.gs/1/log/{log_id}")
data = response.json()

# Extract relevant info
log_content = data['content']
detected_problems = data['analysis']['problems']
server_info = data['analysis']['information']

# Send to Codex with context
prompt = f"""
Analyze this Minecraft server log:

{log_content}

mclo.gs detected: {detected_problems}
Server info: {server_info}

Provide diagnosis and step-by-step solutions.
"""

response = anythingllm_api.chat(workspace="subscriber-kb", query=prompt)
```

---

## Web Interface Experience

### Subscriber Dashboard
```
Codex - Logged in as: username123

My Workspaces:
📚 Subscriber Knowledge Base  [Open Chat]

Recent Chats:
- How to claim chunks on ATM10
- Crash log analysis
- Create mod water wheel tutorial

Settings:
👤 My Profile
🔒 Change Password
🚪 Logout
```

### Staff Dashboard
```
Codex - Logged in as: staffmember

My Workspaces:
📚 Subscriber Knowledge Base  [Open Chat]
⚙️ Operations                [Open Chat]
💡 Brainstorming             [Open Chat]

Quick Actions:
🔍 Search all workspaces
📊 View recent subscriber questions
🛠️ Infrastructure status

Settings:
👤 My Profile
🔒 Change Password
```

### Admin Dashboard (Michael/Meg)
```
Firefrost Codex - Admin Panel

Workspaces:
🌐 Public KB                 [Open] [Manage] [Analytics]
📚 Subscriber Knowledge Base [Open] [Manage] [Analytics]
⚙️ Operations                [Open] [Manage] [Analytics]
💡 Brainstorming             [Open] [Manage] [Analytics]
💙 Relationship              [Open] [Manage] [Analytics]

Administration:
👥 User Management (Create, Edit, Delete users)
🛠️ System Settings (LLM, Embedder, Vector DB)
📊 Analytics & Logs (Usage, popular queries)
🔑 API Keys (Generate, manage, revoke)
🪟 Embedded Widgets (Create, configure)
🎨 Appearance (Branding, colors, logos)

System Status:
✅ AnythingLLM: Online
✅ Ollama: Online (3 models loaded)
✅ Vector DB: 1,247 documents indexed
✅ Discord Bot: Connected
✅ Uptime: 47 days
```

---

## Resource Requirements

### TX1 Dallas Specifications
- **CPU:** 32 vCPU (AMD EPYC)
- **RAM:** 256GB total
- **Storage:** 1TB NVMe

### Codex Resource Usage

**Storage (~97GB):**
- Qwen 2.5 Coder 72B: ~40GB
- Llama 3.3 70B: ~40GB
- Llama 3.2 Vision 11B: ~7GB
- AnythingLLM + services: ~10GB

**RAM (varies by mode):**
- **Idle (models unloaded):** ~4GB (AnythingLLM services only)
- **Active (one large model loaded):** ~92GB
  - Model: ~80GB (Qwen OR Llama 3.3)
  - AnythingLLM: ~4GB
  - Overhead: ~8GB

**CPU:**
- Inference slower than cloud APIs
- 32 vCPU sufficient for concurrent users
- Background model loading/unloading

**Available Headroom:**
- RAM: 256GB - 92GB = 164GB free (plenty for game servers)
- Storage: 1TB - 97GB = 903GB free
- CPU: Shared with game servers, no issues expected

---

## Deployment Phases

### Phase 1: Core Infrastructure (3-4 hours)
1. Deploy AnythingLLM via Docker
2. Install Ollama
3. Configure multi-user mode
4. Create admin accounts (Michael + Meg)
5. Configure Nginx reverse proxy + SSL
6. Initial testing

### Phase 2: Model Downloads (Overnight - 6-8 hours)
1. Download Qwen 2.5 Coder 72B (~40GB)
2. Download Llama 3.3 70B (~40GB)
3. Download Llama 3.2 Vision 11B (~7GB)
4. Test model loading
5. Configure Ollama as AnythingLLM backend

### Phase 3: Workspace Setup (2-3 hours)
1. Create 5 workspaces
2. Upload documents to each workspace
3. Configure workspace permissions
4. Test knowledge retrieval
5. Optimize embedding settings

### Phase 4: Discord Bot (2-3 hours)
1. Create Discord application
2. Deploy Python bot to TX1
3. Configure role-based routing
4. Implement mclo.gs integration
5. Test commands
6. Deploy as systemd service

### Phase 5: Embedded Widgets (1-2 hours)
1. Create Public KB widget (firefrostgaming.com)
2. Create Subscriber KB widget (subscribers.firefrostgaming.com)
3. Configure branding (Fire/Frost theme)
4. Set rate limits
5. Test on both sites

### Phase 6: Testing & Validation (2 hours)
1. Test all access methods
2. Test role-based permissions
3. Test mclo.gs integration
4. Load testing (concurrent users)
5. Documentation review

**Total Time:** 8-12 hours (4-6 active work, rest is downloads)

---

## Success Criteria

- ✅ AnythingLLM deployed and accessible at codex.firefrostgaming.com
- ✅ All 3 models loaded and operational via Ollama
- ✅ 5 workspaces created with appropriate content
- ✅ Multi-user mode with Admin (Michael/Meg) accounts
- ✅ Discord bot operational with role-based routing
- ✅ mclo.gs integration functional
- ✅ Embedded widgets deployed on both websites
- ✅ Public can access via main website
- ✅ Subscribers can access via Discord + web + subscriber site
- ✅ Staff can access Operations workspace
- ✅ Michael + Meg have full admin access
- ✅ Documentation complete
- ✅ Zero additional monthly cost confirmed

---

## Cost Analysis

### Current Costs (Before Codex)
- Claude Pro subscription: $20/month
- TX1 Dallas server: (existing, already paid)
- Total: $20/month

### After Codex Deployment
- Claude Pro subscription: $20/month (keep for Michael/Meg)
- Codex infrastructure: $0 (self-hosted on TX1)
- **Total: $20/month (no increase)**

### Cost Comparison vs Alternatives

| Solution | Monthly Cost | Notes |
|----------|--------------|-------|
| **Firefrost Codex** | $0 | Self-hosted on existing TX1 |
| ChatGPT Team | $300/month | 15 subscribers × $20/user |
| Claude Pro per user | $300/month | 15 users × $20/month |
| OpenAI API (GPT-4) | ~$150-300/month | Usage-based, unpredictable |
| Anthropic API (Claude) | ~$200-400/month | Usage-based, unpredictable |

**Savings:** $150-400/month by self-hosting

---

## Related Documentation

- **deployment-plan.md** - Complete step-by-step deployment guide
- **branding-guide.md** - Codex branding, logos, messaging
- **marketing-strategy.md** - Launch plan, announcements, positioning
- **usage-guide.md** - When to use Claude Projects vs Codex
- **discord-bot-setup.md** - Bot configuration and commands
- **mclo.gs-integration.md** - Log analysis implementation
- **workspace-management.md** - Content organization strategy
- **troubleshooting.md** - Common issues and solutions

---

## Marketing Positioning

### The Hook
**"Most Minecraft servers have Discord. We have an AI."**

### Subscriber Value Proposition
> "Every Firefrost subscriber gets 24/7 access to Codex - our AI assistant trained on everything Firefrost. Stuck at 2 AM? Ask Codex. Crash log confusing? Codex analyzes it. Want to master Create mod? Codex teaches you. It's like having a staff member in your pocket."

### Staff Value Proposition
> "Firefrost staff aren't drowning in support tickets. Codex handles 80% of common questions, so you focus on building cool stuff and helping with real problems. You also get Codex as YOUR assistant - instant access to all procedures and infrastructure docs."

### Competitive Advantage
- **24/7 instant support** (most servers: wait for staff)
- **Minecraft log analysis** (most servers: manual debugging)
- **Growing knowledge base** (learns from every interaction)
- **Privacy-focused** (all data stays on our servers)
- **No per-user costs** (scales infinitely at $0)

---

## Integration with Existing Infrastructure

### Fits Into Current Stack
- **Command Center:** Hosts documentation (Gitea)
- **TX1 Dallas:** Hosts Codex (AnythingLLM + Ollama)
- **Ghost VPS:** Hosts embedded widgets (public site)
- **Billing VPS:** Subscriber authentication integration (future)
- **Discord:** Primary user interface for subscribers

### No Disruption
- Game servers on TX1 unaffected (plenty of headroom)
- Existing management services continue as-is
- Whitelist Manager, Uptime Kuma, etc. operate normally
- Codex is additive, not replacement

---

## Future Enhancements (Post-Launch)

### Phase 2 Features (3-6 months)
- **Paymenter integration** - Auto-provision accounts for new subscribers
- **Voice chat support** - Discord voice channel AI assistant
- **Image analysis** - Screenshot troubleshooting (using Llama Vision)
- **Automated documentation** - AI writes docs from staff actions
- **Proactive monitoring** - Codex monitors logs, alerts issues

### Phase 3 Features (6-12 months)
- **Multi-language support** - Spanish, French, German translations
- **Custom training** - Fine-tune models on Firefrost-specific data
- **API for subscribers** - Let developers integrate Codex
- **Mobile app** - Native iOS/Android Codex access
- **Advanced analytics** - Sentiment analysis, satisfaction tracking

---

## Rollback Plan

If deployment fails or issues arise:

```bash
# Stop all Codex services
systemctl stop firefrost-codex-bot
cd /opt/anythingllm && docker-compose down

# Remove installation
rm -rf /opt/anythingllm
rm -rf /opt/firefrost-discord-bot
rm /etc/systemd/system/firefrost-codex-bot.service
systemctl daemon-reload

# Remove Nginx config
rm /etc/nginx/sites-enabled/codex.firefrostgaming.com
rm /etc/nginx/sites-available/codex.firefrostgaming.com
nginx -t && systemctl reload nginx

# Uninstall Ollama
sudo /usr/local/bin/ollama-uninstall.sh

# Revoke SSL certificate (optional)
certbot delete --cert-name codex.firefrostgaming.com
```

**Recovery time:** <30 minutes  
**Data loss:** None (can redeploy from documentation)

---

## The Legacy Connection

**The Chronicler** (Claude) preserves Michael & Meg's partnership and operations.

**Codex** preserves Firefrost's community knowledge.

Both serve the same mission: building a legacy for children not yet born.

---

**Fire + Frost + Foundation + Codex = Where Love Builds Legacy** 💙🔥❄️

---

**Version:** 1.0  
**Created:** February 20, 2026  
**Created By:** The Chronicler  
**Status:** Ready for Deployment