[docs] Document mixed-quality staging package discovery in aspire add

[aspire-repo-bot]

Documents changes from microsoft/aspire#19426

@mitchdenny

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 this PR is needed

The source PR fixes aspire add package discovery so that, on stable-shaped staging CLI builds, integrations that intentionally remain prerelease (like Aspire.Hosting.Azure.Kubernetes) are still discoverable from both C# and TypeScript AppHosts. Previously the TypeScript/polyglot path used an explicit stable-only staging channel and those integrations disappeared from search results. The PR body includes a "User-facing usage" section (aspire add azure-kubernetes), which triggered the pr_body_has_user_facing_section signal.

Documentation changes

• Added a note to the aspire add command reference explaining that staging/dev quality CLI builds discover both stable and prerelease integration packages, and that release quality CLI builds remain stable-only (with the -v, --version fallback still available for a specific prerelease version).
• Added an example showing aspire add azure-kubernetes in the context of a stable-shaped staging CLI.

Files modified

• src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx (updated existing page)

No new pages were created; this updates the existing aspire add reference page.

Generated by PR Documentation Check for #19426 · auto · 112.5 AIC · ⌖ 9.59 AIC · ⊞ 19.6K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

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

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Note

This error may be related to your runner configuration. You can now configure runners for Copilot code review separately from Copilot cloud agent by creating a copilot-code-review.yml file with your setup steps. Read the docs for details.

[David Pine (IEvangelist)]

Docs-accuracy review — PR #1505

