docs: add mail-overview to the inventory and its traps to the notes

Four of the notes generalise beyond this component. Two were measured while
building it: notmuch fails two different ways and only the rejected-query case
is detectable, the misparsed-query case returning a plausible wrong number
with exit 0; and notmuch deduplicates by message id, so one message with two
file paths is counted twice by a path glob and per-account counts then sum
above the total.

Two more were bugs found only by running the thing. Xapian replaces files on
commit, so a watch on a filename dies with it and the watch belongs on the
directory. And an INI section body is not everything up to the next bracket,
because values can contain brackets themselves: folders named [Gmail]/Bozze
ended a section before its label and three of five accounts quietly displayed
their raw key instead.

The Blur section gains the exclusion-zone note with its measured geometry,
since mail-overview is the first panel here that sits below waybar rather than
over it. The "Both" phrasing that assumed two components is now plural.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWL8JYHu7yhAdtx5pU9PMU

1 files changed, 32 insertions, 3 deletions

diff --git a/AGENTS.md b/AGENTS.md
index cbd9139..4ef879f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,20 +11,21 @@ them runs alone, and running one does not require the others.
     volume-osd/     volume for output and input, plus what is playing
     vm-manager/     libvirt drawer: state, live stats, snapshots
     appearance/     wallpaper picker and colour scheme switcher
+    mail-overview/  notmuch unread counts per account, waybar icon and drawer
 
-Both are started from `~/.config/hypr/sections/autostart.lua` and keep running
+They are started from `~/.config/hypr/sections/autostart.lua` and keep running
 for the whole session.
 
 ## The rule that bites first
 
-**A quickshell config with no visible window exits.** Both components here are
+**A quickshell config with no visible window exits.** These components are
 hidden most of the time, so each holds itself open with a 1x1 transparent
 `PanelWindow` with `mask: Region {}`, which is click-through and draws nothing.
 
 Without it the shell loads, logs `Configuration Loaded`, reports no error, and
 quits. The symptom is never an error message: it is a keybind that appears to
 do nothing, or a panel that never paints. This was removed once during
-development because a process check was measuring the wrong thing, and both
+development because a process check was measuring the wrong thing, and two
 components broke in exactly that way. Any new component needs the same window.
 
 ## Verifying, and how not to
@@ -76,6 +77,26 @@ changing that component. The ones that generalise:
 - **Assigning `running = true` to a `Process` that is already running does
   nothing.** Reusing one `Process` for a sequence of commands needs
   `running = false` immediately before each start.
+- **`notmuch` fails two different ways and only one is detectable.** A
+  rejected query prints nothing and exits 1; a query Xapian merely misparses
+  returns a plausible wrong number and exits 0 (`tag:unread and ((` gave 41).
+  Validate the output as an integer, which catches the first, where empty
+  output would otherwise render as an empty inbox. Nothing catches the second,
+  so keep such queries as fixed strings.
+- **notmuch deduplicates by message id, so one message can have several
+  paths.** A message that arrived at two configured addresses is counted by
+  both accounts under a `path:` glob, and per-account counts then sum above the
+  total. The `account-*` tag is a property of the message, so it is singular.
+- **Xapian replaces files on commit.** A watch held on a filename inside the
+  database directory dies with the file; watch the directory for
+  `close_write,moved_to` instead, and debounce, because one commit touches
+  several files.
+- **An INI section body is not "everything up to the next `[`".** Values can
+  themselves contain brackets: `qtmaildir.conf` has folders named
+  `[Gmail]/Bozze`, which ended a section before its `label` and made three of
+  five accounts silently display their raw key. Walk lines instead. A first fix
+  using a lazy quantifier and a lookahead dropped every label, which is the
+  argument for the boring version.
 - **libvirt's own memory and disk figures are not what they look like.**
   `balloon.current` is memory allocated to the VM and reads full forever;
   `block.allocation` is qcow2 growth on the host, not usage inside the guest.
@@ -108,6 +129,14 @@ frosting needs its own `hl.layer_rule` and a distinct
 `WlrLayershell.namespace`. Without the rule it still works, rendering flat
 translucent.
 
+A panel that should sit below waybar rather than over it wants
+`exclusionMode: ExclusionMode.Normal` on its window, which respects waybar's
+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 three use
+`ExclusionMode.Ignore` and cover the whole screen.
+
 ## Reloading
 
 | | How |