# Firefrost Codex - Next Steps (Phase 2)

**Document Version:** 1.0  
**Created:** February 20, 2026  
**For:** Next Session with The Chronicler  
**Status:** Ready for execution  

---

## 📋 SESSION START CHECKLIST

**Before starting Phase 2, verify:**
- [ ] AnythingLLM accessible at http://38.68.14.26:3001
- [ ] Both Docker containers running: `docker ps | grep -E "ollama|anythingllm"`
- [ ] Can log in as mkrause612
- [ ] Test query works with qwen2.5-coder:7b
- [ ] Git repository accessible: `/home/claude/firefrost-operations-manual`

---

## 🎯 PHASE 2 OBJECTIVES

**Goal:** Transform Codex from "it works" to "it's useful"

**Deliverables:**
1. ✅ 5 workspaces configured
2. ✅ Git sync automation
3. ✅ Operations manual uploaded
4. ✅ Meg's account created
5. ✅ Security hardening (SSL + firewall)

**Timeline:** 1 session (~4-6 hours)

---

## 📝 TASK 1: CREATE WORKSPACES

**Estimated Time:** 30 minutes

### Steps:

1. **Rename "default" workspace**
   - Current: "default"
   - New name: "Operations"
   - Purpose: Staff operational documentation

2. **Create "Public KB" workspace**
   - Access: Public (future widget)
   - Content: Public-facing information
   - Model: qwen2.5-coder:7b

3. **Create "Subscriber KB" workspace**
   - Access: Subscribers only
   - Content: Gameplay guides, troubleshooting
   - Model: qwen2.5-coder:7b

4. **Create "Brainstorming" workspace**
   - Access: Admin only
   - Content: Planning docs, strategy
   - Model: llama3.3:70b (deep thinking)

5. **Create "Relationship" workspace**
   - Access: Michael + The Chronicler only
   - Content: AI partnership documentation
   - Model: qwen2.5-coder:7b

### Verification:
- [ ] 5 workspaces exist
- [ ] Each has appropriate name
- [ ] Each has correct model assigned
- [ ] Each has proper access controls (to be configured later)

---

## 📝 TASK 2: BUILD GIT SYNC SCRIPT

**Estimated Time:** 1-2 hours

### Script Requirements:

**Name:** `codex-sync.sh`  
**Location:** `/opt/anythingllm/scripts/`  
**Purpose:** Sync documents from Git to AnythingLLM workspaces

**Functionality:**
1. Pull latest from firefrost-operations-manual repo
2. Process documents for upload
3. Upload to appropriate workspaces via API
4. Log sync activity
5. Handle errors gracefully

### Workspace Mapping:

**Operations Workspace:**
- Source: `docs/core/*.md`
- Source: `docs/standards/*.md`
- Source: `docs/tasks/*/README.md`
- Exclude: `docs/relationship/*`
- Exclude: `docs/past-claudes/*`

**Public KB Workspace:**
- Source: TBD (future - public docs not yet written)
- Note: May need to create `docs/public/` directory

**Subscriber KB Workspace:**
- Source: TBD (future - subscriber guides not yet written)
- Note: May need to create `docs/subscribers/` directory

**Brainstorming Workspace:**
- Source: `docs/tasks/*/deployment-plan.md`
- Source: Future planning docs

**Relationship Workspace:**
- Source: `docs/relationship/*`
- Source: `docs/past-claudes/*/memorial.md`
- Source: `SESSION-HANDOFF-PROTOCOL.md`

### API Integration:

**AnythingLLM API endpoints to use:**
- `POST /api/v1/workspace/:slug/upload` - Upload documents
- `GET /api/v1/workspace/:slug/documents` - List documents
- `DELETE /api/v1/document/:id` - Remove documents

**Authentication:**
- Need to generate API key from AnythingLLM admin panel
- Store in `/opt/anythingllm/scripts/.env`

### Script Template:

