docs: README — operator control plane (admin API + secrets + Svelte UI) now shipped

Both READMEs predated A17-A19 and described only ingest + the C2 channel. Reflect
the bearer-authenticated operator control plane (cmd/admin) that is now built and
live: admin API (device CRUD + command enqueue), encrypted AES-256-GCM secrets KV
(fail-closed, master key off-disk in the public image), GET /api/events SSE, and
the embedded Svelte 5 operator web UI (//go:embed; login + live roster + read-only
degradation). Honest framing — the SPA shell + roster ship now; the feature pages
(OTA/logs/telemetry/Berry/FaaS/Web-USB) mount in later waves. Also corrected the
stale "a dedicated admin route lands later" note (POST /api/command shipped in A17).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: GottZ

README.md

@@ -14,7 +14,7 @@ Everything is developed in public.
 |---|---|
 | `documentation/` | **published** |
 | `firmware/` | **in progress** — networked run-cycle + recovery guard + Berry render/config engine + HOTP-authed C2 command channel |
-| `backend/` | **in progress** — TimescaleDB + Grafana + telemetry/OTA/log schema + ingest + HOTP-authed C2 command channel |
+| `backend/` | **in progress** — TimescaleDB + Grafana + telemetry/OTA/log schema + ingest + HOTP-authed C2 command channel, plus a bearer-authenticated **operator control plane** (admin API, encrypted secrets KV, embedded Svelte operator web UI) |
 | `tools/` | **started** — picpak-ops operator TUI + air-gap gate (on-device validation pending) |
 | `web-usb/` | not public yet |
 
@@ -129,6 +129,14 @@ A full suite, built clean:
 - [x] [`backend/`](backend/) — self-hostable Docker backend: TimescaleDB + Grafana + the
       telemetry/OTA/log schema + legacy ingest, and the **C2 command channel** (per-device Berry
       command queue + per-device HOTP auth)
+- [x] **operator control plane** (in [`backend/`](backend/)) — a bearer-authenticated admin API in a
+      process and address space **separate from the public ingest parser**: device CRUD + RCE-capable
+      command enqueue, and an **encrypted secrets KV** (AES-256-GCM sealed; the master key is never on
+      disk in the public image and the service fails closed without it). It serves an embedded
+      **operator web UI** — a Svelte 5 SPA (`//go:embed`, one binary, no CORS): key login, a live device
+      roster over server-sent events, and read-only degradation for non-admin keys. The feature pages —
+      OTA rollout, log viewer, telemetry dashboard, Berry editor, FaaS editor, Web-USB onboarding —
+      mount into this shell in later waves.
 - [x] [`tools/`](tools/) — host-side tooling: the **picpak-ops** operator TUI
       (build / flash / console / OTA / telemetry / logs) and the air-gap gate
 

backend/README.md

@@ -5,8 +5,10 @@ Self-hostable telemetry / OTA / log backend for the open-picpak fleet. Go servic
 ad-hoc plotting scripts.
 
 > **Status:** TimescaleDB + Grafana scaffold, schema migration, legacy telemetry ingest, and the
-> **C2 command channel** (per-device Berry command queue + per-device HOTP auth). OTA-signal piggyback,
-> firmware.bin serving, and log reassembly land in later waves.
+> **C2 command channel** (per-device Berry command queue + per-device HOTP auth), plus a
+> bearer-authenticated **operator control plane** (`cmd/admin`: admin API, encrypted secrets KV, and an
+> embedded Svelte operator web UI). OTA-signal piggyback, firmware.bin serving, and log reassembly land
+> in later waves.
 
 ## Quick start (local / dev)
 
@@ -51,8 +53,35 @@ GET  /<INGEST_TOKEN>/c2?sn=<serial>&ack=<applied_seq>&c=<counter>&otp=<hotp>[&wa
   process-wide `LISTEN` connection that fans out in-process to every waiter — or the budget elapses
   (→ 204). Absent/`wait<=0` returns 204 immediately (the battery field poll, no connection hold). One
   DB connection signals the whole fleet.
-- **Enqueue (operator):** insert into `command_queue (serial, script[, note])` — v1 is a SQL/CLI step;
-  a dedicated admin route lands later.
+- **Enqueue (operator):** `POST /api/command` (or per device, `POST /api/devices/{serial}/command`) on
+  the operator control plane below; the enqueue is attributed to the operator key. A direct SQL insert
+  into `command_queue (serial, script[, note])` still works for break-glass.
+
+## Operator control plane (`cmd/admin`)
+
+A second binary, built from `Dockerfile.admin` and run as its own compose service — a **process and
+address space separate from the public `ingest` parser**, so the privileged write path never sits in the
+binary the internet reaches. Bound to host loopback / VPN only (TLS terminates at a tunnel or proxy);
+never published.
+
+- **Bearer auth.** Operator keys live in `operator_keys` (sha256 of the token; the plaintext is shown
+  once at mint and never stored). A soft-revoke (`disabled_at`) authenticates as if absent. Routes split
+  `auth` (any valid key — reads) vs `requireAdmin` (mutations); `GET /api/whoami` reports
+  `{key_id, is_admin, label}`. Keys are minted/listed/revoked out-of-band:
+  `admin create-operator -label <name> [-admin]`.
+- **Encrypted secrets KV.** `PUT/GET/DELETE /api/secrets/{name}` over an AES-256-GCM sealed store; the
+  value is never echoed back. The master key (`SECRETS_KEY`, 32 bytes hex) is injected only into the
+  admin container, lives in a root-only file outside `.env`, and the service **fails closed** without it.
+  Break-glass decrypt is an out-of-band subcommand, not an HTTP route. Back up the key with the host —
+  key loss is total loss.
+- **Live events.** `GET /api/events` is a server-sent-events stream (device-roster snapshot + deltas
+  now; telemetry/log payloads in later waves) with a periodic re-auth that tears the stream down within
+  ~60 s of a key revocation.
+- **Operator web UI.** A Svelte 5 SPA embedded via `//go:embed` (one binary, no second container, no
+  CORS): key login, a live device roster, and read-only degradation for non-admin keys. A checkout
+  without the bun toolchain still builds — the Go binary serves a 503 hint while every `/api` route stays
+  functional. Feature pages (OTA, logs, telemetry, Berry, FaaS, Web-USB onboarding) mount into the shell
+  in later waves. Source + build: `backend/web/` (`bun install && bun run build`).
 
 ## Schema migration