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, 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

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