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 f7ca9a54c..a9acc9c69 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.
+:::
+
 :::note[AI agent setup]
 When you create or initialize an Aspire project, you can choose to configure AI agent support. If you opt in, choose where to install skills, then choose the skills to install. The location and skill prompts start with the Aspire CLI's recommended defaults selected. You can change or clear the selections before continuing.