diff --git a/CLAUDE.md b/CLAUDE.md
index b12e59e..d586d5c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -266,8 +266,9 @@ Before finishing code changes:
   the `disallowed_methods` deny is part of Prime Directive enforcement; a
   hit means move the call off-thread, not silence the lint.
 - Run `cargo test` unless the change is docs-only.
-- For UI changes, render at least one screenshot with
-  `cargo run --bin ferail-gpui -- --screenshot ...` and inspect it.
+- For UI changes, capture and inspect at least one screenshot. On Linux, use
+  the compositor; GPUI does not implement offscreen capture there. On macOS
+  and Windows, use `cargo run --bin ferail-gpui -- --screenshot ...`.
 - Write screenshots to `screenshots/<feature>.png`, not `/tmp`.
   `screenshots/` is gitignored scratch, any image a committed document
   references (README, docs/) must live in `docs/images/` instead, or it
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4795e21..d7d3582 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,7 +41,9 @@ adding cross-crate dependencies.
 - `python3 scripts/check-docs.py` when the change touches Markdown. The
   documentation rules it enforces are in
   [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md).
-- For UI changes, attach a screenshot. Generate one headlessly:
+- For UI changes, attach a screenshot. On Linux, capture the running window
+  through the compositor; GPUI does not implement offscreen capture there.
+  On macOS and Windows, generate one headlessly:
 
   ```sh
   cargo run --bin ferail-gpui -- \