feat: add live K1 Foxglove console

README.md

@@ -7,6 +7,8 @@ or speculative writes.
 Current status: live proof completed on firmware 3.0.2. The Mac provisioned the
 K1 onto an existing LAN without LixelGO, connected to its MQTT broker, captured
 the scan-correlated point-cloud and pose streams, and decoded both successfully.
+The repository also contains a local React control console and a Foxglove live
+bridge for the verified point-cloud and trajectory topics.
 
 The repository now contains one narrowly gated state-changing command:
 `ble wifi-configure`. It accepts only the reviewed firmware-3 provisioning
@@ -53,6 +55,46 @@ uv run k1link doctor
 uv run pytest
 ```
 
+## Live console and Foxglove
+
+Build the browser control surface once, then launch the whole local stand from
+the repository root:
+
+```bash
+cd apps/k1-viewer
+npm install
+npm run build
+cd ../..
+uv run k1link serve
+```
+
+Open `http://127.0.0.1:8000`. The API, credential form and Foxglove WebSocket
+bind to loopback only. The console supports:
+
+- real CoreBluetooth K1 discovery;
+- one operator-triggered reviewed BLE Wi-Fi provisioning write;
+- live read-only MQTT capture with raw-first evidence storage;
+- replay of native `.k1mqtt` evidence and the reviewed four-column TSV capture;
+- `/k1/points`, `/k1/pose`, `/k1/trajectory` and `/k1/metrics` for Foxglove;
+- measured Mac-side MQTT-receive-to-Foxglove-publish latency and bounded
+  latest-wins preview dropping.
+
+For live mode, start the session in the console and use the verified physical
+double-click on K1 to start or stop scanning. The connector deliberately does
+not publish modeling commands yet. For the recorded proof, replay this ignored
+local file at `1x` with loop enabled:
+
+```text
+sessions/20260715T122850Z_live_power_cycle/captures/mqtt_scan_full_payloads_03.tsv
+```
+
+Foxglove remains the full 3D workspace rather than being reimplemented in the
+React console. In its 3D panel, select `/k1/points`, color by `intensity` (or
+`z`/`<distance>`) and choose Turbo, Rainbow or a custom gradient. Add
+`/k1/trajectory` for the cyan path and `/k1/pose` for the current pose. See the
+[live viewer runbook](docs/06_K1_LIVE_VIEWER.md) for timing semantics and current
+limitations.
+
 `doctor` is intentionally non-invasive. It checks the local Python environment
 and reports external tools; it does not request Bluetooth permission, scan the
 LAN, touch the K1, alter Homebrew, or change capture permissions.
@@ -93,6 +135,7 @@ present.
 - [Artifact and secret policy](docs/03_ARTIFACT_POLICY.md)
 - [Reviewed BLE Wi-Fi profile](docs/04_K1_WIFI_PROVISIONING_PROFILE.md)
 - [Verified MQTT stream profile](docs/05_K1_MQTT_STREAM_PROFILE.md)
+- [Live console and Foxglove runbook](docs/06_K1_LIVE_VIEWER.md)
 - [Redacted live lab report](docs/lab/001_K1_LIVE_MQTT_20260715.redacted.md)
 - [Session manifest schema](schemas/session-manifest.schema.json)
 - [Reference input provenance](docs/reference/README.md)