[maui-labs docs] Document multi-agent targeting refusal in DevFlow CLI and MCP tools (PR #353)

## Source PR

**PR**: https://github.com/dotnet/maui-labs/pull/353
**Title**: fix(devflow): refuse ambiguous multi-agent targeting (CLI + MCP) — Fixes #343
**Author**: `@jfversluis`
**Merged**: 2026-07-08

---

## Summary of Changes

Prior to this change, when multiple MAUI DevFlow agents were connected (i.e., multiple apps running simultaneously) and no agent port was specified, the CLI and MCP tools silently picked an arbitrary agent. This could cause commands to target the wrong app without any warning.

**New behavior**: When multiple agents are connected and no target is explicitly specified, all `maui devflow` subcommands and all MCP tools now **refuse** the operation with an actionable error listing the connected agents and their ports.

**Error message format (CLI)**:
````
Multiple MAUI DevFlow agents are connected and no target was specified. Re-run with --agent-port (port) to choose which app to target.
--agent-port 7000 FirstApp (iOS net10.0-ios)
--agent-port 7001 SecondApp (MacCatalyst net10.0-maccatalyst)
```

**Error message format (MCP)**:
```
Multiple MAUI DevFlow agents are connected and no target was specified. Re-run with agentPort (port) to choose which app to target.
agentPort 7000 FirstApp (iOS net10.0-ios)
agentPort 7001 SecondApp (MacCatalyst net10.0-maccatalyst)
````

**Additional fix**: DevFlow commands that fail now return exit code `1` (previously they could return `0` even on failure), making them reliable for scripting.

**Bypass**: This refusal is skipped when:
- `--agent-port` (CLI) or `agentPort` (MCP) is explicitly provided
- A `.mauidevflow` config file specifies a port
- `--agent-host` targets a remote host (the broker only describes agents on the local machine)

---

## Documentation Pages Affected

- **`docs/developer-tools/devflow/get-started.md`** (or equivalent agent connection page) — update agent connection/discovery section to document the multi-agent requirement
- **`docs/developer-tools/devflow/mcp.md`** (or equivalent MCP tools page) — update the `agentPort` parameter description to clarify it is **required** when multiple apps are running
- **`docs/developer-tools/cli/devflow.md`** (or equivalent CLI reference) — update `--agent-port` / `-ap` option description and add a "Multiple apps" section

---

## Suggested Changes

### 1. CLI reference (`docs/developer-tools/cli/devflow.md` or similar)

In the **Global options** or **Connection options** table, update the description of `--agent-port`:

**Before (approximately)**:
| `--agent-port`, `-ap` | Agent HTTP port (auto-discovered via broker, `.mauidevflow`, or default 9223) |

**After**:
| `--agent-port`, `-ap` | Agent HTTP port. Auto-discovered when only one app is running; **required** when multiple apps are connected. |

Add a new **"Multiple apps running"** section after the options table:

````markdown
### Multiple apps running simultaneously

When more than one app with the DevFlow agent is running at the same time, DevFlow cannot
determine which app to target. In this case, commands fail with a message listing all
connected agents:

```
Multiple MAUI DevFlow agents are connected and no target was specified. Re-run with --agent-port (port) to choose which app to target.
--agent-port 7000 MyApp.iOS (iOS net10.0-ios)
--agent-port 7001 MyApp.Mac (MacCatalyst net10.0-maccatalyst)
````

Resolve this by passing `--agent-port` with the port of the app you want to target:

```shell
maui devflow screenshot --agent-port 7000
```

Alternatively, create a `.mauidevflow` file in your project root with the target port:

````json
{ "agentPort": 7000 }
```
````

### 2. MCP tools reference (`docs/developer-tools/devflow/mcp.md` or similar)

Update the `agentPort` parameter description in the tool parameter tables and/or the overview section:

**Add a note** (e.g., in a callout/note block) near the `agentPort` parameter description:

```markdown
> [!IMPORTANT]
> The `agentPort` parameter is **required** when multiple apps are running simultaneously.
> When only one app is running the parameter is optional and the agent is discovered
> automatically. If you omit `agentPort` and multiple agents are connected, the tool
> returns an error listing the available agents and their ports.
```

Update the `agentPort` column in the parameter table for all tools from:

> Agent HTTP port (optional if only one agent connected)

to:

> Agent HTTP port. Optional when only one app is running; required when multiple apps are connected simultaneously.

### 3. Exit code note (CLI reference or scripting guide)

If there is a scripting / automation page, add a note:

```markdown
> [!NOTE]
> DevFlow commands exit with code `1` on failure. You can use this in shell scripts
> to detect errors:
>
> ```shell
> maui devflow screenshot --output screen.png || echo "Screenshot failed"
> ```
```

> Generated by [PR Documentation Check](https://github.com/dotnet/maui-labs/actions/runs/28927361563) for issue #353 · [◷](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)

Start with the merged PR #353, then review docs/developer-tools/devflow/get-started.md, docs/developer-tools/devflow/mcp.md, and docs/developer-tools/cli/devflow.md or their equivalents. Done means the CLI and MCP references explain multi-agent refusal, explicit port selection, the .mauidevflow bypass, and failure exit code 1.

Written by the indexing model from the issue text.