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

app.js is a thin orchestrator. It should almost never change.

All logic lives in ES modules under modules/. app.js only imports modules, wires them to the ticker, and starts the loop. New features go in new modules — not in app.js.

index.html              # Entry point: HUD, chat panel, loading screen
style.css               # Design system: dark space theme, holographic panels
app.js                  # THIN ORCHESTRATOR — imports + init + ticker start (~200 lines)
modules/
  core/
    scene.js            # THREE.Scene, camera, renderer, controls, resize
    ticker.js           # Global Animation Clock — the single RAF loop
    theme.js            # NEXUS.theme — colors, fonts, line weights, glow params
    state.js            # Shared data bus (activity, weather, BTC, agents)
    audio.js            # Web Audio: reverb, panner, ambient, portal hums
  data/
    gitea.js            # All Gitea API calls (commits, PRs, agents)
    weather.js          # Open-Meteo weather fetch
    bitcoin.js          # Blockstream BTC block height
    loaders.js          # JSON file loaders (portals, sovereignty, SOUL)
  panels/
    heatmap.js          # Commit heatmap + zone rendering
    agent-board.js      # Agent status board (Gitea API)
    dual-brain.js       # Dual-brain panel (honest offline)
    lora-panel.js       # LoRA adapter panel (honest empty)
    sovereignty.js      # Sovereignty meter + score arc
    earth.js            # Holographic earth (activity-tethered)
  effects/
    matrix-rain.js      # Matrix rain (commit-tethered)
    lightning.js        # Lightning arcs between zones
    energy-beam.js      # Energy beam (agent-count-tethered)
    rune-ring.js        # Rune ring (portal-tethered)
    gravity-zones.js    # Gravity anomaly zones
    shockwave.js        # Shockwave, fireworks, merge flash
  terrain/
    island.js           # Floating island + crystals
    clouds.js           # Cloud layer (weather-tethered)
    stars.js            # Star field + constellations (BTC-tethered)
  portals/
    portal-system.js    # Portal creation, warp, health checks
    commit-banners.js   # Floating commit banners
  narrative/
    bookshelves.js      # Floating bookshelves (SOUL.md)
    oath.js             # Oath display + enter/exit
    chat.js             # Chat panel, speech bubbles, NPC dialog
  utils/
    perlin.js           # Perlin noise generator
    geometry.js         # Shared geometry helpers
    canvas-utils.js     # Canvas texture creation helpers

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

Conventions

• ES modules only — no CommonJS, no bundler
• Modular architecture — all logic in modules/. app.js is the orchestrator and should almost never change.
• Module contract — every module exports init(scene, state, theme) and update(elapsed, delta). Optional: dispose()
• Single animation clock — one requestAnimationFrame in ticker.js. No module may call RAF directly. All subscribe to the ticker.
• Theme is law — all colors, fonts, line weights come from NEXUS.theme in theme.js. No inline hex codes, no hardcoded font strings.
• Data flows through state — data modules write to state.js, visual modules read from it. No fetch() outside data/ modules.
• 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
• Atomic PRs — target <150 lines changed per PR. Commit by concern: data, logic, or visuals. If a change needs >200 lines, split into sequential PRs.
• No new code in app.js — new features go in a new module or extend an existing module. The only reason to touch app.js is to add an import line for a new module.

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

---

Nexus Data Integrity Standard

This is law. Every contributor — human or AI — must follow these rules. No exceptions.

Core Principle

Every visual element in the Nexus must be tethered to reality. Nothing displayed may present fabricated data as if it were live. If a system is offline, the Nexus shows it as offline. If data doesn't exist yet, the element shows an honest empty state. There are zero acceptable reasons to display mocked data in the Nexus.

The Three Categories

Every visual element falls into exactly one category:

1. REAL — Connected to a live data source (API, file, computed value). Displays truthful, current information. Examples: commit heatmap from Gitea, weather from Open-Meteo, Bitcoin block height.

2. HONEST-OFFLINE — The system it represents doesn't exist yet or is currently unreachable. The element is visible but clearly shows its offline/empty/awaiting state. Dim colors, empty bars, "OFFLINE" or "AWAITING DEPLOYMENT" labels. No fake numbers. Examples: dual-brain panel before deployment, LoRA panel with no adapters trained.

3. DATA-TETHERED AESTHETIC — Visually beautiful and apparently decorative, but its behavior (speed, density, brightness, color, intensity) is driven by a real data stream. The connection doesn't need to be obvious to the viewer, but it must exist in code. Examples: matrix rain density driven by commit activity, star brightness pulsing on Bitcoin blocks, cloud layer density from weather data.

