Clarify non-disruptive operation rules

.claude/skills/maui-ai-debugging/SKILL.md

@@ -522,6 +522,17 @@ something that would require OS-level control (e.g., dismissing a system dialog
 app), **ask the user** to do it manually rather than attempting automation that would hijack
 their input.
 
+### Exceptions — CI / Unattended Environments
+
+The reference files document OS-level tools (`osascript`, `xdotool`) that conflict with
+the rules above. Those tools exist for **unattended environments only** (CI pipelines,
+remote sessions with no active user). Even there, they must only be used as a
+**last-resort troubleshooting step** when the app is non-responsive and `maui-devflow`
+commands cannot reach it — never for routine app interaction or testing.
+
+In any attended / shared-desktop session, **ask the user** to perform the action manually
+instead of using OS-level automation.
+
 ## Tips
 
 - **Use `maui-devflow batch`** for multi-step interactions — resolves port once, adds delays,
@@ -687,4 +698,4 @@ maui-devflow MAUI property <id> Text
 ```bash
 maui-devflow MAUI tap --automationId "IncrementButton"
 maui-devflow MAUI assert --automationId "CounterLabel" Text "1"
-```
+```

.claude/skills/maui-ai-debugging/references/ios-and-mac.md

@@ -206,10 +206,15 @@ Key subcommands beyond the basics:
   ```bash
   rm -rf ~/Library/Saved\ Application\ State/<bundle-id>.savedState
   ```
-  Or detect and dismiss via AppleScript:
-  ```bash
-  osascript -e 'tell application "System Events" to tell process "AppName" to click button "Reopen" of window 1'
-  ```
+  If the dialog persists after clearing saved state, **ask the user to dismiss it manually**.
+
+  > **CI / unattended only:** In environments with no active user, you may dismiss the dialog
+  > via AppleScript as a last resort:
+  > ```bash
+  > osascript -e 'tell application "System Events" to tell process "AppName" to click button "Reopen" of window 1'
+  > ```
+  > Do not use this in attended sessions — it steals focus. See
+  > [Non-Disruptive Operation](../SKILL.md#%EF%B8%8F-non-disruptive-operation).
 - **"Unable to lookup in current state: Shutdown"**: Simulator not booted. Run `xcrun simctl boot <UDID>`.
 - **Build error NETSDK1005 "Assets file doesn't have a target"**: Wrong TFM. Check
   `<TargetFrameworks>` in .csproj and use matching version (e.g. `net10.0-ios` not `net9.0-ios`).
@@ -306,15 +311,22 @@ Use these to test and validate dialog detection and dismissal workflows.
 
 ### Toggle dark mode
 ```bash
-# macOS (affects Mac Catalyst apps)
-osascript -e 'tell application "System Events" to tell appearance preferences to set dark mode to true'
-osascript -e 'tell application "System Events" to tell appearance preferences to set dark mode to false'
-
-# iOS Simulator
+# iOS Simulator (preferred — non-disruptive)
 xcrun simctl ui <UDID> appearance dark
 xcrun simctl ui <UDID> appearance light
 ```
 
+For Mac Catalyst apps, **ask the user** to toggle dark mode via System Settings.
+
+> **CI / unattended only:** In environments with no active user, you may toggle dark mode
+> via AppleScript:
+> ```bash
+> osascript -e 'tell application "System Events" to tell appearance preferences to set dark mode to true'
+> osascript -e 'tell application "System Events" to tell appearance preferences to set dark mode to false'
+> ```
+> Do not use this in attended sessions — it steals focus and requires Accessibility permissions.
+> See [Non-Disruptive Operation](../SKILL.md#%EF%B8%8F-non-disruptive-operation).
+
 ### Verify dark mode via inspection
 Use `maui-devflow` to verify colors without relying on screenshots:
 ```bash

.claude/skills/maui-ai-debugging/references/linux.md

@@ -81,14 +81,19 @@ directly to `http://localhost:<port>`. No port forwarding (unlike Android) or en
 
 ## Key Simulation
 
-The `LinuxAppDriver` uses `xdotool` for key simulation. Install it if needed:
+> **⚠️ Non-Disruptive Operation:** `xdotool` and `ydotool` simulate input at the OS level
+> and require window focus — they **will disrupt the user's session**. Do not use them
+> during normal development. If alert dismissal or keyboard input is needed, **ask the user**
+> to perform it manually. See [SKILL.md § Non-Disruptive Operation](../SKILL.md#%EF%B8%8F-non-disruptive-operation).
+
+The `LinuxAppDriver` uses `xdotool` internally for key simulation in unattended/CI
+environments. Install it if needed:
 
 ```bash
 sudo apt install xdotool
 ```
 
-For Wayland-only environments, `ydotool` may be needed instead. Key simulation is used
-by the CLI for alert dismissal and keyboard input.
+For Wayland-only environments, `ydotool` may be needed instead.
 
 ## Platform Differences
 
@@ -112,10 +117,11 @@ by the CLI for alert dismissal and keyboard input.
 2. Check that `Application.Current` is available when `StartDevFlowAgent()` runs
 3. Verify the port isn't in use: `lsof -i :<port>` or `ss -tlnp | grep <port>`
 
-### xdotool Not Working
+### xdotool Not Working (CI / Unattended Only)
 
 - On Wayland, `xdotool` may not work. Try `ydotool` instead
 - Ensure the app window has focus for key events
+- In attended environments, do not use `xdotool` — ask the user instead
 
 ### WebKitGTK CDP Issues