docs: document aspire stop --volumes opt-in cleanup (#1729)

Documents the new --volumes option added to aspire stop --force in
microsoft/aspire#20195. By default --force still preserves persistent
volumes; --volumes opts in to also removing Aspire-owned named volumes.

Co-authored-by: aspire-repo-bot[bot] <268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: aspire-repo-bot[bot]

src/frontend/src/content/docs/reference/cli/commands/aspire-stop.mdx

@@ -41,7 +41,7 @@ Use `--force` to stop the selected AppHost and then remove the persistent resour
 aspire stop --force
 ```
 
-The command performs the normal stop flow first, then removes persistent resources associated with the AppHost. The command attempts to clean up persistent resources whether or not an instance of the AppHost is running. Persistent resources started using a version of the Aspire CLI released before `--force` support was added can't be cleaned up using `--force`.
+The command performs the normal stop flow first, then removes persistent resources associated with the AppHost. The command attempts to clean up persistent resources whether or not an instance of the AppHost is running. Persistent resources started using a version of the Aspire CLI released before `--force` support was added can't be cleaned up using `--force`. By default, `--force` preserves persistent volumes so that data survives cleanup.
 
 :::caution
 The `--force` option permanently removes the selected AppHost's persistent resource instances without an additional confirmation prompt. Data stored only in those resources can be lost. For container resources, use a [volume or bind mount](/fundamentals/persist-data-volumes/) to persist data independently of a specific resource's lifetime.
@@ -54,6 +54,22 @@ Additional notes and limitations:
 - For a .NET AppHost that doesn't use the Aspire CLI bundle, cleanup requires Aspire.Hosting 13.5 or later. If the AppHost uses an older version, its version can't be determined, or its project can't be inspected, the command displays a warning and still attempts cleanup. Resources created without the required workload metadata might remain.
 - If the AppHost stops successfully, but persistent resource cleanup fails, the command exits with an error but leaves the AppHost stopped. You can resolve any errors and run `aspire stop --force` again or manually clean up any remaining persistent resources if necessary.
 
+### Also remove persistent volumes
+
+By default, `aspire stop --force` preserves any [persistent volumes](/fundamentals/persist-data-volumes/) created for the AppHost, so their data survives cleanup. Pass `--volumes` together with `--force` to also remove those volumes:
+
+```bash title="Aspire CLI"
+aspire stop --force --volumes
+```
+
+`--volumes` requires `--force`; using `--volumes` without `--force` fails with an error. Only named volumes that Aspire created and tracks ownership of are removed. Anonymous volumes and bind mounts are unaffected, and a volume that existed before the AppHost started is adopted for mounting but isn't recorded as Aspire-owned, so cleanup leaves it intact.
+
+:::caution
+Removing persistent volumes permanently deletes their data. There's no additional confirmation prompt before deletion.
+:::
+
+For a non-bundle .NET AppHost older than Aspire.Hosting 13.6, the CLI can't determine whether the AppHost created the volume-ownership records required for cleanup and displays a compatibility warning before still attempting cleanup.
+
 Before scanning for AppHosts to stop, `aspire stop` also detects and cleans up any orphaned AppHosts whose launching CLI process has died, so leaked processes are removed even if a normal stop can't reach one of them.
 
 ## Options
@@ -70,7 +86,11 @@ The following options are available:
 
 - **`--force`**
 
-  Perform the normal attempt to stop all instances of a specific AppHost, then attempt to clean up persistent resources associated with that AppHost. You can combine this option with `--apphost` to specify an AppHost to stop, but not with `--all`.
+  Perform the normal attempt to stop all instances of a specific AppHost, then attempt to clean up persistent resources associated with that AppHost, preserving persistent volumes by default. You can combine this option with `--apphost` to specify an AppHost to stop, but not with `--all`.
+
+- **`--volumes`**
+
+  Also remove persistent volumes created by Aspire during persistent resource cleanup. Requires `--force`.
 
 - <Include relativePath="reference/cli/includes/option-help.md" />
 
@@ -104,12 +124,18 @@ The following options are available:
   aspire stop --all
   ```
 
-- Stop the AppHost and clean up its persistent resources:
+- Stop the AppHost and clean up its persistent resources, preserving volumes:
 
   ```bash title="Aspire CLI"
   aspire stop --force
   ```
 
+- Stop the AppHost and remove its persistent resources, including persistent volumes:
+
+  ```bash title="Aspire CLI"
+  aspire stop --force --volumes
+  ```
+
 - Stop any running instances and clean up persistent resources for a specific AppHost when the target AppHost might be ambiguous:
 
   ```bash title="Aspire CLI"

src/frontend/src/content/docs/whats-new/aspire-13-6.mdx

@@ -251,11 +251,19 @@ aspire sdk export
 - **Stricter `wait` failures.** `aspire wait` exits with code `18` as soon as a resource reaches `FailedToStart`, including when the requested target status is `down`.
 - **Safer resource descriptions.** `aspire describe` redacts a resource's own secret environment-variable values as well as secrets passed to dependents. Secrets embedded inside larger connection strings aren't automatically detected.
 - **Clearer terminal output.** `aspire ps` colorizes statuses, and progress rendering is suppressed when console logging is enabled.
+- **Opt-in volume cleanup.** `aspire stop --force` continues to preserve persistent volumes by default. Add `--volumes` to also remove volumes that Aspire created and owns:
+
+  ```bash title="Aspire CLI — Remove persistent volumes on stop"
+  aspire stop --force --volumes
+  ```
+
+  `--volumes` requires `--force`. Only Aspire-owned named volumes are removed; anonymous volumes, bind mounts, and volumes that existed before the AppHost started are left intact.
 
 <LearnMore>
   See the [`aspire run`](/reference/cli/commands/aspire-run/), [`aspire
-  describe`](/reference/cli/commands/aspire-describe/), and [`aspire
-  wait`](/reference/cli/commands/aspire-wait/) command references.
+  describe`](/reference/cli/commands/aspire-describe/), [`aspire
+  wait`](/reference/cli/commands/aspire-wait/), and [`aspire
+  stop`](/reference/cli/commands/aspire-stop/) command references.
 </LearnMore>
 
 ## 🧰 Visual Studio Code extension