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>

2 files changed, 48 insertions, 2 deletions

diff --git a/AGENTS.md b/AGENTS.md
index a7b841f..c4ab051 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,7 +13,7 @@ modules.
 
     desktop/          the drawer: sound, mail, VMs, appearance
       island/         top-centre pills on DP-1: clock, volume, tray, layout, privacy,
-                      controls panel (SUPER alone), calendar
+                      controls panel (SUPER alone), calendar, performance
     appearance/       wallpaper picker and colour scheme switcher
     window-switcher/  open windows as live previews in a grid, on ALT+TAB
     keybinds/         live keybind reminder, on SUPER+k
@@ -165,6 +165,15 @@ changing that component. The ones that generalise:
 - **Use `/usr/bin/python3` for calctl and its test.** `python3` on PATH is a
   pyenv shim without `icalendar`; the system interpreter has it, for
   cal-notif.
+- **`FileView` reads `/proc` and `/sys` fine, but only on `reload()`.** With
+  `blockLoading: true`, `text()` straight after `reload()` is the fresh
+  contents, which is how `Perf.qml` samples `/proc/stat` and hwmon every 2s
+  without a subprocess. hwmon numbers move across boots; look chips up by
+  their `name` file.
+- **A hot reload does not resize an existing layer surface.** Raising the
+  island's `implicitHeight` from 360 to 480 reloaded cleanly while `hyprctl
+  layers` still reported `h: 360` and the performance panel stayed cut off;
+  `./reload.sh desktop` applied it. Check the layer size, not the source.
 - **A QML method cannot be named `escape`.** It shadows the global JS
   function, and the file fails with `Illegal method name` at load, which a
   hot reload reports as the whole island being unavailable. The island's
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