Banned Practices

• No hardcoded stubs presented as live data. No AGENT_STATUS_STUB, no LORA_STATUS_STUB, no hardcoded scores. If the data source isn't ready, show an empty/offline state.
• No static JSON files pretending to be APIs. Files like api/status.json with hardcoded agent statuses are lies. Either fetch from the real API or show the element as disconnected.
• No fictional artifacts. Files like lora-status.json containing invented adapter names that don't exist must be deleted. The filesystem must not contain fiction.
• No untethered aesthetics. Every moving, glowing, or animated element must be connected to at least one real data stream. Pure decoration with no data connection is not permitted. Constellation lines (structural) are the sole exception.
• No "online" status for unreachable services. If a URL doesn't respond to a health check, it is offline. The Nexus does not lie about availability.

PR Requirements (Mandatory)

Every PR to this repository must include:

1. Data Integrity Audit — A table in the PR description listing every visual element the PR touches, its category (REAL / HONEST-OFFLINE / DATA-TETHERED AESTHETIC), and the data source it connects to. Format:

   | Element | Category | Data Source |
   |---------|----------|-------------|
   | Agent Status Board | REAL | Gitea API /repos/.../commits |
   | Matrix Rain | DATA-TETHERED AESTHETIC | zoneIntensity (commit count) |
   | Dual-Brain Panel | HONEST-OFFLINE | Shows "AWAITING DEPLOYMENT" |
   

2. Test Plan — Specific steps to verify that every changed element displays truthful data or an honest offline state. Include:

   • How to trigger each state (online, offline, empty, active)
   • What the element should look like in each state
   • How to confirm the data source is real (API endpoint, computed value, etc.)

3. Verification Screenshot — At least one screenshot or recording showing the before-and-after state of changed elements. The screenshot must demonstrate:

   • Elements displaying real data or honest offline states
   • No hardcoded stubs visible
   • Aesthetic elements visibly responding to their data tether

4. Syntax Check — node --check app.js must pass. (Existing rule, restated for completeness.)

A PR missing any of these four items must not be merged.

Existing Element Registry

Canonical reference for every Nexus element and its required data source:

#	Element	Category	Data Source	Status
1	Commit Heatmap	REAL	Gitea commits API	✅ Connected
2	Weather System	REAL	Open-Meteo API	✅ Connected
3	Bitcoin Block Height	REAL	blockstream.info	✅ Connected
4	Commit Banners	REAL	Gitea commits API	✅ Connected
5	Floating Bookshelves / Oath	REAL	SOUL.md file	✅ Connected
6	Portal System	REAL + Health Check	portals.json + URL probe	✅ Connected
7	Dual-Brain Panel	HONEST-OFFLINE	— (system not deployed)	✅ Honest
8	Agent Status Board	REAL	Gitea API (commits + PRs)	✅ Connected
9	LoRA Panel	HONEST-OFFLINE	— (no adapters deployed)	✅ Honest
10	Sovereignty Meter	REAL (manual)	sovereignty-status.json + MANUAL label	✅ Connected
11	Matrix Rain	DATA-TETHERED AESTHETIC	zoneIntensity (commits) + commit hashes	✅ Tethered
12	Star Field	DATA-TETHERED AESTHETIC	Bitcoin block events (brightness pulse)	✅ Tethered
13	Constellation Lines	STRUCTURAL (exempt)	—	✅ No change needed
14	Crystal Formations	DATA-TETHERED AESTHETIC	totalActivity()	🔍 Verify connection
15	Cloud Layer	DATA-TETHERED AESTHETIC	Weather API (cloud_cover)	✅ Tethered
16	Rune Ring	DATA-TETHERED AESTHETIC	portals.json (count + status + colors)	✅ Tethered
17	Holographic Earth	DATA-TETHERED AESTHETIC	totalActivity() (rotation speed)	✅ Tethered
18	Energy Beam	DATA-TETHERED AESTHETIC	Active agent count	✅ Tethered
19	Gravity Anomaly Zones	DATA-TETHERED AESTHETIC	Portal positions + status	✅ Tethered
20	Brain Pulse Particles	HONEST-OFFLINE	— (dual-brain not deployed, particles OFF)	✅ Honest

When a new visual element is added, it must be added to this registry in the same PR.

Enforcement

Any agent or contributor that introduces mocked data, untethered aesthetics, or fake statuses into the Nexus is in violation of this standard. The merge-bot should reject PRs that lack the required audit table, test plan, or verification screenshot. This standard is permanent and retroactive — existing violations must be fixed, not grandfathered.