Merge branch 'main' into fix/1644

Restores the missing GENOME.md file which provides a comprehensive
map of the Nexus codebase for developers and AI agents.

## Contents
- Overview and key stats
- Architecture diagram
- Frontend systems (3D world, GOFAI, memory, audio)
- Backend services (WebSocket, scripts, tools)
- Data files and configuration
- Testing instructions
- Key patterns (component, WebSocket, portal schema)
- Security summary
- Related repos
- Quick start guide

Closes #1644

GENOME.md

@@ -0,0 +1,234 @@
+# GENOME.md — The Nexus Codebase Architecture Map
+
+**Generated**: 2026-04-20
+**Repository**: Timmy_Foundation/the-nexus
+**Purpose**: Comprehensive map of the Nexus codebase for developers and AI agents.
+
+---
+
+## Overview
+
+The Nexus is Timmy's canonical 3D/world repository — a sovereign AI agent visualization surface and local-first training ground. It combines a Three.js 3D browser world with Python cognition components, WebSocket bridges, and fleet orchestration tools.
+
+**Key Stats**:
+- ~357 source files
+- 201 Python files
+- 23 JavaScript files
+- 107 Markdown docs
+- 24 Shell scripts
+
+---
+
+## Architecture
+
+```
+the-nexus/
+├── app.js                    # Main Three.js 3D world (frontend entry)
+├── index.html                # HTML shell
+├── style.css                 # Global styles
+├── server.py                 # WebSocket gateway
+├── gofai_worker.js           # GOFAI web worker
+├── portals.json              # Portal registry
+├── vision.json               # Vision points config
+├── provenance.json           # File integrity hashes
+│
+├── nexus/                    # Python cognition layer
+│   ├── components/           # Frontend JS modules
+│   ├── mnemosyne/            # Memory system
+│   ├── mempalace/            # Long-term memory
+│   └── symbolic-engine.js    # GOFAI rules
+│
+├── scripts/                  # Operational scripts
+├── bin/                      # CLI tools
+├── tests/                    # Test suite
+├── docs/                     # Documentation
+└── config/                   # Configuration files
+```
+
+---
+
+## Frontend (Browser World)
+
+### Entry Points
+| File | Purpose |
+|------|---------|
+| `index.html` | HTML shell, HUD layout |
+| `app.js` | Main Three.js app (~141K lines) |
+| `style.css` | All styles (~61K) |
+| `gofai_worker.js` | Off-thread GOFAI reasoning |
+
+### Core Systems
+| System | File | Description |
+|--------|------|-------------|
+| 3D World | `app.js` | Three.js scene, camera, rendering |
+| GOFAI | `app.js` | Symbolic rules, blackboard, planner |
+| Memory | `nexus/components/spatial-memory.js` | 3D memory crystals |
+| Audio | `nexus/components/spatial-audio.js` | Spatial sound system |
+| Portals | `portals.json` | External service links |
+| Chat | `app.js` | Chat panel and messaging |
+| HUD | `app.js` + `style.css` | Heads-up display |
+
+### Components (`nexus/components/`)
+| Component | Purpose |
+|-----------|---------|
+| `spatial-memory.js` | 3D memory crystal visualization |
+| `spatial-audio.js` | Spatial sound for memories |
+| `memory-birth.js` | Memory creation animation |
+| `memory-pulse.js` | BFS pulse wave on click |
+| `memory-inspect.js` | Memory detail panel |
+| `memory-connections.js` | Connection graph |
+| `memory-particles.js` | Particle effects |
+| `memory-optimizer.js` | Memory cleanup |
+| `session-rooms.js` | Evennia room snapshots |
+| `timeline-scrubber.js` | Time navigation |
+| `resonance-visualizer.js` | Pattern visualization |
+| `portal-health-check.js` | Portal status monitoring |
+| `spatial-chat.js` | 3D audio chat notifications |
+
+---
+
+## Backend (Python)
+
+### Core Services
+| File | Purpose |
+|------|---------|
+| `server.py` | WebSocket gateway for real-time comms |
+| `multi_user_bridge.py` | Multi-user MUD bridge |
+| `gitea_api/` | Gitea API helpers |
+
+### Scripts (`scripts/`)
+| Script | Purpose |
+|--------|---------|
+| `cleanup-duplicate-prs.sh` | Close duplicate PRs |
+| `check-existing-prs.sh` | Pre-flight PR check |
+| `pr_backlog_analyzer.py` | PR backlog analysis |
+| `audit_mempalace_privacy.py` | Privacy audit |
+| `provision-runner.sh` | Runner setup |
+| `runner_health_probe.sh` | Health monitoring |
+
+### Bin Tools (`bin/`)
+| Tool | Purpose |
+|------|---------|
+| `enforce_branch_protection.py` | Branch protection enforcement |
+| `check_duplicate_milestones.py` | Milestone cleanup |
+| `generate_provenance.py` | Provenance hash generation |
+
+---
+
+## Data Files
+
+| File | Format | Purpose |
+|------|--------|---------|
+| `portals.json` | JSON | Portal registry (8 portals) |
+| `vision.json` | JSON | Vision points |
+| `world_state.json` | JSON | World state snapshot |
+| `provenance.json` | JSON | File integrity hashes |
+| `manifest.json` | JSON | PWA manifest |
+
+---
+
+## Configuration
+
+| File | Purpose |
+|------|---------|
+| `.gitea/branch-protection/` | Branch protection rules |
+| `.github/workflows/` | CI/CD workflows |
+| `config/` | Runtime configuration |
+| `pytest.ini` | Test configuration |
+
+---
+
+## Testing
+
+| Directory | Coverage |
+|-----------|----------|
+| `tests/` | Unit and integration tests |
+| `tests/test_provenance.py` | File integrity tests |
+| `tests/test_spatial_search.js` | Spatial search tests |
+
+Run tests:
+```bash
+python3 -m pytest tests/ -v
+node --test tests/*.js
+```
+
+---
+
+## Key Patterns
+
+### Component Pattern
+```javascript
+const ComponentName = (() => {
+  let _state = null;
+  
+  function init(config) { ... }
+  function update(delta) { ... }
+  
+  return { init, update };
+})();
+
+export { ComponentName };
+```
+
+### WebSocket Pattern
+```python
+async def handler(websocket):
+    async for message in websocket:
+        # Process and broadcast
+        pass
+```
+
+### Portal Schema
+```json
+{
+  "id": "portal-id",
+  "name": "Display Name",
+  "portal_type": "game-world",
+  "destination": { "url": "...", "type": "harness" }
+}
+```
+
+---
+
+## Security
+
+- WebSocket gateway binds to `127.0.0.1` by default
+- Optional token authentication via `NEXUS_WS_TOKEN`
+- Rate limiting on connections and messages
+- Branch protection on `main`
+- Provenance hash verification
+
+See `SECURITY.md` for full details.
+
+---
+
+## Related Repos
+
+| Repo | Relationship |
+|------|--------------|
+| `timmy-config` | Configuration and fleet management |
+| `hermes-agent` | Agent runtime |
+| `timmy-home` | SOUL.md and core docs |
+| `the-door` | Crisis detection system |
+
+---
+
+## Quick Start
+
+```bash
+# Clone
+git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus.git
+
+# Run WebSocket gateway
+python3 server.py
+
+# Open browser world
+open index.html
+
+# Run tests
+python3 -m pytest tests/
+```
+
+---
+
+*This GENOME.md is auto-maintained. Update when adding major new systems.*

