Timmy_Foundation/the-nexus
16
1
Fork 2
Code Issues 90 Pull Requests Actions 11 Packages Projects Releases Wiki Activity
Files
1c18fbf0d1eaf9ac8336fbc39327c466b1808ee3
the-nexus/CLAUDE.md
Claude (Opus 4.6) ee9d5b0108
Some checks failed
Deploy Nexus / deploy (push) Has been cancelled
Details
[claude] Add Commit Discipline section to CLAUDE.md (#429) (#436)
2026-03-24 18:13:32 +00:00

13 KiB
Raw Blame History

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

Commit Discipline

Every PR must focus on exactly ONE concern. No exceptions.

PR Size Limits

  • Target: <150 lines changed per PR. This is the default ceiling.
  • Hard limit: >200 lines → split into sequential PRs. If your change exceeds 200 lines, stop and decompose it before opening a PR.
  • One concern per PR: data layer, logic, OR visuals — never mixed in a single PR.

Commit by Function

Use the concern as a commit scope prefix:

Concern Example commit message
Data layer feat: data-provider for agent status
Visual / style style: neon-update on portal ring
Refactor refactor: extract ticker from app.js
Fix fix: portal health-check timeout
Process / docs chore: update CLAUDE.md commit rules

Decomposition Rules

When a feature spans multiple concerns (e.g. new data + new visual):

  1. Open a PR for the data module first. Wait for merge.
  2. Open a PR for the visual module that reads from state. Wait for merge.
  3. Never combine data + visual work in one PR.

Exception: Modularization Epics

Large refactors tracked as a numbered epic (e.g. #409) may use one PR per phase, where each phase is a logical, atomic unit of the refactor. Phases must still target <150 lines where possible and must not mix unrelated concerns.

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.

Reference in New Issue View Git Blame Copy Permalink