IDE ⇄ Backend Contract — The Cerebral Project

Living reference for the right-side IDE work (design, gallery, reporting UI). Backend base: http://127.0.0.1:8100 · live bus: ws://127.0.0.1:8100/ws. Everything here is running now — bind, don't mock.

Node graph telemetry (Understand-Anything)

Endpoint	Returns
`GET /v1/nodes`	All 9 nodes: intel (`label`, `summary`, `spoken`, `budgetMs`, `plane`) + `runtime` (`health`, `latencyMs`, `load`, `message`)
`GET /v1/nodes/{id}`	One node, same shape
`GET /v1/status`	Full snapshot (stage, warmProgress, mode, nodes, nvidia, lastTalk)

Node ids: mic presence syncer riva-asr nemotron riva-tts a2f animgraph omniverse. Health values: cold → warming → ready → hot (+ degraded, error).

WebSocket messages (`/ws`)

{type:"snapshot", stage, warmProgress(0..1), mode, controlMs, nodes{...}, event?, nvidia, lastTalk} — continuous
{type:"visemes", source, nodeId?, durationMs, frames:[{tMediaMs, viseme, energy, weights}]} — Pipe 3 mouth timeline; weights are ARKit-52 partials. Sources: phoneme-direct (talk), node-voice (speak), node-converse.

Node voice (click → the node explains itself aloud)

POST /v1/speak {nodeId} or {text} → audio/wav body. Headers: X-Eve-Tts-Engine, X-Eve-Viseme-Count, X-Eve-Duration-Ms. Matching viseme timeline broadcasts on /ws at the same moment — play the WAV and drive any mouth/energy UI off the frames on one clock. Cached per node → repeat clicks instant.

Bi-directional node conversation (talk WITH the node about its role)

POST /v1/nodes/{id}/converse {text, audio?: true} →

{ "ok": true, "reply": "…", "model": "…", "latencyMs": 4225,
  "nodeId": "riva-tts", "audioB64": "…wav-base64…", "engine": "sapi-com", "turns": 1 }

Node answers in FIRST PERSON with live self-knowledge (health, latency, stage, peers).
Thread memory per node (last 6 exchanges) — follow-ups work.
audio: false for text-only; default returns spoken WAV (base64) + viseme broadcast.
IDE-owned capability: works identically over any pipeline mode (mock / NVIDIA / Foundry).

Reporting spine (documents both sides)

GET /v1/report → {mode, stage, uptimeMs, totals{talks, speaks, converses, visemeFramesEmitted, stageChanges, errors}, lastError, perNode{id:{speaks, converses}}, log[last 50]}. Poll it or fold it into the snapshot cadence for the reporting pane.

Avatar gallery data source

GET /v1/gallery → {avatars:[{file, url, name, status: "completed"|"under-development"}], count}. Files live in apps/web/public/staff/ — drop a new still in, it appears. Status heuristic today: natural|closeup filenames = completed; extend with a gallery.json manifest when curation starts.

Stage control

POST /v1/stage {stage: "L0"|"L1"|"L2"} · POST /v1/talk {text, promote?} — EVE herself replies (Nemotron 3 Super 120B live), visemes fork automatically.

Ground rules already enforced backend-side

Reasoning NEVER reaches voice paths (/no_think + sanitizer) — don't re-surface reasoning_content in UI.
.env never committed; key loads server-side only.
Latency numbers in telemetry are real budgets, not decorations — safe to chart.