docs: update README and CLAUDE.md for SharedCameraSource and CI observability

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kieranmanning

CLAUDE.md

@@ -52,11 +52,13 @@ ClientPython/
 - Signaling WebSocket is **never** closed by WebRTC state changes — only by unrecoverable signaling errors
 
 ### Video Capture (`intercomclient/camera_video_stream_track.py`)
-- `CameraVideoStreamTrack` extends `aiortc.VideoStreamTrack`
-- Uses `cv2.VideoCapture` to capture frames from camera source (default device `0`, configurable via `VIDEO_SOURCE`)
-- Converts frames to `av.VideoFrame` (BGR24 format) with proper PTS/time_base timestamps
-- `recv()` loops until a frame is captured (no recursion)
-- `stop()` releases `VideoCapture` to avoid device handle leaks when the PC is replaced
+- `cv2.VideoCapture` can only be opened **once** per process on this hardware. Multi-viewer support is handled by `SharedCameraSource`:
+  - Opens the capture device once; runs a `_read_loop` background task that reads frames and fan-outs to per-viewer `asyncio.Queue(maxsize=4)`.
+  - Subscribers call `subscribe(key) → Queue` / `unsubscribe(key)`. If a queue is full, the oldest frame is dropped (never blocks the read loop).
+  - Released via `stop()` when all viewers disconnect; recreated on next connection.
+- `CameraVideoStreamTrack` extends `aiortc.VideoStreamTrack`; subscribes to a `SharedCameraSource` on init, unsubscribes in `stop()`.
+- Converts frames to `av.VideoFrame` (BGR24 format) with proper PTS/time_base timestamps.
+- `PiClient._get_or_create_camera_source()` — lazily opens the camera; `_release_camera_if_idle()` — stops and nulls it when `peer_connections` is empty.
 
 ### Telemetry (`intercomclient/telemetry.py` — `TelemetryClient`)
 - `send(event, message="", level="INFO")` — synchronous; called via `asyncio.to_thread` from async contexts
@@ -135,3 +137,10 @@ devices:
 ## `.envrc`
 
 **Never modify `.envrc`.** It contains local-only developer environment config and must always reflect the developer's own setup.
+
+## CI/CD Observability
+
+Both workflows send a structured event to Honeycomb's Events API (`github-actions` dataset) at the end of every job (pass or fail). Fields: `workflow`, `job`, `status`, `duration_ms`, `sha`, `ref`, `actor`, `repository`, `run_id`, `run_number`, `commit_message`. Requires the `HONEYCOMB_API_KEY` GitHub Actions secret. Honeycomb failures are non-fatal.
+
+- `build-docker.yml` — one job (`build-and-push`), one event per run
+- `build-deb.yml` — two jobs (`test`, `build`), one event per job per run

README.md

@@ -0,0 +1,49 @@
+# Intercom Python Client
+
+Python device client that authenticates via OAuth2 device flow, streams camera video over WebRTC, and sends telemetry to the Intercom API.
+
+## Tech Stack
+
+- **Python 3.14+**, **uv**
+- **aiortc** (WebRTC), **OpenCV** (camera capture), **websockets** (signaling), **requests** (HTTP)
+
+## Development
+
+```bash
+# From the repo root (recommended)
+docker compose up -d clientpython
+
+# Logs
+docker compose logs -f clientpython
+
+# Rebuild after code changes
+docker compose up -d --build clientpython
+```
+
+Requires `/dev/video0` on the host (mapped into the container). Tokens and OAuth config are shared with the `utility` service via Docker volumes.
+
+## Camera Architecture
+
+A single `SharedCameraSource` opens `cv2.VideoCapture` once and fans frames to per-viewer `asyncio.Queue`s. Each `CameraVideoStreamTrack` subscribes with a unique viewer key. This supports multiple simultaneous viewers without attempting to re-open the device. The camera is released when all viewers disconnect, and re-opened on the next connection.
+
+## CI/CD
+
+Push to `master` triggers two workflows:
+
+**`build-docker.yml`** — builds and pushes `docker.kmanning.ie:5000/intercom-python-client:{latest,sha,version}` (ARM runner)
+
+**`build-deb.yml`** — runs pytest, then builds a native ARM64 binary with Nuitka and packages it as a `.deb` for Raspberry Pi installation. Uploads the artifact with 30-day retention.
+
+Both workflows send a structured event to Honeycomb (`github-actions` dataset) at job completion — requires `HONEYCOMB_API_KEY` GitHub secret.
+
+## Installation on Raspberry Pi (from .deb)
+
+```bash
+sudo dpkg -i intercom-client_<version>_arm64.deb
+
+# Configure
+sudo nano /etc/intercom-client/env
+
+# Enable and start
+sudo systemctl enable --now intercom-client
+```