chore(docs): Add explanation on deleting data and cloud vs local differences (#1114)

docs/docs.json

@@ -75,7 +75,8 @@
                       "v3/documentation/features/advanced/using-filters",
                       "v3/documentation/features/advanced/structured-outputs",
                       "v3/documentation/features/advanced/streaming-response",
-                      "v3/documentation/features/advanced/file-uploads"
+                      "v3/documentation/features/advanced/file-uploads",
+                      "v3/documentation/features/advanced/deleting-data"
                     ]
                   }
                 ]

docs/v3/api-reference/endpoint/keys/create-key.mdx

@@ -1,3 +1,13 @@
 ---
 openapi: post /v3/keys
 ---
+
+<Note>
+**Self-hosted only.** This endpoint is not available on Honcho Cloud
+(`api.honcho.dev`) — requests to it return `405 Method Not Allowed`. Create and
+manage keys for a cloud instance from the
+[API Keys page](https://app.honcho.dev/api-keys) in the dashboard.
+
+On a self-hosted instance it requires an admin key, and returns an error when
+`AUTH_USE_AUTH` is disabled.
+</Note>

docs/v3/documentation/features/advanced/deleting-data.mdx

@@ -0,0 +1,131 @@
+---
+title: 'Deleting Data'
+description: 'How to delete sessions, workspaces, and conclusions — and what survives each'
+icon: 'trash'
+---
+
+Deletion in Honcho is **permanent and cannot be undone**. There is no soft
+delete, no trash, and no restore.
+
+## What can be deleted
+
+| Resource | Endpoint | Behavior |
+|---|---|---|
+| Session | `DELETE /v3/workspaces/{workspace_id}/sessions/{session_id}` | `202` — cascade runs in the background |
+| Workspace | `DELETE /v3/workspaces/{workspace_id}` | `202` — cascade runs in the background |
+| Conclusion | `DELETE /v3/workspaces/{workspace_id}/conclusions/{conclusion_id}` | `204` — immediate |
+| Webhook endpoint | `DELETE /v3/workspaces/{workspace_id}/webhooks/{endpoint_id}` | Immediate |
+
+**Peers and individual messages cannot be deleted.** To remove a peer's data,
+delete the sessions it participated in, then delete its remaining conclusions
+(see [Conclusions outlive their sessions](#conclusions-outlive-their-sessions)).
+To remove a peer from one conversation without deleting anything, use
+[remove peers from session](/v3/api-reference/endpoint/sessions/remove-peers-from-session)
+instead.
+
+## Deleting a session
+
+```bash
+curl -X DELETE "$HONCHO_URL/v3/workspaces/my-app/sessions/session-1" \
+  -H "Authorization: Bearer $HONCHO_API_KEY"
+```
+
+The session is marked inactive immediately and the endpoint returns `202
+Accepted`. The cascade — messages, message embeddings, queued reasoning work,
+session-scoped conclusions, and peer associations — is processed in the
+background with retries.
+
+Because the work is asynchronous, a `202` means *accepted*, not *finished*. The
+session drops out of session listings right away, but its messages and
+conclusions drain afterwards. Deletion tasks are internal infrastructure work
+and do **not** appear in
+[queue status](/v3/documentation/features/advanced/queue-status) counts, so
+there is no endpoint that reports when the cascade has finished.
+
+<CodeGroup>
+```python Python
+session.delete()
+```
+
+```typescript TypeScript
+await session.delete();
+```
+</CodeGroup>
+
+## Deleting a workspace
+
+A workspace can only be deleted once it has **no active sessions**. Deleting a
+workspace that still has sessions returns `409 Conflict`:
+
+```json
+{"detail": "Cannot delete workspace 'my-app': active session(s) remain. Delete all sessions first."}
+```
+
+The correct order is:
+
+1. List the workspace's sessions — `POST /v3/workspaces/{workspace_id}/sessions/list`
+2. Delete each session — `DELETE /v3/workspaces/{workspace_id}/sessions/{session_id}`
+3. Delete the workspace — `DELETE /v3/workspaces/{workspace_id}`
+
+Step 2 returns `202`, so the session deletions are still draining when step 3
+runs. That is fine: a session is marked inactive synchronously, so the workspace
+delete stops returning `409` as soon as the deletes are accepted. Any session
+created after the workspace deletion is accepted is cascade-deleted too.
+
+<CodeGroup>
+```python Python
+# Materialize the list first — deleting shifts the pagination window
+for session in list(honcho.sessions()):
+    session.delete()
+
+honcho.delete_workspace("my-app")
+```
+
+```typescript TypeScript
+// Materialize the list first — deleting shifts the pagination window
+const sessions = [];
+for await (const session of await honcho.sessions()) sessions.push(session);
+for (const session of sessions) await session.delete();
+
+await honcho.deleteWorkspace("my-app");
+```
+</CodeGroup>
+
+Deleting a workspace removes every peer, session, message, conclusion,
+collection, embedding, webhook endpoint, and queued task belonging to it.
+
+## Conclusions outlive their sessions
+
+This is the most common surprise. Deleting a session does **not** erase
+everything Honcho learned in it.
+
+- **Explicit conclusions** — direct facts drawn from messages — are tied to the
+  session they came from and are deleted with it.
+- **Derived conclusions** (deductive, inductive, contradiction) are consolidations
+  that may draw on several sessions. They are stored at the workspace level with
+  no owning session, so they survive session deletion and stay in the peer's
+  [representation](/v3/documentation/core-concepts/representation).
+
+To remove those, list and delete them directly:
+
+<CodeGroup>
+```python Python
+for conclusion in alice.conclusions.list():
+    alice.conclusions.delete(conclusion.id)
+```
+
+```typescript TypeScript
+for (const conclusion of await alice.conclusions.list()) {
+  await alice.conclusions.delete(conclusion.id);
+}
+```
+</CodeGroup>
+
+Deleting the whole workspace removes conclusions at every level and needs no
+follow-up.
+
+## Permissions
+
+Session and workspace deletion accept any key scoped to that workspace — an
+admin key is not required. Deleting a session additionally accepts a
+session-scoped key.

docs/v3/documentation/features/advanced/overview.mdx

@@ -23,3 +23,4 @@ Advanced features give you fine-grained control over Honcho's behavior and imple
 - [Filters](/v3/documentation/features/advanced/using-filters) - Filter queries with advanced parameters
 - [Streaming Responses](/v3/documentation/features/advanced/streaming-response) - Stream dialectic responses in real-time
 - [File Uploads](/v3/documentation/features/advanced/file-uploads) - Ingest files into peer memory
+- [Deleting Data](/v3/documentation/features/advanced/deleting-data) - Delete sessions, workspaces, and conclusions

docs/v3/documentation/features/advanced/webhooks.mdx

@@ -13,6 +13,14 @@ for a session has drained.
 Webhooks are registered per workspace. Every event for that workspace is
 delivered to every endpoint registered on it.
 
+<Note>
+**On Honcho Cloud, register endpoints from the dashboard.** The webhook API
+below is available on self-hosted instances; on `api.honcho.dev` it returns
+`405 Method Not Allowed`. Use the
+[Webhooks page](https://app.honcho.dev/webhooks) instead. Everything else on
+this page — payload shapes, delivery semantics — applies to both.
+</Note>
+
 ## Registering an Endpoint
 
 <CodeGroup>

docs/v3/documentation/reference/platform.mdx

@@ -62,6 +62,8 @@ The **Performance** page provides comprehensive monitoring with usage metrics, h
 ## 3. Manage API Keys
 The [API Keys](https://app.honcho.dev/api-keys) page allows you to create and manage authentication tokens for different environments. You can create admin-level keys with full instance access or scope keys to a specific `Workspace`, `Peer`, or `Session`.
 
+Keys for a cloud instance can only be created here, not through the API — `POST /v3/keys` is disabled on `api.honcho.dev` and returns `405`. The same applies to the webhook management endpoints, which live on the [Webhooks](https://app.honcho.dev/webhooks) page.
+
 Scoped keys are authorized by their narrowest claim and never widen to the whole workspace:
 
 - A **peer-scoped** key acts on its own peer, plus **read-only** access to the sessions its peer is an active member of (context, summaries, peers, its own per-session config, search, and message reads). It cannot write to those sessions or act on other peers.

docs/v3/documentation/reference/sdk.mdx

@@ -206,6 +206,9 @@ honcho.set_metadata(dict)
 
 # Get list of all workspace IDs
 workspaces = honcho.workspaces()
+
+# Delete a workspace and everything in it (requires no active sessions)
+honcho.delete_workspace(workspace_id)
 ```
 
 ```typescript TypeScript
@@ -238,6 +241,9 @@ await honcho.setMetadata(metadata);
 
 // Get list of all workspace IDs
 const workspaces = await honcho.workspaces();
+
+// Delete a workspace and everything in it (requires no active sessions)
+await honcho.deleteWorkspace(workspaceId);
 ```
 </CodeGroup>