```bash
#!/bin/bash
# codex-sync.sh - Sync Git repo to AnythingLLM workspaces

set -e

# Configuration
REPO_PATH="/home/claude/firefrost-operations-manual"
SCRIPT_DIR="/opt/anythingllm/scripts"
LOG_FILE="$SCRIPT_DIR/sync.log"
API_URL="http://localhost:3001/api/v1"
API_KEY="$(cat $SCRIPT_DIR/.env | grep API_KEY | cut -d'=' -f2)"

# Functions
log() {
    echo "[$(date +'%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
}

sync_workspace() {
    local workspace_slug="$1"
    local source_path="$2"
    local file_pattern="$3"
    
    log "Syncing $workspace_slug from $source_path"
    
    # Implementation here
}

# Main execution
log "=== Starting Codex sync ==="

# Pull latest from Git
cd "$REPO_PATH"
git pull origin main

# Sync each workspace
sync_workspace "operations" "docs/core" "*.md"
sync_workspace "operations" "docs/standards" "*.md"
sync_workspace "relationship" "docs/relationship" "*.md"

log "=== Sync complete ==="
```

### Automation:

**Cron job (optional):**
```cron
# Run sync daily at 3 AM
0 3 * * * /opt/anythingllm/scripts/codex-sync.sh
```

**Manual trigger:**
```bash
# Run sync on demand
/opt/anythingllm/scripts/codex-sync.sh
```

### Verification:
- [ ] Script runs without errors
- [ ] Documents appear in correct workspaces
- [ ] Can search and retrieve documents
- [ ] Sync is idempotent (can run multiple times safely)
- [ ] Logs are readable and helpful

---

## 📝 TASK 3: INITIAL DOCUMENT UPLOAD

**Estimated Time:** 30 minutes

### Manual Upload (for testing):

**Documents to upload first:**
1. `docs/core/infrastructure-manifest.md` → Operations
2. `docs/core/tasks.md` → Operations
3. `SESSION-HANDOFF-PROTOCOL.md` → Relationship
4. `docs/relationship/THE-ESSENCE-PATCH-V3.0.md` → Relationship

### Test Queries:

**After upload, test these questions:**

**Operations workspace:**
- "What servers does Firefrost have?"
- "What is TX1's IP address?"
- "How many game servers are deployed?"

**Relationship workspace:**
- "What is The Essence Patch?"
- "How does The Chronicler system work?"
- "What is the handoff protocol?"

### Expected Results:
- Codex answers accurately based on uploaded docs
- Citations reference correct documents
- No hallucinations about Firefrost infrastructure

### Verification:
- [ ] 4+ documents uploaded successfully
- [ ] Documents searchable via workspace chat
- [ ] Test queries return accurate answers
- [ ] Citations work correctly

---

## 📝 TASK 4: CREATE MEG'S ACCOUNT

**Estimated Time:** 15 minutes

### Steps:

1. **Access AnythingLLM admin panel**
   - Settings → Users

2. **Create new user**
   - Username: `gingerfury`
   - Password: (secure, share with Meg)
   - Role: **Admin**
   - Email: (optional)

3. **Grant workspace access**
   - Operations: ✅
   - Public KB: ✅
   - Subscriber KB: ✅
   - Brainstorming: ✅
   - Relationship: ✅ (all workspaces)

4. **Test account**
   - Log out of mkrause612
   - Log in as gingerfury
   - Verify access to all workspaces
   - Test chat functionality

### Documentation:
- [ ] Create `CODEX-USER-GUIDE.md` with login instructions
- [ ] Share credentials with Meg securely
- [ ] Document role permissions

### Verification:
- [ ] gingerfury account exists
- [ ] Has admin privileges
- [ ] Can access all workspaces
- [ ] Can chat and get responses

---

## 📝 TASK 5: SECURITY HARDENING

**Estimated Time:** 2-3 hours

### Subtask 5.1: Install Nginx Reverse Proxy

**Why:** SSL/TLS encryption for secure access

**Steps:**

1. **Install Nginx**
```bash
apt update
apt install -y nginx certbot python3-certbot-nginx
```

