[maui-labs docs] Document Android DevFlow port forwarding improvements (PR #273)

[MauiBot]

Source PR

PR: dotnet/maui-labs#273
Title: Improve Android DevFlow port forwarding
Author: Redth
Merged: 2026-05-21

---

Summary of Changes

This PR overhauls Android ADB port forwarding in the maui devflow CLI surface:

1. New --device (serial) global option on maui devflow (recursive — applies to list, wait, diagnose, and all other devflow subcommands). Allows users to target a specific Android device/emulator when multiple are connected.

2. ANDROID_SERIAL environment variable is now respected as a fallback when --device is not passed.

3. Automatic ADB forwarding — maui devflow list, maui devflow wait, and auto-resolved agent commands now automatically check and repair ADB forwarding rules when exactly one Android device/emulator is online.

4. Corrected forwarding direction — the documentation previously stated adb reverse for both directions. The correct behavior is:

   • App → host broker: adb reverse tcp:19223 tcp:19223
   • Host CLI → in-emulator agent: adb forward tcp:{port} tcp:{port} (forward, not reverse)

5. maui devflow diagnose now shows an android forwarding section — reports which forwarding rules are present or missing, and whether they were auto-repaired.

6. Multiple-device detection — if multiple Android devices are online and --device / ANDROID_SERIAL are not set, commands report an actionable error suggesting --device (serial) candidates rather than silently failing.

---

Documentation Pages Affected

• docs/developer-tools/devflow/android.md (or equivalent Android connectivity page — may need to be created if it doesn't exist)
• docs/developer-tools/devflow/broker.md (or equivalent broker/connectivity reference)
• docs/developer-tools/cli/devflow.md (or equivalent DevFlow CLI command reference)
• docs/TOC.yml (if a new page is added)

---

Suggested Changes

1. CLI command reference — new --device option

In the maui devflow command reference table, add a row for the new global option:

| `--device (serial)` | Device/emulator/simulator identifier for platform-specific DevFlow setup. Currently used as an Android device serial for ADB forwarding. Alternatively, set the `ANDROID_SERIAL` environment variable. |

This option is recursive — it applies to all maui devflow subcommands including list, wait, diagnose, and MCP tool invocations.

2. Android connectivity — corrected forwarding direction

Replace any documentation that says adb reverse for both ports with the corrected direction table:

| Platform       | Broker (CLI → app host)               | Agent (CLI → in-emulator agent)       |
|----------------|---------------------------------------|---------------------------------------|
| Android Emu    | `adb reverse tcp:19223 tcp:19223`     | `adb forward tcp:{port} tcp:{port}`   |

Add a note explaining why the two directions differ:

For Android, the two directions are different: the app in the emulator reaches the host
broker through adb reverse tcp:19223 tcp:19223, while the host CLI reaches the
in-emulator agent through adb forward tcp:{port} tcp:{port}.

3. Android connectivity — automatic forwarding

Add a section explaining automatic forwarding:

## Automatic ADB Forwarding

When exactly one Android device or emulator is online, the `maui devflow list`,
`maui devflow wait`, and `maui devflow diagnose` commands automatically check and
repair the required ADB forwarding rules — no manual `adb reverse` / `adb forward`
commands are needed.

If multiple devices are online, specify the target device:

```bash
# Using a command-line flag
maui devflow list --device emulator-5554
maui devflow wait --device emulator-5554
maui devflow diagnose --device emulator-5554

# Or set the environment variable
export ANDROID_SERIAL=emulator-5554
maui devflow list

### 4. Troubleshooting — updated Android entries

Update the troubleshooting table for Android connection problems:

```markdown
| Symptom | Fix |
|---------|-----|
| Android agent never registers | Run `maui devflow diagnose` (or `maui devflow diagnose --device (serial)` with multiple devices). Manually: `adb reverse tcp:19223 tcp:19223` |
| Android connection refused after registration | Run `maui devflow diagnose` to repair forwarding, or manually: `adb forward tcp:(port) tcp:(port)` using the port from `maui devflow list` |
| Multiple devices online | Pass `--device (serial)` or set `ANDROID_SERIAL=(serial)` |

Update the troubleshooting text under "Firewall?":

Firewall? On Android, run maui devflow diagnose and check the android
forwarding section. If multiple devices are online, retry with --device (serial).

5. maui devflow diagnose — Android section

In the maui devflow diagnose command documentation, add that the output now includes an android forwarding section:

### Android Forwarding Section

When an Android device or emulator is detected, `maui devflow diagnose` reports:
- Whether `adb reverse tcp:19223 tcp:19223` (broker) is present
- Whether `adb forward tcp:{port} tcp:{port}` (agent) is present for each registered agent port
- Whether any missing rules were automatically repaired

Use `--device (serial)` to target a specific device when multiple are connected.

---

Notes for Docs Author

• The in-repo docs/DevFlow/broker.md was updated in this PR and can be used as a reference for the exact wording already validated by the PR author.
• The in-repo plugins/dotnet-maui/skills/maui-devflow-debug/references/connectivity.md was also updated and contains additional troubleshooting table entries.
• The key correctness fix is adb reverse vs adb forward — existing docs that say adb reverse for the agent-side connection are wrong and should be corrected.

Generated by PR Documentation Check for issue #273 · ◷