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..ecfa3fa53 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
@@ -67,6 +67,10 @@ The Command Palette has commands for the most common tasks:
 - **Aspire: Open Aspire terminal** drops you into a terminal with the Aspire CLI already on `PATH` for anything the UI doesn't cover.
 - **Aspire: Update Aspire CLI** and **Aspire: Install Aspire CLI** let you manage CLI installation. **Install Aspire CLI** shows a package-manager picker (WinGet, Homebrew, npm, .NET tool, or mise, depending on your platform) plus a **Daily build (dev)** option and a link to the full [installation guide](/get-started/install-cli/) for every option, including the install script.
 
+:::note[Outdated CLI warning]
+VS Code warns when an operation uses an outdated published Aspire CLI. Stable CLIs are compared with stable releases; daily and staging CLIs are compared with prerelease releases. Local, PR, run, or unrecognized builds and cross-channel recommendations don't trigger the warning. The warning identifies the resolved executable path. `Update Aspire CLI` revalidates and updates that path; `Don't Show Again` suppresses warnings for that exact path and version.
+:::
+
 ## Live editor integration
 
 When an AppHost is running, the extension paints live state directly into your editor.