the-nexus/LEGACY_MATRIX_AUDIT.md

# Legacy Matrix Audit

Purpose:
Preserve useful work from `/Users/apayne/the-matrix` before the Nexus browser shell is rebuilt.

Canonical rule:
- `Timmy_Foundation/the-nexus` is the only canonical 3D repo.
- `/Users/apayne/the-matrix` is legacy source material, not a parallel product.

## Verified Legacy Matrix State

Local legacy repo:
- `/Users/apayne/the-matrix`

Observed facts:
- Vite browser app exists
- `npm test` passes with `87 passed, 0 failed`
- 23 JS modules under `js/`
- package scripts include `dev`, `build`, `preview`, and `test`

## Known historical Nexus snapshot

Useful in-repo reference point:
- `0518a1c3ae3c1d0afeb24dea9772102f5a3d9a66`

That snapshot still contains browser-world root files such as:
- `index.html`
- `app.js`
- `style.css`
- `package.json`
- `tests/`

## Rescue Candidates

### Carry forward into Nexus vNext

1. `agent-defs.js`
- agent identity definitions
- useful as seed data/model for visible entities in the world

2. `agents.js`
- agent objects, state machine, connection lines
- useful for visualizing Timmy / subagents / system processes in a world-native way

3. `avatar.js`
- visitor embodiment, movement, camera handling
- strongly aligned with "training ground" and "walk the world" goals

4. `ui.js`
- HUD, chat surfaces, overlays
- useful if rebuilt against real harness data instead of stale fake state

5. `websocket.js`
- browser-side live bridge patterns
- useful if retethered to Hermes-facing transport

6. `transcript.js`
- local transcript capture pattern
- useful if durable truth still routes through Hermes and browser cache remains secondary

7. `ambient.js`
- mood / atmosphere system
- directly supports wizardly presentation without changing system authority

8. `satflow.js`
- visual economy / payment flow motifs
- useful if Timmy's economy/agent interactions become a real visible layer

9. `economy.js`
- treasury / wallet panel ideas
- useful if later backed by real sovereign metrics

10. `presence.js`
- who-is-here / online-state UI
- useful for showing human + agent + process presence in the world

11. `interaction.js`
- clicking, inspecting, selecting world entities
- likely needed in any real browser-facing Nexus shell

12. `quality.js`
- hardware-aware quality tiering
- useful for local-first graceful degradation on Mac hardware

13. `bark.js`
- prominent speech / bark system
- strong fit for Timmy's expressive presence in-world

14. `world.js`, `effects.js`, `scene-objects.js`, `zones.js`
- broad visual foundation work
- should be mined for patterns, not blindly transplanted

15. `test/smoke.mjs`
- browser smoke discipline
- should inform rebuilt validation in canonical Nexus repo

### Archive as reference, not direct carry-forward

- demo/autopilot assumptions that pretend fake backend activity is real
- any websocket schema that no longer matches Hermes truth
- Vite-specific plumbing that is only useful if we consciously recommit to Vite

### Deliberately drop unless re-justified

- anything that presents mock data as if it were live
- anything that duplicates a better Hermes-native telemetry path
- anything that turns the browser into the system of record

## Concern Separation for Nexus vNext

When rebuilding inside `the-nexus`, keep concerns separated:

1. World shell / rendering
- scene, camera, movement, atmosphere

2. Presence and embodiment
- avatar, agent placement, selection, bark/chat surfaces

3. Harness bridge
- websocket / API bridge from Hermes truth into browser state

4. Visualization panels
- metrics, presence, economy, portal states, transcripts

5. Validation
- smoke tests, screenshot proof, provenance checks

6. Game portal layer
- Morrowind / portal-specific interaction surfaces

Do not collapse all of this into one giant app file again.
Do not let visual shell code become telemetry authority.

## Migration Rule

Rescue knowledge first.
Then rescue modules.
Then rebuild the browser shell inside `the-nexus`.

No more ghost worlds.
No more parallel 3D repos.