docs: ground unified fleet sovereignty directive

Refs #524

GENOME.md

@@ -1,376 +1,209 @@
-# GENOME.md — timmy-config
+# GENOME.md — the-nexus
 
 ## Project Overview
 
-`timmy-config` is the sovereign configuration repository that defines Timmy's identity, operational policies, orchestration workflows, and software stack. It is a canonical **sidecar overlay** deployed onto the Hermes harness — separate from hermes-agent code, versioned independently, and applied to each machine via a GitOps pipeline.
+`the-nexus` is a hybrid repo that combines three layers in one codebase:
 
-The repo treats configuration as a first-class, code-like artifact: everything is version-controlled, everything is reviewable, everything is automatable. It is Timmy's DNA.
+1. A browser-facing world shell rooted in `index.html`, `boot.js`, `bootstrap.mjs`, `app.js`, `style.css`, `portals.json`, `vision.json`, `manifest.json`, and `gofai_worker.js`
+2. A Python realtime bridge centered on `server.py` plus harness code under `nexus/`
+3. A memory / fleet / operator layer spanning `mempalace/`, `mcp_servers/`, `multi_user_bridge.py`, and supporting scripts
 
-Grounded facts from this checkout (commit: STEP35-burn):
-- 646 total files: 228 Python (.py), 74 YAML, 49 shell scripts, 81 test files
-- Core lifecycle file: `deploy.sh` applies config to `~/.hermes/` and `~/.timmy/`
-- Central config: `config.yaml` defines model selection, toolset enablement, privacy, TTS/STT, delegation, memory budgets
-- Hermes state source: `~/.hermes/config.yaml` is a symlink → `~/.timmy-config/config.yaml` after deployment
-- Orchestration engine: Huey (SQLite-backed task queue) in `orchestration.py`, with scheduled work in `tasks.py`
-- Token tracking: Per-pipeline token logging to `~/.hermes/token_usage.jsonl` with daily budget enforcement
-- Git operations abstractions: `gitea_client.py` (pure stdlib HTTP JSON client with typed dataclasses)
-- Operational scripts: 35+ scripts in `bin/` covering dispatch, status, health-check, deadman, model loops, ops panels
-- Agent playbooks: YAML-defined behaviors in `playbooks/` for triage, bug-fixing, refactoring, security auditing
-- IaC layer: Ansible under `ansible/` defines fleet-wide golden state (roles: `wizard_base`, `golden_state`, `deadman_switch`, `request_log`, `cron_manager`)
-- Training factory: `training/` houses data generation, provenance pipelines, synthetic pair builders, evaluation rigs (`Makefile`-driven)
-- Memory layer: Persistent YAML memory files in `memories/` plus continuity doctrine in `docs/memory-continuity-doctrine.md`
-- UI skins: `skins/` contains Timmy-branded Hermes TUI skin assets
-- Scheduling: Cron job templates in `cron/` plus `definitions.yaml` and `jobs.json` for programmatic crontab management
+The repo is not a clean single-purpose frontend and not just a backend harness. It is a mixed world/runtime/ops repository where browser rendering, WebSocket telemetry, MCP-driven game harnesses, and fleet memory tooling coexist.
 
-Sidecar boundary explicitly codified: hermes-agent SHALL NOT fork timmy-config; timmy-config SHALL NOT modify hermes-agent code. The sidecar owns runtime policy; the harness owns runtime capability.
+Grounded repo facts from this checkout:
+- Browser shell files exist at repo root: `index.html`, `app.js`, `style.css`, `manifest.json`, `gofai_worker.js`
+- Data/config files also live at repo root: `portals.json`, `vision.json`
+- Realtime bridge exists in `server.py`
+- Game harnesses exist in `nexus/morrowind_harness.py` and `nexus/bannerlord_harness.py`
+- Memory/fleet sync exists in `mempalace/tunnel_sync.py`
+- Desktop/game automation MCP servers exist in `mcp_servers/desktop_control_server.py` and `mcp_servers/steam_info_server.py`
+- Validation exists in `tests/test_browser_smoke.py`, `tests/test_portals_json.py`, `tests/test_index_html_integrity.py`, and `tests/test_repo_truth.py`
+
+The current architecture is best understood as a sovereign world shell plus operator/game harness backend, with accumulated documentation drift from multiple restoration and migration efforts.
 
 ## Architecture Diagram
 
 ```mermaid
 graph TD
-    SOUL[SOUL.md<br/>On-chain identity / conscience]
-    CFG[config.yaml<br/>Hermes configuration overlay]
-    DEPLOY[deploy.sh<br/>Sidecar deployment script]
-    
-    ORCH[orchestration.py<br/>Huey task queue engine]
-    TASKS[tasks.py<br/>Scheduled @huey.task<br/>heartbeat<br/>triage<br/>budget enforcement]
-    
-    GITEA[gitea_client.py<br/>Gitea REST API wrapper<br/>(std urllib, typed)]
-    
-    BINS[bin/<br/>35+ operational scripts<br/>timmy-orchestrator.sh<br/>agent-dispatch.sh<br/>ops-panel.sh<br/>deadman-fallback.py]
-    
-    PLAY[playbooks/<br/>agent-lanes.json<br/>bug-fixer.yaml<br/>security-auditor.yaml<br/>refactor-specialist.yaml]
-    
-    ANSIBLE[ansible/<br/>site.yml + roles<br/>wizard_base<br/>golden_state<br/>deadman_switch<br/>cron_manager]
-    INV[inventory/hosts.yml<br/>fleet manifest]
-    
-    TRAINING[training/<br/>data-gen factories<br/>provenance rigs<br/>Makefile + scripts]
-    MEMORIES[memories/<br/>persistent YAML memory]
-    SKINS[skins/<br/>TUI skin assets]
-    
-    DOCS[docs/<br/>coordinator-first-protocol.md<br/>memory-continuity-doctrine.md<br/>automation-inventory.md]
-    
-    GIT[Gitea (Source of Truth)]
-    HP[~/.hermes/ (runtime overlay)]
-    WIZ[VPS / Machine target]
-    
-    subgraph Deploy-time
-        DEPLOY --> CFG
-        DEPLOY --> SOUL
-        SOUL -->|cp| HP
-        CFG -->|cp| HP
-    end
-    
-    subgraph Runtime
-        ORCH -->|queues| TASKS
-        TASKS -->|api| GITEA
-        BINS -->|script glue| GITEA
-        GITEA -->|REST| GIT
-    end
-    
-    subgraph Blueprint
-        PLAY -->|behaviors| TASKS
-        ANSIBLE -->|golden state| WIZ
-        INV --> ANSIBLE
-    end
-    
-    subgraph Knowledge
-        TRAINING -->|training pairs| DOCS
-        MEMORIES -->|long-term memory| HP
-        SKINS --> UI
-    end
-    
-    DEPLOY -- applies --> HP
-    ANSIBLE -- converges --> WIZ
+    browser[Index HTML Shell\nindex.html -> boot.js -> bootstrap.mjs -> app.js]
+    assets[Root Assets\nstyle.css\nmanifest.json\ngofai_worker.js]
+    data[World Data\nportals.json\nvision.json]
+    ws[Realtime Bridge\nserver.py\nWebSocket broadcast hub]
+    gofai[In-browser GOFAI\nSymbolicEngine\nNeuroSymbolicBridge\nsetupGOFAI/updateGOFAI]
+    harnesses[Python Harnesses\nnexus/morrowind_harness.py\nnexus/bannerlord_harness.py]
+    mcp[MCP Adapters\nmcp_servers/desktop_control_server.py\nmcp_servers/steam_info_server.py]
+    memory[Memory + Fleet\nmempalace/tunnel_sync.py\nmempalace.js]
+    bridge[Operator / MUD Bridge\nmulti_user_bridge.py\ncommands/timmy_commands.py]
+    tests[Verification\ntests/test_browser_smoke.py\ntests/test_portals_json.py\ntests/test_repo_truth.py]
+    docs[Contracts + Drift Docs\nBROWSER_CONTRACT.md\nREADME.md\nCLAUDE.md\nINVESTIGATION_ISSUE_1145.md]
+
+    browser --> assets
+    browser --> data
+    browser --> gofai
+    browser --> ws
+    harnesses --> mcp
+    harnesses --> ws
+    bridge --> ws
+    memory --> ws
+    tests --> browser
+    tests --> data
+    tests --> docs
+    docs --> browser
 ```
 
-Deployment flow (single machine):
-1. `./deploy.sh` copies `SOUL.md` → `~/.timmy/SOUL.md`, `config.yaml` → `~/.hermes/config.yaml`, `channel_directory.json` → `~/.hermes/channel_directory.json`
-2. `config_validator.py` runs pre-flight; aborts on YAML/JSON/cron syntax errors
-3. On Hermes create/startup, Huey loads `orchestration.py` and `tasks.py`, activates the task loop
-
-Fleet flow (multi-machine):
-1. PR merge to `timmy-config` → Gitea webhook fires
-2. `ansible/scripts/deploy_on_webhook.sh` runs on each target host (via ansible-pull or direct webhook endpoint)
-3. Each machine runs `ansible-playbook -i inventory/hosts.yml playbooks/site.yml --limit <hostname>`
-4. Convergence: files land at canonical paths, deadman switch installed, cron entries written, golden provider list validated
-
 ## Entry Points and Data Flow
 
 ### Primary entry points
 
