From 68801c4813adfff89f78bed12d5dccb51c94fbab Mon Sep 17 00:00:00 2001 From: Timmy Time Date: Sat, 28 Mar 2026 12:53:20 +0000 Subject: [PATCH] docs: sync nexus repo truth and audit legacy matrix (#689) --- CLAUDE.md | 110 +++++++++++++++--------------- LEGACY_MATRIX_AUDIT.md | 141 +++++++++++++++++++++++++++++++++++++++ README.md | 137 ++++++++++++++++++++++--------------- tests/test_repo_truth.py | 35 ++++++++++ 4 files changed, 316 insertions(+), 107 deletions(-) create mode 100644 LEGACY_MATRIX_AUDIT.md create mode 100644 tests/test_repo_truth.py diff --git a/CLAUDE.md b/CLAUDE.md index 0446eef..5769fd4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,77 +2,79 @@ ## Project Overview -The Nexus is a Three.js environment — Timmy's sovereign home in 3D space. It serves as the central hub for all portals to other worlds. Stack: vanilla JS ES modules, Three.js 0.183, no bundler. +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 -## Architecture +## Current Repo Truth -``` -index.html # Entry point: HUD, chat panel, loading screen, live-reload script -style.css # Design system: dark space theme, holographic panels -app.js # Three.js scene, shaders, controls, game loop, WS bridge (~all logic) -portals.json # Portal registry (data-driven) -vision.json # Vision point content (data-driven) -server.js # Optional: proxy server for CORS (commit heatmap API) -``` +Do not describe this repo as a live browser app on `main`. -No build step. Served as static files. Import maps in `index.html` handle Three.js resolution. +Current `main` does not ship the old root frontend files: +- `index.html` +- `app.js` +- `style.css` +- `package.json` -## WebSocket Bridge (v2.0) +A clean checkout of current `main` serves a directory listing if you static-serve the repo root. +That is world-state truth. -The Nexus connects to Timmy's backend via WebSocket for live cognitive state: +The live browser shell people remember exists in legacy form at: +- `/Users/apayne/the-matrix` -- **URL**: `?ws=ws://hermes:8765` query param, or default `ws://localhost:8765` -- **Inbound**: `agent_state`, `agent_move`, `chat_response`, `system_metrics`, `dual_brain`, `heartbeat` -- **Outbound**: `chat_message`, `presence` -- **Graceful degradation**: When WS is offline, agents idle locally, chat shows "OFFLINE" +That legacy app is source material for migration, not a second canonical repo. -## The Hard Rule — Read This First +Timmy_Foundation/the-nexus is the only canonical 3D repo. -**Every PR: net ≤ 10 added lines.** Add 40, remove 30. Can't remove? Import instead. -You MUST plan your cuts BEFORE writing new code. See CONTRIBUTING.md. -Do NOT self-merge. Do NOT submit a PR that violates this. +See: +- `LEGACY_MATRIX_AUDIT.md` +- issues `#684`, `#685`, `#686`, `#687` -## Conventions +## Architecture (current main) -- **ES modules only** — no CommonJS, no bundler -- **Single-file app** — logic lives in `app.js`; don't split without good reason -- **Color palette** — defined in `NEXUS.colors` at top of `app.js` -- **Line budget** — app.js should stay under 1500 lines -- **Conventional commits**: `feat:`, `fix:`, `refactor:`, `test:`, `chore:` -- **Branch naming**: `claude/issue-{N}` (e.g. `claude/issue-5`) -- **One PR at a time** — wait for merge-bot before opening the next +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 -## Validation (merge-bot checks) +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. -The `nexus-merge-bot.sh` validates PRs before auto-merge: +## Hard Rules -1. HTML validation — `index.html` must be valid HTML -2. JS syntax — `node --check app.js` must pass -3. JSON validation — any `.json` files must parse -4. File size budget — JS files must be < 500 KB +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` -**Always run `node --check app.js` before committing.** +## Validation Rule -## PR Rules +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 -- **Net addition limit: ≤ 10 lines.** No exceptions. Plan cuts before writing. -- **Do NOT self-merge.** Submit the PR, a different user merges it. -- Base every PR on latest `main` -- Squash merge only -- Include manual test plan + automated test output in PR body -- Include `Fixes #N` or `Refs #N` in commit message +## Migration Priorities -## Running Locally +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`) -```bash -npx serve . -l 3000 -# open http://localhost:3000 -# To connect to Timmy: http://localhost:3000?ws=ws://hermes:8765 -``` +## Legacy Matrix rescue targets -## Gitea API +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 -``` -Base URL: http://143.198.27.163:3000/api/v1 -Repo: Timmy_Foundation/the-nexus -``` +Preserve the good work. +Do not preserve stale assumptions or fake architecture. diff --git a/LEGACY_MATRIX_AUDIT.md b/LEGACY_MATRIX_AUDIT.md new file mode 100644 index 0000000..54809e4 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 938e33c..a9a791c 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,101 @@ # ◈ The Nexus — Timmy's Sovereign Home -A Three.js environment serving as Timmy's sovereign space — like Dr. Strange's Sanctum Sanctorum, existing outside time. The Nexus is the central hub from which all worlds are accessed through portals. +The Nexus is Timmy's canonical 3D/home-world repo. -## Features +It is meant to become two things at once: +- a local-first training ground for Timmy +- a wizardly visualization surface for the living system -- **Procedural Nebula Skybox** — animated stars, twinkling, layered nebula clouds -- **Batcave Terminal** — 5 holographic display panels arranged in an arc showing: - - Nexus Command (system status, harness state, agent loops) - - Dev Queue (live Gitea issue references) - - Metrics (uptime, commits, CPU/MEM) - - Thought Stream (Timmy's current thoughts) - - Agent Status (all agent states) -- **Morrowind Portal** — glowing torus with animated swirl shader, ready for world connection -- **Admin Chat (Timmy Terminal)** — real-time message interface, ready for Hermes WebSocket -- **Nexus Core** — floating crystalline icosahedron on pedestal -- **Ambient Environment** — crystal formations, floating runestones, energy particles, atmospheric fog -- **WASD + Mouse Navigation** — first-person exploration of the space -- **Post-Processing** — Unreal Bloom + SMAA antialiasing +## Current Truth -## Architecture +As of current `main`, this repo does **not** ship a browser 3D world. +In plain language: current `main` does not ship a browser 3D world. -``` -the-nexus/ -├── index.html # Entry point with HUD overlay, chat panel, loading screen -├── style.css # Nexus design system (dark space theme, holographic panels) -└── app.js # Three.js scene, shaders, controls, game loop -``` +A clean checkout of `Timmy_Foundation/the-nexus` on `main` currently contains: +- Python heartbeat / cognition files under `nexus/` +- `server.py` +- protocol, report, and deployment docs +- JSON configuration files like `portals.json` and `vision.json` + +It does **not** currently contain an active root frontend such as: +- `index.html` +- `app.js` +- `style.css` +- `package.json` + +Serving the repo root today shows a directory listing, not a rendered world. + +## One Canonical 3D Repo + +`Timmy_Foundation/the-nexus` is the only canonical 3D repo. +In plain language: Timmy_Foundation/the-nexus is the only canonical 3D repo. + +The old local browser app at: +- `/Users/apayne/the-matrix` + +is legacy source material, not a second repo to keep evolving in parallel. +Useful work from it must be audited and migrated here. + +See: +- `LEGACY_MATRIX_AUDIT.md` + +## Why this matters + +We do not want to lose real quality work. +We also do not want to keep two drifting 3D repos alive by accident. + +The rule is: +- rescue good work from legacy Matrix +- rebuild inside `the-nexus` +- keep telemetry and durable truth flowing through the Hermes harness +- keep OpenClaw as a sidecar, not the authority + +## Verified historical browser-world snapshot + +The commit the user pointed at: +- `0518a1c3ae3c1d0afeb24dea9772102f5a3d9a66` + +still contains the old root browser files (`index.html`, `app.js`, `style.css`, `package.json`, tests/), so it is a useful in-repo reference point for what existed before the later deletions. + +## Active migration backlog + +- `#684` sync docs to repo truth +- `#685` preserve legacy Matrix quality work before rewrite +- `#686` rebuild browser smoke / visual validation for the real Nexus repo +- `#687` restore a wizardly local-first visual shell from audited Matrix components +- `#672` rebuild the portal stack as Timmy → Reflex → Pilot +- `#673` deterministic Morrowind pilot loop with world-state proof +- `#674` reflex tactical layer and semantic trajectory logging +- `#675` deterministic context compaction for long local sessions + +## What gets preserved from legacy Matrix + +High-value candidates include: +- visitor movement / embodiment +- chat, bark, and presence systems +- transcript logging +- ambient / visual atmosphere systems +- economy / satflow visualizations +- smoke and browser validation discipline + +Those pieces should be carried forward only if they serve the mission and are re-tethered to real local system state. ## Running Locally -```bash -npx serve . -l 3000 -# Open http://localhost:3000 -``` +### Current repo truth -## Roadmap +There is no root browser app on current `main`. +Do not tell people to static-serve the repo root and expect a world. -- [ ] Wire chat to Hermes WebSocket (`/api/world/ws`) -- [ ] Pull live data into terminal panels from Timmy's actual state -- [ ] Portal walk-through interaction to load destination worlds -- [ ] Timmy's avatar (lizard wizard body he designs himself) -- [ ] Connect to AlexanderWhitestone.com as public entry point -- [ ] Integrate existing Replit timmy-tower world code +### What you can run now -## Related +- `python3 server.py` for the local websocket bridge +- Python modules under `nexus/` for heartbeat / cognition work -- **Gitea Issue**: [#1090 — EPIC: Nexus v1](http://143.198.27.163:3000/rockachopa/Timmy-time-dashboard/issues/1090) -- **Live Demo**: Deployed via Perplexity Computer +### Browser world restoration path -## Groq Worker - -The Groq worker is a dedicated worker for the Groq API. It is designed to be used by the Nexus Mind to offload the thinking process to the Groq API. - -### Usage - -To use the Groq worker, you need to set the `GROQ_API_KEY` environment variable. You can then run the `nexus_think.py` script with the `--groq-model` argument: - -```bash -export GROQ_API_KEY="your-api-key" -python -m nexus.nexus_think --groq-model "groq/llama3-8b-8192" -``` - -### Recommendations - -Groq has fast inference, which makes it a good candidate for tasks like PR reviews. You can use the Groq worker to review PRs by a Gitea webhook. +The browser-facing Nexus must be rebuilt deliberately through the migration backlog above, using audited Matrix components and truthful validation. --- -*Part of [The Timmy Foundation](http://143.198.27.163:3000/Timmy_Foundation)* +*One 3D repo. One migration path. No more ghost worlds.* diff --git a/tests/test_repo_truth.py b/tests/test_repo_truth.py new file mode 100644 index 0000000..b56a69a --- /dev/null +++ b/tests/test_repo_truth.py @@ -0,0 +1,35 @@ +from pathlib import Path + + +def test_readme_states_repo_truth_and_single_canonical_3d_repo() -> None: + readme = Path("README.md").read_text() + + assert "current `main` does not ship a browser 3D world" in readme + assert "Timmy_Foundation/the-nexus is the only canonical 3D repo" in readme + assert "/Users/apayne/the-matrix" in readme + assert "npx serve . -l 3000" not in readme + + +def test_claude_doc_matches_current_repo_truth() -> None: + claude = Path("CLAUDE.md").read_text() + + assert "Do not describe this repo as a live browser app on `main`." in claude + assert "Timmy_Foundation/the-nexus is the only canonical 3D repo." in claude + assert "LEGACY_MATRIX_AUDIT.md" in claude + + +def test_legacy_matrix_audit_exists_and_names_rescue_targets() -> None: + audit = Path("LEGACY_MATRIX_AUDIT.md").read_text() + + for term in [ + "agent-defs.js", + "agents.js", + "avatar.js", + "ui.js", + "websocket.js", + "transcript.js", + "ambient.js", + "satflow.js", + "economy.js", + ]: + assert term in audit