docs: wallpaper transitions

Also how to check a shader headless: the offscreen platform is the
software backend, where a ShaderEffect draws nothing, and an end frame
check passes for every shader while proving nothing.

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

1 files changed, 9 insertions, 2 deletions

diff --git a/AGENTS.md b/AGENTS.md
index f7f62a8..30bba4f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,8 +13,8 @@ modules.
 
     desktop/          the drawer (SUPER alone): user details, sound, mail, VMs, status,
                       performance, clipboard, updates; and the settings
-                      window for pages set once: wallpaper, theme, theme status, icons,
-                      sunset, idle (the former appearance shell), notifications, autostart, shells,
+                      window for pages set once: wallpaper, transitions, theme, theme status,
+                      icons, sunset, idle (the former appearance shell), notifications, autostart, shells,
                       the assistant's daemon and presets, qtmaildir, git,
                       Hyprland's keyboard shortcuts, options and monitors, fonts
       island/         top-centre pills on DP-1: clock, volume, tray, layout, privacy,
@@ -81,6 +81,13 @@ returns 144. Always `-x`, never `-f`.
 For anything visual, ask. Screenshots of a transient OSD are a race, and the
 user has the screen.
 
+**A shader can be checked headless, but not with `QT_QPA_PLATFORM=offscreen`.**
+That is the software backend, where a `ShaderEffect` draws nothing, so the new
+picture shows through and an "is the end frame the new picture" check passes
+for every shader while proving nothing. Run Qt's `qml` tool under `Xvfb` with
+`QT_QPA_PLATFORM=xcb LIBGL_ALWAYS_SOFTWARE=1`, which gives llvmpipe, and compare
+`grabToImage` frames; `QSG_INFO=1` prints the backend.
+
 ## Per-component notes
 
 Each directory's README carries its own, and they are worth reading before