Perplexity Computer
cecf4b5f45
Some checks failed
Deploy Nexus / deploy (push) Has been cancelled
Co-authored-by: Perplexity Computer <perplexity@tower.local> Co-committed-by: Perplexity Computer <perplexity@tower.local>
79 lines
2.8 KiB
Markdown
79 lines
2.8 KiB
Markdown
# 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
|
|
```
|