diff --git a/content/03.cloud/01.cloud-guide.md b/content/03.cloud/01.cloud-guide.md
index 8351aaa..c9f3064 100644
--- a/content/03.cloud/01.cloud-guide.md
+++ b/content/03.cloud/01.cloud-guide.md
@@ -104,6 +104,34 @@ 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:
+
+::warning
+If the project has a configured local sync directory, `--cloud --delete-notes` also removes that local directory. Back up any local files you need before running the destructive command. Deletion is irreversible for active project storage; existing point-in-time snapshots may still contain historical copies until those snapshots are deleted or expire.
+::
+
+```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
+```
+
+Keep the explicit `--cloud` flag on the destructive `--delete-notes` command so the CLI also removes any configured local sync directory. Omitting `--cloud` from a cloud-routed project still purges hosted storage, but leaves the local sync copy intact. Hosted deletion is asynchronous: the project is hidden from cloud workspace operations when deletion is accepted, then a background job removes its database rows. A local routing or sync configuration entry can still appear as a config-only row in the combined `bm project list`; that does not mean the hosted project remains. With `--delete-notes`, the background job also removes indexed and unindexed objects under the project's exact storage prefix.
+
+The MCP `delete_project` tool provides the same hosted-storage purge with
+`delete_notes=true` when the MCP session is hosted or explicitly cloud-routed. From a local
+stdio MCP session, also pass `workspace` to route the request to that cloud workspace;
+`delete_notes=true` alone does not switch a local request to Cloud. MCP deletion does not
+remove a configured local sync directory, so use the explicit CLI command above when you need
+to delete both copies. The MCP response reports the pending deletion status and background
+job ID.
+
+---
+
 ## Upload Files to Cloud
 
 ::note{icon="i-lucide-upload"}
diff --git a/content/10.reference/1.cli-reference.md b/content/10.reference/1.cli-reference.md
index 908d70d..980ac7e 100644
--- a/content/10.reference/1.cli-reference.md
+++ b/content/10.reference/1.cli-reference.md
@@ -244,19 +244,33 @@ 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. For
+a cloud project with a configured local sync directory, also pass `--cloud` to remove both the
+hosted objects and that local copy.
 
 ```bash
+# Stop tracking a project while retaining its files
 bm project remove research
+
+# Delete a local project's files
 bm project remove research --delete-notes
+
+# Purge cloud storage and remove any configured local sync directory
+bm project remove research --cloud --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.
+
+::warning
+For a cloud project configured with a local sync path, explicitly passing both `--cloud` and `--delete-notes` also removes that local sync directory. Back up any local files you need before running the command.
+::
+
 ### `bm project default`
 
 Set the default project used as fallback when no project is specified.
diff --git a/content/10.reference/2.mcp-tools-reference.md b/content/10.reference/2.mcp-tools-reference.md
index 41ee0ca..8ef7251 100644
--- a/content/10.reference/2.mcp-tools-reference.md
+++ b/content/10.reference/2.mcp-tools-reference.md
@@ -202,12 +202,15 @@ 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 |
-| `workspace` | string | No | Cloud workspace selector when deleting from a specific workspace |
+| `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. From a local stdio MCP session, provide this to route deletion to cloud unless the session is already explicitly cloud-routed |
+
+Cloud purge behavior applies when the MCP session is hosted or factory-routed to cloud, explicitly cloud-routed, or given a `workspace` selector. From a local stdio MCP session, `delete_notes=true` alone does not switch this tool to cloud routing; pass `workspace` to ensure the hosted project and objects are targeted. 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`