845e2f2ced
Root cause: duplicate agents wrote GOFAI code to public/nexus/app.js (wrong path) instead of root app.js. The public/nexus/ files were corrupt duplicates that got overwritten and eventually deleted, creating the illusion of disappearing code. The classical AI code is fully present in root app.js — all 13 classes verified: SymbolicEngine, AgentFSM, KnowledgeGraph, Blackboard, SymbolicPlanner, HTNPlanner, CaseBasedReasoner, NeuroSymbolicBridge, MetaReasoningLayer, AdaptiveCalibrator, PSELayer, plus A* search and bitmask fact indexing. Prevention: - Added public/nexus/ to .gitignore - Added canonical file path documentation to CLAUDE.md - Filed investigation report (INVESTIGATION_ISSUE_1145.md)
93 lines
3.3 KiB
Markdown
93 lines
3.3 KiB
Markdown
# CLAUDE.md — The Nexus (Timmy_Foundation/the-nexus)
|
|
|
|
## Project Overview
|
|
|
|
The Nexus is Timmy's canonical 3D/home-world repo.
|
|
Its intended role is:
|
|
- local-first training ground for Timmy
|
|
- wizardly visualization surface for the system
|
|
|
|
## Current Repo Truth
|
|
|
|
Do not describe this repo as a live browser app on `main`.
|
|
|
|
Current `main` does not ship the old root frontend files:
|
|
- `index.html`
|
|
- `app.js`
|
|
- `style.css`
|
|
- `package.json`
|
|
|
|
A clean checkout of current `main` serves a directory listing if you static-serve the repo root.
|
|
That is world-state truth.
|
|
|
|
The live browser shell people remember exists in legacy form at:
|
|
- `/Users/apayne/the-matrix`
|
|
|
|
That legacy app is source material for migration, not a second canonical repo.
|
|
|
|
Timmy_Foundation/the-nexus is the only canonical 3D repo.
|
|
|
|
See:
|
|
- `LEGACY_MATRIX_AUDIT.md`
|
|
- issues `#684`, `#685`, `#686`, `#687`
|
|
|
|
## Architecture (current main)
|
|
|
|
Current repo contents are centered on:
|
|
- `nexus/` — Python cognition / heartbeat components
|
|
- `server.py` — local websocket bridge
|
|
- `portals.json`, `vision.json` — data/config artifacts
|
|
- deployment/docs files
|
|
|
|
Do not tell contributors to run Vite or edit a nonexistent root frontend on current `main`.
|
|
If browser/UI work is being restored, it must happen through the migration backlog and land back here.
|
|
|
|
## Canonical File Paths
|
|
|
|
**Frontend code lives at repo ROOT, NOT in `public/nexus/`:**
|
|
- `app.js` — main Three.js app (GOFAI, 3D world, all frontend logic)
|
|
- `index.html` — main HTML shell
|
|
- `style.css` — styles
|
|
- `server.py` — websocket bridge
|
|
- `gofai_worker.js` — web worker for off-thread reasoning
|
|
|
|
**DO NOT write to `public/nexus/`** — this path is gitignored. Agents historically wrote here by mistake, creating corrupt duplicates. See issue #1145 and `INVESTIGATION_ISSUE_1145.md`.
|
|
|
|
## Hard Rules
|
|
|
|
1. One canonical 3D repo only: `Timmy_Foundation/the-nexus`
|
|
2. No parallel evolution of `/Users/apayne/the-matrix` as if it were the product
|
|
3. Rescue useful legacy Matrix work by auditing and migrating it here
|
|
4. Telemetry and durable truth flow through Hermes harness
|
|
5. OpenClaw remains a sidecar, not the governing authority
|
|
6. Before claiming visual validation, prove the app being viewed actually comes from current `the-nexus`
|
|
7. **NEVER write frontend files to `public/nexus/`** — use repo root paths listed above
|
|
|
|
## Validation Rule
|
|
|
|
If you are asked to visually validate Nexus:
|
|
- prove the tested app comes from a clean checkout/worktree of `Timmy_Foundation/the-nexus`
|
|
- if current `main` only serves a directory listing or otherwise lacks the browser world, stop calling it visually validated
|
|
- pivot to migration audit and issue triage instead of pretending the world still exists
|
|
|
|
## Migration Priorities
|
|
|
|
1. `#684` — docs truth
|
|
2. `#685` — legacy Matrix preservation audit
|
|
3. `#686` — browser smoke / visual validation rebuild
|
|
4. `#687` — restore wizardly local-first visual shell
|
|
5. then continue portal/gameplay work (`#672`, `#673`, `#674`, `#675`)
|
|
|
|
## Legacy Matrix rescue targets
|
|
|
|
The old Matrix contains real quality work worth auditing:
|
|
- visitor movement and embodiment
|
|
- agent presence / bark / chat systems
|
|
- transcript logging
|
|
- ambient world systems
|
|
- satflow / economy visualization
|
|
- browser smoke tests and production build discipline
|
|
|
|
Preserve the good work.
|
|
Do not preserve stale assumptions or fake architecture.
|