README.md

@@ -1,19 +1,31 @@
 # claude-gauge
 
-Hardware instrument cluster plus companion web dashboard for Claude
-Code session telemetry.
+Hardware instrument cluster displaying Claude Code session telemetry.
 
-A local Python daemon tails `~/.claude/projects/**/*.jsonl`, parses
-structured events into rolling windows and aggregate stats, and
-exposes them over HTTP. An ESP32 or Pi Pico drives a three-gauge
-analog cluster on the desk (tokens/min tach, 5h fuel, 7d fuel) with
-an annunciator row of model and warning lamps. A browser dashboard
-on the same port surfaces the deep stats.
+Three analog needle gauges (5h fuel, tokens/min tach, 7d fuel) plus
+an annunciator row of model-indicator and warning lamps, driven by
+an ESP32 polling a local Python daemon. The daemon reads either
+Claude Code's native OpenTelemetry feed through a Prometheus stack
+(architecture A) or `ccusage` CLI aggregates with a direct JSONL
+tail for the tach (architecture B). Firmware and cluster are
+identical across both.
 
-See [PLAN.md](PLAN.md) for architecture, the instrument cluster
-layout, the dashboard sections, the full metrics brainstorm, and
-the phasing plan.
+Fighter-jet / race-car aesthetic. Physical-first: all the deep
+stats live in Grafana (A) or ccusage's own surfaces (B). The dial
+on the desk is the ambient summary.
+
+See [PLAN.md](PLAN.md) for:
+
+* Instrument cluster layout and annunciator semantics
+* Architecture A: Docker Compose stack, Claude Code env config,
+  PromQL queries, daemon sketch
+* Architecture B: ccusage subprocess integration, watchdog tail,
+  daemon sketch
+* Hardware: X27.168 steppers, SwitecX25 library, ESP32 wiring,
+  enclosure notes
+* Six-phase plan from daemon MVP through enclosure V1
+* Full metrics brainstorm for later phases
 
 ## Status
 
-Scaffolded. Phase A (daemon MVP) is the first issue.
+Scaffolded. Phase A pending architecture decision and first issue.