[maui-labs docs] Document the DevFlow Agent HTTP API — versioning, endpoints, and AgentClient usage

## Source PR

**PR**: https://github.com/dotnet/maui-labs/pull/426
**Title**: Document the DevFlow Agent API
**Author**: jfversluis
**Merged**: 2026-09-02

---

## Summary of Changes

PR #426 formally documents the DevFlow Agent HTTP/WebSocket API in the `maui-labs` repository. Key user-facing additions:

1. **API versioning**: All agent HTTP endpoints are now versioned under `/api/v1/*`; WebSocket channels under `/ws/v1/*`. The unversioned endpoints from the original `Redth/MauiDevFlow` repository are **not** compatibility aliases in the `Microsoft.Maui.DevFlow` packages.

2. **New endpoints documented in OpenAPI spec** (`docs/DevFlow/spec/openapi.yaml`):
- `POST /api/v1/agent/lease` — control the mutation lease
- `POST /api/v1/agent/recording` — control workflow mutation recording (start/stop/status)
- `POST /api/v1/ui/hittest` — find element at coordinates via JSON body (complements existing `GET` variant)
- `GET /api/v1/ui/diagnostics/layout/rules` — list supported layout diagnostic rules
- `POST /api/v1/ui/diagnostics/layout` — analyze current layout
- `GET /api/v1/webview/network` — list network requests captured from WebViews (convenience alias for `/api/v1/network/requests`)

3. **Agent listening address**: The agent listens on IPv4 loopback (`(localhost/redacted) Port `9223` is only the agent's last-resort default — **not** the broker port. The broker listens on port `19223`.

4. **Preferred .NET client**: For .NET callers, `AgentClient` in `Microsoft.Maui.DevFlow.Driver` is recommended over raw HTTP calls.

5. A new **"Agent API"** section was added to `src/DevFlow/README.md` explaining all of the above.

---

## Documentation Pages Affected

- **`docs/developer-tools/devflow/index.md`** (or equivalent landing page for DevFlow) — add an "Agent HTTP API" section or callout box.
- **`docs/developer-tools/devflow/api-reference.md`** — create this page (new) to describe the HTTP API, versioning, and `AgentClient`.
- **`docs/TOC.yml`** — add the new API reference page under the DevFlow node.

---

## Suggested Changes

### 1. New page: `docs/developer-tools/devflow/api-reference.md`

Create a new page with content similar to the following:

````markdown
---
title: DevFlow Agent HTTP API
description: Reference for the DevFlow Agent HTTP and WebSocket API used by the CLI, MCP tools, and AgentClient.
ms.date: 09/02/2026
---

# DevFlow Agent HTTP API

The in-app DevFlow agent exposes an HTTP/JSON API used by the CLI, MCP tools, and `Microsoft.Maui.DevFlow.Driver`.

## Connecting to the agent

The agent listens on IPv4 loopback:

```
(localhost/redacted)
```

Use the broker (port **19223**), the `maui devflow` CLI, or `AgentClient` to discover the agent's dynamic port. Port `9223` is only the agent's last-resort default when no configured or broker-assigned port is available; it is **not** the broker port.

## API versioning

| Surface | Base path |
|---------|-----------|
| HTTP REST | `/api/v1/*` |
| WebSocket | `/ws/v1/*` |

The unversioned `/api/*` and `/ws/*` endpoints from the original `Redth/MauiDevFlow` repository predate this contract and are **not** compatibility aliases in the `Microsoft.Maui.DevFlow` packages.

## Preferred .NET client

For .NET callers, use the typed `AgentClient` in `Microsoft.Maui.DevFlow.Driver` rather than constructing raw HTTP requests:

```csharp
using Microsoft.Maui.DevFlow.Driver;

var client = new AgentClient("(localhost/redacted)
var info = await client.GetAppInfoAsync();
```

Use the raw protocol documents when implementing a client in another language or integrating directly with the agent.

## Key endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/v1/agent/capabilities` | GET | List capabilities supported by the agent |
| `/api/v1/agent/lease` | POST | Control the mutation lease (acquire, release, status) |
| `/api/v1/agent/recording` | POST | Control workflow mutation recording (start, stop, status) |
| `/api/v1/ui/screenshot` | GET | Capture a screenshot |
| `/api/v1/ui/tree` | GET | Inspect the visual tree |
| `/api/v1/ui/query` | GET | Query elements by type, AutomationId, or text |
| `/api/v1/ui/hittest` | GET / POST | Find elements at screen coordinates |
| `/api/v1/ui/diagnostics/layout` | POST | Analyze the current layout |
| `/api/v1/ui/diagnostics/layout/rules` | GET | List supported layout diagnostic rules |
| `/api/v1/network/requests` | GET | List captured HTTP requests |
| `/api/v1/webview/network` | GET | List network requests from WebViews (alias) |

See the [OpenAPI specification](https://github.com/dotnet/maui-labs/blob/main/docs/DevFlow/spec/openapi.yaml) for the full endpoint reference.
````

### 2. Update `docs/TOC.yml`

Under the DevFlow section, add:

```yaml
- name: Agent HTTP API
href: developer-tools/devflow/api-reference.md
```

### 3. Update the DevFlow overview / landing page

Add a brief paragraph under the DevFlow overview:

> **Agent HTTP API**: The in-app agent exposes a versioned HTTP API (`/api/v1/*`) and WebSocket channels (`/ws/v1/*`) used by the CLI, MCP tools, and `AgentClient`. For .NET automation, use `AgentClient` in `Microsoft.Maui.DevFlow.Driver`. See [DevFlow Agent HTTP API](api-reference.md) for the full reference.

---

## Notes for the docs author

- The OpenAPI YAML source lives at `docs/DevFlow/spec/openapi.yaml` in the `dotnet/maui-labs` repo — link to it rather than duplicate it.
- Emphasize that port `9223` is the **agent** fallback port and `19223` is the **broker** port; this is a common source of confusion.
- The mutation lease and recording endpoints are new in this PR and not yet widely documented elsewhere.

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

Read the existing DevFlow overview, src/DevFlow/README.md, and docs/DevFlow/spec/openapi.yaml first. Create docs/developer-tools/devflow/api-reference.md, update docs/TOC.yml, and add the overview callout; done means the versioned endpoints, ports, AgentClient guidance, and OpenAPI link are documented and navigable.

Written by the indexing model from the issue text.