diff --git a/data/runs.json b/data/runs.json
index 333d549..7ba127f 100644
--- a/data/runs.json
+++ b/data/runs.json
@@ -714,5 +714,23 @@
   "verbatim": true,
   "exit": 0,
   "output": "moved label=Volume to position 0.3 — it reads \"3.0\", was \"5.0\""
+ },
+ "app_launch[1]": {
+  "tool": "app_launch",
+  "index": 1,
+  "command": "mobium launch --gray-box dev.mobium.mobiumapp",
+  "verbatim": true,
+  "exit": 0,
+  "output": "launched dev.mobium.mobiumapp, with the gray box: every action waits for the app to say it is idle"
+ },
+ "app_tap[3]": {
+  "tool": "app_tap",
+  "index": 3,
+  "command": "mobium tap testid=busyRowB",
+  "verbatim": true,
+  "exit": 0,
+  "output": "tapped testid=busyRowB at (540, 1095)\ngray box: waited 307 ms for the app to go idle (busy: quiet)",
+  "caption": "`mobium tap testid=busyRowB` on MobiumApp's Busy Demo, Android 15 emulator, launched with `--gray-box`: the tap waited for the quiet refresh to finish, and Row B is the new generation's",
+  "after": "/img/shots/app_tap-3-after.jpg"
  }
 }
diff --git a/examples/canonical.json b/examples/canonical.json
index f6d43a3..b8aaae7 100644
--- a/examples/canonical.json
+++ b/examples/canonical.json
@@ -332,6 +332,14 @@
       "args": {
         "app": "com.android.settings"
       }
+    },
+    {
+      "title": "Launch an app with the gray box on, so every action waits for it to be idle",
+      "cli": "mobium launch --gray-box dev.mobium.mobiumapp",
+      "args": {
+        "app": "dev.mobium.mobiumapp",
+        "gray_box": true
+      }
     }
   ],
   "app_list_apps": [
@@ -709,6 +717,13 @@
         "target": "@e2",
         "double": true
       }