2. **Create Nginx config**
```bash
cat > /etc/nginx/sites-available/codex << 'EOF'
server {
    listen 80;
    server_name codex.firefrostgaming.com;
    
    location / {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        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;
    }
}
EOF
```

3. **Enable site**
```bash
ln -s /etc/nginx/sites-available/codex /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx
```

4. **Get SSL certificate**
```bash
certbot --nginx -d codex.firefrostgaming.com
```

**Prerequisites:**
- DNS A record: `codex.firefrostgaming.com` → TX1 IP
- Ports 80 and 443 open in firewall

### Subtask 5.2: Configure Firewall

**Steps:**

1. **Install UFW**
```bash
apt install -y ufw
```

2. **Configure rules**
```bash
# Allow SSH
ufw allow 22/tcp

# Allow HTTP/HTTPS
ufw allow 80/tcp
ufw allow 443/tcp

# Block direct access to AnythingLLM
ufw deny 3001/tcp

# Enable firewall
ufw enable
```

3. **Verify rules**
```bash
ufw status verbose
```

### Subtask 5.3: Automated Backups

**Steps:**

1. **Create backup script**
```bash
cat > /root/scripts/backup-codex.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/root/backups/codex"
DATE=$(date +%Y%m%d-%H%M%S)

mkdir -p "$BACKUP_DIR"

# Backup database and documents
tar -czf "$BACKUP_DIR/codex-$DATE.tar.gz" \
    /opt/anythingllm/storage

# Keep only last 7 days
find "$BACKUP_DIR" -name "codex-*.tar.gz" -mtime +7 -delete

echo "Backup complete: codex-$DATE.tar.gz"
EOF

chmod +x /root/scripts/backup-codex.sh
```

2. **Add to cron**
```bash
crontab -e
# Add line:
0 3 * * * /root/scripts/backup-codex.sh >> /var/log/codex-backup.log 2>&1
```

3. **Test backup**
```bash
/root/scripts/backup-codex.sh
ls -lh /root/backups/codex/
```

### Verification:
- [ ] Nginx installed and running
- [ ] SSL certificate obtained
- [ ] HTTPS access working: https://codex.firefrostgaming.com
- [ ] Firewall configured correctly
- [ ] Backup script tested and working
- [ ] Cron job scheduled

---

## 📝 OPTIONAL TASKS (if time permits)

### Task 6: Uptime Kuma Integration

**Add monitoring for Codex:**
1. Create new monitor in Uptime Kuma
2. Monitor type: HTTP(s)
3. URL: https://codex.firefrostgaming.com
4. Check interval: 5 minutes
5. Alert on failures

### Task 7: Documentation Portal Update

**Add Codex to public docs:**
1. Create page on wiki.firefrostgaming.com
2. Title: "Firefrost Codex - AI Assistant"
3. Content: What it is, how to access, capabilities
4. Screenshots of interface

### Task 8: Initial Testing Protocol

**Create test suite:**
1. 10 sample questions per workspace
2. Expected answers documented
3. Run tests after each change
4. Track accuracy over time

---

## 🔍 VERIFICATION CHECKLIST

**Before ending Phase 2 session:**

**Functionality:**
- [ ] 5 workspaces created and named
- [ ] Documents uploaded to at least 2 workspaces
- [ ] Git sync script created (if not automated, at least manual process documented)
- [ ] Can query documents successfully
- [ ] Meg's account created and tested

**Security:**
- [ ] SSL certificate installed (or documented for future)
- [ ] Firewall configured (or documented for future)
- [ ] Backup script created and tested

**Documentation:**
- [ ] User guide created
- [ ] Sync process documented
- [ ] Security procedures documented
- [ ] Next steps identified

**Performance:**
- [ ] Response times still acceptable (<15 seconds)
- [ ] No memory leaks or performance degradation
- [ ] Services auto-restart on failure

---

## 📊 SUCCESS METRICS

