# 📚 ZeroLagHub Knowledge Base

**Single source of truth for AI context across sessions**

**Last Updated**: December 13, 2025  
**Repository**: https://git.zerolaghub.com/jester/knowledge-base

---

## 🎯 Purpose

This repository provides persistent documentation that both Claude (architecture) and Ceàrd (implementation) can access across chat sessions without re-uploading files.

**Base URL for raw files**:
```
https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/
```

---

## 📁 File Structure

### **Core Documents** (Always Available)

| File | Purpose | Primary User | Size |
|------|---------|--------------|------|
| **GPT_Implementation_Handover.md** | Implementation tasks, sprint plan, boundaries | Ceàrd | 18 KB |
| **Cross_Project_Tracker.md** | Architectural boundaries, drift prevention, ADL | Both | 23 KB |
| **Drift_Prevention_Card.md** | 30-second session starter, quick checks | Both | 3 KB |
| **Master_Bootstrap.md** | Strategic overview, business model, infrastructure | Claude | 21 KB |
| **Infrastructure_Specs.md** | GTHost hardware, capacity, constraints | Both | 16 KB |

### **Reference Documents** (As Needed)

| File | Purpose | When to Use |
|------|---------|-------------|
| **Complete_Current_State.md** | Platform status, Kanban, troubleshooting | Implementation sessions |
| **Documentation_Guide.md** | How all docs relate | Onboarding new AI |
| **ADL_Contribution_Summary.md** | Architecture Decision Log explanation | Understanding governance |

---

## 🚀 Session Start Instructions

### **For Ceàrd (Implementation Sessions)**

**Quick Start**:
```
1. Read: Drift_Prevention_Card.md (30 seconds)
2. Read: GPT_Implementation_Handover.md (10 minutes)
3. Reference: Cross_Project_Tracker.md (before crossing boundaries)
```

**URLs to Fetch**:
```
https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Drift_Prevention_Card.md
https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/GPT_Implementation_Handover.md
```

**Session Start Template**:
```
Read knowledge base:
1. https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Drift_Prevention_Card.md
2. https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/GPT_Implementation_Handover.md

Current sprint: [Day X of 3-day sprint]
Task: [Specific implementation task]
```

---

### **For Claude (Strategic/Architecture Sessions)**

**Quick Start**:
```
1. Read: Master_Bootstrap.md (strategic context)
2. Read: Cross_Project_Tracker.md (architectural boundaries)
3. Reference: Infrastructure_Specs.md (capacity constraints)
```

**URLs to Fetch**:
```
https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Master_Bootstrap.md
https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Cross_Project_Tracker.md
```

**Session Start Template**:
```
Read knowledge base:
1. https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Master_Bootstrap.md
2. https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Cross_Project_Tracker.md

Context: [What needs architectural guidance]
Decision: [What needs to be decided]
```

---

## 🛡️ Critical Governance

### **7 Locked Architectural Decisions** (Cannot change without "Revisit decision X")

1. **DEC-001**: Templates + Agent hybrid (not templates-only or agent-only)
2. **DEC-002**: API orchestrates, Agent executes (not reversed)
3. **DEC-003**: API owns DNS (Agent never creates DNS)
4. **DEC-004**: Traefik + Velocity only (no HAProxy)
5. **DEC-005**: MariaDB is source of truth (no flat files)
6. **DEC-006**: Frontend → API only (no direct agent calls)
7. **DEC-007**: Drift prevention mandatory (always enforced)

**Details**: See `Cross_Project_Tracker.md` → Architecture Decision Log section

---

## 🛠️ Current Platform Status (Quick Reference)

**Platform Readiness**: 85% complete  
**Launch Status**: Decision pending (NOW vs +3 days vs +1 week)  
**Recommendation**: +3 days sprint (Option B)

**What's Working** ✅:
- All 6 Minecraft variants (Vanilla, Paper, Purpur, Fabric, Forge, NeoForge)
- DNS automation (Cloudflare + Technitium)
- Velocity proxy integration
- Go agent with self-repair
- Enterprise backup (PBS + Backblaze B2)

**What's Missing** ❌:
- WebSocket console streaming (4-6 hours)
- Crash loop protection (2 hours)
- Disk space monitoring (1 hour)

**Next Sprint** (3 Days):
- Day 1: Dev containers
- Day 2: EdgeState + DNS reliability
- Day 3: Reconciliation + hardening

---

## 🎯 File Descriptions

### **GPT_Implementation_Handover.md**
**For**: Ceàrd implementation sessions  
**Contains**:
- Role definition (Ceàrd implements, Claude architects)
- 3-day sprint with concrete tasks
- Platform status (85% complete)
- Boundaries (API vs Agent vs Frontend)
- Known bugs (3 Go agent issues)
- Testing requirements
- File locations with specific changes needed

**When to Read**: Every Ceàrd session start

---

