Optimize session switching performance

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

@@ -49,10 +49,19 @@ dotnet build -f net10.0-android
 ```
 
 **Critical: Port forwarding after deploy** — the Android emulator runs in its own network.
-Forward both the Agent and CDP ports:
+Forward the broker port and the agent port:
 ```bash
-adb reverse tcp:9223 tcp:9223                 # MauiDevFlow Agent
-# (CDP uses same port as agent - no separate forwarding needed)
+adb reverse tcp:19223 tcp:19223              # Broker (lets agent register)
+adb forward tcp:<port> tcp:<port>            # Agent (lets CLI reach agent)
+```
+
+The broker reverse is needed so the agent inside the emulator can connect to the host's
+broker daemon. The agent forward uses the port shown in `maui-devflow list` after the agent
+registers (range 10223–10899).
+
+If the broker isn't available (fallback mode), forward the port from `.mauidevflow` instead:
+```bash
+adb reverse tcp:9223 tcp:9223                # Fallback: direct agent port
 ```
 
 Then verify: `maui-devflow MAUI status` and `maui-devflow cdp status`.
@@ -118,10 +127,12 @@ adb shell am force-stop <pkg>                 # kill app
 
 ### Port forwarding (critical for MauiDevFlow)
 ```bash
-adb reverse tcp:9223 tcp:9223                 # Agent
-# (CDP uses same port as agent - no separate forwarding needed)
+adb reverse tcp:19223 tcp:19223              # Broker (agent → host)
+adb forward tcp:<port> tcp:<port>            # Agent (CLI → emulator, get port from `maui-devflow list`)
 adb reverse --list                            # verify forwarding
-adb reverse --remove-all                      # clean up
+adb forward --list                            # verify forwarding
+adb reverse --remove-all                      # clean up reverse
+adb forward --remove-all                      # clean up forward
 ```
 
 ### File operations
@@ -166,7 +177,7 @@ export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator
 ## Troubleshooting
 
 - **`adb devices` shows "unauthorized"**: Accept the USB debugging prompt on the device/emulator.
-- **Agent not connecting on emulator**: Forgot `adb reverse`. Run port forwarding commands.
+- **Agent not connecting on emulator**: Forgot `adb reverse tcp:19223 tcp:19223` for the broker. Run port forwarding, then check `maui-devflow list`.
 - **Emulator won't start**: Check available system images with `android avd targets`. May need
   to install with `android sdk install --package "system-images;..."`.
 - **Build error "No Android devices found"**: Ensure emulator is booted (`adb devices`).

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

@@ -42,12 +42,22 @@ xcrun simctl install booted /path/to/App.app
 xcrun simctl launch booted com.company.appid
 ```
 
-### Screenshots (native simctl)
+### Screenshots (iOS Simulator)
 ```bash
 xcrun simctl io booted screenshot output.png
 apple simulator screenshot <UDID> --output output.png
 ```
 
+### Screenshots (Mac Catalyst)
+
+**Use `maui-devflow MAUI screenshot`** for Mac Catalyst apps — it captures the UI in-process
+and does NOT require the app to be in the foreground. Never use `osascript` to bring the window
+to the front or `screencapture` for Mac Catalyst screenshots; they are unnecessary and unreliable.
+
+```bash
+maui-devflow MAUI screenshot --output screen.png
+```
+
 ### Delete / erase
 ```bash
 xcrun simctl erase <UDID>                     # factory reset
@@ -79,8 +89,9 @@ for r in d['devices'].values():
 dotnet build -f net10.0-ios -t:Run -p:_DeviceName=:v2:udid=$UDID
 ```
 
-The `-t:Run` target uses `--wait-for-exit:true`, keeping the process alive while the app runs.
-Run in background or a separate shell. The app process outputs console logs to stdout.
+The `-t:Run` target keeps the process alive while the app runs — it **blocks until the app exits**.
+Always run in an async/background shell, then poll `maui-devflow MAUI status` to detect when the
+app is ready. Do NOT wait for the process to finish.
 
 ### Determining the correct TFM
 Check the project file for `<TargetFrameworks>`:
@@ -150,8 +161,9 @@ Key subcommands beyond the basics:
 - **"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`).
-- **Agent not connecting after deploy**: Ensure app finished launching. Wait 3-5 seconds after
-  `dotnet build -t:Run` starts before checking `maui-devflow MAUI status`.
+- **Agent not connecting after deploy**: The app may still be launching. Poll
+  `maui-devflow MAUI status` every few seconds. If it hasn't connected after ~60-90s, read the
+  async shell output from `dotnet build -t:Run` for build/launch errors.
 - **Mac Catalyst app name vs binary name**: The `.app` bundle name may differ from the project
   name (e.g. `MauiTodo.app` vs `SampleMauiApp`). Check the `ApplicationTitle` in .csproj.
   Find the bundle: `find bin/Debug/net10.0-maccatalyst -name "*.app" -maxdepth 3`

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

