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

## Source PR

**PR**: https://github.com/dotnet/maui-labs/pull/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:

```markdown
| `--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:

```markdown
| 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:

```markdown
## 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:

```markdown
### 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](https://github.com/dotnet/maui-labs/actions/runs/26246024277) for issue #273 · [◷](https://github.com/search?q=repo%3Adotnet%2Fdocs-maui+is%3Aissue+%22gh-aw-workflow-call-id%3A+dotnet%2Fmaui-labs%2Fpr-docs-check%22&type=issues)