docs: sync nexus repo truth and audit legacy matrix (#689)
Some checks failed
Deploy Nexus / deploy (push) Failing after 5s
Some checks failed
Deploy Nexus / deploy (push) Failing after 5s
This commit was merged in pull request #689.
This commit is contained in:
137
README.md
137
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.*
|
||||
|
||||
Reference in New Issue
Block a user