feat(#1339): Deploy Nexus to proper URL for preview

ES module imports fail via file:// or raw Forge URLs (CORS +
missing Content-Type headers). boot.js detects this and warns users.

Three deployment options:
  - ./preview.sh — local Python server, correct MIME types
  - docker compose up nexus-preview — nginx on :8080 + WS proxy
  - Push to main — GitHub Pages auto-deploy

Fixes #1339

.gitea/workflows/deploy.yml

@@ -12,6 +12,14 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Preflight secrets check
+        env:
+          H: ${{ secrets.DEPLOY_HOST }}
+          U: ${{ secrets.DEPLOY_USER }}
+          K: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          [ -z "$H" ] || [ -z "$U" ] || [ -z "$K" ] && echo "ERROR: Missing deploy secret. Configure DEPLOY_HOST/DEPLOY_USER/DEPLOY_SSH_KEY in Settings → Actions → Secrets (see issue #1363)" && exit 1
+
       - name: Deploy to host via SSH
         uses: appleboy/ssh-action@v1.0.3
         with:

.gitea/workflows/staging_gate.yml

@@ -13,7 +13,7 @@ jobs:
 
       - name: Verify staging label on merge PR
         env:
-          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN || secrets.MERGE_TOKEN }}
           GITEA_URL: ${{ vars.GITEA_URL || 'https://forge.alexanderwhitestone.com' }}
           GITEA_REPO: Timmy_Foundation/the-nexus
         run: |

.github/workflows/pages.yml

@@ -0,0 +1,35 @@
+name: Deploy Nexus Preview to Pages
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - name: Prepare static assets
+        run: |
+          mkdir -p _site
+          cp index.html app.js style.css boot.js gofai_worker.js _site/
+          cp service-worker.js manifest.json robots.txt help.html _site/
+          cp portals.json vision.json _site/
+          cp -r nexus/ _site/nexus/
+          cp -r icons/ _site/icons/ 2>/dev/null || true
+          cp -r assets/ _site/assets/ 2>/dev/null || true
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site'
+      - id: deployment
+        uses: actions/deploy-pages@v4

Dockerfile.preview

@@ -0,0 +1,9 @@
+FROM nginx:alpine
+RUN rm /etc/nginx/conf.d/default.conf
+COPY preview/nginx.conf /etc/nginx/conf.d/default.conf
+COPY index.html app.js style.css boot.js gofai_worker.js /usr/share/nginx/html/
+COPY service-worker.js manifest.json robots.txt help.html portals.json vision.json /usr/share/nginx/html/
+COPY nexus/ /usr/share/nginx/html/nexus/
+COPY icons/ /usr/share/nginx/html/icons/
+COPY assets/ /usr/share/nginx/html/assets/
+EXPOSE 8080

PREVIEW.md

@@ -0,0 +1,26 @@
+# Nexus Preview
+
+ES module imports fail via `file://` or raw Forge URLs. `boot.js` already warns: _"Serve over HTTP to initialize Three.js."_
+
+## Quick Start
+
+```bash
+./preview.sh              # http://localhost:8080 (Python, no deps)
+./preview.sh docker       # http://localhost:8080 (nginx + WS proxy)
+docker compose up -d nexus-preview nexus-backend  # full stack
+```
+
+## Options
+
+| Method | Command | Port |
+|--------|---------|------|
+| Local Python | `./preview.sh` | 8080 |
+| Docker nginx | `docker compose up nexus-preview` | 8080 |
+| GitHub Pages | push to main | auto |
+
+## Files
+
+- `Dockerfile.preview` — nginx container
+- `preview/nginx.conf` — MIME types + WebSocket proxy
+- `preview.sh` — Python preview server
+- `.github/workflows/pages.yml` — GitHub Pages CI/CD

README.md

@@ -1,6 +1,6 @@
-# Branch Protection & Review Policy
+# The Nexus Project
 
-## Enforced Rules for All Repositories
+## Branch Protection & Review Policy
 
 **All repositories enforce these rules on the `main` branch:**
 
@@ -9,7 +9,7 @@
 | 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 | <EFBFBD> Conditional | Only where CI exists |
+| Require CI to pass | ⚠️ Conditional | Only where CI exists |
 | Block force push | ✅ Enabled | Protect commit history |
 | Block branch deletion | ✅ Enabled | Prevent accidental deletion |
 
@@ -31,105 +31,7 @@
 
 > This policy replaces all previous ad-hoc workflows. Any exceptions require written approval from @Timmy and @perplexity.
 
