doc: Add paragraph to README.md explaining how to fetch the maui project templates

[durandt]

doc: Add paragraph to README.md explaining how to fetch the maui project templates

Description of Change

README.md explains how to create a new MAUI app using dotnet new maui but the command will fail unless you have already installed the MAUI project templates. This commit adds a paragraph to README.md explaining how to fetch the maui project templates (which is not straightforward as the Microsoft.Maui.Templates point to an outdated .NET 6 version of the templates)

Issues Fixed

Runing dotnet new maui will fail unless you have installed the MAUI templates:

$ dotnet new maui -n NewApp
No templates or subcommands found matching: 'maui'.
Did you mean one of the following templates?
   dotnet new mvc
   dotnet new enum
   dotnet new page

To list installed templates similar to 'maui', run:
   dotnet new list maui
To search for the templates on NuGet.org, run:
   dotnet new search maui


For details on the exit code, refer to https://aka.ms/templating-exit-codes#103

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 34561

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 34561"

[dotnet-policy-service]

Hey there @@durandt! Thank you so much for your PR! Someone from the team will get assigned to your PR shortly and we'll get it reviewed.

[kubaflo]

/review -b feature/refactor-copilot-yml

[MauiBot]

🤖 AI Summary

👋 @durandt — new AI review results are available. Please review the latest session below.

📊 Review Session — bf394b7 · Fix: Use workload install instead of version-specific template package · 2026-05-24 14:55 UTC

🚦 Gate — Test Before & After Fix

Gate Result: ⚠️ SKIPPED

No tests were detected in this PR.

Recommendation: Add tests to verify the fix using the write-tests-agent.

---

🧪 UI Tests

No UI test categories needed for this PR (no UI-relevant changes).

---

🔍 Regression Cross-Reference

🟢 No implementation files modified — skipping regression cross-reference.

---

🔍 Pre-Flight — Context & Validation

Issue: N/A - No linked issue; PR describes dotnet new maui failing when MAUI templates/workload are not installed
PR: #34561 - doc: Add paragraph to README.md explaining how to fetch the maui project templates
Platforms Affected: Documentation only; command relates to MAUI workload installation for all platforms, testing platform requested: android
Files Changed: 0 implementation, 0 test; 1 documentation

Key Findings

• PR doc: Add paragraph to README.md explaining how to fetch the maui project templates #34561 modifies only README.md, adding a note after the Getting Started dotnet new maui example.
• The documented problem is that dotnet new maui -n NewApp can fail with “No templates or subcommands found matching: 'maui'” when the MAUI workload/templates are not installed.
• No inline review comments were present; discussion only included automation comments and /review -b feature/refactor-copilot-yml.
• No UI test categories are impacted because this is documentation-only.
• Gate result supplied by caller: ⚠️ SKIPPED — no tests detected in this PR.

Code Review Summary

Verdict: LGTM
Confidence: high
Errors: 0 | Warnings: 0 | Suggestions: 0

Key code review findings:

• No findings.

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #34561	Adds a README note advising dotnet workload install maui when the maui template is unavailable.	⚠️ SKIPPED (Gate: no tests detected)	README.md	Original PR; documentation-only

---

🔬 Code Review — Deep Analysis

Code Review — PR #34561

Independent Assessment

What this changes: Adds a README note telling users to run dotnet workload install maui if the maui template is unavailable.
Inferred motivation: Help users recover from dotnet new maui failing before MAUI workloads/templates are installed.

Reconciliation with PR Narrative

Author claims: README should explain how to fetch MAUI templates.
Agreement/disagreement: Agrees with the code change.

Findings

No findings.

Devil's Advocate

Documentation-only change; no platform/API risks. Existing install docs remain linked.

Verdict: LGTM

Confidence: high
Summary: Looks correct. CI is still not fully complete, so merge should wait for required checks.

---

