the-nexus/README.md

◈ The Nexus — Timmy's Sovereign Home

The Nexus is Timmy's canonical 3D/home-world repo.

It is meant to become two things at once:

• a local-first training ground for Timmy
• a wizardly visualization surface for the living system

Current Truth

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.

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

Current repo truth

There is no root browser app on current main. Do not tell people to static-serve the repo root and expect a world.

What you can run now

• python3 server.py for the local websocket bridge
• Python modules under nexus/ for heartbeat / cognition work

Browser world restoration path

The browser-facing Nexus must be rebuilt deliberately through the migration backlog above, using audited Matrix components and truthful validation.

---

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

Branch Protection Policy

All repositories enforce the following branch protection rules for the main branch:

1. Require Pull Request before merge - All changes must go through PR process
2. Require 1 approving review - At least one reviewer must approve before merge
3. Dismiss stale approvals - Approvals are automatically dismissed on new commits
4. Require status checks to pass - CI/CD must pass before merge (where applicable)
5. Block force pushes - Prevents rewriting of commit history
6. Block branch deletion - Prevents accidental deletion of main branch

Default Reviewers:

• @perplexity - All repositories
• @Timmy - nexus repository
• @Rockachopa - timmy-home and timmy-config

CI/CD Requirements:

• hermes-agent: Full CI enforcement
• the-nexus: CI disabled (runner issue #915)
• timmy-home: No CI
• timmy-config: No CI

For CI/CD status, see the health dashboard