[docs] Document ASPIRE009/010/011 and restored CLI bundle default

[aspire-repo-bot]

Documents changes from microsoft/aspire#18850 and the resulting release/13.5 CLI invocation behavior.

@DamianEdwards

Targeting release/13.5 based on the source PR milestone 13.5 (exact match on microsoft/aspire.dev).

Why

microsoft/aspire#18850 restores AspireUseCliBundle to false by default so direct dotnet run and IDE launches remain valid without the Aspire CLI. It adds DNX delegation and diagnostics ASPIRE010 (warning when the bundle is disabled) and ASPIRE011 (run-preflight error when a forced DNX mode cannot find dnx). It also changes the resolution and fallback semantics behind existing ASPIRE009.

The corrected documentation separates executable invocation from bundle-layout resolution and reflects all live release/13.5 invocation modes:

• An explicit AspireCliPath is authoritative.
• Default Path mode prefers a compatible aspire on PATH, then falls back through DNX to aspire.cli@$(AspireHostingSDKVersion).
• Dnx invokes unversioned aspire.cli, honoring an in-scope tool manifest or selecting the latest package when no manifest applies.
• DnxPinned invokes aspire.cli@$(AspireHostingSDKVersion).
• AspireCliBundlePath is an explicit bundle-layout input, not an executable invocation candidate.
• Invalid explicit CLI or bundle paths can produce ASPIRE009; a missing dnx command in Dnx or DnxPinned mode is reported as ASPIRE011 during run preflight.

What changed

• Added dedicated pages for ASPIRE009, ASPIRE010, and ASPIRE011, including accurate examples, timing, package selection, fallback behavior, and remedies.
• Added all three diagnostics to the diagnostics overview with their correct severities and canonical messages.
• Registered the pages in the warning/error sidebar groups so Astro topic resolution succeeds.
• Updated the Aspire SDK page to distinguish Path, Dnx, and DnxPinned, including their exact pinned or unversioned DNX package references.

Validation

• pnpm --dir .\src\frontend run lint
• pnpm --dir .\src\frontend exec vitest run --config vitest.config.ts tests/unit/topic-resolver.vitest.test.ts tests/unit/seo-lengths.vitest.test.ts (15 tests)
• Exact-head frontend build, unit, desktop/tablet/mobile E2E, report merge, and forbidden-word checks run in PR CI

Generated by PR Documentation Check · auto · 109.4 AIC · ⌖ 14.7 AIC · ⊞ 19.6K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1512. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

[Copilot]

Pull request overview

This PR updates Aspire documentation to reflect release/13.5 CLI bundle invocation and diagnostic behavior, adding dedicated pages for new/updated diagnostics and clarifying the SDK’s CLI resolution and DNX delegation modes.

Changes:

• Expanded Aspire SDK docs to clearly separate CLI invocation (AspireCliPath / AspireCliInvocationMode) from bundle-layout resolution (AspireCliBundlePath), and documented Path/Dnx/DnxPinned behavior.
• Added dedicated diagnostic pages for ASPIRE009, ASPIRE010, and ASPIRE011, including examples and remediation steps.
• Registered the new diagnostic pages in the diagnostics overview and sidebar navigation.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/frontend/src/content/docs/get-started/aspire-sdk.mdx	Clarifies CLI bundle opt-in, invocation selection, DNX delegation, and related diagnostics.
src/frontend/src/content/docs/diagnostics/overview.mdx	Adds ASPIRE009/010/011 rows to the diagnostics index table.
src/frontend/src/content/docs/diagnostics/aspire009.mdx	New page documenting bundle layout resolution failures and remedies.
src/frontend/src/content/docs/diagnostics/aspire010.mdx	New page documenting the opt-out warning and how to enable/suppress it.
src/frontend/src/content/docs/diagnostics/aspire011.mdx	New page documenting missing dnx behavior during run preflight in forced DNX modes.
src/frontend/config/sidebar/reference.topics.ts	Adds the new diagnostics pages to the appropriate warning/error sidebar groups.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/frontend/src/content/docs/diagnostics/aspire011.mdx:52

• The fenced code block for remedy #3 isn’t indented under the ordered list item, which breaks list formatting in CommonMark/Starlight. Indent the fence and its contents so it renders as part of item 3.

3. Set `AspireCliPath` to an explicit Aspire CLI executable:

