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.