From 7ce54f986be3e642784b17a64c9c960009e427f1 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 05:37:38 +0000
Subject: [PATCH] docs: document aspire stop socket cleanup for detached
 AppHosts

After aspire stop confirms the AppHost process has terminated, it now
removes the backchannel socket file. This prevents stale-socket errors
when running subsequent commands (aspire add, aspire describe, etc.)
after the stop/detach workflow.

Documents the fix from microsoft/aspire#18296 (fixes #17587).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../src/content/docs/reference/cli/commands/aspire-stop.mdx   | 4 ++++
 1 file changed, 4 insertions(+)

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..4a068f41a 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
@@ -29,6 +29,10 @@ When executed without the `--apphost` option, the command:
 
 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.
 
+### Stopping a detached AppHost
+
+When stopping an AppHost that was started with [`aspire run --detach`](/reference/cli/commands/aspire-run/#options), the `aspire stop` command waits for the AppHost process to terminate and then removes the backchannel socket file it previously used for communication. Cleaning up the socket file ensures that subsequent CLI commands such as `aspire add` or `aspire describe` do not encounter stale-connection errors from a dead AppHost process.
+
 ## Options
 
 The following options are available: