1 files changed, 36 insertions, 0 deletions
diff --git a/desktop/modules/perf/README.md b/desktop/modules/perf/README.md
new file mode 100644
index 0000000..dea5a7e
--- /dev/null
+++ b/desktop/modules/perf/README.md
@@ -0,0 +1,36 @@
+# perf
+
+The figures the conky dashboard used to show, as a drawer page of cards, one
+per row; the page scrolls. CPU load with a bar per core, the CPU model and
+RAM; every temperature as a tile; the Arc B580's VRAM and fan (no
+utilisation, xe exposes none); download and upload over the last minute, the
+LAN address and the public IP; the five mounts with their usage; and
+`~/.cache` with its five largest children. `Perf.qml` reads them; `Perf.js`
+holds the parsing, tested by `node desktop/modules/perf/test_perf.js`.
+
+The tile shows CPU and RAM, and a dot for the worst of these, yellow or red:
+
+| Input | Yellow | Red |
+| --- | --- | --- |
+| each temperature | its warn | its crit |
+| RAM | 85% | 95% |
+| each disk | 90% | 95% |
+| public IP | | differs from the pinned one |
+
+CPU load is left out, since spikes would flicker it. There is no hysteresis,
+so a sensor sitting on its threshold can toggle the dot. The pin beside the
+public IP stores the address shown as `perf.pinnedIp` in
+`$XDG_STATE_HOME/quickshell/desktop.json`; the check exists because the VPN
+into the LAN depends on the ISP's fixed address. The fetch is
+`curl -4 https://ipinfo.io/ip` every 30 minutes from the last attempt, into
+`~/.cache/udt/pubip.txt`, the file conky's sampler used. A failed fetch is
+never a mismatch: the old value goes stale after 4 hours and shows as a dash.
+
+CPU, RAM, temperatures and disks are sampled always. Per-core load, the
+network rate, VRAM (a scan of every fdinfo, ~14ms) and the fan run only while
+the page is open. The mount list, `br0`, the GPU name and the 12 GiB VRAM
+size are constants in `Perf.qml`.
+
+The cache card runs `du -B1 -d1` once each time the page opens, 28ms over
+2 GiB, instead of reading conky's 15-minute `cachesize.txt`. The largest
+child is yellow, red when it holds over half the total, as conky had it.