docs: document the system widgets

1 files changed, 94 insertions, 0 deletions

diff --git a/README.md b/README.md
index 9c4af64..bc8776c 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,77 @@ with an error body.
 Location and units live in `weather.env` too (`CITY`, `COUNTRY`, `UNITS`), not
 in the source, so no real location appears in committed files.
 
+## System widgets
+
+Four cards cover the machine itself:
+
+- **System**: CPU load as a per-core equaliser, RAM used/total, and every
+  temperature (CPU package, CCD die, NVMe and two board sensors).
+- **GPU**: Arc B580 package and VRAM temperatures, and fan speed.
+- **Disks**: `/`, `/home`, `/data` and one NFS mount per server, as usage
+  rings. Two servers are configured, each with the same export mounted twice;
+  the card shows one mount per server so no number appears twice.
+- **Cache**: `~/.cache` total and its four largest subdirectories.
+
+The disks and cache cards read a cache file that a sampler writes; they never
+call `du` or `statfs` themselves. `statfs` on an unreachable NFS path blocks,
+and the disks sampler exists so that a dead server costs a stale cache rather
+than a frozen draw. Sampling is scheduled by conky itself: `conky.text` carries
+three `${execi}` entries, even though that block renders nothing under Cairo.
+
+    ${execi 900 ~/.config/conky/bin/weather-fetch.sh}
+    ${execi 60  ~/.config/conky/bin/disks-sample.sh}
+    ${execi 900 ~/.config/conky/bin/cache-sample.sh}
+
+The disks sampler runs once a minute; the cache one every 15, because `du -sh
+~/.cache` walks the tree and takes about 100ms warm, which is fine on a slow
+cycle and unthinkable on the 2-second draw. Tying them to conky means nothing
+samples while the dashboard is down.
+
+To run a sampler by hand:
+
+    ./bin/disks-sample.sh; echo "exit: $?"
+    ./bin/cache-sample.sh; echo "exit: $?"
+
+Both print nothing and exit 0 on success, and both write a temp file and rename
+it over the target, so the widget never reads a half-written file.
+
+### Host bindings
+
+These hwmon bindings, and the ceilings beside them, are specific to this machine
+and will not port. They are written down because the alternative is
+rediscovering them from a wrong reading.
+
+| chip | file | label | warning / critical |
+|---|---|---|---|
+| `k10temp` | `temp1_input` | CPU package | 75 / 90 |
+| `k10temp` | `temp3_input` | CCD die | 75 / 90 |
+| `nvme` | `temp1_input` | WD_BLACK SN850X | 60 / 70 |
+| `xe` | `temp2_input` | Arc B580 package | 75 / 85 |
+| `xe` | `temp3_input` | Arc B580 memory | 80 / 90 |
+| `xe` | `fan1_input` | Arc B580 fan RPM | none |
+| `gigabyte_wmi` | `temp2_input` | board | 60 / 70 |
+| `gigabyte_wmi` | `temp3_input` | board | 60 / 70 |
+
+Chips are globbed by the contents of their hwmon `name` file, never by index:
+indices drift across kernel and hardware reorders and a stale one silently
+reports a different chip. `Tccd1` is read straight from sysfs rather than by
+shelling out to `sensors`; same number, no subprocess. The `gigabyte_wmi` chip
+exposes five unlabelled temperatures, two of which the old conky config showed;
+they are labelled "board" rather than given a meaning they may not have.
+
+### One colour language across all four cards
+
+Anything with a comfortable range and an uncomfortable one is coloured by the
+same three roles, so a card reads without learning a new scheme: `ok` below the
+first threshold, `warning` between them, `critical` above the second.
+
+Filesystems, cache usage and CPU load use 25% and 75%. Temperatures use a
+per-sensor pair (the table above), because 70C is unremarkable on a CPU package
+and alarming on an NVMe. These are starting values, host-specific exactly as the
+bindings are, and sit in one table per widget so they are easy to retune once
+real numbers under load are known.
+
 ## Changing the layout
 
 Edit the `layout` table at the top of `dashboard.lua`. `col`/`row` are grid
@@ -247,6 +318,29 @@ blank dashboard rather than a message.
 grid, and scaling off it made the weather text shrink to a whisper beside the
 clock's numerals when its cell got shorter.
 
+**A bare `df` would silently mis-read every disk figure.** The user's shell
+aliases `df` to `df -h`, so `bin/disks-sample.sh` calls `/usr/bin/df -P -B1` by
+absolute path. `-P` is the POSIX format, one line per filesystem with the
+mountpoint last, and `-B1` is bytes so the parser never interprets a suffix. An
+alias or a function would hand the parser `1.6G` where it expects an integer,
+and every figure would be quietly wrong.
+
+**The Arc B580 reports no utilisation through any stable interface.** The `xe`
+driver exposes no `gpu_busy_percent` (unlike `amdgpu`), `intel_gpu_top` refuses
+the device, and `gputop` prints per-process rows with ANSI escapes, which is not
+something to build a widget on. The GPU card therefore has no load bar; it shows
+what the hardware actually reports rather than inventing a number.
+
+**`/data` has no temperature.** It sits on a spinning disk with no hwmon chip;
+reading its SMART temperature would need `smartctl` as root and would spin up a
+sleeping disk on every poll. The NVMe composite temperature is freely readable
+and is shown; `/data` simply has none.
+
+**Per-core counters are module-level in `widgets/system.lua`.** Load is a delta
+between frames, so the counter has to outlive the draw; one created inside
+`draw` would sample against nothing and report nil forever. The aggregate
+counter is the same.
+
 ## License
 
 GPLv2 only. See `LICENSE`.