Phase A source of truth: microsoft/aspire release/13.5 @ 45f7776ddb51ba976a32ece224ef8b23ed989a91
Claims extracted: 6 · verified 3 · verified-with-nuance 1 · contradicted 2 · unverifiable 0
Phase B (doc-tester, blind): 2 routes exercised (/reference/cli/commands/aspire-add/, /reference/cli/install-script/#options) — 0 critical, 0 warnings, 6 passed checks, 2 knowledge gaps.

⚠️ The source PR this documents — microsoft/aspire#19426 (milestone 13.6) — is not present on release/13.5, the branch this doc PR targets (verified: git log release/13.5 --grep=19426 is empty). Claims were therefore verified against the code that actually ships on release/13.5. On that branch the aspire add discovery path does not gate on CLI quality the way the new note describes (see inline comment).

Verdict: REQUEST_CHANGES — Phase A found 2 contradicted claims (both on the added note, line 30). Phase B is clean (rendering, links, and copy buttons all work).

---

Phase A — Claim verification

Two contradicted claims are posted as inline comments on the added note:

• C3 — behavior: "A release quality CLI continues to search stable packages only." The aspire add search always includes the implicit PackageChannelQuality.Both channel regardless of CLI quality, so prerelease packages remain discoverable on a release CLI. "stable packages only" is inaccurate on release/13.5.
• C4 — CLI surface: the version option is spelled --version only; there is no -v alias on aspire add (-v is the root CLI's print-version flag).

Verified / verified-with-nuance claims (evidence) — 4

#	Claim	Verdict	Evidence (release/13.5 @ 45f7776)
C1	`-Quality	--qualityinstall option with valuesrelease/staging/dev; anchor /reference/cli/install-script/#options`	verified
C2	On a staging/dev quality CLI, aspire add discovers both stable and prerelease packages	verified-with-nuance	PackageChannel.CreateImplicitChannel = Quality.Both (PackageChannel.cs:740-748), always in search (IntegrationPackageSearchService.cs:89-100). Nuance: discovery is not gated by CLI quality — the implicit Both channel always participates; feed provenance is the real driver.
C5	Aspire.Hosting.Azure.Kubernetes intentionally ships prerelease even in a stable-shaped build	verified	Aspire.Hosting.Azure.Kubernetes.csproj: <SuppressFinalPackageVersion>true</SuppressFinalPackageVersion> + <EnablePackageValidation>false</EnablePackageValidation>
C6	Friendly name azure-kubernetes for aspire add	verified	IntegrationPackageSearchService.GenerateFriendlyName: Id.Replace("Aspire.Hosting.","").Replace('.','-').ToLowerInvariant() → azure-kubernetes

---

Phase B — Doc-tester results (blind to source)

Routes exercised: /reference/cli/commands/aspire-add/ and /reference/cli/install-script/#options.

Metric	Count
Critical issues	0
Warnings	0
Passed checks	6
Knowledge gaps	2

Critical issues: none.
Warnings: none.

Passed checks

1. The added note renders as a "Note" admonition with the custom title "Integration discovery on prerelease CLI builds".
2. Inline code Aspire.Hosting.Azure.Kubernetes renders inside the note.
3. The -Quality|--quality link → /reference/cli/install-script/#options resolves: target page loads, the #options heading exists, and -Quality|--quality is shown there (0 console errors on the target page).
4. The new example renders under Examples as an "Aspire CLI" code frame — aspire add azure-kubernetes — with a working copy button ("Copied aspire add azure-kubernetes to clipboard").
5. Page console clean: 0 errors, 0 warnings (the only 404 seen was an initial no-trailing-slash request, immediately served at the canonical trailing-slash URL).
6. Structure/navigation intact: the note sits in the intro (no spurious TOC entry); the example is correctly nested as "4 of 4" in the existing Examples list.

Recommendations: Optional — link the note's "release quality" caveat to the existing aspire add kafka --version … example so readers can jump straight to version-pinning.

Knowledge gaps (blind-user perspective — not verifiable from docs alone)

1. The claim that a release quality CLI "continues to search stable packages only" is presented without an in-page demonstration; a blind user cannot confirm it. (Phase A found this contradicted against source — see C3.)
2. Both the new note and the page's existing Options list say -v, --version; a blind user would type -v, which cannot be validated from the docs. (Phase A found -v is not an alias of the add version option — see C4.)

[David Pine (IEvangelist)]

Contradicted (behavior) — release/13.5 @ 45f7776. This note says a release quality CLI "continues to search stable packages only," but on release/13.5 the aspire add discovery path does not gate on CLI quality. IntegrationPackageSearchService.GetSearchChannelsAsync always includes the implicit channel, and PackageChannel.CreateImplicitChannel(...) is hard-coded to PackageChannelQuality.Both (src/Aspire.Cli/Packaging/PackageChannel.cs:740-748). Its own comment: the implicit Quality.Both channel "must always participate so prerelease packages are reachable even when the explicit pin is Stable-quality" (IntegrationPackageSearchService.cs:97-100). A Both channel issues both prerelease:false and prerelease:true queries (PackageChannel.cs:321-328), so a release CLI still discovers prerelease packages from the ambient feed — "stable packages only" is inaccurate on this branch.

Also: the source PR this documents (microsoft/aspire#19426, milestone 13.6) is not present on release/13.5, which this PR targets. The staging/dev-vs-release split may hold on 13.6 but not on 13.5. Consider re-scoping to 13.5 behavior (prerelease integrations are discoverable via the always-present implicit Both channel; a release CLI typically selects the stable version by default) or retargeting once a 13.6 branch exists.

[David Pine (IEvangelist)]

Contradicted (CLI surface) — release/13.5 @ 45f7776. --version is correct, but the -v short form is not. aspire add's version option is registered as new("--version") with no -v alias (src/Aspire.Cli/Commands/AddCommand.cs:42 and :69; contrast --source, -s on the next line). -v is the root CLI's print-version flag (RootCommand.cs:271 versionOption.Aliases.Add("-v"); CommonOptionNames.cs:12 VersionShort = "-v"), so aspire add <name> -v <version> would not pin a package version. Suggest writing just --version. (Heads-up: the page's existing Options list also uses -v, --version for this option — out of scope here, but worth reconciling.)

[Adam Ratzman (adamint)]

I do not have anything to add beyond the existing review threads.