+    },
+    {
+      "title": "Tap right after work the screen does not show, with the gray box on",
+      "cli": "mobium tap testid=busyRowB",
+      "args": {
+        "target": "testid=busyRowB"
+      }
     }
   ],
   "app_terminate": [
diff --git a/examples/dotnet.json b/examples/dotnet.json
index da20055..2460f48 100644
--- a/examples/dotnet.json
+++ b/examples/dotnet.json
@@ -169,6 +169,9 @@
     "app_launch": [
       {
         "code": "device.Launch(\"com.android.settings\");"
+      },
+      {
+        "code": "device.LaunchWithGrayBox(\"dev.mobium.mobiumapp\");"
       }
     ],
     "app_list_apps": [
@@ -359,6 +362,9 @@
       },
       {
         "code": "device.DoubleTap(\"@e2\");"
+      },
+      {
+        "code": "device.LaunchWithGrayBox(\"dev.mobium.mobiumapp\");\ndevice.Tap(\"testid=busyQuiet\");\ndevice.Tap(\"testid=busyRowB\");   // waits for the app to say it is idle"
       }
     ],
     "app_terminate": [
diff --git a/examples/go.json b/examples/go.json
index d6cb7eb..0d83a69 100644
--- a/examples/go.json
+++ b/examples/go.json
@@ -169,6 +169,9 @@
     "app_launch": [
       {
         "code": "if err := dev.Launch(ctx, \"com.android.settings\"); err != nil {\n\treturn err\n}"
+      },
+      {
+        "code": "if err := dev.LaunchWithGrayBox(ctx, \"dev.mobium.mobiumapp\"); err != nil {\n\treturn err\n}"
       }
     ],
     "app_list_apps": [
@@ -359,6 +362,9 @@
       },
       {
         "code": "if err := dev.DoubleTap(ctx, \"@e2\"); err != nil {\n\treturn err\n}"
+      },
+      {
+        "code": "if err := dev.LaunchWithGrayBox(ctx, \"dev.mobium.mobiumapp\"); err != nil {\n\treturn err\n}\nif err := dev.Tap(ctx, \"testid=busyQuiet\"); err != nil {\n\treturn err\n}\n// Waits for the app to say it is idle.\nif err := dev.Tap(ctx, \"testid=busyRowB\"); err != nil {\n\treturn err\n}"
       }
     ],
     "app_terminate": [
diff --git a/examples/java.json b/examples/java.json
index 25531d7..1533ce8 100644
--- a/examples/java.json
+++ b/examples/java.json
@@ -169,6 +169,9 @@
     "app_launch": [
       {
         "code": "device.launch(\"com.android.settings\");   // returns once it is in front"
+      },
+      {
+        "code": "device.launchWithGrayBox(\"dev.mobium.mobiumapp\");"
       }
     ],
     "app_list_apps": [
@@ -359,6 +362,9 @@
       },
       {
         "code": "device.doubleTap(\"@e2\");"
+      },
+      {
+        "code": "device.launchWithGrayBox(\"dev.mobium.mobiumapp\");\ndevice.tap(\"testid=busyQuiet\");\ndevice.tap(\"testid=busyRowB\");   // waits for the app to say it is idle"
       }
     ],
     "app_terminate": [
diff --git a/examples/javascript.json b/examples/javascript.json
index 6d529f0..cadfac0 100644
--- a/examples/javascript.json
+++ b/examples/javascript.json
@@ -169,6 +169,9 @@
     "app_launch": [
       {
         "code": "await device.launch('com.android.settings')"
+      },
+      {
+        "code": "await device.launch('dev.mobium.mobiumapp', { grayBox: true })"
       }
     ],
     "app_list_apps": [
@@ -359,6 +362,9 @@
       },
       {
         "code": "await device.doubleTap('@e2')"
+      },
+      {
+        "code": "await device.launch('dev.mobium.mobiumapp', { grayBox: true })\nawait device.tap('testid=busyQuiet')\nawait device.tap('testid=busyRowB')   // waits for the app to say it is idle"
       }
     ],
     "app_terminate": [
diff --git a/examples/python.json b/examples/python.json
index 3166f6d..06964f2 100644
--- a/examples/python.json
+++ b/examples/python.json
@@ -169,6 +169,9 @@
     "app_launch": [
       {
         "code": "device.launch(\"com.android.settings\")"
+      },
+      {
+        "code": "device.launch(\"dev.mobium.mobiumapp\", gray_box=True)"
       }
     ],
     "app_list_apps": [
@@ -359,6 +362,9 @@
       },
       {
         "code": "device.double_tap(\"@e2\")"
+      },
+      {
+        "code": "device.launch(\"dev.mobium.mobiumapp\", gray_box=True)\ndevice.tap(\"testid=busyQuiet\")\ndevice.tap(\"testid=busyRowB\")   # waits for the app to say it is idle"
       }
     ],
     "app_terminate": [
diff --git a/scripts/capture.py b/scripts/capture.py
index c507fb0..7198028 100644
--- a/scripts/capture.py
+++ b/scripts/capture.py
@@ -60,12 +60,21 @@ def app_screen(name):
 PLAN = [
     dict(tool="app_devices", i=0),
     dict(tool="app_launch", i=0, setup=[f"terminate {SETTINGS}"], after=True),
+    # MobiumApp links Mobium's gray-box library; the launch says the app answered.
+    dict(tool="app_launch", i=1, setup=[f"terminate {APP}"]),
     dict(tool="app_map", i=0, setup=settings_root(), after=True),
     dict(tool="app_text", i=0, setup=settings_root(), after=True),
     dict(tool="app_find", i=0, setup=settings_root(), after=True),
     dict(tool="app_current", i=0),
     dict(tool="app_state", i=0),
     dict(tool="app_tap", i=0, setup=settings_root(), before=True, after=True),
+    # The gray box: a tap right after a quiet refresh waits for the app to say
+    # it is idle, and the result says how long, and for what.
+    dict(tool="app_tap", i=3, setup=[f"terminate {APP}", f"launch --gray-box {APP}",
+                                     "scroll-to 'label=Busy Demo' --direction down", "tap 'label=Busy Demo'",
+                                     "tap testid=busyQuiet"], after=True,
+         caption="`mobium tap testid=busyRowB` on MobiumApp's Busy Demo, Android 15 emulator, launched with "
+                 "`--gray-box`: the tap waited for the quiet refresh to finish, and Row B is the new generation's"),
     dict(tool="app_scroll_to", i=0, setup=settings_root(), before=True, after=True),
     # The horizontal case, on MobiumApp's Pager Demo: Card 8 starts off screen
     # to the right, as mobium-app.sh checks.
diff --git a/scripts/generate.py b/scripts/generate.py
index 336e716..870a23e 100644
--- a/scripts/generate.py
+++ b/scripts/generate.py
@@ -535,7 +535,8 @@ def doc_text(doc, lang):
 # section's.
 SYNC = {
     "quickstart": ["README.md", "cli.md", "mcp.md", "python.md", "javascript.md", "go.md", "java.md", "dotnet.md"],
-    "guides": ["README.md", "autowait.md", "cli.md", "test-runner.md", "grid.md", "network.md", "inspector.md", "mcp.md"],
+    "guides": ["README.md", "autowait.md", "graybox.md", "graybox-tutorial.md", "cli.md", "test-runner.md", "grid.md",
+               "network.md", "inspector.md", "mcp.md"],
 }
 
 
diff --git a/static/img/shots/app_tap-3-after.jpg b/static/img/shots/app_tap-3-after.jpg
new file mode 100644
index 0000000..f443f36
Binary files /dev/null and b/static/img/shots/app_tap-3-after.jpg differ