1 files changed, 35 insertions, 0 deletions
diff --git a/notifications/README.md b/notifications/README.md
new file mode 100644
index 0000000..91fb758
--- /dev/null
+++ b/notifications/README.md
@@ -0,0 +1,35 @@
+# notifications
+
+The balloon renderer for the notification daemon (`notifyd`, a separate repo).
+It reads the daemon's published files through the `Notify` singleton and draws
+one balloon per live notification, bottom-right of `DP-1`.
+
+## Suppression lives here
+
+The daemon does not know about DND or snooze. This component withholds
+balloons: `status.dnd` suppresses low and normal, `notifyd/snooze` suppresses
+everything. The drawer's reserved space lists every live notification anyway.
+
+## The files are the interface
+
+    $XDG_RUNTIME_DIR/notifyd/queue.json      the live queue
+    $XDG_RUNTIME_DIR/notifyd/history.json    the ring of 20
+    $XDG_RUNTIME_DIR/notifyd/drawer          "1" while the drawer holds the space
+    $XDG_RUNTIME_DIR/notifyd/snooze          an epoch second while snoozing
+
+`notifyctl` and `notify-snooze.sh` are in `~/bin`; without them the balloons
+draw but close and actions do nothing.
+
+## Blur
+
+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`.