```xml title="MyApp.AppHost.csproj"
<PropertyGroup>
  <AspireUseCliBundle>true</AspireUseCliBundle>
  <AspireCliPath>/usr/local/bin/aspire</AspireCliPath>
</PropertyGroup>

**src/frontend/src/content/docs/diagnostics/aspire011.mdx:43**
* The fenced code block for remedy #2 isn’t indented under the ordered list item, so it will render as a separate block outside the list in CommonMark/Starlight. Indent the fence and its contents so it stays associated with item 2.

This issue also appears on line 45 of the same file.

2. Set AspireCliInvocationMode to Path to use a global aspire command:

<PropertyGroup>
  <AspireUseCliBundle>true</AspireUseCliBundle>
  <AspireCliInvocationMode>Path</AspireCliInvocationMode>
</PropertyGroup>

</details>

[David Pine (IEvangelist)]

Docs-accuracy review (automated) — verdict: COMMENT

Strong, accurate PR. Every non-narrative claim checks out against the source of truth, and the rendered pages pass a blind new-user walkthrough. Only two minor wording nuances and a couple of newcomer knowledge-gap notes — nothing blocking.

Summary

• Phase A source of truth: microsoft/aspire @ release/13.5, SHA e076d8e427cb3afb528dbd605acd74c3aea69f94.
• Claims extracted: 19 non-narrative → 17 verified, 2 verified-with-nuance, 0 unverifiable, 0 contradicted.
• Phase B doc-tester: 5 routes exercised on a local build of this PR head — 0 critical, 0 warnings, 0 console errors; 2 non-blocking knowledge-gap notes.

---

Phase A — Claim verification (vs microsoft/aspire release/13.5 @ e076d8e4)

No contradicted or unverifiable claims, so there are no blocking inline comments. Key confirmations:

• Diagnostic messages + severities (ASPIRE009 Error, ASPIRE010 Warning, ASPIRE011 Error) match docs/list-of-diagnostics.md and src/Aspire.Hosting.AppHost/build/Aspire.Hosting.AppHost.in.targets exactly, including the full ASPIRE010 text and aka.ms/aspire/diagnostics/aspire010 link.
• AspireUseCliBundle defaults to false — confirmed in Sdk.in.targets:25 and Aspire.Hosting.AppHost.props:7; so ASPIRE010 firing when the property is unset (not just explicitly false) is correct.
• Invocation modes (Path default, Dnx unversioned aspire.cli, DnxPinned/Path-fallback pinned to aspire.cli@$(AspireHostingSDKVersion)) match the targets logic and the ResolveAspireCliInvocation flow.
• ASPIRE011 is a run-preflight error, not a build error — confirmed: _ValidateAspireCliDnxInvocationMode runs via _AspireComputeRunArguments BeforeTargets="ComputeRunArguments", and is skipped when AspireCliPath is set.
• ASPIRE009 semantics (opt-in + unresolvable bundle layout; missing aspire alone is insufficient because DNX setup can prepare the layout; invalid explicit paths still error) match the auto-setup + gating conditions.

Full claim catalog (19) — verified & verified-with-nuance with evidence

id	claim	verdict	evidence
C1	ASPIRE009 exists, Error, "…is configured to use the Aspire CLI bundle, but the bundle could not be resolved."	verified-with-nuance	list-of-diagnostics.md:14; AppHost.in.targets:433-435. The doc quotes the canonical short message; the actual build-emitted text (AppHost.in.targets:407-409) is longer (adds deprecation notice + install guidance).
C2	ASPIRE010 exists, Warning, full message incl. aka.ms/aspire/diagnostics/aspire010	verified	list-of-diagnostics.md:15; AppHost.in.targets:156-159
C3	ASPIRE011 exists, Error, DNX-not-on-PATH message	verified	list-of-diagnostics.md:16; AppHost.in.targets:620-622
C4	AspireUseCliBundle defaults to false	verified	Sdk.in.targets:25; Aspire.Hosting.AppHost.props:7
C5	ASPIRE010 fires when AspireUseCliBundle=false or unset	verified	AppHost.in.targets:156 (cond == 'false') + default false
C6	AspireCliInvocationMode default = Path	verified	AppHost.in.targets:200
C7	Dnx invokes unversioned aspire.cli; tool-manifest / latest fallback	verified	AppHost.in.targets:203-209; list-of-diagnostics.md:18
C8	DnxPinned invokes aspire.cli@$(AspireHostingSDKVersion)	verified	AppHost.in.targets:209-210
C9	Path fallback uses aspire.cli@$(AspireHostingSDKVersion) via DNX	verified	AppHost.in.targets:210,508-548,601
C10	Command form dnx --yes aspire.cli[@ver] -- ...	verified-with-nuance	AppHost.in.targets:601,456. RunCommand is the resolved dnx host path (+ optional host-arg prefix); real args are --yes <pkg> -- run --project … --no-build. The doc's dnx … -- ... is an accurate simplification.
C11	AspireCliPath authoritative (overrides mode, skips ASPIRE011)	verified	AppHost.in.targets:590,597,619
C12	AspireCliBundlePath = bundle-layout input, not an executable candidate	verified	AppHost.in.targets:275,346 gating; absent from RunCommand (590-594)
C13	ASPIRE009 cond: opt-in true & layout unresolved (DcpDir/Dashboard empty)	verified	AppHost.in.targets:433-434
C14	Missing aspire alone doesn't cause ASPIRE009 (DNX setup prepares layout)	verified	AppHost.in.targets:275-435 auto-setup
C15	Invalid explicit AspireCliPath/AspireCliBundlePath ⇒ ASPIRE009 even with dnx	verified	gating cond skips DNX setup when explicit paths set (275,346)
C16	ASPIRE011 during run preflight, not regular build	verified	AppHost.in.targets:568-571 BeforeTargets=ComputeRunArguments; DependsOn _ValidateAspireCliDnxInvocationMode
C17	.NET SDK 10.0+ provides dnx (remedy)	verified	AppHost.in.targets:622
C18	"Version introduced: 13.5" for ASPIRE009/010/011	verified	present on release/13.5; source PR #18850 (milestone 13.5)
C19	With bundle disabled, DCP/Dashboard restored from NuGet	verified	Sdk.in.targets:76 (AddReferenceToDashboardAndDCP when != 'true')

Optional nudge (non-blocking): for C1, since the page presents the message as a quote, consider noting that the build output is more verbose than the canonical one-line message shown, so readers aren't surprised by the extra deprecation/install text.

---

Phase B — Doc-tester results (blind new-user walkthrough)

Rendered this PR head locally (Astro dev server) and browsed via Playwright. No microsoft/aspire source was consulted in this phase.

Routes exercised (5): /diagnostics/aspire009/, /diagnostics/aspire010/, /diagnostics/aspire011/, /diagnostics/overview/, /get-started/aspire-sdk/ (incl. #use-the-aspire-cli-bundle-for-orchestration-dependencies).

Critical issues: none.
Warnings: none.

Passed checks

• All 5 routes return HTTP 200 — no 404s; the 3 new pages resolve in the sidebar (topic resolution succeeds).
• "Version introduced: 13.5" badge renders on aspire009/aspire010/aspire011.
• Canonical messages render in both the per-page blockquotes and the overview table, with correct severities (ASPIRE009 Error, ASPIRE010 Warning, ASPIRE011 Error).
• All .csproj XML examples render; ASPIRE011 shows its 3 ordered remedies.
• Internal links follow site conventions (site-relative, trailing slash). Overview-table links to the three pages resolve.
• The shared cross-link target #use-the-aspire-cli-bundle-for-orchestration-dependencies exists on the SDK page; a live click navigates and scrolls to it. The SDK page's new "Delegating through DNX" section and Dnx/DnxPinned examples render.
• 0 browser console errors across all pages.

Recommendations / knowledge gaps (non-blocking)

• DNX term never defined. "DNX"/"dnx" appears throughout these pages, but a newcomer only gets the indirect hint ".NET SDK 10.0 or later … provides dnx". Consider a one-line definition or a link on first use so a reader who's never heard of DNX isn't stuck.
• "run preflight" is used as a term without a glossary link; the surrounding phrasing ("when it prepares the launch command") mostly clarifies it, so this is minor.

---

Verdict rationale: no contradicted claims and no Phase B critical issues ⇒ not REQUEST_CHANGES; the two verified-with-nuance wording items plus Phase B knowledge-gap notes ⇒ COMMENT rather than APPROVE. Automated review — Phase A read microsoft/aspire release/13.5 @ e076d8e4; Phase B was blind to source.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

[Adam Ratzman (adamint)]

No additional issues from my pass.

[David Pine (IEvangelist)]

Copilot resolve the merge conflicts in this pull request

[Copilot]

Copilot resolve the merge conflicts in this pull request

Resolved the conflict and merged release/13.5 in 360dae48.