[docs] Document automatic CLI bundle setup recovery

[aspire-repo-bot]

Documents changes from microsoft/aspire#19251

@karolz-ms

Targeting release/13.5 — the latest release branch on microsoft/aspire.dev — because release/13.6 (from the source PR milestone 13.6) does not exist there.

Why

Source PR 19251 fixes a bug where a fresh Aspire CLI installation could have a valid embedded bundle that hadn't been extracted yet. When an AppHost sets AspireUseCliBundle=true, this previously let the build succeed without DCP/dashboard metadata, causing direct or IDE launches to fail before the first Aspire CLI run.

The docs page describing AspireUseCliBundle (get-started/aspire-sdk.mdx) only documented the resolution priority order and the ASPIRE009 failure case — it didn't mention that the build now self-heals by running aspire setup when a bundle exists but hasn't been extracted. This is new user-facing behavior per the PR's "User-facing behavior" section: "After installing the Aspire CLI, users can build and launch an AspireUseCliBundle=true AppHost directly from an IDE without first running an Aspire CLI command."

Changes

• src/frontend/src/content/docs/get-started/aspire-sdk.mdx: Updated the "Use the Aspire CLI bundle for orchestration dependencies" section to describe the automatic aspire setup recovery step that runs at build time before the ASPIRE009 error is emitted.

Existing page updated; no new pages created.

Generated by PR Documentation Check for #19251 · auto · 37 AIC · ⌖ 7.03 AIC · ⊞ 19.6K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1496. 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

Updates the Aspire SDK “Use the Aspire CLI bundle for orchestration dependencies” documentation to reflect new build-time self-healing behavior introduced in microsoft/aspire#19251, where the build can automatically run aspire setup to extract an embedded bundle before failing with ASPIRE009.

Changes:

• Documented automatic aspire setup execution when a resolved CLI bundle exists but hasn’t been extracted yet.
• Clarified that ASPIRE009 is emitted only after the setup recovery attempt fails to resolve the bundle.

---

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

[David Pine (IEvangelist)]

Automated docs-accuracy review — Phase A (claims) + Phase B (doc-tester)

Phase A source of truth: microsoft/aspire @ release/13.5, SHA 8ab6999850d96e0023670799edbd4bdc245ad63c (matches this PR's base).
Reviewed head SHA: 22b8be39d01b978e4f50eb736112f4a6dfa28feb.

Phase A — claims: 2 non-narrative claims (+1 supported narrative) → verified, 0 verified-with-nuance, 0 unverifiable, 0 contradicted.
Phase B — doc-tester: 1 page exercised (/get-started/aspire-sdk/, section #use-the-aspire-cli-bundle-for-orchestration-dependencies) → 0 critical, 0 warnings, 0 knowledge gaps.

Verdict: APPROVE — the updated bullets accurately describe the build-time bundle setup-recovery flow in Aspire.Hosting.AppHost.in.targets on release/13.5, and the list renders correctly.

---

Phase A — Claim verification

No contradicted or unverifiable claims. The behavior is present on the targeted release/13.5 branch and the revised prose matches the MSBuild targets.

Verified claims with source evidence

Evidence paths are in microsoft/aspire @ release/13.5 (8ab6999), file src/Aspire.Hosting.AppHost/build/Aspire.Hosting.AppHost.in.targets.

• "If the resolved Aspire CLI has a bundle that hasn't been extracted yet, the build runs aspire setup through the selected aspire (or paired dnx) invocation to extract it, then resolves the bundle again." — verified. After the first ResolveAspireCliBundle (lines ~246-256), a PropertyGroup gated on '$(DcpDir)' == '' or ('$(AspireDashboardDir)' == '' and '$(AspireDashboardPath)' == '') (line ~267) selects _AspireCliSetupExecutable as the resolved aspire CLI (invocation mode Aspire, lines ~269-270) or the paired dnx host (mode Dnx, line ~271). RunAspireCliCommand then runs ... setup (lines ~310-315), followed by a second ResolveAspireCliBundle (lines ~320-333) that re-resolves. A further paired-DNX fallback + third re-resolve (lines ~340-397) covers the case where a PATH CLI didn't produce a usable bundle.
• "If the bundle still cannot be found or resolved after setup runs, the build emits error ASPIRE009 with a message directing you to get.aspire.dev…" — verified. <Error Code="ASPIRE009" Condition="'$(DcpDir)' == '' or ('$(AspireDashboardDir)' == '' and '$(AspireDashboardPath)' == '')" Text="$(_AspireCliBundleNotFoundError)" /> (lines ~433-435) is positioned after the setup and re-resolve steps, so it only fires if the bundle is still unresolved. The error text (_AspireCliBundleNotFoundError, lines ~400-431) includes "Install the Aspire CLI from https://get.aspire.dev" and appends "Automatic Aspire CLI bundle setup did not produce a usable DCP and dashboard layout." when a setup executable ran.
• (Narrative, supported) "This recovers installations that didn't run the release install scripts, so an AppHost can build and launch directly from an IDE without first running an Aspire CLI command." — substantiated by the target comment (lines ~306-308): "Script installs normally extract during installation. This fallback also covers older installers and DNX-only machines, and runs during real builds so IDE and command-line builds stamp concrete DCP and dashboard assembly metadata."

The unchanged priority-order sub-bullets (explicit AspireCliBundlePath/AspireCliPath, then aspire on PATH) were not modified by this PR and are out of scope.

---

Phase B — Doc-tester results

Report reproduced verbatim from the doc-tester skill run (blind to source; navigation via Playwright; served locally with pnpm dev).

Documentation Test Report

Focus Area: PR #1496 automatic CLI bundle setup recovery
Date: 2026-08-14
Tester: doc-tester agent
Served Base URL: http://localhost:4321/
Served Head SHA: 22b8be39d01b978e4f50eb736112f4a6dfa28feb

Routes Exercised:

• http://localhost:4321/get-started/aspire-sdk/
• http://localhost:4321/get-started/aspire-sdk/#use-the-aspire-cli-bundle-for-orchestration-dependencies

Screenshots:

• pr1496-cli-bundle-setup-recovery-list.png

Summary

Category	Passed	Failed	Warnings
Content Accuracy	4	0	0
Code Examples	0	0	0
CLI Commands	0	0	0
Links	1	0	0

Critical Issues

None.

Warnings

None.

Passed Checks

• The Aspire SDK page loaded successfully.
• The affected "Use the Aspire CLI bundle for orchestration dependencies" section resolved by anchor.
• The AspireUseCliBundle bulleted list rendered correctly.
• The nested priority-order sub-list remains intact with both expected items.
• The new aspire setup recovery bullet appears in the expected order after the priority-order bullet.
• The modified ASPIRE009 bullet appears after the setup recovery bullet.
• Inline code spans render for AspireCliBundlePath, AspireCliPath, aspire, PATH, aspire setup, dnx, and ASPIRE009.
• The get.aspire.dev link renders and points to https://get.aspire.dev.
• No broken formatting, list-nesting issue, or duplicated content was observed in the tested section.

Recommendations

1. Priority fixes: None.
2. Documentation gaps: None found in the tested section.
3. Product issues: None discovered from blind documentation testing.

Knowledge Gaps

None.

---

Automated review: Phase A verifies claims against microsoft/aspire source at the release-branch SHA; Phase B validates the rendered docs as a new user via the doc-tester skill.