1 files changed, 57 insertions, 0 deletions
diff --git a/claude-rules/desktop-capture.md b/claude-rules/desktop-capture.md
new file mode 100644
index 0000000..0051c4d
--- /dev/null
+++ b/claude-rules/desktop-capture.md
@@ -0,0 +1,57 @@
+# Off-Workspace Windows and Captures
+
+Applies to: `**/*` (any task that opens a window or takes a screenshot on the user's live desktop)
+
+Never open a window or take a screenshot on the user's active workspace. When
+visual verification needs a real window on the user's live desktop, keep it off
+the workspace they're working in. An agent doing its own visual verification
+shouldn't hijack the desktop the user is actively using.
+
+The principle is environment-general: don't commandeer the user's active
+workspace for agent-side visual work. The recipe below is the Hyprland/Wayland
+implementation; other environments implement the same principle with their own
+off-screen mechanism.
+
+## Captures for your own verification
+
+Render and grab the window off the user's physical screen, then tear it down. On
+Hyprland this is a virtual headless output, verified non-disruptive on ratio
+2026-07-06 — the physical monitor stayed on its workspace, focused, throughout:
+
+```sh
+hyprctl output create headless                          # virtual output on its own workspace
+setsid <app> >/tmp/x.log 2>&1 </dev/null &
+addr=$(hyprctl -j clients | python3 -c 'import json,sys; print(next((c["address"] for c in json.load(sys.stdin) if c.get("class")=="<CLASS>"), ""))')
+hyprctl dispatch movetoworkspacesilent "<ws-on-headless>,address:$addr"   # silent = keeps the user's focus
+grim -o HEADLESS-<n> /tmp/shot.png                       # capture the virtual output only
+pkill -f '<app>$'; hyprctl output remove HEADLESS-<n>    # tear down, restore the display
+```
+
+Key constraint: `grim` captures a *visible output*, so a window merely parked on
+another Hyprland workspace can't be screenshotted — it must render on the
+headless (or another real) output. That's why a headless output, not just
+"another workspace," is the tool for self-captures. A nested compositor
+(weston/cage/sway) is the alternative on non-Hyprland Wayland or when a headless
+output isn't available; it needs the compositor installed.
+
+## Showing the user something
+
+Open it on a *separate* real workspace and tell them which one, so it never
+grabs their active workspace. They switch when ready. Craig's viewer preference
+is `imv`; launch it through the compositor (`hyprctl dispatch exec "imv
+<files>"`) so it survives the agent's shell rather than a bare `&` job that gets
+reaped.
+
+## Always clean up
+
+Close the window and remove any headless output afterward. Verify the user's
+display is restored: physical monitor back to its workspace, no orphan
+processes.
+
+## Related
+
+- `verification.md` — this is part of how visual verification is done without
+  disrupting the user.
+- `interaction.md` — the broader "don't disrupt the user's active work" concern.
+- `emacs.md` — the screenshot note for Emacs changes uses the same off-screen
+  capture approach.