jester/knowledge-base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README - point to Apr 2026 Master Bootstrap, refresh session start URLs

Browse Source
This commit is contained in:
jester 2026-04-07 20:57:13 +00:00
parent 4fc64527f4
commit 3bfcd1d9c7
1 changed files with 89 additions and 279 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

368
README.md
View File

@ -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 ✅