diff --git a/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx b/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx
index 41d941a41..264a1a08c 100644
--- a/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx
+++ b/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx
@@ -197,6 +197,10 @@ The extension detects each resource's language and attaches the right debugger:
 | C# / .NET | `coreclr` | [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) (recommended) or [C#](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp) |
 | Azure Functions | Per language | [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) plus the language extension for your function app (C#, JavaScript/TypeScript, or Python) |
 
+::::note[Unpackaged WinUI 3 projects]
+For an unpackaged WinUI 3 resource added with a normal `Project` launch profile (for example, `builder.AddProject<Projects.WinUIApp>("winui")`), the extension launches the project's generated apphost executable (`RunCommand`) instead of the managed DLL. Launching the managed DLL directly under the debugger crashes WinUI 3 startup in `Microsoft.UI.Xaml.Application.Start()`. No project configuration changes are required — debugger attach, launch-profile arguments, environment variables, and cleanup behavior are unaffected.
+::::
+
 ## Feedback and issues
 
 Found a bug or have an idea? File it on the [microsoft/aspire](https://github.com/microsoft/aspire/issues) repo: