diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..9251335
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,77 @@
+# CLAUDE.md — The Nexus (Timmy_Foundation/the-nexus)
+
+## Project Overview
+
+The Nexus is a Three.js environment — Timmy's sovereign home in 3D space. It serves as the central hub for all portals to other worlds. Stack: vanilla JS ES modules, Three.js 0.183, no bundler.
+
+## Architecture
+
+```
+index.html    # Entry point: HUD, chat panel, loading screen, live-reload script
+style.css     # Design system: dark space theme, holographic panels
+app.js        # Three.js scene, shaders, controls, game loop (~all logic)
+```
+
+No build step. Served as static files. Import maps in `index.html` handle Three.js resolution.
+
+## Conventions
+
+- **ES modules only** — no CommonJS, no bundler
+- **Single-file app** — logic lives in `app.js`; don't split without good reason
+- **Color palette** — defined in `NEXUS.colors` at top of `app.js`
+- **Conventional commits**: `feat:`, `fix:`, `refactor:`, `test:`, `chore:`
+- **Branch naming**: `claude/issue-{N}` (e.g. `claude/issue-5`)
+- **One PR at a time** — wait for merge-bot before opening the next
+
+## Validation (merge-bot checks)
+
+The `nexus-merge-bot.sh` validates PRs before auto-merge:
+
+1. HTML validation — `index.html` must be valid HTML
+2. JS syntax — `node --check app.js` must pass
+3. JSON validation — any `.json` files must parse
+4. File size budget — JS files must be < 500 KB
+
+**Always run `node --check app.js` before committing.**
+
+## Sequential Build Order — Nexus v1
+
+Issues must be addressed one at a time. Only one PR open at a time.
+
+| # | Issue | Status |
+|---|-------|--------|
+| 1 | #4 — Three.js scene foundation (lighting, camera, navigation) | ✅ done |
+| 2 | #5 — Portal system — YAML-driven registry | pending |
+| 3 | #6 — Batcave terminal — workshop integration in 3D | pending |
+| 4 | #9 — Visitor presence — live count + Timmy greeting | pending |
+| 5 | #8 — Agent idle behaviors in 3D world | pending |
+| 6 | #10 — Kimi & Perplexity as visible workshop agents | pending |
+| 7 | #11 — Tower Log — narrative event feed | pending |
+| 8 | #12 — NIP-07 visitor identity in the workshop | pending |
+| 9 | #13 — Timmy Nostr identity, zap-out, vouching | pending |
+| 10 | #14 — PWA manifest + service worker | pending |
+| 11 | #15 — Edge intelligence — browser model + silent Nostr signing | pending |
+| 12 | #16 — Session power meter — 3D balance visualizer | pending |
+| 13 | #18 — Unified memory graph & sovereignty loop visualization | pending |
+
+## PR Rules
+
+- Base every PR on latest `main`
+- Squash merge only
+- **Do NOT merge manually** — merge-bot handles merges
+- If merge-bot comments "CONFLICT": rebase onto `main` and force-push your branch
+- Include `Fixes #N` or `Refs #N` in commit message
+
+## Running Locally
+
+```bash
+npx serve . -l 3000
+# open http://localhost:3000
+```
+
+## Gitea API
+
+```
+Base URL: http://143.198.27.163:3000/api/v1
+Repo:     Timmy_Foundation/the-nexus
+```