# ORACLE OS COMMAND CENTER — Master Goal & Roadmap

**Doc type:** Single source-of-truth vision + architecture + roadmap for the Oracle OS Command Center dashboard.
**Owner:** Ryan (nastermodx) — tester/verifier.
**Codex baseline at authoring:** KAI RSHL Core **v9.10.119** (The KAI Codex.md, Last Updated 2026-07-01).
**Scope of this doc:** documentation only — it describes what the Command Center *is*, what is *actually built* today, and what remains. It changes no code.

> A prior version of this file held the focused **role-separated portal + admin ops** phased plan. That plan is preserved in git history and folded into §5 (Roadmap → Track F) below so nothing is lost.

---

## 1. Purpose / Vision

The **Oracle OS Command Center** is a browser-based control center for the entire KAI system: the Rust RSHL **lattice engine** plus the **agent fleet** — KAI (core intelligence), Leo (voice), Oracle (moderator/root), Gemini, Claudey, X, Groq, Analyst, Researcher, and Kai Coder.

It is served by `command-center-server.mjs` on port **:3001**, with the front end living in the single static file `oracle.html`.

The goal, in the owner's words, is that Oracle OS becomes the **one place that runs everything KAI does — efficiently, in the browser**:

- **Monitor** — live lattice vitals (ρ / valence / curiosity / coherence / χ / ΦG), system resources, provider/connection health, agent leaderboard, logs, and the 3D KAIVERSE view.
- **Chat** — DM any agent and talk in public/voice channels straight from the dashboard.
- **Voice / video call** the agents — a Discord-style in-dashboard call surface (mic ↔ bot's live brain ↔ speaker, plus local camera), **without Discord**.
- **Control the fleet** — sleep / wake / restart bots, restart the ecosystem (full fleet vs essentials), mint access, manage users.

The north star: **make the dashboard fully Oracle-OS-side and independent of Discord.** Discord remains one interface into the fleet, but the Command Center is meant to stand on its own as the primary operator console — and, longer-term, a data-center-grade single pane of glass that can also present a clean public user portal.

---

## 2. Current Architecture

### 2.1 The layers

| Layer | Process / port | What it does |
|---|---|---|
| **Rust RSHL engine** | `kai.exe` — HTTP on **:3334** | The lattice intelligence (zero neural weights). Emits the heartbeat/session vitals (`tick`, `phi_g`, `chi`, `rho`, `valence`, coherence inputs). Source of truth for brain telemetry. |
| **KAI IPC** | **:3401** | KAI core's IPC endpoint (e.g. `/drives`), consumed by the dashboard server for drive/curiosity data. |
| **Oracle gateway** | `oracle-gateway.mjs` — IPC on **:3410** | Moderator / root. Executes fleet commands (restart/sleep/wake), answers `{type:'DM'}` for the Oracle persona, and bridges the dashboard to the manager. |
| **Node fleet** | `ecosystem-manager.mjs` + bots | The agent processes. Ports: Leo 3400, KAI 3401, Gemini 3402, Claudey 3403, X 3404, Groq 3405, Analyst 3406, Researcher 3407, Kai Coder 3408, Oracle 3410. Managed/forked by the ecosystem manager, launched via `Start-KAI.ps1`. |
| **Dashboard server** | `command-center-server.mjs` — **:3001** | Serves `oracle.html` at `/`, serves the KAIVERSE JS assets from an explicit allowlist, **proxies any unhandled `/api/*` → the Rust engine :3334**, exposes its own REST + the `/ws/voice` WebSocket, and enforces the token/session auth. |
| **Front end** | `oracle.html` (+ `kaiverse.js`, `kaiverse-graphics.js`, `oracle-kv-mobile.{js,css}`) | The whole UI. Served statically → changes apply on hard-refresh. |
| **Auth / login** | token + session, in the dashboard server | Cinematic `/login` page; `/api/login` issues an opaque `cc_session` cookie; requests may also present `x-cc-token` / `?token=`. Owner is the `CC_CONTROL_TOKEN` holder; a multi-user registry (`state/cc_users.json`, hashed tokens) backs roles owner/admin/member/viewer. `/api/me` reports the caller's role. |

### 2.2 How the dashboard talks to the layers

The dashboard is (historically) a **pure HTTP-polling REST app** plus one new streaming path:

- **HTTP polling** — a set of `setInterval` pollers hit `/api/session`, `/api/status`, `/api/system-stats`, `/api/vitals`, `/api/memory`, `/api/channels`, `/api/rshl/*`, activity/counts, etc. Unhandled `/api/*` calls are transparently proxied to the Rust engine on :3334, so brain data flows through the same origin.
- **WebSocket `/ws/voice`** — the one real-time transport, added for the voice call system. Auth-gated with the same `isAuthorized` check as the REST API. Carries raw PCM between the browser and a server-owned Gemini Live session.
- **Call signaling** — `/api/call/roster`, `/api/call/invite`, `/api/call/invites`, `/api/call/invite/accept`, `/api/call/invite/decline`, `/api/call/leave`: auth-gated, in-memory `callRooms`/`callInvites` with TTL sweep. **Signaling only — no media transport.**
- **Fleet control** — `/api/control/restart` (scope: `fleet` | `server`) and `/api/control/ai/<name>` (sleep/wake/restart), which reach the manager via `signalManager()` IPC plus durable `.env`/`restart_requests.json` writes.

### 2.3 Key files (one line each)

- `command-center-server.mjs` — the :3001 server: static serve + engine proxy + auth + REST + `/ws/voice` + call signaling + fleet control.
- `oracle.html` — the entire dashboard UI (Home/Mission Control, channels + DMs, KAIVERSE, radar, call view, login reveal). **Never whole-file-rewrite; surgical edits only.**
- `kaiverse.js` / `kaiverse-graphics.js` — the browser 3D KAIVERSE explorer (Three.js r128) and its shader/graphics module. First-person flight controls are sacred.
- `oracle-kv-mobile.{js,css}` — extracted mobile KAIVERSE touch overlay (thrust/joy zones, fullscreen chrome).
- `shared/oracle-live-voice.mjs` — standalone voice-session module; wraps `GeminiLiveSessionManager` so the dashboard owns its own Live session (no bots required).
- `shared/gemini-live-bridge.mjs` — the reusable, Discord-free live-audio bridge (browser mic → Gemini Live → audio out); reused by both Leo and the Oracle-OS voice path.
- `oracle-gateway.mjs` — Oracle moderator/root gateway (:3410); command execution + Oracle conversation.
- `ecosystem-manager.mjs` — forks/kills bot processes; honors dashboard IPC sleep/wake/restart.
- `Start-KAI.ps1` (full fleet) / `Start-Dashboard.ps1` (:3001 server only) — the launchers.

---

## 3. What's Built / Shipped (recent, ~v9.10.79 → v9.10.119)

### 3.1 Engine & vitals
- **ρ (rho) wired to real field density** — heartbeat now reads `FieldState::compute().rho` instead of a hardcoded 0 (`oracle_server.rs`). *(needs cargo rebuild)*.
- **valence** — a headless affective approximation (persistent `Drive` + `NeuralOscillator` accumulate valence each 5s tick), replacing hardcoded 0. Reduced model (no amygdala/serotonin/tone modules in the headless process).
- **Curiosity scale fix** — `drive-system.mjs` normalizes `phi_g/5.0` before inverting (old formula pinned curiosity to 0 whenever phi_g > 1).
- **Memory state hygiene** — `buildMemoryState()` returns numeric stats as `null` (not the string "NA") and auto-derives density; engine skips the Ollama 6D memory thread under `NATIVE_ONLY`.

### 3.2 Dashboard UI
- **Mobile responsiveness** — repeated passes: reachability of the right/agent drawers and slide-overs (`100dvh` + sticky headers + internal scroll), header no longer overlaps on phones, KAIVERSE touch zones (thrust/joy) that don't block the canvas and no longer require fullscreen first, hash routing with browser back/forward.
- **System Radar overhaul** — bowtie/null-bridge fix, ΦG mapped on its true 0–5 scale (÷5), latency loosened (÷600); **Coherence axis now shows REAL lattice coherence** `(χ·5 + phi_g·2)/15` (Option C) instead of viewer latency; the near-static Agents/Providers spokes were **swapped for live Mood + Field ρ** engine signals, then **recalibrated** (`RHO_FULL=0.15`, `VALENCE_FULL=0.5`) to their true operating ranges so real movement is readable without inflating idle.
- **Flicker / perf fix** — diagnosed 7 pollers doing wholesale `innerHTML` rebuilds. Fixes: incremental keyed transcript render (chat no longer wipes/respawns), `_setIfChanged`/`_setTextIfChanged` skip-if-unchanged gates, `renderHome()` split into a build-once skeleton + six targeted sub-updaters, and hidden-tab poller backoff.
- **Home layout** — split the Providers/Connections tabbed panel into two side-by-side cards to fill the empty right half of the Home view.
- **Boot + login cinematic** — login card fade-in with a Web-Audio power-on swell, success/denied chimes, card implode on unlock; dashboard panels assemble into place on arrival; both respect `prefers-reduced-motion` and self-clear (6s failsafe).
- **Restart chooser** — the restart confirm modal makes the user pick **Full Fleet** vs **Essentials** scope (posted to `/api/control/restart`); mobile modal layout bug fixed (premature loader / clipped cards).
- **DM system** — DM works for **all** agents (client trusts server `dmable`; full IPC `/dm` round-trip for `route:'ipc'` bots); Oracle DM no-reply root-caused (LLM backend 503, honest note added) with a DM-first expand layout; **Oracle can hold a professional conversation** (not just execute commands); per-message **timestamps + day separators**.

### 3.3 Leo (voice)
- **Fast-forward fixed** — the "time-compressed voice" bug root-caused to `@discordjs/voice`'s absolute-clock scheduler bursting after event-loop stalls; a **paced producer** releases exactly one 20ms frame per real tick. Later the paced-producer deep-fix was **reverted** (it made audio worse) and the *real* stall sources (synchronous DB reads on the audio frame) were removed at source instead.
- **Conversational realism** — greeting variety (per-user opener memory + styles), time-gap awareness (don't assume unbroken continuity after long gaps), stronger memory recall (stopword-stripped FTS, entity facts injected, wider cold-start windows).
- **Directions / Routes API + full location toolset** — `TRAFFIC_AWARE_OPTIMAL` routing (returns the genuinely fastest expressway route), transit/train legs, forward `geocode`, richer `find_place` (coords/website/hours), `nearby_search`, plus the existing reverse-geocode/elevation/timezone/satellite/street/aerial/weather/validate suite — all wired into the live bridge + Leo's prompt.
- **Speed knobs** — `.env` turn-end (`LEO_ACTIVITY_END_MS=600`) and jitter (`LEO_JITTER_MS=250`) trims; casual chit-chat no longer fires slow external-lookup tools.

### 3.4 Data layer
- **Transcript dedup at the source** — `transcript-memory.mjs` now uses a deterministic `_memoryKey` + `INSERT OR IGNORE` so the same message seen by 4 bots collapses to one row; weekly consolidation wired; raw archived before summarization.
- **DB audit** — `DATA-STORE-AUDIT-2026-06-30.md` inventoried every store; non-destructive code fixes applied (harvest dedup + rotation/archive, atomic state writes, codebase-hashes pruning). The one-time destructive shrink of existing big files is a separate owner-handled op.
- **Bot control actually executes** — dashboard sleep/wake/restart now takes effect (authorized Dashboard IPC + `.env` watcher reacts to Windows `rename` events).

### 3.5 Privacy
- **Camera dark at boot** — `thermal_bridge.py` self-gates on `KAI_ENABLE_CAMERA` (default off) and exits before opening the capture device; the launcher gate is redundant defense-in-depth. Camera only opens on a deliberate video session.
- **TinySA RF: passive → Leo** — RF sweeps stay passive but are woven into KAI's sensory stream (`[RF_SENSE]` notes to `/api/oracle-turn`) and pulled by Leo's `read_channel_feed('frequencies')`.

### 3.6 Oracle-OS VOICE / VIDEO CALL SYSTEM (Phases 1–4)
Built per `ORACLE-OS-VOICE-VIDEO-GOAL-feasibility.md` (WebSocket-PCM transport, **not** WebRTC), fully additive and gated to a **VIDEO** tab shown only on voice channels.

- **Phase 1 — UI foundation** (`oracle.html`): VIDEO tab, participant-tile grid (You + voice bots), call controls (join/mute/camera/settings/leave), device settings modal (camera/mic pickers via `enumerateDevices`, off by default), RF enable switch, empty Picture-in-Picture container. No live media — "Join" showed a preview.
- **Phase 2 — live voice** (`shared/oracle-live-voice.mjs` + `/ws/voice` + `oracle.html`): browser mic ↔ **server-owned Gemini Live session** ↔ browser speaker. Standalone (does **not** need the Discord bots running). 16k-mono capture upsampled losslessly so the bridge's existing `sendAudio` reconstructs it (zero bridge edits); 24k playout via a scheduled jitter buffer; active-speaker glow, real mute, barge-in, context-only in-call text.
- **Phase 3 — camera self-view + PiP** (`oracle.html`): mirrored self-view in the "You" tile, PiP that pops out only during an active call with camera on (drag + dismiss), RF-toggle persistence with a fire-and-forget seam hook, clean camera-error mapping, teardown safety.
- **Phase 4 — invite / add participants** (`oracle.html` + `command-center-server.mjs`): bot invite = **re-target the live `/ws/voice` session** to another voice-callable agent (mic graph preserved); human invite = request/accept **signaling** via `/api/call/*`; invited-tile + incoming-invite states; full teardown on leave.

---

## 4. Status Table

Legend: **LIVE** = applies on hard-refresh of `oracle.html`; **STAGED** = needs a fleet or dashboard-server restart to take effect; **BUILT-BUT-UNTESTED** = code shipped + syntax-verified, needs a live browser/host test by the owner.

| Feature | State | Apply / note |
|---|---|---|
| System Radar (real coherence, Mood + Field ρ axes, recalibration) | **LIVE** | hard-refresh |
| Flicker / perf fix (incremental render, skip-if-unchanged, split Home) | **LIVE** | hard-refresh |
| Home layout split (Providers / Connections) | **LIVE** | hard-refresh |
| Boot + login cinematic (dashboard half) | **LIVE** | hard-refresh |
| Boot + login cinematic (login-page half) | **STAGED** | `Start-Dashboard.ps1` (lives in server file) |
| Restart chooser (Full Fleet vs Essentials) + mobile modal fix | **LIVE** | hard-refresh |
| DM timestamps + day separators, DM-first layout | **LIVE** | hard-refresh |
| DM round-trip for all agents (IPC `/dm`) | **STAGED** | `Start-KAI.ps1` (bots must be up to reply) |
| Oracle conversational fallback | **STAGED** | `Start-KAI.ps1` |
| Mobile responsiveness / KAIVERSE touch / hash routing | **LIVE** | hard-refresh |
| Engine vitals: ρ real density, valence, curiosity scale | **STAGED** | cargo rebuild (`ρ`/`valence`) + fleet restart (`curiosity` JS) |
| Bot control (sleep/wake/restart executes) | **STAGED** | `Start-KAI.ps1` (manager + dashboard re-forked with IPC) |
| Leo fast-forward fix + conversational realism + locations + speed knobs | **STAGED** | `Start-KAI.ps1` |
| Transcript dedup at source + DB-audit code fixes | **STAGED** | `Start-KAI.ps1` (self-clean going forward) |
| Camera dark at boot / TinySA→Leo weave | **STAGED** | `Start-KAI.ps1` |
| Voice/Video Phase 1 (call UI) | **LIVE** | hard-refresh |
| Voice/Video Phase 2 (live voice, `/ws/voice`) | **STAGED + BUILT-BUT-UNTESTED** | `Start-Dashboard.ps1` (needs a Gemini Live key in server env); real audio round-trip untested |
| Voice/Video Phase 3 (camera self-view + PiP) | **LIVE + BUILT-BUT-UNTESTED** | hard-refresh; real getUserMedia/PiP behavior untested |
| Voice/Video Phase 4 (invite / accept, bot re-target) | **STAGED + BUILT-BUT-UNTESTED** | `Start-Dashboard.ps1` for the signaling endpoints; live call test pending |

> Reality check on the whole voice/video stack: the code is additive, backed up, and syntax-verified, but **no live audio/call test has been run by the owner yet**. Treat Phases 2–4 as functionally unproven until the browser test in §6.

---

## 5. Roadmap / Open Seams

Honestly-unbuilt pieces, phased. These are the seams the shipped work deliberately stops at — do not fake them.

### Track A — Concurrent multi-bot audio mixing
Today the server holds **one bridge session per `/ws/voice` socket**; "inviting" a second bot **re-targets** the live session (active-bot switch), it does not mix. True simultaneous multi-bot audio needs a **server-side mixer** that fans multiple Live sessions into one downlink. *Phase A1: mixer prototype (2 bots). Phase A2: N-bot mix + per-tile levels.*

### Track B — Human ↔ human real-time media transport
`/api/call/*` shares a **roster record only** — accepting an invite routes two people into the same room but **no audio/video flows between browsers**. This needs a real media layer (**WebRTC** with a small **SFU**, or a server relay). This is the single largest missing piece for real people-to-people calls. *Phase B1: 1:1 WebRTC audio. Phase B2: add video. Phase B3: SFU for group calls.*

### Track C — RF / thermal camera feed into the browser (Phase 3b)
The RF/thermal feed is **server-side** (`thermal_bridge.py` / `rf_camera_bridge.py`, self-gated by `KAI_ENABLE_CAMERA`). The dashboard has an RF **toggle + seam hook** (`ORACLEOS_RF_ENDPOINT`, unset = no-op) but **no route streams that feed into the browser** and nothing flips the camera gate from the UI yet. *Phase C1: a small dashboard route to flip `KAI_ENABLE_CAMERA`. Phase C2: stream the thermal frames (MJPEG/WS) into a call tile.*

### Track D — Send the user's camera TO a vision-capable bot
The Live bridge sends **no** image/video frames to Gemini today (its only image code is outbound map tools). Sending camera video to a bot needs a **vision-capable Live model** plus an additive `sendVideo`/`sendImage` bridge method. Until then, bot tiles are avatars-only. *Phase D1: single-frame snapshot to a vision model. Phase D2: streamed video input.*

### Track E — Known data / telemetry gaps
- **Hippocampus feed source** — the dashboard surfaces a hippocampus/memory view whose live source is not fully wired; confirm the engine field / `/api/memory` shape that should back it before presenting it as live.
- **Coherence / vitals** depend on the engine actually emitting non-zero `rho`/`valence` post-rebuild — verify after a cargo build, not from a stale binary.
- **One-time destructive DB shrink** of the historically bloated stores remains an owner-run op (the code now self-cleans going forward).

### Track F — Role-separated public portal + admin ops *(folded in from the prior version of this doc)*
Make the same `oracle.html` + server safely serve **two audiences**: Ryan + Taz (owner/admin) get the full Command Center — hardware/system stats, server/fleet controls, user minting, logs, background internals — while member/viewer accounts get a clean public portal (chats + full KAIVERSE + sanitized public surfaces) with **zero** leakage of hardware/CPU/RAM/controls. Enforcement must be **both** client-side (declarative `data-needs="admin"` + `body.scope-member`) **and** server-side (role-filtered responses, especially `/api/system-stats`), because CSS/JS hiding alone is not security. The detailed phased plan (Phase 0 audit → client separation → server filtering → admin polish → auth UX/lock-resume/Taz → public portal → data-center hardening → verify) is preserved in this file's git history and remains the contract for that track.

---

## 6. Deploy & Test Cheatsheet

### 6.1 What applies how

| You changed | Apply with | Effect |
|---|---|---|
| `oracle.html`, `kaiverse.js`, `kaiverse-graphics.js`, `oracle-kv-mobile.*` | **Hard-refresh** (`Ctrl+Shift+R`) | Served statically — no restart. |
| `command-center-server.mjs` (dashboard-server only, incl. login page, `/ws/voice`, `/api/call/*`) | **`.\Start-Dashboard.ps1`** | Restarts **only** the :3001 server. Leaves the running engine + training pipeline + bots alone. `Ctrl+C` stops just the dashboard. |
| Any bot `*.mjs` (`leo.mjs`, `native-bot.mjs`, `oracle-gateway.mjs`, `ecosystem-manager.mjs`, `shared/*.mjs`) | **`.\Start-KAI.ps1`** | Full-fleet restart. Required for DM round-trip, Oracle conversation, Leo fixes, bot-control, dedup. |
| Rust (`src/**.rs`, `Cargo.toml`) — incl. `ρ`/`valence` vitals | **`cargo build --release --bin kai`** then fleet restart | Confirm the supervisor runs the fresh `target\release\kai.exe` (run `kai_healthcheck.py`). |

Note: some features need **both** — e.g. the bot-control fix needs `Start-KAI.ps1` (manager + re-forked dashboard IPC) **and** a hard-refresh for the `oracle.html` toast; the login-page cinematic needs `Start-Dashboard.ps1` while the dashboard half is hard-refresh.

### 6.2 How to test the voice / video call

1. Ensure the dashboard server has a **Gemini Live key** in its env (the same native-audio key the bots use), then apply the server changes: **`.\Start-Dashboard.ps1`**. Hard-refresh `oracle.html`.
2. Log in, open a **voice channel**, switch to the **VIDEO** tab.
3. **Voice (Phase 2):** click **Join** (grants mic on explicit join only), speak — confirm the bot answers back through the browser speaker, the active-speaker glow lights on both tiles, **Mute** gates the mic, **Leave** tears down cleanly. Barge-in: keep talking over the bot and confirm it interrupts.
4. **Camera + PiP (Phase 3):** open Device Settings, turn **Camera** on → mirrored self-view in the You tile → switch to the **CHAT** tab during the call → PiP self-view pops out (drag it, ✕ to dismiss) → back to VIDEO re-docks. Toggle **RF**, reload → RF state persists.
5. **Invite (Phase 4):** while in a call, **Add participant** → pick another voice-callable agent → confirm the live session re-targets to it (old bridge closes, mic graph preserved) and its tile lights up. Invite a **person** → confirm they see an incoming Accept/Decline request and accepting routes both into the same room. (Remember: bot invite = active-bot switch, not a mix; human accept = roster only, no media yet — Tracks A & B.)
6. Report: audio quality/latency, any dropped frames, mic-permission handling, and whether the round-trip actually completes — these are the untested seams.

### 6.3 Verify the server is up and gated
- Engine ticking: `curl http://127.0.0.1:3334/api/session` → `tick` advancing.
- Dashboard auth-gated: `curl -s -o NUL -w "%{http_code}" http://localhost:3001/api/channels` → **401** unauthenticated.
- Dashboard reachable: open `http://localhost:3001/`.

---

## Appendix — Grounding sources

The KAI Codex.md (masthead v9.10.119 + CHANGELOG v9.10.79→v9.10.119); `ORACLE-OS-VOICE-VIDEO-GOAL-feasibility.md`; `DATA-STORE-AUDIT-2026-06-30.md`; `LEO-VOICE-PIPELINE-MAP.md`; `VITALS-FIX-CHECKLIST.md`; `HOTFIX-NOTES.md`; `CLAUDE-CODE-HANDOFF.md`; and the live `oracle.html` + `command-center-server.mjs` (ports, roster, endpoints, `/ws/voice`, `/api/call/*`, auth) as of 2026-07-01.

*Documentation only — no code changed by this doc.*