Merge main into live

.github/workflows/docs-from-code.md

@@ -7,7 +7,13 @@ description: |
 
 on:
   issues:
-    types: [opened, labeled]
+    types: [opened]
+  workflow_dispatch:
+    inputs:
+      issue_number:
+        description: "Issue number to process"
+        required: true
+        type: string
 
 if: >-
   startsWith(github.event.issue.title, '[maui-labs docs]')
@@ -46,14 +52,15 @@ Read a `[maui-labs docs]` issue and create a draft PR with the documentation cha
 
 ## Context
 
-- **Issue Number**: `${{ github.event.issue.number }}`
-- **Issue Title**: `${{ github.event.issue.title }}`
+- **Issue Number**: `${{ github.event.issue.number || github.event.inputs.issue_number }}`
 - **Repository**: `dotnet/docs-maui`
 
 ## Step 1: Read the Issue
 
-Read the full issue body for issue #`${{ github.event.issue.number }}`. The issue
-was created by an automated workflow on `dotnet/maui-labs` and contains:
+Read the full issue body for issue #`${{ github.event.issue.number || github.event.inputs.issue_number }}`.
+If triggered via `workflow_dispatch`, use the `issue_number` input.
+
+The issue was created by an automated workflow on `dotnet/maui-labs` and contains:
 
 - **Source PR** — link to the maui-labs PR that triggered this
 - **Summary of Changes** — what user-facing changes were made

docs/TOC.yml

@@ -1358,6 +1358,8 @@
               href: developer-tools/cli/apple-management.md
             - name: Device management
               href: developer-tools/cli/device-management.md
+            - name: App profiling
+              href: developer-tools/cli/profile.md
         - name: DevFlow
           items:
             - name: Overview
@@ -1370,6 +1372,14 @@
               href: developer-tools/devflow/blazor-cdp.md
             - name: MCP server for AI agents
               href: developer-tools/devflow/mcp-server.md
+            - name: File storage access
+              href: developer-tools/devflow/storage.md
+            - name: MCP tools reference
+              href: developer-tools/devflow/mcp-tools.md
+            - name: Agent HTTP API reference
+              href: developer-tools/devflow/agent-api.md
+            - name: AgentClient API reference
+              href: developer-tools/devflow/agent-client.md
             - name: Network monitoring and profiling
               href: developer-tools/devflow/network-profiling.md
             - name: Broker architecture
@@ -1382,6 +1392,16 @@
                   href: developer-tools/devflow/setup-apple.md
                 - name: Windows
                   href: developer-tools/devflow/setup-windows.md
+        - name: Platform backends
+          items:
+            - name: Overview
+              href: developer-tools/platform-backends/index.md
+            - name: macOS AppKit
+              href: developer-tools/platform-backends/macos.md
+            - name: Linux GTK4
+              href: developer-tools/platform-backends/linux-gtk4.md
+            - name: Windows WPF
+              href: developer-tools/platform-backends/windows-wpf.md
     - name: Enterprise application patterns
       items:
         - name: Overview

docs/developer-tools/cli/apple-management.md

@@ -1,7 +1,7 @@
 ---
 title: "Apple platform management"
 description: "Learn how to use the .NET MAUI CLI to manage Xcode installations, simulator runtimes, and iOS simulators for .NET MAUI development."
-ms.date: 04/13/2026
+ms.date: 05/08/2026
 ---
 
 # Apple platform management