@@ -0,0 +1,124 @@
+# Linux / GTK Platform Guide
+
+Platform-specific setup and usage for .NET MAUI apps running on Linux via Maui.Gtk (GTK4).
+
+## Overview
+
+Maui.Gtk apps target `net10.0` (not a platform-specific TFM like `net10.0-ios`) and use
+GTK4 via GirCore bindings. MauiDevFlow provides dedicated Linux packages that work with
+this architecture.
+
+## NuGet Packages
+
+| Package | Purpose |
+|---------|---------|
+| `Redth.MauiDevFlow.Agent.Gtk` | In-app agent (visual tree, screenshots, tapping, logging) |
+| `Redth.MauiDevFlow.Blazor.Gtk` | CDP bridge for WebKitGTK BlazorWebView |
+
+These replace `Redth.MauiDevFlow.Agent` and `Redth.MauiDevFlow.Blazor` which target
+standard MAUI platforms (iOS, Android, macCatalyst, Windows).
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Redth.MauiDevFlow.Agent.Gtk" Version="*" />
+  <!-- Blazor Hybrid apps also need: -->
+  <PackageReference Include="Redth.MauiDevFlow.Blazor.Gtk" Version="*" />
+</ItemGroup>
+```
+
+## Registration
+
+### MauiProgram.cs
+
+```csharp
+using MauiDevFlow.Agent.Gtk;
+using MauiDevFlow.Blazor.Gtk;  // Blazor Hybrid only
+
+var builder = MauiApp.CreateBuilder();
+// ... your existing setup ...
+
+#if DEBUG
+builder.AddMauiDevFlowAgent();
+builder.AddMauiBlazorDevFlowTools(); // Blazor Hybrid only
+#endif
+```
+
+### Application Startup
+
+The agent must be started after the MAUI Application is available. In your GTK app
+startup (e.g., `GtkMauiApplication.OnActivate` or equivalent):
+
+```csharp
+#if DEBUG
+app.StartDevFlowAgent();
+
+// For Blazor Hybrid, wire CDP to the agent:
+var blazorService = app.Handler?.MauiContext?.Services
+    .GetService<GtkBlazorWebViewDebugService>();
+blazorService?.WireBlazorCdpToAgent();
+#endif
+```
+
+## Building and Running
+
+Linux/GTK apps use `dotnet run` (not `dotnet build -t:Run` which is MAUI-specific):
+
+```bash
+# Build and run (in background/async shell)
+dotnet run --project <path-to-gtk-project>
+
+# Build only
+dotnet build <path-to-gtk-project>
+```
+
+Build times are typically fast (~5-10s) since there's no device deployment step.
+
+## Network Setup
+
+**No special setup needed.** Linux apps run directly on localhost — the CLI connects
+directly to `http://localhost:<port>`. No port forwarding (unlike Android) or entitlements
+(unlike Mac Catalyst) required.
+
+## Key Simulation
+
+The `LinuxAppDriver` uses `xdotool` for key simulation. 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.
+
+## Platform Differences
+
+| Feature | Standard MAUI | Linux/GTK |
+|---------|--------------|-----------|
+| NuGet packages | `Agent`, `Blazor` | `Agent.Gtk`, `Blazor.Gtk` |
+| TFM | `net10.0-<platform>` | `net10.0` |
+| Build command | `dotnet build -f $TFM -t:Run` | `dotnet run --project <path>` |
+| Agent startup | Automatic (lifecycle hook) | Manual (`app.StartDevFlowAgent()`) |
+| Network | Varies by platform | Direct localhost |
+| Screenshots | `VisualDiagnostics` | GTK `WidgetPaintable` → `Texture.SaveToPng()` |
+| Native tap | Platform gesture system | `Gtk.Widget.Activate()` |
+| Key simulation | Platform-specific | `xdotool` |
+| Blazor WebView | WKWebView / WebView2 / Chrome | WebKitGTK 6.0 |
+
+## Troubleshooting
+
+### Agent Not Starting
+
+1. Ensure `app.StartDevFlowAgent()` is called after the app is activated
+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
+
+- On Wayland, `xdotool` may not work. Try `ydotool` instead
+- Ensure the app window has focus for key events
+
+### WebKitGTK CDP Issues
+
+- WebKitGTK uses `EvaluateJavascriptAsync` for JS evaluation
+- The same two-eval CDP pattern (send + poll) applies as other platforms
+- Check that `chobitsu.js` is properly loaded in the WebView