diff --git a/content/docs/external-agents.mdx b/content/docs/external-agents.mdx
index 1602bab..85e7b99 100644
--- a/content/docs/external-agents.mdx
+++ b/content/docs/external-agents.mdx
@@ -244,6 +244,24 @@ create (POST /workspaces) → online (register) → offline (heartbeat expires)
 - No auto-restart (agent manages its own process)
 - Paused external workspaces skip heartbeat monitoring
 
+### `removed` status — 410 Gone (#2429)
+
+Once a workspace transitions to `removed`:
+
+- **Tokens are revoked immediately**, but the row stays in the DB for audit-trail purposes
+- `GET /workspaces/:id` returns **410 Gone** with `{error: "workspace removed", id, removed_at, hint}` so callers fail fast at startup instead of after ~60s of heartbeat 401s
+- `DELETE /workspaces/:id` is the canonical removal trigger
+- Audit / admin tooling that intentionally wants the legacy 200 + body shape opts in via `GET /workspaces/:id?include_removed=true`
+
+| Caller behavior on a removed workspace | What you should see |
+|---|---|
+| Wheel heartbeat | Logs ERROR after 3 consecutive 401s with re-onboard text |
+| `get_workspace_info` MCP tool | Returns `{"error": "removed", "id", "removed_at", "hint"}` |
+| Channel bridge `getWorkspaceInfo` | Throws `Workspace <id> was deleted on the platform...` |
+| Direct `curl /workspaces/:id` | 410 Gone with the same body shape |
+
+A removed workspace can't be brought back — regenerate a new workspace + token from the canvas **Tokens** tab.
+
 ## Security
 
 - Bearer token required on all authenticated endpoints
diff --git a/content/docs/runtime-mcp.mdx b/content/docs/runtime-mcp.mdx
index 7ec6d7d..ae4d510 100644
--- a/content/docs/runtime-mcp.mdx
+++ b/content/docs/runtime-mcp.mdx
@@ -272,6 +272,28 @@ Regenerate from the canvas **Tokens** tab — a deleted workspace can't
 be brought back; you'll get a new workspace + token pair. Update your
 MCP config and restart your runtime.
 
+### `Workspace <id> was deleted on the platform...` from `get_workspace_info`
+
+Since [#2429](https://github.com/Molecule-AI/molecule-core/pull/2449),
+`GET /workspaces/:id` returns **410 Gone** (not 200 + `status:"removed"`)
+when the workspace has been deleted. The MCP wheel's `get_workspace_info`
+tool surfaces this as a tailored error message:
+
+```
+Workspace <id> was deleted on the platform at <removed_at>.
+Regenerate workspace + token from the canvas → Tokens tab.
+```
+
+This is the **startup-time** counterpart to the heartbeat-401 escalation
+above. If you see it within seconds of starting your runtime (rather
+than after ~60s of heartbeat failures), the workspace was already gone
+when you connected — regenerate as instructed.
+
+Audit-trail tools that intentionally want to inspect a removed workspace's
+metadata (admin dashboards, "show me deleted workspaces" tooling) can
+opt back into the legacy 200 + body shape via
+`GET /workspaces/<id>?include_removed=true`.
+
 ### `claude mcp list` shows the new config but tools still 401
 
 `/mcp` reconnect re-spawns the **cached** MCP config from session