-- `deploy.sh` — root entrypoint for local/sidecar deployment; symlinks `config.yaml` into `~/.hermes/` after schema validation via `scripts/config_validator.py`
-- `config.yaml` — harness configuration consumed at agent startup; controls model routing, toolset enablement, memory budgets, TTS provider
-- `orchestration.py` — declares `huey = SqliteHuey(...)` and defines `log_token_usage`, `check_budget`; this module is imported by `tasks.py`
-- `tasks.py` — contains @huey.task functions (`heartbeat`, `heartbeat_heavy`, `gitea_issue_triage`, `model_health_check`, `daily_reset`, `flush_continuity`, `orphan_work_cleanup`, `token_budget_enforcer`); these are the scheduled runtime workers
-- `bin/timmy-orchestrator.sh` — manual orchestrator loop for Timmy's governing logic; calls Gitea API to triage, assign, accept/reject PRs
-- `ansible/scripts/deploy_on_webhook.sh` — HTTP endpoint that clones timmy-config and runs ansible-pull; this is the automated fleet rendezvous
-- `ansible/playbooks/site.yml` — master playbook; runs everywhere and guarantees convergence to golden state (roles: `wizard_base`, `golden_state`, `deadman_switch`, `request_log`, `cron_manager`)
-- `gitea_client.py` — typed Python wrapper used by Huey tasks and bin scripts; discovers token from `~/.hermes/gitea_token`, `~/.hermes/gitea_token_vps`, or `~/.config/gitea/token`
+- `index.html` — root browser entry point
+- `boot.js` — startup selector; `tests/boot.test.js` shows it chooses file-mode vs HTTP/module-mode and injects `bootstrap.mjs` when served over HTTP
+- `bootstrap.mjs` — module bootstrap for the browser shell
+- `app.js` — main browser runtime; owns world state, GOFAI wiring, metrics polling, and portal/UI logic
+- `server.py` — WebSocket broadcast bridge on `ws://0.0.0.0:8765`
+- `nexus/morrowind_harness.py` — GamePortal/MCP harness for OpenMW Morrowind
+- `nexus/bannerlord_harness.py` — GamePortal/MCP harness for Bannerlord
+- `mempalace/tunnel_sync.py` — pulls remote fleet closets into the local palace over HTTP
+- `multi_user_bridge.py` — HTTP bridge for multi-user chat/session integration
+- `mcp_servers/desktop_control_server.py` — stdio MCP server exposing screenshots/mouse/keyboard control
 
 ### Data flow
 
-1. **Deploy-time**: `deploy.sh` → validate configs → copy `config.yaml`, `SOUL.md`, `channel_directory.json` to `~/.hermes/` → optionally rebuild caches; sidecar overlay is now live
-2. **Fleet sync**: `deploy_on_webhook.sh` triggers → clones timmy-config (depth-1, main) → runs `ansible-playbook` locally → Ansible roles write files, install cron entries, assert banned providers absent
-3. **Runtime loop**: `tasks.py` schedule (crontab + Huey periodic) → tasks import `gitea_client` → call Gitea REST API → mutate issues/PRs → log token usage to `~/.hermes/token_usage.jsonl`
-4. **Timer fidelity**: `cron/definitions.yaml` + `jobs.json` represent a declarative crontab overlay; `bin/pipeline-freshness.sh` compares Gitea pipeline registrations to local cron state to detect drift
-5. **Coordinator lane**: Timmy's state lives in running Huey + local ephemeris; any durable handoff must go through `flush_continuity(**kwargs)` → writes to `~/.timmy/daily-notes/YYYY-MM-DD.md`
-6. **Sidecar boundary enforcement**: `orchestration.py` and `tasks.py` read configuration from `~/.hermes/` — never from the repo's working copy; the deployed files are the runtime overlay, the Git checkout is only for upgrade/sync
-7. **Training dump**: `training/ingest_trajectories.py` reads session database, emits JSONL training pairs → `build_curated.py` filters/curates → `axolotl.yaml` defines LoRA recipe → `Makefile` runs training → `output/` gets LORA weights
+1. Browser startup begins at `index.html`
+2. `boot.js` decides whether the page is being served correctly; in HTTP mode it injects `bootstrap.mjs`
+3. `bootstrap.mjs` hands off to `app.js`
+4. `app.js` loads world configuration from `portals.json` and `vision.json`
+5. `app.js` constructs the Three.js scene and in-browser reasoning components, including `SymbolicEngine`, `NeuroSymbolicBridge`, `setupGOFAI()`, and `updateGOFAI()`
+6. Browser state and external runtimes connect through `server.py`, which broadcasts messages between connected clients
+7. Python harnesses (`nexus/morrowind_harness.py`, `nexus/bannerlord_harness.py`) spawn MCP subprocesses for desktop control / Steam metadata, capture state, execute actions, and feed telemetry into the Nexus bridge
+8. Memory/fleet tools like `mempalace/tunnel_sync.py` import remote palace data into local closets, extending what the operator/runtime layers can inspect
+9. Tests validate both the static browser contract and the higher-level repo-truth/memory contracts
 
 ### Important repo-specific runtime facts
 
-- `config.yaml` is both static config and dynamic override source; hermes-agent reloads only on process restart — config mutation in-place does NOT hot-reload
-- `bin/timmy-orchestrator.sh` is a single-instance guard loop; it writes PID to `~/.hermes/logs/timmy-orchestrator.pid` and refuses second start
-- Huey task results are persisted to `~/.hermes/orchestration.db` (SQLite); the `log_token_usage` hook augments every task with token accounting if the result dict contains `input_tokens`/`output_tokens`
-- `ansible/roles/golden_state` installs a provider chain list; `pre_tasks` in `site.yml` assert no banned provider (Anthropic/Claude names) appears anywhere
-- `training/provenance.py` walks the session database and builds `(prompt, response, metadata)` pairs with derivation chain; it is the source of truth for training-data license/consent
-- `bin/deadman-switch.sh` watches `tasks.py` heartbeat task misses and spins up a replacement agent process; it is the ops team's sleep insurance
-- `bin/quality-gate.py` checks that candidate PRs pass style-tests, have no banned providers, and operator review sign-off before merge eligibility
+- `portals.json` is a JSON array of portal/world/operator entries; examples in this checkout include `morrowind`, `bannerlord`, `workshop`, `archive`, `chapel`, and `courtyard`
+- `server.py` is a plain broadcast hub: clients send messages, the server forwards them to other connected clients
+- `nexus/morrowind_harness.py` and `nexus/bannerlord_harness.py` both implement a GamePortal pattern with MCP subprocess clients over stdio and WebSocket telemetry uplink
+- `mempalace/tunnel_sync.py` is not speculative; it is a real client that discovers remote wings, searches remote rooms, and writes `.closet.json` payloads locally
 
 ## Key Abstractions
 
-### Sidecar overlay pattern
+### Browser runtime
 
-The entire repository assumes a sidecar relationship: timmy-config is configuration and policy only. Hermes-agent is the engine. Deployment patches `~/.harness/` but never touches the agent's own code. This separation keeps agent upgrades independent of policy changes and keeps Timmy's soul and decision-determining weights composable.
+- `app.js`
+  - Defines in-browser reasoning/state machinery, including `class SymbolicEngine`, `class NeuroSymbolicBridge`, `setupGOFAI()`, and `updateGOFAI()`
+  - Couples rendering, local symbolic reasoning, metrics polling, and portal/UI logic in one very large root module
+- `BROWSER_CONTRACT.md`
+  - Acts like an executable architecture contract for the browser surface
+  - Declares required files, DOM IDs, Three.js expectations, provenance rules, and WebSocket expectations
 
-- Deploy script: `deploy.sh` (imperative, runs once)
-- Ansible playbooks: `ansible/playbooks/site.yml` + roles (declarative golden state)
-- Deployment gap bridge: `ansible/scripts/deploy_on_webhook.sh` (pulls → converges)
+### Realtime bridge
 
-### Huey orchestration
+- `server.py`
+  - Single hub abstraction: a WebSocket broadcast server maintaining a `clients` set and forwarding messages from one client to the others
+  - This is the seam between browser shell, harnesses, and external telemetry producers
 
-Scheduled and pipeline work is defined using `huey.SqliteHuey` (local SQLite queue, no Redis required). Each scheduled function is a `@huey.task` with periodic crontab hz. The heartbeat is a `@huey.periodic_task(minute='*/1')`; heavier work hourly. Token tracking is injected whenever result dicts carry token counts via `log_token_usage`.
+### GamePortal harness layer
 
