Skills: retarget DevFlow skills to the unified maui CLI

plugins/dotnet-maui/skills/maui-devflow-debug/SKILL.md

@@ -8,8 +8,10 @@ description: >-
   Blazor WebView CDP debugging, reading DevFlow logs, and iterative app
   debugging. DO NOT USE FOR: first-time DevFlow package setup (use
   maui-devflow-onboard), or generic desktop automation unrelated to MAUI. INVOKES:
-  maui devflow CLI, dotnet CLI, Android adb/android tools, and Apple simctl
-  tools.
+  the unified `maui` CLI (devflow, device, android, apple, doctor command
+  groups) and dotnet CLI. Falls back to raw `adb` and `xcrun simctl` only for
+  operations not yet wrapped by the `maui` CLI (port forwarding, APK install,
+  logcat, simulator create/install/launch/appearance).
 ---
 
 # DevFlow Debug
@@ -89,6 +91,22 @@ for MAUI DevFlow product feedback. Do not run it automatically.
 
 7. Inspect, interact, capture evidence, then edit the app and repeat from launch.
 
+## Reading machine-readable output
+
+Always prefer the unified `maui` CLI surface for device prep and DevFlow
+operations. For programmatic consumption:
+
+- Pass `--json` to any command an agent will parse. Errors are emitted as a
+  structured envelope at the **top level** of stdout (no `"error"` wrapper),
+  with `snake_case` property names. See `references/troubleshooting.md`.
+- Inspect `code` to branch logic. Categories: `E1xxx` tool, `E2xxx`
+  platform/SDK, `E3xxx` user action, `E4xxx` network, `E5xxx` permission.
+- When `remediation` is present and `remediation.type` is `autofixable`
+  (lowercase), run `remediation.command` and retry. When it is `useraction`,
+  follow `remediation.manual_steps`. If `remediation` is absent, surface
+  `message` and stop retrying — there is no auto-fix.
+- Use `--ci` for non-interactive failure-fast runs (no prompts, fail on first error).
+
 ## Critical Anti-patterns
 
 - Do not treat an empty `maui devflow list` as proof the project is not integrated. `list` is runtime state; project files are source of truth.

plugins/dotnet-maui/skills/maui-devflow-debug/references/android.md

@@ -1,70 +1,63 @@
 # Android Reference
 
