[docs] Document VS Code outdated Aspire CLI warning

[aspire-repo-bot]

Documents changes from microsoft/aspire#19670

@ellahathaway

Targeting release/13.6 based on the source PR milestone 13.6.

Why

PR microsoft/aspire#19670 adds a new VS Code extension feature: a warning notification shown when an Aspire CLI selected for an operation (run/debug, terminal commands, one-shot AppHost operations, ps, describe, etc.) is outdated relative to the latest release in its own identity lane (stable vs. daily/staging/prerelease). The warning identifies the exact executable and offers Update Aspire CLI (updates that resolved path) and Don't Show Again (persists suppression for that exact path/version). This is a new user-facing behavior not previously covered anywhere on the docs site.

What changed

Updated src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx:

• Added a new :::note[Outdated CLI warning] callout directly after the existing "Update Aspire CLI" / "Install Aspire CLI" command bullet list, explaining when the warning appears, the two available actions, and the lane-matching behavior (stable-only vs. prerelease-only comparisons, silent for local/PR/unknown builds).

No new pages were created; this was a targeted addition to the existing VS Code extension page since the update-related commands were already documented there.

Generated by PR Documentation Check for #19670 · auto · 38.3 AIC · ⌖ 13.2 AIC · ⊞ 19.7K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

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

🟡 Changes recommended

The new callout omits key behavioral details (lane matching, silence conditions, and per-path/version suppression scope) described as required by the PR metadata/source PR.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds documentation to the VS Code extension “get started” page describing the new warning notification shown when the extension detects it is using an outdated Aspire CLI.

Changes:

• Added an “Outdated CLI warning” note callout under the VS Code command palette section.
• Described when the warning can appear and the available actions in the notification.

File summaries

File	Description
src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx	Adds a callout documenting the new VS Code outdated Aspire CLI warning behavior.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 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 — PR #1608

Source of truth: microsoft/aspire@main @ c8c77cd55acce332fa199a1a96da408394dde8e0 — contains source PR microsoft/aspire#19670 ("Warn when VS Code uses an outdated Aspire CLI", milestone 13.6, merge 039a7c58f1).

⚠️ Branch mismatch (non-blocking). This PR targets release/13.6, which does not exist in microsoft/aspire (latest release branch is release/13.5). 13.6 is still in development on main, so main is used as the source of truth — consistent with prior reviews of release/13.6-targeted docs PRs.

Phase A — claims: 5 non-narrative claims → 5 verified · 0 verified-with-nuance · 0 contradicted · 0 unverifiable.
Phase B — doc-tester: exercised /get-started/aspire-vscode-extension/ → HTTP 200, 0 console errors/warnings; insertion region present and correctly placed; the titled :::note[…] aside is already a rendered, reused component on this exact page. No new links or code introduced. Knowledge gap: the running build predates this PR.

Verdict: 🟡 COMMENT

Every factual claim in the added note is verified against source. Verdict is COMMENT (not APPROVE) only because Phase B could validate the page structure, insertion point, and the identical reused aside component, but not the rendered new prose itself (the deployed/local build predates this PR), plus one minor source-side casing nuance noted below. Nothing here blocks the PR.

---

Phase A — Claim verification

All 5 non-narrative claims in the added :::note[Outdated CLI warning] callout are verified. No inline comments (no contradicted/unverifiable claims).

✅ Verified claims (5) — evidence

Added text (aspire-vscode-extension.mdx, L70–72):

VS Code shows a warning when it uses an Aspire CLI executable that is outdated within its release channel. This can happen when you run or debug an app, use the Aspire terminal, or run an Aspire: … command. For example, VS Code might warn when it finds stable CLI 13.4.0 while stable 13.5.2 is available. Choose Update Aspire CLI to update the CLI or Don't Show Again to suppress warnings.

C1 — Warns when the in-use CLI is outdated within its release channel. ✅ verified
extension/src/utils/outdatedCliNotifier.ts fires showWarning(...) when compareCliVersionValues(identity.version, recommendation.version) < 0. The message is outdatedAspireCliWarning = "Aspire CLI {0} at {1} has a newer version available for its current channel: {2}." (extension/src/loc/strings.ts). configInfoProvider.ts#getCliUpdateRecommendation is documented as returning "a same-lane update … Stable installations follow stable releases and prerelease installations follow prerelease recommendations." The notifier class doc: "Checks actively used Aspire CLIs for a same-channel update."

