Add comprehensive README

README.md

@@ -0,0 +1,53 @@
+# ◈ The Nexus — Timmy's Sovereign Home
+
+A Three.js environment serving as Timmy's sovereign space — like Dr. Strange's Sanctum Sanctorum, existing outside time. The Nexus is the central hub from which all worlds are accessed through portals.
+
+## Features
+
+- **Procedural Nebula Skybox** — animated stars, twinkling, layered nebula clouds
+- **Batcave Terminal** — 5 holographic display panels arranged in an arc showing:
+  - Nexus Command (system status, harness state, agent loops)
+  - Dev Queue (live Gitea issue references)
+  - Metrics (uptime, commits, CPU/MEM)
+  - Thought Stream (Timmy's current thoughts)
+  - Agent Status (all agent states)
+- **Morrowind Portal** — glowing torus with animated swirl shader, ready for world connection
+- **Admin Chat (Timmy Terminal)** — real-time message interface, ready for Hermes WebSocket
+- **Nexus Core** — floating crystalline icosahedron on pedestal
+- **Ambient Environment** — crystal formations, floating runestones, energy particles, atmospheric fog
+- **WASD + Mouse Navigation** — first-person exploration of the space
+- **Post-Processing** — Unreal Bloom + SMAA antialiasing
+
+## Architecture
+
+```
+the-nexus/
+├── index.html    # Entry point with HUD overlay, chat panel, loading screen
+├── style.css     # Nexus design system (dark space theme, holographic panels)
+└── app.js        # Three.js scene, shaders, controls, game loop
+```
+
+## Running Locally
+
+```bash
+npx serve . -l 3000
+# Open http://localhost:3000
+```
+
+## Roadmap
+
+- [ ] Wire chat to Hermes WebSocket (`/api/world/ws`)
+- [ ] Pull live data into terminal panels from Timmy's actual state
+- [ ] Portal walk-through interaction to load destination worlds
+- [ ] Timmy's avatar (lizard wizard body he designs himself)
+- [ ] Connect to AlexanderWhitestone.com as public entry point
+- [ ] Integrate existing Replit timmy-tower world code
+
+## Related
+
+- **Gitea Issue**: [#1090 — EPIC: Nexus v1](http://143.198.27.163:3000/rockachopa/Timmy-time-dashboard/issues/1090)
+- **Live Demo**: Deployed via Perplexity Computer
+
+---
+
+*Part of [The Timmy Foundation](http://143.198.27.163:3000/Timmy_Foundation)*