# 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, WS bridge (~all logic)
portals.json  # Portal registry (data-driven)
vision.json   # Vision point content (data-driven)
server.js     # Optional: proxy server for CORS (commit heatmap API)
```

No build step. Served as static files. Import maps in `index.html` handle Three.js resolution.

## WebSocket Bridge (v2.0)

The Nexus connects to Timmy's backend via WebSocket for live cognitive state:

- **URL**: `?ws=ws://hermes:8765` query param, or default `ws://localhost:8765`
- **Inbound**: `agent_state`, `agent_move`, `chat_response`, `system_metrics`, `dual_brain`, `heartbeat`
- **Outbound**: `chat_message`, `presence`
- **Graceful degradation**: When WS is offline, agents idle locally, chat shows "OFFLINE"

## The Hard Rule — Read This First

**Every PR: net ≤ 10 added lines.** Add 40, remove 30. Can't remove? Import instead.
You MUST plan your cuts BEFORE writing new code. See CONTRIBUTING.md.
Do NOT self-merge. Do NOT submit a PR that violates this.

## 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`
- **Line budget** — app.js should stay under 1500 lines
- **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.**

## PR Rules

- **Net addition limit: ≤ 10 lines.** No exceptions. Plan cuts before writing.
- **Do NOT self-merge.** Submit the PR, a different user merges it.
- Base every PR on latest `main`
- Squash merge only
- Include manual test plan + automated test output in PR body
- Include `Fixes #N` or `Refs #N` in commit message

## Running Locally

```bash
npx serve . -l 3000
# open http://localhost:3000
# To connect to Timmy: http://localhost:3000?ws=ws://hermes:8765
```

## Gitea API

```
Base URL: http://143.198.27.163:3000/api/v1
Repo:     Timmy_Foundation/the-nexus
```