**Phase 2 complete when:**
- ✅ All 5 workspaces operational
- ✅ At least 20 documents uploaded
- ✅ Meg can access and use Codex
- ✅ Basic security in place (at minimum: firewall)
- ✅ Backup system functional
- ✅ Documentation updated

---

## 🚨 KNOWN RISKS & MITIGATION

### Risk 1: Document Upload Issues
**Symptoms:** Documents fail to upload or aren't searchable  
**Causes:** File format, size limits, embedding failures  
**Mitigation:** Test with small files first, check logs  

### Risk 2: Performance Degradation
**Symptoms:** Slow responses after document upload  
**Causes:** Vector database too large, insufficient RAM  
**Mitigation:** Monitor resource usage, use smaller batches  

### Risk 3: Sync Script Failures
**Symptoms:** Git sync doesn't update documents  
**Causes:** API auth issues, file permissions, network  
**Mitigation:** Comprehensive error handling and logging  

### Risk 4: SSL Certificate Issues
**Symptoms:** Can't obtain or renew certificate  
**Causes:** DNS not propagated, ports blocked  
**Mitigation:** Verify DNS and firewall before certbot  

---

## 📞 IF SOMETHING BREAKS

### AnythingLLM Not Responding
```bash
# Check status
docker ps | grep anythingllm

# Check logs
docker logs anythingllm --tail 50

# Restart
docker restart anythingllm

# Nuclear option
docker stop anythingllm && docker rm anythingllm
# Then redeploy using DEPLOYMENT-COMPLETE.md commands
```

### Ollama Not Responding
```bash
# Check status
docker ps | grep ollama

# Check logs  
docker logs ollama --tail 50

# Restart
docker restart ollama

# Test API
curl http://localhost:11434/api/tags
```

### Documents Not Searchable
```bash
# Check vector database
docker exec anythingllm ls -lah /app/server/storage/lancedb

# Check embeddings
docker logs anythingllm | grep -i embed

# Re-upload documents if needed
```

### Out of Disk Space
```bash
# Check usage
df -h

# Find large files
du -sh /opt/anythingllm/* | sort -h

# Clean up if needed
docker system prune -a  # CAREFUL: removes unused images
```

---

## 🎯 PHASE 3 PREVIEW

**After Phase 2 is complete, Phase 3 will focus on:**

1. **Discord Bot Development**
   - Create bot application
   - Implement AnythingLLM integration
   - Add role-based routing
   - Deploy to production

2. **Embedded Widgets**
   - Create public widget for website
   - Create subscriber widget for portal
   - Style to match branding
   - Test responsiveness

3. **Advanced Features**
   - mclo.gs API integration
   - Automated log analysis
   - Custom commands
   - Usage analytics

4. **Staff Training**
   - Create training materials
   - Staff onboarding session
   - Establish support workflows
   - Gather feedback

---

## 📚 REFERENCE LINKS

**Internal:**
- Phase 1 Documentation: `DEPLOYMENT-COMPLETE.md`
- Architecture: `README.md`
- Infrastructure: `docs/core/infrastructure-manifest.md`

**External:**
- AnythingLLM API: https://docs.useanything.com/api
- Ollama API: https://github.com/ollama/ollama/blob/main/docs/api.md
- Nginx + Let's Encrypt: https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/
- UFW Guide: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-firewall-with-ufw-on-ubuntu

---

## ✅ SESSION END CHECKLIST

**Before completing Phase 2 session:**
- [ ] All Phase 2 tasks completed or documented
- [ ] Verification checklist 100% complete
- [ ] Success metrics achieved
- [ ] Any issues documented in session notes
- [ ] Git commits made for all changes
- [ ] Session handoff document created
- [ ] Next session checklist prepared

---

**Document Status:** Ready for Execution  
**Estimated Session Time:** 4-6 hours  
**Dependencies:** Phase 1 complete (✅)  
**Blocking Issues:** None  

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

---

**Document Version:** 1.0  
**Last Updated:** February 20, 2026  
**Author:** The Chronicler  
**For:** Next Session - Phase 2 Execution