docs: document the network and slackware cards

Notes the two things a reader would otherwise get wrong: br0 is a bridge, so
local VM traffic shows up in the chart, and the disks card reads df's
available column rather than computing size minus used, which would overstate
free space by the root-reserved blocks.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 69 insertions, 15 deletions

diff --git a/README.md b/README.md
index ba3e260..bf71d2d 100644
--- a/README.md
+++ b/README.md
@@ -63,39 +63,85 @@ in the source, so no real location appears in committed files.
 
 ## System widgets
 
-Four cards cover the machine itself:
+Six 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).
+- **System**: CPU load as a per-core equaliser, the CPU and motherboard model
+  as two rows under the header, 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.
+  rings, with free space and total size printed under each ring. 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.
+- **Network**: LAN and public address, and download/upload throughput as two
+  lines on one chart. See below.
+- **Slackware**: distribution version, package count, kernel, install age, and
+  time since the last `slackpkg` ChangeLog update. See below.
 
 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.
+five `${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}
+    ${execi 900  ~/.config/conky/bin/weather-fetch.sh}
+    ${execi 60   ~/.config/conky/bin/disks-sample.sh}
+    ${execi 900  ~/.config/conky/bin/cache-sample.sh}
+    ${execi 1800 ~/.config/conky/bin/pubip-sample.sh}
+    ${execi 900  ~/.config/conky/bin/slackware-sample.sh}
 
-The disks sampler runs once a minute; the cache one every 15 minutes, because `du -sh
+The disks sampler runs once a minute; the cache, Slackware and public-IP
+samplers run every 15, 15 and 30 minutes respectively, 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.
+cycle and unthinkable on the 2-second draw, and a residential public address
+does not change often enough to warrant asking more frequently. 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: $?"
+    ./bin/pubip-sample.sh; echo "exit: $?"
+    ./bin/slackware-sample.sh; echo "exit: $?"
 
-Both print nothing and exit 0 on success, and both write a temp file and rename
+All print nothing and exit 0 on success, and all write a temp file and rename
 it over the target, so the widget never reads a half-written file.
 
+### Network
+
+The chart plots download and upload as two lines on **one shared vertical
+scale**: scaled independently they would lie about their relative size, which
+is the entire reason to draw them together. The window peak is printed at the
+chart's top-left and the live rates at the bottom corners, each in its line's
+colour. History is module state inside `widgets/network.lua`, one sample per
+pixel column of the chart so it is exactly as wide as the card and never
+interpolates; it does not survive a `restart.sh` or a conky restart, so the
+chart starts empty and fills left to right.
+
+The rates come from the graphed interface's own byte counters under
+`/sys/class/net`, read on every draw: two file reads, no subprocess. The LAN
+address comes from `ip -4 addr show br0` and is memoized on first success,
+retried while nil because a bridge may not be up yet when conky starts. The
+public address comes from the cache file `bin/pubip-sample.sh` writes; once
+that cache is older than four hours the card shows `--` instead, because an
+address that may no longer be yours displayed with confidence is worse than a
+dash.
+
+**`br0` is a bridge, not a physical interface**, and the `IFACE` constant at
+the top of `widgets/network.lua` is the one edit that changes which interface
+is graphed. VM-to-host traffic crosses a bridge without reaching the router,
+so a local copy of that traffic appears in the chart. This carries over
+unchanged from the previous text config and is accepted behaviour, not a bug.
+
+### Slackware
+
+The big top-right value is the time since `/var/lib/slackpkg/ChangeLog.txt`
+last changed, coloured `ok` under 24 hours, `warning` to a week, `critical`
+beyond, the same three-role language the system, GPU, disks and cache cards
+use. Below it: distribution version, package count, kernel, and install age
+(the root filesystem's birth time, where the filesystem records one).
+
 ### Host bindings
 
 These hwmon bindings, and the ceilings beside them, are specific to this machine
@@ -120,7 +166,7 @@ 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
+### One colour language across every card
 
 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
@@ -128,7 +174,9 @@ 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
+and alarming on an NVMe. The Slackware card's ChangeLog age uses the same
+three roles on an hour scale (24 / 168) instead of a percentage. 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.
 
@@ -335,6 +383,12 @@ 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 disks card shows `df`'s available column, not `size - used`.** On this
+machine's root filesystem the two differ by about 13GB of root-reserved
+blocks, which exist on disk but are not available to any non-root user. A
+card that computed free space as `size - used` would overstate it by exactly
+that reserve.
+
 **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