docs: sync nexus repo truth and audit legacy matrix (#689)

LEGACY_MATRIX_AUDIT.md

@@ -0,0 +1,141 @@
+# 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.