From 882c0c7169f498c762d79a124d1bf95017f5cefa Mon Sep 17 00:00:00 2001 From: jester Date: Sat, 13 Dec 2025 16:36:57 +0000 Subject: [PATCH] Update README.md --- README.md | 365 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 363 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 58c97fc..2f51500 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,364 @@ -# knowledge-base +# 📚 ZeroLagHub Knowledge Base -Single source of truth for AI context \ No newline at end of file +**Single source of truth for AI context across sessions** + +**Last Updated**: December 7, 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.** \ No newline at end of file