diff --git a/README.md b/README.md
index 6d03f3ee1..283cd89dd 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,42 @@ Experimental packages and tooling for .NET MAUI. This repository hosts pre-relea
 
 > ⚠️ **These packages are experimental.** APIs may change between releases. These packages are not covered by the [.NET MAUI Support Policy](https://dotnet.microsoft.com/platform/support/policy/maui) and are provided as-is.
 
+## Fastest install path
+
+Install the unified `maui` CLI once, then let it guide the rest of your machine setup:
+
+```bash
+dotnet tool install -g Microsoft.Maui.Cli --prerelease
+maui doctor
+```
+
+For Android development, the CLI can install and configure the JDK, Android SDK, licenses, and an emulator:
+
+```bash
+maui android install
+maui device list
+```
+
+On macOS, use the Apple commands to inspect your Xcode, simulator runtimes, and devices:
+
+```bash
+maui apple xcode list
+maui apple runtime list
+maui apple simulator list
+```
+
+For DevFlow app automation, initialize the bundled agent skills in your app workspace, then add the in-app agent package as described in [DevFlow](src/DevFlow/README.md):
+
+```bash
+maui devflow init
+```
+
+## Manual setup details
+
+If you prefer to install pieces yourself, install the [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0), install the MAUI workload with `dotnet workload install maui`, and configure each platform's native tools directly (Xcode on macOS; Android Studio, Android SDK, and JDK for Android).
+
+The CLI can still manage individual pieces when you do not want the full interactive setup: `maui android jdk install`, `maui android sdk install`, `maui android emulator create`, and the `maui apple ...` commands on macOS.
+
 ## Products
 
 ### Cli
@@ -24,11 +60,7 @@ A command-line tool for .NET MAUI development environment setup, device manageme
 |---------|-------------|
 | `Microsoft.Maui.Cli` | CLI global tool (`maui`) |
 
-```bash
-# Microsoft.Maui.Cli is currently released as a pre-release, so make sure to use the --prerelease flag
-dotnet tool install -g Microsoft.Maui.Cli --prerelease
-maui doctor
-```
+Start with the [fastest install path](#fastest-install-path), then run `maui <command> --help` for command-specific options.
 
 ### Comet
 
diff --git a/src/DevFlow/README.md b/src/DevFlow/README.md
index 8f560c89b..e638bd2cd 100644
--- a/src/DevFlow/README.md
+++ b/src/DevFlow/README.md
@@ -4,29 +4,61 @@ A comprehensive testing, automation, and debugging toolkit for .NET MAUI applica
 
 > ⚠️ **Experimental** — APIs may change between releases. Not covered by the Microsoft Support Policy.
 
-## Packages
+## Fastest path
 
-| Package | Description |
-|---------|-------------|
-| **Microsoft.Maui.DevFlow.Agent** | In-app agent for .NET MAUI apps. Exposes visual tree, element interactions, screenshots, and profiling via HTTP/JSON API. |
-| **Microsoft.Maui.DevFlow.Agent.Core** | Platform-agnostic core: HTTP server, visual tree walker, CSS selector engine, network capture, profiling. |
-| **Microsoft.Maui.DevFlow.Agent.Gtk** | GTK/Linux agent for Maui.Gtk apps. |
-| **Microsoft.Maui.DevFlow.Blazor** | Blazor WebView CDP bridge. Enables Chrome DevTools Protocol access for Blazor Hybrid content via Chobitsu. |
-| **Microsoft.Maui.DevFlow.Blazor.Gtk** | Blazor CDP bridge for WebKitGTK on Linux. |
-| **Microsoft.Maui.DevFlow.CLI** | DevFlow command implementation used by the unified `maui devflow` CLI surface for automation, debugging, and MCP server support. |
-| **Microsoft.Maui.DevFlow.Driver** | Platform-aware app driver for iOS, Android, Mac Catalyst, Windows, and Linux. |
-| **Microsoft.Maui.DevFlow.Logging** | Buffered rotating JSONL file logger. No MAUI dependency. |
+Install the unified `maui` CLI and initialize the bundled DevFlow skills in your app workspace:
+
+```bash
+dotnet tool install -g Microsoft.Maui.Cli --prerelease
+maui devflow init
+```
+
+Add the in-app agent package to the MAUI app you want to automate:
+
+```bash
+dotnet add package Microsoft.Maui.DevFlow.Agent --prerelease
+
+# Blazor Hybrid apps only
+dotnet add package Microsoft.Maui.DevFlow.Blazor --prerelease
+```
+
+Register the agent in `MauiProgram.cs` for debug builds:
+
+```csharp
+using Microsoft.Maui.DevFlow.Agent;
+
+public static MauiApp CreateMauiApp()
+{
+    var builder = MauiApp.CreateBuilder();
+    builder.UseMauiApp<App>();
+
+    #if DEBUG
+    builder.AddMauiDevFlowAgent();
+    #endif
 
-## Quick Start
+    return builder.Build();
+}
+```
+
+Run your app, then connect to it:
+
+```bash
+maui devflow wait
+maui devflow ui tree
+maui devflow ui screenshot -o screenshot.png
+maui devflow mcp
+```
 
-### 1. Install the NuGet packages
+## Manual setup details
+
+### NuGet package references
 
 ```xml
 <PackageReference Include="Microsoft.Maui.DevFlow.Agent" />
 <PackageReference Include="Microsoft.Maui.DevFlow.Blazor" />  <!-- If using Blazor Hybrid -->
 ```
 
-### 2. Register in MauiProgram.cs
+### MauiProgram.cs registration
 
 ```csharp
 using Microsoft.Maui.DevFlow.Agent;
@@ -44,18 +76,17 @@ public static MauiApp CreateMauiApp()
 }
 ```
 
-### 3. Install the unified CLI tool
+### CLI installation
 
 ```bash
 dotnet tool install -g Microsoft.Maui.Cli --prerelease
 ```
 
-### 4. Interact with your running app
+### Common commands
 
 ```bash
 # Install DevFlow skills for AI agent integration (auto-detects target directory;
 # defaults to .claude/skills/ — configurable via --target: claude, github, agent, agents, or auto)
-# (configurable via --target: claude, github, agent, agents, or auto)
 maui devflow init
 
 # Visual tree
@@ -71,6 +102,19 @@ maui devflow ui tap --automationid "MyButton"
 maui devflow mcp
 ```
 
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| **Microsoft.Maui.DevFlow.Agent** | In-app agent for .NET MAUI apps. Exposes visual tree, element interactions, screenshots, and profiling via HTTP/JSON API. |
+| **Microsoft.Maui.DevFlow.Agent.Core** | Platform-agnostic core: HTTP server, visual tree walker, CSS selector engine, network capture, profiling. |
+| **Microsoft.Maui.DevFlow.Agent.Gtk** | GTK/Linux agent for Maui.Gtk apps. |
+| **Microsoft.Maui.DevFlow.Blazor** | Blazor WebView CDP bridge. Enables Chrome DevTools Protocol access for Blazor Hybrid content via Chobitsu. |
+| **Microsoft.Maui.DevFlow.Blazor.Gtk** | Blazor CDP bridge for WebKitGTK on Linux. |
+| **Microsoft.Maui.DevFlow.CLI** | DevFlow command implementation used by the unified `maui devflow` CLI surface for automation, debugging, and MCP server support. |
+| **Microsoft.Maui.DevFlow.Driver** | Platform-aware app driver for iOS, Android, Mac Catalyst, Windows, and Linux. |
+| **Microsoft.Maui.DevFlow.Logging** | Buffered rotating JSONL file logger. No MAUI dependency. |
+
 ### Session identity
 
 When `Microsoft.Maui.DevFlow.Agent` is referenced, builds are tagged with a **session identity**