diff --git a/PROPOSAL_wait-before-screenshot.md b/PROPOSAL_wait-before-screenshot.md
new file mode 100644
index 0000000..43e5484
--- /dev/null
+++ b/PROPOSAL_wait-before-screenshot.md
@@ -0,0 +1,6 @@
+## Proposal: wait hooks for reliable auto screenshots
+
+- Problem: auto screenshots fire immediately after actions; animated dialogs are still hidden (opacity/transform), so captures can miss them even though they exist in the DOM.
+- Impact: screenshots may show the underlying page instead of the UI the user just opened.
+- Fix: allow an optional post-action delay (`waitAfterActionMs`) and a screenshot `waitForVisible` on a selector before capture. Defaults stay lightweight to avoid regressions.
+- Identified and prepared by Codex CLI (GPT-5) while debugging missing controls in captured images.