docs: spec the desktop modes tool

The first tool that changes something: dnd, presentation, nolock and
quiet through statusctl, applied with no confirmation since a mode is
one bit and undone by asking again.

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

1 files changed, 72 insertions, 0 deletions

diff --git a/docs/superpowers/specs/2026-10-19-mode-tool-design.md b/docs/superpowers/specs/2026-10-19-mode-tool-design.md
new file mode 100644
index 0000000..9c69d32
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-19-mode-tool-design.md
@@ -0,0 +1,72 @@
+# Desktop modes tool: design
+
+Date: 2026-10-19. Status: approved, not implemented.
+
+## Goal
+
+The quickshell settings window now controls most of the desktop. The
+assistant should be able to set some of it too. This first step covers
+the quick toggles only: the desktop modes in the status registry
+(`~/bin/statusctl`, quickshell repo). Appearance, daemon configs and
+lists are out of scope, each its own step later.
+
+This is the first tool that changes something (phase 2 in
+`2026-09-26-tools-and-config-design.md`). A mode is one bit and is undone
+by asking again, so it applies at once with no confirmation step; the
+canvas already shows the `tool` event. Tools that change more than a bit
+still need the review step phase 2 describes.
+
+## Tool
+
+`examples/tools/mode.toml`, installed to `~/.config/desktop-assistant/tools/`
+like the others. No change to `assistant.py`: the tool format already
+passes parameters as argv, with no shell.
+
+```toml
+description = "Desktop modes: dnd (do not disturb), presentation (calls, screen sharing), nolock (screen does not lock), quiet (no notification sounds). Read one, or turn it on or off. Changes it immediately; say what changed."
+command = ["mode.sh", "{mode}", "{on}"]
+timeout = 5
+
+[params.mode]
+type = "string"
+description = "dnd, presentation, nolock or quiet"
+
+[params.on]
+type = "string"
+description = "1 to turn on, 0 to turn off. Empty to only read it."
+```
+
+`examples/tools/mode.sh`:
+
+- `{on}` empty: read the mode. `0` or `1`: `statusctl <mode> set <on>`,
+  then read it back. Anything else: an error naming the accepted values.
+- Prints `<mode>: on` or `<mode>: off`, from the read-back, never from
+  the request, so a set that did not land reports the real state.
+- An unknown mode fails in statusctl, which names the valid ones; the
+  model sees that error.
+- `presentation` with `status.gaming` at 1: statusctl's own effective
+  state is on whatever the manual half says, so the output adds
+  `(held on by a running game)`. Setting it still writes the manual half,
+  which applies when the game exits.
+
+statusctl writes the registry files, not the shell, and the shell
+reapplies each mode's effects from its own watch, so the tool works
+whether or not quickshell is up.
+
+## Check
+
+Live, against the running model:
+
+- 10 phrasings, Italian and English: on, off, and "is DND on?". Count
+  right tool calls and arguments; after each, `statusctl <mode> get` must
+  agree with what the reply said.
+- The same set-then-ask sequence after unrelated history. Past tool
+  results are placeholders, so the model must call the tool again rather
+  than repeat an old state.
+- presentation with a game running reports the hold.
+
+## Not included
+
+Night light (hyprsunset has no switch in the registry), the break and
+snooze timers, and every settings page. Each can be a further tool file
+when wanted.