Fix stale documentation across server, pecan, kvaser-bridge, and root docs

Audited docs against current code/config and corrected drift: sandbox
docs still described the removed Cohere integration instead of
MiniMax-M3 via the Anthropic-compatible API; several installer docs
referenced services that no longer exist (startup-data-loader,
timescaledb-explorer) or wrong env var names/ports/API routes
(health-monitor, data-downloader, kvaser-bridge WS port, comms-setup
path); root README referenced the removed pecan-bridge dir and was
missing livestream/; car-simulate port docs and pecan's CAN log format
decision doc were out of date with the shipped implementation.

Author: claude

.hermes/plans/2026-05-21_124500-unified-health-endpoint.md

@@ -1,5 +1,7 @@
 # Unified Health Endpoint
 
+> **Status: Implemented.** The `/health` endpoint exists (`universal-telemetry-software/src/status_server.py`), backed by `data.py` writing the health file, and the 8080 status page polls it every 2s (`universal-telemetry-software/status/index.html`). Documented in `universal-telemetry-software/README.md` and `deploy/MACBOOK_DEPLOY.md`. This plan is kept for historical context only.
+
 ## Goal
 
 Replace the three independent, semi-redundant health detection mechanisms in the telemetry stack with a single `/health` HTTP JSON endpoint that aggregates the authoritative state of every pipeline component. Surface it in the existing 8080 status page UI in place of the current WebSocket-derived indicators.

README.md

@@ -130,9 +130,13 @@ Development and testing tools for simulating vehicle telemetry without physical
 - Example DBC (CAN database) file for message definitions
 - Docker Compose setups for isolated testing environments, including a dev/demo server configuration in `car-simulate/persistent-broadcast`
 
-### CAN Adapter Bridges (`/kvaser-bridge`, `/pecan-bridge`)
+### CAN Adapter Bridge (`/kvaser-bridge`)
 
-GUI adapters for Kvaser and PECAN CAN hardware interfaces. Used during bench testing when physical vehicle hardware is unavailable.
+GUI adapter that bridges a Kvaser CAN interface to the dashboard over WebSocket. Used during bench testing when physical vehicle hardware is unavailable.
+
+### Livestream Overlay (`/livestream`)
+
+OBS Browser Source overlay and setup notes for streaming telemetry alongside live race video. See `livestream/OBS-SETUP.md`.
 
 ### Flight Recorder (`/flight-recorder`)
 
@@ -316,7 +320,7 @@ data-acquisition/
 │       └── slackbot/       # Slack bot
 ├── secret-dbc/        # Git submodule: private DBC files (restricted)
 ├── kvaser-bridge/     # Kvaser CAN adapter GUI