-Key task categories:
-- **Heartbeat** (`heartbeat`, `heartbeat_heavy`) — regen local model checkpoints, verify Gitea reachability
-- **Triage** (`gitea_issue_triage`) — label, assign, apply trademark urgency, close stale
-- **Governance** (`orphan_work_cleanup`, `daily_reset`) — sanity enforcement, resource reclamation
-- **Budget** (`token_budget_enforcer`) — reads `~/.hermes/token_budget.json`, halts pipelines when daily caps are hit
+- `nexus/morrowind_harness.py`
+- `nexus/bannerlord_harness.py`
+  - Both define MCP client wrappers, `GameState` / `ActionResult`-style data classes, and an Observe-Decide-Act telemetry loop
+  - The harnesses are symmetric enough to be understood as reusable portal adapters with game-specific context injected on top
 
-### Gitea as coordination truth
+### Memory / fleet layer
 
-All work items, PRs, review state, and assignments are the shared state mechanism. The `gitea_client.py` abstracts HTTP calls into typed methods (`list_issues`, `create_comment`, `create_pr`, `merge_pr`). Multiple scripts use the same client library, guaranteeing consistent authentication and error handling.
+- `mempalace/tunnel_sync.py`
+  - Encodes the fleet-memory sync client contract: discover wings, pull broad room queries, write closet files, support dry-run
+- `mempalace.js`
+  - Minimal browser/Electron bridge to MemPalace commands via `window.electronAPI.execPython(...)`
+  - Important because it shows a second memory integration surface distinct from the Python fleet sync path
 
-Discovery: The client probes for token in three canonical locations:
-1. `~/.hermes/gitea_token` — local workstation token (user rockachopa)
-2. `~/.hermes/gitea_token_vps` — VPS operator token (Timmy Foundation service account)
-3. `~/.config/gitea/token` — platform default location (migration path)
+### Operator / interaction bridge
 
-### Golden state + deadman switch
-
-Ansible roles define fleet golden state; `deadman_switch` installs a watchdog cron entry and fallback dispatch script. If a heartbeat task fails to mark the agent alive within N minutes, the deadman switch triggers bounded rollback actions: re-deploy the previous known-good config, alert ops.
-
-The deadman boundary is narrow: it never re-deploys timmy-config on its own; it restarts the agent process and bumps a `deadman_active` flag for human-in-the-loop recovery.
-
-### Training data provenance
-
-`training/provenance.py` walks the local `~/.hermes/sessions/` and `~/.hermes/transcripts/` and emits provenance-rich training pairs. Each pair includes:
-- `session_id` and `timestamp` (session anchored)
-- `model_provider` and `model_name` (model grounded)
-- `consent_level` (user opt-in state at time of session)
-- `tool_call_trajectory` (observable action trace)
-- `license` (default: `CC-BY-SA-4.0` unless otherwise indicated)
-
-The pipeline enforces "no session, no data, no model" — training data without anchor to a signed-off transcript is rejected.
-
-### Coordinator-first protocol
-
-Timmy is the coordinator; Allegro is the ops integrator; infra automation supports both.
-
-The protocol: `intake → triage → route → track → verify → report`. Every work item goes through these six gates before a handoff is considered complete. The gate logic is codified in `docs/coordinator-first-protocol.md` and partially automated by `bin/timmy-orchestrator.sh`.
+- `multi_user_bridge.py`
+- `commands/timmy_commands.py`
+  - These bridge user-facing conversations or MUD/Evennia interactions back into Timmy/Nexus services
 
 ## API Surface
 
-### Configuration schema
+### Browser / static surface
 
-`config.yaml` defines the Hermes harness; governed by `scripts/config_validator.py`.
+- `index.html` served over HTTP
+- `boot.js` exports `bootPage()`; verified by `node --test tests/boot.test.js`
+- Data APIs are file-based inside the repo: `portals.json`, `vision.json`, `manifest.json`
 
-Top-level keys:
-| Key | Type | Purpose |
-|-----|------|---------|
-| `model` | dict | `default`, `provider`, `base_url` (when non-local), `api_key` |
-| `toolsets` | list | "all" or subset like `["web","terminal","file"]` |
-| `agent` | dict | `max_turns`, `reasoning_effort`, `verbose` |
-| `terminal` | dict | `backend`, `cwd`, `timeout`, `docker_*`, `singularity_image` |
-| `browser` | dict | `inactivity_timeout`, `record_sessions` |
-| `privacy` | dict | `redact_pii` boolean |
-| `memory` | dict | `memory_enabled`, `user_profile_enabled`, `memory_char_limit`, `nudge_interval`, `flush_min_turns` |
-| `delegation` | dict | optional per-task model override |
-| `display` | dict | `skin`, `bell_on_complete`, `show_cost` |
-| `tts` / `stt` | dict | voice and transcription providers |
-| `auxiliary.*` | dict | vision, web_extract, compression, session_search, skills_hub, mcp sub-configs |
+### Network/runtime surface
 
-The deploy process does not rewrite these values — it copies as ground truth. If validation fails, deploy aborts before touching `~/.hermes/`.
+- `python3 server.py`
+  - Starts the WebSocket bridge on port `8765`
+- `python3 l402_server.py`
+  - Local HTTP microservice for cost-estimate style responses
+- `python3 multi_user_bridge.py`
+  - Multi-user HTTP/chat bridge
 
-### Orchestration tasks (Huey)
+### Harness / operator CLI surfaces
 
-Each task is a Python function decorated with `@huey.task()` or `@huey.periodic_task()`; they execute concurrently in background Huey workers.
+- `python3 nexus/morrowind_harness.py`
+- `python3 nexus/bannerlord_harness.py`
+- `python3 mempalace/tunnel_sync.py --peer <url> [--dry-run] [--n N]`
+- `python3 mcp_servers/desktop_control_server.py`
+- `python3 mcp_servers/steam_info_server.py`
 
-| Task | Frequency | Purpose |
-|------|-----------|---------|
-| `heartbeat` | every 1 min | Gitea connection health check, re-enqueue if down |
-| `heartbeat_heavy` | every 30 min | Model health probe, local inference smoke |
-| `gitea_issue_triage` | every 5 min | Apply labels/assignees based on rules engine |
-| `orphan_work_cleanup` | daily | Find issues with stale assignee/no activity > 72h → reset |
-| `daily_reset` | daily midnight UTC | Clear expired caches, rotate logs |
-| `token_budget_enforcer` | every 15 min | Read `~/.hermes/token_budget.json`, pause budget-exhausted pipelines |
-| `flush_continuity` | on-demand | Write active session state to `~/.timmy/daily-notes/` pre-context-drop |
+### Validation surface
 
