◈ 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.

Branch Protection Policy

All repositories must enforce the following branch protection rules on the main branch:

Rule	Status	Description
Require PR for merge	✅ Enabled	No direct pushes to main
Required approvals	✅ 1+	At least one reviewer must approve
Dismiss stale approvals	✅ Enabled	Re-review after new commits
Require CI to pass	⚠️ Conditional	Enabled where CI exists
Block force push	✅ Enabled	Protect commit history
Block branch deletion	✅ Enabled	Prevent accidental main deletion

Repository-Specific Settings

• hermes-agent

  • ✅ All branch protection rules enabled
  • ✅ CI/CD pipeline active
  • 🧑‍🤝 Required reviewers: @Timmy (owner), @perplexity (QA)

• the-nexus

  • ✅ All branch protection rules enabled
  • ⚠️ CI/CD pipeline pending (#915)
  • 🧑‍🤝 Required reviewers: @perplexity (QA)

• timmy-home

  • ✅ PR + 1 approval required
  • ❌ No CI/CD pipeline
  • 🧑‍🤝 Required reviewers: @perplexity (QA)

• timmy-config

  • ✅ PR + 1 approval required
  • ⚠️ Limited CI/CD
  • 🧑‍🤝 Required reviewers: @perplexity (QA)

Default Reviewer Assignment

Gitea CODEOWNERS-style configuration:

* @perplexity # QA gate
:hermes-agent/* @Timmy # Owner gate

Acceptance Criteria

• ✅ Branch protection enabled on all repos
• ✅ @perplexity set as default reviewer
• ✅ Policy documented here
• ⚠️ CI/CD status tracked in #915

Implementation Status

Repository	Branch Protection	CI/CD	Reviewer
hermes-agent	✅ Enabled	✅ Active	@Timmy, @perplexity
the-nexus	✅ Enabled	⚠️ Pending	@perplexity
timmy-home	✅ Enabled	❌ None	@perplexity
timmy-config	✅ Enabled	⚠️ Limited	@perplexity

This document is maintained as part of our QA Policy and should be updated when repository configurations change.

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.