🔧 Fix — Analysis & Comparison

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
1	try-fix	Move workload installation into an explicit prerequisite step and fenced command before dotnet new maui.	⚠️ BLOCKED (no executable tests; git diff --check passed)	README.md	Proactive, but verbose and may imply all users must install manually.
2	try-fix	Make “with the .NET MAUI workload installed” an inline precondition in the create-app paragraph.	⚠️ BLOCKED (no executable tests; git diff --check passed)	README.md	Concise, but makes an already long paragraph denser and hides the recovery command.
3	try-fix	Clarify the existing Install .NET MAUI bullet as setting up workload/templates used by dotnet new maui.	⚠️ BLOCKED (no executable tests; git diff --check passed)	README.md	Cleanest flow and delegates setup to authoritative docs, but less directly actionable for the exact error.
4	try-fix	Replace the note with an error-keyed Troubleshooting callout for “No templates or subcommands found matching: 'maui'”.	⚠️ BLOCKED (no executable tests; git diff --check passed)	README.md	More targeted than the PR wording, but structurally close to the PR's post-command note.
5	try-fix	Add a verify-and-recover snippet with dotnet new list maui followed by dotnet workload install maui.	⚠️ BLOCKED (no executable tests; git diff --check passed)	README.md	Most procedural, but adds diagnostic command overhead and may confuse first-time users.
PR	PR #34561	Adds a standalone note advising dotnet workload install maui if the maui template is unavailable.	⚠️ SKIPPED (Gate: no tests detected)	README.md	Original PR; simple and directly actionable.

Cross-Pollination

Model	Round	New Ideas?	Details
claude-opus-4.6	2	No	All structurally distinct placements had been tried; remaining variants were wording changes.
claude-opus-4.7	2	Yes	Suggested an exact-error troubleshooting callout; recorded as candidate #4.
gpt-5.3-codex	2	Yes	Suggested a verify-and-recover flow using dotnet new list maui; recorded as candidate #5.
gpt-5.5	2	No	Meaningful placement options were exhausted: before command, inline, existing install text, after command.

Exhausted: Yes
Selected Fix: PR's fix — The PR's standalone note is the best tradeoff for this docs-only change: it is short, directly actionable, and avoids adding extra setup flow or diagnostic commands. Candidate #4 is slightly more specific to the observed error, but it is not demonstrably better without a documentation standard preferring exact-error troubleshooting callouts.

Testing constraint: The supplied gate result was skipped because no tests were detected, and gate verification was not re-run. For each candidate, docs sanity validation used git diff --check -- README.md, which passed. No candidate can be marked full PASS because there is no executable regression/product test for this README-only PR.

---

try-fix-1 — Explicit prerequisite step

Approach

Move workload installation from an after-the-fact note into an explicit prerequisite before the dotnet new maui command. This prevents users from copying the creation command before seeing the setup requirement.

Diff

