From b98a5482faf5108fad47ffa8875ccdda01050a2a Mon Sep 17 00:00:00 2001
From: Ryan Malloy <ryan@supported.systems>
Date: Tue, 17 Feb 2026 17:54:35 -0700
Subject: [PATCH] Document screenshot capture workflow and MCP server

---
 CLAUDE.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 8fc54dc..af07d0b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -739,3 +739,75 @@ ssh -A warehack-ing@warehack.ing "cd birdcage-docs && git pull && make prod"
 ```
 
 TLS is automatic via caddy-docker-proxy (ACME + Vultr DNS challenge). New subdomains take ~2 minutes for certificate issuance.
+
+### Screenshots
+
+TUI screenshots live in `site/public/screenshots/` (the site repo, not the main repo).
+An automated capture script uses Textual's Pilot API to render each screen in demo mode.
+
+**Regenerating all screenshots:**
+
+```bash
+cd tui && uv run python scripts/capture_screenshots.py
+```
+
+This captures 8 SVG + 8 PNG screenshots plus a 2×3 collage:
+- `tui-dashboard` — F1 action cards
+- `tui-control` — F2 Manual mode with compass rose
+- `tui-craft-search` — F2 Craft mode with satellite search results
+- `tui-craft-tracking` — F2 Craft mode tracking the Moon
+- `tui-signal` — F3 Monitor mode with RSSI gauge and receiver info
+- `tui-system` — F4 Hardware mode with firmware ID and A3981 diagnostics
+- `tui-console` — F5 overlay with serial console
+- `tui-camera` — F6 overlay with capture triggers
+- `tui-collage` — 2×3 montage of 6 main screens (via ImageMagick `montage`)
+
+**Dependencies:** `rsvg-convert` (SVG→PNG), `montage` (collage).
+
+**When to regenerate:** After any UI change that affects widget layout, button labels,
+or screen content. The script populates Craft search results and tracking state
+directly via widget API for deterministic screenshots.
+
+## MCP Server
+
+| Property | Value |
+|----------|-------|
+| Package | `birdcage-mcp` |
+| Source | `mcp/src/birdcage_mcp/` |
+| Entry point | `birdcage_mcp.server:main` |
+| Tools | 35 (connection, movement, signal, system, satellite, console) |
+| Resources | 5 (`birdcage://config`, `position`, `firmware`, `motor-dynamics`, `el-limits`) |
+| Prompts | 3 (`setup_wizard`, `satellite_tracking_guide`, `rf_sweep_guide`) |
+| Tests | `mcp/tests/` — 49 tests against DemoDevice via `run_server_async` |
+
+### Running
+
+```bash
+# Demo mode (no hardware)
+BIRDCAGE_DEMO=1 uv run --directory mcp birdcage-mcp
+
+# Hardware mode
+BIRDCAGE_PORT=/dev/ttyUSB2 uv run --directory mcp birdcage-mcp
+```
+
+### Adding to Claude Code
+
+```bash
+claude mcp add birdcage-mcp -- env BIRDCAGE_DEMO=1 uv run --directory mcp birdcage-mcp
+```
+
+### Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `BIRDCAGE_DEMO` | `false` | Enable demo mode (DemoDevice + DemoCraftClient) |
+| `BIRDCAGE_PORT` | `/dev/ttyUSB0` | Serial port for hardware mode |
+| `BIRDCAGE_FIRMWARE` | `g2` | Firmware variant (`g2`, `hal205`, etc.) |
+| `BIRDCAGE_CRAFT_URL` | `https://space.warehack.ing` | Orbital prediction API |
+
+### Testing
+
+```bash
+cd mcp && uv run pytest tests/       # 49 tests via FastMCP run_server_async
+uv run ruff check src/                # Lint
+```