-Tasks are registered/imported by `tasks.py`; each function returns a dict which `orchestration.log_token_usage` inspects for `(input_tokens, output_tokens)` and appends to `~/.hermes/token_usage.jsonl`. No task is trusted to self-audit; the wrapper is central.
-
-### Gitea REST API wrapper methods
-
-`gitea_client.py` exposes (not exhaustive):
-- `list_issues(repo, state='open', type='issues', limit=50)` → `list[Issue]` (filters out PRs by default)
-- `list_prs(repo, state='open', limit=30)` → `list[PullRequest]`
-- `create_comment(repo, number, body)` → Comment object
-- `create_pr(repo, head, base, title, body)` → PR object or `None` on conflict (idempotent)
-- `merge_pr(repo, number, method='merge')` → Merge result
-- `get_repo(repo)` → Repo metadata
-- `assign_issue(repo, number, assignee)` → mutation
-- `add_label(repo, number, label)` → returns Label dict
-- `get_label_id(repo, label_name)` → integer ID required by batch operations
-
-HTTP layer uses only `urllib.request` — no `requests` dependency. Token discovered from 3 canonical paths; base URL from `GITEA_URL` env var or default `http://143.198.27.163:3000`.
-
-### Operational CLI tools (bin/)
-
-Each script returns structured status via exit codes and stdout; none of them daemonize themselves (supervised externally). Selected scripts:
-
-| Script | Interface | Primary function |
-|--------|-----------|------------------|
-| `timmy-orchestrator.sh` | loop (PID-gated) | Singleton governing loop; auto-assigns unassigned issues, accepts PRs, tracks state under `~/.hermes/logs/timmy-orchestrator.log` |
-| `agent-dispatch.sh` | `dispatch <repo> <issue>` | Fast manual dispatch with pre-flight duplicate-PR guard |
-| `ops-panel.sh` | interactive print panels | Current state dashboard: assigns, PR health, fleet status, cost report |
-| `ops-gitea.sh` | subcommand (`pr_count`, `label_list`, etc.) | One-liners for frequent Gitea queries |
-| `pipeline-freshness.sh` | `--diff` mode | Compare registered pipeline tasks vs cron state; surface drift |
-| `soul_eval_gate.py` | `--check` | Evaluate config against soul constraints (banned providers, forbidden API destinations) |
-| `validate_config.py` | `--strict` | Full YAML/JSON/cron file validation pre-deploy |
-| `preflight-provider-check.py` | None | Scan HARVEST files for banned provider strings |
-
-All scripts treat `~/.hermes/` as the runtime root; they never read directly from `timmy-config` repo after deployment.
-
-### Ansible module interface
-
-The ansible playbook is camel not idempotent by default — roles are idempotent.
-
-Playbook entry: `ansible-playbook -i inventory/hosts.yml playbooks/site.yml`
-
-Key variables (from group_vars/wizards.yml):
-- `wizard_name` (string), `wizard_role` (string), `hermes_home`, `wizard_home`, `golden_state_providers` (list of provider config dicts), `banned_providers` (set of provider names)
-
-The `golden_state` role writes a thin wrapper config (`thin_config_path`) around the canonical `config.yaml` with provider/API key placeholders. The `deadman_switch` role installs a low-cost `crontab` entry that watches `/tmp/agent-heartbeat-<wizard>.stamp` and, on expiry, runs `bin/deadman-fallback.py`.
-
-### Training pipeline entrypoints
-
-- `training/Makefile` targets: `data/`, `curated/`, `pairs/`, `eval/`, `lora/`
-- `training/build_curated.py` — reads `training/data/*.jsonl`, filters by provenance, de-dupes
-- `training/ingest_trajectories.py` — walks `~/.hermes/sessions/` (session database JSON blobs) and emits raw pairs
-- `training/run_adversary_eval.py` — launches a hot eval run against the latest model checkpoint
-- `training/validate_provenance.py` — asserts every pair has non-null `provenance.session_id` and `license` declared
-
-Results land in `training/output/loras/` (GGUF LoRA weights) and can be applied to a local `hermes-agent` runtime via `--lora-path` flag on hermes CLI.
+- `python3 -m pytest tests/test_portals_json.py tests/test_index_html_integrity.py tests/test_repo_truth.py -q`
+- `node --test tests/boot.test.js`
+- `python3 -m py_compile server.py nexus/morrowind_harness.py nexus/bannerlord_harness.py mempalace/tunnel_sync.py mcp_servers/desktop_control_server.py`
+- `tests/test_browser_smoke.py` defines the higher-cost Playwright smoke contract for the world shell
 
 ## Test Coverage Gaps
 
-Overall: timmy-config is a **configuration + orchestration** repository — most unit tests target config validation, cron definition consistency, and training pair provenance. Runtime behavior is exercised by smoke tests from other repos (timmy-home, hermes-agent) rather than by this repo's in-repo tests.
+Strongly covered in this checkout:
+- `tests/test_portals_json.py` validates `portals.json`
+- `tests/test_index_html_integrity.py` checks merge-marker/DOM-integrity regressions in `index.html`
+- `tests/boot.test.js` verifies `boot.js` startup behavior
+- `tests/test_repo_truth.py` validates the repo-truth documents
+- Multiple `tests/test_mempalace_*.py` files cover the palace layer
+- `tests/test_bannerlord_harness.py` exists for the Bannerlord harness
 
-**Strong coverage:**
-- `scripts/config_validator.py` invalid files get rejected
-- `training/scripts/test_training_pair_provenance.py` validates provenance records
-- `training/tests/test_provenance.py` exercises `ingest_trajectories.py` on fixture data
-- `bin/validate_config.py` catches YAML syntax errors pre-deploy (used by `deploy.sh`)
-- `ansible/` has no unit tests; however, idempotence is implicitly tested in CI redeploy smoke runs
-
-**Notable gaps:**
-- `bin/timmy-orchestrator.sh` is the central governing loop; there is NO Python-level unit test suite for its state machine or its Gitea mutation paths. Validation is manual (orchestration run, log review, ops panel). High regression risk every time `gitea_client.py` changes or Gitea API evolves.
-- `ansible/` effective golden state is verified through manual integration runs (PR merge → webhook → ansible-pull). No playbook unit testing framework is set up. Subtle variable name typos or role ordering bugs can cause fleet drift without immediate signal.
-- `tasks.py` orchestrates over 15 Huey tasks; each task has branching logic but there are NO dedicated tests for individual tasks. Errors surface at runtime in the Huey worker process, often in staging first. Test infrastructure exists but tasks are not directly targeted.
-- `gitea_client.py` — wrapper has zero automated unit tests; it is exercised indirectly via bin scripts. Bugs in pagination, error classification, or token-discovery paths are discovered manually.
-- `bin/` operational scripts are shell scripts with minimal coverage (lint exists but not functional tests). Scripts like `agent-loop.sh`, `claude-loop.sh`, `gemini-loop.sh` are dozens of lines of control flow; no mock-based integration tests validate exit code propagation.
-- `training/` end-to-end data lineage from `sessions/` → `curated/` → LoRA publish is run manually; Makefile has no smoke test rule to assert final artifacts exist with correct schema.
-- No Selenium / Playwright test for Ansible deployments; fleet ops rely on manual `ansible-playbook --check` followed by hot-fix cycles.
-
-This is a conscious trade-off: timmy-config is intentionally lean on in-repo auto-harness because:
-1. many parts of timmy-config are themselves test harnesses for other components
-2. real coverage happens in integration runs (full-fleet deploy, orchestrator loop activation)
-
-The recommended test additions (if time permits) are:
-- In-process Huey task unit tests using an in-memory SQLite database for the Huey backend
-- Ansible Molecule scenario for `golden_state` + `deadman_switch` roles
-- `bin/timmy-orchestrator.sh` state-machine harness using `bats` + mocked Gitea API fixture
-- `gitea_client.py` unit-tests with `urllib` patched and canned API payloads
+Notable gaps or weak seams:
+- `nexus/morrowind_harness.py` is large and operationally critical, but the generated baseline still flags it as a gap relative to its size/complexity
+- `mcp_servers/desktop_control_server.py` exposes high-power automation but has no obvious dedicated test file in the root `tests/` suite
+- `app.js` is the dominant browser runtime file and mixes rendering, GOFAI, metrics, and integration logic in one place; browser smoke exists, but there is limited unit-level decomposition around those subsystems
+- `mempalace.js` appears minimally bridged and stale relative to the richer Python MemPalace layer
+- `multi_user_bridge.py` is a large integration surface and should be treated as high regression risk even though it is central to operator/chat flow
 
 ## Security Considerations
 
-**Banned provider enforcement:** `site.yml` `pre_tasks` loop scans all provider configs (`golden_state_providers`) and fails placement if `item.name in banned_providers`. An `ansible.cfg` + custom `preflight-provider-check.py` ensures Anthropic/Claude family is NEVER deployed on any wizard. This is an guardrail; many scripts also grep for banned strings pre-commit.
+- `server.py` binds `HOST = "0.0.0.0"`, exposing the broadcast bridge beyond localhost unless network controls limit it
+- The WebSocket bridge is a broadcast hub without visible authentication in `server.py`; connected clients are trusted to send messages into the bus
+- `mcp_servers/desktop_control_server.py` exposes mouse/keyboard/screenshot control through a stdio MCP server. In any non-local or poorly isolated runtime, this is a privileged automation surface
+- `app.js` contains hardcoded local/network endpoints such as `http://localhost:${L402_PORT}/api/cost-estimate` and `http://localhost:8082/metrics`; these are convenient for local development but create environment drift and deployment assumptions
+- `app.js` also embeds explicit endpoint/status references like `ws://143.198.27.163:8765`, which is operationally brittle and the kind of hardcoded location data that drifts across environments
+- `mempalace.js` shells out through `window.electronAPI.execPython(...)`; this is powerful and useful, but it is a clear trust boundary between UI and host execution
+- `INVESTIGATION_ISSUE_1145.md` documents an earlier integrity hazard: agents writing to `public/nexus/` instead of canonical root paths. That path confusion is both an operational and security concern because it makes provenance harder to reason about
 
-**Token handling:** `gitea_client.py` discovers tokens from file-backed stores; tokens are never CLI args or environment variables exposed to child processes. All bin scripts source `~/.hermes/gitea_token_vps` via heredoc-embedded path; tokens avoid shell expansion. Recommendation: tighten to 0600 permissions enforced by Ansible on token files.
+## Runtime Truth and Docs Drift
 
-**Cron injection surface:** `cron/jobs.json` is consumed by `bin/cron-manager.sh`; cron expression strings are blindly written to `crontab`. Any injection path there can execute arbitrary code as the user. PRs that modify `cron/` must review with elevated scrutiny.
+The most important architecture finding in this repo is not a class or subsystem. It is a truth mismatch.
 
