the-nexus/CLAUDE.md

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

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