### **Cross_Project_Tracker.md**
**For**: Both Claude and Ceàrd  
**Contains**:
- Ownership matrix (who owns what)
- Canonical contracts (API ↔ Agent, Frontend ↔ API)
- Drift detection rules (5 violation patterns)
- Architecture Decision Log (7 locked decisions)
- High-risk integration zones
- Enforcement policies

**When to Read**: Before any architectural change or boundary crossing

---

### **Drift_Prevention_Card.md**
**For**: Both Claude and Ceàrd  
**Contains**:
- 30-second boundary check
- 7 locked decisions (quick reference)
- Violation triggers
- Golden rules (API orchestrates, Agent executes, Frontend displays)

**When to Read**: Every session start (30 seconds)

---

### **Master_Bootstrap.md**
**For**: Claude strategic sessions  
**Contains**:
- Platform overview (85% ready)
- Infrastructure (11 VMs)
- Network architecture (dual-router)
- Launch decision framework (3 options)
- Business model (9.75x revenue multiplier)
- Security vulnerabilities
- Game support matrix

**When to Read**: Strategic planning, launch decisions, business model discussions

---

### **Infrastructure_Specs.md**
**For**: Both (capacity planning)  
**Contains**:
- GTHost hardware (Xeon Silver 4116, 192GB RAM, 3.84TB SSD)
- Capacity constraints (30-50 servers, 128 GB available)
- Network bottleneck (300 Mbit/s)
- Cost analysis
- Optimization opportunities

**When to Read**: Implementation planning, resource allocation, scaling decisions

---

## 📝 Keeping Knowledge Base Updated

### **After Major Changes**

**Update these files**:
1. **Current_Sprint.md** - After completing sprint tasks
2. **Platform_Status** section in README.md - After status changes
3. **Known_Bugs** section - After fixing or discovering bugs
4. **ADL** in Cross_Project_Tracker.md - After locking new decisions

### **Version Control**

**Commit Messages Should Include**:
- What changed (file + section)
- Why it changed (decision, bug fix, completion)
- Date of change

**Example**:
```
Update GPT_Implementation_Handover.md - Day 1 sprint complete
- Marked dev containers as DONE
- Updated Kanban board
- Added Day 2 tasks
Date: 2025-12-08
```

---

## 💡 Best Practices

### **For Session Continuity**

**At Session Start**:
1. Provide 2-3 file URLs (based on session type)
2. AI reads files (establishes context)
3. Proceed with work (no re-upload needed)

**During Session**:
- Reference files by name (e.g., "Check Cross_Project_Tracker.md")
- AI can re-fetch if needed
- No need to re-paste content

**At Session End**:
- Update relevant files in Gitea
- Commit with clear message
- Next session picks up where you left off

---

### **For New AI Assistants**

**Onboarding**:
1. Read this README.md (understand structure)
2. Read role-specific files (Ceàrd vs Claude)
3. Activate drift prevention (check boundaries)
4. Begin work within constraints

**No Re-Upload Needed**: Everything persists in Gitea

---

## 🚨 Emergency Session Recovery

**If Session Loses Context**:

1. Paste this README URL:
   ```
   https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/README.md
   ```

2. AI reads README, identifies needed files

3. AI fetches role-specific documents

4. Context restored in <2 minutes

---

## 🔎 Quick Reference URLs

**Most Common Files**:

```bash
# Drift Prevention (session start)
https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Drift_Prevention_Card.md

# Ceàrd Implementation
https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/GPT_Implementation_Handover.md

# Boundaries (before code changes)
https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Cross_Project_Tracker.md

# Strategic Planning
https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Master_Bootstrap.md

# Hardware Constraints
https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Infrastructure_Specs.md
```

---

## ✅ Verification

**Test Knowledge Base Access**:

```bash
# Fetch this README
curl https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/README.md

# Should return this file content
# If successful, knowledge base is accessible to AIs
```

---

## 🎯 Success Metrics

**Knowledge Base is Working If**:
- ✅ Claude/Ceàrd can fetch files without re-upload
- ✅ Session start takes <2 minutes (load context)
- ✅ No duplicate documentation (single source of truth)
- ✅ Architectural boundaries enforced (drift prevention active)
- ✅ Both AIs have same context (no divergence)

---

## 📊 Repository Stats

**Total Size**: ~150 KB (5 core files + 3 reference files)  
**Load Time**: ~2-3 seconds (all files)  
**Maintenance**: Update after sprint completion or major decisions  
**Access**: Public read (no authentication needed)

---

**Status**: Knowledge base operational, ready for AI consumption ✅

---

## 🚀 Next Steps

1. Upload core files to this repository
2. Test URLs work (fetch in browser)
3. Test AI access (paste URL in Claude/Ceàrd)
4. Begin using for session continuity

---

**Repository Owner**: jester  
**Platform**: ZeroLagHub  
**Purpose**: Single source of truth for AI context  
**Status**: Ready for population

🎯 **Populate knowledge base with 5 core files, then both AIs can access across all sessions.**