-**Deploy script privilege:** `deploy.sh` writes under `~/.hermes/` and `~/.timmy/`. The deployment boundary is the user account. If timmy-config is compromised (malicious PR), deploy.sh would plant poisoned config files that the next Hermes agent start will consume. Mitigation: PR review ONLY from trusted committers; CI runs `soul_eval_gate.py` which diffs the proposed config against golden rules forbidding remote base_urls and unknown TTS providers.
+- README.md says current `main` does not ship a browser 3D world
+- CLAUDE.md declares root `app.js` and `index.html` as canonical frontend paths
+- tests and browser contract now assume the root frontend exists
 
-**Ansible pull exposure:** `deploy_on_webhook.sh` listens on port 9000 (`/hooks/deploy-timmy-config`). It is currently **no auth** — the endpoint accepts a shared secret check in the payload but that is weak. Gitea webhook secret SHOULD be validated; currently not. This is a pending hardening item.
+All three statements are simultaneously present in this checkout.
 
-**Deadman switch runaway:** `deadman-fallback.py` can re-deploy an earlier config snapshot if the heartbeat stops. It respects a `--dry-run` gate in staging but in prod it RNA mutates `~/.hermes/config.yaml`. A bug could cycle config back to a vulnerable state. The cycle limiter (`MAX_RETRIES=3`) should be enforced vigorously.
+Grounded evidence:
+- `README.md` still says the repo does not contain an active root frontend such as `index.html`, `app.js`, or `style.css`
+- the current checkout does contain `index.html`, `app.js`, `style.css`, `manifest.json`, and `gofai_worker.js`
+- `BROWSER_CONTRACT.md` explicitly treats those root files as required browser assets
+- `tests/test_browser_smoke.py` serves those exact files and validates DOM/WebGL contracts against them
+- `tests/test_index_html_integrity.py` assumes `index.html` is canonical and production-relevant
+- `CLAUDE.md` says frontend code lives at repo root and explicitly warns against `public/nexus/`
+- `INVESTIGATION_ISSUE_1145.md` explains why `public/nexus/` is a bad/corrupt duplicate path and confirms the real classical AI code lives in root `app.js`
 
-**Training data ingestion:** `training/ingest_trajectories.py` walks the user's local `~/.hermes/sessions/` database. If a malicious session record is present, it can poison the training corpus. The `consent_level` field MUST be respected; `build_curated.py` rejects any pair with missing `consent`. This is a trust boundary for model fine-tuning; if crossed, poisoned weights could propagate to agent runs.
+The honest conclusion:
+- The repo contains a partially restored or actively re-materialized browser surface
+- The docs are preserving an older migration truth while the runtime files and smoke contracts describe a newer present-tense truth
+- Any future work in `the-nexus` must choose one truth and align `README.md`, `CLAUDE.md`, smoke tests, and file layout around it
 
-## Performance Characteristics
-
-**Startup:** `deploy.sh` is O(file count) copy; small (<0.5 s on SSD). Ansible pull (fleet deploy) is dominated by git clone (~2–3 s) + Ansible run (~5–8 s per host). Network-bound; no heavy CPU work.
-
-**Huey task latency:** Huey runs with `immediate=False` (persistent queue). Latency is bounded by queue drain rate; single-worker can process 12–18 simple tasks/s; heavier tasks (session flush, token budget) can block the queue under high load. Queue size monitored by `pipeline-freshness.sh`.
-
-**Token accounting overhead:** `log_token_usage` writes one line per-task to `~/.hermes/token_usage.jsonl`. Each append locks briefly; negligible for TPS < 100. Database write to `orchestration.db` also performs一條 INSERT per task completion. Both are disk-bound but WAL mode; acceptable for daily operation; verified on macOS local APFS.
-
-**Gitea API rate limits:** The VPS instance uses HTTP Basic API token without rate limiting in current 10k request/minute range. Tasks iterate over repos and open issues; polling every 2 minutes across 7 repos could hit soft limits. `tasks.py` has an exponential backoff on 429 response.
-
-**Bin script boot time:** Shell scripts with embedded Python one-liners (`python3 -c "..."`) have interpreter start cost (~200ms). Suboptimal but acceptable since orchestrator runs every 5 minutes. Candidate for refactor → compiled beef -> faster binary using static lib.
-
-**Training pipeline:** ingesting 10k sessions → filtering → curated → pair-building → training is compute-bound by LoRA step AXOLOTL; data prep is memory-intensive but fits in 8 GB RAM. Pipeline is designed for offline batch; no time guarantees.
-
-**Ansible invariance check cost:** Fleet convergence checks (`--check`) run every PR merge; a full fleet check is a network round-trip (~30 hosts) which takes ~15 s with local parallel = acceptable. The `pre_tasks` banned provider scan is a grep over files; sub-second.
-
-## Sidecar Boundary and Timmy-Home Relationship
-
-The sidecar pattern is explicit: `timmy-config` owns the policy layer that configures Hermes; `hermes-agent` owns runtime execution environment (Python interpreter, tool sandboxes, model provider adapters). `timmy-home` is the user data overlay: personal memories, timmy-specific local state, `.hermes/` symlink roots.
-
-From `README.md`:
-
-> This repo is the canonical source of truth for Timmy's identity and harness overlay. Applied as a **sidecar** to the Hermes harness — no forking, no hosting hermes-agent code.
-
-The boundary contract:
-- `deploy.sh` writes only to `$HERMES_HOME` and `$TIMMY_HOME`; it never modifies `$HERMES_HOME/hermes-agent/` source trees
-- `orchestration.py` and `tasks.py` dynamically discover the Hermes install by `HERMES_HOME` and import from `hermes_agent` virtualenv within it; they use only configuration overrides, never code mutation
-- `bin/` scripts operate hermes via the CLI (`hermes chat --yolo`, `hermes status`) and via Gitea API; they do not edit any agent Python modules
-- `ansible/` manages system-level services (cron, deadman, watchdog) and file placement; it deliberately avoids tampering with agent virtualenv contents
-- `ansible/roles/golden_state` installs a Cannibal provider chain constraint; it is a policy-enforcement overlay, not a code fork
-
-In practical terms, when you run `hermes` after `./deploy.sh`, the agent reads `~/.hermes/config.yaml` that came from this repo. That config selects model providers, enables toolsets, sets delegation, privacy, memory limits. The agent executable itself lives in `~/.hermes/hermes-agent/venv/` and is managed by the user's package manager / pew / uv; timmy-config does not touch it.
-
-`timmy-home` is distinct: it is the per-user interactive ground (notes, metrics cache, local workspace files, chat history). `timmy-config` is blanket over all machines; it is not user-specific session state. `timmy-home` may extend memory files (`memories/`), but those also originated in `timmy-config` and are overlaid, not replaced.
-
-**Sidecar failure contract:** If timmy-config deployment fails but `~/.hermes/hermes-agent/` remains operable, the agent SHOULD continue running on the previous config. The sidecar must never make the harness unrecoverable. A failed `deploy.sh` or Ansible run leaves the harness running on the existing stable state; atom + symlink update is used to avoid partial writes.
-
-## Performance Characteristics
-
-**Deploy speed**: `deploy.sh` copies 646 files (~15 MB total) in ~0.3–0.7 s on modern SSDs. Main bottleneck is YAML/JSON parsing (`config_validator.py` runs after copy).
-- Key files: `config.yaml` (~4 KB) parses via `yaml.safe_load` in <5ms
-- Deployment then completes by touching `~/.timmy/SOUL.md` (cold-cache ~0.4 ms)
-
-**Runtime overhead**: `tasks.py` background tasks run inside Huey worker processes; each task is limited to 180 s timeout (default `HERMES_TIMEOUT`). The `token_budget_enforcer` hits SQLite with a simple `SELECT sum(tokens) FROM usage WHERE day = today`; aggregation over 10k rows is sub-10ms on local SSD.
-
-**Gitea API calls**: Most `gitea_client.py` operations are `GET /api/v1/repos/...` which are served locally; typical latency 40–120 ms per call. The agent batch-worker pattern aims to minimize round trips. `ops-panel.sh` makes several queries concurrently but remains sub-second overall.
-
-**Processing time**: `training/ingest_trajectories.py` processes a 24-hour session backlog (~8k sessions) in ~45 s on M3 Max; dominated by JSON deserialization and deduplication.
-
-**Memory footprint**: The sidecar itself consumes negligible RAM (Python interpreter + config ~20 MB resident). The heavy runtime is the agent virtualenv (Claude/LLM inference); that is outside this repo's concern.
-
-**Concurrency control**: `deploy.sh` is single-instance (no race); Ansible `site.yml` uses `serial: 1` (converge hosts one at a time for noise reduction), but can be run in parallel for sub-roles like `deadman_switch`. Fleet deployments across 10 hosts complete in ~90 s serial, ~25 s with 4-way parallel.
-
-**Webhook latency**: From PR merge to webhook delivery to `deploy_on_webhook.sh` = Gitea→HTTP POST (~0.5–2 s delay variable); subsequent ansible-pull run ~8 s. Mutation visible in ~10–15 s per target machine path.
-
-**Orchestration cache hits**: The Huey result backend reads/writes a few KB per task; SQLite WAL caching keeps hot operations sub-millisecond. Task throughput limited more by Gitea API availability than local disk.
+That drift is itself a critical architectural fact and should be treated as first-order design debt, not a side note.

