diff --git a/scripts/verify.sh b/scripts/verify.sh
index 9c01ac2..dad342f 100644
--- a/scripts/verify.sh
+++ b/scripts/verify.sh
@@ -10,6 +10,17 @@
 # Requires WINDOWS dotnet (never Linux dotnet — it re-downloads the windowsdesktop packs
 # over the slow 9p bridge; see docs/ai/environment.md -> Run). Reads the Windows path from the
 # WSL mount.
+#
+# Two switches, both for running this on a machine somebody is using:
+#   FAST=1            skip the twelve heaviest test classes (527 tests, ~50s of test time) —
+#                     most of their cost is the RealApp fixture: the WPF App, its XAML resources
+#                     and audio/WebView2 startup, created once and charged to whichever UI test
+#                     runs first. Full suite: 575 tests, ~1m50s.
+#   PHYSICAL_TESTS=1  include tests that drive the REAL cursor (SetCursorPos + mouse_event).
+#                     Excluded by default: running them hijacks the machine you are typing on.
+#                     (The old mouse-drag test is gone; its arithmetic is pure now — see
+#                     DragReorderMathTests. The switch stays for anything of that kind later.)
+# Scoped runs while working:  dotnet vstest <dll> --TestCaseFilter:"FullyQualifiedName~TheClass"
 
 set -euo pipefail