docs: the notification settings page and config.json

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

3 files changed, 28 insertions, 4 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 57f4914..2b6315f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,7 +14,7 @@ modules.
     desktop/          the drawer (SUPER alone): user details, sound, mail, VMs, status,
                       performance, clipboard, updates; and the settings
                       window for pages set once: wallpaper, theme, icons,
-                      sunset, idle (the former appearance shell), autostart,
+                      sunset, idle (the former appearance shell), notifications, autostart,
                       the assistant's daemon and presets, qtmaildir, git
       island/         top-centre pills on DP-1: clock, volume, tray, layout, privacy,
                       calendar, OBS
diff --git a/desktop/modules/notifications/README.md b/desktop/modules/notifications/README.md
new file mode 100644
index 0000000..c3b2e9d
--- /dev/null
+++ b/desktop/modules/notifications/README.md
@@ -0,0 +1,18 @@
+# notifications (settings page)
+
+Edits `~/.config/notifyd/config.json`, the one file behind both the daemon
+and the balloon shell:
+
+| key | read by |
+| --- | --- |
+| `timeouts`, `liveCap`, `historyCap` | notifyd, at start and on `notifyctl reload` |
+| `balloons`, `dndPassCritical`, `muted` | both shells, through `Notify.config` |
+
+`shared/NotifyConfig.js` resolves the file over its defaults and holds the
+mute/DND decision. Check: `node shared/test_notify_config.js`.
+
+Save writes the file with `cat` (unknown keys kept) then runs `notifyctl
+reload`. If notifyd is not running the file is still written and the page
+says so; the daemon reads it when it starts.
+
+Snooze is not here: the status tile has it.
diff --git a/notifications/README.md b/notifications/README.md
index 36df6da..f80c79e 100644
--- a/notifications/README.md
+++ b/notifications/README.md
@@ -6,9 +6,14 @@ 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 daemon does not know about DND, snooze or mute. This component withholds
+balloons: `status.dnd` suppresses low and normal (and critical too when
+`dndPassCritical` is off), a muted app is always withheld, and
+`notifyd/snooze` suppresses everything. The drawer's reserved space lists
+every live notification anyway.
+
+Placement, mute and the DND rule come from `~/.config/notifyd/config.json`,
+edited from the settings window (Desktop → Notifications).
 
 ## The files are the interface
 
@@ -16,6 +21,7 @@ everything. The drawer's reserved space lists every live notification anyway.
     $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
+    ~/.config/notifyd/config.json            settings, shared with the daemon
 
 `notifyctl` and `notify-snooze.sh` are in `~/bin`; without them the balloons
 draw but close and actions do nothing.