docs: the desktop shell and what the merge changed

Five components become three, and the Theme symlink count with them. Two
new notes: a pragma Singleton in a subdirectory resolves through a plain
directory import with no qmldir, and Virsh.sampling gates only the stats
poll, not the lifecycle stream that keeps the tile correct while the page
is closed.

1 files changed, 16 insertions, 9 deletions

diff --git a/AGENTS.md b/AGENTS.md
index ee37cf7..67603e2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,12 +6,11 @@ Guidance for agents working in this repository.
 
 Quickshell components for a Hyprland desktop, one per directory, each a
 complete shell in its own right. They are not modules of a single bar: any of
-them runs alone, and running one does not require the others.
+them runs alone, and running one does not require the others. One of them,
+`desktop/`, is itself a host for modules.
 
-    volume-osd/       volume for output and input, plus what is playing
-    vm-manager/       libvirt drawer: state, live stats, snapshots
+    desktop/          the drawer: sound, mail, VMs, appearance
     appearance/       wallpaper picker and colour scheme switcher
-    mail-overview/    notmuch unread counts per account, waybar icon and drawer
     window-switcher/  open windows as live previews in a grid, on ALT+TAB
 
 They are started from `~/.config/hypr/sections/autostart.lua` and keep running
@@ -137,6 +136,14 @@ changing that component. The ones that generalise:
   not `(0, 0)`. An aspect ratio guard has to test for a positive height: the
   obvious rewrites, `!== 0` or a truthiness check, all pass on `-1` and produce
   a negative ratio.
+- **A `pragma Singleton` in a subdirectory needs no `qmldir`.** A plain
+  directory import resolves it, the same way quickshell resolves the
+  `Theme.qml` symlink. Tested while merging the components: the control was a
+  reference to an undefined type, which warns `ReferenceError: <name> is not
+  defined`, and the singleton case produced no such warning.
+- **`Virsh.sampling` gates the 2s stats poll, not the whole service.** The
+  lifecycle event stream runs unconditionally, which is what keeps the VM list
+  and the tile's dots current while the page is closed.
 
 ## Theme
 
@@ -163,7 +170,7 @@ they never had. A symlink rather than a shared import path because a singleton
 outside the config directory needs a `qmldir`, which is the same friction that
 keeps the palette parsed rather than imported; quickshell follows the link and
 resolves the singleton with no qmldir and no consumer change. Editing any
-component's `Theme.qml` edits all five. Do not replace a link with a copy.
+component's `Theme.qml` edits all three. Do not replace a link with a copy.
 
 ## Blur
 
@@ -179,11 +186,11 @@ A panel that should sit below waybar rather than over it wants
 exclusive zone without the component knowing the bar's height. Measured with
 `hyprctl layers`: waybar at `y=-540 h=42`, a `Normal` overlay on the same
 screen at `y=-498 h=1038`, starting exactly where the bar ends, so the
-backdrop never dims it. `mail-overview` does this; the other four use
-`ExclusionMode.Ignore` and cover the whole screen.
+backdrop never dims it. The `desktop` drawer does this; components that cover
+the whole screen use `ExclusionMode.Ignore`.
 
-`window-switcher` is the fifth, with namespace `quickshell-window-switcher` and
-a `blur-window-switcher` rule of its own.
+`window-switcher` has namespace `quickshell-window-switcher` and a
+`blur-window-switcher` rule of its own.
 
 ## Reloading