diff --git a/README.md b/README.md
index 949e35eb3f..30e8906b05 100644
--- a/README.md
+++ b/README.md
@@ -9,9 +9,13 @@
 * [.NET MAUI Samples](https://github.com/dotnet/maui-samples)
 * [Development Guide](./.github/DEVELOPMENT.md)
 
-Create a new app with `dotnet new maui -n NewApp` or a [sample app](https://github.com/dotnet/maui-samples/tree/main/10.0/Apps/DeveloperBalance#developer-balance) with `dotnet new maui -n NewApp -sc` that includes the [open-source Syncfusion Toolkit for .NET MAUI](https://www.syncfusion.com/net-maui-toolkit?utm_source=msftdotnet&utm_medium=banner&utm_campaign=mauipremium_sep25) with over 30 additional controls, the [.NET MAUI Community Toolkit](https://github.com/CommunityToolkit/Maui) with tons of helpers and views, and [MVVM Toolkit](https://github.com/CommunityToolkit/dotnet). 
+Before creating a .NET MAUI app, make sure the .NET MAUI workload is installed:
 
-**Note:** If the `maui` template is not available, first install the .NET MAUI workload with `dotnet workload install maui`.
+```bash
+dotnet workload install maui
+```
+
+Then create a new app with `dotnet new maui -n NewApp` or a [sample app](https://github.com/dotnet/maui-samples/tree/main/10.0/Apps/DeveloperBalance#developer-balance) with `dotnet new maui -n NewApp -sc` that includes the [open-source Syncfusion Toolkit for .NET MAUI](https://www.syncfusion.com/net-maui-toolkit?utm_source=msftdotnet&utm_medium=banner&utm_campaign=mauipremium_sep25) with over 30 additional controls, the [.NET MAUI Community Toolkit](https://github.com/CommunityToolkit/Maui) with tons of helpers and views, and [MVVM Toolkit](https://github.com/CommunityToolkit/dotnet). 
 
 ## Overview
 

Test Results

• Gate verification was not re-run per instruction; prior gate result was skipped because no tests were detected.
• git diff --check -- README.md: passed.
• Regression/product tests: blocked/not applicable for this docs-only README change; no executable test was detected.

Failure Analysis

Blocked from demonstrating a full pass because there is no regression test or product gate for this documentation-only change. The candidate is more proactive than the PR fix but more verbose and may overstate that every reader must run workload installation.

---

try-fix-2 — Inline workload precondition

Approach

Fold the workaround into the command paragraph by making the workload a precondition before mentioning dotnet new maui, while keeping the recovery command inline. This avoids a separate note and avoids candidate #1's explicit setup step.

Diff

diff --git a/README.md b/README.md
index 949e35eb3f..97fae0507d 100644
--- a/README.md
+++ b/README.md
@@ -9,9 +9,7 @@
 * [.NET MAUI Samples](https://github.com/dotnet/maui-samples)
 * [Development Guide](./.github/DEVELOPMENT.md)
 
-Create a new app with `dotnet new maui -n NewApp` or a [sample app](https://github.com/dotnet/maui-samples/tree/main/10.0/Apps/DeveloperBalance#developer-balance) with `dotnet new maui -n NewApp -sc` that includes the [open-source Syncfusion Toolkit for .NET MAUI](https://www.syncfusion.com/net-maui-toolkit?utm_source=msftdotnet&utm_medium=banner&utm_campaign=mauipremium_sep25) with over 30 additional controls, the [.NET MAUI Community Toolkit](https://github.com/CommunityToolkit/Maui) with tons of helpers and views, and [MVVM Toolkit](https://github.com/CommunityToolkit/dotnet). 
-
-**Note:** If the `maui` template is not available, first install the .NET MAUI workload with `dotnet workload install maui`.
+With the .NET MAUI workload installed, create a new app with `dotnet new maui -n NewApp` or a [sample app](https://github.com/dotnet/maui-samples/tree/main/10.0/Apps/DeveloperBalance#developer-balance) with `dotnet new maui -n NewApp -sc` that includes the [open-source Syncfusion Toolkit for .NET MAUI](https://www.syncfusion.com/net-maui-toolkit?utm_source=msftdotnet&utm_medium=banner&utm_campaign=mauipremium_sep25) with over 30 additional controls, the [.NET MAUI Community Toolkit](https://github.com/CommunityToolkit/Maui) with tons of helpers and views, and [MVVM Toolkit](https://github.com/CommunityToolkit/dotnet). If the `maui` template is missing, install the workload with `dotnet workload install maui`.
 
 ## Overview
 

Test Results

• Gate verification was not re-run per instruction; prior gate result was skipped because no tests were detected.
• git diff --check -- README.md: passed.
• Regression/product tests: blocked/not applicable for this docs-only README change; no executable test was detected.

Failure Analysis

Blocked from demonstrating a full pass because there is no executable regression test. Candidate #2 is concise and avoids overemphasizing installation, but the already-long README paragraph becomes denser and the recovery command is less visible than the PR's standalone note.

---

try-fix-3 — Clarify existing Install link

Approach

Avoid adding a separate recovery note. Instead, clarify the existing Install .NET MAUI bullet so the prerequisite appears before the dotnet new maui command and remains delegated to the authoritative install documentation.

Diff

diff --git a/README.md b/README.md
index 949e35eb3f..5a1a469ce8 100644
--- a/README.md
+++ b/README.md
@@ -4,15 +4,13 @@
 
 ## Getting Started ##
 
-* [Install .NET MAUI](https://dot.net/maui)
+* [Install .NET MAUI](https://dot.net/maui) — sets up the .NET MAUI workload and templates used by `dotnet new maui`.
 * [.NET MAUI Documentation](https://docs.microsoft.com/dotnet/maui)
 * [.NET MAUI Samples](https://github.com/dotnet/maui-samples)
 * [Development Guide](./.github/DEVELOPMENT.md)
 
 Create a new app with `dotnet new maui -n NewApp` or a [sample app](https://github.com/dotnet/maui-samples/tree/main/10.0/Apps/DeveloperBalance#developer-balance) with `dotnet new maui -n NewApp -sc` that includes the [open-source Syncfusion Toolkit for .NET MAUI](https://www.syncfusion.com/net-maui-toolkit?utm_source=msftdotnet&utm_medium=banner&utm_campaign=mauipremium_sep25) with over 30 additional controls, the [.NET MAUI Community Toolkit](https://github.com/CommunityToolkit/Maui) with tons of helpers and views, and [MVVM Toolkit](https://github.com/CommunityToolkit/dotnet). 
 
-**Note:** If the `maui` template is not available, first install the .NET MAUI workload with `dotnet workload install maui`.
-
 ## Overview
 
 .NET Multi-platform App UI (.NET MAUI) is the evolution of Xamarin.Forms that expand capabilities beyond mobile Android and iOS into desktop apps for Windows and macOS. With .NET MAUI, you can build apps that perform great on any device that runs Windows, macOS, Android, & iOS from a single codebase. Coupled with Visual Studio productivity tools and emulators, .NET and Visual Studio significantly speed up the development process for building apps that target the widest possible set of devices. Use a single development stack that supports the best-of-breed solutions for all modern workloads with a unified SDK, base class libraries, and a toolchain.

Test Results

• Gate verification was not re-run per instruction; prior gate result was skipped because no tests were detected.
• git diff --check -- README.md: passed.
• Regression/product tests: blocked/not applicable for this docs-only README change; no executable test was detected.

Failure Analysis

Blocked from demonstrating a full pass because there is no executable regression test. Candidate #3 keeps setup before usage and avoids hard-coding a command, but it is less directly actionable for users who encounter the exact “template missing” error and do not click the install link.

---

try-fix-4 — Error-keyed troubleshooting callout

Approach

Keep the guidance after the create command, but key it to the exact failure message users see. This makes it a troubleshooting entry instead of a general note, distinguishing it from the PR's broader “template not available” wording.

Diff

diff --git a/README.md b/README.md
index 949e35eb3f..49253ee4da 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@
 
 Create a new app with `dotnet new maui -n NewApp` or a [sample app](https://github.com/dotnet/maui-samples/tree/main/10.0/Apps/DeveloperBalance#developer-balance) with `dotnet new maui -n NewApp -sc` that includes the [open-source Syncfusion Toolkit for .NET MAUI](https://www.syncfusion.com/net-maui-toolkit?utm_source=msftdotnet&utm_medium=banner&utm_campaign=mauipremium_sep25) with over 30 additional controls, the [.NET MAUI Community Toolkit](https://github.com/CommunityToolkit/Maui) with tons of helpers and views, and [MVVM Toolkit](https://github.com/CommunityToolkit/dotnet). 
 
-**Note:** If the `maui` template is not available, first install the .NET MAUI workload with `dotnet workload install maui`.
+**Troubleshooting:** If `dotnet new maui` reports "No templates or subcommands found matching: 'maui'", install the .NET MAUI workload with `dotnet workload install maui`, then run the command again.
 
 ## Overview
 

Test Results

• Gate verification was not re-run per instruction; prior gate result was skipped because no tests were detected.
• git diff --check -- README.md: passed.
• Regression/product tests: blocked/not applicable for this docs-only README change; no executable test was detected.

Failure Analysis

Blocked from demonstrating a full pass because there is no executable regression test. Candidate #4 is more actionable for the documented failure mode than the PR note, but it remains structurally similar to the PR because it is still a post-command callout.

---

try-fix-5 — Verify-and-recover snippet

Approach

Add a small verification flow using dotnet new list maui before the recovery command. This gives users a way to confirm whether the MAUI template is installed instead of only reacting to the failure.

Diff

diff --git a/README.md b/README.md
index 949e35eb3f..6b0d711e1c 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,12 @@
 
 Create a new app with `dotnet new maui -n NewApp` or a [sample app](https://github.com/dotnet/maui-samples/tree/main/10.0/Apps/DeveloperBalance#developer-balance) with `dotnet new maui -n NewApp -sc` that includes the [open-source Syncfusion Toolkit for .NET MAUI](https://www.syncfusion.com/net-maui-toolkit?utm_source=msftdotnet&utm_medium=banner&utm_campaign=mauipremium_sep25) with over 30 additional controls, the [.NET MAUI Community Toolkit](https://github.com/CommunityToolkit/Maui) with tons of helpers and views, and [MVVM Toolkit](https://github.com/CommunityToolkit/dotnet). 
 
-**Note:** If the `maui` template is not available, first install the .NET MAUI workload with `dotnet workload install maui`.
+If the `maui` template is not listed, install the .NET MAUI workload and try again:
+
+```bash
+dotnet new list maui
+dotnet workload install maui
+```
 
 ## Overview
 

Test Results

• Gate verification was not re-run per instruction; prior gate result was skipped because no tests were detected.
• git diff --check -- README.md: passed.
• Regression/product tests: blocked/not applicable for this docs-only README change; no executable test was detected.

Failure Analysis

Blocked from demonstrating a full pass because there is no executable regression test. Candidate #5 is the most procedural, but it adds more commands and may confuse users because dotnet new list maui is diagnostic, not required for normal app creation.

---

📋 Report — Final Recommendation

Comparative Report — PR #34561

Candidates compared

Candidate	Approach	Regression result	Assessment	Rank
pr	Adds a standalone README note advising dotnet workload install maui when the maui template is unavailable.	Skipped: no tests detected	Direct, concise, and accurate for the reported missing-template failure.	1
pr-plus-reviewer	PR fix with expert reviewer feedback applied.	Skipped: no tests detected	Expert reviewer had no actionable feedback, so this is identical to pr.	1
try-fix-4	Replaces the note with exact-error troubleshooting text for "No templates or subcommands found matching: 'maui'".	Blocked: no executable tests	More specific to the observed CLI error, but not materially better than the PR unless README style prefers exact-error troubleshooting callouts.	3
try-fix-3	Clarifies the existing Install .NET MAUI bullet as setting up workload/templates used by dotnet new maui.	Blocked: no executable tests	Good information architecture because setup precedes use, but less directly actionable for users who already hit the failure.	4
try-fix-2	Folds workload availability and recovery command into the create-app paragraph.	Blocked: no executable tests	Concise, but makes an already long paragraph denser and hides the recovery action.	5
try-fix-1	Adds an explicit prerequisite step and fenced dotnet workload install maui command before app creation.	Blocked: no executable tests	Preventive, but heavier and can imply every reader must manually run workload installation.	6
try-fix-5	Adds a verify-and-recover snippet with dotnet new list maui and dotnet workload install maui.	Blocked: no executable tests	Procedural, but adds diagnostic overhead and can distract first-time users from the simple recovery command.	7

Test-result ordering

No candidate failed regression tests, and no candidate had an executable regression test available because this PR only changes README documentation. The raw PR fix had a skipped gate result; try-fix candidates were blocked from full regression validation for the same reason and only recorded documentation sanity checks.

Expert-review comparison

The expert reviewer produced no actionable inline findings against the PR diff, so pr-plus-reviewer does not improve on pr. The reviewed PR text is technically correct, localized to the missing-template scenario, and avoids adding unnecessary command flow or troubleshooting structure.

Winning candidate

Winner: pr

The raw PR fix is the best candidate because it is the shortest direct correction that addresses the documented user failure without overcomplicating the Getting Started section. pr-plus-reviewer is equivalent after review, and the try-fix alternatives either add verbosity, bury the recovery command, or optimize for a more specific wording preference without a demonstrated correctness advantage.

---