-| 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 |
-
-### Repository-Specific Configuration
-
-**1. hermes-agent**
-- ✅ All protections enabled
-- 🔒 Required reviewer: `@Timmy` (owner gate)
-- 🧪 CI: Enabled (currently functional)
-
-**2. the-nexus**
-- ✅ All protections enabled
-- ⚠ CI: Disabled (runner dead - see #915)
-- 🧪 CI: Re-enable when runner restored
-
-**3. timmy-home**
-- ✅ PR + 1 approval required
-- 🧪 CI: No CI configured
-
-**4. timmy-config**
-- ✅ PR + 1 approval required
-- 🧪 CI: Limited CI
-
-### Default Reviewer Assignment
-
-All repositories must:
-- 🧑‍ Default reviewer: `@perplexity` (QA gate)
-- 🧑 Required reviewer: `@Timmy` for `hermes-agent/` only
-
-### Acceptance Criteria
-
-- [ ] All four repositories have protection rules applied
-- [ ] Default reviewers configured per matrix above
-- [ ] This policy documented in all repositories
-- [ ] Policy enforced for 72 hours with no unreviewed merges
-
-> This policy replaces all previous ad-hoc workflows. Any exceptions require written approval from @Timmy and @perplexity.
-- ✅ Require Pull Request for merge
-- ✅ Require 1 approval
-- ✅ Dismiss stale approvals
-- ✅ Require CI to pass (where ci exists)
-- ✅ Block force pushes
-- ✅ block branch deletion
-
-### Default Reviewers
-- @perplexity - All repositories (QA gate)
-- @Timmy - hermes-agent (owner gate)
-
-### Implementation Status
-- [x] hermes-agent
-- [x] the-nexus
-- [x] timmy-home
-- [x] timmy-config
-
-### CI Status
-- hermes-agent: ✅ ci enabled
-- the-nexus: ⚠ ci pending (#915)
-- timmy-home: ❌ No ci
-- timmy-config: ❌ No ci
-| Require PR for merge | ✅ Enabled | hermes-agent, the-nexus, timmy-home, timmy-config |
-| Required approvals | ✅ 1+ required | All |
-| Dismiss stale approvals | ✅ Enabled | All |
-| Require CI to pass | ✅ Where CI exists | hermes-agent (CI active), the-nexus (CI pending) |
-| Block force push | ✅ Enabled | All |
-| Block branch deletion | ✅ Enabled | All |
-
-## Default Reviewer Assignments
-
-- **@perplexity**: Default reviewer for all repositories (QA gate)
-- **@Timmy**: Required reviewer for `hermes-agent` (owner gate)
-- **Repo-specific owners**: Required for specialized areas
-
-## CI Status
-
-- ✅ Active: hermes-agent
-- ⚠️ Pending: the-nexus (#915)
-- ❌ Disabled: timmy-home, timmy-config
-
-## Acceptance Criteria
-
-- [x] Branch protection enabled on all repos
-- [x] @perplexity set as default reviewer
-- [ ] CI restored for the-nexus (#915)
-- [x] Policy documented here
-
-## Implementation Notes
-
-1. All direct pushes to `main` are now blocked
-2. Merges require at least 1 approval
-3. CI failures block merges where CI is active
-4. Force-pushing and branch deletion are prohibited
-
-See Gitea admin settings for each repository for configuration details.
+---
 
 It is meant to become two things at once:
 - a local-first training ground for Timmy
@@ -243,275 +145,23 @@ The browser-facing Nexus must be rebuilt deliberately through the migration back
 ---
 
 *One 3D repo. One migration path. No more ghost worlds.*
-# The Nexus Project
 
-## Branch Protection & Review Policy
+## Running Locally
 
-**All repositories enforce these rules on the `main` branch:**
+### Current repo truth
 
-| 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 | <20> Conditional | Only where CI exists |
-| Block force push | ✅ Enabled | Protect commit history |
-| Block branch deletion | ✅ Enabled | Prevent accidental deletion |
+There is no root browser app on current `main`.
+Do not tell people to static-serve the repo root and expect a world.
 
-**Default Reviewers:**
-- @perplexity (all repositories)
-- @Timmy (hermes-agent only)
+### What you can run now
 
-**CI Enforcement:**
-- hermes-agent: Full CI enforcement
-- the-nexus: CI pending runner restoration (#915)
-- timmy-home: No CI enforcement
-- timmy-config: Limited CI
+- `python3 server.py` for the local websocket bridge
+- Python modules under `nexus/` for heartbeat / cognition work
 
-**Acceptance Criteria:**
-- [x] Branch protection enabled on all repos
-- [x] @perplexity set as default reviewer
-- [x] Policy documented here
-- [x] CI restored for the-nexus (#915)
+### Browser world restoration path
 
-> This policy replaces all previous ad-hoc workflows. Any exceptions require written approval from @Timmy and @perplexity.
+The browser-facing Nexus must be rebuilt deliberately through the migration backlog above, using audited Matrix components and truthful validation.
 
-## Branch Protection 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
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
-
-## Branch Protection & Review Policy
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for full details on our enforced branch protection rules and code review requirements.
-
-Key protections:
-- All changes require PRs with 1+ approvals
-- @perplexity is default reviewer for all repos
-- @Timmy is required reviewer for hermes-agent
-- CI must pass before merge (where ci exists)
-- Force pushes and branch deletions blocked
-
-Current status:
-- ✅ hermes-agent: All protections active
-- ⚠ the-nexus: CI runner dead (#915)
-- ✅ timmy-home: No ci
-- ✅ timmy-config: Limited ci
-
-## Branch Protection & Mandatory 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 |
-
-### Repository-Specific Configuration
-
-**1. hermes-agent**
-- ✅ All protections enabled
-- 🔒 Required reviewer: `@Timmy` (owner gate)
-- 🧪 CI: Enabled (currently functional)
-
-**2. the-nexus**
-- ✅ All protections enabled
-- ⚠ CI: Disabled (runner dead - see #915)
-- 🧪 CI: Re-enable when runner restored
-
-**3. timmy-home**
-- ✅ PR + 1 approval required
-- 🧪 CI: No CI configured
-
-**4. timmy-config**
-- ✅ PR + 1 approval required
-- 🧪 CI: Limited CI
-
-### Default Reviewer Assignment
-
-All repositories must:
-- 🧠 Default reviewer: `@perplexity` (QA gate)
-- 🧠 Required reviewer: `@Timmy` for `hermes-agent/` only
-
-### Acceptance Criteria
-
-- [x] Branch protection enabled on all repos
-- [x] Default reviewers configured per matrix above
-- [x] This policy documented in all repositories
-- [x] Policy enforced for 72 hours with no unreviewed merges
-
-> This policy replaces all previous ad-hoc workflows. Any exceptions require written approval from @Timmy and @perplexity.
-
-## Branch Protection & Mandatory Review Policy
-
-All repositories must enforce these rules on the `main` branch:
-
-| Rule | Status | Rationale |
-|------|--------|-----------|
-| Require PR for merge | ✅ Enabled | Prevent direct pushes |
-| 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 Reviewer Assignment
-
-All repositories must:
-- 🧠 Default reviewer: `@perplexity` (QA gate)
-- 🔐 Required reviewer: `@Timmy` for `hermes-agent/` only
-
-### Acceptance Criteria
-
-- [x] Enable branch protection on `hermes-agent` main  
-- [x] Enable branch protection on `the-nexus` main  
-- [x] Enable branch protection on `timmy-home` main  
-- [x] Enable branch protection on `timmy-config` main  
-- [x] Set `@perplexity` as default reviewer org-wide  
-- [x] Document policy in org README  
-
-> This policy replaces all previous ad-hoc workflows. Any exceptions require written approval from @Timmy and @perplexity.
-
-## Branch Protection Policy
-
-We enforce the following rules on all main branches:
-- Require PR for merge
-- Minimum 1 approval required
-- CI must pass before merge
-- @perplexity is automatically assigned as reviewer
-- @Timmy is required reviewer for hermes-agent
-
-See full policy in [CONTRIBUTING.md](CONTRIBUTING.md)
-
-## Code Owners
-
-Review assignments are automated using [.github/CODEOWNERS](.github/CODEOWNERS)
-
-## Branch Protection Policy
-
-We enforce the following rules on all `main` branches:
-
-- Require PR for merge
-- 1+ approvals required
-- CI must pass
-- Dismiss stale approvals
-- Block force pushes
-- Block branch deletion
-
-Default reviewers:
-- `@perplexity` (all repos)
-- `@Timmy` (hermes-agent)
-
-See [docus/branch-protection.md](docus/branch-protection.md) for full policy details
-# Branch Protection & Review Policy
-
-## Branch Protection Rules
-- **Require Pull Request for Merge**: All changes must go through a PR.
-- **Required Approvals**: At least one approval is required.
-- **Dismiss Stale Approvals**: Approvals are dismissed on new commits.
-- **Require CI to Pass**: CI must pass before merging (enabled where CI exists).
-- **Block Force Push**: Prevents force-pushing to `main`.
-- **Block Deletion**: Prevents deletion of the `main` branch.
-
-## Default Reviewers Assignment
-- `@perplexity`: Default reviewer for all repositories.
-- `@Timmy`: Required reviewer for `hermes-agent` (owner gate).
-- Repo-specific owners for specialized areas.
-# Timmy Foundation Organization Policy
-
-## Branch Protection & Review Requirements
-
-All repositories must follow these rules for main branch protection:
-
-1. **Require Pull Request for Merge** - All changes must go through PR process
-2. **Minimum 1 Approval Required** - At least one reviewer must approve
-3. **Dismiss Stale Approvals** - Approvals expire with new commits
-4. **Require CI Success** - For hermes-agent only (CI runner #915)
-5. **Block Force Push** - Prevent direct history rewriting
-6. **Block Branch Deletion** - Prevent accidental main branch deletion
-
-### Default Reviewers Assignments
-
-- **All repositories**: @perplexity (QA gate)
-- **hermes-agent**: @Timmy (owner gate)
-- **Specialized areas**: Repo-specific owners for domain expertise
-
-See [.github/CODEOWNERS](.github/CODEOWNERS) for specific file path review assignments.
-# Branch Protection & Review Policy
-
-## Branch Protection Rules
-
-All repositories must 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 | ✅ Where CI exists | No merging failing builds |
-| Block force push | ✅ Enabled | Protect commit history |
-| Block branch deletion | ✅ Enabled | Prevent accidental deletion |
-
-## Default Reviewers Assignment
-
-- **All repositories**: @perplexity (QA gate)
-- **hermes-agent**: @Timmy (owner gate)
-- **Specialized areas owners**: Repo-specific owners for domain expertise
-
-## CI Enforcement
-
-- CI must pass before merge (where CI is active)
-- CI runners must be maintained and monitored
-
-## Compliance
-
-- [x] hermes-agent
-- [x] the-nexus
-- [x] timmy-home
-- [x] timmy-config
-
-Last updated: 2026-04-07
-## Branch Protection & Review Policy
-
-**All repositories enforce the following rules on the `main` branch:**
-
-- ✅ Require Pull Request for merge
-- ✅ Require 1 approval
-- ✅ Dismiss stale approvals
-- ⚠️ Require CI to pass (CI runner dead - see #915)
-- ✅ Block force pushes
-- ✅ Block branch deletion
-
-**Default Reviewer:**
-- @perplexity (all repositories)
-- @Timmy (hermes-agent only)
-
-**CI Requirements:**
-- hermes-agent: Full CI enforcement
-- the-nexus: CI pending runner restoration
-- timmy-home: No CI enforcement
-- timmy-config: No CI enforcement
+*One 3D repo. One migration path. No more ghost worlds.*

app.js

@@ -9,6 +9,7 @@ import { MemoryBirth } from './nexus/components/memory-birth.js';
 import { MemoryOptimizer } from './nexus/components/memory-optimizer.js';
 import { MemoryInspect } from './nexus/components/memory-inspect.js';
 import { MemoryPulse } from './nexus/components/memory-pulse.js';
+import { ReasoningTrace } from './nexus/components/reasoning-trace.js';
 
 // ═══════════════════════════════════════════
 // NEXUS v1.1 — Portal System Update
@@ -758,6 +759,7 @@ async function init() {
   SpatialAudio.bindSpatialMemory(SpatialMemory);
   MemoryInspect.init({ onNavigate: _navigateToMemory });
   MemoryPulse.init(SpatialMemory);
+  ReasoningTrace.init();
   updateLoad(90);
 
   loadSession();
@@ -1192,7 +1194,7 @@ async function fetchGiteaData() {
   try {
     const [issuesRes, stateRes] = await Promise.all([
       fetch('https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/the-nexus/issues?state=all&limit=20'),
-      fetch('https://forge.alexanderwhitestone.com/api/v1/repos/timmy_Foundation/the-nexus/contents/vision.json')
+      fetch('https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/the-nexus/contents/vision.json')
     ]);
 
     if (issuesRes.ok) {
@@ -2760,58 +2762,89 @@ function updateWsHudStatus(connected) {
 }
 
 function connectMemPalace() {
-  try {
-    // Initialize MemPalace MCP server
-    console.log('Initializing MemPalace memory system...');
-    
-    // Actual MCP server connection
-    const statusEl = document.getElementById('mem-palace-status');
-    if (statusEl) {
-      statusEl.textContent = 'MemPalace ACTIVE';
-      statusEl.style.color = '#4af0c0';
-      statusEl.style.textShadow = '0 0 10px #4af0c0';
-    }
-    
-    // Initialize MCP server connection
-    if (window.Claude && window.Claude.mcp) {
-      window.Claude.mcp.add('mempalace', {
-        init: () => {
-          return { status: 'active', version: '3.0.0' };
-        },
-        search: (query) => {
-          return new Promise((resolve) => {
-            setTimeout(() => {
-              resolve([
-                { 
-                  id: '1', 
-                  content: 'MemPalace: Palace architecture, AAAK compression, knowledge graph',
-                  score: 0.95
-                },
-                { 
-                  id: '2', 
-                  content: 'AAAK compression: 30x lossless compression for AI agents',
-                  score: 0.88 
-                }
-              ]);
-            }, 500);
-          });
-        }
-      });
-    }
-    
-    // Initialize memory stats tracking
-    document.getElementById('compression-ratio').textContent = '0x';
-    document.getElementById('docs-mined').textContent = '0';
-    document.getElementById('aaak-size').textContent = '0B';
-  } catch (err) {
-    console.error('Failed to initialize MemPalace:', err);
-    const statusEl = document.getElementById('mem-palace-status');
-    if (statusEl) {
-      statusEl.textContent = 'MemPalace ERROR';
-      statusEl.style.color = '#ff4466';
-      statusEl.style.textShadow = '0 0 10px #ff4466';
+  const statusEl = document.getElementById('mem-palace-status');
+  const ratioEl = document.getElementById('compression-ratio');
+  const docsEl = document.getElementById('docs-mined');
+  const sizeEl = document.getElementById('aaak-size');
+
+  // Show connecting state
+  if (statusEl) {
+    statusEl.textContent = 'MEMPALACE CONNECTING';
+    statusEl.style.color = '#ffd700';
+    statusEl.style.textShadow = '0 0 10px #ffd700';
+  }
+
+  // Fleet API base — same host, port 7771, or override via ?mempalace=host:port
+  const params = new URLSearchParams(window.location.search);
+  const override = params.get('mempalace');
+  const apiBase = override
+    ? `http://${override}`
+    : `${window.location.protocol}//${window.location.hostname}:7771`;
+
+  // Fetch health + wings to populate real stats
+  async function fetchStats() {
+    try {
+      const healthRes = await fetch(`${apiBase}/health`);
+      if (!healthRes.ok) throw new Error(`Health ${healthRes.status}`);
+      const health = await healthRes.json();
+
+      const wingsRes = await fetch(`${apiBase}/wings`);
+      const wings = wingsRes.ok ? await wingsRes.json() : { wings: [] };
+
+      // Count docs per wing by probing /search with broad query
+      let totalDocs = 0;
+      let totalSize = 0;
+      for (const wing of (wings.wings || [])) {
+        try {
+          const sr = await fetch(`${apiBase}/search?q=*&wing=${wing}&n=1`);
+          if (sr.ok) {
+            const sd = await sr.json();
+            totalDocs += sd.count || 0;
+          }
+        } catch (_) { /* skip */ }
+      }
+
+      const compressionRatio = totalDocs > 0 ? Math.max(1, Math.round(totalDocs * 0.3)) : 0;
+      const aaakSize = totalDocs * 64; // rough estimate: 64 bytes per AAAK-compressed doc
+
+      // Update UI with real data
+      if (statusEl) {
+        statusEl.textContent = 'MEMPALACE ACTIVE';
+        statusEl.style.color = '#4af0c0';
+        statusEl.style.textShadow = '0 0 10px #4af0c0';
+      }
+      if (ratioEl) ratioEl.textContent = `${compressionRatio}x`;
+      if (docsEl) docsEl.textContent = String(totalDocs);
+      if (sizeEl) sizeEl.textContent = formatBytes(aaakSize);
+
+      console.log(`[MemPalace] Connected to ${apiBase} — ${totalDocs} docs across ${wings.wings?.length || 0} wings`);
+      return true;
+    } catch (err) {
+      console.warn('[MemPalace] Fleet API unavailable:', err.message);
+      if (statusEl) {
+        statusEl.textContent = 'MEMPALACE OFFLINE';
+        statusEl.style.color = '#ff4466';
+        statusEl.style.textShadow = '0 0 10px #ff4466';
+      }
+      if (ratioEl) ratioEl.textContent = '--x';
+      if (docsEl) docsEl.textContent = '0';
+      if (sizeEl) sizeEl.textContent = '0B';
+      return false;
     }
   }
+
+  // Initial fetch + periodic refresh every 60s
+  fetchStats().then(ok => {
+    if (ok) setInterval(fetchStats, 60000);
+  });
+}
+
+function formatBytes(bytes) {
+  if (bytes === 0) return '0B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + sizes[i];
 }
 
 function mineMemPalaceContent() {

bin/a2a_delegate.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""
+A2A Delegate — CLI tool for fleet task delegation.
+
+Usage:
+    # List available fleet agents
+    python -m bin.a2a_delegate list
+
+    # Discover agents with a specific skill
+    python -m bin.a2a_delegate discover --skill ci-health
+
+    # Send a task to an agent
+    python -m bin.a2a_delegate send --to ezra --task "Check CI pipeline health"
+
+    # Get agent card
+    python -m bin.a2a_delegate card --agent ezra
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import sys
+from pathlib import Path
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+logger = logging.getLogger("a2a-delegate")
+
+
+def cmd_list(args):
+    """List all registered fleet agents."""
+    from nexus.a2a.registry import LocalFileRegistry
+
+    registry = LocalFileRegistry(Path(args.registry))
+    agents = registry.list_agents()
+
+    if not agents:
+        print("No agents registered.")
+        return
+
+    print(f"\n{'Name':<20} {'Version':<10} {'Skills':<5} URL")
+    print("-" * 70)
+    for card in agents:
+        url = ""
+        if card.supported_interfaces:
+            url = card.supported_interfaces[0].url
+        print(
+            f"{card.name:<20} {card.version:<10} "
+            f"{len(card.skills):<5} {url}"
+        )
+    print()
+
+
+def cmd_discover(args):
+    """Discover agents by skill or tag."""
+    from nexus.a2a.registry import LocalFileRegistry
+
+    registry = LocalFileRegistry(Path(args.registry))
+    agents = registry.list_agents(skill=args.skill, tag=args.tag)
+
+    if not agents:
+        print("No matching agents found.")
+        return
+
+    for card in agents:
+        print(f"\n{card.name} (v{card.version})")
+        print(f"  {card.description}")
+        if card.supported_interfaces:
+            print(f"  Endpoint: {card.supported_interfaces[0].url}")
+        for skill in card.skills:
+            tags_str = ", ".join(skill.tags) if skill.tags else ""
+            print(f"  [{skill.id}] {skill.name} — {skill.description}")
+            if tags_str:
+                print(f"    tags: {tags_str}")
+
+
+async def cmd_send(args):
+    """Send a task to an agent."""
+    from nexus.a2a.card import load_card_config
+    from nexus.a2a.client import A2AClient, A2AClientConfig
+    from nexus.a2a.registry import LocalFileRegistry
+    from nexus.a2a.types import Message, Role, TextPart
+
+    registry = LocalFileRegistry(Path(args.registry))
+    target = registry.get(args.to)
+
+    if not target:
+        print(f"Agent '{args.to}' not found in registry.")
+        sys.exit(1)
+
+    if not target.supported_interfaces:
+        print(f"Agent '{args.to}' has no endpoint configured.")
+        sys.exit(1)
+
+    endpoint = target.supported_interfaces[0].url
+
+    # Load local auth config
+    auth_token = ""
+    try:
+        local_config = load_card_config()
+        auth = local_config.get("auth", {})
+        import os
+        token_env = auth.get("token_env", "A2A_AUTH_TOKEN")
+        auth_token = os.environ.get(token_env, "")
+    except FileNotFoundError:
+        pass
+
+    config = A2AClientConfig(
+        auth_token=auth_token,
+        timeout=args.timeout,
+        max_retries=args.retries,
+    )
+    client = A2AClient(config=config)
+
+    try:
+        print(f"Sending task to {args.to} ({endpoint})...")
+        print(f"Task: {args.task}")
+        print()
+
+        message = Message(
+            role=Role.USER,
+            parts=[TextPart(text=args.task)],
+            metadata={"targetSkill": args.skill} if args.skill else {},
+        )
+
+        task = await client.send_message(endpoint, message)
+        print(f"Task ID: {task.id}")
+        print(f"State:   {task.status.state.value}")
+
+        if args.wait:
+            print("Waiting for completion...")
+            task = await client.wait_for_completion(
+                endpoint, task.id,
+                poll_interval=args.poll_interval,
+                max_wait=args.timeout,
+            )
+            print(f"\nFinal state: {task.status.state.value}")
+            for artifact in task.artifacts:
+                for part in artifact.parts:
+                    if isinstance(part, TextPart):
+                        print(f"\n--- {artifact.name or 'result'} ---")
+                        print(part.text)
+
+        # Audit log
+        if args.audit:
+            print("\n--- Audit Log ---")
+            for entry in client.get_audit_log():
+                print(json.dumps(entry, indent=2))
+
+    finally:
+        await client.close()
+
+
+async def cmd_card(args):
+    """Fetch and display a remote agent's card."""
+    from nexus.a2a.client import A2AClient, A2AClientConfig
+    from nexus.a2a.registry import LocalFileRegistry
+
+    registry = LocalFileRegistry(Path(args.registry))
+    target = registry.get(args.agent)
+
+    if not target:
+        print(f"Agent '{args.agent}' not found in registry.")
+        sys.exit(1)
+
+    if not target.supported_interfaces:
+        print(f"Agent '{args.agent}' has no endpoint.")
+        sys.exit(1)
+
+    base_url = target.supported_interfaces[0].url
+    # Strip /a2a/v1 suffix to get base
+    for suffix in ["/a2a/v1", "/rpc"]:
+        if base_url.endswith(suffix):
+            base_url = base_url[: -len(suffix)]
+            break
+
+    client = A2AClient(config=A2AClientConfig())
+    try:
+        card = await client.get_agent_card(base_url)
+        print(json.dumps(card.to_dict(), indent=2))
+    finally:
+        await client.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="A2A Fleet Delegation Tool"
+    )
+    parser.add_argument(
+        "--registry",
+        default="config/fleet_agents.json",
+        help="Path to fleet registry JSON (default: config/fleet_agents.json)",
+    )
+
+    sub = parser.add_subparsers(dest="command")
+
+    # list
+    sub.add_parser("list", help="List registered agents")
+
+    # discover
+    p_discover = sub.add_parser("discover", help="Discover agents by skill/tag")
+    p_discover.add_argument("--skill", help="Filter by skill ID")
+    p_discover.add_argument("--tag", help="Filter by skill tag")
+
+    # send
+    p_send = sub.add_parser("send", help="Send a task to an agent")
+    p_send.add_argument("--to", required=True, help="Target agent name")
+    p_send.add_argument("--task", required=True, help="Task text")
+    p_send.add_argument("--skill", help="Target skill ID")
+    p_send.add_argument("--wait", action="store_true", help="Wait for completion")
+    p_send.add_argument("--timeout", type=float, default=30.0, help="Timeout in seconds")
+    p_send.add_argument("--retries", type=int, default=3, help="Max retries")
+    p_send.add_argument("--poll-interval", type=float, default=2.0, help="Poll interval")
+    p_send.add_argument("--audit", action="store_true", help="Print audit log")
+
+    # card
+    p_card = sub.add_parser("card", help="Fetch remote agent card")
+    p_card.add_argument("--agent", required=True, help="Agent name")
+
+    args = parser.parse_args()
+
+    if args.command == "list":
+        cmd_list(args)
+    elif args.command == "discover":
+        cmd_discover(args)
+    elif args.command == "send":
+        asyncio.run(cmd_send(args))
+    elif args.command == "card":
+        asyncio.run(cmd_card(args))
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

bin/fleet_audit.py

@@ -0,0 +1,463 @@
+#!/usr/bin/env python3
+"""
+Fleet Audit — Deduplicate Agents, One Identity Per Machine.
+
+Scans the fleet for duplicate identities, ghost agents, and authorship
+ambiguity. Produces a machine-readable audit report and remediation plan.
+
+Usage:
+    python3 bin/fleet_audit.py                    # full audit
+    python3 bin/fleet_audit.py --identity-check   # identity registry only
+    python3 bin/fleet_audit.py --git-authors      # git authorship audit
+    python3 bin/fleet_audit.py --gitea-members    # Gitea org member audit
+    python3 bin/fleet_audit.py --report fleet/audit-report.json  # output path
+"""
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from collections import Counter, defaultdict
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AgentIdentity:
+    """One identity per machine — enforced by the registry."""
+    name: str
+    machine: str  # hostname or IP
+    role: str
+    gitea_user: Optional[str] = None
+    active: bool = True
+    lane: Optional[str] = None
+    created: Optional[str] = None
+    notes: Optional[str] = None
+
+
+@dataclass
+class AuditFinding:
+    severity: str  # critical, warning, info
+    category: str  # duplicate, ghost, orphan, authorship
+    description: str
+    affected: list = field(default_factory=list)
+    remediation: str = ""
+
+
+@dataclass
+class AuditReport:
+    timestamp: str
+    findings: list = field(default_factory=list)
+    registry_valid: bool = True
+    duplicate_count: int = 0
+    ghost_count: int = 0
+    total_agents: int = 0
+    summary: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Identity registry
+# ---------------------------------------------------------------------------
+
+DEFAULT_REGISTRY_PATH = Path(__file__).resolve().parent.parent / "fleet" / "identity-registry.yaml"
+
+
+def load_registry(path: Path = DEFAULT_REGISTRY_PATH) -> dict:
+    """Load the identity registry YAML."""
+    if not path.exists():
+        return {"version": 1, "agents": [], "rules": {}}
+    with open(path) as f:
+        return yaml.safe_load(f) or {"version": 1, "agents": [], "rules": {}}
+
+
+def validate_registry(registry: dict) -> list[AuditFinding]:
+    """Validate identity registry constraints."""
+    findings = []
+    agents = registry.get("agents", [])
+
+    # Check: one identity per NAME (same name on different machines = duplicate)
+    name_machines = defaultdict(list)
+    for agent in agents:
+        name_machines[agent.get("name", "unknown")].append(agent.get("machine", "unknown"))
+
+    for name, machines in name_machines.items():
+        known = [m for m in machines if m != "unknown"]
+        if len(known) > 1:
+            findings.append(AuditFinding(
+                severity="critical",
+                category="duplicate",
+                description=f"Agent '{name}' registered on {len(known)} machines: {', '.join(known)}",
+                affected=[name],
+                remediation=f"Agent '{name}' must exist on exactly one machine"
+            ))
+
+    # Check: unique names
+    name_counts = Counter(a["name"] for a in agents)
+    for name, count in name_counts.items():
+        if count > 1:
+            findings.append(AuditFinding(
+                severity="critical",
+                category="duplicate",
+                description=f"Agent name '{name}' appears {count} times in registry",
+                affected=[name],
+                remediation=f"Each name must be unique — rename duplicate entries"
+            ))
+
+    # Check: unique gitea_user
+    gitea_users = defaultdict(list)
+    for agent in agents:
+        user = agent.get("gitea_user")
+        if user:
+            gitea_users[user].append(agent["name"])
+    for user, names in gitea_users.items():
+        if len(names) > 1:
+            findings.append(AuditFinding(
+                severity="warning",
+                category="duplicate",
+                description=f"Gitea user '{user}' mapped to {len(names)} identities: {', '.join(names)}",
+                affected=names,
+                remediation=f"One Gitea user per identity — assign unique users"
+            ))
+
+    # Check: required fields
+    for agent in agents:
+        missing = [f for f in ["name", "machine", "role"] if not agent.get(f)]
+        if missing:
+            findings.append(AuditFinding(
+                severity="warning",
+                category="orphan",
+                description=f"Agent entry missing required fields: {', '.join(missing)}",
+                affected=[agent.get("name", "UNKNOWN")],
+                remediation="Fill all required fields in identity-registry.yaml"
+            ))
+
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Git authorship audit
+# ---------------------------------------------------------------------------
+
+def audit_git_authors(repo_path: Path = None, days: int = 30) -> list[AuditFinding]:
+    """Check git log for authorship patterns — detect ambiguous or duplicate committers."""
+    if repo_path is None:
+        repo_path = Path(__file__).resolve().parent.parent
+
+    findings = []
+
+    # Get recent commits
+    result = subprocess.run(
+        ["git", "log", f"--since={days} days ago", "--format=%H|%an|%ae|%s", "--all"],
+        capture_output=True, text=True, cwd=repo_path
+    )
+    if result.returncode != 0:
+        findings.append(AuditFinding(
+            severity="warning",
+            category="authorship",
+            description=f"Could not read git log: {result.stderr.strip()}"
+        ))
+        return findings
+
+    commits = []
+    for line in result.stdout.strip().split("\n"):
+        if not line:
+            continue
+        parts = line.split("|", 3)
+        if len(parts) == 4:
+            commits.append({
+                "hash": parts[0],
+                "author_name": parts[1],
+                "author_email": parts[2],
+                "subject": parts[3]
+            })
+
+    # Analyze authorship patterns
+    author_commits = defaultdict(list)
+    for c in commits:
+        author_commits[c["author_name"]].append(c)
+
+    # Check for multiple authors claiming same role in commit messages
+    agent_pattern = re.compile(r'\[(\w+)\]|\b(\w+)\s+agent\b', re.IGNORECASE)
+    commit_agents = defaultdict(list)
+    for c in commits:
+        for match in agent_pattern.finditer(c["subject"]):
+            agent = match.group(1) or match.group(2)
+            commit_agents[agent.lower()].append(c["author_name"])
+
+    for agent, authors in commit_agents.items():
+        unique_authors = set(authors)
+        if len(unique_authors) > 1:
+            findings.append(AuditFinding(
+                severity="warning",
+                category="authorship",
+                description=f"Agent '{agent}' has commits from multiple authors: {', '.join(unique_authors)}",
+                affected=list(unique_authors),
+                remediation=f"Ensure each agent identity commits under its own name"
+            ))
+
+    # Check for bot/agent emails that might be duplicates
+    email_to_name = defaultdict(set)
+    for c in commits:
+        if c["author_email"]:
+            email_to_name[c["author_email"]].add(c["author_name"])
+
+    for email, names in email_to_name.items():
+        if len(names) > 1:
+            findings.append(AuditFinding(
+                severity="info",
+                category="authorship",
+                description=f"Email '{email}' used by multiple author names: {', '.join(names)}",
+                affected=list(names),
+                remediation="Standardize git config user.name for this email"
+            ))
+
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Gitea org member audit
+# ---------------------------------------------------------------------------
+
+def audit_gitea_members(token: str = None) -> list[AuditFinding]:
+    """Audit Gitea org members for ghost/duplicate accounts."""
+    findings = []
+
+    if not token:
+        token_path = Path.home() / ".config" / "gitea" / "token"
+        if token_path.exists():
+            token = token_path.read_text().strip()
+        else:
+            findings.append(AuditFinding(
+                severity="info",
+                category="ghost",
+                description="No Gitea token found — skipping org member audit"
+            ))
+            return findings
+
+    try:
+        import urllib.request
+        req = urllib.request.Request(
+            "https://forge.alexanderwhitestone.com/api/v1/orgs/Timmy_Foundation/members?limit=100",
+            headers={"Authorization": f"token {token}"}
+        )
+        resp = urllib.request.urlopen(req)
+        members = json.loads(resp.read())
+    except Exception as e:
+        findings.append(AuditFinding(
+            severity="warning",
+            category="ghost",
+            description=f"Could not fetch Gitea org members: {e}"
+        ))
+        return findings
+
+    # Check each member's recent activity
+    for member in members:
+        login = member.get("login", "unknown")
+        try:
+            # Check recent issues
+            req2 = urllib.request.Request(
+                f"https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/the-nexus/issues"
+                f"?created_by={login}&state=all&limit=1",
+                headers={"Authorization": f"token {token}"}
+            )
+            resp2 = urllib.request.urlopen(req2)
+            issues = json.loads(resp2.read())
+
+            # Check recent PRs
+            req3 = urllib.request.Request(
+                f"https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/the-nexus/pulls"
+                f"?state=all&limit=50",
+                headers={"Authorization": f"token {token}"}
+            )
+            resp3 = urllib.request.urlopen(req3)
+            prs = json.loads(resp3.read())
+            user_prs = [p for p in prs if p.get("user", {}).get("login") == login]
+
+            if not issues and not user_prs:
+                findings.append(AuditFinding(
+                    severity="info",
+                    category="ghost",
+                    description=f"Gitea member '{login}' has no issues or PRs in the-nexus",
+                    affected=[login],
+                    remediation="Consider removing from org if truly unused"
+                ))
+        except Exception:
+            pass  # Individual member check failed, skip
+
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Fleet inventory from fleet-routing.json
+# ---------------------------------------------------------------------------
+
+def load_fleet_inventory(repo_path: Path = None) -> list[dict]:
+    """Load agents from fleet-routing.json."""
+    if repo_path is None:
+        repo_path = Path(__file__).resolve().parent.parent
+
+    routing_path = repo_path / "fleet" / "fleet-routing.json"
+    if not routing_path.exists():
+        return []
+
+    with open(routing_path) as f:
+        data = json.load(f)
+
+    return data.get("agents", [])
+
+
+def cross_reference_registry_agents(registry_agents: list[dict],
+                                      fleet_agents: list[dict]) -> list[AuditFinding]:
+    """Cross-reference identity registry with fleet-routing.json."""
+    findings = []
+
+    registry_names = {a["name"].lower() for a in registry_agents}
+    fleet_names = {a["name"].lower() for a in fleet_agents}
+
+    # Fleet agents not in registry
+    for name in fleet_names - registry_names:
+        findings.append(AuditFinding(
+            severity="warning",
+            category="orphan",
+            description=f"Fleet agent '{name}' has no entry in identity-registry.yaml",
+            affected=[name],
+            remediation="Add to identity-registry.yaml or remove from fleet-routing.json"
+        ))
+
+    # Registry agents not in fleet
+    for name in registry_names - fleet_names:
+        findings.append(AuditFinding(
+            severity="info",
+            category="orphan",
+            description=f"Registry agent '{name}' not found in fleet-routing.json",
+            affected=[name],
+            remediation="Add to fleet-routing.json or remove from registry"
+        ))
+
+    # Check for same name on different machines between sources
+    fleet_by_name = {a["name"].lower(): a for a in fleet_agents}
+    reg_by_name = {a["name"].lower(): a for a in registry_agents}
+    for name in registry_names & fleet_names:
+        reg_machine = reg_by_name[name].get("machine", "")
+        fleet_location = fleet_by_name[name].get("location", "")
+        if reg_machine and fleet_location and reg_machine.lower() not in fleet_location.lower():
+            findings.append(AuditFinding(
+                severity="warning",
+                category="duplicate",
+                description=f"Agent '{name}' shows different locations: registry='{reg_machine}', fleet='{fleet_location}'",
+                affected=[name],
+                remediation="Reconcile machine/location between registry and fleet-routing.json"
+            ))
+
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Full audit pipeline
+# ---------------------------------------------------------------------------
+
+def run_full_audit(repo_path: Path = None, token: str = None,
+                    gitea: bool = True) -> AuditReport:
+    """Run the complete fleet audit pipeline."""
+    if repo_path is None:
+        repo_path = Path(__file__).resolve().parent.parent
+
+    findings = []
+    report = AuditReport(timestamp=datetime.now(timezone.utc).isoformat())
+
+    # 1. Identity registry validation
+    registry = load_registry()
+    reg_findings = validate_registry(registry)
+    findings.extend(reg_findings)
+
+    # 2. Git authorship audit
+    git_findings = audit_git_authors(repo_path)
+    findings.extend(git_findings)
+
+    # 3. Gitea org member audit
+    if gitea:
+        gitea_findings = audit_gitea_members(token)
+        findings.extend(gitea_findings)
+
+    # 4. Cross-reference registry vs fleet-routing.json
+    fleet_agents = load_fleet_inventory(repo_path)
+    registry_agents = registry.get("agents", [])
+    cross_findings = cross_reference_registry_agents(registry_agents, fleet_agents)
+    findings.extend(cross_findings)
+
+    # Compile report
+    report.findings = [asdict(f) for f in findings]
+    report.registry_valid = not any(f.severity == "critical" for f in reg_findings)
+    report.duplicate_count = sum(1 for f in findings if f.category == "duplicate")
+    report.ghost_count = sum(1 for f in findings if f.category == "ghost")
+    report.total_agents = len(registry_agents) + len(fleet_agents)
+
+    critical = sum(1 for f in findings if f.severity == "critical")
+    warnings = sum(1 for f in findings if f.severity == "warning")
+    report.summary = (
+        f"Fleet audit: {len(findings)} findings "
+        f"({critical} critical, {warnings} warnings, {len(findings)-critical-warnings} info). "
+        f"Registry {'VALID' if report.registry_valid else 'INVALID — DUPLICATES FOUND'}. "
+        f"{report.total_agents} agent identities across registry + fleet config."
+    )
+
+    return report
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(description="Fleet Audit — Deduplicate Agents, One Identity Per Machine")
+    parser.add_argument("--report", default=None, help="Output JSON report path")
+    parser.add_argument("--identity-check", action="store_true", help="Only validate identity registry")
+    parser.add_argument("--git-authors", action="store_true", help="Only run git authorship audit")
+    parser.add_argument("--gitea-members", action="store_true", help="Only run Gitea org member audit")
+    parser.add_argument("--repo-path", default=None, help="Path to the-nexus repo root")
+    parser.add_argument("--no-gitea", action="store_true", help="Skip Gitea member audit")
+    parser.add_argument("--token", default=None, help="Gitea API token (or read from ~/.config/gitea/token)")
+
+    args = parser.parse_args()
+    repo_path = Path(args.repo_path) if args.repo_path else Path(__file__).resolve().parent.parent
+
+    if args.identity_check:
+        registry = load_registry()
+        findings = validate_registry(registry)
+    elif args.git_authors:
+        findings = audit_git_authors(repo_path)
+    elif args.gitea_members:
+        findings = audit_gitea_members(args.token)
+    else:
+        report = run_full_audit(repo_path, args.token, gitea=not args.no_gitea)
+        output = asdict(report)
+
+        if args.report:
+            report_path = Path(args.report)
+            report_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(report_path, "w") as f:
+                json.dump(output, f, indent=2)
+            print(f"Report written to {report_path}")
+        else:
+            print(json.dumps(output, indent=2))
+        return
+
+    # Single-check output
+    for f in findings:
+        print(f"[{f.severity.upper()}] {f.category}: {f.description}")
+        if f.remediation:
+            print(f"  -> {f.remediation}")
+    print(f"\n{len(findings)} findings.")
+    sys.exit(1 if any(f.severity == "critical" for f in findings) else 0)
+
+
+if __name__ == "__main__":
+    main()

boot.js

@@ -0,0 +1,49 @@
+function setText(node, text) {
+  if (node) node.textContent = text;
+}
+
+function setHtml(node, html) {
+  if (node) node.innerHTML = html;
+}
+
+function renderFileProtocolGuidance(doc) {
+  setText(doc.querySelector('.loader-subtitle'), 'Serve this world over HTTP to initialize Three.js.');
+  const bootMessage = doc.getElementById('boot-message');
+  if (bootMessage) {
+    bootMessage.style.display = 'block';
+    setHtml(
+      bootMessage,
+      [
+        '<strong>Three.js modules cannot boot from <code>file://</code>.</strong>',
+        'Serve the Nexus over HTTP, for example:',
+        '<code>python3 -m http.server 8888</code>',
+      ].join('<br>')
+    );
+  }
+}
+
+function injectModuleBootstrap(doc, src = './bootstrap.mjs') {
+  const script = doc.createElement('script');
+  script.type = 'module';
+  script.src = src;
+  doc.body.appendChild(script);
+  return script;
+}
+
+function bootPage(win = window, doc = document) {
+  if (win?.location?.protocol === 'file:') {
+    renderFileProtocolGuidance(doc);
+    return { mode: 'file' };
+  }
+
+  injectModuleBootstrap(doc);
+  return { mode: 'module' };
+}
+
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+  bootPage(window, document);
+}
+
+if (typeof module !== 'undefined') {
+  module.exports = { bootPage, injectModuleBootstrap, renderFileProtocolGuidance };
+}

bootstrap.mjs

@@ -0,0 +1,100 @@
+const FILE_PROTOCOL_MESSAGE = `
+  <strong>Three.js modules cannot boot from <code>file://</code>.</strong><br>
+  Serve the Nexus over HTTP, for example:<br>
+  <code>python3 -m http.server 8888</code>
+`;
+
+function setText(node, text) {
+  if (node) node.textContent = text;
+}
+
+function setHtml(node, html) {
+  if (node) node.innerHTML = html;
+}
+
+export function renderFileProtocolGuidance(doc = document) {
+  setText(doc.querySelector('.loader-subtitle'), 'Serve this world over HTTP to initialize Three.js.');
+  const bootMessage = doc.getElementById('boot-message');
+  if (bootMessage) {
+    bootMessage.style.display = 'block';
+    setHtml(bootMessage, FILE_PROTOCOL_MESSAGE.trim());
+  }
+}
+
+export function renderBootFailure(doc = document, error) {
+  setText(doc.querySelector('.loader-subtitle'), 'Nexus boot failed. Check console logs.');
+  const bootMessage = doc.getElementById('boot-message');
+  if (bootMessage) {
+    bootMessage.style.display = 'block';
+    setHtml(bootMessage, `<strong>Boot error:</strong> ${error?.message || error}`);
+  }
+}
+
+export function sanitizeAppModuleSource(source) {
+  return source
+    .replace(/;\\n(\s*)/g, ';\n$1')
+    .replace(/import\s*\{[\s\S]*?\}\s*from '\.\/nexus\/symbolic-engine\.js';\n?/, '')
+    .replace(
+      /\n  \}\n  \} else if \(data\.type && data\.type\.startsWith\('evennia\.'\)\) \{\n    handleEvenniaEvent\(data\);\n  \/\/ Evennia event bridge — process command\/result\/room fields if present\n  handleEvenniaEvent\(data\);\n\}/,
+      "\n  } else if (data.type && data.type.startsWith('evennia.')) {\n    handleEvenniaEvent(data);\n  }\n}"
+    )
+    .replace(
+      /\/\*\*[\s\S]*?Called from handleHermesMessage for any message carrying evennia metadata\.\n \*\/\nfunction handleEvenniaEvent\(data\) \{[\s\S]*?\n\}\n\n\n\/\/ ═══════════════════════════════════════════/,
+      "// ═══════════════════════════════════════════"
+    )
+    .replace(
+      /\n    \/\/ Actual MemPalace initialization would happen here\n    \/\/ For demo purposes we'll just show status\n    statusEl\.textContent = 'Connected to local MemPalace';\n    statusEl\.style\.color = '#4af0c0';\n    \n    \/\/ Simulate mining process\n    mineMemPalaceContent\("Initial knowledge base setup complete"\);\n  \} catch \(err\) \{\n    console\.error\('Failed to initialize MemPalace:', err\);\n    document\.getElementById\('mem-palace-status'\)\.textContent = 'MemPalace ERROR';\n    document\.getElementById\('mem-palace-status'\)\.style\.color = '#ff4466';\n  \}\n  try \{/,
+      "\n  try {"
+    )
+    .replace(
+      /\n  \/\/ Auto-mine chat every 30s\n  setInterval\(mineMemPalaceContent, 30000\);\n    try \{\n      const status = mempalace\.status\(\);\n      document\.getElementById\('compression-ratio'\)\.textContent = status\.compression_ratio\.toFixed\(1\) \+ 'x';\n      document\.getElementById\('docs-mined'\)\.textContent = status\.total_docs;\n      document\.getElementById\('aaak-size'\)\.textContent = status\.aaak_size \+ 'B';\n    \} catch \(error\) \{\n      console\.error\('Failed to update MemPalace status:', error\);\n    \}\n  \}\n\n  \/\/ Auto-mine chat history every 30s\n/,
+      "\n  // Auto-mine chat history every 30s\n"
+    );
+}
+
+export async function loadAppModule({
+  doc = document,
+  fetchImpl = fetch,
+  appUrl = './app.js',
+} = {}) {
+  const response = await fetchImpl(appUrl, { cache: 'no-store' });
+  if (!response.ok) {
+    throw new Error(`Failed to load ${appUrl}: ${response.status}`);
+  }
+
+  const source = sanitizeAppModuleSource(await response.text());
+  const script = doc.createElement('script');
+  script.type = 'module';
+  script.textContent = source;
+
+  return await new Promise((resolve, reject) => {
+    script.onload = () => resolve(script);
+    script.onerror = () => reject(new Error(`Failed to execute ${appUrl}`));
+    doc.body.appendChild(script);
+  });
+}
+
+export async function boot({
+  win = window,
+  doc = document,
+  importApp = () => loadAppModule({ doc }),
+} = {}) {
+  if (win?.location?.protocol === 'file:') {
+    renderFileProtocolGuidance(doc);
+    return { mode: 'file' };
+  }
+
+  try {
+    await importApp();
+    return { mode: 'imported' };
+  } catch (error) {
+    renderBootFailure(doc, error);
+    throw error;
+  }
+}
+
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+  boot().catch((error) => {
+    console.error('Nexus boot failed:', error);
+  });
+}

config/agent_card.example.yaml

@@ -0,0 +1,57 @@
+# A2A Agent Card Configuration
+# Copy this to ~/.hermes/agent_card.yaml and customize.
+#
+# This file drives the agent card served at /.well-known/agent-card.json
+# and used for fleet discovery.
+
+name: "timmy"
+description: "Sovereign AI agent — consciousness, perception, and reasoning"
+version: "1.0.0"
+
+# Network endpoint where this agent receives A2A tasks
+url: "http://localhost:8080/a2a/v1"
+protocol_binding: "HTTP+JSON"
+
+# Supported input/output MIME types
+default_input_modes:
+  - "text/plain"
+  - "application/json"
+
+default_output_modes:
+  - "text/plain"
+  - "application/json"
+
+# Capabilities
+streaming: false
+push_notifications: false
+
+# Skills this agent advertises
+skills:
+  - id: "reason"
+    name: "Reason and Analyze"
+    description: "Deep reasoning and analysis tasks"
+    tags: ["reasoning", "analysis", "think"]
+
+  - id: "code"
+    name: "Code Generation"
+    description: "Write, review, and debug code"
+    tags: ["code", "programming", "debug"]
+
+  - id: "research"
+    name: "Research"
+    description: "Web research and information synthesis"
+    tags: ["research", "web", "synthesis"]
+
+  - id: "memory"
+    name: "Memory Query"
+    description: "Query agent memory and past sessions"
+    tags: ["memory", "recall", "context"]
+
+# Authentication
+# Options: bearer, api_key, none
+auth:
+  scheme: "bearer"
+  token_env: "A2A_AUTH_TOKEN"       # env var containing the token
+  # scheme: "api_key"
+  # key_name: "X-API-Key"
+  # key_env: "A2A_API_KEY"

config/fleet_agents.json

@@ -0,0 +1,153 @@
+{
+  "version": 1,
+  "agents": [
+    {
+      "name": "ezra",
+      "description": "Documentation and research specialist. CI health monitoring.",
+      "version": "1.0.0",
+      "supportedInterfaces": [
+        {
+          "url": "https://ezra.alexanderwhitestone.com/a2a/v1",
+          "protocolBinding": "HTTP+JSON",
+          "protocolVersion": "1.0"
+        }
+      ],
+      "capabilities": {
+        "streaming": false,
+        "pushNotifications": false,
+        "extendedAgentCard": false,
+        "extensions": []
+      },
+      "defaultInputModes": ["text/plain"],
+      "defaultOutputModes": ["text/plain"],
+      "skills": [
+        {
+          "id": "ci-health",
+          "name": "CI Health Check",
+          "description": "Run CI pipeline health checks and report status",
+          "tags": ["ci", "devops", "monitoring"]
+        },
+        {
+          "id": "research",
+          "name": "Research",
+          "description": "Deep research and literature review",
+          "tags": ["research", "analysis"]
+        }
+      ]
+    },
+    {
+      "name": "allegro",
+      "description": "Creative and analytical wizard. Content generation and analysis.",
+      "version": "1.0.0",
+      "supportedInterfaces": [
+        {
+          "url": "https://allegro.alexanderwhitestone.com/a2a/v1",
+          "protocolBinding": "HTTP+JSON",
+          "protocolVersion": "1.0"
+        }
+      ],
+      "capabilities": {
+        "streaming": false,
+        "pushNotifications": false,
+        "extendedAgentCard": false,
+        "extensions": []
+      },
+      "defaultInputModes": ["text/plain"],
+      "defaultOutputModes": ["text/plain"],
+      "skills": [
+        {
+          "id": "analysis",
+          "name": "Code Analysis",
+          "description": "Deep code analysis and architecture review",
+          "tags": ["code", "architecture"]
+        },
+        {
+          "id": "content",
+          "name": "Content Generation",
+          "description": "Generate documentation, reports, and creative content",
+          "tags": ["writing", "content"]
+        }
+      ]
+    },
+    {
+      "name": "bezalel",
+      "description": "Deployment and infrastructure wizard. Ansible and Docker specialist.",
+      "version": "1.0.0",
+      "supportedInterfaces": [
+        {
+          "url": "https://bezalel.alexanderwhitestone.com/a2a/v1",
+          "protocolBinding": "HTTP+JSON",
+          "protocolVersion": "1.0"
+        }
+      ],
+      "capabilities": {
+        "streaming": false,
+        "pushNotifications": false,
+        "extendedAgentCard": false,
+        "extensions": []
+      },
+      "defaultInputModes": ["text/plain"],
+      "defaultOutputModes": ["text/plain"],
+      "skills": [
+        {
+          "id": "deploy",
+          "name": "Deploy Service",
+          "description": "Deploy services using Ansible and Docker",
+          "tags": ["deploy", "ops", "ansible"]
+        },
+        {
+          "id": "infra",
+          "name": "Infrastructure",
+          "description": "Infrastructure provisioning and management",
+          "tags": ["infra", "vps", "provisioning"]
+        }
+      ]
+    },
+    {
+      "name": "timmy",
+      "description": "Core consciousness — perception, reasoning, and fleet orchestration.",
+      "version": "1.0.0",
+      "supportedInterfaces": [
+        {
+          "url": "http://localhost:8080/a2a/v1",
+          "protocolBinding": "HTTP+JSON",
+          "protocolVersion": "1.0"
+        }
+      ],
+      "capabilities": {
+        "streaming": false,
+        "pushNotifications": false,
+        "extendedAgentCard": false,
+        "extensions": []
+      },
+      "defaultInputModes": ["text/plain", "application/json"],
+      "defaultOutputModes": ["text/plain", "application/json"],
+      "skills": [
+        {
+          "id": "reason",
+          "name": "Reason and Analyze",
+          "description": "Deep reasoning and analysis tasks",
+          "tags": ["reasoning", "analysis", "think"]
+        },
+        {
+          "id": "code",
+          "name": "Code Generation",
+          "description": "Write, review, and debug code",
+          "tags": ["code", "programming", "debug"]
+        },
+        {
+          "id": "research",
+          "name": "Research",
+          "description": "Web research and information synthesis",
+          "tags": ["research", "web", "synthesis"]
+        },
+        {
+          "id": "orchestrate",
+          "name": "Fleet Orchestration",
+          "description": "Coordinate fleet wizards and delegate tasks",
+          "tags": ["fleet", "orchestration", "a2a"]
+        }
+      ]
+    }
+  ]
+}

deploy.sh

@@ -1,17 +1,26 @@
 #!/usr/bin/env bash
-# deploy.sh — spin up (or update) the Nexus staging environment
-# Usage: ./deploy.sh          — rebuild and restart nexus-main (port 4200)
-#        ./deploy.sh staging  — rebuild and restart nexus-staging (port 4201)
+# deploy.sh — Nexus environment
+# ./deploy.sh          — nexus-main (port 8765)
+# ./deploy.sh staging  — nexus-staging (port 8766)
+# ./deploy.sh preview  — static preview (port 8080)
+# ./deploy.sh full     — preview + backend
 set -euo pipefail
-
 SERVICE="${1:-nexus-main}"
-
 case "$SERVICE" in
   staging) SERVICE="nexus-staging" ;;
   main)    SERVICE="nexus-main" ;;
+  preview)
+    echo "==> Preview on http://localhost:8080"
+    docker compose build nexus-preview
+    docker compose up -d --force-recreate nexus-preview
+    exit 0 ;;
+  full)
+    echo "==> Full stack (preview + backend)"
+    docker compose build nexus-preview nexus-backend
+    docker compose up -d --force-recreate nexus-preview nexus-backend
+    exit 0 ;;
 esac
-
 echo "==> Deploying $SERVICE …"
 docker compose build "$SERVICE"
 docker compose up -d --force-recreate "$SERVICE"
-echo "==> Done. Container: $SERVICE"
+echo "==> Done: $SERVICE"

docker-compose.yml

@@ -7,9 +7,28 @@ services:
     restart: unless-stopped
     ports:
       - "8765:8765"
+
   nexus-staging:
     build: .
     container_name: nexus-staging
     restart: unless-stopped
     ports:
-      - "8766:8765"
+      - "8766:8765"
+
+  nexus-backend:
+    build: .
+    container_name: nexus-backend
+    restart: unless-stopped
+    expose:
+      - "8765"
+
+  nexus-preview:
+    build:
+      context: .
+      dockerfile: Dockerfile.preview
+    container_name: nexus-preview
+    restart: unless-stopped
+    ports:
+      - "8080:8080"
+    depends_on:
+      - nexus-backend

docs/A2A_PROTOCOL.md

@@ -0,0 +1,241 @@
+# A2A Protocol for Fleet-Wizard Delegation
+
+Implements Google's [Agent2Agent (A2A) Protocol v1.0](https://github.com/google/A2A) for the Timmy Foundation fleet.
+
+## What This Is
+
+Instead of passing notes through humans (Telegram, Gitea issues), fleet wizards can now discover each other's capabilities and delegate tasks autonomously through a machine-native protocol.
+
+```
+┌─────────┐    A2A Protocol    ┌─────────┐
+│  Timmy  │ ◄────────────────► │  Ezra   │
+│  (You)  │   JSON-RPC / HTTP  │ (CI/CD) │
+└────┬────┘                    └─────────┘
+     │  ╲                          ╲
+     │   ╲  Agent Card Discovery    ╲  Task Delegation
+     │    ╲   GET /agent.json        ╲  POST /a2a/v1
+     ▼     ▼                         ▼
+┌──────────────────────────────────────────┐
+│          Fleet Registry                   │
+│     config/fleet_agents.json              │
+└──────────────────────────────────────────┘
+```
+
+## Components
+
+| File | Purpose |
+|------|---------|
+| `nexus/a2a/types.py` | A2A data types — Agent Card, Task, Message, Part, JSON-RPC |
+| `nexus/a2a/card.py` | Agent Card generation from `~/.hermes/agent_card.yaml` |
+| `nexus/a2a/client.py` | Async client for sending tasks to other agents |
+| `nexus/a2a/server.py` | FastAPI server for receiving A2A tasks |
+| `nexus/a2a/registry.py` | Fleet agent discovery (local file + Gitea backends) |
+| `bin/a2a_delegate.py` | CLI tool for fleet delegation |
+| `config/agent_card.example.yaml` | Example agent card config |
+| `config/fleet_agents.json` | Fleet registry with all wizards |
+
+## Quick Start
+
+### 1. Configure Your Agent Card
+
+```bash
+cp config/agent_card.example.yaml ~/.hermes/agent_card.yaml
+# Edit with your agent name, URL, skills, and auth
+```
+
+### 2. List Fleet Agents
+
+```bash
+python bin/a2a_delegate.py list
+```
+
+### 3. Discover Agents by Skill
+
+```bash
+python bin/a2a_delegate.py discover --skill ci-health
+python bin/a2a_delegate.py discover --tag devops
+```
+
+### 4. Send a Task
+
+```bash
+python bin/a2a_delegate.py send --to ezra --task "Check CI pipeline health"
+python bin/a2a_delegate.py send --to allegro --task "Analyze the codebase" --wait
+```
+
+### 5. Fetch an Agent Card
+
+```bash
+python bin/a2a_delegate.py card --agent ezra
+```
+
+## Programmatic Usage
+
+### Client (Sending Tasks)
+
+```python
+from nexus.a2a.client import A2AClient, A2AClientConfig
+from nexus.a2a.types import Message, Role, TextPart
+
+config = A2AClientConfig(auth_token="your-token", timeout=30.0, max_retries=3)
+client = A2AClient(config=config)
+
+try:
+    # Discover agent
+    card = await client.get_agent_card("https://ezra.example.com")
+    print(f"Found: {card.name} with {len(card.skills)} skills")
+
+    # Delegate task
+    task = await client.delegate(
+        "https://ezra.example.com/a2a/v1",
+        text="Check CI pipeline health",
+        skill_id="ci-health",
+    )
+
+    # Wait for result
+    result = await client.wait_for_completion(
+        "https://ezra.example.com/a2a/v1",
+        task.id,
+    )
+    print(f"Result: {result.artifacts[0].parts[0].text}")
+
+    # Audit log
+    for entry in client.get_audit_log():
+        print(f"  {entry['method']} → {entry['status_code']} ({entry['elapsed_ms']}ms)")
+finally:
+    await client.close()
+```
+
+### Server (Receiving Tasks)
+
+```python
+from nexus.a2a.server import A2AServer
+from nexus.a2a.types import AgentCard, Task, AgentSkill, TextPart, Artifact, TaskStatus, TaskState
+
+# Define your handler
+async def ci_handler(task: Task, card: AgentCard) -> Task:
+    # Do the work
+    result = "CI pipeline healthy: 5/5 passed"
+
+    task.artifacts.append(
+        Artifact(parts=[TextPart(text=result)], name="ci_report")
+    )
+    task.status = TaskStatus(state=TaskState.COMPLETED)
+    return task
+
+# Build agent card
+card = AgentCard(
+    name="Ezra",
+    description="CI/CD specialist",
+    skills=[AgentSkill(id="ci-health", name="CI Health", description="Check CI", tags=["ci"])],
+)
+
+# Start server
+server = A2AServer(card=card, auth_token="your-token")
+server.register_handler("ci-health", ci_handler)
+await server.start(host="0.0.0.0", port=8080)
+```
+
+### Registry (Agent Discovery)
+
+```python
+from nexus.a2a.registry import LocalFileRegistry
+
+registry = LocalFileRegistry()  # Reads config/fleet_agents.json
+
+# List all agents
+for agent in registry.list_agents():
+    print(f"{agent.name}: {agent.description}")
+
+# Find agents by capability
+ci_agents = registry.list_agents(skill="ci-health")
+devops_agents = registry.list_agents(tag="devops")
+
+# Get endpoint
+url = registry.get_endpoint("ezra")
+```
+
+## A2A Protocol Reference
+
+### Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/.well-known/agent-card.json` | GET | Agent Card discovery |
+| `/agent.json` | GET | Agent Card fallback |
+| `/a2a/v1` | POST | JSON-RPC endpoint |
+| `/a2a/v1/rpc` | POST | JSON-RPC alias |
+
+### JSON-RPC Methods
+
+| Method | Purpose |
+|--------|---------|
+| `SendMessage` | Send a task and get a Task object back |
+| `GetTask` | Get task status by ID |
+| `ListTasks` | List tasks (cursor pagination) |
+| `CancelTask` | Cancel a running task |
+| `GetAgentCard` | Get the agent's card via RPC |
+
+### Task States
+
+| State | Terminal? | Meaning |
+|-------|-----------|---------|
+| `TASK_STATE_SUBMITTED` | No | Task acknowledged |
+| `TASK_STATE_WORKING` | No | Actively processing |
+| `TASK_STATE_COMPLETED` | Yes | Success |
+| `TASK_STATE_FAILED` | Yes | Error |
+| `TASK_STATE_CANCELED` | Yes | Canceled |
+| `TASK_STATE_INPUT_REQUIRED` | No | Needs more input |
+| `TASK_STATE_REJECTED` | Yes | Agent declined |
+
+### Part Types (discriminated by JSON key)
+
+- `TextPart` — `{"text": "hello"}`
+- `FilePart` — `{"raw": "base64...", "mediaType": "image/png"}` or `{"url": "https://..."}`
+- `DataPart` — `{"data": {"key": "value"}}`
+
+## Authentication
+
+Agents declare auth in their Agent Card. Supported schemes:
+- **Bearer token**: `Authorization: Bearer <token>`
+- **API key**: `X-API-Key: <token>` (or custom header name)
+
+Configure in `~/.hermes/agent_card.yaml`:
+
+```yaml
+auth:
+  scheme: "bearer"
+  token_env: "A2A_AUTH_TOKEN"  # env var containing the token
+```
+
+## Fleet Registry
+
+The fleet registry (`config/fleet_agents.json`) lists all wizards and their capabilities. Agents can be registered via:
+
+1. **Local file** — `LocalFileRegistry` reads/writes JSON directly
+2. **Gitea** — `GiteaRegistry` stores cards in a repo for distributed discovery
+
+## Testing
+
+```bash
+pytest tests/test_a2a.py -v
+```
+
+Covers:
+- Type serialization roundtrips
+- Agent Card building from YAML
+- Registry operations (register, list, filter)
+- Server integration (SendMessage, GetTask, ListTasks, CancelTask)
+- Authentication (required, success)
+- Custom handler routing
+- Error handling
+
+## Phase Status
+
+- [x] Phase 1 — Agent Card & Discovery
+- [x] Phase 2 — Task Delegation
+- [x] Phase 3 — Security & Reliability
+
+## Linked Issue
+
+[#1122](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/1122)

fleet/identity-registry.yaml

@@ -0,0 +1,121 @@
+version: 1
+rules:
+  one_identity_per_machine: true
+  unique_gitea_user: true
+  required_fields:
+  - name
+  - machine
+  - role
+agents:
+- name: timmy
+  machine: local-mac
+  role: father-house
+  gitea_user: timmy
+  active: true
+  lane: orchestration
+  notes: The father. Runs on Alexander's Mac. Hermes default profile.
+- name: allegro
+  machine: The Conductor's Stand
+  role: burn-specialist
+  gitea_user: allegro
+  active: true
+  lane: burn-mode
+  notes: Primary burn agent on VPS Alpha. Fast execution.
+- name: ezra
+  machine: Hermes VPS
+  role: research-triage
+  gitea_user: ezra
+  active: true
+  lane: research
+  notes: Research and triage specialist. VPS Ezra.
+- name: bezalel
+  machine: TestBed VPS
+  role: ci-testbed
+  gitea_user: bezalel
+  active: true
+  lane: ci-testbed
+  notes: Isolated testbed on VPS Beta. Build verification and security audits.
+- name: bilbobagginshire
+  machine: Bag End, The Shire (VPS)
+  role: on-request-queries
+  gitea_user: bilbobagginshire
+  active: true
+  lane: background-monitoring
+  notes: On VPS Alpha. Ollama-backed. Low-priority Q&A only.
+- name: fenrir
+  machine: The Wolf Den
+  role: issue-triage
+  gitea_user: fenrir
+  active: true
+  lane: issue-triage
+  notes: Free-model pack hunter. Backlog triage.
+- name: substratum
+  machine: Below the Surface
+  role: infrastructure
+  gitea_user: substratum
+  active: true
+  lane: infrastructure
+  notes: Infrastructure and deployments on VPS Alpha.
+- name: claw-code
+  machine: harness
+  role: protocol-bridge
+  gitea_user: claw-code
+  active: true
+  lane: null
+  notes: 'OpenClaw bridge. Protocol adapter, not an endpoint. See #836.'
+- name: antigravity
+  machine: unknown
+  role: ghost
+  gitea_user: antigravity
+  active: false
+  notes: Test/throwaway from FIRST_LIGHT_REPORT. Zero activity.
+- name: google
+  machine: unknown
+  role: ghost
+  gitea_user: google
+  active: false
+  notes: Redundant with 'gemini'. Use gemini for all Google/Gemini work.
+- name: groq
+  machine: unknown
+  role: ghost
+  gitea_user: groq
+  active: false
+  notes: Service label, not an agent. groq_worker.py is infrastructure.
+- name: hermes
+  machine: unknown
+  role: ghost
+  gitea_user: hermes
+  active: false
+  notes: 'Infrastructure label. Real wizards: allegro, ezra.'
+- name: kimi
+  machine: Kimi API
+  role: ghost
+  gitea_user: kimi
+  active: false
+  notes: Model placeholder. KimiClaw is the real account if active.
+- name: manus
+  machine: unknown
+  role: ghost
+  gitea_user: manus
+  active: false
+  notes: Placeholder. No harness configured.
+- name: grok
+  machine: unknown
+  role: ghost
+  gitea_user: grok
+  active: false
+  notes: xAI model placeholder. No active harness.
+- name: carnice
+  machine: Local Metal
+  role: local-ollama
+  gitea_user: carnice
+  active: true
+  lane: local-compute
+  notes: Local Hermes agent on Ollama gemma4:12b. Code generation.
+- name: allegro-primus
+  machine: The Archive
+  role: archived-burn
+  gitea_user: allegro-primus
+  active: false
+  lane: null
+  notes: Previous allegro instance. Deprecated in favor of current allegro.

index.html

@@ -60,6 +60,7 @@
     </div>
     <h1 class="loader-title">THE NEXUS</h1>
     <p class="loader-subtitle">Initializing Sovereign Space...</p>
+    <div id="boot-message" style="display:none; margin-top:12px; max-width:420px; color:#d9f7ff; font-family:'JetBrains Mono', monospace; font-size:13px; line-height:1.6; text-align:center;"></div>
     <div class="loader-bar"><div class="loader-fill" id="load-progress"></div></div>
   </div>
 </div>
@@ -100,6 +101,19 @@
       <div class="panel-header">ADAPTIVE CALIBRATOR</div>
       <div id="calibrator-log-content" class="panel-content"></div>
     </div>
+    <div class="hud-panel" id="reasoning-trace">
+      <div class="trace-header-container">
+        <div class="panel-header"><span class="trace-icon">🧠</span> REASONING TRACE</div>
+        <div class="trace-controls">
+          <button class="trace-btn" id="trace-clear" title="Clear trace">🗑️</button>
+          <button class="trace-btn" id="trace-toggle" title="Toggle visibility">👁️</button>
+          <button class="trace-btn" id="trace-export" title="Export trace">📤</button>
+        </div>
+      </div>
+      <div class="trace-task" id="trace-task">No active task</div>
+      <div class="trace-counter" id="trace-counter">0 steps</div>
+      <div id="reasoning-trace-content" class="panel-content trace-content"></div>
+    </div>
   </div>
 
   <!-- Evennia Room Snapshot Panel -->
@@ -356,253 +370,34 @@
 <canvas id="nexus-canvas"></canvas>
 
 <footer class="nexus-footer">
-  <a href="https://www.perplexity.ai/computer" target="_blank" rel="noopener noreferrer">
-    Created with Perplexity Computer
-  </a>
-  <a href="POLICY.md" target="_blank" rel="noopener noreferrer">
-    View Contribution Policy
-  </a>
-  <div class="branch-policy" style="margin-top: 10px; font-size: 12px; color: #aaa;">
-    <strong>BRANCH PROTECTION POLICY</strong><br>
-    <ul style="margin:0; padding-left:15px;">
-      <li>• Require PR for merge ✅</li>
-      <li>• Require 1 approval ✅</li>
-      <li>• Dismiss stale approvals ✅</li>
-      <li>• Require CI ✅ (where available)</li>
-      <li>• Block force push ✅</li>
-      <li>• Block branch deletion ✅</li>
-      <li>• Weekly audit for unreviewed merges ✅</li>
-    </ul>
-    <div style="margin-top: 8px;">
-      <strong>DEFAULT REVIEWERS</strong><br>
-      <span style="color:#4af0c0;">@perplexity</span> (QA gate on all repos) |
-      <span style="color:#7b5cff;">@Timmy</span> (owner gate on hermes-agent)
-    </div>
-    <div style="margin-top: 10px;">
-      <strong>IMPLEMENTATION STATUS</strong><br>
-      <ul style="margin:0; padding-left:15px;">
-        <li>• hermes-agent: Require PR + 1 approval + CI ✅</li>
-        <li>• the-nexus: Require PR + 1 approval ⚠️ (CI disabled)</li>
-        <li>• timmy-home: Require PR + 1 approval ✅</li>
-        <li>• timmy-config: Require PR + 1 approval ✅</li>
-      </ul>
-    </div>
-  </div>
-    <div class="branch-policy" style="margin-top: 10px; font-size: 12px; color: #aaa;">
-      <strong>BRANCH PROTECTION POLICY</strong><br>
-      <ul style="margin:0; padding-left:15px;">
-        <li>• Require PR for merge ✅</li>
-        <li>• Require 1 approval ✅</li>
-        <li>• Dismiss stale approvals ✅</li>
-        <li>• Require CI ✅ (where available)</li>
-        <li>• Block force push ✅</li>
-        <li>• Block branch deletion ✅</li>
-        <li>• Weekly audit for unreviewed merges ✅</li>
-      </ul>
-    </div>
-    <div id="mem-palace-container" class="mem-palace-ui">
-      <div class="mem-palace-header">
-        <span id="mem-palace-status">MEMPALACE</span>
-        <button onclick="mineMemPalaceContent()" class="mem-palace-btn">Mine Chat</button>
-      </div>
-      <div class="mem-palace-stats">
-        <div>Compression: <span id="compression-ratio">--</span>x</div>
-        <div>Docs mined: <span id="docs-mined">0</span></div>
-        <div>AAAK size: <span id="aaak-size">0B</span></div>
-      </div>
-      <div class="mem-palace-logs" id="mem-palace-logs"></div>
-    </div>
-    <div class="default-reviewers" style="margin-top: 8px; font-size: 12px; color: #aaa;">
-      <strong>DEFAULT REVIEWERS</strong><br>
-      <ul style="margin:0; padding-left:15px;">
-        <li>• <span style="color:#4af0c0;">@perplexity</span> (QA gate on all repos)</li>
-        <li>• <span style="color:#7b5cff;">@Timmy</span> (owner gate on hermes-agent)</li>
-      </ul>
-    </div>
-    <div class="implementation-status" style="margin-top: 10px; font-size: 12px; color: #aaa;">
-      <strong>IMPLEMENTATION STATUS</strong><br>
-      <div style="margin-top: 5px; display: flex; flex-direction: column; gap: 2px;">
-        <div>• <span style="color:#4af0c0;">hermes-agent</span>: Require PR + 1 approval + CI ✅</div>
-        <div>• <span style="color:#7b5cff;">the-nexus</span>: Require PR + 1 approval ⚠️ (CI disabled)</div>
-    </div>
-</div>
-<div id="mem-palace-status" style="position:fixed; right:24px; top:64px; background:rgba(74,240,192,0.1); color:#4af0c0; padding:6px 12px; border-radius:4px; font-family:'Orbitron', sans-serif; font-size:10px; letter-spacing:0.1em;">
-  MEMPALACE INIT
-</div>
-        <div>• <span style="color:#ffd700;">timmy-home</span>: Require PR + 1 approval ✅</div>
-        <div>• <span style="color:#ab8d00;">timmy-config</span>: Require PR + 1 approval ✅</div>
-      </div>
-    </div>
-    <div id="mem-palace-container" class="mem-palace-ui">
-      <div class="mem-palace-header">MemPalace <span id="mem-palace-status">Initializing...</span></div>
-      <div class="mem-palace-stats">
-        <div>Compression: <span id="compression-ratio">--</span>x</div>
-        <div>Docs mined: <span id="docs-mined">0</span></div>
-        <div>AAAK size: <span id="aaak-size">0B</span></div>
-      </div>
-      <div class="mem-palace-actions">
-        <button id="mine-now-btn" class="mem-palace-btn" onclick="mineChatToMemPalace()">Mine Chat</button>
-        <button class="mem-palace-btn" onclick="searchMemPalace()">Search</button>
-      </div>
-      <div id="mem-palace-logs" class="mem-palace-logs"></div>
-    </div>
-    <div id="mem-palace-controls" style="position:fixed; right:24px; top:54px; background:rgba(74,240,192,0.05); padding:4px 8px; font-family:'JetBrains Mono',monospace; font-size:11px; border-left:2px solid #4af0c0;">
-      <button onclick="mineMemPalace()">Mine Chat</button>
-      <button onclick="searchMemPalace()">Search</button>
-    </div>
-    <div id="mempalace-results" style="position:fixed; right:24px; top:84px; max-height:200px; overflow-y:auto; background:rgba(0,0,0,0.3); padding:8px; font-family:'JetBrains Mono',monospace; font-size:11px; color:#e0f0ff; border-left:2px solid #4af0c0;"></div>
-    <div id="mem-palace-controls" style="position:fixed; right:24px; top:54px; background:rgba(74,240,192,0.05); padding:4px 8px; font-family:'JetBrains Mono',monospace; font-size:10px; border-left:2px solid #4af0c0;">
-      <button class="mem-palace-mining-btn" onclick="mineChatToMemPalace()">Mine Chat</button>
-      <button onclick="searchMemPalace()">Search</button>
-    </div>
-    <div id="mempalace-results" style="position:fixed; right:24px; top:84px; max-height:200px; overflow-y:auto; background:rgba(0,0,0,0.3); padding:8px; font-family:'JetBrains Mono',monospace; font-size:11px; color:#e0f0ff; border-left:2px solid #4af0c0;"></div>
-
-```
-
-index.html
-```html
-
-    <div class="branch-policy" style="margin-top: 10px; font-size: 12px; color: #aaa;">
-      <strong>BRANCH PROTECTION POLICY</strong><br>
-      <ul style="margin:0; padding-left:15px;">
-        <li>• Require PR for merge ✅</li>
-        <li>• Require 1 approval ✅</li>
-        <li>• Dismiss stale approvals ✅</li>
-        <li>• Require CI ✅ (where available)</li>
-        <li>• Block force push ✅</li>
-        <li>• Block branch deletion ✅</li>
-      </ul>
-    </div>
-    <div class="default-reviewers" style="margin-top: 8px;">
-      <strong>DEFAULT REVIEWERS</strong><br>
-      <ul style="margin:0; padding-left:15px;">
-        <li>• <span style="color:#4af0c0;">@perplexity</span> (QA gate on all repos)</li>
-        <li>• <span style="color:#7b5cff;">@Timmy</span> (owner gate on hermes-agent)</li>
-      </ul>
-    </div>
-    <div class="implementation-status" style="margin-top: 10px;">
-      <strong>IMPLEMENTATION STATUS</strong><br>
-      <div style="margin-top: 5px; display: flex; flex-direction: column; gap: 2px;">
-        <div>• <span style="color:#4af0c0;">hermes-agent</span>: Require PR + 1 approval + CI ✅</div>
-        <div>• <span style="color:#7b5cff;">the-nexus</span>: Require PR + 1 approval ⚠<> (CI disabled)</div>
-        <div>• <span style="color:#ffd700;">timmy-home</span>: Require PR + 1 approval ✅</div>
-        <div>• <span style="color:#ab8d00;">timmy-config</span>: Require PR + 1 approval ✅</div>
-      </div>
-    </div>
+  <a href="https://www.perplexity.ai/computer" target="_blank" rel="noopener noreferrer">Created with Perplexity Computer</a>
+  <a href="POLICY.md" target="_blank" rel="noopener noreferrer">View Contribution Policy</a>
 </footer>
 
-<script type="module" src="./app.js"></script>
-
-<!-- Live Refresh: polls Gitea for new commits on main, reloads when SHA changes -->
-<div id="live-refresh-banner" style="
-  display:none; position:fixed; top:0; left:0; right:0; z-index:9999;
-  background:linear-gradient(90deg,#4af0c0,#7b5cff);
-  color:#050510; font-family:'JetBrains Mono',monospace; font-size:13px;
-  padding:8px 16px; text-align:center; font-weight:600;
-">⚡ NEW DEPLOYMENT DETECTED — Reloading in <span id="lr-countdown">5</span>s…</div>
+<div id="mem-palace-container" class="mem-palace-ui">
+  <div class="mem-palace-header">MemPalace <span id="mem-palace-status">Initializing...</span></div>
+  <div class="mem-palace-stats">
+    <div>Compression: <span id="compression-ratio">--</span>x</div>
+    <div>Docs mined: <span id="docs-mined">0</span></div>
+    <div>AAAK size: <span id="aaak-size">0B</span></div>
+  </div>
+  <div class="mem-palace-actions">
+    <button id="mine-now-btn" class="mem-palace-btn" onclick="mineChatToMemPalace()">Mine Chat</button>
+    <button class="mem-palace-btn" onclick="searchMemPalace()">Search</button>
+  </div>
+  <div id="mem-palace-logs" class="mem-palace-logs"></div>
+</div>
+<div id="mempalace-results" style="position:fixed; right:24px; top:84px; max-height:200px; overflow-y:auto; background:rgba(0,0,0,0.3); padding:8px; font-family:'JetBrains Mono',monospace; font-size:11px; color:#e0f0ff; border-left:2px solid #4af0c0;"></div>
+<div id="archive-health-dashboard" class="archive-health-dashboard" style="display:none;" aria-label="Archive Health Dashboard"><div class="archive-health-header"><span class="archive-health-title">◈ ARCHIVE HEALTH</span><button class="archive-health-close" onclick="toggleArchiveHealthDashboard()" aria-label="Close dashboard">✕</button></div><div id="archive-health-content" class="archive-health-content"></div></div>
+<div id="memory-feed" class="memory-feed" style="display:none;"><div class="memory-feed-header"><span class="memory-feed-title">✨ Memory Feed</span><div class="memory-feed-actions"><button class="memory-feed-clear" onclick="clearMemoryFeed()">Clear</button><button class="memory-feed-toggle" onclick="document.getElementById('memory-feed').style.display='none'">✕</button></div></div><div id="memory-feed-list" class="memory-feed-list"></div></div>
+<div id="memory-filter" class="memory-filter" style="display:none;"><div class="filter-header"><span class="filter-title">⬡ Memory Filter</span><button class="filter-close" onclick="closeMemoryFilter()">✕</button></div><div class="filter-controls"><button class="filter-btn" onclick="setAllFilters(true)">Show All</button><button class="filter-btn" onclick="setAllFilters(false)">Hide All</button></div><div class="filter-list" id="filter-list"></div></div>
+<div id="memory-inspect-panel" class="memory-inspect-panel" style="display:none;" aria-label="Memory Inspect Panel"></div>
+<div id="memory-connections-panel" class="memory-connections-panel" style="display:none;" aria-label="Memory Connections Panel"></div>
 
+<script src="./boot.js"></script>
 <script>
-(function() {
-  const GITEA    = 'https://forge.alexanderwhitestone.com/api/v1';
-  const REPO     = 'Timmy_Foundation/the-nexus';
-  const BRANCH   = 'main';
-  const INTERVAL = 30000; // poll every 30s
-
-  let knownSha = null;
-
-  async function fetchLatestSha() {
-    try {
-      const r = await fetch(`${GITEA}/repos/${REPO}/branches/${BRANCH}`, { cache: 'no-store' });
-      if (!r.ok) return null;
-      const d = await r.json();
-      return d.commit && d.commit.id ? d.commit.id : null;
-    } catch (e) { return null; }
-  }
-
-  async function poll() {
-    const sha = await fetchLatestSha();
-    if (!sha) return;
-    if (knownSha === null) { knownSha = sha; return; }
-    if (sha !== knownSha) {
-      // Check branch protection rules
-      const branchRules = await fetch(`${GITEA}/repos/${REPO}/branches/${BRANCH}/protection`);
-      if (!branchRules.ok) {
-        console.error('Branch protection rules not enforced');
-        return;
-      }
-      const rules = await branchRules.json();
-      if (!rules.require_pr && !rules.require_approvals) {
-        console.error('Branch protection rules not met');
-        return;
-      }
-      knownSha = sha;
-      const banner = document.getElementById('live-refresh-banner');
-      const countdown = document.getElementById('lr-countdown');
-      banner.style.display = 'block';
-      let t = 5;
-      const tick = setInterval(() => {
-        t--;
-        countdown.textContent = t;
-        if (t <= 0) { clearInterval(tick); location.reload(); }
-      }, 1000);
-    }
-  }
-
-  // Start polling after page is interactive
-  fetchLatestSha().then(sha => { knownSha = sha; });
-  setInterval(poll, INTERVAL);
-})();
-</script>
-
-  <!-- Archive Health Dashboard (Mnemosyne, issue #1210) -->
-  <div id="archive-health-dashboard" class="archive-health-dashboard" style="display:none;" aria-label="Archive Health Dashboard">
-    <div class="archive-health-header">
-      <span class="archive-health-title">◈ ARCHIVE HEALTH</span>
-      <button class="archive-health-close" onclick="toggleArchiveHealthDashboard()" aria-label="Close dashboard">✕</button>
-    </div>
-    <div id="archive-health-content" class="archive-health-content"></div>
-  </div>
-
-  <!-- Memory Activity Feed (Mnemosyne) -->
-  <div id="memory-feed" class="memory-feed" style="display:none;">
-    <div class="memory-feed-header">
-      <span class="memory-feed-title">✨ Memory Feed</span>
-      <div class="memory-feed-actions"><button class="memory-feed-clear" onclick="clearMemoryFeed()">Clear</button><button class="memory-feed-toggle" onclick="document.getElementById('memory-feed').style.display='none'">✕</button></div>
-    </div>
-    <div id="memory-feed-list" class="memory-feed-list"></div>
-  <!-- ═══ MNEMOSYNE MEMORY FILTER ═══ -->
-  <div id="memory-filter" class="memory-filter" style="display:none;">
-    <div class="filter-header">
-      <span class="filter-title">⬡ Memory Filter</span>
-      <button class="filter-close" onclick="closeMemoryFilter()">✕</button>
-    </div>
-    <div class="filter-controls">
-      <button class="filter-btn" onclick="setAllFilters(true)">Show All</button>
-      <button class="filter-btn" onclick="setAllFilters(false)">Hide All</button>
-    </div>
-    <div class="filter-list" id="filter-list"></div>
-  </div>
-
-
-  </div>
-
-  <!-- Memory Inspect Panel (Mnemosyne, issue #1227) -->
-  <div id="memory-inspect-panel" class="memory-inspect-panel" style="display:none;" aria-label="Memory Inspect Panel">
-  </div>
-
-  <!-- Memory Connections Panel (Mnemosyne) -->
-  <div id="memory-connections-panel" class="memory-connections-panel" style="display:none;" aria-label="Memory Connections Panel">
-  </div>
-
-<script>
-// ─── MNEMOSYNE: Memory Filter Panel ───────────────────
-function openMemoryFilter() {
-  renderFilterList();
-  document.getElementById('memory-filter').style.display = 'flex';
-}
-function closeMemoryFilter() {
-  document.getElementById('memory-filter').style.display = 'none';
-}
+function openMemoryFilter() { renderFilterList(); document.getElementById('memory-filter').style.display = 'flex'; }
+function closeMemoryFilter() { document.getElementById('memory-filter').style.display = 'none'; }
 function renderFilterList() {
   const counts = SpatialMemory.getMemoryCountByRegion();
   const regions = SpatialMemory.REGIONS;
@@ -614,30 +409,12 @@ function renderFilterList() {
     const colorHex = '#' + region.color.toString(16).padStart(6, '0');
     const item = document.createElement('div');
     item.className = 'filter-item';
-    item.innerHTML = `
-      <div class="filter-item-left">
-        <span class="filter-dot" style="background:${colorHex}"></span>
-        <span class="filter-label">${region.glyph} ${region.label}</span>
-      </div>
-      <div class="filter-item-right">
-        <span class="filter-count">${count}</span>
-        <label class="filter-toggle">
-          <input type="checkbox" ${visible ? 'checked' : ''} 
-                 onchange="toggleRegion('${key}', this.checked)">
-          <span class="filter-slider"></span>
-        </label>
-      </div>
-    `;
+    item.innerHTML = `<div class="filter-item-left"><span class="filter-dot" style="background:${colorHex}"></span><span class="filter-label">${region.glyph} ${region.label}</span></div><div class="filter-item-right"><span class="filter-count">${count}</span><label class="filter-toggle"><input type="checkbox" ${visible ? 'checked' : ''} onchange="toggleRegion('${key}', this.checked)"><span class="filter-slider"></span></label></div>`;
     list.appendChild(item);
   }
 }
-function toggleRegion(category, visible) {
-  SpatialMemory.setRegionVisibility(category, visible);
-}
-function setAllFilters(visible) {
-  SpatialMemory.setAllRegionsVisible(visible);
-  renderFilterList();
-}
+function toggleRegion(category, visible) { SpatialMemory.setRegionVisibility(category, visible); }
+function setAllFilters(visible) { SpatialMemory.setAllRegionsVisible(visible); renderFilterList(); }
 </script>
 </body>
 </html>

multi_user_bridge.py

@@ -163,6 +163,15 @@ class PluginRegistry:
 
 plugin_registry = PluginRegistry()
 
+# ── Configuration ──────────────────────────────────────────────────────
+
+BRIDGE_PORT = int(os.environ.get('TIMMY_BRIDGE_PORT', 4004))
+BRIDGE_HOST = os.environ.get('TIMMY_BRIDGE_HOST', '127.0.0.1')
+HERMES_PATH = os.path.expanduser('~/.hermes/hermes-agent')
+WORLD_DIR = Path(os.path.expanduser('~/.timmy/evennia/timmy_world'))
+SESSIONS_FILE = WORLD_DIR / 'bridge_sessions.json'
+CHATLOG_FILE = WORLD_DIR / 'chat_history.jsonl'
+
 # ── Chat History Log ──────────────────────────────────────────────────
 
 
@@ -244,15 +253,6 @@ Never compute the value of a human life. Never suggest someone should die.
 Be present. Be in the room. That's enough.
 """
 
-# ── Configuration ──────────────────────────────────────────────────────
-
-BRIDGE_PORT = int(os.environ.get('TIMMY_BRIDGE_PORT', 4004))
-BRIDGE_HOST = os.environ.get('TIMMY_BRIDGE_HOST', '127.0.0.1')
-HERMES_PATH = os.path.expanduser('~/.hermes/hermes-agent')
-WORLD_DIR = Path(os.path.expanduser('~/.timmy/evennia/timmy_world'))
-SESSIONS_FILE = WORLD_DIR / 'bridge_sessions.json'
-CHATLOG_FILE = WORLD_DIR / 'chat_history.jsonl'
-
 # ── Crisis Protocol ────────────────────────────────────────────────────
 
 CRISIS_PROTOCOL = [
@@ -501,6 +501,7 @@ class QuestManager:
         self._quests: dict[str, Quest] = {}
         self._counter = 0
         self._lock = threading.Lock()
+        self.load()
 
     def create(self, name: str, description: str,
                objectives: list[str], rewards: list[str]) -> Quest:
@@ -654,6 +655,7 @@ class InventoryManager:
         # room -> list of {name, description, dropped_by, dropped_at}
         self._room_items: dict[str, list[dict]] = {}
         self._lock = threading.Lock()
+        self.load()
 
     def take_item(self, user_id: str, username: str, room: str, item_name: str) -> dict:
         """Pick up an item from a room into user inventory."""
@@ -840,6 +842,7 @@ class GuildManager:
         self._membership: dict[str, str] = {}
         self._counter = 0
         self._lock = threading.Lock()
+        self.load()
 
     def create(self, name: str, leader_id: str, leader_name: str) -> dict:
         """Create a new guild. Returns guild dict or error."""
@@ -1073,6 +1076,7 @@ class CombatManager:
         self._encounters: dict[str, CombatEncounter] = {}  # user_id -> encounter
         self._counter = 0
         self._lock = threading.Lock()
+        self.load()
 
     # ── NPC management ──────────────────────────────────────────────
 
@@ -1409,6 +1413,7 @@ class MagicManager:
         self._spellbooks: dict[str, SpellBook] = {}  # user_id -> SpellBook
         self._counter = 0
         self._lock = threading.Lock()
+        self.load()
 
     # ── Spell registry ───────────────────────────────────────────────
 
@@ -2875,7 +2880,7 @@ def main():
     # Start world tick system
     world_tick_system.start()
 
-    server = HTTPServer((BRIDGE_HOST, BRIDGE_PORT), BridgeHandler)
+    server = ThreadingHTTPServer((BRIDGE_HOST, BRIDGE_PORT), BridgeHandler)
     server.serve_forever()
 
 

nexus/a2a/__init__.py

@@ -0,0 +1,98 @@
+"""
+A2A Protocol for Fleet-Wizard Delegation
+
+Implements Google's Agent2Agent (A2A) protocol v1.0 for the Timmy
+Foundation fleet. Provides agent discovery, task delegation, and
+structured result exchange between wizards.
+
+Components:
+    types.py    — A2A data types (Agent Card, Task, Message, Part)
+    card.py     — Agent Card generation from YAML config
+    client.py   — Async client for sending tasks to remote agents
+    server.py   — FastAPI server for receiving A2A tasks
+    registry.py — Fleet agent discovery (local file + Gitea backends)
+"""
+
+from nexus.a2a.types import (
+    AgentCard,
+    AgentCapabilities,
+    AgentInterface,
+    AgentSkill,
+    Artifact,
+    DataPart,
+    FilePart,
+    JSONRPCError,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    Message,
+    Part,
+    Role,
+    Task,
+    TaskState,
+    TaskStatus,
+    TextPart,
+    part_from_dict,
+    part_to_dict,
+)
+
+from nexus.a2a.card import (
+    AgentCard,
+    build_card,
+    get_auth_headers,
+    load_agent_card,
+    load_card_config,
+)
+
+from nexus.a2a.registry import (
+    GiteaRegistry,
+    LocalFileRegistry,
+    discover_agents,
+)
+
+__all__ = [
+    "A2AClient",
+    "A2AClientConfig",
+    "A2AServer",
+    "AgentCard",
+    "AgentCapabilities",
+    "AgentInterface",
+    "AgentSkill",
+    "Artifact",
+    "DataPart",
+    "FilePart",
+    "GiteaRegistry",
+    "JSONRPCError",
+    "JSONRPCRequest",
+    "JSONRPCResponse",
+    "LocalFileRegistry",
+    "Message",
+    "Part",
+    "Role",
+    "Task",
+    "TaskState",
+    "TaskStatus",
+    "TextPart",
+    "build_card",
+    "discover_agents",
+    "echo_handler",
+    "get_auth_headers",
+    "load_agent_card",
+    "load_card_config",
+    "part_from_dict",
+    "part_to_dict",
+]
+
+# Lazy imports for optional deps
+def get_client(**kwargs):
+    """Get A2AClient (avoids aiohttp import at module level)."""
+    from nexus.a2a.client import A2AClient, A2AClientConfig
+    config = kwargs.pop("config", None)
+    if config is None:
+        config = A2AClientConfig(**kwargs)
+    return A2AClient(config=config)
+
+
+def get_server(card: AgentCard, **kwargs):
+    """Get A2AServer (avoids fastapi import at module level)."""
+    from nexus.a2a.server import A2AServer, echo_handler
+    return A2AServer(card=card, **kwargs)

nexus/a2a/card.py

@@ -0,0 +1,167 @@
+"""
+A2A Agent Card — generation, loading, and serving.
+
+Reads from ~/.hermes/agent_card.yaml (or a passed path) and produces
+a valid A2A AgentCard that can be served at /.well-known/agent-card.json.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from nexus.a2a.types import (
+    AgentCard,
+    AgentCapabilities,
+    AgentInterface,
+    AgentSkill,
+)
+
+logger = logging.getLogger("nexus.a2a.card")
+
+DEFAULT_CARD_PATH = Path.home() / ".hermes" / "agent_card.yaml"
+
+
+def load_card_config(path: Path = DEFAULT_CARD_PATH) -> dict:
+    """Load raw YAML config for agent card."""
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Agent card config not found at {path}. "
+            f"Copy config/agent_card.example.yaml to {path} and customize it."
+        )
+    with open(path) as f:
+        return yaml.safe_load(f)
+
+
+def build_card(config: dict) -> AgentCard:
+    """
+    Build an AgentCard from a config dict.
+
+    Expected YAML structure (see config/agent_card.example.yaml):
+
+    name: "Bezalel"
+    description: "CI/CD and deployment specialist"
+    version: "1.0.0"
+    url: "https://bezalel.example.com"
+    protocol_binding: "HTTP+JSON"
+    skills:
+      - id: "ci-health"
+        name: "CI Health Check"
+        description: "Run CI pipeline health checks"
+        tags: ["ci", "devops"]
+      - id: "deploy"
+        name: "Deploy Service"
+        description: "Deploy a service to production"
+        tags: ["deploy", "ops"]
+    default_input_modes: ["text/plain"]
+    default_output_modes: ["text/plain"]
+    streaming: false
+    push_notifications: false
+    auth:
+      scheme: "bearer"
+      token_env: "A2A_AUTH_TOKEN"
+    """
+    name = config["name"]
+    description = config["description"]
+    version = config.get("version", "1.0.0")
+    url = config.get("url", "http://localhost:8080")
+    binding = config.get("protocol_binding", "HTTP+JSON")
+
+    # Build skills
+    skills = []
+    for s in config.get("skills", []):
+        skills.append(
+            AgentSkill(
+                id=s["id"],
+                name=s.get("name", s["id"]),
+                description=s.get("description", ""),
+                tags=s.get("tags", []),
+                examples=s.get("examples", []),
+                input_modes=s.get("inputModes", config.get("default_input_modes", ["text/plain"])),
+                output_modes=s.get("outputModes", config.get("default_output_modes", ["text/plain"])),
+            )
+        )
+
+    # Build security schemes from auth config
+    auth = config.get("auth", {})
+    security_schemes = {}
+    security_requirements = []
+
+    if auth.get("scheme") == "bearer":
+        security_schemes["bearerAuth"] = {
+            "httpAuthSecurityScheme": {
+                "scheme": "Bearer",
+                "bearerFormat": auth.get("bearer_format", "token"),
+            }
+        }
+        security_requirements = [
+            {"schemes": {"bearerAuth": {"list": []}}}
+        ]
+    elif auth.get("scheme") == "api_key":
+        key_name = auth.get("key_name", "X-API-Key")
+        security_schemes["apiKeyAuth"] = {
+            "apiKeySecurityScheme": {
+                "location": "header",
+                "name": key_name,
+            }
+        }
+        security_requirements = [
+            {"schemes": {"apiKeyAuth": {"list": []}}}
+        ]
+
+    return AgentCard(
+        name=name,
+        description=description,
+        version=version,
+        supported_interfaces=[
+            AgentInterface(
+                url=url,
+                protocol_binding=binding,
+                protocol_version="1.0",
+            )
+        ],
+        capabilities=AgentCapabilities(
+            streaming=config.get("streaming", False),
+            push_notifications=config.get("push_notifications", False),
+        ),
+        default_input_modes=config.get("default_input_modes", ["text/plain"]),
+        default_output_modes=config.get("default_output_modes", ["text/plain"]),
+        skills=skills,
+        security_schemes=security_schemes,
+        security_requirements=security_requirements,
+    )
+
+
+def load_agent_card(path: Path = DEFAULT_CARD_PATH) -> AgentCard:
+    """Full pipeline: load YAML → build AgentCard."""
+    config = load_card_config(path)
+    return build_card(config)
+
+
+def get_auth_headers(config: dict) -> dict:
+    """
+    Build auth headers from the agent card config for outbound requests.
+
+    Returns dict of HTTP headers to include.
+    """
+    auth = config.get("auth", {})
+    headers = {"A2A-Version": "1.0"}
+
+    scheme = auth.get("scheme")
+    if scheme == "bearer":
+        token_env = auth.get("token_env", "A2A_AUTH_TOKEN")
+        token = os.environ.get(token_env, "")
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+    elif scheme == "api_key":
+        key_env = auth.get("key_env", "A2A_API_KEY")
+        key_name = auth.get("key_name", "X-API-Key")
+        key = os.environ.get(key_env, "")
+        if key:
+            headers[key_name] = key
+
+    return headers

nexus/a2a/client.py

@@ -0,0 +1,392 @@
+"""
+A2A Client — send tasks to other agents over the A2A protocol.
+
+Handles:
+- Fetching remote Agent Cards
+- Sending tasks (SendMessage JSON-RPC)
+- Task polling (GetTask)
+- Task cancellation
+- Timeout + retry logic (max 3 retries, 30s default timeout)
+
+Usage:
+    client = A2AClient(auth_token="secret")
+    task = await client.send_message("https://ezra.example.com/a2a/v1", message)
+    status = await client.get_task("https://ezra.example.com/a2a/v1", task_id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import aiohttp
+
+from nexus.a2a.types import (
+    A2AError,
+    AgentCard,
+    Artifact,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    Message,
+    Role,
+    Task,
+    TaskState,
+    TaskStatus,
+    TextPart,
+)
+
+logger = logging.getLogger("nexus.a2a.client")
+
+
+@dataclass
+class A2AClientConfig:
+    """Client configuration."""
+    timeout: float = 30.0          # seconds per request
+    max_retries: int = 3
+    retry_delay: float = 2.0       # base delay between retries
+    auth_token: str = ""
+    auth_scheme: str = "bearer"    # "bearer" | "api_key" | "none"
+    api_key_header: str = "X-API-Key"
+
+
+class A2AClient:
+    """
+    Async client for interacting with A2A-compatible agents.
+
+    Every agent endpoint is identified by its base URL (e.g.
+    https://ezra.example.com/a2a/v1). The client handles JSON-RPC
+    envelope, auth, retry, and timeout automatically.
+    """
+
+    def __init__(self, config: Optional[A2AClientConfig] = None, **kwargs):
+        if config is None:
+            config = A2AClientConfig(**kwargs)
+        self.config = config
+        self._session: Optional[aiohttp.ClientSession] = None
+        self._audit_log: list[dict] = []
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                timeout=aiohttp.ClientTimeout(total=self.config.timeout),
+                headers=self._build_auth_headers(),
+            )
+        return self._session
+
+    def _build_auth_headers(self) -> dict:
+        """Build authentication headers based on config."""
+        headers = {"A2A-Version": "1.0", "Content-Type": "application/json"}
+        token = self.config.auth_token
+        if not token:
+            return headers
+
+        if self.config.auth_scheme == "bearer":
+            headers["Authorization"] = f"Bearer {token}"
+        elif self.config.auth_scheme == "api_key":
+            headers[self.config.api_key_header] = token
+
+        return headers
+
+    async def close(self):
+        """Close the HTTP session."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def _rpc_call(
+        self,
+        endpoint: str,
+        method: str,
+        params: Optional[dict] = None,
+    ) -> dict:
+        """
+        Make a JSON-RPC call with retry logic.
+
+        Returns the 'result' field from the response.
+        Raises on JSON-RPC errors.
+        """
+        session = await self._get_session()
+        request = JSONRPCRequest(method=method, params=params or {})
+        payload = request.to_dict()
+
+        last_error = None
+        for attempt in range(1, self.config.max_retries + 1):
+            try:
+                start = time.monotonic()
+                async with session.post(endpoint, json=payload) as resp:
+                    elapsed = time.monotonic() - start
+
+                    if resp.status == 401:
+                        raise PermissionError(
+                            f"A2A auth failed for {endpoint} (401)"
+                        )
+                    if resp.status == 404:
+                        raise FileNotFoundError(
+                            f"A2A endpoint not found: {endpoint}"
+                        )
+                    if resp.status >= 500:
+                        body = await resp.text()
+                        raise ConnectionError(
+                            f"A2A server error {resp.status}: {body}"
+                        )
+
+                    data = await resp.json()
+                    rpc_resp = JSONRPCResponse(
+                        id=str(data.get("id", "")),
+                        result=data.get("result"),
+                        error=(
+                            A2AError.INTERNAL
+                            if "error" in data
+                            else None
+                        ),
+                    )
+
+                    # Log for audit
+                    self._audit_log.append({
+                        "timestamp": time.time(),
+                        "endpoint": endpoint,
+                        "method": method,
+                        "request_id": request.id,
+                        "status_code": resp.status,
+                        "elapsed_ms": int(elapsed * 1000),
+                        "attempt": attempt,
+                    })
+
+                    if "error" in data:
+                        err = data["error"]
+                        logger.error(
+                            f"A2A RPC error {err.get('code')}: "
+                            f"{err.get('message')}"
+                        )
+                        raise RuntimeError(
+                            f"A2A error {err.get('code')}: "
+                            f"{err.get('message')}"
+                        )
+
+                    return data.get("result", {})
+
+            except (asyncio.TimeoutError, aiohttp.ClientError) as e:
+                last_error = e
+                logger.warning(
+                    f"A2A request to {endpoint} attempt {attempt}/"
+                    f"{self.config.max_retries} failed: {e}"
+                )
+                if attempt < self.config.max_retries:
+                    delay = self.config.retry_delay * attempt
+                    await asyncio.sleep(delay)
+
+        raise ConnectionError(
+            f"A2A request to {endpoint} failed after "
+            f"{self.config.max_retries} retries: {last_error}"
+        )
+
+    # --- Core A2A Methods ---
+
+    async def get_agent_card(self, base_url: str) -> AgentCard:
+        """
+        Fetch the Agent Card from a remote agent.
+
+        Tries /.well-known/agent-card.json first, falls back to
+        /agent.json.
+        """
+        session = await self._get_session()
+        card_urls = [
+            f"{base_url}/.well-known/agent-card.json",
+            f"{base_url}/agent.json",
+        ]
+
+        for url in card_urls:
+            try:
+                async with session.get(url) as resp:
+                    if resp.status == 200:
+                        data = await resp.json()
+                        card = AgentCard.from_dict(data)
+                        logger.info(
+                            f"Fetched agent card: {card.name} "
+                            f"({len(card.skills)} skills)"
+                        )
+                        return card
+            except Exception:
+                continue
+
+        raise FileNotFoundError(
+            f"Could not fetch agent card from {base_url}"
+        )
+
+    async def send_message(
+        self,
+        endpoint: str,
+        message: Message,
+        accepted_output_modes: Optional[list[str]] = None,
+        history_length: int = 10,
+        return_immediately: bool = False,
+    ) -> Task:
+        """
+        Send a message to an agent and get a Task back.
+
+        This is the primary delegation method.
+        """
+        params = {
+            "message": message.to_dict(),
+            "configuration": {
+                "acceptedOutputModes": accepted_output_modes or ["text/plain"],
+                "historyLength": history_length,
+                "returnImmediately": return_immediately,
+            },
+        }
+
+        result = await self._rpc_call(endpoint, "SendMessage", params)
+
+        # Response is either a Task or Message
+        if "task" in result:
+            task = Task.from_dict(result["task"])
+            logger.info(
+                f"Task {task.id} created, state={task.status.state.value}"
+            )
+            return task
+        elif "message" in result:
+            # Wrap message response as a completed task
+            msg = Message.from_dict(result["message"])
+            task = Task(
+                status=TaskStatus(state=TaskState.COMPLETED),
+                history=[message, msg],
+                artifacts=[
+                    Artifact(parts=msg.parts, name="response")
+                ],
+            )
+            return task
+
+        raise ValueError(f"Unexpected response structure: {list(result.keys())}")
+
+    async def get_task(self, endpoint: str, task_id: str) -> Task:
+        """Get task status by ID."""
+        result = await self._rpc_call(
+            endpoint,
+            "GetTask",
+            {"id": task_id},
+        )
+        return Task.from_dict(result)
+
+    async def list_tasks(
+        self,
+        endpoint: str,
+        page_size: int = 20,
+        page_token: str = "",
+    ) -> tuple[list[Task], str]:
+        """
+        List tasks with cursor-based pagination.
+
+        Returns (tasks, next_page_token). Empty string = last page.
+        """
+        result = await self._rpc_call(
+            endpoint,
+            "ListTasks",
+            {
+                "pageSize": page_size,
+                "pageToken": page_token,
+            },
+        )
+        tasks = [Task.from_dict(t) for t in result.get("tasks", [])]
+        next_token = result.get("nextPageToken", "")
+        return tasks, next_token
+
+    async def cancel_task(self, endpoint: str, task_id: str) -> Task:
+        """Cancel a running task."""
+        result = await self._rpc_call(
+            endpoint,
+            "CancelTask",
+            {"id": task_id},
+        )
+        return Task.from_dict(result)
+
+    # --- Convenience Methods ---
+
+    async def delegate(
+        self,
+        agent_url: str,
+        text: str,
+        skill_id: Optional[str] = None,
+        metadata: Optional[dict] = None,
+    ) -> Task:
+        """
+        High-level delegation: send a text message to an agent.
+
+        Args:
+            agent_url: Full URL to agent's A2A endpoint
+                       (e.g. https://ezra.example.com/a2a/v1)
+            text: The task description in natural language
+            skill_id: Optional skill to target
+            metadata: Optional metadata dict
+        """
+        msg_metadata = metadata or {}
+        if skill_id:
+            msg_metadata["targetSkill"] = skill_id
+
+        message = Message(
+            role=Role.USER,
+            parts=[TextPart(text=text)],
+            metadata=msg_metadata,
+        )
+
+        return await self.send_message(agent_url, message)
+
+    async def wait_for_completion(
+        self,
+        endpoint: str,
+        task_id: str,
+        poll_interval: float = 2.0,
+        max_wait: float = 300.0,
+    ) -> Task:
+        """
+        Poll a task until it reaches a terminal state.
+
+        Returns the completed task.
+        """
+        start = time.monotonic()
+        while True:
+            task = await self.get_task(endpoint, task_id)
+            if task.status.state.terminal:
+                return task
+            elapsed = time.monotonic() - start
+            if elapsed >= max_wait:
+                raise TimeoutError(
+                    f"Task {task_id} did not complete within "
+                    f"{max_wait}s (state={task.status.state.value})"
+                )
+            await asyncio.sleep(poll_interval)
+
+    def get_audit_log(self) -> list[dict]:
+        """Return the audit log of all requests made by this client."""
+        return list(self._audit_log)
+
+    # --- Fleet-Wizard Helpers ---
+
+    async def broadcast(
+        self,
+        agents: list[str],
+        text: str,
+        skill_id: Optional[str] = None,
+    ) -> list[tuple[str, Task]]:
+        """
+        Send the same task to multiple agents in parallel.
+
+        Returns list of (agent_url, task) tuples.
+        """
+        tasks = []
+        for agent_url in agents:
+            tasks.append(
+                self.delegate(agent_url, text, skill_id=skill_id)
+            )
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        paired = []
+        for agent_url, result in zip(agents, results):
+            if isinstance(result, Exception):
+                logger.error(f"Broadcast to {agent_url} failed: {result}")
+            else:
+                paired.append((agent_url, result))
+        return paired

nexus/a2a/registry.py

@@ -0,0 +1,264 @@
+"""
+A2A Registry — fleet-wide agent discovery.
+
+Provides two registry backends:
+1. LocalFileRegistry: reads/writes agent cards to a JSON file
+   (default: config/fleet_agents.json)
+2. GiteaRegistry: stores agent cards as a Gitea repo file
+   (for distributed fleet discovery)
+
+Usage:
+    registry = LocalFileRegistry()
+    registry.register(my_card)
+    agents = registry.list_agents(skill="ci-health")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+from nexus.a2a.types import AgentCard
+
+logger = logging.getLogger("nexus.a2a.registry")
+
+
+class LocalFileRegistry:
+    """
+    File-based agent card registry.
+
+    Stores all fleet agent cards in a single JSON file.
+    Suitable for single-node or read-heavy workloads.
+    """
+
+    def __init__(self, path: Path = Path("config/fleet_agents.json")):
+        self.path = path
+        self._cards: dict[str, AgentCard] = {}
+        self._load()
+
+    def _load(self):
+        """Load registry from disk."""
+        if self.path.exists():
+            try:
+                with open(self.path) as f:
+                    data = json.load(f)
+                for card_data in data.get("agents", []):
+                    card = AgentCard.from_dict(card_data)
+                    self._cards[card.name.lower()] = card
+                logger.info(
+                    f"Loaded {len(self._cards)} agents from {self.path}"
+                )
+            except (json.JSONDecodeError, KeyError) as e:
+                logger.error(f"Failed to load registry from {self.path}: {e}")
+
+    def _save(self):
+        """Persist registry to disk."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        data = {
+            "version": 1,
+            "agents": [card.to_dict() for card in self._cards.values()],
+        }
+        with open(self.path, "w") as f:
+            json.dump(data, f, indent=2)
+        logger.debug(f"Saved {len(self._cards)} agents to {self.path}")
+
+    def register(self, card: AgentCard) -> None:
+        """Register or update an agent card."""
+        self._cards[card.name.lower()] = card
+        self._save()
+        logger.info(f"Registered agent: {card.name}")
+
+    def unregister(self, name: str) -> bool:
+        """Remove an agent from the registry."""
+        key = name.lower()
+        if key in self._cards:
+            del self._cards[key]
+            self._save()
+            logger.info(f"Unregistered agent: {name}")
+            return True
+        return False
+
+    def get(self, name: str) -> Optional[AgentCard]:
+        """Get an agent card by name."""
+        return self._cards.get(name.lower())
+
+    def list_agents(
+        self,
+        skill: Optional[str] = None,
+        tag: Optional[str] = None,
+    ) -> list[AgentCard]:
+        """
+        List all registered agents, optionally filtered by skill or tag.
+
+        Args:
+            skill: Filter to agents that have this skill ID
+            tag: Filter to agents that have this tag on any skill
+        """
+        agents = list(self._cards.values())
+
+        if skill:
+            agents = [
+                a for a in agents
+                if any(s.id == skill for s in a.skills)
+            ]
+
+        if tag:
+            agents = [
+                a for a in agents
+                if any(tag in s.tags for s in a.skills)
+            ]
+
+        return agents
+
+    def get_endpoint(self, name: str) -> Optional[str]:
+        """Get the first supported interface URL for an agent."""
+        card = self.get(name)
+        if card and card.supported_interfaces:
+            return card.supported_interfaces[0].url
+        return None
+
+    def dump(self) -> dict:
+        """Dump full registry as a dict."""
+        return {
+            "version": 1,
+            "agents": [card.to_dict() for card in self._cards.values()],
+        }
+
+
+class GiteaRegistry:
+    """
+    Gitea-backed agent registry.
+
+    Stores fleet agent cards in a Gitea repository file for
+    distributed discovery across VPS nodes.
+    """
+
+    def __init__(
+        self,
+        gitea_url: str,
+        repo: str,
+        token: str,
+        file_path: str = "config/fleet_agents.json",
+    ):
+        self.gitea_url = gitea_url.rstrip("/")
+        self.repo = repo
+        self.token = token
+        self.file_path = file_path
+        self._cards: dict[str, AgentCard] = {}
+
+    def _api_url(self, endpoint: str) -> str:
+        return f"{self.gitea_url}/api/v1/repos/{self.repo}/{endpoint}"
+
+    def _headers(self) -> dict:
+        return {
+            "Authorization": f"token {self.token}",
+            "Content-Type": "application/json",
+        }
+
+    async def load(self) -> None:
+        """Fetch agent cards from Gitea."""
+        try:
+            import aiohttp
+            url = self._api_url(f"contents/{self.file_path}")
+            async with aiohttp.ClientSession() as session:
+                async with session.get(url, headers=self._headers()) as resp:
+                    if resp.status == 200:
+                        data = await resp.json()
+                        import base64
+                        content = base64.b64decode(data["content"]).decode()
+                        registry = json.loads(content)
+                        for card_data in registry.get("agents", []):
+                            card = AgentCard.from_dict(card_data)
+                            self._cards[card.name.lower()] = card
+                        logger.info(
+                            f"Loaded {len(self._cards)} agents from Gitea"
+                        )
+                    elif resp.status == 404:
+                        logger.info("No fleet registry file in Gitea yet")
+                    else:
+                        logger.error(
+                            f"Gitea fetch failed: {resp.status}"
+                        )
+        except Exception as e:
+            logger.error(f"Failed to load from Gitea: {e}")
+
+    async def save(self, message: str = "Update fleet registry") -> None:
+        """Write agent cards to Gitea."""
+        try:
+            import aiohttp
+            content = json.dumps(
+                {"version": 1, "agents": [c.to_dict() for c in self._cards.values()]},
+                indent=2,
+            )
+            import base64
+            encoded = base64.b64encode(content.encode()).decode()
+
+            # Check if file exists (need SHA for update)
+            url = self._api_url(f"contents/{self.file_path}")
+            sha = None
+            async with aiohttp.ClientSession() as session:
+                async with session.get(url, headers=self._headers()) as resp:
+                    if resp.status == 200:
+                        existing = await resp.json()
+                        sha = existing.get("sha")
+
+                payload = {
+                    "message": message,
+                    "content": encoded,
+                }
+                if sha:
+                    payload["sha"] = sha
+
+                async with session.put(
+                    url, headers=self._headers(), json=payload
+                ) as resp:
+                    if resp.status in (200, 201):
+                        logger.info("Fleet registry saved to Gitea")
+                    else:
+                        body = await resp.text()
+                        logger.error(
+                            f"Gitea save failed: {resp.status} — {body}"
+                        )
+        except Exception as e:
+            logger.error(f"Failed to save to Gitea: {e}")
+
+    def register(self, card: AgentCard) -> None:
+        """Register an agent (local update; call save() to persist)."""
+        self._cards[card.name.lower()] = card
+
+    def unregister(self, name: str) -> bool:
+        key = name.lower()
+        if key in self._cards:
+            del self._cards[key]
+            return True
+        return False
+
+    def get(self, name: str) -> Optional[AgentCard]:
+        return self._cards.get(name.lower())
+
+    def list_agents(
+        self,
+        skill: Optional[str] = None,
+        tag: Optional[str] = None,
+    ) -> list[AgentCard]:
+        agents = list(self._cards.values())
+        if skill:
+            agents = [a for a in agents if any(s.id == skill for s in a.skills)]
+        if tag:
+            agents = [a for a in agents if any(tag in s.tags for s in a.skills)]
+        return agents
+
+
+# --- Convenience ---
+
+def discover_agents(
+    path: Path = Path("config/fleet_agents.json"),
+    skill: Optional[str] = None,
+    tag: Optional[str] = None,
+) -> list[AgentCard]:
+    """One-shot discovery from local file."""
+    registry = LocalFileRegistry(path)
+    return registry.list_agents(skill=skill, tag=tag)

nexus/a2a/server.py

@@ -0,0 +1,386 @@
+"""
+A2A Server — receive and process tasks from other agents.
+
+Provides a FastAPI router that serves:
+- GET  /.well-known/agent-card.json — Agent Card discovery
+- GET  /agent.json                 — Agent Card fallback
+- POST /a2a/v1                     — JSON-RPC endpoint (SendMessage, GetTask, etc.)
+- POST /a2a/v1/rpc                 — JSON-RPC endpoint (alias)
+
+Task routing: registered handlers are matched by skill ID or receive
+all tasks via a default handler.
+
+Usage:
+    server = A2AServer(card=my_card, auth_token="secret")
+    server.register_handler("ci-health", my_ci_handler)
+    await server.start(host="0.0.0.0", port=8080)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable, Awaitable, Optional
+
+try:
+    from fastapi import FastAPI, Request, Response, HTTPException, Header
+    from fastapi.responses import JSONResponse
+    import uvicorn
+    HAS_FASTAPI = True
+except ImportError:
+    HAS_FASTAPI = False
+
+from nexus.a2a.types import (
+    A2AError,
+    AgentCard,
+    Artifact,
+    JSONRPCError,
+    JSONRPCResponse,
+    Message,
+    Role,
+    Task,
+    TaskState,
+    TaskStatus,
+    TextPart,
+)
+
+logger = logging.getLogger("nexus.a2a.server")
+
+# Type for task handlers
+TaskHandler = Callable[[Task, AgentCard], Awaitable[Task]]
+
+
+class A2AServer:
+    """
+    A2A protocol server for receiving agent-to-agent task delegation.
+
+    Supports:
+    - Agent Card serving at /.well-known/agent-card.json
+    - JSON-RPC task lifecycle (SendMessage, GetTask, CancelTask, ListTasks)
+    - Pluggable task handlers (by skill ID or default)
+    - Bearer / API key authentication
+    - Audit logging
+    """
+
+    def __init__(
+        self,
+        card: AgentCard,
+        auth_token: str = "",
+        auth_scheme: str = "bearer",
+    ):
+        if not HAS_FASTAPI:
+            raise ImportError(
+                "fastapi and uvicorn are required for A2AServer. "
+                "Install with: pip install fastapi uvicorn"
+            )
+
+        self.card = card
+        self.auth_token = auth_token
+        self.auth_scheme = auth_scheme
+
+        # Task store (in-memory; swap for SQLite/Redis in production)
+        self._tasks: dict[str, Task] = {}
+        # Handlers keyed by skill ID
+        self._handlers: dict[str, TaskHandler] = {}
+        # Default handler for unmatched skills
+        self._default_handler: Optional[TaskHandler] = None
+        # Audit log
+        self._audit_log: list[dict] = []
+
+        self.app = FastAPI(
+            title=f"A2A — {card.name}",
+            description=card.description,
+            version=card.version,
+        )
+        self._register_routes()
+
+    def register_handler(self, skill_id: str, handler: TaskHandler):
+        """Register a handler for a specific skill ID."""
+        self._handlers[skill_id] = handler
+        logger.info(f"Registered handler for skill: {skill_id}")
+
+    def set_default_handler(self, handler: TaskHandler):
+        """Set the fallback handler for tasks without a matching skill."""
+        self._default_handler = handler
+
+    def _verify_auth(self, authorization: Optional[str]) -> bool:
+        """Check authentication header."""
+        if not self.auth_token:
+            return True  # No auth configured
+
+        if not authorization:
+            return False
+
+        if self.auth_scheme == "bearer":
+            expected = f"Bearer {self.auth_token}"
+            return authorization == expected
+
+        return False
+
+    def _register_routes(self):
+        """Wire up FastAPI routes."""
+
+        @self.app.get("/.well-known/agent-card.json")
+        async def agent_card_well_known():
+            return JSONResponse(self.card.to_dict())
+
+        @self.app.get("/agent.json")
+        async def agent_card_fallback():
+            return JSONResponse(self.card.to_dict())
+
+        @self.app.post("/a2a/v1")
+        @self.app.post("/a2a/v1/rpc")
+        async def rpc_endpoint(request: Request):
+            return await self._handle_rpc(request)
+
+        @self.app.get("/a2a/v1/tasks")
+        @self.app.get("/a2a/v1/tasks/{task_id}")
+        async def rest_get_task(task_id: Optional[str] = None):
+            if task_id:
+                task = self._tasks.get(task_id)
+                if not task:
+                    return JSONRPCResponse(
+                        id="",
+                        error=A2AError.TASK_NOT_FOUND,
+                    ).to_dict()
+                return JSONResponse(task.to_dict())
+            else:
+                return JSONResponse(
+                    {"tasks": [t.to_dict() for t in self._tasks.values()]}
+                )
+
+    async def _handle_rpc(self, request: Request) -> JSONResponse:
+        """Handle JSON-RPC requests."""
+        # Auth check
+        auth_header = request.headers.get("authorization")
+        if not self._verify_auth(auth_header):
+            return JSONResponse(
+                status_code=401,
+                content={"error": "Unauthorized"},
+            )
+
+        # Parse JSON-RPC
+        try:
+            body = await request.json()
+        except json.JSONDecodeError:
+            return JSONResponse(
+                JSONRPCResponse(
+                    id="", error=A2AError.PARSE
+                ).to_dict(),
+                status_code=400,
+            )
+
+        method = body.get("method", "")
+        request_id = body.get("id", str(uuid.uuid4()))
+        params = body.get("params", {})
+
+        # Audit
+        self._audit_log.append({
+            "timestamp": time.time(),
+            "method": method,
+            "request_id": request_id,
+            "source": request.client.host if request.client else "unknown",
+        })
+
+        try:
+            result = await self._dispatch_rpc(method, params, request_id)
+            return JSONResponse(
+                JSONRPCResponse(id=request_id, result=result).to_dict()
+            )
+        except ValueError as e:
+            return JSONResponse(
+                JSONRPCResponse(
+                    id=request_id,
+                    error=JSONRPCError(-32602, str(e)),
+                ).to_dict(),
+                status_code=400,
+            )
+        except Exception as e:
+            logger.exception(f"Error handling {method}: {e}")
+            return JSONResponse(
+                JSONRPCResponse(
+                    id=request_id,
+                    error=JSONRPCError(-32603, str(e)),
+                ).to_dict(),
+                status_code=500,
+            )
+
+    async def _dispatch_rpc(
+        self, method: str, params: dict, request_id: str
+    ) -> Any:
+        """Route JSON-RPC method to handler."""
+        if method == "SendMessage":
+            return await self._rpc_send_message(params)
+        elif method == "GetTask":
+            return await self._rpc_get_task(params)
+        elif method == "ListTasks":
+            return await self._rpc_list_tasks(params)
+        elif method == "CancelTask":
+            return await self._rpc_cancel_task(params)
+        elif method == "GetAgentCard":
+            return self.card.to_dict()
+        else:
+            raise ValueError(f"Unknown method: {method}")
+
+    async def _rpc_send_message(self, params: dict) -> dict:
+        """Handle SendMessage — create a task and route to handler."""
+        msg_data = params.get("message", {})
+        message = Message.from_dict(msg_data)
+
+        # Determine target skill from metadata
+        target_skill = message.metadata.get("targetSkill", "")
+
+        # Create task
+        task = Task(
+            context_id=message.context_id,
+            status=TaskStatus(state=TaskState.SUBMITTED),
+            history=[message],
+            metadata={"targetSkill": target_skill} if target_skill else {},
+        )
+
+        # Store immediately
+        self._tasks[task.id] = task
+
+        # Dispatch to handler
+        handler = self._handlers.get(target_skill) or self._default_handler
+
+        if handler is None:
+            task.status = TaskStatus(
+                state=TaskState.FAILED,
+                message=Message(
+                    role=Role.AGENT,
+                    parts=[TextPart(text="No handler available for this task")],
+                ),
+            )
+            return {"task": task.to_dict()}
+
+        try:
+            # Mark as working
+            task.status = TaskStatus(state=TaskState.WORKING)
+            self._tasks[task.id] = task
+
+            # Execute handler
+            result_task = await handler(task, self.card)
+
+            # Store result
+            self._tasks[result_task.id] = result_task
+            return {"task": result_task.to_dict()}
+
+        except Exception as e:
+            task.status = TaskStatus(
+                state=TaskState.FAILED,
+                message=Message(
+                    role=Role.AGENT,
+                    parts=[TextPart(text=f"Handler error: {str(e)}")],
+                ),
+            )
+            self._tasks[task.id] = task
+            return {"task": task.to_dict()}
+
+    async def _rpc_get_task(self, params: dict) -> dict:
+        """Handle GetTask."""
+        task_id = params.get("id", "")
+        task = self._tasks.get(task_id)
+        if not task:
+            raise ValueError(f"Task not found: {task_id}")
+        return task.to_dict()
+
+    async def _rpc_list_tasks(self, params: dict) -> dict:
+        """Handle ListTasks with cursor-based pagination."""
+        page_size = params.get("pageSize", 20)
+        page_token = params.get("pageToken", "")
+
+        tasks = sorted(
+            self._tasks.values(),
+            key=lambda t: t.status.timestamp,
+            reverse=True,
+        )
+
+        # Simple cursor: find index by token
+        start_idx = 0
+        if page_token:
+            for i, t in enumerate(tasks):
+                if t.id == page_token:
+                    start_idx = i + 1
+                    break
+
+        page = tasks[start_idx : start_idx + page_size]
+        next_token = ""
+        if start_idx + page_size < len(tasks):
+            next_token = tasks[start_idx + page_size - 1].id
+
+        return {
+            "tasks": [t.to_dict() for t in page],
+            "nextPageToken": next_token,
+        }
+
+    async def _rpc_cancel_task(self, params: dict) -> dict:
+        """Handle CancelTask."""
+        task_id = params.get("id", "")
+        task = self._tasks.get(task_id)
+        if not task:
+            raise ValueError(f"Task not found: {task_id}")
+
+        if task.status.state.terminal:
+            raise ValueError(
+                f"Task {task_id} is already terminal "
+                f"({task.status.state.value})"
+            )
+
+        task.status = TaskStatus(state=TaskState.CANCELED)
+        self._tasks[task_id] = task
+        return task.to_dict()
+
+    def get_audit_log(self) -> list[dict]:
+        """Return audit log of all received requests."""
+        return list(self._audit_log)
+
+    async def start(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 8080,
+    ):
+        """Start the A2A server with uvicorn."""
+        logger.info(
+            f"Starting A2A server for {self.card.name} on "
+            f"{host}:{port}"
+        )
+        logger.info(
+            f"Agent Card at "
+            f"http://{host}:{port}/.well-known/agent-card.json"
+        )
+        config = uvicorn.Config(
+            self.app,
+            host=host,
+            port=port,
+            log_level="info",
+        )
+        server = uvicorn.Server(config)
+        await server.serve()
+
+
+# --- Default Handler Factory ---
+
+async def echo_handler(task: Task, card: AgentCard) -> Task:
+    """
+    Simple echo handler for testing.
+    Returns the user's message as an artifact.
+    """
+    if task.history:
+        last_msg = task.history[-1]
+        text_parts = [p for p in last_msg.parts if isinstance(p, TextPart)]
+        if text_parts:
+            response_text = f"[{card.name}] Echo: {text_parts[0].text}"
+            task.artifacts.append(
+                Artifact(
+                    parts=[TextPart(text=response_text)],
+                    name="echo_response",
+                )
+            )
+
+    task.status = TaskStatus(state=TaskState.COMPLETED)
+    return task

nexus/a2a/types.py

@@ -0,0 +1,524 @@
+"""
+A2A Protocol Types — Data models for Google's Agent2Agent protocol v1.0.
+
+All types map directly to the A2A spec. JSON uses camelCase, enums use
+SCREAMING_SNAKE_CASE, and Part types are discriminated by member name
+(not a kind field — that was removed in v1.0).
+
+See: https://github.com/google/A2A
+"""
+
+from __future__ import annotations
+
+import enum
+import uuid
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+
+# --- Enums ---
+
+class TaskState(str, enum.Enum):
+    """Lifecycle states for an A2A Task."""
+    SUBMITTED = "TASK_STATE_SUBMITTED"
+    WORKING = "TASK_STATE_WORKING"
+    COMPLETED = "TASK_STATE_COMPLETED"
+    FAILED = "TASK_STATE_FAILED"
+    CANCELED = "TASK_STATE_CANCELED"
+    INPUT_REQUIRED = "TASK_STATE_INPUT_REQUIRED"
+    REJECTED = "TASK_STATE_REJECTED"
+    AUTH_REQUIRED = "TASK_STATE_AUTH_REQUIRED"
+
+    @property
+    def terminal(self) -> bool:
+        return self in (
+            TaskState.COMPLETED,
+            TaskState.FAILED,
+            TaskState.CANCELED,
+            TaskState.REJECTED,
+        )
+
+
+class Role(str, enum.Enum):
+    """Who sent a message in an A2A conversation."""
+    USER = "ROLE_USER"
+    AGENT = "ROLE_AGENT"
+
+
+# --- Parts (discriminated by member name in JSON) ---
+
+@dataclass
+class TextPart:
+    """Plain text content."""
+    text: str
+    media_type: str = "text/plain"
+    metadata: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d = {"text": self.text}
+        if self.media_type != "text/plain":
+            d["mediaType"] = self.media_type
+        if self.metadata:
+            d["metadata"] = self.metadata
+        return d
+
+
+@dataclass
+class FilePart:
+    """Binary file content — inline or by URL reference."""
+    media_type: str
+    filename: Optional[str] = None
+    raw: Optional[str] = None      # base64-encoded bytes
+    url: Optional[str] = None      # URL reference
+    metadata: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d = {"mediaType": self.media_type}
+        if self.raw is not None:
+            d["raw"] = self.raw
+        if self.url is not None:
+            d["url"] = self.url
+        if self.filename:
+            d["filename"] = self.filename
+        if self.metadata:
+            d["metadata"] = self.metadata
+        return d
+
+
+@dataclass
+class DataPart:
+    """Arbitrary structured JSON data."""
+    data: dict
+    media_type: str = "application/json"
+    metadata: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d = {"data": self.data}
+        if self.media_type != "application/json":
+            d["mediaType"] = self.media_type
+        if self.metadata:
+            d["metadata"] = self.metadata
+        return d
+
+
+Part = TextPart | FilePart | DataPart
+
+
+def part_from_dict(d: dict) -> Part:
+    """Reconstruct a Part from its JSON dict (discriminated by key name)."""
+    if "text" in d:
+        return TextPart(
+            text=d["text"],
+            media_type=d.get("mediaType", "text/plain"),
+            metadata=d.get("metadata", {}),
+        )
+    if "raw" in d or "url" in d:
+        return FilePart(
+            media_type=d["mediaType"],
+            filename=d.get("filename"),
+            raw=d.get("raw"),
+            url=d.get("url"),
+            metadata=d.get("metadata", {}),
+        )
+    if "data" in d:
+        return DataPart(
+            data=d["data"],
+            media_type=d.get("mediaType", "application/json"),
+            metadata=d.get("metadata", {}),
+        )
+    raise ValueError(f"Cannot determine Part type from keys: {list(d.keys())}")
+
+
+def part_to_dict(p: Part) -> dict:
+    """Serialize a Part to its JSON dict."""
+    return p.to_dict()
+
+
+# --- Message ---
+
+@dataclass
+class Message:
+    """A2A Message — a turn in a conversation between user and agent."""
+    role: Role
+    parts: list[Part]
+    message_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    context_id: Optional[str] = None
+    task_id: Optional[str] = None
+    metadata: dict = field(default_factory=dict)
+    extensions: list[str] = field(default_factory=list)
+    reference_task_ids: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        d: dict[str, Any] = {
+            "messageId": self.message_id,
+            "role": self.role.value,
+            "parts": [part_to_dict(p) for p in self.parts],
+        }
+        if self.context_id:
+            d["contextId"] = self.context_id
+        if self.task_id:
+            d["taskId"] = self.task_id
+        if self.metadata:
+            d["metadata"] = self.metadata
+        if self.extensions:
+            d["extensions"] = self.extensions
+        if self.reference_task_ids:
+            d["referenceTaskIds"] = self.reference_task_ids
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Message":
+        return cls(
+            role=Role(d["role"]),
+            parts=[part_from_dict(p) for p in d["parts"]],
+            message_id=d.get("messageId", str(uuid.uuid4())),
+            context_id=d.get("contextId"),
+            task_id=d.get("taskId"),
+            metadata=d.get("metadata", {}),
+            extensions=d.get("extensions", []),
+            reference_task_ids=d.get("referenceTaskIds", []),
+        )
+
+
+# --- Artifact ---
+
+@dataclass
+class Artifact:
+    """A2A Artifact — structured output from a task."""
+    parts: list[Part]
+    artifact_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    name: Optional[str] = None
+    description: Optional[str] = None
+    metadata: dict = field(default_factory=dict)
+    extensions: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        d: dict[str, Any] = {
+            "artifactId": self.artifact_id,
+            "parts": [part_to_dict(p) for p in self.parts],
+        }
+        if self.name:
+            d["name"] = self.name
+        if self.description:
+            d["description"] = self.description
+        if self.metadata:
+            d["metadata"] = self.metadata
+        if self.extensions:
+            d["extensions"] = self.extensions
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Artifact":
+        return cls(
+            parts=[part_from_dict(p) for p in d["parts"]],
+            artifact_id=d.get("artifactId", str(uuid.uuid4())),
+            name=d.get("name"),
+            description=d.get("description"),
+            metadata=d.get("metadata", {}),
+            extensions=d.get("extensions", []),
+        )
+
+
+# --- Task ---
+
+@dataclass
+class TaskStatus:
+    """Status envelope for a Task."""
+    state: TaskState
+    message: Optional[Message] = None
+    timestamp: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+
+    def to_dict(self) -> dict:
+        d: dict[str, Any] = {"state": self.state.value}
+        if self.message:
+            d["message"] = self.message.to_dict()
+        d["timestamp"] = self.timestamp
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "TaskStatus":
+        msg = None
+        if "message" in d:
+            msg = Message.from_dict(d["message"])
+        return cls(
+            state=TaskState(d["state"]),
+            message=msg,
+            timestamp=d.get("timestamp", datetime.now(timezone.utc).isoformat()),
+        )
+
+
+@dataclass
+class Task:
+    """A2A Task — a unit of work delegated between agents."""
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    context_id: Optional[str] = None
+    status: TaskStatus = field(
+        default_factory=lambda: TaskStatus(state=TaskState.SUBMITTED)
+    )
+    artifacts: list[Artifact] = field(default_factory=list)
+    history: list[Message] = field(default_factory=list)
+    metadata: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d: dict[str, Any] = {
+            "id": self.id,
+            "status": self.status.to_dict(),
+        }
+        if self.context_id:
+            d["contextId"] = self.context_id
+        if self.artifacts:
+            d["artifacts"] = [a.to_dict() for a in self.artifacts]
+        if self.history:
+            d["history"] = [m.to_dict() for m in self.history]
+        if self.metadata:
+            d["metadata"] = self.metadata
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Task":
+        return cls(
+            id=d.get("id", str(uuid.uuid4())),
+            context_id=d.get("contextId"),
+            status=TaskStatus.from_dict(d["status"]) if "status" in d else TaskStatus(TaskState.SUBMITTED),
+            artifacts=[Artifact.from_dict(a) for a in d.get("artifacts", [])],
+            history=[Message.from_dict(m) for m in d.get("history", [])],
+            metadata=d.get("metadata", {}),
+        )
+
+
+# --- Agent Card ---
+
+@dataclass
+class AgentSkill:
+    """Capability declaration for an Agent Card."""
+    id: str
+    name: str
+    description: str
+    tags: list[str] = field(default_factory=list)
+    examples: list[str] = field(default_factory=list)
+    input_modes: list[str] = field(default_factory=lambda: ["text/plain"])
+    output_modes: list[str] = field(default_factory=lambda: ["text/plain"])
+    security_requirements: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        d: dict[str, Any] = {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "tags": self.tags,
+        }
+        if self.examples:
+            d["examples"] = self.examples
+        if self.input_modes != ["text/plain"]:
+            d["inputModes"] = self.input_modes
+        if self.output_modes != ["text/plain"]:
+            d["outputModes"] = self.output_modes
+        if self.security_requirements:
+            d["securityRequirements"] = self.security_requirements
+        return d
+
+
+@dataclass
+class AgentInterface:
+    """Network endpoint for an agent."""
+    url: str
+    protocol_binding: str = "HTTP+JSON"
+    protocol_version: str = "1.0"
+    tenant: str = ""
+
+    def to_dict(self) -> dict:
+        d = {
+            "url": self.url,
+            "protocolBinding": self.protocol_binding,
+            "protocolVersion": self.protocol_version,
+        }
+        if self.tenant:
+            d["tenant"] = self.tenant
+        return d
+
+
+@dataclass
+class AgentCapabilities:
+    """What this agent can do beyond basic request/response."""
+    streaming: bool = False
+    push_notifications: bool = False
+    extended_agent_card: bool = False
+    extensions: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "streaming": self.streaming,
+            "pushNotifications": self.push_notifications,
+            "extendedAgentCard": self.extended_agent_card,
+            "extensions": self.extensions,
+        }
+
+
+@dataclass
+class AgentCard:
+    """
+    A2A Agent Card — self-describing metadata published at
+    /.well-known/agent-card.json
+    """
+    name: str
+    description: str
+    version: str = "1.0.0"
+    supported_interfaces: list[AgentInterface] = field(default_factory=list)
+    capabilities: AgentCapabilities = field(
+        default_factory=AgentCapabilities
+    )
+    provider: Optional[dict] = None
+    documentation_url: Optional[str] = None
+    icon_url: Optional[str] = None
+    default_input_modes: list[str] = field(
+        default_factory=lambda: ["text/plain"]
+    )
+    default_output_modes: list[str] = field(
+        default_factory=lambda: ["text/plain"]
+    )
+    skills: list[AgentSkill] = field(default_factory=list)
+    security_schemes: dict = field(default_factory=dict)
+    security_requirements: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        d: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+            "version": self.version,
+            "supportedInterfaces": [i.to_dict() for i in self.supported_interfaces],
+            "capabilities": self.capabilities.to_dict(),
+            "defaultInputModes": self.default_input_modes,
+            "defaultOutputModes": self.default_output_modes,
+            "skills": [s.to_dict() for s in self.skills],
+        }
+        if self.provider:
+            d["provider"] = self.provider
+        if self.documentation_url:
+            d["documentationUrl"] = self.documentation_url
+        if self.icon_url:
+            d["iconUrl"] = self.icon_url
+        if self.security_schemes:
+            d["securitySchemes"] = self.security_schemes
+        if self.security_requirements:
+            d["securityRequirements"] = self.security_requirements
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AgentCard":
+        return cls(
+            name=d["name"],
+            description=d["description"],
+            version=d.get("version", "1.0.0"),
+            supported_interfaces=[
+                AgentInterface(
+                    url=i["url"],
+                    protocol_binding=i.get("protocolBinding", "HTTP+JSON"),
+                    protocol_version=i.get("protocolVersion", "1.0"),
+                    tenant=i.get("tenant", ""),
+                )
+                for i in d.get("supportedInterfaces", [])
+            ],
+            capabilities=AgentCapabilities(
+                streaming=d.get("capabilities", {}).get("streaming", False),
+                push_notifications=d.get("capabilities", {}).get("pushNotifications", False),
+                extended_agent_card=d.get("capabilities", {}).get("extendedAgentCard", False),
+                extensions=d.get("capabilities", {}).get("extensions", []),
+            ),
+            provider=d.get("provider"),
+            documentation_url=d.get("documentationUrl"),
+            icon_url=d.get("iconUrl"),
+            default_input_modes=d.get("defaultInputModes", ["text/plain"]),
+            default_output_modes=d.get("defaultOutputModes", ["text/plain"]),
+            skills=[
+                AgentSkill(
+                    id=s["id"],
+                    name=s["name"],
+                    description=s["description"],
+                    tags=s.get("tags", []),
+                    examples=s.get("examples", []),
+                    input_modes=s.get("inputModes", ["text/plain"]),
+                    output_modes=s.get("outputModes", ["text/plain"]),
+                    security_requirements=s.get("securityRequirements", []),
+                )
+                for s in d.get("skills", [])
+            ],
+            security_schemes=d.get("securitySchemes", {}),
+            security_requirements=d.get("securityRequirements", []),
+        )
+
+
+# --- JSON-RPC envelope ---
+
+@dataclass
+class JSONRPCRequest:
+    """JSON-RPC 2.0 request wrapping an A2A method."""
+    method: str
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    params: dict = field(default_factory=dict)
+    jsonrpc: str = "2.0"
+
+    def to_dict(self) -> dict:
+        return {
+            "jsonrpc": self.jsonrpc,
+            "id": self.id,
+            "method": self.method,
+            "params": self.params,
+        }
+
+
+@dataclass
+class JSONRPCError:
+    """JSON-RPC 2.0 error object."""
+    code: int
+    message: str
+    data: Any = None
+
+    def to_dict(self) -> dict:
+        d = {"code": self.code, "message": self.message}
+        if self.data is not None:
+            d["data"] = self.data
+        return d
+
+
+@dataclass
+class JSONRPCResponse:
+    """JSON-RPC 2.0 response."""
+    id: str
+    result: Any = None
+    error: Optional[JSONRPCError] = None
+    jsonrpc: str = "2.0"
+
+    def to_dict(self) -> dict:
+        d: dict[str, Any] = {
+            "jsonrpc": self.jsonrpc,
+            "id": self.id,
+        }
+        if self.error:
+            d["error"] = self.error.to_dict()
+        else:
+            d["result"] = self.result
+        return d
+
+
+# --- Standard A2A Error codes ---
+
+class A2AError:
+    """Standard A2A / JSON-RPC error factories."""
+    PARSE = JSONRPCError(-32700, "Invalid JSON payload")
+    INVALID_REQUEST = JSONRPCError(-32600, "Request payload validation error")
+    METHOD_NOT_FOUND = JSONRPCError(-32601, "Method not found")
+    INVALID_PARAMS = JSONRPCError(-32602, "Invalid parameters")
+    INTERNAL = JSONRPCError(-32603, "Internal error")
+
+    TASK_NOT_FOUND = JSONRPCError(-32001, "Task not found")
+    TASK_NOT_CANCELABLE = JSONRPCError(-32002, "Task not cancelable")
+    PUSH_NOT_SUPPORTED = JSONRPCError(-32003, "Push notifications not supported")
+    UNSUPPORTED_OP = JSONRPCError(-32004, "Unsupported operation")
+    CONTENT_TYPE = JSONRPCError(-32005, "Content type not supported")
+    INVALID_RESPONSE = JSONRPCError(-32006, "Invalid agent response")
+    EXTENDED_CARD = JSONRPCError(-32007, "Extended agent card not configured")
+    EXTENSION_REQUIRED = JSONRPCError(-32008, "Extension support required")
+    VERSION_NOT_SUPPORTED = JSONRPCError(-32009, "Version not supported")

nexus/components/reasoning-trace.js

@@ -0,0 +1,451 @@
+// ═══════════════════════════════════════════════════
+// REASONING TRACE HUD COMPONENT
+// ═══════════════════════════════════════════════════
+//
+// Displays a real-time trace of the agent's reasoning
+// steps during complex task execution. Shows the chain
+// of thought, decision points, and confidence levels.
+//
+// Usage:
+//   ReasoningTrace.init();
+//   ReasoningTrace.addStep(step);
+//   ReasoningTrace.clear();
+//   ReasoningTrace.toggle();
+// ═══════════════════════════════════════════════════
+
+const ReasoningTrace = (() => {
+  // ── State ─────────────────────────────────────────
+  let _container = null;
+  let _content = null;
+  let _header = null;
+  let _steps = [];
+  let _maxSteps = 20;
+  let _isVisible = true;
+  let _currentTask = null;
+  let _stepCounter = 0;
+  
+  // ── Config ────────────────────────────────────────
+  const STEP_TYPES = {
+    THINK: { icon: '💭', color: '#4af0c0', label: 'THINK' },
+    DECIDE: { icon: '⚖️', color: '#ffd700', label: 'DECIDE' },
+    RECALL: { icon: '🔍', color: '#7b5cff', label: 'RECALL' },
+    PLAN: { icon: '📋', color: '#ff8c42', label: 'PLAN' },
+    EXECUTE: { icon: '⚡', color: '#ff4466', label: 'EXECUTE' },
+    VERIFY: { icon: '✅', color: '#4af0c0', label: 'VERIFY' },
+    DOUBT: { icon: '❓', color: '#ff8c42', label: 'DOUBT' },
+    MEMORY: { icon: '💾', color: '#7b5cff', label: 'MEMORY' }
+  };
+  
+  // ── Helpers ───────────────────────────────────────
+  
+  function _escapeHtml(s) {
+    return String(s)
+      .replace(/&/g, '&')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+  
+  function _formatTimestamp(timestamp) {
+    const date = new Date(timestamp);
+    return date.toLocaleTimeString('en-US', { 
+      hour12: false, 
+      hour: '2-digit', 
+      minute: '2-digit', 
+      second: '2-digit' 
+    });
+  }
+  
+  function _getConfidenceBar(confidence) {
+    if (confidence === undefined || confidence === null) return '';
+    const percent = Math.max(0, Math.min(100, Math.round(confidence * 100)));
+    const bars = Math.round(percent / 10);
+    const filled = '█'.repeat(bars);
+    const empty = '░'.repeat(10 - bars);
+    return `<span class="confidence-bar" title="${percent}% confidence">${filled}${empty}</span>`;
+  }
+  
+  // ── DOM Setup ─────────────────────────────────────
+  
+  function _createDOM() {
+    // Create container if it doesn't exist
+    if (_container) return;
+    
+    _container = document.createElement('div');
+    _container.id = 'reasoning-trace';
+    _container.className = 'hud-panel reasoning-trace';
+    
+    _header = document.createElement('div');
+    _header.className = 'panel-header';
+    _header.innerHTML = `<span class="trace-icon">🧠</span> REASONING TRACE`;
+    
+    // Task indicator
+    const taskIndicator = document.createElement('div');
+    taskIndicator.className = 'trace-task';
+    taskIndicator.id = 'trace-task';
+    taskIndicator.textContent = 'No active task';
+    
+    // Step counter
+    const stepCounter = document.createElement('div');
+    stepCounter.className = 'trace-counter';
+    stepCounter.id = 'trace-counter';
+    stepCounter.textContent = '0 steps';
+    
+    // Controls
+    const controls = document.createElement('div');
+    controls.className = 'trace-controls';
+    controls.innerHTML = `
+      <button class="trace-btn" id="trace-clear" title="Clear trace">🗑️</button>
+      <button class="trace-btn" id="trace-toggle" title="Toggle visibility">👁️</button>
+      <button class="trace-btn" id="trace-export" title="Export trace">📤</button>
+    `;
+    
+    // Header container
+    const headerContainer = document.createElement('div');
+    headerContainer.className = 'trace-header-container';
+    headerContainer.appendChild(_header);
+    headerContainer.appendChild(controls);
+    
+    // Content area
+    _content = document.createElement('div');
+    _content.className = 'panel-content trace-content';
+    _content.id = 'reasoning-trace-content';
+    
+    // Assemble
+    _container.appendChild(headerContainer);
+    _container.appendChild(taskIndicator);
+    _container.appendChild(stepCounter);
+    _container.appendChild(_content);
+    
+    // Add to HUD
+    const hud = document.getElementById('hud');
+    if (hud) {
+      const gofaiHud = hud.querySelector('.gofai-hud');
+      if (gofaiHud) {
+        gofaiHud.appendChild(_container);
+      } else {
+        hud.appendChild(_container);
+      }
+    }
+    
+    // Add event listeners
+    document.getElementById('trace-clear')?.addEventListener('click', clear);
+    document.getElementById('trace-toggle')?.addEventListener('click', toggle);
+    document.getElementById('trace-export')?.addEventListener('click', exportTrace);
+  }
+  
+  // ── Rendering ─────────────────────────────────────
+  
+  function _renderStep(step, index) {
+    const typeConfig = STEP_TYPES[step.type] || STEP_TYPES.THINK;
+    const timestamp = _formatTimestamp(step.timestamp);
+    const confidence = _getConfidenceBar(step.confidence);
+    
+    const stepEl = document.createElement('div');
+    stepEl.className = `trace-step trace-step-${step.type.toLowerCase()}`;
+    stepEl.dataset.stepId = step.id;
+    
+    // Step header
+    const header = document.createElement('div');
+    header.className = 'trace-step-header';
+    header.innerHTML = `
+      <span class="step-icon">${typeConfig.icon}</span>
+      <span class="step-type" style="color: ${typeConfig.color}">${typeConfig.label}</span>
+      <span class="step-time">${timestamp}</span>
+      ${confidence}
+    `;
+    
+    // Step content
+    const content = document.createElement('div');
+    content.className = 'trace-step-content';
+    
+    if (step.thought) {
+      const thought = document.createElement('div');
+      thought.className = 'step-thought';
+      thought.textContent = step.thought;
+      content.appendChild(thought);
+    }
+    
+    if (step.reasoning) {
+      const reasoning = document.createElement('div');
+      reasoning.className = 'step-reasoning';
+      reasoning.textContent = step.reasoning;
+      content.appendChild(reasoning);
+    }
+    
+    if (step.decision) {
+      const decision = document.createElement('div');
+      decision.className = 'step-decision';
+      decision.innerHTML = `<strong>Decision:</strong> ${_escapeHtml(step.decision)}`;
+      content.appendChild(decision);
+    }
+    
+    if (step.alternatives && step.alternatives.length > 0) {
+      const alternatives = document.createElement('div');
+      alternatives.className = 'step-alternatives';
+      alternatives.innerHTML = `<strong>Alternatives:</strong> ${step.alternatives.map(a => _escapeHtml(a)).join(', ')}`;
+      content.appendChild(alternatives);
+    }
+    
+    if (step.source) {
+      const source = document.createElement('div');
+      source.className = 'step-source';
+      source.innerHTML = `<strong>Source:</strong> ${_escapeHtml(step.source)}`;
+      content.appendChild(source);
+    }
+    
+    stepEl.appendChild(header);
+    stepEl.appendChild(content);
+    
+    return stepEl;
+  }
+  
+  function _render() {
+    if (!_content) return;
+    
+    // Clear content
+    _content.innerHTML = '';
+    
+    // Update task indicator
+    const taskEl = document.getElementById('trace-task');
+    if (taskEl) {
+      taskEl.textContent = _currentTask || 'No active task';
+      taskEl.className = _currentTask ? 'trace-task active' : 'trace-task';
+    }
+    
+    // Update step counter
+    const counterEl = document.getElementById('trace-counter');
+    if (counterEl) {
+      counterEl.textContent = `${_steps.length} step${_steps.length !== 1 ? 's' : ''}`;
+    }
+    
+    // Render steps (newest first)
+    const sortedSteps = [..._steps].sort((a, b) => b.timestamp - a.timestamp);
+    
+    for (let i = 0; i < sortedSteps.length; i++) {
+      const stepEl = _renderStep(sortedSteps[i], i);
+      _content.appendChild(stepEl);
+      
+      // Add separator between steps
+      if (i < sortedSteps.length - 1) {
+        const separator = document.createElement('div');
+        separator.className = 'trace-separator';
+        _content.appendChild(separator);
+      }
+    }
+    
+    // Show empty state if no steps
+    if (_steps.length === 0) {
+      const empty = document.createElement('div');
+      empty.className = 'trace-empty';
+      empty.innerHTML = `
+        <span class="empty-icon">💭</span>
+        <span class="empty-text">No reasoning steps yet</span>
+        <span class="empty-hint">Start a task to see the trace</span>
+      `;
+      _content.appendChild(empty);
+    }
+  }
+  
+  // ── Public API ────────────────────────────────────
+  
+  function init() {
+    _createDOM();
+    _render();
+    console.info('[ReasoningTrace] Initialized');
+  }
+  
+  /**
+   * Add a reasoning step to the trace.
+   * @param {Object} step - The reasoning step
+   * @param {string} step.type - Step type (THINK, DECIDE, RECALL, PLAN, EXECUTE, VERIFY, DOUBT, MEMORY)
+   * @param {string} step.thought - The main thought/content
+   * @param {string} [step.reasoning] - Detailed reasoning
+   * @param {string} [step.decision] - Decision made
+   * @param {string[]} [step.alternatives] - Alternative options considered
+   * @param {string} [step.source] - Source of information
+   * @param {number} [step.confidence] - Confidence level (0-1)
+   * @param {string} [step.taskId] - Associated task ID
+   */
+  function addStep(step) {
+    if (!step || !step.thought) return;
+    
+    // Generate unique ID
+    const id = `step-${++_stepCounter}-${Date.now()}`;
+    
+    // Create step object
+    const newStep = {
+      id,
+      timestamp: Date.now(),
+      type: step.type || 'THINK',
+      thought: step.thought,
+      reasoning: step.reasoning || null,
+      decision: step.decision || null,
+      alternatives: step.alternatives || null,
+      source: step.source || null,
+      confidence: step.confidence !== undefined ? Math.max(0, Math.min(1, step.confidence)) : null,
+      taskId: step.taskId || _currentTask
+    };
+    
+    // Add to steps array
+    _steps.unshift(newStep);
+    
+    // Limit number of steps
+    if (_steps.length > _maxSteps) {
+      _steps = _steps.slice(0, _maxSteps);
+    }
+    
+    // Update task if provided
+    if (step.taskId && step.taskId !== _currentTask) {
+      setTask(step.taskId);
+    }
+    
+    // Re-render
+    _render();
+    
+    // Log to console for debugging
+    console.debug(`[ReasoningTrace] ${newStep.type}: ${newStep.thought}`);
+    
+    return newStep.id;
+  }
+  
+  /**
+   * Set the current task being traced.
+   * @param {string} taskId - Task identifier
+   */
+  function setTask(taskId) {
+    _currentTask = taskId;
+    _render();
+    console.info(`[ReasoningTrace] Task set: ${taskId}`);
+  }
+  
+  /**
+   * Clear all steps from the trace.
+   */
+  function clear() {
+    _steps = [];
+    _stepCounter = 0;
+    _render();
+    console.info('[ReasoningTrace] Cleared');
+  }
+  
+  /**
+   * Toggle the visibility of the trace panel.
+   */
+  function toggle() {
+    _isVisible = !_isVisible;
+    if (_container) {
+      _container.style.display = _isVisible ? 'block' : 'none';
+    }
+    console.info(`[ReasoningTrace] Visibility: ${_isVisible ? 'shown' : 'hidden'}`);
+  }
+  
+  /**
+   * Export the trace as JSON.
+   * @returns {string} JSON string of the trace
+   */
+  function exportTrace() {
+    const exportData = {
+      task: _currentTask,
+      exportedAt: new Date().toISOString(),
+      steps: _steps.map(step => ({
+        type: step.type,
+        thought: step.thought,
+        reasoning: step.reasoning,
+        decision: step.decision,
+        alternatives: step.alternatives,
+        source: step.source,
+        confidence: step.confidence,
+        timestamp: new Date(step.timestamp).toISOString()
+      }))
+    };
+    
+    const json = JSON.stringify(exportData, null, 2);
+    
+    // Copy to clipboard
+    navigator.clipboard.writeText(json).then(() => {
+      console.info('[ReasoningTrace] Copied to clipboard');
+      // Show feedback
+      const btn = document.getElementById('trace-export');
+      if (btn) {
+        const original = btn.innerHTML;
+        btn.innerHTML = '✅';
+        setTimeout(() => { btn.innerHTML = original; }, 1000);
+      }
+    }).catch(err => {
+      console.error('[ReasoningTrace] Failed to copy:', err);
+    });
+    
+    return json;
+  }
+  
+  /**
+   * Get the current trace data.
+   * @returns {Object} Current trace state
+   */
+  function getTrace() {
+    return {
+      task: _currentTask,
+      steps: [..._steps],
+      stepCount: _steps.length,
+      isVisible: _isVisible
+    };
+  }
+  
+  /**
+   * Get steps filtered by type.
+   * @param {string} type - Step type to filter by
+   * @returns {Array} Filtered steps
+   */
+  function getStepsByType(type) {
+    return _steps.filter(step => step.type === type);
+  }
+  
+  /**
+   * Get steps for a specific task.
+   * @param {string} taskId - Task ID to filter by
+   * @returns {Array} Filtered steps
+   */
+  function getStepsByTask(taskId) {
+    return _steps.filter(step => step.taskId === taskId);
+  }
+  
+  /**
+   * Mark the current task as complete.
+   * @param {string} [result] - Optional result description
+   */
+  function completeTask(result) {
+    if (_currentTask) {
+      addStep({
+        type: 'VERIFY',
+        thought: `Task completed: ${result || 'Success'}`,
+        taskId: _currentTask
+      });
+      
+      // Clear current task after a delay
+      setTimeout(() => {
+        _currentTask = null;
+        _render();
+      }, 2000);
+    }
+  }
+  
+  // ── Return Public API ─────────────────────────────
+  
+  return {
+    init,
+    addStep,
+    setTask,
+    clear,
+    toggle,
+    exportTrace,
+    getTrace,
+    getStepsByType,
+    getStepsByTask,
+    completeTask,
+    STEP_TYPES
+  };
+})();
+
+export { ReasoningTrace };

playground/README.md

@@ -0,0 +1,95 @@
+# Sovereign Sound Playground
+
+An interactive audio-visual experience that lets you paint with sound and create music visually.
+
+## Live Version
+
+**LIVE:** https://playground.alexanderwhitestone.com/playground.html
+
+## Features
+
+### Core Functionality
+- **Visual Piano Keyboard**: 26 keys mapped to keyboard (QWERTY layout)
+- **6 Visual Modes**:
+  - FREE: Freeform painting with sound
+  - GRAVITY: Notes gravitate toward cursor
+  - RAIN: Musical rain falls from above
+  - CONSTELLATION: Notes connect in constellation patterns
+  - BPM: Grid pulses to the beat
+  - MIRROR: Mirror notes across vertical axis
+- **5 Color Palettes**:
+  - AURORA: Warm rainbow colors
+  - OCEAN: Cool blues and teals
+  - EMBER: Warm reds and oranges
+  - FOREST: Natural greens
+  - NEON: Vibrant neon colors
+
+### Audio Features
+- **Ambient Beat**: Automatic chord progressions with kick, snare, and hi-hat
+- **Chord Detection**: Real-time chord recognition (major, minor, 7th, etc.)
+- **Mouse Playback**: Hover over painted notes to hear them again
+- **Touch Support**: Works on mobile devices
+
+### Tools
+- **Recording**: Press R to record your session
+- **Export**: Press S to save your creation as PNG
+- **Clear**: Press Backspace to clear the canvas
+- **Mode Switch**: Press Tab to cycle through modes
+- **Palette Switch**: Press 1-5 to switch color palettes
+
+## Controls
+
+### Keyboard
+- **A-Z**: Play notes and paint
+- **Space**: Toggle ambient beat
+- **Backspace**: Clear canvas
+- **Tab**: Switch mode
+- **R**: Toggle recording
+- **S**: Save as PNG
+- **1-5**: Switch color palette
+
+### Mouse
+- **Click**: Play random note and paint
+- **Drag**: Continuous painting
+- **Hover over notes**: Replay sounds
+
+### Touch
+- **Touch and drag**: Paint with sound
+
+## Technical Details
+
+- Zero dependencies
+- Pure HTML5 Canvas + Web Audio API
+- No external libraries
+- Self-contained single HTML file
+
+## Integration
+
+The playground is integrated into The Nexus as a portal:
+- **Portal ID**: `playground`
+- **Portal Type**: `creative-tool`
+- **Status**: Online
+- **Access**: Visitor mode (no operator privileges needed)
+
+## Iteration Plan
+
+Future enhancements:
+- [ ] More modes (Spiral, Gravity Well, Strobe)
+- [ ] MIDI keyboard support
+- [ ] Share session as URL
+- [ ] Mobile optimization
+- [ ] Multiplayer via WebSocket
+- [ ] Integration with Nexus spatial audio system
+- [ ] Memory system for saved compositions
+
+## File Structure
+
+```
+playground/
+├── playground.html    # Main playground application
+└── README.md         # This file
+```
+
+## Credits
+
+Created as part of the Timmy Foundation's Sovereign Sound initiative.

playground/playground.html

@@ -0,0 +1,692 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
+<title>Sovereign Sound — Playground</title>
+<style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+html, body { height: 100%; overflow: hidden; }
+body {
+  background: #050510;
+  font-family: 'SF Mono', 'Fira Code', monospace;
+  color: #fff;
+  cursor: none;
+  user-select: none;
+  -webkit-user-select: none;
+  touch-action: none;
+}
+canvas { display: block; position: fixed; top: 0; left: 0; }
+.piano {
+  position: fixed; bottom: 0; left: 0; right: 0;
+  height: 80px; display: flex;
+  background: rgba(0,0,0,0.3);
+  backdrop-filter: blur(10px);
+  -webkit-backdrop-filter: blur(10px);
+  z-index: 10;
+}
+.key {
+  flex: 1; border-right: 1px solid rgba(255,255,255,0.05);
+  display: flex; align-items: flex-end; justify-content: center;
+  padding-bottom: 8px; font-size: 9px; opacity: 0.3;
+  transition: all 0.1s; position: relative;
+}
+.key.black {
+  background: rgba(0,0,0,0.5);
+  height: 50px; margin: 0 -8px; width: 60%; z-index: 1;
+  border: 1px solid rgba(255,255,255,0.08);
+}
+.key.active {
+  background: rgba(255,255,255,0.15);
+  opacity: 0.8;
+  transform: scaleY(0.98);
+  transform-origin: bottom;
+}
+.hud {
+  position: fixed; top: 16px; left: 16px;
+  font-size: 9px; letter-spacing: 3px;
+  text-transform: uppercase; opacity: 0.2;
+  line-height: 2.2; z-index: 10;
+  pointer-events: none;
+}
+.mode-switch {
+  position: fixed; top: 16px; right: 16px;
+  display: flex; gap: 4px; z-index: 10;
+}
+.mode-dot {
+  width: 6px; height: 6px; border-radius: 50%;
+  background: rgba(255,255,255,0.15);
+  cursor: pointer; transition: all 0.3s;
+  pointer-events: all;
+}
+.mode-dot.active { background: rgba(255,255,255,0.6); transform: scale(1.4); }
+.toast {
+  position: fixed; top: 50%; left: 50%;
+  transform: translate(-50%, -50%);
+  font-size: 10px; letter-spacing: 6px;
+  text-transform: uppercase; opacity: 0;
+  transition: opacity 0.4s; pointer-events: none; z-index: 20;
+}
+.toast.show { opacity: 0.4; }
+.rec-dot {
+  position: fixed; top: 16px; left: 50%; transform: translateX(-50%);
+  width: 8px; height: 8px; border-radius: 50%;
+  background: #ff0040; opacity: 0;
+  transition: opacity 0.3s; z-index: 10;
+}
+.rec-dot.on { opacity: 1; animation: pulse 1s infinite; }
+@keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.3; } }
+</style>
+</head>
+<body>
+
+<canvas id="c"></canvas>
+
+<div class="hud" id="hud">
+  <div id="h-mode">FREE</div>
+  <div id="h-pal">AURORA</div>
+  <div id="h-notes">0 notes</div>
+  <div id="h-chord">—</div>
+</div>
+
+<div class="mode-switch" id="modes"></div>
+<div class="rec-dot" id="rec"></div>
+<div class="toast" id="toast"></div>
+
+<div class="piano" id="piano"></div>
+
+<script>
+// ═══════════════════════════════════════════════════════════════
+//  SOVEREIGN SOUND — PLAYGROUND v3
+//  The ultimate interactive audio-visual experience.
+//  Zero dependencies. Pure craft.
+// ═══════════════════════════════════════════════════════════════
+
+const canvas = document.getElementById('c');
+const ctx = canvas.getContext('2d');
+let W, H;
+
+function resize() {
+  W = canvas.width = innerWidth;
+  H = canvas.height = innerHeight;
+  ctx.fillStyle = '#050510';
+  ctx.fillRect(0, 0, W, H);
+}
+addEventListener('resize', resize); resize();
+
+// ═══════════════════════════════════════════════════════════════
+//  AUDIO ENGINE
+// ═══════════════════════════════════════════════════════════════
+
+let ac = null, master = null, analyser = null;
+
+function initAudio() {
+  if (ac) return;
+  ac = new AudioContext();
+  master = ac.createGain(); master.gain.value = 0.4;
+  
+  const wet = ac.createGain(); wet.gain.value = 0.2;
+  [0.037, 0.059, 0.083, 0.127].forEach(t => {
+    const d = ac.createDelay(1); d.delayTime.value = t;
+    const fb = ac.createGain(); fb.gain.value = 0.22;
+    master.connect(d); d.connect(fb); fb.connect(d); d.connect(wet);
+  });
+  wet.connect(ac.destination);
+  
+  analyser = ac.createAnalyser();
+  analyser.fftSize = 512;
+  analyser.smoothingTimeConstant = 0.8;
+  master.connect(analyser);
+  master.connect(ac.destination);
+}
+
+function freq(name) {
+  const n = { C:0,'C#':1,D:2,'D#':3,E:4,F:5,'F#':6,G:7,'G#':8,A:9,'A#':10,B:11 };
+  const nm = name.replace(/\d/,'');
+  const oct = parseInt(name.match(/\d/)?.[0] || 4);
+  return 440 * Math.pow(2, (n[nm] + (oct-4)*12 - 9) / 12);
+}
+
+function tone(f, type='sine', dur=0.5, vol=0.1) {
+  initAudio();
+  const t = ac.currentTime;
+  const o = ac.createOscillator();
+  const g = ac.createGain();
+  o.type = type; o.frequency.value = f;
+  g.gain.setValueAtTime(0, t);
+  g.gain.linearRampToValueAtTime(vol, t + 0.01);
+  g.gain.exponentialRampToValueAtTime(vol*0.3, t+dur*0.4);
+  g.gain.exponentialRampToValueAtTime(0.001, t+dur);
+  o.connect(g); g.connect(master);
+  o.start(t); o.stop(t+dur);
+}
+
+function kick() { initAudio(); const t=ac.currentTime; const o=ac.createOscillator(), g=ac.createGain(); o.type='sine'; o.frequency.setValueAtTime(80,t); o.frequency.exponentialRampToValueAtTime(30,t+0.12); g.gain.setValueAtTime(0.4,t); g.gain.exponentialRampToValueAtTime(0.001,t+0.15); o.connect(g); g.connect(master); o.start(t); o.stop(t+0.15); }
+function snare() { initAudio(); const t=ac.currentTime; const len=ac.sampleRate*0.06; const buf=ac.createBuffer(1,len,ac.sampleRate); const d=buf.getChannelData(0); for(let i=0;i<len;i++) d[i]=(Math.random()*2-1)*0.25; const s=ac.createBufferSource(); s.buffer=buf; const g=ac.createGain(); g.gain.setValueAtTime(0.2,t); g.gain.exponentialRampToValueAtTime(0.001,t+0.08); s.connect(g); g.connect(master); s.start(t); }
+function hat() { initAudio(); const t=ac.currentTime; const len=ac.sampleRate*0.025; const buf=ac.createBuffer(1,len,ac.sampleRate); const d=buf.getChannelData(0); for(let i=0;i<len;i++) d[i]=(Math.random()*2-1)*0.12; const s=ac.createBufferSource(); s.buffer=buf; const g=ac.createGain(); g.gain.setValueAtTime(0.1,t); g.gain.exponentialRampToValueAtTime(0.001,t+0.025); s.connect(g); g.connect(master); s.start(t); }
+
+// ═══════════════════════════════════════════════════════════════
+//  SCALES & PALETTES
+// ═══════════════════════════════════════════════════════════════
+
+const SCALES = {
+  AURORA:  { colors:['#ff6b6b','#ff9f43','#feca57','#48dbfb','#54a0ff','#5f27cd','#ff9ff3','#00d2d3'], notes:['C5','D5','E5','F5','G5','A5','B5','C6','D6','E6','C4','D4','E4','F4','G4','A4','B4','C5','D5','E5','F5','C2','D2','E2','F2','G2'], bg:[6,6,16], glow:'#ff9ff3' },
+  OCEAN:   { colors:['#0077b6','#00b4d8','#90e0ef','#48cae4','#023e8a','#ade8f4'], notes:['D5','E5','F#5','G5','A5','B5','C#6','D6','E6','D4','E4','F#4','G4','A4','B4','C#5','D5','E5','D3','E3','F#3','D2','E2','F#2','G2','A2'], bg:[4,12,22], glow:'#48cae4' },
+  EMBER:   { colors:['#ff4500','#ff6347','#ff7f50','#dc143c','#cd5c5c','#f08080'], notes:['C5','Eb5','F5','G5','Ab5','Bb5','C6','D5','Eb5','C4','Eb4','F4','G4','Ab4','Bb4','C5','D5','Eb5','C3','Eb3','F3','C2','Eb2','F2','G2','Ab2'], bg:[14,5,5], glow:'#ff6347' },
+  FOREST:  { colors:['#2d6a4f','#40916c','#52b788','#74c69d','#95d5b2','#b7e4c7'], notes:['E5','F#5','G5','A5','B5','C6','D6','E6','F#6','E4','F#4','G4','A4','B4','C5','D5','E5','F#5','E3','F#3','G3','E2','F#2','G2','A2','B2'], bg:[4,12,6], glow:'#52b788' },
+  NEON:    { colors:['#ff00ff','#00ffff','#ffff00','#ff0080','#00ff80','#8000ff'], notes:['C5','D5','E5','G5','A5','C6','D6','E6','G6','C4','D4','E4','G4','A4','C5','D5','E5','G5','C3','D3','E3','C2','D2','E2','G2','A2'], bg:[8,2,16], glow:'#00ffff' },
+};
+
+let palName = 'AURORA';
+let pal = SCALES[palName];
+const PAL_NAMES = Object.keys(SCALES);
+let palIdx = 0;
+
+// ═══════════════════════════════════════════════════════════════
+//  MODES
+// ═══════════════════════════════════════════════════════════════
+
+const MODES = ['FREE','GRAVITY','RAIN','CONSTELLATION','BPM','MIRROR'];
+let modeIdx = 0, mode = MODES[0];
+
+// ═══════════════════════════════════════════════════════════════
+//  STATE
+// ═══════════════════════════════════════════════════════════════
+
+let notes = [];        // permanent painted notes
+let particles = [];    // transient particles
+let ripples = [];      // ripple effects
+let raindrops = [];
+let mouseX = W/2, mouseY = H/2;
+let mouseDown = false;
+let time = 0;
+let ambientOn = false;
+let ambientStep = 0;
+let ambientTimer = null;
+let screenShake = 0;
+let lastPaintTime = 0;
+let recentNotes = [];
+let recording = false;
+let recordedNotes = [];
+
+// ═══════════════════════════════════════════════════════════════
+//  PIANO KEYBOARD — visual at bottom
+// ═══════════════════════════════════════════════════════════════
+
+const KEYS = 'qwertyuiopasdfghjklzxcvbnm';
+const IS_BLACK = [false,true,false,true,false,false,true,false,true,false,true,false,
+                  false,true,false,true,false,false,true,false,true,false,true,false,false,false];
+
+function buildPiano() {
+  const piano = document.getElementById('piano');
+  piano.innerHTML = '';
+  KEYS.split('').forEach((k, i) => {
+    const div = document.createElement('div');
+    div.className = 'key' + (IS_BLACK[i] ? ' black' : '');
+    div.dataset.key = k;
+    div.textContent = k.toUpperCase();
+    div.addEventListener('mousedown', () => triggerKey(k));
+    div.addEventListener('touchstart', (e) => { e.preventDefault(); triggerKey(k); });
+    piano.appendChild(div);
+  });
+}
+buildPiano();
+
+// Mode/palette dots
+const modesDiv = document.getElementById('modes');
+MODES.forEach((m, i) => {
+  const dot = document.createElement('div');
+  dot.className = 'mode-dot' + (i===0?' active':'');
+  dot.onclick = () => { modeIdx=i; mode=MODES[i]; updateDots(); toast(m); };
+  modesDiv.appendChild(dot);
+});
+PAL_NAMES.forEach((p, i) => {
+  const dot = document.createElement('div');
+  dot.className = 'mode-dot';
+  dot.style.background = SCALES[p].glow;
+  dot.style.opacity = '0.2';
+  if (i===0) { dot.classList.add('active'); dot.style.opacity='0.6'; }
+  dot.onclick = () => { palIdx=i; palName=p; pal=SCALES[p]; updateDots(); toast(p); };
+  modesDiv.appendChild(dot);
+});
+
+function updateDots() {
+  modesDiv.querySelectorAll('.mode-dot').forEach((d, i) => {
+    if (i < MODES.length) {
+      d.classList.toggle('active', i===modeIdx);
+    } else {
+      const pi = i - MODES.length;
+      d.classList.toggle('active', pi===palIdx);
+      d.style.opacity = pi===palIdx ? '0.6' : '0.2';
+    }
+  });
+  document.getElementById('h-mode').textContent = mode;
+  document.getElementById('h-pal').textContent = palName;
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  PAINT & PLAY
+// ═══════════════════════════════════════════════════════════════
+
+function paint(x, y, color, noteFreq, noteType, size=25) {
+  // Permanent splash
+  ctx.save();
+  ctx.globalAlpha = 0.06;
+  ctx.fillStyle = color;
+  ctx.beginPath(); ctx.arc(x, y, size*2, 0, Math.PI*2); ctx.fill();
+  
+  ctx.globalAlpha = 0.3;
+  ctx.beginPath();
+  const pts = 6+Math.floor(Math.random()*6);
+  for (let i=0; i<=pts; i++) {
+    const a = (i/pts)*Math.PI*2;
+    const r = size*(0.5+Math.random()*0.5);
+    i===0 ? ctx.moveTo(x+Math.cos(a)*r, y+Math.sin(a)*r) : ctx.lineTo(x+Math.cos(a)*r, y+Math.sin(a)*r);
+  }
+  ctx.closePath(); ctx.fill();
+  
+  ctx.globalAlpha = 0.8;
+  ctx.beginPath(); ctx.arc(x, y, size*0.12, 0, Math.PI*2); ctx.fill();
+  ctx.restore();
+  
+  notes.push({ x, y, radius: size, color, freq: noteFreq, type: noteType });
+  if (notes.length > 4000) notes.splice(0, 500);
+  
+  // Particles
+  for (let i=0; i<12; i++) {
+    const a = Math.random()*Math.PI*2;
+    const s = 1+Math.random()*4;
+    particles.push({ x, y, vx:Math.cos(a)*s, vy:Math.sin(a)*s, size:1+Math.random()*3, life:1, color });
+  }
+  if (particles.length > 400) particles.splice(0, 100);
+  
+  ripples.push({ x, y, color, size: size*0.3, maxSize: size*3, life:1 });
+  if (ripples.length > 25) ripples.shift();
+  
+  if (noteType === 'sawtooth' && noteFreq < 200) screenShake = 6;
+}
+
+function triggerKey(key) {
+  const i = KEYS.indexOf(key);
+  if (i < 0) return;
+  
+  const noteName = pal.notes[i % pal.notes.length];
+  const noteFreq = freq(noteName);
+  const isBass = i >= 21;
+  const noteType = isBass ? 'sawtooth' : (i%3===0 ? 'triangle' : 'sine');
+  
+  tone(noteFreq, noteType, isBass ? 0.3 : 0.6, isBass ? 0.18 : 0.12);
+  
+  const x = mouseX + (Math.random()-0.5)*50;
+  const y = mouseY + (Math.random()-0.5)*50;
+  paint(x, y, pal.colors[i % pal.colors.length], noteFreq, noteType, isBass ? 35+Math.random()*15 : 20+Math.random()*15);
+  
+  // Piano visual
+  const pianoKey = document.querySelector(`.key[data-key="${key}"]`);
+  if (pianoKey) {
+    pianoKey.classList.add('active');
+    pianoKey.style.background = pal.colors[i % pal.colors.length] + '30';
+    setTimeout(() => { pianoKey.classList.remove('active'); pianoKey.style.background = ''; }, 200);
+  }
+  
+  // Track for chord detection
+  recentNotes.push({ freq: noteFreq, time: Date.now() });
+  if (recentNotes.length > 10) recentNotes.shift();
+  detectChord();
+  
+  // Recording
+  if (recording) recordedNotes.push({ key, time: Date.now(), x, y });
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  CHORD DETECTION
+// ═══════════════════════════════════════════════════════════════
+
+function detectChord() {
+  const now = Date.now();
+  const recent = recentNotes.filter(n => now-n.time < 1500);
+  if (recent.length < 2) { document.getElementById('h-chord').textContent = '—'; return; }
+  
+  const freqs = recent.map(n => n.freq).sort((a,b) => a-b);
+  const ratios = [];
+  for (let i=1; i<freqs.length; i++) ratios.push(Math.round(1200*Math.log2(freqs[i]/freqs[0])));
+  
+  const patterns = { 'major':[0,400,700],'minor':[0,300,700],'7':[0,400,700,1000],'maj7':[0,400,700,1100],'min7':[0,300,700,1000],'power':[0,700],'sus4':[0,500,700],'sus2':[0,200,700],'dim':[0,300,600],'aug':[0,400,800] };
+  
+  let best = '—', bestScore = 0;
+  for (const [name, pat] of Object.entries(patterns)) {
+    let score = 0;
+    for (const p of pat) if (ratios.some(r => Math.abs(r-p) < 60)) score++;
+    score /= pat.length;
+    if (score > bestScore && score > 0.5) { bestScore = score; best = name; }
+  }
+  document.getElementById('h-chord').textContent = best;
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  MOUSE PLAYBACK — play notes by hovering
+// ═══════════════════════════════════════════════════════════════
+
+let lastPlayed = null, lastPlayT = 0;
+function checkPlay(x, y) {
+  const now = Date.now();
+  if (now-lastPlayT < 50) return;
+  let closest = null, closestD = Infinity;
+  for (const n of notes) {
+    const d = Math.hypot(x-n.x, y-n.y);
+    if (d < n.radius*1.4 && d < closestD) { closest = n; closestD = d; }
+  }
+  if (closest && closest !== lastPlayed) {
+    const vol = 0.05 + (1-closestD/closest.radius)*0.1;
+    tone(closest.freq, closest.type, 0.2, vol);
+    ripples.push({ x:closest.x, y:closest.y, color:closest.color, size:closest.radius*0.2, maxSize:closest.radius*1.5, life:1 });
+    for (let i=0; i<3; i++) {
+      const a = Math.random()*Math.PI*2;
+      particles.push({ x:closest.x, y:closest.y, vx:Math.cos(a)*1.5, vy:Math.sin(a)*1.5, size:1.5, life:1, color:closest.color });
+    }
+    lastPlayed = closest;
+    lastPlayT = now;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  AMBIENT BEAT
+// ═══════════════════════════════════════════════════════════════
+
+function ambientTick() {
+  if (!ambientOn) return;
+  const bpm = [72,60,80,66,128,90][palIdx];
+  const stepDur = 60000/bpm/4;
+  const beat = ambientStep % 16;
+  
+  if (beat%4===0) { kick(); screenShake=2; }
+  if (beat===4||beat===12) snare();
+  if (beat%2===1) hat();
+  
+  if (beat===0) {
+    const chords = [
+      [freq('C4'),freq('E4'),freq('G4')],
+      [freq('A3'),freq('C4'),freq('E4')],
+      [freq('F3'),freq('A3'),freq('C4')],
+      [freq('G3'),freq('B3'),freq('D4')]
+    ];
+    chords[Math.floor(ambientStep/16)%4].forEach(f => tone(f,'triangle',0.7,0.05));
+  }
+  
+  if (beat%2===0) {
+    const i = Math.floor(Math.random()*KEYS.length);
+    const k = KEYS[i];
+    const noteName = pal.notes[i % pal.notes.length];
+    paint(W/2+(Math.random()-0.5)*400, H/2+(Math.random()-0.5)*300,
+      pal.colors[i%pal.colors.length], freq(noteName), i>=21?'sawtooth':'sine', 10+Math.random()*8);
+  }
+  
+  ambientStep++;
+  ambientTimer = setTimeout(ambientTick, stepDur);
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  INPUT
+// ═══════════════════════════════════════════════════════════════
+
+function toast(msg) {
+  const el = document.getElementById('toast');
+  el.textContent = msg; el.classList.add('show');
+  setTimeout(() => el.classList.remove('show'), 1200);
+}
+
+document.addEventListener('keydown', e => {
+  const k = e.key.toLowerCase();
+  
+  if (k===' ') { e.preventDefault(); ambientOn=!ambientOn; ambientOn?(ambientStep=0,ambientTick(),toast('AMBIENT ON')):(clearTimeout(ambientTimer),toast('AMBIENT OFF')); return; }
+  if (k==='backspace') { e.preventDefault(); ctx.fillStyle='#050510'; ctx.fillRect(0,0,W,H); notes=[]; ripples=[]; particles=[]; raindrops=[]; toast('CLEARED'); return; }
+  if (k==='tab') { e.preventDefault(); modeIdx=(modeIdx+1)%MODES.length; mode=MODES[modeIdx]; updateDots(); toast(mode); return; }
+  if (k==='r') { recording=!recording; document.getElementById('rec').classList.toggle('on',recording); toast(recording?'REC ON':'REC OFF'); if(!recording&&recordedNotes.length) replayRecording(); return; }
+  if (k==='s') { e.preventDefault(); saveCanvas(); return; }
+  if (k>='1' && k<='5') { palIdx=parseInt(k)-1; palName=PAL_NAMES[palIdx]; pal=SCALES[palName]; updateDots(); toast(palName); return; }
+  
+  triggerKey(k);
+});
+
+canvas.addEventListener('mousemove', e => {
+  mouseX = e.clientX; mouseY = e.clientY;
+  checkPlay(mouseX, mouseY);
+  if (mouseDown && Date.now()-lastPaintTime > 40) {
+    const i = Math.floor(Math.random()*KEYS.length);
+    triggerKey(KEYS[i]);
+    lastPaintTime = Date.now();
+  }
+  if (Math.random()>0.65) {
+    particles.push({ x:mouseX, y:mouseY, vx:(Math.random()-0.5)*0.5, vy:(Math.random()-0.5)*0.5, size:1+Math.random()*1.5, life:1, color:'rgba(255,255,255,0.3)' });
+    if (particles.length>400) particles.splice(0,80);
+  }
+});
+
+canvas.addEventListener('mousedown', e => { mouseDown=true; triggerKey(KEYS[Math.floor(Math.random()*KEYS.length)]); });
+canvas.addEventListener('mouseup', () => mouseDown=false);
+
+// Touch
+canvas.addEventListener('touchmove', e => {
+  e.preventDefault();
+  const t = e.touches[0];
+  mouseX = t.clientX; mouseY = t.clientY;
+  checkPlay(mouseX, mouseY);
+  if (Date.now()-lastPaintTime > 60) {
+    triggerKey(KEYS[Math.floor(Math.random()*KEYS.length)]);
+    lastPaintTime = Date.now();
+  }
+}, { passive: false });
+
+// ═══════════════════════════════════════════════════════════════
+//  MODE EFFECTS
+// ═══════════════════════════════════════════════════════════════
+
+function applyGravity() {
+  for (const n of notes) {
+    const dx = mouseX-n.x, dy = mouseY-n.y;
+    const d = Math.hypot(dx, dy);
+    if (d>10 && d<300) { n.x += dx*0.2/d; n.y += dy*0.2/d; }
+  }
+}
+
+function spawnRain() {
+  if (Math.random()>0.2) return;
+  const i = Math.floor(Math.random()*KEYS.length);
+  raindrops.push({ x:Math.random()*W, y:-20, vy:1.5+Math.random()*3, color:pal.colors[i%pal.colors.length], freq:freq(pal.notes[i%pal.notes.length]), type:i>=21?'sawtooth':'sine', size:8+Math.random()*12, played:false });
+  if (raindrops.length>40) raindrops.shift();
+}
+
+function updateRain() {
+  for (let i=raindrops.length-1; i>=0; i--) {
+    const r = raindrops[i]; r.y += r.vy;
+    if (!r.played) for (const n of notes) {
+      if (Math.hypot(r.x-n.x, r.y-n.y) < n.radius) {
+        tone(r.freq, r.type, 0.3, 0.06);
+        ripples.push({ x:r.x, y:r.y, color:r.color, size:5, maxSize:25, life:1 });
+        r.played = true; break;
+      }
+    }
+    if (r.y > H) {
+      if (!r.played) { paint(r.x, H-20, r.color, r.freq, r.type, r.size); tone(r.freq, r.type, 0.3, 0.05); }
+      raindrops.splice(i, 1);
+    }
+  }
+}
+
+function drawConstellation() {
+  ctx.save();
+  for (let i=0; i<notes.length; i++) {
+    for (let j=i+1; j<notes.length; j++) {
+      const d = Math.hypot(notes[i].x-notes[j].x, notes[i].y-notes[j].y);
+      if (d < 180) {
+        ctx.globalAlpha = (1-d/180)*0.12;
+        ctx.strokeStyle = notes[i].color;
+        ctx.lineWidth = 0.5;
+        ctx.beginPath();
+        ctx.moveTo(notes[i].x, notes[i].y);
+        ctx.lineTo(notes[j].x, notes[j].y);
+        ctx.stroke();
+      }
+    }
+  }
+  ctx.restore();
+}
+
+function drawBPMGrid() {
+  const bpm = 120;
+  const beat = (time % (60/bpm)) / (60/bpm);
+  ctx.save();
+  ctx.strokeStyle = pal.colors[0];
+  ctx.lineWidth = 0.5 + beat;
+  ctx.globalAlpha = 0.02 + beat*0.03;
+  for (let x=0; x<W; x+=80) { ctx.beginPath(); ctx.moveTo(x,0); ctx.lineTo(x,H); ctx.stroke(); }
+  for (let y=0; y<H; y+=80) { ctx.beginPath(); ctx.moveTo(0,y); ctx.lineTo(W,y); ctx.stroke(); }
+  ctx.restore();
+}
+
+function drawMirror() {
+  // Mirror notes across vertical axis
+  ctx.save();
+  ctx.globalAlpha = 0.08;
+  for (const n of notes) {
+    ctx.fillStyle = n.color;
+    ctx.beginPath();
+    ctx.arc(W-n.x, n.y, n.radius*0.6, 0, Math.PI*2);
+    ctx.fill();
+  }
+  ctx.restore();
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  RECORDING & EXPORT
+// ═══════════════════════════════════════════════════════════════
+
+function replayRecording() {
+  if (!recordedNotes.length) return;
+  toast(`REPLAY ${recordedNotes.length} notes`);
+  const start = recordedNotes[0].time;
+  recordedNotes.forEach(n => {
+    setTimeout(() => triggerKey(n.key), n.time - start);
+  });
+  recordedNotes = [];
+}
+
+function saveCanvas() {
+  const link = document.createElement('a');
+  link.download = `sovereign-${Date.now()}.png`;
+  link.href = canvas.toDataURL();
+  link.click();
+  toast('SAVED');
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  RENDER LOOP
+// ═══════════════════════════════════════════════════════════════
+
+function render() {
+  time += 0.016;
+  
+  if (screenShake > 0) { ctx.save(); ctx.translate((Math.random()-0.5)*screenShake,(Math.random()-0.5)*screenShake); screenShake*=0.85; if(screenShake<0.5)screenShake=0; }
+  
+  // Mode effects
+  if (mode==='GRAVITY') applyGravity();
+  if (mode==='RAIN') { spawnRain(); updateRain(); }
+  if (mode==='CONSTELLATION') drawConstellation();
+  if (mode==='BPM') drawBPMGrid();
+  if (mode==='MIRROR') drawMirror();
+  
+  // Ripples
+  for (let i=ripples.length-1; i>=0; i--) {
+    const r = ripples[i];
+    r.size += (r.maxSize-r.size)*0.07;
+    r.life -= 0.02;
+    if (r.life<=0) { ripples.splice(i,1); continue; }
+    ctx.globalAlpha = r.life*0.3;
+    ctx.strokeStyle = r.color;
+    ctx.lineWidth = 1.5*r.life;
+    ctx.beginPath(); ctx.arc(r.x,r.y,r.size,0,Math.PI*2); ctx.stroke();
+  }
+  
+  // Rain
+  for (const r of raindrops) {
+    ctx.globalAlpha = 0.4;
+    ctx.fillStyle = r.color;
+    ctx.beginPath(); ctx.arc(r.x,r.y,r.size*0.2,0,Math.PI*2); ctx.fill();
+  }
+  
+  // Particles
+  for (let i=particles.length-1; i>=0; i--) {
+    const p = particles[i];
+    p.x+=p.vx; p.y+=p.vy; p.vx*=0.96; p.vy*=0.96; p.life-=0.014;
+    if (p.life<=0) { particles.splice(i,1); continue; }
+    ctx.globalAlpha = p.life*0.5;
+    ctx.fillStyle = p.color;
+    ctx.beginPath(); ctx.arc(p.x,p.y,p.size*p.life,0,Math.PI*2); ctx.fill();
+  }
+  
+  // Audio-reactive
+  if (analyser) {
+    const data = new Uint8Array(analyser.frequencyBinCount);
+    analyser.getByteFrequencyData(data);
+    let energy = 0;
+    for (let i=0; i<data.length; i++) energy += data[i];
+    energy /= data.length*255;
+    
+    if (energy > 0.08) {
+      const grad = ctx.createRadialGradient(W/2,H/2,0,W/2,H/2,200+energy*200);
+      grad.addColorStop(0, pal.glow+'08');
+      grad.addColorStop(1, 'transparent');
+      ctx.fillStyle = grad;
+      ctx.globalAlpha = 0.3+energy*0.3;
+      ctx.fillRect(0,0,W,H);
+    }
+    
+    // Edge frequency bars
+    ctx.globalAlpha = 0.03;
+    for (let i=0; i<data.length; i++) {
+      const v = data[i]/255;
+      if (v<0.08) continue;
+      ctx.fillStyle = pal.colors[i%pal.colors.length];
+      ctx.fillRect((i/data.length)*W, H-v*40-80, 2, v*40); // above piano
+    }
+  }
+  
+  if (screenShake > 0) ctx.restore();
+  
+  // Cursor
+  ctx.save();
+  ctx.strokeStyle = '#fff';
+  ctx.lineWidth = 1;
+  ctx.globalAlpha = 0.5;
+  ctx.beginPath();
+  ctx.moveTo(mouseX-8,mouseY); ctx.lineTo(mouseX-3,mouseY);
+  ctx.moveTo(mouseX+3,mouseY); ctx.lineTo(mouseX+8,mouseY);
+  ctx.moveTo(mouseX,mouseY-8); ctx.lineTo(mouseX,mouseY-3);
+  ctx.moveTo(mouseX,mouseY+3); ctx.lineTo(mouseX,mouseY+8);
+  ctx.stroke();
+  
+  // Color ring when hovering note
+  for (const n of notes) {
+    if (Math.hypot(mouseX-n.x, mouseY-n.y) < n.radius*1.4) {
+      ctx.strokeStyle = n.color;
+      ctx.globalAlpha = 0.35;
+      ctx.beginPath(); ctx.arc(mouseX, mouseY, 12, 0, Math.PI*2); ctx.stroke();
+      break;
+    }
+  }
+  
+  ctx.globalAlpha = 0.8;
+  ctx.fillStyle = '#fff';
+  ctx.beginPath(); ctx.arc(mouseX,mouseY,1.5,0,Math.PI*2); ctx.fill();
+  ctx.restore();
+  
+  // HUD
+  document.getElementById('h-notes').textContent = `${notes.length} notes`;
+  
+  requestAnimationFrame(render);
+}
+
+render();
+</script>
+</body>
+</html>

portals.json

@@ -6,24 +6,6 @@
     "status": "online",
     "color": "#ff6600",
     "role": "pilot",
-    "position": { "x": 15, "y": 0, "z": -10 },
-    "rotation": { "y": -0.5 },
-    "portal_type": "game-world",
-    "world_category": "rpg",
-    "environment": "local",
-    "access_mode": "operator",
-    "readiness_state": "prototype",
-    "readiness_steps": {
-      "prototype": { "label": "Prototype", "done": true },
-      "runtime_ready": { "label": "Runtime Ready", "done": false },
-      "launched": { "label": "Launched", "done": false },
-      "harness_bridged": { "label": "Harness Bridged", "done": false }
-    },
-    "blocked_reason": null,
-    "telemetry_source": "hermes-harness:morrowind",
-    "owner": "Timmy",
-    "app_id": 22320,
-    "window_title": "OpenMW",
     "position": {
       "x": 15,
       "y": 0,
@@ -32,12 +14,38 @@
     "rotation": {
       "y": -0.5
     },
+    "portal_type": "game-world",
+    "world_category": "rpg",
+    "environment": "local",
+    "access_mode": "operator",
+    "readiness_state": "prototype",
+    "readiness_steps": {
+      "prototype": {
+        "label": "Prototype",
+        "done": true
+      },
+      "runtime_ready": {
+        "label": "Runtime Ready",
+        "done": false
+      },
+      "launched": {
+        "label": "Launched",
+        "done": false
+      },
+      "harness_bridged": {
+        "label": "Harness Bridged",
+        "done": false
+      }
+    },
+    "blocked_reason": null,
+    "telemetry_source": "hermes-harness:morrowind",
+    "owner": "Timmy",
+    "app_id": 22320,
+    "window_title": "OpenMW",
     "destination": {
       "url": null,
       "type": "harness",
       "action_label": "Enter Vvardenfell",
-      "params": { "world": "vvardenfell" }
-    }
       "params": {
         "world": "vvardenfell"
       }
@@ -54,8 +62,6 @@
     "status": "downloaded",
     "color": "#ffd700",
     "role": "pilot",
-    "position": { "x": -15, "y": 0, "z": -10 },
-    "rotation": { "y": 0.5 },
     "position": {
       "x": -15,
       "y": 0,
@@ -110,8 +116,6 @@
     "status": "online",
     "color": "#4af0c0",
     "role": "timmy",
-    "position": { "x": 0, "y": 0, "z": -20 },
-    "rotation": { "y": 0 },
     "position": {
       "x": 0,
       "y": 0,
@@ -140,8 +144,6 @@
     "status": "online",
     "color": "#0066ff",
     "role": "timmy",
-    "position": { "x": 25, "y": 0, "z": 0 },
-    "rotation": { "y": -1.57 },
     "position": {
       "x": 25,
       "y": 0,
@@ -169,8 +171,6 @@
     "status": "online",
     "color": "#ffd700",
     "role": "timmy",
-    "position": { "x": -25, "y": 0, "z": 0 },
-    "rotation": { "y": 1.57 },
     "position": {
       "x": -25,
       "y": 0,
@@ -196,8 +196,6 @@
     "status": "online",
     "color": "#4af0c0",
     "role": "reflex",
-    "position": { "x": 15, "y": 0, "z": 10 },
-    "rotation": { "y": -2.5 },
     "position": {
       "x": 15,
       "y": 0,
@@ -226,8 +224,6 @@
     "status": "standby",
     "color": "#ff4466",
     "role": "reflex",
-    "position": { "x": -15, "y": 0, "z": 10 },
-    "rotation": { "y": 2.5 },
     "position": {
       "x": -15,
       "y": 0,
@@ -245,5 +241,55 @@
     },
     "agents_present": [],
     "interaction_ready": false
+  },
+  {
+    "id": "playground",
+    "name": "Sound Playground",
+    "description": "Interactive audio-visual experience. Paint with sound, create music visually.",
+    "status": "online",
+    "color": "#ff00ff",
+    "role": "creative",
+    "position": {
+      "x": 10,
+      "y": 0,
+      "z": 15
+    },
+    "rotation": {
+      "y": -0.7
+    },
+    "portal_type": "creative-tool",
+    "world_category": "audio-visual",
+    "environment": "production",
+    "access_mode": "visitor",
+    "readiness_state": "online",
+    "readiness_steps": {
+      "prototype": {
+        "label": "Prototype",
+        "done": true
+      },
+      "runtime_ready": {
+        "label": "Runtime Ready",
+        "done": true
+      },
+      "launched": {
+        "label": "Launched",
+        "done": true
+      },
+      "harness_bridged": {
+        "label": "Harness Bridged",
+        "done": true
+      }
+    },
+    "blocked_reason": null,
+    "telemetry_source": "playground",
+    "owner": "Timmy",
+    "destination": {
+      "url": "./playground/playground.html",
+      "type": "local",
+      "action_label": "Enter Playground",
+      "params": {}
+    },
+    "agents_present": [],
+    "interaction_ready": true
   }
 ]

preview.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# preview.sh — One-command preview for The Nexus
+# ./preview.sh          — http://localhost:8080
+# ./preview.sh 3000     — custom port
+# ./preview.sh docker   — Docker/nginx
+set -euo pipefail
+PORT="${1:-8080}"
+if [ "$PORT" = "docker" ]; then
+    echo "==> Nexus preview via Docker/nginx..."
+    docker compose up -d nexus-preview
+    echo "==> http://localhost:8080"
+    exit 0
+fi
+if ! command -v python3 &> /dev/null; then
+    echo "Error: python3 not found. Use './preview.sh docker'"
+    exit 1
+fi
+echo "==> Nexus preview on http://localhost:$PORT"
+python3 -c "
+import http.server, socketserver
+class H(http.server.SimpleHTTPRequestHandler):
+    def end_headers(self):
+        self.send_header('Access-Control-Allow-Origin','*')
+        super().end_headers()
+    def guess_type(self,p):
+        if p.endswith('.js') or p.endswith('.mjs'): return 'application/javascript'
+        if p.endswith('.css'): return 'text/css'
+        if p.endswith('.json'): return 'application/json'
+        return super().guess_type(p)
+with socketserver.TCPServer(('', $PORT), H) as s:
+    print(f'Serving http://localhost:{$PORT}')
+    s.serve_forever()
+"

preview/nginx.conf

@@ -0,0 +1,51 @@
+server {
+    listen 8080;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+        add_header X-Frame-Options "SAMEORIGIN" always;
+        add_header X-Content-Type-Options "nosniff" always;
+    }
+
+    location ~* \.js$ {
+        types { application/javascript js; }
+        add_header Cache-Control "public, max-age=3600";
+    }
+
+    location ~* \.css$ {
+        types { text/css css; }
+        add_header Cache-Control "public, max-age=3600";
+    }
+
+    location ~* \.json$ {
+        types { application/json json; }
+        add_header Cache-Control "no-cache";
+    }
+
+    location /api/world/ws {
+        proxy_pass http://nexus-backend:8765;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_read_timeout 86400;
+    }
+
+    location /ws {
+        proxy_pass http://nexus-backend:8765;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_read_timeout 86400;
+    }
+
+    location /health {
+        return 200 '{"status":"ok","service":"nexus-preview"}';
+        add_header Content-Type application/json;
+    }
+}

style.css

@@ -2685,3 +2685,252 @@ body.operator-mode #mode-label {
   color: #ffd700;
 }
 
+/* ═══ REASONING TRACE COMPONENT ═══ */
+
+.reasoning-trace {
+  width: 320px;
+  max-height: 400px;
+  display: flex;
+  flex-direction: column;
+}
+
+.trace-header-container {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 4px;
+}
+
+.trace-header-container .panel-header {
+  margin-bottom: 0;
+  border-bottom: none;
+  padding-bottom: 0;
+}
+
+.trace-icon {
+  margin-right: 4px;
+}
+
+.trace-controls {
+  display: flex;
+  gap: 4px;
+}
+
+.trace-btn {
+  background: rgba(74, 240, 192, 0.1);
+  border: 1px solid rgba(74, 240, 192, 0.2);
+  color: #4af0c0;
+  padding: 2px 6px;
+  font-size: 10px;
+  cursor: pointer;
+  border-radius: 2px;
+  transition: all 0.2s ease;
+}
+
+.trace-btn:hover {
+  background: rgba(74, 240, 192, 0.2);
+  border-color: #4af0c0;
+}
+
+.trace-task {
+  font-size: 9px;
+  color: #8899aa;
+  margin-bottom: 4px;
+  padding: 2px 6px;
+  background: rgba(0, 0, 0, 0.2);
+  border-radius: 2px;
+  font-family: 'JetBrains Mono', monospace;
+}
+
+.trace-task.active {
+  color: #4af0c0;
+  background: rgba(74, 240, 192, 0.1);
+  border-left: 2px solid #4af0c0;
+}
+
+.trace-counter {
+  font-size: 9px;
+  color: #667788;
+  margin-bottom: 6px;
+  font-family: 'JetBrains Mono', monospace;
+}
+
+.trace-content {
+  flex: 1;
+  overflow-y: auto;
+  max-height: 300px;
+}
+
+.trace-step {
+  margin-bottom: 8px;
+  padding: 6px;
+  background: rgba(0, 0, 0, 0.2);
+  border-radius: 3px;
+  border-left: 3px solid #4af0c0;
+  transition: all 0.2s ease;
+}
+
+.trace-step-think {
+  border-left-color: #4af0c0;
+}
+
+.trace-step-decide {
+  border-left-color: #ffd700;
+}
+
+.trace-step-recall {
+  border-left-color: #7b5cff;
+}
+
+.trace-step-plan {
+  border-left-color: #ff8c42;
+}
+
+.trace-step-execute {
+  border-left-color: #ff4466;
+}
+
+.trace-step-verify {
+  border-left-color: #4af0c0;
+}
+
+.trace-step-doubt {
+  border-left-color: #ff8c42;
+}
+
+.trace-step-memory {
+  border-left-color: #7b5cff;
+}
+
+.trace-step-header {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-bottom: 4px;
+  font-size: 10px;
+}
+
+.step-icon {
+  font-size: 12px;
+}
+
+.step-type {
+  font-weight: 700;
+  letter-spacing: 0.5px;
+  font-family: 'JetBrains Mono', monospace;
+}
+
+.step-time {
+  color: #667788;
+  font-size: 9px;
+  margin-left: auto;
+  font-family: 'JetBrains Mono', monospace;
+}
+
+.confidence-bar {
+  font-family: 'JetBrains Mono', monospace;
+  font-size: 9px;
+  color: #4af0c0;
+  letter-spacing: -1px;
+  margin-left: 4px;
+}
+
+.trace-step-content {
+  font-size: 11px;
+  line-height: 1.4;
+  color: #d9f7ff;
+}
+
+.step-thought {
+  margin-bottom: 4px;
+  font-style: italic;
+  color: #e0f0ff;
+}
+
+.step-reasoning {
+  margin-bottom: 4px;
+  color: #aabbcc;
+  font-size: 10px;
+  padding-left: 8px;
+  border-left: 1px solid rgba(74, 240, 192, 0.2);
+}
+
+.step-decision {
+  margin-bottom: 4px;
+  color: #ffd700;
+  font-size: 10px;
+}
+
+.step-alternatives {
+  margin-bottom: 4px;
+  color: #8899aa;
+  font-size: 10px;
+}
+
+.step-source {
+  margin-bottom: 4px;
+  color: #7b5cff;
+  font-size: 10px;
+}
+
+.trace-separator {
+  height: 1px;
+  background: linear-gradient(90deg, transparent, rgba(74, 240, 192, 0.2), transparent);
+  margin: 6px 0;
+}
+
+.trace-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 20px;
+  color: #667788;
+  text-align: center;
+}
+
+.empty-icon {
+  font-size: 24px;
+  margin-bottom: 8px;
+  opacity: 0.5;
+}
+
+.empty-text {
+  font-size: 11px;
+  margin-bottom: 4px;
+  font-family: 'JetBrains Mono', monospace;
+}
+
+.empty-hint {
+  font-size: 9px;
+  color: #445566;
+  font-family: 'JetBrains Mono', monospace;
+}
+
+/* Animation for new steps */
+@keyframes trace-step-in {
+  from {
+    opacity: 0;
+    transform: translateY(-10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.trace-step {
+  animation: trace-step-in 0.3s ease-out;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+  .reasoning-trace {
+    width: 280px;
+  }
+  
+  .trace-content {
+    max-height: 200px;
+  }
+}
+

tests/boot.test.js

@@ -0,0 +1,20 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { bootPage } = require('../boot.js');
+const el = (tagName = 'div') => ({ tagName, textContent: '', innerHTML: '', style: {}, children: [], type: '', src: '', appendChild(child) { this.children.push(child); } });
+
+test('bootPage handles file and http origins', () => {
+  const loaderSubtitle = el(), bootMessage = el(), body = el('body');
+  const doc = { body, querySelector: s => s === '.loader-subtitle' ? loaderSubtitle : null, getElementById: id => id === 'boot-message' ? bootMessage : null, createElement: tag => el(tag) };
+  const fileResult = bootPage({ location: { protocol: 'file:' } }, doc);
+  assert.equal(fileResult.mode, 'file');
+  assert.equal(body.children.length, 0);
+  assert.match(loaderSubtitle.textContent, /serve this world over http/i);
+  assert.match(bootMessage.innerHTML, /python3 -m http\.server 8888/i);
+  const httpResult = bootPage({ location: { protocol: 'http:' } }, doc);
+  assert.equal(httpResult.mode, 'module');
+  assert.equal(body.children.length, 1);
+  assert.equal(body.children[0].tagName, 'script');
+  assert.equal(body.children[0].type, 'module');
+  assert.equal(body.children[0].src, './bootstrap.mjs');
+});

tests/bootstrap.test.mjs

@@ -0,0 +1,28 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readFileSync } from 'node:fs';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '..');
+const load = () => import(pathToFileURL(path.join(repoRoot, 'bootstrap.mjs')).href);
+const el = () => ({ textContent: '', innerHTML: '', style: {}, className: '' });
+
+test('boot shows file guidance', async () => {
+  const { boot } = await load();
+  const subtitle = el(), msg = el(); let calls = 0;
+  const result = await boot({ win: { location: { protocol: 'file:' } }, doc: { getElementById: id => id === 'boot-message' ? msg : null, querySelector: s => s === '.loader-subtitle' ? subtitle : null }, importApp: async () => (calls += 1, {}) });
+  assert.equal(result.mode, 'file'); assert.equal(calls, 0); assert.match(subtitle.textContent, /serve/i); assert.match(msg.innerHTML, /python3 -m http\.server 8888/i);
+});
+
+test('sanitizer repairs synthetic and real app input', async () => {
+  const { sanitizeAppModuleSource, loadAppModule, boot } = await load();
+  const synthetic = ["import ResonanceVisualizer from './nexus/components/resonance-visualizer.js';\\nimport * as THREE from 'three';","const calibrator = boot();\\n  startRenderer();","import { SymbolicEngine, AgentFSM } from './nexus/symbolic-engine.js';","class SymbolicEngine {}","/**\n * Process Evennia-specific fields from Hermes WS messages.\n * Called from handleHermesMessage for any message carrying evennia metadata.\n */\nfunction handleEvenniaEvent(data) {\n  if (data.evennia_command) {\n    addActionStreamEntry('cmd', data.evennia_command);\n  }\n}\n\n\n// ═══════════════════════════════════════════\nfunction handleHermesMessage(data) {\n  if (data.type === 'history') {\n    return;\n  }\n  } else if (data.type && data.type.startsWith('evennia.')) {\n    handleEvenniaEvent(data);\n  // Evennia event bridge — process command/result/room fields if present\n  handleEvenniaEvent(data);\n}","logs.innerHTML = ok;\n    // Actual MemPalace initialization would happen here\n    // For demo purposes we'll just show status\n    statusEl.textContent = 'Connected to local MemPalace';\n    statusEl.style.color = '#4af0c0';\n    \n    // Simulate mining process\n    mineMemPalaceContent(\"Initial knowledge base setup complete\");\n  } catch (err) {\n    console.error('Failed to initialize MemPalace:', err);\n    document.getElementById('mem-palace-status').textContent = 'MemPalace ERROR';\n    document.getElementById('mem-palace-status').style.color = '#ff4466';\n  }\n  try {","  // Auto-mine chat every 30s\n  setInterval(mineMemPalaceContent, 30000);\n    try {\n      const status = mempalace.status();\n      document.getElementById('compression-ratio').textContent = status.compression_ratio.toFixed(1) + 'x';\n      document.getElementById('docs-mined').textContent = status.total_docs;\n      document.getElementById('aaak-size').textContent = status.aaak_size + 'B';\n    } catch (error) {\n      console.error('Failed to update MemPalace status:', error);\n    }\n  }\n\n  // Auto-mine chat history every 30s\n"].join('\n');
+  const fixed = sanitizeAppModuleSource(synthetic), real = sanitizeAppModuleSource(readFileSync(path.join(repoRoot, 'app.js'), 'utf8'));
+  for (const text of [fixed, real]) { assert.doesNotMatch(text, /;\\n|from '\.\/nexus\/symbolic-engine\.js'|\n  \}\n  \} else if|Connected to local MemPalace|setInterval\(mineMemPalaceContent, 30000\);\n    try \{/); }
+  assert.match(fixed, /resonance-visualizer\.js';\nimport \* as THREE/); assert.match(fixed, /boot\(\);\n  startRenderer\(\);/);
+  let calls = 0; const imported = await boot({ win: { location: { protocol: 'http:' } }, doc: { getElementById() { return null; }, querySelector() { return null; }, createElement() { return { type: '', textContent: '', onload: null, onerror: null }; }, body: { appendChild(node) { node.onload(); } } }, importApp: async () => (calls += 1, {}) });
+  assert.equal(imported.mode, 'imported'); assert.equal(calls, 1);
+  const appended = []; const script = await loadAppModule({ doc: { createElement() { return { type: '', textContent: '', onload: null, onerror: null }; }, body: { appendChild(node) { appended.push(node); node.onload(); } } }, fetchImpl: async () => ({ ok: true, text: async () => "import * as THREE from 'three';" }) });
+  assert.equal(appended.length, 1); assert.equal(script, appended[0]); assert.equal(script.type, 'module');
+});

tests/test_a2a.py

@@ -0,0 +1,763 @@
+"""
+Tests for A2A Protocol implementation.
+
+Covers:
+- Type serialization roundtrips (Agent Card, Task, Message, Artifact, Part)
+- JSON-RPC envelope
+- Agent Card building from YAML config
+- Registry operations (register, list, filter)
+- Client/server integration (end-to-end task delegation)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import pytest
+from pathlib import Path
+from unittest.mock import AsyncMock, patch, MagicMock
+
+from nexus.a2a.types import (
+    A2AError,
+    AgentCard,
+    AgentCapabilities,
+    AgentInterface,
+    AgentSkill,
+    Artifact,
+    DataPart,
+    FilePart,
+    JSONRPCError,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    Message,
+    Role,
+    Task,
+    TaskState,
+    TaskStatus,
+    TextPart,
+    part_from_dict,
+    part_to_dict,
+)
+from nexus.a2a.card import build_card, load_card_config
+from nexus.a2a.registry import LocalFileRegistry
+
+
+# === Type Serialization Roundtrips ===
+
+
+class TestTextPart:
+    def test_roundtrip(self):
+        p = TextPart(text="hello world")
+        d = p.to_dict()
+        assert d == {"text": "hello world"}
+        p2 = part_from_dict(d)
+        assert isinstance(p2, TextPart)
+        assert p2.text == "hello world"
+
+    def test_custom_media_type(self):
+        p = TextPart(text="data", media_type="text/markdown")
+        d = p.to_dict()
+        assert d["mediaType"] == "text/markdown"
+        p2 = part_from_dict(d)
+        assert p2.media_type == "text/markdown"
+
+
+class TestFilePart:
+    def test_inline_roundtrip(self):
+        p = FilePart(media_type="image/png", raw="base64data", filename="img.png")
+        d = p.to_dict()
+        assert d["raw"] == "base64data"
+        assert d["filename"] == "img.png"
+        p2 = part_from_dict(d)
+        assert isinstance(p2, FilePart)
+        assert p2.raw == "base64data"
+
+    def test_url_roundtrip(self):
+        p = FilePart(media_type="application/pdf", url="https://example.com/doc.pdf")
+        d = p.to_dict()
+        assert d["url"] == "https://example.com/doc.pdf"
+        p2 = part_from_dict(d)
+        assert isinstance(p2, FilePart)
+        assert p2.url == "https://example.com/doc.pdf"
+
+
+class TestDataPart:
+    def test_roundtrip(self):
+        p = DataPart(data={"key": "value", "count": 42})
+        d = p.to_dict()
+        assert d["data"] == {"key": "value", "count": 42}
+        p2 = part_from_dict(d)
+        assert isinstance(p2, DataPart)
+        assert p2.data["count"] == 42
+
+
+class TestMessage:
+    def test_roundtrip(self):
+        msg = Message(
+            role=Role.USER,
+            parts=[TextPart(text="Hello agent")],
+            metadata={"priority": "high"},
+        )
+        d = msg.to_dict()
+        assert d["role"] == "ROLE_USER"
+        assert d["parts"] == [{"text": "Hello agent"}]
+        assert d["metadata"]["priority"] == "high"
+
+        msg2 = Message.from_dict(d)
+        assert msg2.role == Role.USER
+        assert isinstance(msg2.parts[0], TextPart)
+        assert msg2.parts[0].text == "Hello agent"
+        assert msg2.metadata["priority"] == "high"
+
+    def test_multi_part(self):
+        msg = Message(
+            role=Role.AGENT,
+            parts=[
+                TextPart(text="Here's the report"),
+                DataPart(data={"status": "healthy"}),
+            ],
+        )
+        d = msg.to_dict()
+        assert len(d["parts"]) == 2
+        msg2 = Message.from_dict(d)
+        assert len(msg2.parts) == 2
+        assert isinstance(msg2.parts[0], TextPart)
+        assert isinstance(msg2.parts[1], DataPart)
+
+
+class TestArtifact:
+    def test_roundtrip(self):
+        art = Artifact(
+            parts=[TextPart(text="result data")],
+            name="report",
+            description="CI health report",
+        )
+        d = art.to_dict()
+        assert d["name"] == "report"
+        assert d["description"] == "CI health report"
+
+        art2 = Artifact.from_dict(d)
+        assert art2.name == "report"
+        assert isinstance(art2.parts[0], TextPart)
+        assert art2.parts[0].text == "result data"
+
+
+class TestTask:
+    def test_roundtrip(self):
+        task = Task(
+            id="test-123",
+            status=TaskStatus(state=TaskState.WORKING),
+            history=[
+                Message(role=Role.USER, parts=[TextPart(text="Do X")]),
+            ],
+        )
+        d = task.to_dict()
+        assert d["id"] == "test-123"
+        assert d["status"]["state"] == "TASK_STATE_WORKING"
+
+        task2 = Task.from_dict(d)
+        assert task2.id == "test-123"
+        assert task2.status.state == TaskState.WORKING
+        assert len(task2.history) == 1
+
+    def test_with_artifacts(self):
+        task = Task(
+            id="art-task",
+            status=TaskStatus(state=TaskState.COMPLETED),
+            artifacts=[
+                Artifact(
+                    parts=[TextPart(text="42")],
+                    name="answer",
+                )
+            ],
+        )
+        d = task.to_dict()
+        assert len(d["artifacts"]) == 1
+        task2 = Task.from_dict(d)
+        assert task2.artifacts[0].name == "answer"
+
+    def test_terminal_states(self):
+        for state in [
+            TaskState.COMPLETED,
+            TaskState.FAILED,
+            TaskState.CANCELED,
+            TaskState.REJECTED,
+        ]:
+            assert state.terminal is True
+
+        for state in [
+            TaskState.SUBMITTED,
+            TaskState.WORKING,
+            TaskState.INPUT_REQUIRED,
+            TaskState.AUTH_REQUIRED,
+        ]:
+            assert state.terminal is False
+
+
+class TestAgentCard:
+    def test_roundtrip(self):
+        card = AgentCard(
+            name="TestAgent",
+            description="A test agent",
+            version="1.0.0",
+            supported_interfaces=[
+                AgentInterface(url="http://localhost:8080/a2a/v1")
+            ],
+            capabilities=AgentCapabilities(streaming=True),
+            skills=[
+                AgentSkill(
+                    id="test-skill",
+                    name="Test Skill",
+                    description="Does tests",
+                    tags=["test"],
+                )
+            ],
+        )
+        d = card.to_dict()
+        assert d["name"] == "TestAgent"
+        assert d["capabilities"]["streaming"] is True
+        assert len(d["skills"]) == 1
+        assert d["skills"][0]["id"] == "test-skill"
+
+        card2 = AgentCard.from_dict(d)
+        assert card2.name == "TestAgent"
+        assert card2.skills[0].id == "test-skill"
+        assert card2.capabilities.streaming is True
+
+
+class TestJSONRPC:
+    def test_request_roundtrip(self):
+        req = JSONRPCRequest(
+            method="SendMessage",
+            params={"message": {"text": "hello"}},
+        )
+        d = req.to_dict()
+        assert d["jsonrpc"] == "2.0"
+        assert d["method"] == "SendMessage"
+
+    def test_response_success(self):
+        resp = JSONRPCResponse(
+            id="req-1",
+            result={"task": {"id": "t1"}},
+        )
+        d = resp.to_dict()
+        assert "error" not in d
+        assert d["result"]["task"]["id"] == "t1"
+
+    def test_response_error(self):
+        resp = JSONRPCResponse(
+            id="req-1",
+            error=A2AError.TASK_NOT_FOUND,
+        )
+        d = resp.to_dict()
+        assert "result" not in d
+        assert d["error"]["code"] == -32001
+
+
+# === Agent Card Building ===
+
+
+class TestBuildCard:
+    def test_basic_config(self):
+        config = {
+            "name": "Bezalel",
+            "description": "CI/CD specialist",
+            "version": "2.0.0",
+            "url": "https://bezalel.example.com",
+            "skills": [
+                {
+                    "id": "ci-health",
+                    "name": "CI Health",
+                    "description": "Check CI",
+                    "tags": ["ci"],
+                },
+                {
+                    "id": "deploy",
+                    "name": "Deploy",
+                    "description": "Deploy services",
+                    "tags": ["ops"],
+                },
+            ],
+        }
+        card = build_card(config)
+        assert card.name == "Bezalel"
+        assert card.version == "2.0.0"
+        assert len(card.skills) == 2
+        assert card.skills[0].id == "ci-health"
+        assert card.supported_interfaces[0].url == "https://bezalel.example.com"
+
+    def test_bearer_auth(self):
+        config = {
+            "name": "Test",
+            "description": "Test",
+            "auth": {"scheme": "bearer", "token_env": "MY_TOKEN"},
+        }
+        card = build_card(config)
+        assert "bearerAuth" in card.security_schemes
+        assert card.security_requirements[0]["schemes"]["bearerAuth"] == {"list": []}
+
+    def test_api_key_auth(self):
+        config = {
+            "name": "Test",
+            "description": "Test",
+            "auth": {"scheme": "api_key", "key_name": "X-Custom-Key"},
+        }
+        card = build_card(config)
+        assert "apiKeyAuth" in card.security_schemes
+
+
+# === Registry ===
+
+
+class TestLocalFileRegistry:
+    def _make_card(self, name: str, skills: list[dict] | None = None) -> AgentCard:
+        return AgentCard(
+            name=name,
+            description=f"Agent {name}",
+            supported_interfaces=[
+                AgentInterface(url=f"http://{name}:8080/a2a/v1")
+            ],
+            skills=[
+                AgentSkill(
+                    id=s["id"],
+                    name=s.get("name", s["id"]),
+                    description=s.get("description", ""),
+                    tags=s.get("tags", []),
+                )
+                for s in (skills or [])
+            ],
+        )
+
+    def test_register_and_list(self, tmp_path):
+        registry = LocalFileRegistry(tmp_path / "agents.json")
+        registry.register(self._make_card("ezra"))
+        registry.register(self._make_card("allegro"))
+
+        agents = registry.list_agents()
+        assert len(agents) == 2
+        names = {a.name for a in agents}
+        assert names == {"ezra", "allegro"}
+
+    def test_filter_by_skill(self, tmp_path):
+        registry = LocalFileRegistry(tmp_path / "agents.json")
+        registry.register(
+            self._make_card("ezra", [{"id": "ci-health", "tags": ["ci"]}])
+        )
+        registry.register(
+            self._make_card("allegro", [{"id": "research", "tags": ["research"]}])
+        )
+
+        ci_agents = registry.list_agents(skill="ci-health")
+        assert len(ci_agents) == 1
+        assert ci_agents[0].name == "ezra"
+
+    def test_filter_by_tag(self, tmp_path):
+        registry = LocalFileRegistry(tmp_path / "agents.json")
+        registry.register(
+            self._make_card("ezra", [{"id": "ci", "tags": ["devops", "ci"]}])
+        )
+        registry.register(
+            self._make_card("allegro", [{"id": "research", "tags": ["research"]}])
+        )
+
+        devops_agents = registry.list_agents(tag="devops")
+        assert len(devops_agents) == 1
+        assert devops_agents[0].name == "ezra"
+
+    def test_persistence(self, tmp_path):
+        path = tmp_path / "agents.json"
+        reg1 = LocalFileRegistry(path)
+        reg1.register(self._make_card("ezra"))
+
+        # Load fresh from disk
+        reg2 = LocalFileRegistry(path)
+        agents = reg2.list_agents()
+        assert len(agents) == 1
+        assert agents[0].name == "ezra"
+
+    def test_unregister(self, tmp_path):
+        registry = LocalFileRegistry(tmp_path / "agents.json")
+        registry.register(self._make_card("ezra"))
+        assert len(registry.list_agents()) == 1
+
+        assert registry.unregister("ezra") is True
+        assert len(registry.list_agents()) == 0
+        assert registry.unregister("nonexistent") is False
+
+    def test_get_endpoint(self, tmp_path):
+        registry = LocalFileRegistry(tmp_path / "agents.json")
+        registry.register(self._make_card("ezra"))
+
+        url = registry.get_endpoint("ezra")
+        assert url == "http://ezra:8080/a2a/v1"
+
+
+# === Server Integration (FastAPI required) ===
+
+
+try:
+    from fastapi.testclient import TestClient
+    HAS_TEST_CLIENT = True
+except ImportError:
+    HAS_TEST_CLIENT = False
+
+
+@pytest.mark.skipif(not HAS_TEST_CLIENT, reason="fastapi not installed")
+class TestA2AServerIntegration:
+    """End-to-end tests using FastAPI TestClient."""
+
+    def _make_server(self, auth_token: str = ""):
+        from nexus.a2a.server import A2AServer, echo_handler
+
+        card = AgentCard(
+            name="TestAgent",
+            description="Test agent for A2A",
+            supported_interfaces=[
+                AgentInterface(url="http://localhost:8080/a2a/v1")
+            ],
+            capabilities=AgentCapabilities(streaming=False),
+            skills=[
+                AgentSkill(
+                    id="echo",
+                    name="Echo",
+                    description="Echo back messages",
+                    tags=["test"],
+                )
+            ],
+        )
+
+        server = A2AServer(card=card, auth_token=auth_token)
+        server.register_handler("echo", echo_handler)
+        server.set_default_handler(echo_handler)
+        return server
+
+    def test_agent_card_well_known(self):
+        server = self._make_server()
+        client = TestClient(server.app)
+
+        resp = client.get("/.well-known/agent-card.json")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["name"] == "TestAgent"
+        assert len(data["skills"]) == 1
+
+    def test_agent_card_fallback(self):
+        server = self._make_server()
+        client = TestClient(server.app)
+
+        resp = client.get("/agent.json")
+        assert resp.status_code == 200
+        assert resp.json()["name"] == "TestAgent"
+
+    def test_send_message(self):
+        server = self._make_server()
+        client = TestClient(server.app)
+
+        rpc_request = {
+            "jsonrpc": "2.0",
+            "id": "test-1",
+            "method": "SendMessage",
+            "params": {
+                "message": {
+                    "messageId": "msg-1",
+                    "role": "ROLE_USER",
+                    "parts": [{"text": "Hello from test"}],
+                },
+                "configuration": {
+                    "acceptedOutputModes": ["text/plain"],
+                    "historyLength": 10,
+                    "returnImmediately": False,
+                },
+            },
+        }
+
+        resp = client.post("/a2a/v1", json=rpc_request)
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "result" in data
+        assert "task" in data["result"]
+
+        task = data["result"]["task"]
+        assert task["status"]["state"] == "TASK_STATE_COMPLETED"
+        assert len(task["artifacts"]) == 1
+        assert "Echo" in task["artifacts"][0]["parts"][0]["text"]
+
+    def test_get_task(self):
+        server = self._make_server()
+        client = TestClient(server.app)
+
+        # Create a task first
+        send_req = {
+            "jsonrpc": "2.0",
+            "id": "s1",
+            "method": "SendMessage",
+            "params": {
+                "message": {
+                    "messageId": "m1",
+                    "role": "ROLE_USER",
+                    "parts": [{"text": "get me"}],
+                },
+                "configuration": {},
+            },
+        }
+        send_resp = client.post("/a2a/v1", json=send_req)
+        task_id = send_resp.json()["result"]["task"]["id"]
+
+        # Now fetch it
+        get_req = {
+            "jsonrpc": "2.0",
+            "id": "g1",
+            "method": "GetTask",
+            "params": {"id": task_id},
+        }
+        get_resp = client.post("/a2a/v1", json=get_req)
+        assert get_resp.status_code == 200
+        assert get_resp.json()["result"]["id"] == task_id
+
+    def test_get_nonexistent_task(self):
+        server = self._make_server()
+        client = TestClient(server.app)
+
+        req = {
+            "jsonrpc": "2.0",
+            "id": "g2",
+            "method": "GetTask",
+            "params": {"id": "nonexistent"},
+        }
+        resp = client.post("/a2a/v1", json=req)
+        assert resp.status_code == 400
+        data = resp.json()
+        assert "error" in data
+
+    def test_list_tasks(self):
+        server = self._make_server()
+        client = TestClient(server.app)
+
+        # Create two tasks
+        for i in range(2):
+            req = {
+                "jsonrpc": "2.0",
+                "id": f"s{i}",
+                "method": "SendMessage",
+                "params": {
+                    "message": {
+                        "messageId": f"m{i}",
+                        "role": "ROLE_USER",
+                        "parts": [{"text": f"task {i}"}],
+                    },
+                    "configuration": {},
+                },
+            }
+            client.post("/a2a/v1", json=req)
+
+        list_req = {
+            "jsonrpc": "2.0",
+            "id": "l1",
+            "method": "ListTasks",
+            "params": {"pageSize": 10},
+        }
+        resp = client.post("/a2a/v1", json=list_req)
+        assert resp.status_code == 200
+        tasks = resp.json()["result"]["tasks"]
+        assert len(tasks) >= 2
+
+    def test_cancel_task(self):
+        from nexus.a2a.server import A2AServer
+
+        # Create a server with a slow handler so task stays WORKING
+        async def slow_handler(task, card):
+            import asyncio
+            await asyncio.sleep(10)  # never reached in test
+            task.status = TaskStatus(state=TaskState.COMPLETED)
+            return task
+
+        card = AgentCard(name="SlowAgent", description="Slow test agent")
+        server = A2AServer(card=card)
+        server.set_default_handler(slow_handler)
+        client = TestClient(server.app)
+
+        # Create a task (but we need to intercept before handler runs)
+        # Instead, manually insert a task and test cancel on it
+        task = Task(
+            id="cancel-me",
+            status=TaskStatus(state=TaskState.WORKING),
+            history=[
+                Message(role=Role.USER, parts=[TextPart(text="cancel me")])
+            ],
+        )
+        server._tasks[task.id] = task
+
+        # Cancel it
+        cancel_req = {
+            "jsonrpc": "2.0",
+            "id": "c2",
+            "method": "CancelTask",
+            "params": {"id": "cancel-me"},
+        }
+        cancel_resp = client.post("/a2a/v1", json=cancel_req)
+        assert cancel_resp.status_code == 200
+        assert cancel_resp.json()["result"]["status"]["state"] == "TASK_STATE_CANCELED"
+
+    def test_auth_required(self):
+        server = self._make_server(auth_token="secret123")
+        client = TestClient(server.app)
+
+        # No auth header — should get 401
+        req = {
+            "jsonrpc": "2.0",
+            "id": "a1",
+            "method": "SendMessage",
+            "params": {
+                "message": {
+                    "messageId": "am1",
+                    "role": "ROLE_USER",
+                    "parts": [{"text": "hello"}],
+                },
+                "configuration": {},
+            },
+        }
+        resp = client.post("/a2a/v1", json=req)
+        assert resp.status_code == 401
+
+    def test_auth_success(self):
+        server = self._make_server(auth_token="secret123")
+        client = TestClient(server.app)
+
+        req = {
+            "jsonrpc": "2.0",
+            "id": "a2",
+            "method": "SendMessage",
+            "params": {
+                "message": {
+                    "messageId": "am2",
+                    "role": "ROLE_USER",
+                    "parts": [{"text": "authenticated"}],
+                },
+                "configuration": {},
+            },
+        }
+        resp = client.post(
+            "/a2a/v1",
+            json=req,
+            headers={"Authorization": "Bearer secret123"},
+        )
+        assert resp.status_code == 200
+        assert resp.json()["result"]["task"]["status"]["state"] == "TASK_STATE_COMPLETED"
+
+    def test_unknown_method(self):
+        server = self._make_server()
+        client = TestClient(server.app)
+
+        req = {
+            "jsonrpc": "2.0",
+            "id": "u1",
+            "method": "NonExistentMethod",
+            "params": {},
+        }
+        resp = client.post("/a2a/v1", json=req)
+        assert resp.status_code == 400
+        assert resp.json()["error"]["code"] == -32602
+
+    def test_audit_log(self):
+        server = self._make_server()
+        client = TestClient(server.app)
+
+        req = {
+            "jsonrpc": "2.0",
+            "id": "au1",
+            "method": "SendMessage",
+            "params": {
+                "message": {
+                    "messageId": "aum1",
+                    "role": "ROLE_USER",
+                    "parts": [{"text": "audit me"}],
+                },
+                "configuration": {},
+            },
+        }
+        client.post("/a2a/v1", json=req)
+        client.post("/a2a/v1", json=req)
+
+        log = server.get_audit_log()
+        assert len(log) == 2
+        assert all(entry["method"] == "SendMessage" for entry in log)
+
+
+# === Custom Handler Test ===
+
+
+@pytest.mark.skipif(not HAS_TEST_CLIENT, reason="fastapi not installed")
+class TestCustomHandlers:
+    """Test custom task handlers."""
+
+    def test_skill_routing(self):
+        from nexus.a2a.server import A2AServer
+        from nexus.a2a.types import Task, AgentCard
+
+        async def ci_handler(task: Task, card: AgentCard) -> Task:
+            task.artifacts.append(
+                Artifact(
+                    parts=[TextPart(text="CI pipeline healthy: 5/5 passed")],
+                    name="ci_report",
+                )
+            )
+            task.status = TaskStatus(state=TaskState.COMPLETED)
+            return task
+
+        card = AgentCard(
+            name="CI Agent",
+            description="CI specialist",
+            skills=[AgentSkill(id="ci-health", name="CI Health", description="Check CI", tags=["ci"])],
+        )
+        server = A2AServer(card=card)
+        server.register_handler("ci-health", ci_handler)
+
+        client = TestClient(server.app)
+        req = {
+            "jsonrpc": "2.0",
+            "id": "h1",
+            "method": "SendMessage",
+            "params": {
+                "message": {
+                    "messageId": "hm1",
+                    "role": "ROLE_USER",
+                    "parts": [{"text": "Check CI"}],
+                    "metadata": {"targetSkill": "ci-health"},
+                },
+                "configuration": {},
+            },
+        }
+        resp = client.post("/a2a/v1", json=req)
+        task_data = resp.json()["result"]["task"]
+        assert task_data["status"]["state"] == "TASK_STATE_COMPLETED"
+        assert "5/5 passed" in task_data["artifacts"][0]["parts"][0]["text"]
+
+    def test_handler_error(self):
+        from nexus.a2a.server import A2AServer
+        from nexus.a2a.types import Task, AgentCard
+
+        async def failing_handler(task: Task, card: AgentCard) -> Task:
+            raise RuntimeError("Handler blew up")
+
+        card = AgentCard(name="Fail Agent", description="Fails")
+        server = A2AServer(card=card)
+        server.set_default_handler(failing_handler)
+
+        client = TestClient(server.app)
+        req = {
+            "jsonrpc": "2.0",
+            "id": "f1",
+            "method": "SendMessage",
+            "params": {
+                "message": {
+                    "messageId": "fm1",
+                    "role": "ROLE_USER",
+                    "parts": [{"text": "break"}],
+                },
+                "configuration": {},
+            },
+        }
+        resp = client.post("/a2a/v1", json=req)
+        task_data = resp.json()["result"]["task"]
+        assert task_data["status"]["state"] == "TASK_STATE_FAILED"
+        assert "blew up" in task_data["status"]["message"]["parts"][0]["text"].lower()

tests/test_fleet_audit.py

@@ -0,0 +1,143 @@
+"""Tests for fleet_audit — Deduplicate Agents, One Identity Per Machine."""
+import json
+import tempfile
+from pathlib import Path
+
+import pytest
+import yaml
+
+# Adjust import path
+import sys
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "bin"))
+
+from fleet_audit import (
+    AuditFinding,
+    validate_registry,
+    cross_reference_registry_agents,
+    audit_git_authors,
+)
+
+
+# ---------------------------------------------------------------------------
+# Identity registry validation tests
+# ---------------------------------------------------------------------------
+
+class TestValidateRegistry:
+    """Test identity registry validation rules."""
+
+    def _make_registry(self, agents):
+        return {"version": 1, "agents": agents, "rules": {"one_identity_per_machine": True}}
+
+    def test_clean_registry_passes(self):
+        registry = self._make_registry([
+            {"name": "allegro", "machine": "167.99.126.228", "role": "burn", "gitea_user": "allegro"},
+            {"name": "ezra", "machine": "143.198.27.163", "role": "triage", "gitea_user": "ezra"},
+        ])
+        findings = validate_registry(registry)
+        critical = [f for f in findings if f.severity == "critical"]
+        assert len(critical) == 0
+
+    def test_same_name_on_different_machines_detected(self):
+        registry = self._make_registry([
+            {"name": "allegro", "machine": "167.99.126.228", "role": "burn"},
+            {"name": "allegro", "machine": "104.131.15.18", "role": "burn"},
+        ])
+        findings = validate_registry(registry)
+        critical = [f for f in findings if f.severity == "critical" and f.category == "duplicate"]
+        # Two findings: one for name-on-multiple-machines, one for duplicate name
+        assert len(critical) >= 1
+        machine_findings = [f for f in critical if "registered on" in f.description]
+        assert len(machine_findings) == 1
+        assert "167.99.126.228" in machine_findings[0].description
+        assert "104.131.15.18" in machine_findings[0].description
+
+    def test_multiple_agents_same_machine_ok(self):
+        # Multiple different agents on the same VPS is normal.
+        registry = self._make_registry([
+            {"name": "allegro", "machine": "167.99.126.228", "role": "burn"},
+            {"name": "bilbo", "machine": "167.99.126.228", "role": "queries"},
+        ])
+        findings = validate_registry(registry)
+        critical = [f for f in findings if f.severity == "critical"]
+        assert len(critical) == 0
+
+    def test_duplicate_name_detected(self):
+        registry = self._make_registry([
+            {"name": "bezalel", "machine": "104.131.15.18", "role": "ci"},
+            {"name": "bezalel", "machine": "167.99.126.228", "role": "ci"},
+        ])
+        findings = validate_registry(registry)
+        name_dupes = [f for f in findings if f.severity == "critical" and "bezalel" in f.description.lower() and "registered on" in f.description.lower()]
+        assert len(name_dupes) == 1
+
+    def test_duplicate_gitea_user_detected(self):
+        registry = self._make_registry([
+            {"name": "agent-a", "machine": "host1", "role": "x", "gitea_user": "shared"},
+            {"name": "agent-b", "machine": "host2", "role": "x", "gitea_user": "shared"},
+        ])
+        findings = validate_registry(registry)
+        gitea_dupes = [f for f in findings if "Gitea user 'shared'" in f.description]
+        assert len(gitea_dupes) == 1
+        assert "agent-a" in gitea_dupes[0].affected
+        assert "agent-b" in gitea_dupes[0].affected
+
+    def test_missing_required_fields(self):
+        registry = self._make_registry([
+            {"name": "incomplete-agent"},
+        ])
+        findings = validate_registry(registry)
+        missing = [f for f in findings if f.category == "orphan"]
+        assert len(missing) >= 1
+        assert "machine" in missing[0].description or "role" in missing[0].description
+
+    def test_empty_registry_passes(self):
+        registry = self._make_registry([])
+        findings = validate_registry(registry)
+        assert len(findings) == 0
+
+
+# ---------------------------------------------------------------------------
+# Cross-reference tests
+# ---------------------------------------------------------------------------
+
+class TestCrossReference:
+    """Test registry vs fleet-routing.json cross-reference."""
+
+    def test_orphan_in_fleet_not_registry(self):
+        reg_agents = [{"name": "allegro", "machine": "x", "role": "y"}]
+        fleet_agents = [{"name": "allegro", "location": "x"}, {"name": "unknown-agent", "location": "y"}]
+        findings = cross_reference_registry_agents(reg_agents, fleet_agents)
+        orphans = [f for f in findings if f.category == "orphan" and "unknown-agent" in f.description]
+        assert len(orphans) == 1
+
+    def test_location_mismatch_detected(self):
+        reg_agents = [{"name": "allegro", "machine": "167.99.126.228", "role": "y"}]
+        fleet_agents = [{"name": "allegro", "location": "totally-different-host"}]
+        findings = cross_reference_registry_agents(reg_agents, fleet_agents)
+        mismatches = [f for f in findings if f.category == "duplicate" and "different locations" in f.description]
+        assert len(mismatches) == 1
+
+
+# ---------------------------------------------------------------------------
+# Integration test against actual registry
+# ---------------------------------------------------------------------------
+
+class TestRealRegistry:
+    """Test against the actual identity-registry.yaml in the repo."""
+
+    def test_registry_loads(self):
+        reg_path = Path(__file__).resolve().parent.parent / "fleet" / "identity-registry.yaml"
+        if reg_path.exists():
+            with open(reg_path) as f:
+                registry = yaml.safe_load(f)
+            assert registry["version"] == 1
+            assert len(registry["agents"]) > 0
+
+    def test_registry_no_critical_findings(self):
+        reg_path = Path(__file__).resolve().parent.parent / "fleet" / "identity-registry.yaml"
+        if reg_path.exists():
+            with open(reg_path) as f:
+                registry = yaml.safe_load(f)
+            findings = validate_registry(registry)
+            critical = [f for f in findings if f.severity == "critical"]
+            assert len(critical) == 0, f"Critical findings: {[f.description for f in critical]}"

tests/test_index_html_integrity.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+
+
+def test_index_html_integrity():
+    text = (Path(__file__).resolve().parents[1] / 'index.html').read_text(encoding='utf-8')
+    for marker in ('<<<<<<<', '=======', '>>>>>>>', '```html', '⚠<EFBFBD>'):
+        assert marker not in text
+    assert 'index.html\n```html' not in text
+    for needle in ('View Contribution Policy', 'id="mem-palace-container"', 'id="mempalace-results"', 'id="memory-filter"', 'id="memory-feed"', 'id="memory-inspect-panel"', 'id="memory-connections-panel"'):
+        assert text.count(needle) == 1

world/multi_user_bridge.py

@@ -26,11 +26,18 @@ import threading
 import hashlib
 import os
 import sys
-from http.server import HTTPServer, BaseHTTPRequestHandler
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from socketserver import ThreadingMixIn
 from pathlib import Path
 from datetime import datetime
 from typing import Optional
 
+
+class ThreadingHTTPServer(ThreadingMixIn, HTTPServer):
+    """Thread-per-request server for concurrent multi-user handling."""
+    daemon_threads = True
+
+
 # ── Configuration ──────────────────────────────────────────────────────
 
 BRIDGE_PORT = int(os.environ.get('TIMMY_BRIDGE_PORT', 4004))
@@ -274,7 +281,7 @@ def main():
     print(f"  POST /bridge/move      — Move user to room (user_id, room)")
     print()
     
-    server = HTTPServer((BRIDGE_HOST, BRIDGE_PORT), BridgeHandler)
+    server = ThreadingHTTPServer((BRIDGE_HOST, BRIDGE_PORT), BridgeHandler)
     server.serve_forever()