chore: add CLAUDE.md for session 1

Repo-level CLAUDE.md captures current project state (pre-Phase-A,
architecture decision open, PR #2 in flight), project conventions,
where things live, and the session 1 log pointing at the wiki
retrospective.

.gitignore

@@ -175,3 +175,6 @@ cython_debug/
 # Superpowers brainstorm companion working dir
 .superpowers/
 
+
+# Local wiki checkout (separate git repo)
+docs/wiki/

CLAUDE.md

@@ -0,0 +1,100 @@
+# claude-gauge (repo instructions)
+
+## What this is
+
+Hardware instrument cluster displaying Claude Code session telemetry
+in real time. Four analog needles (5h fuel, tokens/min tach,
+thinking ratio, cache hit) plus annunciator row, driven by an ESP32
+polling a local Python daemon. Full documentation lives in the
+[wiki](https://forgejo.labbity.unbiasedgeek.com/archeious/claude-gauge/wiki).
+
+## Current Project State
+
+* **Phase**: pre-Phase-A. Scaffolded, planned, not yet implementing.
+* **Last worked on**: 2026-04-17
+* **Last commit on main**: `a683828` — Initial scaffold
+* **Open PRs**: #2 (flesh out PLAN.md, add wiki + README image)
+* **Open issues**: #1 (flesh out PLAN.md; tracked by PR #2)
+* **Architecture decision**: **open**. PR #2 recommends A (OTEL +
+  Prometheus) over B (ccusage + JSONL tail). Must be chosen before
+  Phase A ships because the daemon implementation differs.
+* **Migrations**: n/a (no DB yet)
+* **Blocking issues**: architecture choice
+
+## Project conventions
+
+* **Issue-driven work**: every change ties to a Forgejo issue.
+  Branch as `feat/<issue>-<slug>`.
+* **Atomic commits**. One logical change each.
+* **Merge via Forgejo API / UI**, not `git merge` locally. Delete
+  remote branch, `git pull --ff-only`, delete local branch, close
+  the tracking issue manually.
+* **Wiki checkout** lives at `docs/wiki/` (gitignored in the main
+  repo; it is its own git repo against
+  `archeious/claude-gauge.wiki.git`).
+
+## Where things live
+
+* `PLAN.md` — working notes and full two-architecture plan.
+* `README.md` — short overview, render image, wiki pointer.
+* `docs/images/` — tracked images (monitor-dash, exotic-dashes).
+* `docs/wiki/` — local wiki checkout; commit and push separately
+  to the wiki remote.
+* `src/claude_gauge/` — Python package skeleton (no runtime code
+  yet).
+* `tests/` — test skeleton.
+* `pyproject.toml` — uv-managed Python 3.12+, no dependencies
+  declared yet (picked per architecture).
+
+## Architecture choice (open)
+
+See [DataSources](https://forgejo.labbity.unbiasedgeek.com/archeious/claude-gauge/wiki/DataSources) for specifics.
+Short form:
+
+| | A. OTEL-native | B. ccusage-sourced |
+|---|---|---|
+| Data source | Claude Code OTLP -> Prom | ccusage CLI + JSONL tail |
+| Day 1 to ship | Two (stand up stack first) | One |
+| Deep-stats dashboard | Grafana 25052 free | None / ccusage TUI |
+| Homelab-enterprise fit | Strong | Weak |
+
+Default recommendation: A.
+
+## Session Log
+
+Most recent 3 sessions (full history in the
+[wiki](https://forgejo.labbity.unbiasedgeek.com/archeious/claude-gauge/wiki/SessionRetrospectives)).
+
+### Session 1 — 2026-04-17
+
+Greenfield conception through a full two-architecture plan and
+seven-page wiki. Notable milestones:
+
+* Project conceived mid-session from "can we read Claude Max usage
+  programmatically" -> "I want an analog needle gauge for it" ->
+  "like an instrument cluster in a fighter jet."
+* Prior-art research: software side of LLM-usage tracking is
+  crowded (ccusage, Claude-Code-Usage-Monitor, multiple Grafana
+  dashboards, Anthropic's own monitoring guide). Physical-gauge
+  variant for LLM usage has zero prior art.
+* Claude Code ships with native OpenTelemetry support; architecture
+  A piggybacks on it. Grafana dashboard 25052 is a free deep-stats
+  surface.
+* Architecture B (ccusage CLI + watchdog tail) is documented as the
+  faster-start alternative.
+* Adopted the image-rendered four-gauge layout (5h fuel, tach,
+  thinking ratio, cache hit) over the original three-gauge plan.
+  The 7d window moves too slowly to warrant a needle.
+* Hardware path: X27.168 steppers + Arduino SwitecX25 library on
+  ESP32 Arduino C++ (no MicroPython port exists). Motorcycle
+  tachometers documented as a V1 shortcut (Liam Jackson's prior
+  art).
+* Seven wiki pages: Home, Architecture, DataSources, Hardware,
+  Ecosystem, Roadmap, Ideas. Monitor Dash render on Home and
+  README; exotic variants on Ideas.
+* PR #2 open against main with the full plan; issue #1 tracks it.
+
+One side-deliverable: a quartermaster MCP proposal document drafted
+earlier in the session (now PR #24 on that repo).
+
+Full retro: [Session1](https://forgejo.labbity.unbiasedgeek.com/archeious/claude-gauge/wiki/Session1).

README.md

@@ -1,19 +1,39 @@
 # claude-gauge
 
-Hardware instrument cluster plus companion web dashboard for Claude
+Hardware instrument cluster displaying Claude Code session telemetry
-Code session telemetry.
+in real time.
 
-A local Python daemon tails `~/.claude/projects/**/*.jsonl`, parses
+![Monitor-mounted cluster with four gauges and annunciator row](docs/images/monitor-dash.png)
-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.
 
-See [PLAN.md](PLAN.md) for architecture, the instrument cluster
+Four analog needle gauges (5h fuel, tokens/min tach, thinking ratio,
-layout, the dashboard sections, the full metrics brainstorm, and
+cache hit) plus an annunciator row of model-indicator and warning
-the phasing plan.
+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.
+
+Fighter-jet / race-car aesthetic. Physical-first: the deep stats
+live in Grafana (A) or `ccusage` (B); the dial on the desk is the
+ambient summary.
+
+## Documentation
+
+Full documentation is in the [wiki](https://forgejo.labbity.unbiasedgeek.com/archeious/claude-gauge/wiki):
+
+* **Home** — overview and cluster at a glance
+* **Architecture** — two-architecture tradeoff, daemon contract
+* **DataSources** — Docker Compose + PromQL (A), `ccusage` +
+  watchdog (B)
+* **Hardware** — X27.168 steppers, ESP32 wiring, firmware,
+  enclosure
+* **Roadmap** — phases, shipped, deferred
+* **Ideas** — exotic enclosure variants, metrics brainstorm,
+  parked thoughts
+
+Working notes live in [PLAN.md](PLAN.md). Session records and
+in-flight thinking happen there; the wiki is the curated surface.
 
 ## Status
 
-Scaffolded. Phase A (daemon MVP) is the first issue.
+Scaffolded. Phase A pending architecture decision.