docs/UNIFIED_FLEET_SOVEREIGNTY_STATUS.md

@@ -0,0 +1,107 @@
+# [DIRECTIVE] Unified Fleet Sovereignty & Comms Migration
+
+Grounding report for `timmy-home #524`.
+
+Issue #524 is a multi-lane directive, not a one-commit feature. This report grounds the directive in repo evidence, highlights stale cross-links, and names the missing operator bundles that still need real execution.
+
+This remains a `Refs #524` artifact. The directive spans multiple repos and operator actions, so this report makes the current repo-side state executable without pretending the whole migration is complete.
+
+## Directive Snapshot
+
+- Repo-grounded workstreams: 0
+- Partial workstreams: 4
+- Missing workstreams: 1
+- Drifted references: 4
+
+## Reference Drift
+
+- #813 is cited for Nostr Migration Leadership, but its current title is 'docs: refresh the-playground genome analysis (#671)'.
+- #819 is cited for Nostr Migration Leadership, but its current title is 'docs: verify #648 already implemented (closes #818)'.
+- #139 is cited for v0.7.0 Feature Audit, but its current title is '🐣 Allegro-Primus is born'.
+- #103 is cited for Morrowind Local-First Benchmark, but its current title is 'Build comprehensive caching layer — cache everywhere'.
+
+## Workstream Matrix
+
+### 1. Nostr Migration Leadership — PARTIAL
+
+- Requirement: Replace Telegram with relay-based sovereign comms, verify wizard keypairs, and prove the NIP-29 group path is stable.
+- Referenced issues:
+  - #813 (closed) — docs: refresh the-playground genome analysis (#671) [DRIFT]
+  - #819 (open) — docs: verify #648 already implemented (closes #818) [DRIFT]
+- Repo evidence present:
+  - `infrastructure/timmy-bridge/client/timmy_client.py` — Nostr event client scaffold already exists
+  - `infrastructure/timmy-bridge/monitor/timmy_monitor.py` — Nostr relay monitor already exists
+  - `specs/wizard-telegram-bot-cutover.md` — Telegram cutover planning exists, so the migration lane is real
+- Missing operator deliverables:
+  - wizard keypair inventory and ownership matrix
+  - NIP-29 relay group verification report
+  - operator runbook for cutting traffic off Telegram
+- Why this lane remains open: The repo has Nostr-adjacent scaffolding, but the directive still lacks a verified migration packet and the cited issue links drift away from the stated Nostr scope.
+
+### 2. Lexicon Enforcement — PARTIAL
+
+- Requirement: Enforce the Fleet Lexicon in PR review and issue triage so the team uses one shared language.
+- Referenced issues:
+  - #388 (closed) — [KT] Fleet Lexicon & Techniques — Shared Vocabulary, Patterns, and Standards for All Agents [aligned]
+- Repo evidence present:
+  - `docs/WIZARD_APPRENTICESHIP_CHARTER.md` — The repo already uses wizard-language canon in docs
+  - `specs/timmy-ezra-bezalel-canon-sheet.md` — Canonical agent naming already exists
+  - `docs/OPERATIONS_DASHBOARD.md` — Operational roles are already described in repo language
+- Missing operator deliverables:
+  - machine-checkable lexicon policy for review/triage
+  - terminology lint or reviewer checklist tied to the lexicon
+- Why this lane remains open: The naming canon exists, but there is still no executable enforcement bundle that would catch drift during future reviews and triage passes.
+
+### 3. v0.7.0 Feature Audit — PARTIAL
+
+- Requirement: Audit Hermes features that can reduce cloud dependency and turn the findings into a sovereignty implementation plan.
+- Referenced issues:
+  - #139 (open) — 🐣 Allegro-Primus is born [DRIFT]
+- Repo evidence present:
+  - `scripts/sovereignty_audit.py` — Cloud-vs-local audit machinery already exists
+  - `reports/evaluations/2026-04-15-phase-4-sovereignty-audit.md` — Recent sovereignty audit report is committed
+  - `timmy-local/README.md` — Local-first status is already documented for operators
+- Missing operator deliverables:
+  - Hermes v0.7.0 feature inventory linked to cloud-reduction leverage
+  - Sovereignty Implementation Plan derived from that feature audit
+- Why this lane remains open: The repo has sovereignty-audit infrastructure, but it does not yet contain the requested v0.7.0 feature inventory or the plan that turns those findings into rollout steps.
+
+### 4. Morrowind Local-First Benchmark — PARTIAL
+
+- Requirement: Compare cloud and local Morrowind agents, prove local parity where possible, and document the reasoning gap when it fails.
+- Referenced issues:
+  - #103 (open) — Build comprehensive caching layer — cache everywhere [DRIFT]
+- Repo evidence present:
+  - `morrowind/local_brain.py` — Local Morrowind control loop already exists
+  - `morrowind/mcp_server.py` — Morrowind MCP control surface is already wired
+  - `morrowind/pilot.py` — Trajectory logging for evaluation already exists
+- Missing operator deliverables:
+  - cloud-vs-local benchmark report for the combat loop
+  - reasoning-gap writeup tied to a proposed LoRA/fine-tune path
+- Why this lane remains open: The repo has a local Morrowind stack, but it does not yet contain the requested benchmark artifact; the cited issue number also points at an unrelated caching task.
+
+### 5. Infrastructure Hardening / Syntax Guard — MISSING
+
+- Requirement: Verify Syntax Guard pre-receive protection across Gitea repos so syntax failures stop earlier.
+- Referenced issues: none listed in the directive body
+- Repo evidence present: none
+- Missing operator deliverables:
+  - repo inventory of Gitea targets that should carry Syntax Guard
+  - deployment verifier for hook presence across those repos
+  - operator report proving installation state instead of assuming it
+- Why this lane remains open: No repo-managed syntax-guard verifier is present yet, so this directive still depends on manual trust rather than auditable proof.
+
+## Highest-Leverage Next Actions
+
+- Nostr Migration Leadership: wizard keypair inventory and ownership matrix
+- Lexicon Enforcement: machine-checkable lexicon policy for review/triage
+- v0.7.0 Feature Audit: Hermes v0.7.0 feature inventory linked to cloud-reduction leverage
+- Morrowind Local-First Benchmark: cloud-vs-local benchmark report for the combat loop
+- Infrastructure Hardening / Syntax Guard: repo inventory of Gitea targets that should carry Syntax Guard
+
+## Why #524 Remains Open
+
+- The directive bundles five separate workstreams with different evidence surfaces.
+- Multiple cited issue numbers have drifted away from the work they are supposed to anchor.
+- Repo scaffolding exists for Nostr, sovereignty audits, and Morrowind, but the operator-facing bundles are still missing.
+- Syntax Guard verification is still undocumented and unproven inside this repo.

scripts/unified_fleet_sovereignty_status.py

