the-nexus/README.md

The Nexus Project

Branch Protection & Review Policy

All repositories enforce these rules on the main branch:

Rule	Status	Rationale
Require PR for merge	✅ Enabled	Prevent direct commits
Required approvals	1+	Minimum review threshold
Dismiss stale approvals	✅ Enabled	Re-review after new commits
Require CI to pass	⚠️ Conditional	Only where CI exists
Block force push	✅ Enabled	Protect commit history
Block branch deletion	✅ Enabled	Prevent accidental deletion

Default Reviewers:

• @perplexity (all repositories)
• @Timmy (hermes-agent only)

CI Enforcement:

• hermes-agent: Full CI enforcement
• the-nexus: CI pending runner restoration (#915)
• timmy-home: No CI enforcement
• timmy-config: Limited CI

Implementation Status:

• hermes-agent protection enabled
• the-nexus protection enabled
• timmy-home protection enabled
• timmy-config protection enabled

This policy replaces all previous ad-hoc workflows. Any exceptions require written approval from @Timmy and @perplexity.

---

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
• Hermes is the sole harness — no external gateway dependencies

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.