docs: document XCUITest pasteboard prompt suppression

skills/agent-device/references/permissions.md

@@ -22,6 +22,10 @@ If daemon startup fails with stale metadata hints, clean stale files and retry:
 - `~/.agent-device/daemon.json`
 - `~/.agent-device/daemon.lock`
 
+## iOS: "Allow Paste" dialog
+
+iOS 16+ shows an "Allow Paste" prompt when an app reads the system pasteboard. Under XCUITest (which `agent-device` uses), this prompt is suppressed by the testing runtime. Use `xcrun simctl pbcopy booted` to set clipboard content directly on the simulator instead.
+
 ## Simulator troubleshooting
 
 - If snapshots return 0 nodes, restart Simulator and re-open the app.

website/docs/docs/_meta.json

@@ -43,5 +43,10 @@
     "name": "snapshots",
     "type": "file",
     "label": "Snapshots"
+  },
+  {
+    "name": "known-limitations",
+    "type": "file",
+    "label": "Known Limitations"
   }
 ]

website/docs/docs/known-limitations.md

@@ -0,0 +1,21 @@
+---
+title: Known Limitations
+---
+
+# Known Limitations
+
+Platform constraints that affect automation behavior.
+
+## iOS: "Allow Paste" dialog suppressed under XCUITest
+
+iOS 16+ shows an "Allow Paste" system prompt when an app reads `UIPasteboard.general` in the foreground. When an app is launched or activated through the XCUITest runner (which `agent-device` uses for iOS), the iOS runtime detects the testing context and silently grants pasteboard access — the prompt never appears.
+
+This is an Apple platform constraint that affects all XCUITest-based automation tools.
+
+**Workarounds:**
+
+- **Pre-fill the pasteboard via simctl** — set clipboard content without triggering the dialog:
+  ```bash
+  echo "some text" | xcrun simctl pbcopy booted
+  ```
+- **Test the dialog manually** — the "Allow Paste" UX cannot be exercised through XCUITest-based automation.