+Prefer the unified `maui` CLI for Android device prep and DevFlow workflows.
+Raw `adb` and `android` (`androidsdk.tool`) commands are kept only for
+operations that the `maui` CLI does not yet wrap; those are grouped under
+[Raw fallbacks not yet in `maui` CLI](#raw-fallbacks-not-yet-in-maui-cli).
+
 ## Table of Contents
 - [Emulator Management](#emulator-management)
 - [Building and Deploying](#building-and-deploying)
-- [Android CLI Tool](#android-cli-tool)
-- [ADB Reference](#adb-reference)
-- [SDK Management](#sdk-management)
+- [SDK and JDK Management](#sdk-and-jdk-management)
+- [Raw fallbacks not yet in `maui` CLI](#raw-fallbacks-not-yet-in-maui-cli)
 - [Troubleshooting](#troubleshooting)
 
 ## Emulator Management
 
 ### Avoiding multi-project conflicts
 
-When multiple projects (or AI agents) may deploy to Android emulators simultaneously,
-each project should use its own dedicated AVD. Two apps deployed to the same emulator
-will coexist (unlike iOS), but `adb reverse`/`adb forward` port forwarding is per-device
-and can cause confusion when multiple emulators are running.
+When multiple projects (or AI agents) may deploy to Android emulators
+simultaneously, each project should use its own dedicated AVD. Two apps
+deployed to the same emulator will coexist (unlike iOS), but `adb reverse` /
+`adb forward` port forwarding is per-device and can cause confusion when
+multiple emulators are running.
 
 **Before creating or starting an emulator, check what's already in use:**
 ```bash
-maui devflow list                             # shows agents with platform + port
-adb devices                                   # shows connected emulators
+maui devflow list                                 # agents with platform + port
+maui device list --platform android               # connected emulators / devices
 ```
 
 If an emulator is already running another project's agent, create a new AVD:
 ```bash
-android avd create --name "ProjectName-Pixel8" \
-  --sdk "system-images;android-35;google_apis;arm64-v8a" --device pixel_8
-android avd start --name "ProjectName-Pixel8"
+maui android emulator create "ProjectName-Pixel8" \
+  --package "system-images;android-35;google_apis;arm64-v8a" \
+  --device pixel_8
+maui android emulator start "ProjectName-Pixel8"
 ```
 
-**When multiple emulators are running**, use `-s <serial>` to target a specific one:
-```bash
-adb -s emulator-5554 reverse tcp:19223 tcp:19223   # first emulator
-adb -s emulator-5556 reverse tcp:19223 tcp:19223   # second emulator
-```
+**When multiple emulators are running**, target a specific serial with raw
+`adb -s <serial>` for port forwarding (see fallbacks below).
 
-**Naming convention:** Use `<ProjectName>-<DeviceType>` (e.g. `TodoApp-Pixel8`) so it's
-clear which AVD belongs to which project.
+**Naming convention:** Use `<ProjectName>-<DeviceType>` (e.g. `TodoApp-Pixel8`)
+so it's clear which AVD belongs to which project.
 
-### List and start AVDs
+### List, create, start, stop, delete AVDs
 ```bash
-android avd list                              # list available AVDs
-android avd start --name <avd-name>           # start emulator
+maui android emulator list                       # available AVDs
+maui android emulator create <name> --package <system-image> --device <device>
+maui android emulator start <name>               # add --cold-boot --wait if needed
+maui android emulator stop <name>
+maui android emulator delete <name>
 ```
 
-### Create AVD
-```bash
-# List available targets and device profiles
-android avd targets                           # system images
-android avd devices                           # device profiles (pixel, etc.)
-
-android avd create --name "Pixel8API35" \
-  --sdk "system-images;android-35;google_apis;arm64-v8a" \
-  --device pixel_8
-```
-
-### Delete AVD
-```bash
-android avd delete --name <avd-name>
-```
+All of the above accept `--json` for machine-readable output. The emulator
+`create` command will prompt interactively for system image / device profile
+when run without `--package` / `--device`.
 
 ### Verify emulator is running
 ```bash
-adb devices                                   # should show "emulator-5554 device"
-android device list                           # formatted list
+maui device list --platform android
 ```
 
 ## Building and Deploying
@@ -77,137 +70,150 @@ dotnet build -f net10.0-android -t:Run
 dotnet build -f net10.0-android
 ```
 
-**Critical: Port forwarding after deploy** — the Android emulator runs in its own network.
-Forward the broker port and the agent port:
+**Critical: Port forwarding after deploy** — the Android emulator runs in its
+own network. Both directions need forwarding:
+
 ```bash
-adb reverse tcp:19223 tcp:19223              # Broker (lets agent register)
-adb forward tcp:<port> tcp:<port>            # Agent (lets CLI reach agent)
+# Not yet wrapped by 'maui' CLI — use raw adb
+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).
+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:
+If the broker isn't available (fallback mode), forward the port from
+`.mauidevflow` instead:
 ```bash
-adb forward tcp:9223 tcp:9223                # Fallback: direct agent port
+# Not yet wrapped by 'maui' CLI — use raw adb
+adb forward tcp:9223 tcp:9223                    # Fallback: direct agent port
 ```
 
 Then verify: `maui devflow ui status` and `maui devflow webview status`.
 
-### Install APK manually
+## SDK and JDK Management
+
+### SDK
 ```bash
-adb install -r path/to/app.apk               # install/reinstall
-android device install --package path/to/app.apk
+maui android sdk check                           # status with --json support (also reports SDK path)
+maui android sdk list                            # installed packages
+maui android sdk list --available                # all available packages
+maui android sdk list --all                      # both installed and available
+maui android sdk install "platforms;android-35"
+maui android sdk install "system-images;android-35;google_apis;arm64-v8a"
+maui android sdk install "emulator"
+maui android sdk install "platform-tools"
+maui android sdk uninstall <package-name>
+maui android sdk accept-licenses
 ```
 
-## Android CLI Tool
-
-The `android` command (from `androidsdk.tool` NuGet) wraps SDK tools.
+`install` and `uninstall` accept package names as **positional** arguments
+(no `--package` flag); pass multiple packages by space-separating them.
 
-### SDK management
-```
-android sdk list                              # all packages
-android sdk list --installed                  # installed only
-android sdk list --available                  # available for install
-android sdk install --package "platforms;android-35"
-android sdk install --package "system-images;android-35;google_apis;arm64-v8a"
-android sdk install --package "emulator"
-android sdk uninstall --package <package-name>
-android sdk info                              # SDK location, tools versions
-android sdk accept-licenses                   # accept all SDK licenses
-android sdk download                          # download cmdline-tools
+For a guided full-stack setup, run:
+```bash
+maui android install                             # interactive: platform + scope
 ```
 
-### AVD management
-```
-android avd list                              # available AVDs
-android avd targets                           # available system images
-android avd devices                           # available device profiles
-android avd create --name <name> --sdk <system-image> --device <device>
-android avd delete --name <name>
-android avd start --name <name>
+### Typical setup for MAUI Android development
+```bash
+maui android sdk accept-licenses
+maui android sdk install "platforms;android-35"
+maui android sdk install "build-tools;35.0.0"
+maui android sdk install "system-images;android-35;google_apis;arm64-v8a"
+maui android sdk install "emulator"
+maui android sdk install "platform-tools"
 ```
 
-### Device/emulator operations
-```
-android device list                           # connected devices/emulators
-android device info [--device <serial>]       # device properties
-android device install --package <apk>        # install APK
-android device uninstall --package <pkg-id>   # uninstall by package name
+### JDK
+```bash
+maui android jdk check                           # current JDK status (path, version)
+maui android jdk install --version 17            # install OpenJDK 17 or 21
+maui android jdk list                            # available JDKs
 ```
 
-### JDK management
-```
-android jdk list                              # available JDKs
-android jdk info                              # current JDK info
+### Environment variables
+```bash
+export ANDROID_HOME=$HOME/Library/Android/sdk
+export ANDROID_SDK_ROOT=$ANDROID_HOME
+export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator
 ```
 
-## ADB Reference
+## Raw fallbacks not yet in `maui` CLI
 
-### Device/emulator basics
-```bash
-adb devices                                   # list connected devices
-adb -s <serial> shell                         # shell into specific device
-adb shell pm list packages | grep <name>      # find installed packages
-adb shell am start -n <pkg>/<activity>        # launch activity
-adb shell am force-stop <pkg>                 # kill app
-```
+These operations are not wrapped by the `maui` CLI today. Use the raw tool and
+prefer `maui` for everything else.
 
 ### Port forwarding (critical for MAUI DevFlow)
 ```bash
-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 forward --list                            # verify forwarding
-adb reverse --remove-all                      # clean up reverse
-adb forward --remove-all                      # clean up forward
+adb reverse tcp:19223 tcp:19223                  # Broker (agent → host)
+adb forward tcp:<port> tcp:<port>                # Agent (CLI → emulator)
+adb reverse --list
+adb forward --list
+adb reverse --remove-all
+adb forward --remove-all
+
+# Target a specific serial when multiple emulators are running:
+adb -s emulator-5554 reverse tcp:19223 tcp:19223
+adb -s emulator-5556 reverse tcp:19223 tcp:19223
 ```
 
-### File operations
+### Install / uninstall / launch APK
 ```bash
-adb push local/file /sdcard/path              # push file to device
-adb pull /sdcard/path local/file              # pull file from device
+adb install -r path/to/app.apk
+adb uninstall <pkg>
+adb shell am start -n <pkg>/<activity>
+adb shell am force-stop <pkg>
+adb shell pm list packages | grep <name>
 ```
 
 ### Logs
+Once a DevFlow agent is connected, prefer in-app logs:
+```bash
+maui devflow logs --limit 50
+```
+Pre-agent or for system-level traces, use `adb logcat`:
 ```bash
-adb logcat -s "DOTNET" --format brief         # .NET runtime logs
-adb logcat -s "MauiDevFlow"                   # agent logs
-adb logcat --pid=$(adb shell pidof <pkg>)     # app-specific logs
-adb logcat -c                                 # clear log buffer
+adb logcat -s "DOTNET" --format brief             # .NET runtime logs
+adb logcat -s "MauiDevFlow"                       # agent logs
+adb logcat --pid=$(adb shell pidof <pkg>)         # app-specific logs
+adb logcat -c                                     # clear log buffer
 ```
 
 ### Screenshots and screen recording
+For a running MAUI app, prefer:
 ```bash
-adb shell screencap /sdcard/screen.png && adb pull /sdcard/screen.png
-adb shell screenrecord /sdcard/video.mp4      # Ctrl+C to stop
+maui devflow ui screenshot --output screen.png
 ```
-
-## SDK Management
-
-### Typical setup for MAUI Android development
+For pre-launch / system-level capture:
 ```bash
-android sdk accept-licenses
-android sdk install --package "platforms;android-35"
-android sdk install --package "build-tools;35.0.0"
-android sdk install --package "system-images;android-35;google_apis;arm64-v8a"
-android sdk install --package "emulator"
-android sdk install --package "platform-tools"
+adb shell screencap /sdcard/screen.png && adb pull /sdcard/screen.png
+adb shell screenrecord /sdcard/video.mp4          # Ctrl+C to stop
 ```
 
-### Environment variables
+### File operations / shell
 ```bash
-export ANDROID_HOME=$HOME/Library/Android/sdk
-export ANDROID_SDK_ROOT=$ANDROID_HOME
-export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator
+adb push local/file /sdcard/path
+adb pull /sdcard/path local/file
+adb -s <serial> shell
 ```
 
 ## Troubleshooting
 
-- **`adb devices` shows "unauthorized"**: Accept the USB debugging prompt on the device/emulator.
-- **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`).
-- **Slow emulator**: Use hardware acceleration. Prefer `arm64-v8a` images on Apple Silicon Macs.
+- **`maui device list --platform android` shows "unauthorized"**: Accept the
+  USB debugging prompt on the device/emulator.
+- **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 installed system images with
+  `maui android sdk list`. Install one with
+  `maui android sdk install "system-images;android-XX;..."`.
+- **Build error "No Android devices found"**: Ensure emulator is booted
+  (`maui device list --platform android`).
+- **Slow emulator**: Use hardware acceleration. Prefer `arm64-v8a` images on
+  Apple Silicon Macs.
+- **JSON error envelope**: When a `maui` command fails with `--json`, parse
+  the top-level `code` and `remediation` fields (no `error` wrapper; see
+  `troubleshooting.md`). Common Android codes: `E2101` AndroidSdkNotFound,
+  `E2103` AndroidLicensesNotAccepted, `E2106` AndroidEmulatorNotFound,
+  `E2110` AndroidAdbNotFound, `E2111` AndroidDeviceNotFound.