1 files changed, 59 insertions, 0 deletions
diff --git a/desktop/modules/status/README.md b/desktop/modules/status/README.md
new file mode 100644
index 0000000..0bb376f
--- /dev/null
+++ b/desktop/modules/status/README.md
@@ -0,0 +1,59 @@
+# status
+
+Desktop modes as state: `dnd` and `presentation`, owned by the `Status`
+singleton and stored as files under `$XDG_RUNTIME_DIR`.
+
+## The files are the interface
+
+    $XDG_RUNTIME_DIR/status.dnd
+    $XDG_RUNTIME_DIR/status.presentation
+
+Each holds `0` or `1`; a missing file means off. That directory is tmpfs, so a
+reboot resets every mode and there is no cleanup code. A shell restart does
+not: the files outlive the process and the singleton reads them back.
+
+Anything can read a mode with `cat`. `statusctl` is the convenience, not the
+mechanism, which is why it keeps working while quickshell is down.
+
+## statusctl
+
+    statusctl <mode> get          prints 0 or 1
+    statusctl <mode> set 0|1
+    statusctl <mode> toggle
+    statusctl <mode> watch        waybar JSON on every change
+
+The repo copy is the source; the user installs it to `~/bin`. `watch` watches
+the directory rather than the file, because an atomic write replaces the file
+and a watch on the old inode dies with it.
+
+Setting a mode with `statusctl` records the state without firing its effects.
+The shell sees the change through its own `FileView` watch and asserts them,
+so the effects follow either way. If the shell is down, the state is recorded
+and reasserted when it returns.
+
+## Effects
+
+`dnd` has none of its own. It is state the notification daemon reads.
+
+`presentation` sets `dnd`, asserts a Wayland idle inhibitor, and pauses
+breaktimer. Turning it off restores `dnd` to the value it had before rather
+than clearing it, so hand-set DND survives a presentation.
+
+breaktimer owns `$XDG_RUNTIME_DIR/breaktimer.state`. This module calls
+`breaktimer.sh pause|resume` and never writes that file: its daemon loop
+rewrites it on every phase change, and two writers would race.
+
+## Waybar
+
+`custom/presentation` reads `statusctl presentation watch`. It replaces
+waybar's built-in `idle_inhibitor`, which cannot be kept alongside it: that
+module owns its own inhibitor object, so both would have to be released
+before the screen could lock.
+
+## The check
+
+    ./test-statusctl.sh
+
+Points `XDG_RUNTIME_DIR` at a temporary directory, so it never touches live
+modes. Covers the file format, the atomic write, the toggle, the unknown-mode
+error and both watch states.