# GENESIS LIVING SITEMAP PRD
*Instant Agent Orientation Architecture - The "Mall Directory" for Genesis*

**Created:** 2026-01-16
**Author:** Claude Opus 4.5 + Kinan
**Status:** Ready for Ralph Loop Execution
**Estimated Stories:** 12 atomic user stories
**Budget:** ~$0.15 via Gemini Flash 2.0

---

## MISSION STATEMENT

> **"When a new agent enters Genesis, they should know EVERYTHING in 30 seconds."**

Create an **interactive living sitemap** - a clickable visual map that:
1. Shows all Genesis components at a glance
2. Links directly to files/directories when clicked
3. Auto-updates as Genesis evolves
4. Serves as the "Info Desk" for any agent entering the system

---

## THE PROBLEM

### Current State: Fragmented Orientation

| What Exists | Problem |
|------------|---------|
| `system_overview.md` | Too sparse (46 lines), no links |
| `GENESIS_2026_ARCHITECTURE.md` | Technical deep-dive, not quick orientation |
| `HANDOFF.md` | Session state, not system structure |
| `CLAUDE.md` | Briefing, not map |
| `docs/AGENTS.md` | Coding standards, not navigation |

**Result:** New agents waste 5-10 minutes exploring, burn ~20K tokens scanning files, often misunderstand the system anyway.

### Desired State: Instant Orientation

```
New Agent Arrives
       │
       ▼
┌─────────────────────────────────┐
│      GENESIS LIVING SITEMAP     │
│  ┌─────────────────────────┐    │
│  │  [Interactive Visual]   │    │
│  │  Click any component    │    │
│  │  to jump directly       │    │
│  └─────────────────────────┘    │
│                                  │
│  "You Are Here" marker           │
│  Component descriptions          │
│  Relationship arrows             │
│  Entry points highlighted        │
└─────────────────────────────────┘
       │
       ▼
Agent understands Genesis in 30 seconds
```

---

## RESEARCH: BEST TOOLS FOR LIVING MAPS (2026)

### Selected Approach: Multi-Layer Architecture

| Layer | Tool | Purpose |
|-------|------|---------|
| **L1: Visual** | Mermaid + HTML | Version-controlled, renders in browser |
| **L2: Interactive** | Clickable SVG/HTML | Jump to files on click |
| **L3: Aesthetic** | Excalidraw export | Hand-drawn style option |
| **L4: Living** | Python generator | Auto-updates from codebase |

### Why This Stack?

1. **Mermaid** - Text-based = version controlled in git, renders on GitHub
2. **HTML wrapper** - Clickable regions, custom styling
3. **Excalidraw** - Beautiful hand-drawn aesthetic (optional export)
4. **Python scanner** - Keeps map current with actual codebase

### Alternative Tools Considered