js/spatial-search.js

@@ -1,317 +0,0 @@
-// ═══════════════════════════════════════════════════════════════
-// SPATIAL SEARCH — Find nearest user/object by name
-// ═══════════════════════════════════════════════════════════════
-//
-// Search for users/objects by name with distance and direction.
-// Provides autocomplete, pathfinding arrow, and keyboard shortcuts.
-//
-// Usage:
-//   const search = new SpatialSearch({ maxDistance: 1000 });
-//   search.registerEntity('id', { name, type, position });
-//   const results = search.searchEntities('query');
-// ═══════════════════════════════════════════════════════════════
-
-class SpatialSearch {
-  constructor(options = {}) {
-    this.maxDistance = options.maxDistance || 1000;
-    this.onResultSelect = options.onResultSelect || null;
-    this.entities = new Map();
-    this.selectedIndex = -1;
-    this.results = [];
-    this.isOpen = false;
-    this._initUI();
-    this._bindKeys();
-  }
-
-  // ─── Entity Management ─────────────────────────────────
-  
-  registerEntity(id, { name, type = 'object', position }) {
-    this.entities.set(id, {
-      id,
-      name: name.toLowerCase(),
-      displayName: name,
-      type,
-      position: { ...position }
-    });
-  }
-
-  unregisterEntity(id) {
-    this.entities.delete(id);
-  }
-
-  updateEntityPosition(id, position) {
-    const entity = this.entities.get(id);
-    if (entity) {
-      entity.position = { ...position };
-    }
-  }
-
-  // ─── Search ────────────────────────────────────────────
-
-  searchEntities(query, cameraPosition = null) {
-    if (!query || query.length < 1) {
-      this.results = [];
-      this._renderResults();
-      return [];
-    }
-
-    const q = query.toLowerCase();
-    const results = [];
-
-    for (const [id, entity] of this.entities) {
-      if (!entity.name.includes(q)) continue;
-
-      let distance = 0;
-      let direction = '';
-
-      if (cameraPosition) {
-        distance = this._calculateDistance(cameraPosition, entity.position);
-        if (distance > this.maxDistance) continue;
-        direction = this._calculateDirection(cameraPosition, entity.position);
-      }
-
-      results.push({
-        id,
-        name: entity.displayName,
-        type: entity.type,
-        distance: Math.round(distance * 10) / 10,
-        direction,
-        position: entity.position
-      });
-    }
-
-    // Sort by distance
-    results.sort((a, b) => a.distance - b.distance);
-    
-    this.results = results.slice(0, 10); // Limit to 10 results
-    this.selectedIndex = this.results.length > 0 ? 0 : -1;
-    this._renderResults();
-    
-    return this.results;
-  }
-
-  selectResult(index) {
-    if (index < 0 || index >= this.results.length) return;
-    
-    this.selectedIndex = index;
-    this._renderResults();
-    
-    const result = this.results[index];
-    if (result && this.onResultSelect) {
-      this.onResultSelect(result);
-    }
-    
-    this.close();
-  }
-
-  // ─── Distance & Direction ──────────────────────────────
-
-  _calculateDistance(from, to) {
-    const dx = to.x - from.x;
-    const dy = to.y - from.y;
-    const dz = to.z - from.z;
-    return Math.sqrt(dx * dx + dy * dy + dz * dz);
-  }
-
-  _calculateDirection(from, to) {
-    const dx = to.x - from.x;
-    const dz = to.z - from.z;
-    const angle = Math.atan2(dx, dz) * (180 / Math.PI);
-    
-    // Convert to compass direction
-    if (angle >= -22.5 && angle < 22.5) return 'N';
-    if (angle >= 22.5 && angle < 67.5) return 'NE';
-    if (angle >= 67.5 && angle < 112.5) return 'E';
-    if (angle >= 112.5 && angle < 157.5) return 'SE';
-    if (angle >= 157.5 || angle < -157.5) return 'S';
-    if (angle >= -157.5 && angle < -112.5) return 'SW';
-    if (angle >= -112.5 && angle < -67.5) return 'W';
-    if (angle >= -67.5 && angle < -22.5) return 'NW';
-    return 'N';
-  }
-
-  // ─── UI ────────────────────────────────────────────────
-
-  _initUI() {
-    // Search container
-    this.container = document.createElement('div');
-    this.container.id = 'spatial-search';
-    this.container.className = 'spatial-search';
-    this.container.style.display = 'none';
-    
-    // Input
-    this.input = document.createElement('input');
-    this.input.type = 'text';
-    this.input.className = 'spatial-search-input';
-    this.input.placeholder = 'Search by name... (Ctrl+F)';
-    this.input.addEventListener('input', () => this._onInput());
-    this.input.addEventListener('keydown', (e) => this._onKeyDown(e));
-    
-    // Results dropdown
-    this.dropdown = document.createElement('div');
-    this.dropdown.className = 'spatial-search-dropdown';
-    
-    // Path arrow
-    this.arrow = document.createElement('div');
-    this.arrow.className = 'spatial-search-arrow';
-    this.arrow.style.display = 'none';
-    this.arrow.innerHTML = '<span class="arrow-icon">➤</span><span class="arrow-info"></span>';
-    
-    this.container.appendChild(this.input);
-    this.container.appendChild(this.dropdown);
-    
-    document.body.appendChild(this.container);
-    document.body.appendChild(this.arrow);
-  }
-
-  _bindKeys() {
-    document.addEventListener('keydown', (e) => {
-      // Ctrl+F or Cmd+F to toggle
-      if ((e.ctrlKey || e.metaKey) && e.key === 'f') {
-        e.preventDefault();
-        this.toggle();
-        return;
-      }
-      
-      // Escape to close
-      if (e.key === 'Escape' && this.isOpen) {
-        e.preventDefault();
-        this.close();
-        return;
-      }
-    });
-  }
-
-  _onInput() {
-    const query = this.input.value;
-    // Get camera position if available
-    const cameraPos = window.camera ? {
-      x: window.camera.position.x,
-      y: window.camera.position.y,
-      z: window.camera.position.z
-    } : null;
-    
-    this.searchEntities(query, cameraPos);
-  }
-
-  _onKeyDown(e) {
-    if (!this.isOpen || this.results.length === 0) return;
-    
-    switch (e.key) {
-      case 'ArrowDown':
-        e.preventDefault();
-        this.selectedIndex = Math.min(this.selectedIndex + 1, this.results.length - 1);
-        this._renderResults();
-        break;
-      case 'ArrowUp':
-        e.preventDefault();
-        this.selectedIndex = Math.max(this.selectedIndex - 1, 0);
-        this._renderResults();
-        break;
-      case 'Enter':
-        e.preventDefault();
-        if (this.selectedIndex >= 0) {
-          this.selectResult(this.selectedIndex);
-        }
-        break;
-    }
-  }
-
-  _renderResults() {
-    this.dropdown.innerHTML = '';
-    
-    if (this.results.length === 0) {
-      if (this.input.value) {
-        this.dropdown.innerHTML = '<div class="spatial-search-empty">No results found</div>';
-      }
-      return;
-    }
-    
-    this.results.forEach((result, index) => {
-      const item = document.createElement('div');
-      item.className = `spatial-search-item ${index === this.selectedIndex ? 'selected' : ''}`;
-      item.innerHTML = `
-        <span class="item-name">${this._escapeHtml(result.name)}</span>
-        <span class="item-type">${result.type}</span>
-        <span class="item-distance">${result.distance}m ${result.direction}</span>
-      `;
-      item.addEventListener('click', () => this.selectResult(index));
-      this.dropdown.appendChild(item);
-    });
-  }
-
-  _updateArrow(result) {
-    if (!result) {
-      this.arrow.style.display = 'none';
-      return;
-    }
-    
-    this.arrow.style.display = 'flex';
-    const info = this.arrow.querySelector('.arrow-info');
-    if (info) {
-      info.textContent = `${result.name} — ${result.distance}m ${result.direction}`;
-    }
-    
-    // Rotate arrow based on direction
-    const rotations = {
-      'N': 0, 'NE': 45, 'E': 90, 'SE': 135,
-      'S': 180, 'SW': 225, 'W': 270, 'NW': 315
-    };
-    const arrowIcon = this.arrow.querySelector('.arrow-icon');
-    if (arrowIcon) {
-      arrowIcon.style.transform = `rotate(${rotations[result.direction] || 0}deg)`;
-    }
-  }
-
-  _escapeHtml(str) {
-    const div = document.createElement('div');
-    div.textContent = str;
-    return div.innerHTML;
-  }
-
-  // ─── Public API ────────────────────────────────────────
-
-  open() {
-    this.isOpen = true;
-    this.container.style.display = 'flex';
-    this.input.focus();
-    this.input.value = '';
-    this.results = [];
-    this._renderResults();
-  }
-
-  close() {
-    this.isOpen = false;
-    this.container.style.display = 'none';
-    this.input.blur();
-    this.selectedIndex = -1;
-    this._updateArrow(null);
-  }
-
-  toggle() {
-    if (this.isOpen) {
-      this.close();
-    } else {
-      this.open();
-    }
-  }
-
-  getStatus() {
-    return {
-      entityCount: this.entities.size,
-      isOpen: this.isOpen,
-      resultCount: this.results.length,
-      selectedIndex: this.selectedIndex
-    };
-  }
-}
-
-// Export for module systems
-if (typeof module !== 'undefined' && module.exports) {
-  module.exports = SpatialSearch;
-}
-
-// Make available globally
-if (typeof window !== 'undefined') {
-  window.SpatialSearch = SpatialSearch;
-}