@@ -0,0 +1,418 @@
+#!/usr/bin/env python3
+"""Ground timmy-home #524 as an executable status report.
+
+Refs: timmy-home #524
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+from urllib import request
+
+DEFAULT_BASE_URL = "https://forge.alexanderwhitestone.com/api/v1"
+DEFAULT_OWNER = "Timmy_Foundation"
+DEFAULT_REPO = "timmy-home"
+DEFAULT_TOKEN_FILE = Path.home() / ".config" / "gitea" / "token"
+DEFAULT_REPO_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_DOC_PATH = DEFAULT_REPO_ROOT / "docs" / "UNIFIED_FLEET_SOVEREIGNTY_STATUS.md"
+
+DIRECTIVE_TITLE = "[DIRECTIVE] Unified Fleet Sovereignty & Comms Migration"
+DIRECTIVE_SUMMARY = (
+    "Issue #524 is a multi-lane directive, not a one-commit feature. "
+    "This report grounds the directive in repo evidence, highlights stale cross-links, "
+    "and names the missing operator bundles that still need real execution."
+)
+
+DEFAULT_REFERENCE_SNAPSHOT = {
+    388: {
+        "title": "[KT] Fleet Lexicon & Techniques — Shared Vocabulary, Patterns, and Standards for All Agents",
+        "state": "closed",
+    },
+    103: {
+        "title": "Build comprehensive caching layer — cache everywhere",
+        "state": "open",
+    },
+    139: {
+        "title": "🐣 Allegro-Primus is born",
+        "state": "open",
+    },
+    813: {
+        "title": "docs: refresh the-playground genome analysis (#671)",
+        "state": "closed",
+    },
+    819: {
+        "title": "docs: verify #648 already implemented (closes #818)",
+        "state": "open",
+    },
+}
+
+WORKSTREAMS = [
+    {
+        "key": "nostr-migration",
+        "name": "Nostr Migration Leadership",
+        "requirement": "Replace Telegram with relay-based sovereign comms, verify wizard keypairs, and prove the NIP-29 group path is stable.",
+        "references": [813, 819],
+        "expected_keywords": ["nostr", "relay", "telegram", "comms", "messenger"],
+        "repo_evidence": [
+            {
+                "path": "infrastructure/timmy-bridge/client/timmy_client.py",
+                "description": "Nostr event client scaffold already exists",
+            },
+            {
+                "path": "infrastructure/timmy-bridge/monitor/timmy_monitor.py",
+                "description": "Nostr relay monitor already exists",
+            },
+            {
+                "path": "specs/wizard-telegram-bot-cutover.md",
+                "description": "Telegram cutover planning exists, so the migration lane is real",
+            },
+        ],
+        "missing_deliverables": [
+            "wizard keypair inventory and ownership matrix",
+            "NIP-29 relay group verification report",
+            "operator runbook for cutting traffic off Telegram",
+        ],
+        "why_open": "The repo has Nostr-adjacent scaffolding, but the directive still lacks a verified migration packet and the cited issue links drift away from the stated Nostr scope.",
+    },
+    {
+        "key": "lexicon-enforcement",
+        "name": "Lexicon Enforcement",
+        "requirement": "Enforce the Fleet Lexicon in PR review and issue triage so the team uses one shared language.",
+        "references": [388],
+        "expected_keywords": ["lexicon", "vocabulary", "standards", "shared vocabulary"],
+        "repo_evidence": [
+            {
+                "path": "docs/WIZARD_APPRENTICESHIP_CHARTER.md",
+                "description": "The repo already uses wizard-language canon in docs",
+            },
+            {
+                "path": "specs/timmy-ezra-bezalel-canon-sheet.md",
+                "description": "Canonical agent naming already exists",
+            },
+            {
+                "path": "docs/OPERATIONS_DASHBOARD.md",
+                "description": "Operational roles are already described in repo language",
+            },
+        ],
+        "missing_deliverables": [
+            "machine-checkable lexicon policy for review/triage",
+            "terminology lint or reviewer checklist tied to the lexicon",
+        ],
+        "why_open": "The naming canon exists, but there is still no executable enforcement bundle that would catch drift during future reviews and triage passes.",
+    },
+    {
+        "key": "feature-audit",
+        "name": "v0.7.0 Feature Audit",
+        "requirement": "Audit Hermes features that can reduce cloud dependency and turn the findings into a sovereignty implementation plan.",
+        "references": [139],
+        "expected_keywords": ["hermes", "feature", "audit", "v0.7.0", "sovereignty"],
+        "repo_evidence": [
+            {
+                "path": "scripts/sovereignty_audit.py",
+                "description": "Cloud-vs-local audit machinery already exists",
+            },
+            {
+                "path": "reports/evaluations/2026-04-15-phase-4-sovereignty-audit.md",
+                "description": "Recent sovereignty audit report is committed",
+            },
+            {
+                "path": "timmy-local/README.md",
+                "description": "Local-first status is already documented for operators",
+            },
+        ],
+        "missing_deliverables": [
+            "Hermes v0.7.0 feature inventory linked to cloud-reduction leverage",
+            "Sovereignty Implementation Plan derived from that feature audit",
+        ],
+        "why_open": "The repo has sovereignty-audit infrastructure, but it does not yet contain the requested v0.7.0 feature inventory or the plan that turns those findings into rollout steps.",
+    },
+    {
+        "key": "morrowind-benchmark",
+        "name": "Morrowind Local-First Benchmark",
+        "requirement": "Compare cloud and local Morrowind agents, prove local parity where possible, and document the reasoning gap when it fails.",
+        "references": [103],
+        "expected_keywords": ["morrowind", "combat", "benchmark", "local", "cloud"],
+        "repo_evidence": [
+            {
+                "path": "morrowind/local_brain.py",
+                "description": "Local Morrowind control loop already exists",
+            },
+            {
+                "path": "morrowind/mcp_server.py",
+                "description": "Morrowind MCP control surface is already wired",
+            },
+            {
+                "path": "morrowind/pilot.py",
+                "description": "Trajectory logging for evaluation already exists",
+            },
+        ],
+        "missing_deliverables": [
+            "cloud-vs-local benchmark report for the combat loop",
+            "reasoning-gap writeup tied to a proposed LoRA/fine-tune path",
+        ],
+        "why_open": "The repo has a local Morrowind stack, but it does not yet contain the requested benchmark artifact; the cited issue number also points at an unrelated caching task.",
+    },
+    {
+        "key": "syntax-guard",
+        "name": "Infrastructure Hardening / Syntax Guard",
+        "requirement": "Verify Syntax Guard pre-receive protection across Gitea repos so syntax failures stop earlier.",
+        "references": [],
+        "expected_keywords": [],
+        "repo_evidence": [],
+        "missing_deliverables": [
+            "repo inventory of Gitea targets that should carry Syntax Guard",
+            "deployment verifier for hook presence across those repos",
+            "operator report proving installation state instead of assuming it",
+        ],
+        "why_open": "No repo-managed syntax-guard verifier is present yet, so this directive still depends on manual trust rather than auditable proof.",
+    },
+]
+
+
+def default_snapshot() -> dict[int, dict[str, str]]:
+    return deepcopy(DEFAULT_REFERENCE_SNAPSHOT)
+
+
+class GiteaClient:
+    def __init__(self, token: str, owner: str = DEFAULT_OWNER, repo: str = DEFAULT_REPO, base_url: str = DEFAULT_BASE_URL):
+        self.token = token
+        self.owner = owner
+        self.repo = repo
+        self.base_url = base_url.rstrip("/")
+
+    def get_issue(self, issue_number: int) -> dict[str, Any]:
+        req = request.Request(
+            f"{self.base_url}/repos/{self.owner}/{self.repo}/issues/{issue_number}",
+            headers={"Authorization": f"token {self.token}", "Accept": "application/json"},
+        )
+        with request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode())
+
+
+def load_snapshot(path: Path | None = None) -> dict[int, dict[str, str]]:
+    if path is None:
+        return default_snapshot()
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return {int(k): v for k, v in data.items()}
+
+
+def refresh_snapshot(token_file: Path = DEFAULT_TOKEN_FILE) -> dict[int, dict[str, str]]:
+    token = token_file.read_text(encoding="utf-8").strip()
+    client = GiteaClient(token=token)
+    snapshot: dict[int, dict[str, str]] = {}
+    for issue_number in sorted(DEFAULT_REFERENCE_SNAPSHOT):
+        issue = client.get_issue(issue_number)
+        snapshot[issue_number] = {
+            "title": issue["title"],
+            "state": issue["state"],
+        }
+    return snapshot
+
+
+def collect_repo_evidence(entries: list[dict[str, str]], repo_root: Path) -> tuple[list[str], list[str]]:
+    present: list[str] = []
+    missing: list[str] = []
+    for entry in entries:
+        label = f"`{entry['path']}` — {entry['description']}"
+        if (repo_root / entry["path"]).exists():
+            present.append(label)
+        else:
+            missing.append(label)
+    return present, missing
+
+
+
+def evaluate_reference(issue_number: int, snapshot: dict[int, dict[str, str]], expected_keywords: list[str]) -> dict[str, Any]:
+    record = snapshot.get(issue_number, {"title": "missing from snapshot", "state": "unknown"})
+    title = record["title"]
+    title_lower = title.lower()
+    matched_keywords = [kw for kw in expected_keywords if kw.lower() in title_lower]
+    aligned = bool(matched_keywords) if expected_keywords else True
+    return {
+        "number": issue_number,
+        "title": title,
+        "state": record["state"],
+        "aligned": aligned,
+        "matched_keywords": matched_keywords,
+    }
+
+
+
+def classify_workstream(reference_results: list[dict[str, Any]], evidence_present: list[str], missing_deliverables: list[str]) -> str:
+    has_drift = any(not item["aligned"] for item in reference_results)
+    if not evidence_present:
+        return "MISSING"
+    if has_drift or missing_deliverables:
+        return "PARTIAL"
+    return "GROUNDED"
+
+
+
+def evaluate_directive(snapshot: dict[int, dict[str, str]] | None = None, repo_root: Path | None = None) -> dict[str, Any]:
+    snapshot = snapshot or default_snapshot()
+    repo_root = repo_root or DEFAULT_REPO_ROOT
+    workstreams: list[dict[str, Any]] = []
+    drift_items: list[str] = []
+
+    for lane in WORKSTREAMS:
+        reference_results = [
+            evaluate_reference(issue_number, snapshot, lane["expected_keywords"])
+            for issue_number in lane["references"]
+        ]
+        present, missing = collect_repo_evidence(lane["repo_evidence"], repo_root)
+        for item in reference_results:
+            if not item["aligned"]:
+                drift_items.append(
+                    f"#{item['number']} is cited for {lane['name']}, but its current title is '{item['title']}'."
+                )
+        workstream = {
+            "key": lane["key"],
+            "name": lane["name"],
+            "requirement": lane["requirement"],
+            "reference_results": reference_results,
+            "repo_evidence_present": present,
+            "repo_evidence_missing": missing,
+            "missing_deliverables": list(lane["missing_deliverables"]),
+            "why_open": lane["why_open"],
+        }
+        workstream["status"] = classify_workstream(
+            reference_results=reference_results,
+            evidence_present=present,
+            missing_deliverables=workstream["missing_deliverables"],
+        )
+        workstreams.append(workstream)
+
+    next_actions: list[str] = []
+    for workstream in workstreams:
+        if workstream["missing_deliverables"]:
+            next_actions.append(f"{workstream['name']}: {workstream['missing_deliverables'][0]}")
+
+    return {
+        "issue_number": 524,
+        "title": DIRECTIVE_TITLE,
+        "summary": DIRECTIVE_SUMMARY,
+        "reference_snapshot": {str(k): v for k, v in sorted(snapshot.items())},
+        "workstreams": workstreams,
+        "reference_drift": drift_items,
+        "grounded_workstreams": sum(1 for item in workstreams if item["status"] == "GROUNDED"),
+        "partial_workstreams": sum(1 for item in workstreams if item["status"] == "PARTIAL"),
+        "missing_workstreams": sum(1 for item in workstreams if item["status"] == "MISSING"),
+        "next_actions": next_actions,
+    }
+
+
+
+def render_markdown(result: dict[str, Any]) -> str:
+    lines = [
+        f"# {result['title']}",
+        "",
+        "Grounding report for `timmy-home #524`.",
+        "",
+        result["summary"],
+        "",
+        "This remains a `Refs #524` artifact. The directive spans multiple repos and operator actions, so this report makes the current repo-side state executable without pretending the whole migration is complete.",
+        "",
+        "## Directive Snapshot",
+        "",
+        f"- Repo-grounded workstreams: {result['grounded_workstreams']}",
+        f"- Partial workstreams: {result['partial_workstreams']}",
+        f"- Missing workstreams: {result['missing_workstreams']}",
+        f"- Drifted references: {len(result['reference_drift'])}",
+        "",
+        "## Reference Drift",
+        "",
+    ]
+    if result["reference_drift"]:
+        lines.extend(f"- {item}" for item in result["reference_drift"])
+    else:
+        lines.append("- No stale cross-links detected in the directive snapshot.")
+
+    lines.extend(["", "## Workstream Matrix", ""])
+    for index, workstream in enumerate(result["workstreams"], start=1):
+        lines.extend(
+            [
+                f"### {index}. {workstream['name']} — {workstream['status']}",
+                "",
+                f"- Requirement: {workstream['requirement']}",
+            ]
+        )
+        if workstream["reference_results"]:
+            lines.append("- Referenced issues:")
+            for ref in workstream["reference_results"]:
+                alignment = "aligned" if ref["aligned"] else "DRIFT"
+                lines.append(
+                    f"  - #{ref['number']} ({ref['state']}) — {ref['title']} [{alignment}]"
+                )
+        else:
+            lines.append("- Referenced issues: none listed in the directive body")
+
+        if workstream["repo_evidence_present"]:
+            lines.append("- Repo evidence present:")
+            lines.extend(f"  - {item}" for item in workstream["repo_evidence_present"])
+        else:
+            lines.append("- Repo evidence present: none")
+
+        if workstream["repo_evidence_missing"]:
+            lines.append("- Repo evidence expected but missing:")
+            lines.extend(f"  - {item}" for item in workstream["repo_evidence_missing"])
+
+        if workstream["missing_deliverables"]:
+            lines.append("- Missing operator deliverables:")
+            lines.extend(f"  - {item}" for item in workstream["missing_deliverables"])
+        else:
+            lines.append("- Missing operator deliverables: none")
+
+        lines.append(f"- Why this lane remains open: {workstream['why_open']}")
+        lines.append("")
+
+    lines.extend(["## Highest-Leverage Next Actions", ""])
+    lines.extend(f"- {item}" for item in result["next_actions"])
+
+    lines.extend(
+        [
+            "",
+            "## Why #524 Remains Open",
+            "",
+            "- The directive bundles five separate workstreams with different evidence surfaces.",
+            "- Multiple cited issue numbers have drifted away from the work they are supposed to anchor.",
+            "- Repo scaffolding exists for Nostr, sovereignty audits, and Morrowind, but the operator-facing bundles are still missing.",
+            "- Syntax Guard verification is still undocumented and unproven inside this repo.",
+        ]
+    )
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Render the unified fleet sovereignty status report for issue #524")
+    parser.add_argument("--snapshot", help="Optional JSON snapshot file overriding the default issue-title/state snapshot")
+    parser.add_argument("--live", action="store_true", help="Refresh the issue snapshot from Gitea before rendering")
+    parser.add_argument("--token-file", default=str(DEFAULT_TOKEN_FILE), help="Token file used with --live")
+    parser.add_argument("--output", help="Optional path to write the rendered report")
+    parser.add_argument("--json", action="store_true", help="Print computed JSON instead of markdown")
+    args = parser.parse_args()
+
+    if args.live:
+        snapshot = refresh_snapshot(Path(args.token_file).expanduser())
+    else:
+        snapshot = load_snapshot(Path(args.snapshot).expanduser() if args.snapshot else None)
+
+    result = evaluate_directive(snapshot=snapshot, repo_root=DEFAULT_REPO_ROOT)
+    rendered = json.dumps(result, indent=2) if args.json else render_markdown(result)
+
+    if args.output:
+        output_path = Path(args.output).expanduser()
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(rendered, encoding="utf-8")
+        print(f"Directive status written to {output_path}")
+    else:
+        print(rendered)
+
+
+if __name__ == "__main__":
+    main()

tests/test_unified_fleet_sovereignty_status.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPT_PATH = ROOT / "scripts" / "unified_fleet_sovereignty_status.py"
+DOC_PATH = ROOT / "docs" / "UNIFIED_FLEET_SOVEREIGNTY_STATUS.md"
+
+
+def _load_module(path: Path, name: str):
+    assert path.exists(), f"missing {path.relative_to(ROOT)}"
+    spec = importlib.util.spec_from_file_location(name, path)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _workstream(result: dict, key: str) -> dict:
+    for workstream in result["workstreams"]:
+        if workstream["key"] == key:
+            return workstream
+    raise AssertionError(f"missing workstream {key}")
+
+
+def test_evaluate_directive_flags_reference_drift_without_faking_completion() -> None:
+    mod = _load_module(SCRIPT_PATH, "unified_fleet_sovereignty_status")
+    result = mod.evaluate_directive(snapshot=mod.default_snapshot(), repo_root=ROOT)
+
+    assert len(result["reference_drift"]) == 4
+    assert any("#813" in item for item in result["reference_drift"])
+    assert any("#103" in item for item in result["reference_drift"])
+
+    nostr = _workstream(result, "nostr-migration")
+    assert nostr["status"] == "PARTIAL"
+    assert any("timmy_client.py" in item for item in nostr["repo_evidence_present"])
+
+    lexicon = _workstream(result, "lexicon-enforcement")
+    assert all(item["aligned"] for item in lexicon["reference_results"])
+    assert lexicon["status"] == "PARTIAL"
+
+    syntax_guard = _workstream(result, "syntax-guard")
+    assert syntax_guard["status"] == "MISSING"
+    assert any("deployment verifier" in item for item in syntax_guard["missing_deliverables"])
+
+
+def test_render_markdown_includes_required_sections_and_grounding_evidence() -> None:
+    mod = _load_module(SCRIPT_PATH, "unified_fleet_sovereignty_status")
+    result = mod.evaluate_directive(snapshot=mod.default_snapshot(), repo_root=ROOT)
+    report = mod.render_markdown(result)
+
+    for snippet in (
+        "# [DIRECTIVE] Unified Fleet Sovereignty & Comms Migration",
+        "## Directive Snapshot",
+        "## Reference Drift",
+        "## Workstream Matrix",
+        "### 5. Infrastructure Hardening / Syntax Guard — MISSING",
+        "`infrastructure/timmy-bridge/client/timmy_client.py`",
+        "machine-checkable lexicon policy for review/triage",
+        "## Why #524 Remains Open",
+    ):
+        assert snippet in report
+
+
+def test_repo_contains_committed_issue_524_grounding_doc() -> None:
+    assert DOC_PATH.exists(), "missing committed directive grounding doc"
+    text = DOC_PATH.read_text(encoding="utf-8")
+    for snippet in (
+        "# [DIRECTIVE] Unified Fleet Sovereignty & Comms Migration",
+        "## Reference Drift",
+        "## Workstream Matrix",
+        "## Highest-Leverage Next Actions",
+        "## Why #524 Remains Open",
+    ):
+        assert snippet in text