E0 · App-driving + screenshot recipe

[hellno]

Goal

Commit a documented, reusable way to drive the running app and capture per-window screenshots, so every GUI issue can produce before/after evidence.

Depends on / blocks

• Depends on: nothing (prerequisite).
• Blocks: every GUI issue's evidence (E2–E7).

Do not touch

• App code.

Acceptance criteria

• A committed docs/dev/* recipe + a helper script (not gitignored).
• Another agent can follow it to unlock the demo and capture a labelled screenshot.
• macOS path documented: just demo (funded fork) or just run; window-scoped capture via screencapture -l<CGWindowID> (id via a Swift CGWindowListCopyWindowInfo snippet) + cliclick for clicks/typing; unlock via click (synthetic Enter won't submit).
• Honest caveats documented (save agents hours): synthetic input does NOT reliably fire the ⌘↵/click confirm, the ⌘K query, or Activity j/k/x/Esc (GPUI hand-rolled on_key_down + focus quirks); registered-action shortcuts (⌘,, ⌘⇧D) DO. So: capture compose/review SCREENS via clicks; drive real broadcasts through the headless agent (just demo-agent / just demo-deposit); verify LOGIC via tests, not screenshots.
• Links docs/dev/headless-gui-screenshots.md for Linux/CI.

Files

• docs/dev/, scripts/ (or just targets).

Golden-ref fidelity

No view / see AC. (E0 is tooling, not a screen.)

Definition of Done

Follows the Implementer Contract in the epic (#179).

---

Part of the v4 epic #179. Implements #170.