@@ -113,6 +113,111 @@ Permanently remove a simulator and its associated data:
 maui apple simulator delete "iPhone 17 Pro"
 ```
 
+### Create a simulator
+
+Creates a new simulator device from a device-type identifier.
+
+**macOS only.**
+
+```dotnetcli
+maui apple simulator create (device-type) [--name (name)] [--runtime (runtime)] [--if-not-exists] [--json]
+```
+
+| Argument / Option | Required | Description |
+|---|---|---|
+| `(device-type)` | ✅ | Device type identifier, e.g. `com.apple.CoreSimulator.SimDeviceType.iPhone-15` |
+| `--name` | ❌ | Custom display name for the simulator. Defaults to a name derived from `(device-type)`. |
+| `--runtime` | ❌ | Runtime identifier, e.g. `com.apple.CoreSimulator.SimRuntime.iOS-17-2`. When specified, the derived default name includes the runtime version. |
+| `--if-not-exists` | ❌ | If a simulator with the same name already exists, return its UDID instead of failing. Useful for idempotent scripting. |
+| `--json` | ❌ | Emit machine-readable JSON output. |
+
+**Examples:**
+
+```bash
+# Create an iPhone 15 simulator with a generated name
+maui apple simulator create com.apple.CoreSimulator.SimDeviceType.iPhone-15
+
+# Create with a custom name and a specific runtime
+maui apple simulator create com.apple.CoreSimulator.SimDeviceType.iPhone-15 \
+  --name "My Test iPhone" \
+  --runtime com.apple.CoreSimulator.SimRuntime.iOS-17-2
+
+# Idempotent create (returns existing UDID if name already exists)
+maui apple simulator create com.apple.CoreSimulator.SimDeviceType.iPhone-15 \
+  --name "CI iPhone" --if-not-exists --json
+```
+
+**JSON output (`--json`):**
+
+```json
+{
+  "udid": "AABBCCDD-1234-5678-ABCD-000000000001",
+  "name": "My Test iPhone",
+  "device_type": "com.apple.CoreSimulator.SimDeviceType.iPhone-15",
+  "runtime": "com.apple.CoreSimulator.SimRuntime.iOS-17-2"
+}
+```
+
+`runtime` is omitted from the JSON when not specified.
+
+**Error codes:**
+
+| Code | Meaning |
+|---|---|
+| `E2207` | Simulator creation failed |
+| `E2204` | A named simulator already exists and `--if-not-exists` was not specified |
+
+### Erase a simulator
+
+Erases (resets) a simulator device to factory state. The simulator must be shut down before erasing.
+
+**macOS only.**
+
+```dotnetcli
+maui apple simulator erase (name-or-udid) [--json]
+```
+
+| Argument / Option | Required | Description |
+|---|---|---|
+| `(name-or-udid)` | ✅ | Simulator name or UDID |
+| `--json` | ❌ | Emit machine-readable JSON output |
+
+**Examples:**
+
+```bash
+# Erase by name
+maui apple simulator erase "My Test iPhone"
+
+# Erase by UDID
+maui apple simulator erase AABBCCDD-1234-5678-ABCD-000000000001
+
+# Erase and confirm in JSON
+maui apple simulator erase "My Test iPhone" --json
+```
+
+**JSON output (`--json`):**
+
+```json
+{
+  "target": "My Test iPhone",
+  "erased": true
+}
+```
+
+> [!NOTE]
+> The simulator must be in `Shutdown` state before erasing. If it is booted, stop it first:
+>
+> ```bash
+> maui apple simulator stop (name-or-udid)
+> ```
+
+**Error codes:**
+
+| Code | Meaning |
+|---|---|
+| `E2208` | Erase failed (check simulator state) |
+| `E2204` | Simulator not found |
+
 ## Use in CI pipelines
 
 In automated environments, combine Apple commands with the `--json` and `--ci` flags for non-interactive, machine-readable output:

docs/developer-tools/cli/index.md

@@ -1,7 +1,7 @@
 ---
 title: ".NET MAUI CLI overview"
 description: "Learn about the .NET MAUI CLI, a command-line tool for environment setup, device management, and app automation."
-ms.date: 04/03/2026
+ms.date: 05/07/2026
 ---
 
 # .NET MAUI CLI overview
@@ -62,6 +62,8 @@ The following table lists the available `maui` CLI commands:
 | `maui apple simulator start` | Boot a simulator (macOS) |
 | `maui apple simulator stop` | Shut down a simulator (macOS) |
 | `maui apple simulator delete` | Delete a simulator (macOS) |
+| `maui profile startup` | Profile app startup by capturing a trace from launch |
+| `maui profile manual` | Launch the app and attach `dotnet-trace` on demand |
 | `maui devflow` | DevFlow app automation and debugging |
 | `maui devflow MAUI tree` | Dump the visual tree of a running MAUI app |
 | `maui devflow MAUI screenshot` | Take a screenshot of a running MAUI app |
@@ -75,6 +77,7 @@ For more information, see:
 - [Android SDK & emulator management](android-management.md)
 - [Apple platform management](apple-management.md)
 - [Device management](device-management.md)
+- [App profiling](profile.md)
 - [DevFlow overview](../devflow/index.md)
 
 ## Global options
@@ -116,4 +119,5 @@ maui doctor --json
 - [Android SDK & emulator management](android-management.md)
 - [Apple platform management](apple-management.md)
 - [Device management](device-management.md)
+- [App profiling](profile.md)
 - [DevFlow overview](../devflow/index.md)