the-nexus/CLAUDE.md

CLAUDE.md — The Nexus (Timmy_Foundation/the-nexus)

Project Overview

The Nexus is Timmy's canonical 3D/home-world repo. Its intended role is:

• local-first training ground for Timmy
• wizardly visualization surface for the system

Current Repo Truth

Do not describe this repo as a live browser app on main.

Current main does not ship the old root frontend files:

• index.html
• app.js
• style.css
• package.json

A clean checkout of current main serves a directory listing if you static-serve the repo root. That is world-state truth.

The live browser shell people remember exists in legacy form at:

• /Users/apayne/the-matrix

That legacy app is source material for migration, not a second canonical repo.

Timmy_Foundation/the-nexus is the only canonical 3D repo.

See:

• LEGACY_MATRIX_AUDIT.md
• issues #684, #685, #686, #687

Architecture (current main)

Current repo contents are centered on:

• nexus/ — Python cognition / heartbeat components
• server.py — local websocket bridge
• portals.json, vision.json — data/config artifacts
• deployment/docs files

Do not tell contributors to run Vite or edit a nonexistent root frontend on current main. If browser/UI work is being restored, it must happen through the migration backlog and land back here.

Hard Rules

1. One canonical 3D repo only: Timmy_Foundation/the-nexus
2. No parallel evolution of /Users/apayne/the-matrix as if it were the product
3. Rescue useful legacy Matrix work by auditing and migrating it here
4. Telemetry and durable truth flow through Hermes harness
5. OpenClaw remains a sidecar, not the governing authority
6. Before claiming visual validation, prove the app being viewed actually comes from current the-nexus

Validation Rule

If you are asked to visually validate Nexus:

• prove the tested app comes from a clean checkout/worktree of Timmy_Foundation/the-nexus
• if current main only serves a directory listing or otherwise lacks the browser world, stop calling it visually validated
• pivot to migration audit and issue triage instead of pretending the world still exists

Migration Priorities

1. #684 — docs truth
2. #685 — legacy Matrix preservation audit
3. #686 — browser smoke / visual validation rebuild
4. #687 — restore wizardly local-first visual shell
5. then continue portal/gameplay work (#672, #673, #674, #675)

Legacy Matrix rescue targets

The old Matrix contains real quality work worth auditing:

• visitor movement and embodiment
• agent presence / bark / chat systems
• transcript logging
• ambient world systems
• satflow / economy visualization
• browser smoke tests and production build discipline

Preserve the good work. Do not preserve stale assumptions or fake architecture.