docs: the performance panel

What the panel shows, the dot's thresholds and their lack of
hysteresis, why the public IP is pinned, and what is sampled always
versus only while open. AGENTS.md gains two gotchas found building it:
FileView reads /proc on reload(), and a hot reload does not resize an
existing layer surface, which left the panel cut off after the height
was raised.

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

1 files changed, 38 insertions, 1 deletions

diff --git a/desktop/island/README.md b/desktop/island/README.md
index 96716d2..c4cf35f 100644
--- a/desktop/island/README.md
+++ b/desktop/island/README.md
@@ -46,8 +46,11 @@ is open or not. Click opens the calendar panel.
 
 ## Status pill
 
-Left to right: controls icon, volume icon, tray, layout flag.
+Left to right: performance icon, controls icon, volume icon, tray, layout
+flag.
 
+- **Performance icon** opens the performance panel, see below. A dot on its
+  corner warns when something needs attention.
 - **Controls icon** opens the controls panel, see below.
 - **Volume icon** shows the default sink (muted, low, medium, high). Click
   opens the sound panel.
@@ -81,6 +84,40 @@ they change and keeping keys it does not know. A tile added to the code
 later starts hidden. Pure helpers in `Controls.js`, tested with
 `node island/test_controls.js`.
 
+## Performance panel
+
+The system monitor icon, first in the status pill, opens a card grid of the
+figures the conky dashboard used to show: CPU load with a bar per core, the
+CPU model, RAM and five temperatures; the Arc B580's temperatures, VRAM and
+fan (no utilisation, xe exposes none); download and upload over the last
+minute, the LAN address and the public IP; and the five mounts with their
+usage. `perf/Perf.qml` reads them; `perf/Perf.js` holds the parsing, tested by
+`node desktop/island/perf/test_perf.js`.
+
+A dot on the icon shows 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, so the dot works with
+the panel closed. Per-core load, the network rate, VRAM (a scan of every
+fdinfo, ~14ms) and the fan run only while the panel is open, and the panel
+itself is loaded only then. The mount list, `br0`, the GPU name and the
+12 GiB VRAM size are constants in `Perf.qml`.
+
 ## Calendar panel
 
 The clock pill opens a month grid beside the selected day's agenda. Dots