docs(notifications): document the renderers and record the traps

The daemon is a separate process and the files are the interface; suppression
lives in the balloon shell so the drawer can list what DND held back; and the
drawer flag is what stops a notification appearing as both a balloon and a
row.

1 files changed, 15 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 963bda2..ccd2fa3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -229,6 +229,21 @@ changing that component. The ones that generalise:
   throwaway `hypridle -c` with a short timeout whose `on-timeout` writes a
   marker, confirm the marker does not appear while presentation is on, and
   that it appears within a few seconds of turning presentation off.
+- **The notification daemon is a separate process that owns the D-Bus name.**
+  The quickshell side only reads its published files under
+  `$XDG_RUNTIME_DIR/notifyd/`; the files are the interface, and `notifyctl` is
+  the one path back. `notifications/` is inert without it: balloons still
+  draw, but close and actions do nothing.
+- **Suppression is in the balloon shell, not the daemon.** `status.dnd`
+  withholds low and normal balloons and `notifyd/snooze` withholds all, but
+  the drawer's reserved space lists everything, because a list the user opened
+  is not an interruption.
+- **A notification appears as a balloon or in the drawer's reserved space,
+  never both.** The drawer writes `notifyd/drawer` and the balloon shell reads
+  it; `Drawer.qml`'s reserved `Item` is the space.
+- **The dead `waybar/modules/custom/notification.jsonc` and
+  `waybar/scripts/notifications.py` still shell out to `dunstctl`.** They are
+  not in the live waybar config; do not resurrect them.
 
 ## Theme