377 lines
11 KiB
Markdown
377 lines
11 KiB
Markdown
# 📚 ZeroLagHub Documentation Navigation Guide
|
|
|
|
**Last Updated**: December 13, 2025
|
|
**Purpose**: Guide to all project documentation and how they relate
|
|
|
|
---
|
|
|
|
## 🗺️ Document Hierarchy
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 📋 MASTER BOOTSTRAP (START HERE) │
|
|
│ ZeroLagHub_Master_Bootstrap_Dec2025.md │
|
|
│ ├─ Strategic vision & business model │
|
|
│ ├─ Infrastructure overview (11 VMs) │
|
|
│ ├─ Launch decision framework │
|
|
│ └─ High-level architecture │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
┌───────────────┼───────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌────────────┐ ┌────────────┐ ┌────────────┐
|
|
│ TACTICAL │ │ COMPLETE │ │ EVOLUTION │
|
|
│ HANDOVER │ │ STATE │ │ ANALYSIS │
|
|
└────────────┘ └────────────┘ └────────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
Engineering Strategic + Nov → Dec
|
|
Implementation Tactical Comparison
|
|
Details Integration
|
|
```
|
|
|
|
---
|
|
|
|
## 📖 Document Purposes
|
|
|
|
### 🎯 **1. Master Bootstrap** (ENTRY POINT)
|
|
|
|
**File**: `ZeroLagHub_Master_Bootstrap_Dec2025.md`
|
|
|
|
**Use When**:
|
|
- Starting a new session
|
|
- Need strategic overview
|
|
- Making launch decisions
|
|
- Understanding business model
|
|
|
|
**Contains**:
|
|
- Platform overview (85% ready)
|
|
- Infrastructure topology (11 VMs)
|
|
- Network architecture (dual-router)
|
|
- Launch decision framework (3 options)
|
|
- Business model (9.75x multiplier)
|
|
- Security vulnerabilities
|
|
- Success metrics
|
|
- Glossary of terms
|
|
|
|
**Audience**:
|
|
- New AI assistants (start here)
|
|
- Strategic decision-making
|
|
- Executive overview
|
|
|
|
**Update Frequency**: After major milestones or architectural changes
|
|
|
|
---
|
|
|
|
### 🛠️ **2. GPT Implementation Handover** (IMPLEMENTATION)
|
|
|
|
**File**: `ZeroLagHub_GPT_Implementation_Handover_Dec2025.md`
|
|
|
|
**Use When**:
|
|
- Implementing features
|
|
- Debugging provisioning
|
|
- Understanding agent architecture
|
|
- Working on tactical tasks
|
|
|
|
**Contains**:
|
|
- Engineering Kanban board (DONE/IN PROGRESS/TODO)
|
|
- 3-day sprint plan (specific tasks)
|
|
- System lifecycle diagram (ASCII)
|
|
- Troubleshooting guide per variant
|
|
- Provisioning sequence specification
|
|
- Verification system details
|
|
- Dev container roadmap
|
|
- Ceàrd's role definition
|
|
|
|
**Audience**:
|
|
- Ceàrd (implementation AI)
|
|
- Developers working on code
|
|
- Debugging specific issues
|
|
|
|
**Update Frequency**: Daily during active development
|
|
|
|
---
|
|
|
|
### 🎯 **3. Complete Current State** (INTEGRATION)
|
|
|
|
**File**: `ZeroLagHub_Complete_Current_State_Dec7.md`
|
|
|
|
**Use When**:
|
|
- Need both strategic AND tactical view
|
|
- Planning next sprint
|
|
- Comprehensive status review
|
|
- Integrating architecture with implementation
|
|
|
|
**Contains**:
|
|
- Two-perspective view (strategic + tactical)
|
|
- Engineering kanban (from handover)
|
|
- 3-day sprint plan (detailed)
|
|
- Complete system lifecycle (with ASCII diagram)
|
|
- MC variant status matrix
|
|
- Troubleshooting guide
|
|
- Dev container roadmap (detailed)
|
|
- Launch readiness matrix
|
|
- Launch decision framework
|
|
|
|
**Audience**:
|
|
- Management/coordination role
|
|
- Both AIs (Claude + Ceàrd)
|
|
- Comprehensive planning
|
|
|
|
**Update Frequency**: End of day during active sprints
|
|
|
|
---
|
|
|
|
### 🛡️ **4. Cross-Project Tracker** (GOVERNANCE)
|
|
|
|
**File**: `ZeroLagHub_Cross_Project_Tracker.md`
|
|
|
|
**Use When**:
|
|
- Before crossing architectural boundaries
|
|
- Understanding ownership matrix
|
|
- Checking for drift violations
|
|
- Reviewing Architecture Decision Log
|
|
|
|
**Contains**:
|
|
- Ownership matrix (API vs Agent vs Frontend)
|
|
- Canonical contracts (API ↔ Agent, Frontend ↔ API)
|
|
- Drift detection rules (5 violation patterns)
|
|
- Architecture Decision Log (7 locked decisions)
|
|
- High-risk integration zones
|
|
- Enforcement policies
|
|
|
|
**Audience**:
|
|
- Both Claude and Ceàrd
|
|
- Before any architectural changes
|
|
- Drift prevention
|
|
|
|
**Update Frequency**: After locking new architectural decisions
|
|
|
|
---
|
|
|
|
### 📊 **5. Infrastructure Specifications** (CONSTRAINTS)
|
|
|
|
**File**: `ZeroLagHub_Infrastructure_Specifications.md`
|
|
|
|
**Use When**:
|
|
- Planning resource allocation
|
|
- Understanding hardware limits
|
|
- Capacity planning
|
|
- Cost analysis
|
|
|
|
**Contains**:
|
|
- GTHost hardware specs
|
|
- Capacity constraints (30-50 servers)
|
|
- Network bottleneck (300 Mbit/s)
|
|
- Cost analysis
|
|
- Optimization opportunities
|
|
|
|
**Audience**:
|
|
- Both AIs for capacity planning
|
|
- Resource allocation decisions
|
|
- Scaling considerations
|
|
|
|
**Update Frequency**: After infrastructure changes
|
|
|
|
---
|
|
|
|
### ⚡ **6. Drift Prevention Card** (SESSION START)
|
|
|
|
**File**: `ZeroLagHub_Drift_Prevention_Card.md`
|
|
|
|
**Use When**:
|
|
- Every session start (30 seconds)
|
|
- Before any code changes
|
|
- Quick boundary check
|
|
|
|
**Contains**:
|
|
- 30-second boundary check
|
|
- 7 locked decisions (quick reference)
|
|
- Violation triggers
|
|
- Golden rules
|
|
|
|
**Audience**:
|
|
- Both Claude and Ceàrd
|
|
- Mandatory session start
|
|
|
|
**Update Frequency**: When new violations are discovered
|
|
|
|
---
|
|
|
|
## 🎯 Usage Patterns
|
|
|
|
### **Starting Fresh Session (Claude - Architecture)**
|
|
|
|
1. Read: **Master Bootstrap** (get strategic context)
|
|
2. Read: **Cross-Project Tracker** (architectural boundaries)
|
|
3. Check: **Complete Current State** (current status)
|
|
4. Reference: **Infrastructure Specs** (as needed)
|
|
|
|
### **Starting Fresh Session (Ceàrd - Implementation)**
|
|
|
|
1. Read: **Drift Prevention Card** (30 seconds)
|
|
2. Read: **GPT Implementation Handover** (implementation tasks)
|
|
3. Reference: **Cross-Project Tracker** (before crossing boundaries)
|
|
4. Check: **Complete Current State** (sprint status)
|
|
|
|
### **Planning Next Sprint**
|
|
|
|
1. Review: **Complete Current State** (current status)
|
|
2. Check: **Engineering Kanban** (what's in progress)
|
|
3. Reference: **Launch Decision Framework** (timing)
|
|
4. Plan: Next 3-day sprint based on priorities
|
|
|
|
### **Making Strategic Decisions**
|
|
|
|
1. Review: **Master Bootstrap** (business model, competitive position)
|
|
2. Check: **Launch Readiness Matrix** (current %)
|
|
3. Consult: **Cross-Project Tracker** (architectural constraints)
|
|
4. Decide: Launch timing, feature prioritization
|
|
|
|
### **Implementing Features**
|
|
|
|
1. Check: **Drift Prevention Card** (boundary check)
|
|
2. Read: **GPT Implementation Handover** (specific tasks)
|
|
3. Reference: **Cross-Project Tracker** (before crossing boundaries)
|
|
4. Update: **Kanban Board** (move tasks)
|
|
|
|
### **Debugging Issues**
|
|
|
|
1. Check: **Complete Current State** → Troubleshooting Guide
|
|
2. Reference: **System Lifecycle** (understand flow)
|
|
3. Review: **Verification System Spec** (self-repair logic)
|
|
4. Consult: **Cross-Project Tracker** (ownership boundaries)
|
|
|
|
---
|
|
|
|
## 📊 Document Status Matrix
|
|
|
|
| Document | Completeness | Accuracy | Update Needed | Priority |
|
|
|----------|--------------|----------|---------------|----------|
|
|
| **Master Bootstrap** | ✅ 100% | ✅ Current | ✅ Complete | 🟢 High |
|
|
| **GPT Implementation Handover** | ✅ 100% | ✅ Current | ✅ Complete | 🟢 High |
|
|
| **Complete Current State** | ✅ 100% | ✅ Current | ✅ Complete | 🟢 High |
|
|
| **Cross-Project Tracker** | ✅ 100% | ✅ Current | ✅ Complete | 🟢 High |
|
|
| **Infrastructure Specs** | ✅ 100% | ✅ Current | ✅ Complete | 🟢 High |
|
|
| **Drift Prevention Card** | ✅ 100% | ✅ Current | ✅ Complete | 🟢 High |
|
|
|
|
---
|
|
|
|
## 🎯 Recommended Reading Order
|
|
|
|
### **For New Claude Session** (Architecture):
|
|
1. Master Bootstrap (strategic context)
|
|
2. Cross-Project Tracker (boundaries)
|
|
3. Complete Current State (current status)
|
|
|
|
### **For New Ceàrd Session** (Implementation):
|
|
1. Drift Prevention Card (30 second check)
|
|
2. GPT Implementation Handover (implementation tasks)
|
|
3. Complete Current State (sprint status)
|
|
|
|
### **For Launch Decision**:
|
|
1. Master Bootstrap → Launch Decision Framework
|
|
2. Complete Current State → Launch Readiness Matrix
|
|
3. Cross-Project Tracker → Architectural constraints
|
|
|
|
### **For Feature Implementation**:
|
|
1. Drift Prevention Card → Boundary check
|
|
2. GPT Implementation Handover → Specific tasks
|
|
3. Complete Current State → Sprint Plan
|
|
|
|
---
|
|
|
|
## 📋 Quick Reference
|
|
|
|
### **Launch Status**: 85% ready
|
|
### **Next Sprint**: 3 days (Dev containers → EdgeState → Reconcile)
|
|
### **Launch Options**: NOW / +3 days / +1 week
|
|
### **Recommendation**: +3 days (Option B)
|
|
|
|
### **Working Components** ✅:
|
|
- All 6 MC variants
|
|
- DNS automation
|
|
- Velocity routing
|
|
- Self-repair system
|
|
|
|
### **Missing Components** ❌:
|
|
- WebSocket console
|
|
- Crash protection
|
|
- Disk monitoring
|
|
- Dev containers (in progress)
|
|
|
|
### **Known Bugs** (Non-Blocking):
|
|
- 3 Go agent issues (cleanup)
|
|
- EdgeState schema (not migrated)
|
|
- DNS deletion (needs record IDs)
|
|
|
|
---
|
|
|
|
## 🎯 Document Maintenance
|
|
|
|
### **Master Bootstrap Updates**:
|
|
- After major milestones
|
|
- After architectural changes
|
|
- After launch decision
|
|
- Monthly during operations
|
|
|
|
### **Complete Current State Updates**:
|
|
- End of each sprint day
|
|
- After significant progress
|
|
- Before major decisions
|
|
|
|
### **GPT Implementation Handover Updates**:
|
|
- Daily during active development
|
|
- After completing sprint tasks
|
|
- When priorities change
|
|
|
|
### **Cross-Project Tracker Updates**:
|
|
- After locking new architectural decisions
|
|
- When adding new boundaries
|
|
- After discovering drift violations
|
|
|
|
---
|
|
|
|
## 📞 Session Continuity
|
|
|
|
### **Quick Resume Prompt (Claude)**:
|
|
|
|
> Read ZeroLagHub Master Bootstrap Dec 2025, then Cross-Project Tracker.
|
|
>
|
|
> Platform 85% ready, all MC variants working.
|
|
>
|
|
> Current sprint: 3 days (dev containers → EdgeState → reconcile)
|
|
>
|
|
> Decision: Launch now vs +3 days?
|
|
|
|
### **Quick Resume Prompt (Ceàrd)**:
|
|
|
|
> Read Drift Prevention Card, then GPT Implementation Handover.
|
|
>
|
|
> Platform 85% ready, executing 3-day sprint.
|
|
>
|
|
> Current task: [specific implementation task]
|
|
|
|
---
|
|
|
|
## ✅ Navigation Summary
|
|
|
|
**Strategic** → Master Bootstrap
|
|
**Tactical** → GPT Implementation Handover
|
|
**Integrated** → Complete Current State
|
|
**Governance** → Cross-Project Tracker
|
|
**Constraints** → Infrastructure Specifications
|
|
**Session Start** → Drift Prevention Card
|
|
|
|
**Claude Start** → Master Bootstrap → Cross-Project Tracker
|
|
**Ceàrd Start** → Drift Prevention Card → GPT Implementation Handover
|
|
|
|
**Quick Status** → Complete Current State (first 2 sections)
|
|
|
|
**Implementation** → GPT Implementation Handover → Cross-Project Tracker
|
|
|
|
---
|
|
|
|
🎯 **All documentation in Gitea knowledge base. Both AIs have single source of truth.**
|