-├── pecan-bridge/      # PECAN CAN adapter
+├── livestream/        # OBS Browser Source overlay for race streams
 └── grafana-worker/    # Cloudflare Workers proxy for Grafana
 ```
 

car-simulate/persistent-broadcast/README.md

@@ -153,7 +153,7 @@ asyncio.run(connect())
 
 ## Data Format
 
-The server broadcasts batches of 100 CAN messages at 5 Hz. Each message has the following format:
+The server broadcasts a mix of generators at different rates (accumulator at 10 Hz, standard-ID frames at 20 Hz, charger frames at 5 Hz), or replays a CSV file if `ENABLE_CSV=true`. Each message has the following format:
 
 ```json
 {
@@ -184,8 +184,8 @@ docker-compose up -d --build
 
 ## Port Configuration
 
-- **8080**: WebSocket (ws://) - unencrypted
-- **8443**: Secure WebSocket (wss://) - encrypted
+- **9080**: WebSocket (ws://) - unencrypted
+- **9443**: Secure WebSocket (wss://) - encrypted
 
 ## Troubleshooting
 
@@ -207,8 +207,8 @@ docker-compose up -d --build
 
 You can customize the following variables in `docker-compose.yml`:
 
-- `WS_PORT`: WebSocket port (default: 8080)
-- `WSS_PORT`: Secure WebSocket port (default: 8443)
+- `WS_PORT`: WebSocket port (default: 9080)
+- `WSS_PORT`: Secure WebSocket port (default: 9443)
 - `CSV_FILE`: Path to CSV data file
 - `SSL_CERT`: Path to SSL certificate
 - `SSL_KEY`: Path to SSL private key

kvaser-bridge/README.md

@@ -33,11 +33,20 @@ python src/main.py
 A small window appears with:
 - **Channel** - select which Kvaser CAN channel to use
 - **Bitrate** - CAN bus bitrate (default 500k)
-- **WS URL** - WebSocket URL of the dashboard (default `ws://localhost:9080`)
+- **WS URL** - WebSocket URL of the dashboard (default `wss://127.0.0.1:9081`; TLS is on by default)
 - **Start/Stop Bridge** - toggle the connection
 
 Click **Start Bridge** to begin streaming CAN frames to the dashboard.
 
+### Trusting the certificate (first run)
+
+The bridge serves a self-signed TLS certificate over `wss://`, so the browser dashboard will refuse the connection until that certificate is trusted:
+
+- **Windows**: click **Trust Certificate (Automatic)** to install it into the current-user Root store (no admin rights needed; works for Chrome/Edge). Use **Manual…** instead for Firefox, or if the automatic install fails.
+- **Other platforms**: click **Trust Certificate** to open the bridge URL in the browser, then click through **Advanced → Proceed** and wait for the green "Certificate trusted" confirmation page.
+
+Do this once per machine/browser before starting the bridge.
+
 ## Build (standalone binary)
 
 ```bash

pecan/README.md

@@ -193,7 +193,7 @@ npm run test:ui
 
 #### Test Coverage
 
-The test suite includes **42 tests** covering:
+The test suite covers:
 
 - ✅ CAN log line parsing (CSV format)
 - ✅ CAN message decoding with DBC files

pecan/docs/CAN_LOG_FORMAT_DECISION.md

@@ -1,5 +1,7 @@
 # PECAN CAN Log Format Decision
 
+> **Status:** Phase 1 (PECAN CSV v1 machine columns) and Phase 4 (`.pecan` session container) are implemented — see `exportCsv()`/`exportPecanSession()` in `src/pages/Trace.tsx` and `src/utils/pecanSerializer.ts`/`src/utils/replayParser.ts`. The "Migration Note" and container `version` below are historical/outdated; the shipped container format is `version: 2` (`serializePecanV2`).
+
 ## Decision Summary
 
 Use a machine-readable raw frame format as the canonical PECAN replay format.

server/docs/comms-setup.md

@@ -24,7 +24,7 @@ Base Station RPI                    Car RPI
 ### Base Station
 
 ```bash
-cd universal-telemetry-software
+cd universal-telemetry-software/deploy
 docker compose -f docker-compose.jitsi.yml up -d
 ```
 
@@ -36,7 +36,7 @@ Access: `http://<base-ip>:8000`
 # Set base station IP first
 export JITSI_URL=http://192.168.1.1:8000
 
-cd universal-telemetry-software
+cd universal-telemetry-software/deploy
 docker compose -f docker-compose.jitsi.yml --profile car up -d car-jitsi-client
 ```
 

server/docs/containers/startup-data-loader.md

@@ -1,5 +1,7 @@
 # Startup data loader
 
+> **Removed.** This service no longer exists in `server/installer/docker-compose.yml` and the `startup-data-loader/` directory it describes is gone. TimescaleDB now starts empty; use the `file-uploader` web UI (or the `data-downloader` scanner/API) to import CAN CSV archives. This doc is kept for historical reference only.
+
 The startup data loader seeds TimescaleDB with a small, deterministic dataset on first boot. It can also backfill additional files if you mount them into the container.
 
 ## Responsibilities

server/docs/docker-compose.md

@@ -5,30 +5,39 @@ The `installer/docker-compose.yml` file orchestrates the complete DAQ telemetry
 ## High-level architecture
 
 ```text
-┌────────────┐                                ┌────────────┐
-│ Startup    │                                │ TimescaleDB │
-│ data loader├───────────────────────────────▶│ + Explorer │
-└────────────┘                                └────────────┘
-       │                                           │
-       │                                           ▼
-       │                               ┌─────────────────────┐
-       │                               │ Grafana dashboards  │
-       ▼                               └─────────────────────┘
-┌────────────┐                                   │
-│ File       │                                   ▼
-│ uploader   ├──────────────────────────────────▶│ Slack bot &
-└────────────┘                                   │ notifications
+┌──────────────┐    ┌───────────┐    ┌───────────────────┐
+│ File uploader│───▶│           │───▶│ Grafana dashboards │
+└──────────────┘    │           │    └───────────────────┘
+                     │           │
+┌──────────────┐     │           │    ┌───────────────────┐
+│ data-downloader   ─┤ TimescaleDB├───▶│ grafana-bridge     │
+│ (api/scanner/UI)   │           │    │ (Pecan → Grafana)  │
+└──────────────┘     │           │    └───────────────────┘
+                     │           │
+┌──────────────┐     │           │    ┌───────────────────┐
+│ sandbox +    │────▶│           │    │ health-monitor      │
+│ code-generator│    └───────────┘    │ (watches containers)│
+└──────────────┘                      └───────────────────┘
+
+┌──────────────┐    ┌──────────────┐
+│ slackbot     │◀──▶│ code-generator│  (Slack `!agent` commands)
+└──────────────┘    └──────────────┘
+
+┌──────────────┐
+│ lap-detector │  (disabled by default; opt in via --profile disabled)
+└──────────────┘
 ```
 
-All containers join the `datalink` bridge network, enabling them to communicate using Docker hostnames (for example `http://timescaledb:8181`).
+All containers join the `datalink` bridge network, enabling them to communicate using Docker hostnames (for example `http://timescaledb:5432`). The actual service list lives in `installer/docker-compose.yml`; see the [service catalogue in the installer README](../installer/README.md#service-catalogue) for ports and one-line descriptions of each service.
 
 ## Volumes
 
 | Volume | Mounted by | Purpose |
 | --- | --- | --- |
 | `timescaledb-data` | `timescaledb` | Persists TimescaleDB metadata and stored telemetry. |
-| `timescaledb-explorer-db` | `timescaledb-explorer` | Keeps explorer UI preferences. |
 | `grafana-storage` | `grafana` | Stores dashboards, plugins, and Grafana state. |
+| `code-generator-chroma` | `code-generator` | Persists the ChromaDB RAG index used for code generation. |
+| `code-generator-cache` | `code-generator` | Persists the diskcache used to avoid re-generating identical requests. |
 
 Remove volumes with `docker compose down -v` if you need a clean slate.
 
@@ -42,14 +51,13 @@ The Slack bot relies on valid `SLACK_APP_TOKEN` and `SLACK_BOT_TOKEN` values. Le
 
 ## Health checks
 
-- `timescaledb` exposes a TCP healthcheck on port 8181 to ensure the database is reachable before dependants start.
-- `startup-data-loader` waits an additional 5 seconds (`sleep 5`) to give TimescaleDB time to finish booting before loading the sample data.
+- `timescaledb` runs `pg_isready` against port 5432 to ensure the database is reachable before dependants start (`data-downloader-api` and `health-monitor` wait on `service_healthy`).
 
 ## Customisation tips
 
 - Override exposed ports in `docker-compose.override.yml` if default host ports conflict with local services.
 - Drop in custom dashboards under `installer/grafana/dashboards/`—Grafana auto-imports JSON files at startup.
-- Swap the example dataset in `installer/startup-data-loader/data/` for real telemetry and update `example.dbc` to match your CAN specification.
+- Import real telemetry via the `file-uploader` web UI, and update `example.dbc` (or set `GITHUB_DBC_PATH`) to match your CAN specification.
 
 ## Useful commands
 
@@ -59,7 +67,7 @@ cd installer
 docker compose config
 
 # Tail logs for a specific service
-docker compose logs -f startup-data-loader
+docker compose logs -f code-generator
 
 # Execute a shell inside the TimescaleDB container
 docker compose exec timescaledb /bin/sh

server/installer/LOCAL_STACK.md

@@ -1,5 +1,7 @@
 # Local Stack — Offline Testing Guide
 
+> **Note:** This guide references `docker-compose.local.yml`, which does not currently exist in `server/installer/` (only `docker-compose.yml`, the full stack, is present). Create that override file yourself (scoping it to `timescaledb`, `grafana`, and `file-uploader`) before following the steps below, or run the equivalent `docker compose -f docker-compose.yml up -d timescaledb grafana file-uploader` against the full compose file instead.
+
 Minimal stack for testing without internet: TimescaleDB, Grafana, and file-uploader only.
 
 ## First-time setup (requires internet)