# aldermon

btop-style TUI monitor for Alder Lake (i5-12600KF), built around real vCore
voltage for overclock-safety work.

## Usage

```sh
aldermon --tui          # TUI (default workhorse)
aldermon --vid          # VID spike tool (debug; needs MSR access, see below)
aldermon --log          # append CSV samples to ./aldermon-vid.log
aldermon                # one-shot sensor dump
aldermon --help         # options
aldermon --version      # aldermon x.y.z
```

The TUI always shows the delivered vCore (SIO in0), the CPU's requested SVID
setpoint (IA32_PERF_STATUS), and the delta (delivered − requested; negative =
VRM droop, positive = LLC overshoot). VID needs MSR access: run under root,
or install once (below) — the setcap'd `aldermon-msr` helper holds
`CAP_SYS_RAWIO`, the app itself stays unprivileged. Without access the panel
shows `VID n/a (no msr access)`.

`--log` appends one CSV row per poll to `./aldermon-vid.log` (header +
per-CPU VID / frequency / raw MSR columns). With `--tui` it logs live; with
`--vid` it logs continuously until interrupted.

Short flags group: `-lvt` == `--log --vid --tui`.

The TUI needs a real terminal; piped/redirected stdout exits with a clear
error instead of a panic.

Features: vCore hero panel (limit marker, 5-min peak, auto-scale),
package power/temp, per-core frequency bars + temps, E/P-core sections,
braille sub-pixel scrolling graphs, footer max frequency.

## Config

`aldermon.conf` is read from the working directory, then
`~/.config/aldermon/aldermon.conf`, then `/etc/aldermon/aldermon.conf`
(first file found wins; no merging). Simple `KEY = VALUE` lines; `#`
comments; unknown keys are ignored. All values optional — built-in
defaults target an ASRock Z690M ITX/ax (nct6798). Numeric keys are
range-checked; an out-of-range value falls back to the default.

```ini
vcore_limit   = 1.403   # safety limit shown as marker on the vCore bar
temp_warn     = 80.0
temp_crit     = 95.0

# Per-graph y scales (also editable in the settings pane, F2)
vcore_min     = 0.0
vcore_bar_max = 1.50
clock_min     = 0          # kHz
clock_bar_max = 4500000
power_min     = 0.0
power_bar_max = 200.0
temp_min      = 0
temp_max      = 100

poll_ms         = 250      # sample/tick period (50..10000)
graph_secs      = 300      # history kept, sizes peaks + auto-scale
graph_scale_fixed = false  # true = pin to the scales above
graphs          = true
layout          = auto     # auto | single | dual
```

## Install

One command, from this directory:

```sh
./aldermon-install.sh   # recon -> printed plan -> confirm -> ONE doas/sudo
                        # prompt -> install only what's needed -> verify
```

Stages: **[1/4]** binary+helper — version-gated (installs if missing or
older, skips if current); **[2/4]** `/etc` config — only if missing (your
system-conf edits survive; per-user `~/.config/aldermon/` never touched);
**[3/4]** watts — powercap udev rule + chmod helper (group `adm`);
**[4/4] VID is OPTIONAL**: after the root prompt the installer asks whether
to add the msr udev rule + helper capability. Declining leaves vCore/temps/
freqs untouched (already unprivileged) — the panel just keeps showing
`VID n/a (no msr access)`.

Modes: `--check` status report, changes nothing; `--setup` privileged parts
only (for staged/package installs); `--clean`/`-c` force-reinstall binary,
helper, permissions and STOCK config; `--vid`/`--no-vid` pre-answer stage 4;
`--yes`/`-y` accept the plan without prompting; `--uninstall` removes the
binaries, capability, udev rules and RUN helper and restores the device
nodes' stock permissions (keeps your `/etc` config); `--purge` also deletes
the config. On uninstall it asks whether to drop your user from group `adm`
(`--del-adm`/`--keep-adm` pre-answer).

Low-level: `make check`, `doas make install` (honors PREFIX/DESTDIR; keeps
an existing system conf; setcaps when unstaged — run
`aldermon-install.sh --setup` after staged installs), `make uninstall`
reverses (leaves the system conf dir if non-empty).

## Why the privileges look like this (RAPL watts + VID)

- RAPL `energy_uj` is `0400` root-only; powercap has NO devnode, so udev's
  `RUN+=` helper chgrp/chmods it to `0440 adm`.
- `/dev/cpu/*/msr` (VID) passes TWO gates on open: the DAC file-mode check
  first (nodes are `0600` — `CAP_SYS_RAWIO` is not `CAP_DAC_OVERRIDE`, so
  setcap alone gets `EACCES`), then `msr_open()`'s `capable(CAP_SYS_RAWIO)`
  (so chmod alone gets `EPERM`). The installer opens both: udev
  `MODE/GROUP 0440 adm` for the nodes, `cap_sys_rawio+ep` on the read-only
  `aldermon-msr` helper only — the app never holds the capability.
- Once per user: the installer adds you to group `adm` if missing; activate
  it with a re-login (or `newgrp adm` for the current shell). Uninstall asks
  whether to remove you from `adm` (`adm` also grants log access).

## Status

Working: TUI, config (+ system /etc default), RAPL power. Remaining
notes live in the local-only `.LLM_Memory/` (gitignored).