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.

2 files changed, 23 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
 
diff --git a/notifications/README.md b/notifications/README.md
index e71237a..91fb758 100644
--- a/notifications/README.md
+++ b/notifications/README.md
@@ -25,3 +25,11 @@ draw but close and actions do nothing.
 Hyprland blurs a layer surface only when a rule names its namespace. This
 component sets `quickshell-notifications`; the rule is in
 `~/.config/hypr/sections/decorations.lua`.
+
+## History rows
+
+The spec calls history rows closable individually. `notifyctl` has no per-id
+history delete, only `clear-history`, so the history page ships a clear all
+and inert rows. The daemon verb and the renderer row it needs are tracked in
+the `notifyd` repo's `TODO.md`; when that ships, the row's X is wired to
+`notifyctl history-remove`.