| Tool | Verdict |
|------|---------|
| [CodeSee](https://www.codesee.io/) | Great but SaaS, not self-hosted |
| [Eraser](https://eraser.io/) | AI diagrams, but external dependency |
| [D2](https://d2lang.com/) | Excellent but less ecosystem support |
| [tldraw](https://tldraw.dev/) | Good for live editing, not auto-generation |

**Decision:** Build in-house with Mermaid + HTML for maximum control and zero external dependencies.

---

## ARCHITECTURE

### File Structure

```
/mnt/e/genesis-system/
├── SITEMAP.html              # THE LIVING MAP (main entry point)
├── SITEMAP.md                # Mermaid source (version controlled)
├── sitemap/
│   ├── generator.py          # Auto-generates sitemap from codebase
│   ├── components.json       # Component registry with descriptions
│   ├── relationships.json    # How components connect
│   ├── styles.css            # Visual styling
│   └── excalidraw/           # Excalidraw export files
│       └── genesis_map.excalidraw
└── docs/
    └── SITEMAP_INFO_DESK.md  # Quick reference companion
```

### The Living Map Components

```
┌──────────────────────────────────────────────────────────────────┐
│                    GENESIS LIVING SITEMAP                         │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐        │
│  │   CORE      │────▶│   MEMORY    │────▶│   SKILLS    │        │
│  │  (Engine)   │     │  (Cortex)   │     │ (Actions)   │        │
│  └──────┬──────┘     └──────┬──────┘     └──────┬──────┘        │
│         │                   │                   │                │
│         ▼                   ▼                   ▼                │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐        │
│  │   AIVA      │     │    RLM      │     │    MCP      │        │
│  │  (Queen)    │     │  (Learning) │     │  (Tools)    │        │
│  └─────────────┘     └─────────────┘     └─────────────┘        │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              INFRASTRUCTURE                              │    │
│  │  PostgreSQL │ Redis │ Qdrant │ n8n │ Elestio            │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                   │
│  Click any component to navigate directly ▶                      │
└──────────────────────────────────────────────────────────────────┘
```

---

## USER STORIES (Atomic, Sequential)

### PHASE 1: Foundation (Stories 1-4)

#### **US-001: Component Registry**
**Session:** Fresh Claude Code #1
**Estimated Time:** 10 minutes

**Goal:** Create JSON registry of all Genesis components with descriptions

**Acceptance Criteria:**
- [ ] GIVEN Genesis codebase WHEN scanned THEN all major components identified
- [ ] AND each component has: name, path, description, category
- [ ] AND stored in `/mnt/e/genesis-system/sitemap/components.json`
- [ ] AND includes at minimum 20 core components

**Files to Create:**
```
/mnt/e/genesis-system/sitemap/components.json
```

**Technical Hints:**
```json
{
  "components": [
    {
      "id": "genesis_kernel",
      "name": "Genesis Kernel",
      "path": "/core/genesis_kernel.py",
      "category": "core",
      "description": "Central orchestrator - manages lifecycle, session state, component integration",
      "entry_point": true,
      "links_to": ["blackboard", "memory_cortex", "heartbeat"]
    }
  ]
}
```

**Dependencies:** None (foundational)

---

#### **US-002: Relationship Mapper**
**Session:** Fresh Claude Code #2
**Estimated Time:** 10 minutes

**Goal:** Map how Genesis components connect to each other

**Acceptance Criteria:**
- [ ] GIVEN components.json WHEN analyzed THEN relationships extracted
- [ ] AND relationship has: source, target, type (uses/feeds/triggers)
- [ ] AND stored in `/mnt/e/genesis-system/sitemap/relationships.json`
- [ ] AND captures at minimum 30 relationships

**Files to Create:**
```
/mnt/e/genesis-system/sitemap/relationships.json
```

**Technical Hints:**
```json
{
  "relationships": [
    {
      "source": "genesis_kernel",
      "target": "blackboard",
      "type": "manages",
      "description": "Kernel writes events to blackboard"
    },
    {
      "source": "heartbeat",
      "target": "axiom_generator",
      "type": "triggers",
      "description": "Heartbeat triggers axiom compression on high surprise"
    }
  ]
}
```

**Dependencies:** US-001

---

#### **US-003: Mermaid Source Generator**
**Session:** Fresh Claude Code #3
**Estimated Time:** 12 minutes

**Goal:** Generate Mermaid diagram from component/relationship data

**Acceptance Criteria:**
- [ ] GIVEN components.json and relationships.json WHEN processed THEN valid Mermaid generated
- [ ] AND Mermaid renders without errors
- [ ] AND includes click handlers for navigation
- [ ] AND stored in `/mnt/e/genesis-system/SITEMAP.md`

**Files to Create:**
```
/mnt/e/genesis-system/sitemap/generator.py
/mnt/e/genesis-system/SITEMAP.md
```

**Technical Hints:**
```python
def generate_mermaid(components, relationships):
    lines = ["```mermaid", "flowchart TB"]

    # Add components with click handlers
    for c in components:
        lines.append(f'    {c["id"]}["{c["name"]}"]')
        lines.append(f'    click {c["id"]} "{c["path"]}"')

    # Add relationships
    for r in relationships:
        arrow = "-->" if r["type"] == "uses" else "-.->""
        lines.append(f'    {r["source"]} {arrow} {r["target"]}')

    lines.append("```")
    return "\n".join(lines)
```

**Dependencies:** US-001, US-002

---

#### **US-004: Category Subgraphs**
**Session:** Fresh Claude Code #4
**Estimated Time:** 8 minutes

**Goal:** Organize components into visual subgraphs by category

**Acceptance Criteria:**
- [ ] GIVEN Mermaid diagram WHEN categories applied THEN subgraphs created
- [ ] AND categories include: Core, Memory, Skills, Infrastructure, AIVA, Revenue
- [ ] AND subgraphs have distinct styling
- [ ] AND SITEMAP.md updated with subgraphs

**Files to Modify:**
```
/mnt/e/genesis-system/sitemap/generator.py
/mnt/e/genesis-system/SITEMAP.md
```

**Technical Hints:**
```mermaid
flowchart TB
    subgraph CORE["🧠 Core Engine"]
        kernel[Genesis Kernel]
        blackboard[Blackboard]
        heartbeat[Heartbeat]
    end

    subgraph MEMORY["💾 Memory System"]
        cortex[Memory Cortex]
        rlm[RLM Bridge]
        qdrant[Vector Store]
    end

    CORE --> MEMORY
```

**Dependencies:** US-003

---

### PHASE 2: Interactive HTML (Stories 5-8)

#### **US-005: HTML Wrapper**
**Session:** Fresh Claude Code #5
**Estimated Time:** 12 minutes

**Goal:** Create interactive HTML page that renders the Mermaid sitemap

**Acceptance Criteria:**
- [ ] GIVEN SITEMAP.md WHEN opened in browser THEN Mermaid renders
- [ ] AND page is styled professionally
- [ ] AND includes Genesis branding
- [ ] AND works offline (no CDN dependencies)
- [ ] AND stored as `/mnt/e/genesis-system/SITEMAP.html`

**Files to Create:**
```
/mnt/e/genesis-system/SITEMAP.html
/mnt/e/genesis-system/sitemap/styles.css
```

**Technical Hints:**
```html
<!DOCTYPE html>
<html>
<head>
    <title>Genesis Living Sitemap</title>
    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
    <link rel="stylesheet" href="sitemap/styles.css">
</head>
<body>
    <header>
        <h1>🗺️ Genesis Living Sitemap</h1>
        <p>Click any component to navigate</p>
    </header>
    <main class="mermaid">
        <!-- Mermaid content injected here -->
    </main>
    <script>mermaid.initialize({startOnLoad:true});</script>
</body>
</html>
```

**Dependencies:** US-003

---

#### **US-006: Clickable Navigation**
**Session:** Fresh Claude Code #6
**Estimated Time:** 10 minutes

**Goal:** Make diagram components clickable, linking to actual files

**Acceptance Criteria:**
- [ ] GIVEN rendered diagram WHEN component clicked THEN file opens
- [ ] AND for directories, opens in file explorer
- [ ] AND for .py/.md files, opens in VS Code
- [ ] AND click feedback shown (hover state)

**Files to Modify:**
```
/mnt/e/genesis-system/SITEMAP.html
/mnt/e/genesis-system/sitemap/styles.css
```

**Technical Hints:**
```javascript
// Mermaid click handler
mermaid.initialize({
    startOnLoad: true,
    securityLevel: 'loose',  // Allow clicks
    flowchart: {
        useMaxWidth: true,
        htmlLabels: true
    }
});

// Custom click handler
document.querySelectorAll('.node').forEach(node => {
    node.addEventListener('click', (e) => {
        const path = node.dataset.path;
        // Open in VS Code
        window.location.href = `vscode://file${path}`;
    });
});
```

**Dependencies:** US-005

---

#### **US-007: Info Panel**
**Session:** Fresh Claude Code #7
**Estimated Time:** 10 minutes

**Goal:** Show component details on hover/click without leaving the map

**Acceptance Criteria:**
- [ ] GIVEN component hovered WHEN 500ms elapsed THEN info panel appears
- [ ] AND panel shows: name, description, files, relationships
- [ ] AND panel positioned near cursor
- [ ] AND panel dismissable

**Files to Modify:**
```
/mnt/e/genesis-system/SITEMAP.html
/mnt/e/genesis-system/sitemap/styles.css
```

**Technical Hints:**
```html
<div id="info-panel" class="hidden">
    <h3 id="panel-title"></h3>
    <p id="panel-description"></p>
    <div id="panel-links">
        <h4>Key Files:</h4>
        <ul id="panel-files"></ul>
    </div>
    <button onclick="hidePanel()">×</button>
</div>
```

**Dependencies:** US-005, US-006

---

#### **US-008: Search & Filter**
**Session:** Fresh Claude Code #8
**Estimated Time:** 10 minutes

**Goal:** Add search box to quickly find components

**Acceptance Criteria:**
- [ ] GIVEN search input WHEN typing THEN matching components highlighted
- [ ] AND non-matching components dimmed
- [ ] AND category filter buttons work
- [ ] AND search is instant (no delay)

**Files to Modify:**
```
/mnt/e/genesis-system/SITEMAP.html
/mnt/e/genesis-system/sitemap/styles.css
```

**Technical Hints:**
```javascript
function searchComponents(query) {
    const nodes = document.querySelectorAll('.node');
    nodes.forEach(node => {
        const name = node.textContent.toLowerCase();
        if (name.includes(query.toLowerCase())) {
            node.classList.add('highlighted');
            node.classList.remove('dimmed');
        } else {
            node.classList.remove('highlighted');
            node.classList.add('dimmed');
        }
    });
}
```

**Dependencies:** US-007

---

### PHASE 3: Living Updates (Stories 9-10)

#### **US-009: Auto-Scanner**
**Session:** Fresh Claude Code #9
**Estimated Time:** 15 minutes

**Goal:** Script that scans Genesis codebase and updates sitemap data

**Acceptance Criteria:**
- [ ] GIVEN Genesis codebase WHEN scanner runs THEN components.json updated
- [ ] AND new files detected and added
- [ ] AND deleted files removed
- [ ] AND relationships inferred from imports

**Files to Create:**
```
/mnt/e/genesis-system/sitemap/scanner.py
```

**Technical Hints:**
```python
import ast
import os

def scan_codebase(root_path):
    components = []

    for root, dirs, files in os.walk(root_path):
        for file in files:
            if file.endswith('.py'):
                path = os.path.join(root, file)
                # Parse imports to infer relationships
                with open(path) as f:
                    tree = ast.parse(f.read())
                imports = [node.module for node in ast.walk(tree)
                          if isinstance(node, ast.Import)]
                components.append({
                    "path": path,
                    "imports": imports
                })

    return components
```

**Dependencies:** US-001, US-002

---

#### **US-010: Refresh Command**
**Session:** Fresh Claude Code #10
**Estimated Time:** 8 minutes

**Goal:** CLI command to regenerate sitemap

**Acceptance Criteria:**
- [ ] GIVEN command `python sitemap/refresh.py` WHEN run THEN sitemap regenerated
- [ ] AND SITEMAP.md updated
- [ ] AND SITEMAP.html updated
- [ ] AND timestamp logged

**Files to Create:**
```
/mnt/e/genesis-system/sitemap/refresh.py
```

**Technical Hints:**
```python
#!/usr/bin/env python3
"""Refresh Genesis Living Sitemap"""

from scanner import scan_codebase
from generator import generate_mermaid, generate_html

def main():
    print("🗺️ Refreshing Genesis Sitemap...")

    # Scan
    components = scan_codebase("/mnt/e/genesis-system")

    # Generate
    mermaid = generate_mermaid(components)
    html = generate_html(mermaid)

    # Write
    with open("/mnt/e/genesis-system/SITEMAP.md", "w") as f:
        f.write(mermaid)

    with open("/mnt/e/genesis-system/SITEMAP.html", "w") as f:
        f.write(html)

    print(f"✅ Sitemap refreshed with {len(components)} components")

if __name__ == "__main__":
    main()
```

**Dependencies:** US-003, US-005, US-009

---

### PHASE 4: Info Desk & Integration (Stories 11-12)

#### **US-011: Info Desk Document**
**Session:** Fresh Claude Code #11
**Estimated Time:** 10 minutes

**Goal:** Create quick-reference companion document

**Acceptance Criteria:**
- [ ] GIVEN components.json WHEN processed THEN SITEMAP_INFO_DESK.md generated
- [ ] AND organized by category
- [ ] AND includes "What is this?" for each component
- [ ] AND includes "Entry Points" section
- [ ] AND includes "Common Questions" FAQ

**Files to Create:**
```
/mnt/e/genesis-system/docs/SITEMAP_INFO_DESK.md
```

**Technical Hints:**
```markdown
# Genesis Info Desk

## Quick Answers

### "Where do I start?"
→ Read `HANDOFF.md` for current session state
→ Open `SITEMAP.html` for visual navigation

### "What does X component do?"
| Component | One-Line Answer |
|-----------|-----------------|
| Genesis Kernel | Central orchestrator that manages all components |
| Blackboard | Shared memory bus for agent communication |
| Heartbeat | 10-minute cognitive loop for learning |

### Entry Points by Task
- **New to Genesis?** → Start with SITEMAP.html
- **Continuing work?** → Read HANDOFF.md
- **Building feature?** → Check skills/ directory
- **Debugging?** → Check logs/ directory
```

**Dependencies:** US-001

---

#### **US-012: CLAUDE.md Integration**
**Session:** Fresh Claude Code #12
**Estimated Time:** 5 minutes

**Goal:** Update CLAUDE.md to point agents to the sitemap first

**Acceptance Criteria:**
- [ ] GIVEN CLAUDE.md WHEN agent reads THEN directed to sitemap
- [ ] AND sitemap mentioned in first 10 lines
- [ ] AND clear instruction: "Open SITEMAP.html first"

**Files to Modify:**
```
/mnt/e/genesis-system/CLAUDE.md
```

**Technical Hints:**
```markdown
# GENESIS PROTOCOL - LEAD ARCHITECT BRIEFING

> [!TIP]
> **NEW AGENT?** Open `SITEMAP.html` in browser for instant visual orientation.
> Or read `docs/SITEMAP_INFO_DESK.md` for quick reference.
```

**Dependencies:** US-005, US-011

---

## BONUS: Excalidraw Export (Optional)

#### **US-BONUS: Excalidraw Version**
**Session:** Optional Fresh Session
**Estimated Time:** 15 minutes

**Goal:** Export sitemap to Excalidraw for hand-drawn aesthetic

**Acceptance Criteria:**
- [ ] GIVEN SITEMAP.md WHEN converted THEN valid .excalidraw file created
- [ ] AND maintains clickable links
- [ ] AND uses hand-drawn style

**Files to Create:**
```
/mnt/e/genesis-system/sitemap/excalidraw/genesis_map.excalidraw
```

**Technical Hints:**
- Use [mermaid-to-excalidraw](https://github.com/excalidraw/mermaid-to-excalidraw) converter
- Or [Mermaid to Excalidraw Playground](https://mermaid-to-excalidraw.vercel.app/)

**Dependencies:** US-003

---

## SUCCESS CRITERIA

### Functional
- [ ] SITEMAP.html opens in browser and renders correctly
- [ ] All major components visible (minimum 20)
- [ ] Clicking component navigates to file
- [ ] Info panel shows component details
- [ ] Search finds components instantly
- [ ] Refresh command regenerates sitemap

### Quality
- [ ] New agent can understand Genesis in <30 seconds
- [ ] Zero exploration needed - all info visible
- [ ] Map stays current with codebase
- [ ] Works offline (no external dependencies)

### Integration
- [ ] CLAUDE.md points to sitemap
- [ ] HANDOFF.md references sitemap
- [ ] Info Desk answers common questions

---

## EXECUTION INSTRUCTIONS

### For Ralph Loop Execution:

**Model:** Gemini Flash 2.0 (90% of work)
**Escalation:** Claude Sonnet if needed
**Max Iterations:** 20 per story

**Before Starting:**
1. Read this PRD completely
2. Check `/mnt/e/genesis-system/sitemap/` doesn't exist yet
3. Create directory: `mkdir -p /mnt/e/genesis-system/sitemap`

**For Each Story:**
1. Fresh session (no context accumulation)
2. Execute story atomically
3. Validate all acceptance criteria
4. Log to HANDOFF.md
5. Move to next story

---

## ESTIMATED OUTCOMES

| Metric | Before | After |
|--------|--------|-------|
| Agent orientation time | 5-10 minutes | 30 seconds |
| Tokens wasted exploring | ~20K | ~2K |
| Misunderstanding risk | High | Low |
| Cross-agent consistency | Fragmented | Unified |

---

## REFERENCES

### Tools Research
- [Excalidraw Alternatives](https://clickup.com/blog/excalidraw-alternatives/)
- [CodeSee - Codebase Visibility](https://www.codesee.io/)
- [Mermaid vs D2 Comparison](https://aaronjbecker.com/posts/mermaid-vs-d2-comparing-text-to-diagram-tools/)
- [Mermaid to Excalidraw](https://github.com/excalidraw/mermaid-to-excalidraw)
- [Code Visualization Tools 2026](https://thectoclub.com/tools/best-code-visualization-tools/)

### Genesis Context
- Ralph Matrix: `/mnt/e/genesis-system/backups/ralph-wiggum-20260115/Ralph Matrix/`
- TRUE Method: `Voice_PRD_True_Method.md`
- Current overview: `/mnt/e/genesis-system/system_overview.md`

---

*"A map is not the territory, but a good map makes the territory navigable."*

**Ready for Ralph Loop execution. Start with US-001 in fresh session.**
