🧬 kbird.ai

CLAUDE

7 min read

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Convergence Protocol is an interactive web-based experience composed of 40 philosophical/psychological scenarios accessible through a 3D hallway interface (“The Motel”). The project is pre-launch with complete content, requiring audio generation and guidebook population to reach full launch.

Status: Phase 2 - Content complete, audio & guidebook in progress Location: ~/Public/convergence-protocol/ Size: ~3MB

Architecture

Core Components

  1. The Motel (index.html)

    • 3D Three.js hallway using vanilla JavaScript
    • 40 numbered doors representing philosophical/cognitive topics
    • WASD movement + mouse look (desktop) with mobile grid fallback
    • AudioManager class for spatial audio integration
    • Door states: available (cyan), preview (purple), locked (grey)
    • Real-time progress tracking and completion state persistence

  2. Experiences (experiences/ directory)

    • 40 self-contained HTML files (one per topic)
    • Each is vanilla JS/CSS - no build tools required
    • Topics: cognitive biases, existential threats, system failures, etc.
    • File naming: topic-name.html (maps to door title)
    • All experience files have “Back to Motel” navigation

  3. Audio System (assets/audio/)

    • Generated via ElevenLabs API (generate_audio.py)
    • Categories: door sounds, ambient loops, narration, UI feedback
    • Spatial audio ready (Web Audio API mixing)
    • Not yet generated - requires API key and script execution

  4. Guidebook (guidebook/ directory)

    • Wikipedia article summaries for each of the 40 topics
    • Populated via fetch_wiki.sh script
    • Currently empty - awaiting script execution
    • Serves as primers before entering experience rooms

  5. Documentation (docs/)

    • design-system/ - Visual styles, typography, responsive design
    • motel/ - 3D hallway architecture, door mechanics, navigation
    • hero-moloch/ - Special experience: The Well (epic narrative)
    • convergence-protocol/ - Framework, progression system, cookies

Development Commands

Audio Generation

export ELEVENLABS_API_KEY="your-key"
python3 generate_audio.py

This generates all sound effects and narration to assets/audio/ using ElevenLabs APIs. No audio files exist yet.

Populate Guidebook

cd ~/Public/convergence-protocol
bash fetch_wiki.sh

This downloads Wikipedia article summaries and creates JSON files in guidebook/ for each of the 40 topics.

Running the Project

# Open in browser (no server required for most features)
open index.html
 
# Or use a local server (needed for some AJAX/fetch operations)
python3 -m http.server 8000
# Then visit http://localhost:8000

Configuration & Deployment

# Export settings for syncing across machines
tar -czf ~/openclaw_settings_backup.tar.gz ~/.openclaw
 
# Sync settings from Mac to Lenovo
~/Public/convergence-protocol/sync_openclaw_settings.sh nosos@home-server
 
# Sync from Lenovo back to Mac
~/Public/convergence-protocol/sync_from_legion.sh [email protected]
 
# Deploy to production server
rsync -avz ~/Public/convergence-protocol/ user@server:/var/www/convergence-protocol/

Key Files & Structure

convergence-protocol/
├── index.html                    # Main entry point - The Motel hallway (3D)
├── experiences/                  # 40 interactive experience rooms
│   ├── the-well.html            # Epic experience: Moloch (hero narrative)
│   ├── black-swan.html
│   ├── cognitive_bias_*.html    # Various cognitive biases
│   └── ... (34 more experiences)
├── guidebook/                    # Wikipedia summaries (in progress)
│   ├── fetch_wiki.sh            # Script to populate this directory
│   └── (40 .json files - currently empty)
├── assets/
│   ├── audio/                   # Audio files (not yet generated)
│   │   ├── generate_audio.py    # ElevenLabs generation script
│   │   ├── doors/               # Door interaction sounds
│   │   ├── ambient/             # Hallway loops & atmosphere
│   │   ├── ui/                  # UI feedback sounds
│   │   └── narration/           # Welcome/completion narration
│   └── (empty - room for textures/assets)
├── docs/
│   ├── design-system/           # Visual system specs
│   ├── motel/                   # Hallway architecture & mechanics
│   ├── hero-moloch/             # The Well narrative structure
│   └── convergence-protocol/    # Framework & progression system
├── HANDOFF.md                    # Detailed handoff notes
├── 3_NODE_STRATEGY.md           # OpenClaw multi-node sync strategy
├── SYNC_GUIDE.md                # Sync workflows for config management
├── 100_SAYINGS.md               # Curated wisdom quotes (metadata)
└── README files and scripts

Code Patterns & Conventions

HTML/JS Structure

  • Vanilla JavaScript, no frameworks required
  • Each experience is self-contained with embedded CSS and JS
  • Bootstrap with <meta charset="UTF-8"> and viewport meta tag
  • CSS uses custom properties (:root --variables) for theming
  • Dark theme with luminous accents (neon, gold, bioluminescence)

