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.

## Canonical File Paths

**Frontend code lives at repo ROOT, NOT in `public/nexus/`:**
- `app.js` — main Three.js app (GOFAI, 3D world, all frontend logic)
- `index.html` — main HTML shell
- `style.css` — styles
- `server.py` — websocket bridge
- `gofai_worker.js` — web worker for off-thread reasoning

**DO NOT write to `public/nexus/`** — this path is gitignored. Agents historically wrote here by mistake, creating corrupt duplicates. See issue #1145 and `INVESTIGATION_ISSUE_1145.md`.

## 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`
7. **NEVER write frontend files to `public/nexus/`** — use repo root paths listed above

## 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.