docs: the plan does not launch anything on the user's screen

The user works at this machine and runs the shell themselves. An agent
executing this plan writes code and runs non-GUI checks, then hands over the
command and the numbers to compare against; the four steps that need a running
qs are now marked as the user's.

Also warns against a bare pkill -x qs, which would take down the three
components the user already has running.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWL8JYHu7yhAdtx5pU9PMU

1 files changed, 11 insertions, 4 deletions

diff --git a/docs/superpowers/plans/2026-09-12-mail-overview.md b/docs/superpowers/plans/2026-09-12-mail-overview.md
index b1009ff..0e01d3e 100644
--- a/docs/superpowers/plans/2026-09-12-mail-overview.md
+++ b/docs/superpowers/plans/2026-09-12-mail-overview.md
@@ -23,6 +23,13 @@ bash, waybar.
 
 ## Before starting
 
+**Nothing in this plan launches an application on the user's screen.** The user
+works at this machine and runs the shell themselves; an agent executing this
+plan writes code and runs non-GUI checks (`notmuch`, `git`, `grep`), then hands
+the user the exact command to run and the values to compare against. Steps
+below that need a running `qs` are marked "user runs this". Never run a bare
+`pkill -x qs`: the user's three other components are running under it.
+
 Read `AGENTS.md` at the repo root. Four traps in it cost real time and this
 plan depends on all four:
 
@@ -333,7 +340,7 @@ ShellRoot {
 }
 ```
 
-- [ ] **Step 4: Verify it loads and stays running**
+- [ ] **Step 4: Verify it loads and stays running — USER RUNS THIS**
 
 Start it in the foreground so the harness owns the process. A detached `qs`
 does not survive a tool call and a later `pgrep` will report it dead whether
@@ -347,7 +354,7 @@ Expected: `Configuration Loaded` in the output, no QML errors, and the command
 runs for the full 10 seconds before `timeout` ends it. If it returns in under
 a second, the config exited on its own: the keepalive window is wrong.
 
-- [ ] **Step 5: Verify IPC reaches it**
+- [ ] **Step 5: Verify IPC reaches it — USER RUNS THIS**
 
 In one terminal:
 
@@ -611,7 +618,7 @@ Singleton {
 }
 ```
 
-- [ ] **Step 3: Verify the parse and the counts from the log**
+- [ ] **Step 3: Verify the parse and the counts from the log — USER RUNS THIS**
 
 Add a temporary probe to `mail-overview/shell.qml`, inside `ShellRoot`:
 
@@ -960,7 +967,7 @@ and guard the click:
 
 matching whatever identifiers the copied file actually uses.
 
-- [ ] **Step 4: Verify it opens, shows real numbers, and closes**
+- [ ] **Step 4: Verify it opens, shows real numbers, and closes — USER RUNS THIS**
 
 ```bash
 qs -p mail-overview