docs: explain cloud project data purge

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

content/03.cloud/01.cloud-guide.md

@@ -104,6 +104,28 @@ The full command walkthrough — sign-in options, API keys, workspaces, routing,
 
 ---
 
+## Remove a Cloud Project and Its Data
+
+Cloud project removal keeps note files by default. Use `--delete-notes` when you also want to purge the project's active cloud storage:
+
+```bash
+# Stop tracking the project, but retain its cloud files
+bm project remove research --cloud
+
+# Remove the project and purge every object under its cloud storage prefix
+bm project remove research --cloud --delete-notes
+```
+
+The `--cloud` flag is optional when `research` is already configured as a cloud-routed project. Hosted deletion is asynchronous: the project disappears from normal listings when deletion is accepted, then a background job removes its database rows. With `--delete-notes`, that job also removes indexed and unindexed objects under the project's exact storage prefix.
+
+The MCP `delete_project` tool provides the same behavior with `delete_notes=true`. Its response reports the pending deletion status and background job ID.
+
+::warning
+Deleting with `--delete-notes` is irreversible for active project storage. Existing point-in-time snapshots may still contain historical copies until those snapshots are deleted or expire.
+::
+
+---
+
 ## Upload Files to Cloud
 
 ::note{icon="i-lucide-upload"}

content/10.reference/1.cli-reference.md

@@ -244,7 +244,7 @@ bm project add research ~/Documents/research --default
 
 ### `bm project remove`
 
-Remove a project from configuration.
+Remove a project. Files are retained by default; pass `--delete-notes` to remove them too.
 
 ```bash
 bm project remove research
@@ -253,10 +253,12 @@ bm project remove research --delete-notes
 
 | Flag | Description |
 |------|-------------|
-| `--delete-notes` | Also delete project files from disk |
+| `--delete-notes` | Also delete project files: local files for a local project, or all active objects under the project prefix for a cloud project |
 | `--local` | Force local routing |
 | `--cloud` | Force cloud routing |
 
+Cloud deletion is accepted asynchronously. Without `--delete-notes`, the project is removed from the hosted database but its cloud files remain. With `--delete-notes`, the background job purges indexed and unindexed objects under the exact project storage prefix before completing the hard delete. Existing cloud snapshots follow their own retention and deletion lifecycle.
+
 ### `bm project default`
 
 Set the default project used as fallback when no project is specified.

content/10.reference/2.mcp-tools-reference.md

@@ -202,13 +202,16 @@ Create a project.
 
 ### `delete_project`
 
-Remove a project from Basic Memory config.
+Remove a project from Basic Memory. Note files are retained by default.
 
 | Parameter | Type | Required | Notes |
 |---|---|---|---|
 | `project_name` | string | Yes | Name of the project to remove |
+| `delete_notes` | boolean | No | Default `false`. Set to `true` to delete local files or purge every active cloud object under the project's storage prefix |
 | `workspace` | string | No | Cloud workspace selector when deleting from a specific workspace |
 
+Hosted deletion is asynchronous. The tool response reports the project deletion status and background job ID when the cloud backend queues the work. With `delete_notes=false`, cloud objects are retained even though the project and its indexed database rows are removed. With `delete_notes=true`, the background job removes indexed and unindexed objects under the exact project prefix before completing the hard delete. Existing snapshots follow their separate retention lifecycle.
+
 ### `list_directory`
 
 List directory contents with optional depth and glob filter.