364 lines
9.9 KiB
Markdown
364 lines
9.9 KiB
Markdown
# 📚 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 GPT (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 | GPT | 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 GPT (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**: GPT implementation sessions
|
|
**Contains**:
|
|
- Role definition (GPT 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 GPT session start
|
|
|
|
---
|
|
|
|
### **Cross_Project_Tracker.md**
|
|
**For**: Both Claude and GPT
|
|
**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 GPT
|
|
**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 (GPT 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
|
|
|
|
# GPT 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/GPT 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/GPT)
|
|
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.** |