the-nexus/README.md

# The Nexus

Timmy's canonical 3D home-world — a local-first training ground and wizardly visualization surface for the living system.

## Current Truth

Current `main` does **not** ship a browser 3D world. A clean checkout contains:

- Python heartbeat / cognition files under `nexus/`
- `server.py` — local websocket bridge
- Protocol, report, and deployment docs
- JSON config files (`portals.json`, `vision.json`)

It does **not** currently contain an active root frontend (`index.html`, `app.js`, `style.css`).

## One Canonical 3D Repo

`Timmy_Foundation/the-nexus` is the **only** canonical 3D repo.

The legacy browser app at `/Users/apayne/the-matrix` is source material for migration, 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:
- Rescue good work from legacy Matrix
- Rebuild inside `the-nexus`
- Keep telemetry and durable truth flowing through the Hermes harness

## Active Migration Backlog

| Issue | Work |
|-------|------|
| #684 | Sync docs to repo truth |
| #685 | Preserve legacy Matrix quality work |
| #686 | Rebuild browser smoke / visual validation |
| #687 | Restore wizardly local-first visual shell |
| #672 | Rebuild portal stack (Timmy → Reflex → Pilot) |
| #673 | Deterministic Morrowind pilot loop |
| #674 | Reflex tactical layer + trajectory logging |
| #675 | Deterministic context compaction |

## Running Locally

There is no root browser app on current `main`. Do not static-serve the repo root expecting a world.

You can run:
- `python3 server.py` — local websocket bridge
- Python modules under `nexus/` — heartbeat / cognition work

The browser-facing Nexus must be rebuilt through the migration backlog using audited Matrix components.

## Branch Protection & Review Policy

**All repositories enforce these rules on `main`:**

| Rule | Status |
|------|--------|
| Require Pull Request for merge | ✅ Enabled |
| Require 1 approval before merge | ✅ Enabled |
| Dismiss stale approvals on new commits | ✅ Enabled |
| Require CI to pass (where CI exists) | ⚠️ Conditional |
| Block force pushes to `main` | ✅ Enabled |
| Block deletion of `main` branch | ✅ Enabled |

**Default reviewers:**
- `@perplexity` — all repositories (QA gate)
- `@Timmy` — `hermes-agent` only (owner gate)

**CI status:**
- `hermes-agent`: ✅ Active
- `the-nexus`: ⚠️ Runner pending (#915)
- `timmy-home`: ❌ No CI
- `timmy-config`: ❌ Limited CI

See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.

---

*One 3D repo. One migration path. No more ghost worlds.*