Three.js Hallway (index.html)

  • FPV camera movement (WASD + mouse look)
  • Door objects with clickable areas that trigger modal overlays
  • Progress persistence using browser localStorage
  • Mobile fallback: CSS grid of door cards instead of 3D hallway
  • Responsive: switches to grid layout on small screens

Styling Patterns

  • Design uses gradients, text-shadows, and glowing effects
  • Animation utilities: fadeUp, fadeIn, slideReveal, pulseGlow, breathe
  • Color scheme: void black background, cyan/purple/gold accents
  • Typography: Courier New monospace for digital aesthetic

Audio Integration

  • AudioManager class handles spatial audio mixing
  • Hooks: door hover (available/preview/locked), door open, ambient loops, narration
  • Lazy-loaded: audio files only play when relevant events occur
  • Note: All audio files reference paths that don’t exist yet

Important Architectural Notes

Linear vs Branching

Currently a linear hallway with 40 sequential doors. Branching hallway (left/right splits) was proposed but deferred for launch. Keep linear for now.

Data Persistence

  • Uses localStorage to track visited rooms and completion state
  • Cookie system tracks user progression (see cookie-architecture.md)
  • No server-side persistence required for MVP

Mobile Support

  • Detection: if viewport < 768px or touch device
  • Fallback: CSS grid of door cards replaces 3D hallway
  • All experiences work on mobile (self-contained, responsive)

The Well Experience

  • experiences/the-well.html is special: the “hero” experience
  • Epic narrative with multiple choice branching
  • Represents Moloch (sacrifice, systems, inevitable structures)
  • More complex than other experiences - careful when editing

Integration Points

Audio System (Not Yet Generated)

  • generate_audio.py requires ElevenLabs API key
  • Output directories are created but files are empty
  • Categories: doors (metal/wood open/close, locked, hover states), ambient (hallway, void, neon), UI (check-in, complete, transition), narration
  • Once generated, triggered by AudioManager on DOM events

Guidebook (Not Yet Populated)

  • fetch_wiki.sh downloads summaries for all 40 topics
  • Should create 40 JSON files in guidebook/
  • Each file contains Wikipedia summary for that room’s topic
  • Can be linked from mind map nodes or presented before entering rooms

Mind Map / Terminal UI (Future)

  • Proposed: pydo.html (terminal-like interface) and mindmap.html (node visualization)
  • Should link to guidebook articles and track node clicks
  • Not yet implemented

Testing & Validation

Manual Testing Checklist

  1. Open index.html in browser (or run local server)
  2. WASD movement + mouse look should work smoothly
  3. Click doors to open room modals
  4. Verify all 40 experiences load correctly
  5. Check back button returns to motel
  6. Verify progress persistence (reload and check completed rooms)
  7. Test mobile fallback by shrinking window to <768px

Browser Requirements

  • Modern browser with Three.js support (Chrome, Firefox, Safari, Edge)
  • ES6 JavaScript (template literals, arrow functions)
  • Web Audio API for spatial audio
  • localStorage for persistence

Future Development

Immediate (Pre-Launch)

  1. Run generate_audio.py with ElevenLabs API key
  2. Run fetch_wiki.sh to populate guidebook
  3. Full integration testing

Short Term (2 Weeks)

  1. Implement mindmap.html and pydo.html (terminal UI)
  2. Add “Back to Motel” buttons to any experiences missing them
  3. Optimize load times and Three.js performance

Medium Term (1 Month)

  1. Analytics: room completion rates, user paths, engagement heatmaps
  2. Production deployment and monitoring
  3. Optional: branching hallway implementation

Important Decisions & Context

Why No Build Tools?

  • Experiences are meant to be portable, standalone HTML files
  • Simplifies deployment and reduces dependencies
  • Easier for users to remix/fork individual experiences
  • Fast development iteration without build step

Audio Strategy

  • Pre-generate audio via API (not runtime generation) to save costs
  • Spatial Web Audio mixing in browser (no server-side processing)
  • Ambient loops play continuously; effects are event-triggered

Content Strategy

  • 40 topics chosen to represent cognitive biases, systemic risks, and philosophical paradoxes
  • Each experience is 5-15 minute immersion
  • The Well (Moloch) is the capstone experience with branching narrative
  • Guidebook provides context without spoiling experience

OpenClaw Multi-Node Setup

  • MacBook (primary dev, voice clone generation)
  • Lenovo (24/7 always-on, syncs from Mac)
  • China node (separate config, VPN-routed, different endpoints)
  • See 3_NODE_STRATEGY.md for detailed sync and config management

Notes for Future Work

  • Audio files are not checked into version control (generated on demand)
  • Guidebook articles can be manually edited after script population if needed
  • Three.js scene is optimized but may need LOD (level of detail) for lower-end devices
  • Consider adding haptic feedback for mobile door interactions
  • Social features deferred to post-launch phase

Graph View