diff --git a/README.md b/README.md
index 6d8a478..e0836cb 100644
--- a/README.md
+++ b/README.md
@@ -3,5 +3,54 @@
 btop-style TUI monitor for Alder Lake (i5-12600KF), built around real vCore
 voltage for overclock-safety work.
 
-Current stage: sensor dump tool (`cargo run`). The TUI lands after the
-vCore source spike. See to-do.md.
+## Usage
+
+```sh
+cargo run --release -- --tui    # TUI (default workhorse)
+cargo run -- --vid              # VID spike tool (debug)
+cargo run                       # one-shot sensor dump
+```
+
+The TUI needs a real terminal (pty); it will not run on redirected output.
+
+Features: vCore hero panel (limit marker, 5-min peak, auto-scale), board
+rails, package power/temp, per-core frequency bars + temps, E/P-core
+sections, footer max frequency.
+
+## Config
+
+`adlermon.conf` is read from the working directory, then
+`~/.config/adlermon/adlermon.conf`. Simple `KEY = VALUE` lines; `#`
+comments; unknown keys are ignored. All values optional — built-in defaults
+target an ASRock Z690M ITX/ax (nct6798).
+
+```ini
+vcore_limit   = 1.403   # safety limit shown as marker on the vCore bar
+temp_warn     = 80.0
+temp_crit     = 95.0
+vcore_bar_max = 1.50
+power_bar_max = 200.0
+
+rail.in0.label = CPU Vcore   # hwmon input label
+rail.in4.label = VCCIO?
+rail.in5.hide  = true        # hide unwired/floating inputs
+```
+
+Rail labels for this board were confirmed against the BIOS and differential
+stress-ng probing (2026-08-29); see comments in `adlermon.conf`. The only
+remaining guess is in4 = VCCIO.
+
+## Package power (RAPL) — one-time setup
+
+`energy_uj` is root-only on this kernel. To read watts as a normal user,
+install the udev rule once as root:
+
+```sh
+doas ./powercap-pl-rules.sh
+doas usermod -aG adm $USER   # then re-login
+```
+
+## Status
+
+Working: TUI, config, RAPL power, rail map for Z690M ITX/ax. Remaining
+notes in `to-do.md`.
\ No newline at end of file