knowledge-base/README.md

# 📚 ZeroLagHub Knowledge Base

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

**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/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/
```

---

## AI Role Split

| AI | Role | Workspace |
|----|------|-----------|
| **Claude** | Architecture, strategy, design decisions | `jester/knowledge-base` |
| **GPT (Ceàrd)** | Implementation, code, verification, session continuity | `jester/zlh-grind` |

**Hard rule**: GPT must not make architecture decisions. If architectural interpretation is required, stop and defer to Claude or canonical docs.

---

## 📁 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 Claude (Strategic/Architecture Sessions)**

**Quick Start**:
```
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/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/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]
```

---

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

**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)
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)
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 `ZeroLagHub_Cross_Project_Tracker.md` → Architecture Decision Log section

---

## 🔄 Keeping Knowledge Base Updated

### After Major Changes

**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

**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**:

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

```bash
# Claude bootstrap (session start)
https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/ZeroLagHub_Master_Bootstrap_Apr2026.md

# Drift prevention (both AIs)
https://git.zerolaghub.com/jester/knowledge-base/raw/branch/main/ZeroLagHub_Drift_Prevention_Card.md

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

# GPT current state
https://git.zerolaghub.com/jester/zlh-grind/raw/branch/main/SCRATCH/handover-apr-2026.md

# GPT active work
https://git.zerolaghub.com/jester/zlh-grind/raw/branch/main/OPEN_THREADS.md

# Infrastructure (VMs + IPs)
https://git.zerolaghub.com/jester/zlh-grind/raw/branch/main/INFRASTRUCTURE.md
```

---

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