C2 — Can appear on run/debug, Aspire terminal, or an Aspire: command. ✅ verified
notifyIfOutdated is wired via onDidResolveCliForOperation (extension/src/extension.ts:114). reportCliResolvedForOperation fires from appHostCliRunner.ts (run/debug the AppHost), AspireTerminalProvider.ts (Aspire terminal), and workspace.ts / AppHostDataRepository.ts / appHostPsPoller.ts / AppHostStopper.ts / AspirePackageRestoreProvider.ts (Aspire: commands, incl. describe/ps/stop/restore). The doc's "This can happen when …" list is a correct, representative (non-exhaustive) subset.

C3 — Example: stable 13.4.0 in use while stable 13.5.2 is available. ✅ verified
Behavior matches: within-lane comparison, warns when installed < recommended (comparison < 0), stable follows stable (getCliUpdateRecommendation doc). The version numbers are explicitly illustrative ("For example …"), so no assertion about actual releases is made.

C4 — Update Aspire CLI action updates the CLI. ✅ verified
strings.updateAspireCliAction = l10n.t({ message: 'Update Aspire CLI', … }) (exact string). package.nls.json command.updateSelf = "Update Aspire CLI". Selecting it executes aspire-vscode.updateSelf.

C5 — Don't Show Again action suppresses warnings. ✅ verified
strings.dontShowAgainLabel = l10n.t("Don't Show Again") — exact casing match to the doc. Selecting it calls _suppressNotification, which persists suppression via OutdatedCliSuppressionStore.
Minor nuance (non-blocking, source-side): package.nls.json localizes the analogous entry as "Don't show again" (lowercase "show"), but the runtime label the notifier actually passes to showWarningMessage is the strings.ts literal "Don't Show Again", which is what the doc quotes — so the doc matches the authoritative source string.

---

Phase B — Doc-tester results

Focus area: the single affected route derived from the PR diff — /get-started/aspire-vscode-extension/. Exercised as a new user via the browser, without consulting microsoft/aspire source.

Category	Passed	Failed	Warnings
Content accuracy (blind read)	1	0	0
Rendering / components	1	0	0
Links	1 (n/a — no new links)	0	0
Console health	1	0	0

Critical issues

None.

Warnings

None.

Passed checks

• Page loads — https://aspire.dev/get-started/aspire-vscode-extension/ returns HTTP 200, title "Aspire Visual Studio Code extension | Aspire".
• Console clean — 0 errors, 0 warnings (2 info) on load.
• Insertion region present & correctly placed — the Command Palette bullet list containing Aspire: Update Aspire CLI and Aspire: Install Aspire CLI renders immediately before the Live editor integration section, which is exactly where the new note is inserted.
• Reused component proven on this page — the page already renders titled note asides (:::note[Prerequisites] → a complementary "Prerequisites" landmark; :::note[Debugging]). The new :::note[Outdated CLI warning] uses the identical Starlight primitive and will render the same way.
• No new links or code — the note is prose plus two inline-code button labels; it introduces nothing that can 404 or fail to compile.
• Blind-user clarity — the note is self-contained: it states when the warning appears, the triggers, a concrete example, and the two actions. Understandable without prior Aspire knowledge.

Recommendations

None required.

Knowledge gap

The deployed site (and any local build) predates this unmerged PR, so the exact rendered new prose could not be observed directly. I validated the page structure, the precise insertion point, and the identical reused aside component instead. A full local PR-branch Astro build was intentionally skipped: the note adds no links or code examples and reuses a component already proven to render on this page, so the marginal value did not justify the heavy build.

---

_{Automated docs-accuracy reviewer · Phase A read microsoft/aspire@main c8c77cd5; Phase B ran the doc-tester skill blind against the live docs site. Out of scope (owned by CI): build/lint/formatting/spelling/markdown-style/broken-link checks, editorial tone.}