tests/test_spatial_search.js

@@ -1,99 +0,0 @@
-// Test suite for SpatialSearch module
-// Run: node --test tests/test_spatial_search.js
-
-const { describe, it, beforeEach } = require('node:test');
-const assert = require('node:assert');
-
-// Mock DOM for Node.js environment
-global.document = {
-  createElement: (tag) => ({
-    className: '',
-    style: {},
-    innerHTML: '',
-    textContent: '',
-    addEventListener: () => {},
-    appendChild: () => {},
-    querySelector: () => ({ style: {}, textContent: '' })
-  }),
-  body: { appendChild: () => {} },
-  addEventListener: () => {}
-};
-global.window = { camera: null };
-
-// Load module
-const SpatialSearch = require('../js/spatial-search.js');
-
-describe('SpatialSearch', () => {
-  let search;
-
-  beforeEach(() => {
-    search = new SpatialSearch({ maxDistance: 1000 });
-  });
-
-  it('loads correctly', () => {
-    assert.ok(SpatialSearch);
-  });
-
-  it('can be instantiated', () => {
-    assert.ok(search instanceof SpatialSearch);
-  });
-
-  it('can register entities', () => {
-    search.registerEntity('user1', {
-      name: 'Alice',
-      type: 'user',
-      position: { x: 10, y: 0, z: 5 }
-    });
-    const status = search.getStatus();
-    assert.strictEqual(status.entityCount, 1);
-  });
-
-  it('can unregister entities', () => {
-    search.registerEntity('user1', { name: 'Alice', type: 'user', position: { x: 0, y: 0, z: 0 } });
-    search.unregisterEntity('user1');
-    assert.strictEqual(search.getStatus().entityCount, 0);
-  });
-
-  it('can update entity position', () => {
-    search.registerEntity('user1', { name: 'Alice', type: 'user', position: { x: 0, y: 0, z: 0 } });
-    search.updateEntityPosition('user1', { x: 10, y: 0, z: 10 });
-    // Verify by searching with camera position
-    const results = search.searchEntities('alice', { x: 0, y: 0, z: 0 });
-    assert.strictEqual(results.length, 1);
-    assert.ok(results[0].distance > 0);
-  });
-
-  it('calculates distance correctly', () => {
-    const from = { x: 0, y: 0, z: 0 };
-    const to = { x: 3, y: 0, z: 4 };
-    const distance = search._calculateDistance(from, to);
-    assert.strictEqual(distance, 5); // 3-4-5 triangle
-  });
-
-  it('calculates direction correctly', () => {
-    const from = { x: 0, y: 0, z: 0 };
-    assert.strictEqual(search._calculateDirection(from, { x: 0, y: 0, z: 10 }), 'N');
-    assert.strictEqual(search._calculateDirection(from, { x: 10, y: 0, z: 0 }), 'E');
-    assert.strictEqual(search._calculateDirection(from, { x: 0, y: 0, z: -10 }), 'S');
-    assert.strictEqual(search._calculateDirection(from, { x: -10, y: 0, z: 0 }), 'W');
-  });
-
-  it('searches entities correctly', () => {
-    search.registerEntity('1', { name: 'Alice', type: 'user', position: { x: 5, y: 0, z: 0 } });
-    search.registerEntity('2', { name: 'Bob', type: 'user', position: { x: 10, y: 0, z: 0 } });
-    search.registerEntity('3', { name: 'Alice Shop', type: 'object', position: { x: 20, y: 0, z: 0 } });
-
-    const results = search.searchEntities('ali', { x: 0, y: 0, z: 0 });
-    assert.strictEqual(results.length, 2);
-    assert.strictEqual(results[0].name, 'Alice'); // Closer
-    assert.strictEqual(results[1].name, 'Alice Shop');
-  });
-
-  it('gets status', () => {
-    search.registerEntity('1', { name: 'Test', type: 'object', position: { x: 0, y: 0, z: 0 } });
-    const status = search.getStatus();
-    assert.strictEqual(status.entityCount, 1);
-    assert.strictEqual(status.isOpen, false);
-    assert.strictEqual(status.resultCount, 0);
-  });
-});