# 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
```