From 318d782931ba420a5c4e3a3fee39358f26679628 Mon Sep 17 00:00:00 2001
From: "aspire-repo-bot[bot]"
 <268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Date: Tue, 23 Jun 2026 22:30:31 +0000
Subject: [PATCH] docs: update aspire run/stop graceful shutdown docs for
 #17814
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Expand aspire-run.mdx 'Stopping the AppHost' section with the full
  three-step shutdown ladder (cooperative cancellation → graceful wait →
  automatic force-kill) and clarify the second Ctrl+C behavior.
- Add a Windows note about isolated console session for tsx/npm AppHosts.
- Correct aspire-stop.mdx description: signal targets the AppHost process
  directly, not an intermediary CLI process.

Source: microsoft/aspire#17814

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../docs/reference/cli/commands/aspire-run.mdx       | 12 ++++++++++--
 .../docs/reference/cli/commands/aspire-stop.mdx      |  2 +-
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx
index 9e4c82ac6..b87ca5c30 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx
@@ -35,9 +35,17 @@ The command performs the following steps to run an Aspire AppHost:
 
 ## Stopping the AppHost
 
-To stop the running AppHost and exit, press <Kbd windows="Ctrl+C" mac="⌃+C" linux="Ctrl+C" /> (or send `SIGTERM` on Linux/macOS). The CLI requests a graceful shutdown of the AppHost and its resources.
+To stop the running AppHost and exit, press <Kbd windows="Ctrl+C" mac="⌃+C" linux="Ctrl+C" /> (or send `SIGTERM` on Linux/macOS). The shutdown follows a three-step sequence:
 
-If graceful shutdown is taking too long and you need to exit immediately, press <Kbd windows="Ctrl+C" mac="⌃+C" linux="Ctrl+C" /> a second time to terminate the process immediately.
+1. **Cooperative cancellation** — The CLI requests that the AppHost stop gracefully. Resources receive cancellation signals and begin their own cleanup.
+2. **Graceful wait** — The CLI waits for the AppHost process to exit cleanly on its own.
+3. **Automatic force-kill** — If the AppHost does not exit within the graceful timeout, the CLI terminates the process automatically.
+
+If graceful shutdown is taking too long and you need to exit immediately, press <Kbd windows="Ctrl+C" mac="⌃+C" linux="Ctrl+C" /> a second time. This collapses the graceful window and starts the force-kill sequence immediately.
+
+:::note
+On Windows, TypeScript/JavaScript AppHosts started with `tsx` or `npm` run in an isolated console session so that the Ctrl+C signal is delivered correctly to the Node.js process rather than to an unrelated foreground window.
+:::
 
 ## Hot Reload and watch behavior
 
diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-stop.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-stop.mdx
index bcca26551..a9ae2bf83 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-stop.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-stop.mdx
@@ -27,7 +27,7 @@ When executed without the `--apphost` option, the command:
 3. If only one AppHost is running in scope, stops it directly.
 4. If no in-scope AppHosts are found but out-of-scope AppHosts exist, displays all running AppHosts for selection.
 
-The command sends a stop signal to the CLI process that started the AppHost, which ensures a clean shutdown of all resources including the dashboard and any containers or processes that were started.
+The command sends a graceful stop signal to the running AppHost process, which ensures a clean shutdown of all resources including the dashboard and any containers or processes that were started.
 
 ## Options