diff --git a/README.md b/README.md index e3bad7d..c00eef7 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,14 @@ **Single source of truth for AI context across sessions** -**Last Updated**: December 20, 2025 +**Last Updated**: April 7, 2026 **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. +This repository provides persistent documentation that both Claude (architecture) and Ceàrd/GPT (implementation) can access across chat sessions without re-uploading files. **Base URL for raw files**: ``` @@ -18,78 +18,63 @@ https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/ --- -## 📁 File Structure +## AI Role Split -### **Core Documents** (Always Available) +| AI | Role | Workspace | +|----|------|-----------| +| **Claude** | Architecture, strategy, design decisions | `jester/knowledge-base` | +| **GPT (Ceàrd)** | Implementation, code, verification, session continuity | `jester/zlh-grind` | -| 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 | +**Hard rule**: GPT must not make architecture decisions. If architectural interpretation is required, stop and defer to Claude or canonical docs. -### **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_Summaries/** | Historical session notes | Context recovery | +## 📁 Core Documents + +### Current (April 2026) + +| File | Purpose | Primary User | +|------|---------|--------------| +| **ZeroLagHub_Master_Bootstrap_Apr2026.md** | Platform overview, infrastructure, architecture rules, current state, pre-launch blockers | Claude | +| **ZeroLagHub_Cross_Project_Tracker.md** | Architectural boundaries, drift prevention, ADL | Both | +| **ZeroLagHub_Drift_Prevention_Card.md** | 30-second session starter, quick checks | Both | +| **ZeroLagHub_Infrastructure_Specifications.md** | Hardware specs, capacity constraints | Both | + +### Reference / Historical + +| File | Notes | +|------|-------| +| `ZeroLagHub_Master_Bootstrap_Dec2025.md` | Superseded — kept for historical reference | +| `ZeroLagHub_GPT_Implementation_Handover_Dec2025.md` | Superseded — GPT now uses `zlh-grind` for continuity | +| `ZeroLagHub_Complete_Current_State_Dec7.md` | Historical snapshot | +| `ZeroLagHub_Complete_Current_State_Jan2026.md` | Historical snapshot | +| `ZeroLagHub_Quick_Status_Feb2026.md` | Historical snapshot | +| `Session_Summaries/` | Historical session notes | --- ## 🚀 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) +1. Read: ZeroLagHub_Master_Bootstrap_Apr2026.md (platform context) +2. Read: ZeroLagHub_Cross_Project_Tracker.md (architectural boundaries) +3. Reference: zlh-grind/INFRASTRUCTURE.md for current IPs/VMs ``` **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 +https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/ZeroLagHub_Master_Bootstrap_Apr2026.md +https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/ZeroLagHub_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 +1. https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/ZeroLagHub_Master_Bootstrap_Apr2026.md +2. https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/ZeroLagHub_Cross_Project_Tracker.md Context: [What needs architectural guidance] Decision: [What needs to be decided] @@ -97,9 +82,29 @@ Decision: [What needs to be decided] --- -## 🛡️ Critical Governance +### **For Ceàrd/GPT (Implementation Sessions)** -### **7 Locked Architectural Decisions** (Cannot change without "Revisit decision X") +**Quick Start**: +``` +1. Read: zlh-grind/SCRATCH/handover-apr-2026.md (current state) +2. Read: zlh-grind/OPEN_THREADS.md (active work) +3. Read: zlh-grind/INFRASTRUCTURE.md (IPs + VMs) +``` + +**Session Start Template**: +``` +Read knowledge base: +1. https://git.zerolaghub.com/jester/zlh-grind/raw/branch/main/SCRATCH/handover-apr-2026.md +2. https://git.zerolaghub.com/jester/zlh-grind/raw/branch/main/OPEN_THREADS.md + +Current task: [Specific implementation task] +``` + +--- + +## 🔒 Critical Governance + +### 11 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) @@ -108,178 +113,34 @@ Decision: [What needs to be decided] 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) +8. **DEC-008**: Control plane uses IP env vars, not internal.zlh DNS in hot paths +9. **DEC-009**: Redis never restored from backup — always start clean +10. **DEC-010**: Vanilla Minecraft uses Fabric loader + FabricProxy-Lite (not vanilla JAR) +11. **DEC-011**: Velocity forwarding mode = `modern` (not `none`) -**Details**: See `Cross_Project_Tracker.md` → Architecture Decision Log section +**Details**: See `ZeroLagHub_Cross_Project_Tracker.md` → Architecture Decision Log section --- -## 🟢 Current Platform Status (Quick Reference) +## 🔄 Keeping Knowledge Base Updated -**Platform Readiness**: 85% complete -**Launch Status**: Decision pending (NOW vs +3 days vs +1 week) -**Recommendation**: +3 days sprint (Option B) +### After Major Changes -**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) +**Claude updates**: +- `ZeroLagHub_Master_Bootstrap_Apr2026.md` — after architecture decisions or major state changes +- `ZeroLagHub_Cross_Project_Tracker.md` — after locking new decisions +- `Session_Summaries/` — after significant architectural sessions -**Critical Bug Identified** ⚠️ (Fix Ready): -- **DNS Record Creation**: EdgePublisher contract broken in dev container refactor -- **Impact**: Servers provision but unreachable (DNS not created) -- **Fix**: 3-line change in provisionAgent.js (documented in zlh-grind repo) -- **Status**: Identified Dec 20, ready for next GPT session to apply - -**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**: DNS fix (5 min) → Dev containers implementation -- **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 -5. **Session_Summaries/** - After each significant session - -### **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 +**GPT updates**: +- `zlh-grind/OPEN_THREADS.md` — after completing or discovering work +- `zlh-grind/SCRATCH/handover-*.md` — session handovers +- `zlh-grind/INFRASTRUCTURE.md` — if IPs/VMs change --- ## 🚨 Emergency Session Recovery -**If Session Loses Context**: +**If session loses context**: 1. Paste this README URL: ``` @@ -294,82 +155,31 @@ Date: 2025-12-08 --- -## 🏷️ Quick Reference URLs - -**Most Common Files**: +## ⚡ Quick Reference URLs ```bash -# Drift Prevention (session start) -https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Drift_Prevention_Card.md +# Claude bootstrap (session start) +https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/ZeroLagHub_Master_Bootstrap_Apr2026.md -# Ceàrd Implementation -https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/GPT_Implementation_Handover.md +# Drift prevention (both AIs) +https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/ZeroLagHub_Drift_Prevention_Card.md -# Boundaries (before code changes) -https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Cross_Project_Tracker.md +# Boundaries (before any code changes) +https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/ZeroLagHub_Cross_Project_Tracker.md -# Strategic Planning -https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Master_Bootstrap.md +# GPT current state +https://git.zerolaghub.com/jester/zlh-grind/raw/branch/main/SCRATCH/handover-apr-2026.md -# Hardware Constraints -https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Infrastructure_Specs.md +# GPT active work +https://git.zerolaghub.com/jester/zlh-grind/raw/branch/main/OPEN_THREADS.md -# Latest Session -https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/Session_Summaries/2025-12-20_DNS_Fix_Identification.md +# Infrastructure (VMs + IPs) +https://git.zerolaghub.com/jester/zlh-grind/raw/branch/main/INFRASTRUCTURE.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 + session summaries) -**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.** +**Status**: Operational ✅