diff --git a/docs/18-http-api.md b/docs/18-http-api.md
index ea0e7ac1..0b2b1614 100644
--- a/docs/18-http-api.md
+++ b/docs/18-http-api.md
@@ -11,7 +11,7 @@ Interactive documentation is available at `/docs` (Swagger UI) and the raw OpenA
 All HTTP endpoints (except `/health`) require authentication via Bearer token in the `Authorization` header:
 
 ```
-Authorization: Bearer <token>
+Authorization: Bearer <TOKEN>
 ```
 
 Two token types are accepted:
@@ -23,7 +23,7 @@ Two token types are accepted:
 
 API keys are hashed with SHA-256 before lookup — the raw key is never stored. See [20 — API Keys & Auth](20-api-keys-auth.md) for details.
 
-> Some endpoints accept the token as a query parameter `?token=<token>` for use in `<img>` and `<audio>` tags (e.g., `/v1/files/`, `/v1/media/`).
+> Some endpoints accept the token as a query parameter `?token=<TOKEN>` for use in `<img>` and `<audio>` tags (e.g., `/v1/files/`, `/v1/media/`).
 
 ### Common Headers
 
@@ -95,6 +95,7 @@ CRUD operations for agent management. Requires `X-GoClaw-User-Id` header for mul
 | `GET` | `/v1/agents/{id}` | Get agent by ID or key | Bearer |
 | `PUT` | `/v1/agents/{id}` | Update agent (owner only) | Bearer |
 | `DELETE` | `/v1/agents/{id}` | Delete agent (owner only) | Bearer |
+| `POST` | `/v1/agents/sync-workspace` | Sync agent workspace files | Admin |
 
 ### Shares
 
@@ -110,6 +111,8 @@ CRUD operations for agent management. Requires `X-GoClaw-User-Id` header for mul
 |--------|------|-------------|
 | `POST` | `/v1/agents/{id}/regenerate` | Regenerate agent config with custom prompt |
 | `POST` | `/v1/agents/{id}/resummon` | Retry initial LLM summoning |
+| `POST` | `/v1/agents/{id}/cancel-summon` | Cancel an in-progress summon |
+| `GET` | `/v1/agents/{id}/system-prompt-preview` | Preview rendered system prompt |
 
 ### Predefined Agent Instances
 
@@ -117,7 +120,6 @@ CRUD operations for agent management. Requires `X-GoClaw-User-Id` header for mul
 |--------|------|-------------|
 | `GET` | `/v1/agents/{id}/instances` | List user instances |
 | `GET` | `/v1/agents/{id}/instances/{userID}/files` | List user context files |
-| `GET` | `/v1/agents/{id}/instances/{userID}/files/{fileName}` | Get specific user context file |
 | `PUT` | `/v1/agents/{id}/instances/{userID}/files/{fileName}` | Update user file (USER.md only) |
 | `PATCH` | `/v1/agents/{id}/instances/{userID}/metadata` | Update instance metadata |
 
@@ -466,6 +468,7 @@ Per-user credential storage for MCP servers (e.g., API keys users provide for ex
 | `GET` | `/v1/tools/builtin` | List all built-in tools |
 | `GET` | `/v1/tools/builtin/{name}` | Get tool definition |
 | `PUT` | `/v1/tools/builtin/{name}` | Update enabled/settings |
+| `GET` | `/v1/tools/builtin/{name}/tenant-config` | Get tenant-level tool config |
 | `PUT` | `/v1/tools/builtin/{name}/tenant-config` | Set tenant-level tool config |
 | `DELETE` | `/v1/tools/builtin/{name}/tenant-config` | Delete tenant-level tool config |
 
@@ -492,6 +495,26 @@ Set `"dryRun": true` to return tool schema without execution.
 
 ---
 
+## 9. TTS
+
+Text-to-speech synthesis and configuration.
+
+### Synthesis & Connection
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/v1/tts/synthesize` | Synthesize speech from text (operator role) |
+| `POST` | `/v1/tts/test-connection` | Test TTS provider connection (operator role) |
+
+### Configuration
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/tts/config` | Get tenant TTS configuration (admin) |
+| `POST` | `/v1/tts/config` | Save tenant TTS configuration (admin) |
+
+---
+
 ## 10. Memory
 
 Per-agent vector memory using pgvector.
@@ -512,7 +535,80 @@ Optional query parameter `?user_id=` for per-user scoping.
 
 ---
 
-## 11. Knowledge Graph
+## 11. Episodic Memory
+
+Episodic memory captures conversation summaries per user session for long-term context continuity.
+
+### List Episodic Summaries
+
+```
+GET /v1/agents/{agentID}/episodic
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `user_id` | string | Filter by user ID (optional). |
+| `limit` | integer | Max results (default: 20, max: 500). |
+| `offset` | integer | Pagination offset (default: 0). |
+
+**Response:**
+
+```json
+[
+  {
+    "id": "uuid",
+    "agent_id": "uuid",
+    "user_id": "user-123",
+    "summary": "User asked about deployment pipeline optimization. Discussed GitHub Actions, Docker layers, caching strategies. User implemented multi-stage builds.",
+    "key_entities": ["GitHub Actions", "Docker", "CI/CD"],
+    "sentiment": "positive",
+    "interaction_count": 5,
+    "tokens_exchanged": 4200,
+    "created_at": "2026-04-05T10:00:00Z",
+    "updated_at": "2026-04-05T11:30:00Z"
+  }
+]
+```
+
+### Search Episodic Summaries
+
+```
+POST /v1/agents/{agentID}/episodic/search
+```
+
+**Request:**
+
+```json
+{
+  "query": "Docker optimization strategies",
+  "user_id": "optional-user-id",
+  "max_results": 10,
+  "min_score": 0.5
+}
+```
+
+Runs hybrid search combining BM25 (keyword) and vector (semantic) matching.
+
+**Response:**
+
+```json
+[
+  {
+    "id": "uuid",
+    "agent_id": "uuid",
+    "user_id": "user-123",
+    "summary": "User asked about deployment pipeline optimization...",
+    "similarity_score": 0.92,
+    "created_at": "2026-04-05T10:00:00Z"
+  }
+]
+```
+
+---
+
+## 12. Knowledge Graph
 
 Per-agent entity-relation graph.
 
@@ -526,6 +622,7 @@ Per-agent entity-relation graph.
 | `POST` | `/v1/agents/{agentID}/kg/extract` | LLM-powered entity extraction |
 | `GET` | `/v1/agents/{agentID}/kg/stats` | Knowledge graph statistics |
 | `GET` | `/v1/agents/{agentID}/kg/graph` | Full graph for visualization |
+| `GET` | `/v1/agents/{agentID}/kg/graph/compact` | Compact graph optimized for 10k+ nodes |
 | `POST` | `/v1/agents/{agentID}/kg/dedup/scan` | Scan for duplicate entities |
 | `GET` | `/v1/agents/{agentID}/kg/dedup` | List dedup candidates |
 | `POST` | `/v1/agents/{agentID}/kg/merge` | Merge duplicate entities |
@@ -533,7 +630,282 @@ Per-agent entity-relation graph.
 
 ---
 
-## 12. Channels
+## 13. Knowledge Vault
+
+Persistent knowledge vault stores documents with vector embeddings and outbound/backlink graph connections.
+
+### Global Vault Operations
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/vault/documents` | List all vault documents (cross-agent) |
+| `POST` | `/v1/vault/documents` | Create vault document |
+| `GET` | `/v1/vault/documents/{docID}` | Get document |
+| `PUT` | `/v1/vault/documents/{docID}` | Update document |
+| `DELETE` | `/v1/vault/documents/{docID}` | Delete document |
+| `GET` | `/v1/vault/documents/{docID}/links` | Get document outlinks and backlinks |
+| `POST` | `/v1/vault/links` | Create link between documents |
+| `DELETE` | `/v1/vault/links/{linkID}` | Delete link |
+| `POST` | `/v1/vault/links/batch` | Batch get links |
+| `POST` | `/v1/vault/upload` | Upload document file |
+| `POST` | `/v1/vault/rescan` | Rescan vault for FS sync |
+| `GET` | `/v1/vault/tree` | Get vault file tree |
+| `POST` | `/v1/vault/search` | Hybrid FTS+vector search (cross-agent) |
+| `GET` | `/v1/vault/enrichment/status` | Get enrichment pipeline status |
+| `POST` | `/v1/vault/enrichment/stop` | Stop enrichment pipeline |
+| `GET` | `/v1/vault/graph` | Get vault document relationship graph |
+
+### Per-Agent Vault Operations
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/agents/{agentID}/vault/documents` | List agent vault documents |
+| `GET` | `/v1/agents/{agentID}/vault/documents/{docID}` | Get agent document |
+| `POST` | `/v1/agents/{agentID}/vault/documents` | Create agent document |
+| `PUT` | `/v1/agents/{agentID}/vault/documents/{docID}` | Update agent document |
+| `DELETE` | `/v1/agents/{agentID}/vault/documents/{docID}` | Delete agent document |
+| `GET` | `/v1/agents/{agentID}/vault/documents/{docID}/links` | Get agent document links |
+| `POST` | `/v1/agents/{agentID}/vault/search` | Search agent vault documents |
+| `POST` | `/v1/agents/{agentID}/vault/links` | Create link for agent document |
+| `DELETE` | `/v1/agents/{agentID}/vault/links/{linkID}` | Delete agent document link |
+
+**Query Parameters (list):**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `scope` | string | Filter by scope (e.g., `team`, `user`, `global`). |
+| `doc_type` | string | Comma-separated doc types (e.g., `guide,reference,note`). |
+| `limit` | integer | Max results (default: 20, max: 500). |
+| `offset` | integer | Pagination offset. |
+| `agent_id` | string | (Cross-agent only) Filter by specific agent. |
+
+---
+
+## 14. Evolution Metrics & Suggestions
+
+Per-agent evolution metrics track tool usage, retrieval performance, and user feedback to drive automated agent improvements.
+
+### Get Evolution Metrics
+
+```
+GET /v1/agents/{agentID}/evolution/metrics
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | no | Filter by metric type: `tool`, `retrieval`, `feedback`. Omit for all types. |
+| `aggregate` | boolean | no | Return aggregated metrics (grouped by tool/metric). Default: `false` (raw metrics). |
+| `since` | ISO 8601 | no | Start timestamp (default: 7 days ago). Example: `2026-04-01T00:00:00Z` |
+| `limit` | integer | no | Max results (default: 100, max: 500). |
+
+**Response (raw metrics):**
+
+```json
+[
+  {
+    "id": "uuid",
+    "agent_id": "uuid",
+    "metric_type": "tool",
+    "tool_name": "web_fetch",
+    "metric_key": "invocation_count",
+    "metric_value": 15,
+    "metadata": {"status": "success"},
+    "recorded_at": "2026-04-06T10:30:00Z"
+  }
+]
+```
+
+**Response (aggregated metrics):**
+
+```json
+{
+  "tool_aggregates": [
+    {
+      "tool_name": "web_fetch",
+      "invocation_count": 15,
+      "success_count": 14,
+      "failure_count": 1,
+      "avg_duration_ms": 2340
+    }
+  ],
+  "retrieval_aggregates": [
+    {
+      "query_count": 42,
+      "avg_recall": 0.78,
+      "avg_precision": 0.85,
+      "avg_relevance_score": 0.81
+    }
+  ]
+}
+```
+
+### List Evolution Suggestions
+
+```
+GET /v1/agents/{agentID}/evolution/suggestions
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `status` | string | Filter: `pending`, `approved`, `applied`, `rejected`, `rolled_back`. Omit for all. |
+| `limit` | integer | Max results (default: 50, max: 500). |
+
+**Response:**
+
+```json
+[
+  {
+    "id": "uuid",
+    "agent_id": "uuid",
+    "suggestion_type": "low_retrieval_usage",
+    "status": "pending",
+    "title": "Improve retrieval threshold",
+    "description": "Recent queries show low recall. Consider lowering retrieval_threshold from 0.5 to 0.4.",
+    "parameters": {
+      "current_threshold": 0.5,
+      "proposed_threshold": 0.4,
+      "confidence": 0.85
+    },
+    "created_at": "2026-04-06T09:00:00Z",
+    "reviewed_by": null,
+    "reviewed_at": null
+  }
+]
+```
+
+**Suggestion Types:**
+- `low_retrieval_usage` — Retrieval recall is below threshold for recent queries.
+- `tool_failure` — High failure rate detected for a tool.
+- `repeated_tool` — Tool called repeatedly without context change; candidate for skill.
+
+### Update Suggestion Status
+
+```
+PATCH /v1/agents/{agentID}/evolution/suggestions/{suggestionID}
+```
+
+**Request:**
+
+```json
+{
+  "status": "approved",
+  "reviewed_by": "optional-user-id"
+}
+```
+
+**Valid status transitions:** `pending` → `approved`, `rejected`, `rolled_back`.
+
+**Response:**
+
+```json
+{
+  "status": "ok"
+}
+```
+
+---
+
+## 15. Orchestration Mode
+
+Determines how an agent routes requests (standalone, delegation, team-based).
+
+### Get Agent Orchestration Mode
+
+```
+GET /v1/agents/{agentID}/orchestration
+```
+
+**Response:**
+
+```json
+{
+  "mode": "delegate",
+  "delegate_targets": [
+    {
+      "agent_key": "research-agent",
+      "display_name": "Research Specialist"
+    }
+  ],
+  "team": null
+}
+```
+
+Or in team mode:
+
+```json
+{
+  "mode": "team",
+  "delegate_targets": [],
+  "team": {
+    "id": "uuid",
+    "name": "Platform Team"
+  }
+}
+```
+
+**Mode values:**
+- `standalone` — No delegation. Agent handles all requests directly.
+- `delegate` — Routes complex requests to specialized agents (via agent links).
+- `team` — Routes to team members via task system.
+
+---
+
+## 16. V3 Feature Flags
+
+Per-agent feature flags control v3 system capabilities (evolution, episodic memory, vault, etc.).
+
+### Get V3 Flags
+
+```
+GET /v1/agents/{agentID}/v3-flags
+```
+
+**Response:**
+
+```json
+{
+  "evolution_enabled": true,
+  "episodic_enabled": true,
+  "vault_enabled": true,
+  "orchestration_enabled": false,
+  "skill_evolve": true,
+  "self_evolve": false
+}
+```
+
+### Update V3 Flags
+
+```
+PATCH /v1/agents/{agentID}/v3-flags
+```
+
+Accepts partial updates. Flag keys are validated against recognized v3 flags.
+
+**Request:**
+
+```json
+{
+  "evolution_enabled": true,
+  "episodic_enabled": false,
+  "vault_enabled": true
+}
+```
+
+**Response:**
+
+```json
+{
+  "status": "ok"
+}
+```
+
+---
+
+## 17. Channels
 
 ### Channel Instances
 
@@ -577,7 +949,7 @@ Credentials are masked in HTTP responses.
 
 ---
 
-## 13. Pending Messages
+## 18. Pending Messages
 
 | Method | Path | Description |
 |--------|------|-------------|
@@ -590,7 +962,7 @@ Compaction runs in the background. Falls back to hard delete if no LLM provider
 
 ---
 
-## 14. Team Events
+## 19. Team Events
 
 Team activity and audit trail.
 
@@ -600,7 +972,7 @@ Team activity and audit trail.
 
 ---
 
-## 16. Secure CLI Credentials
+## 20. Secure CLI Credentials
 
 CLI authentication credentials for secure command execution. Requires **admin role** (full gateway token or empty gateway token in dev/single-user mode).
 
@@ -608,10 +980,11 @@ CLI authentication credentials for secure command execution. Requires **admin ro
 |--------|------|-------------|
 | `GET` | `/v1/cli-credentials` | List all credentials |
 | `POST` | `/v1/cli-credentials` | Create new credential |
+| `GET` | `/v1/cli-credentials/presets` | Get preset credential templates |
+| `POST` | `/v1/cli-credentials/check-binary` | Check binary availability |
 | `GET` | `/v1/cli-credentials/{id}` | Get credential details |
 | `PUT` | `/v1/cli-credentials/{id}` | Update credential |
 | `DELETE` | `/v1/cli-credentials/{id}` | Delete credential |
-| `GET` | `/v1/cli-credentials/presets` | Get preset credential templates |
 | `POST` | `/v1/cli-credentials/{id}/test` | Test credential connection (dry-run) |
 
 ### Per-User Credentials
@@ -623,9 +996,19 @@ CLI authentication credentials for secure command execution. Requires **admin ro
 | `PUT` | `/v1/cli-credentials/{id}/user-credentials/{userId}` | Set user credential |
 | `DELETE` | `/v1/cli-credentials/{id}/user-credentials/{userId}` | Delete user credential |
 
+### Agent Grants
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/cli-credentials/{id}/agent-grants` | List agent grants for CLI cred |
+| `POST` | `/v1/cli-credentials/{id}/agent-grants` | Create agent grant |
+| `GET` | `/v1/cli-credentials/{id}/agent-grants/{grantId}` | Get agent grant |
+| `PUT` | `/v1/cli-credentials/{id}/agent-grants/{grantId}` | Update agent grant |
+| `DELETE` | `/v1/cli-credentials/{id}/agent-grants/{grantId}` | Delete agent grant |
+
 ---
 
-## 17. Runtime & Packages Management
+## 21. Runtime & Packages Management
 
 Manage system (apk), Python (pip), and Node (npm) package installation in the GoClaw runtime container. These endpoints do not inspect host-level runtimes. Requires authentication. When `GOCLAW_GATEWAY_TOKEN` is empty (dev/single-user mode), all users get admin role and can manage packages.
 
@@ -697,15 +1080,6 @@ POST /v1/packages/uninstall
 
 Same format as install. System packages are removed from persist file and container state.
 
-**Response:**
-
-```json
-{
-  "ok": true,
-  "error": ""
-}
-```
-
 ### Check Runtime Availability
 
 ```
@@ -729,11 +1103,25 @@ Check which prerequisite runtimes are available inside the active GoClaw runtime
 }
 ```
 
-The published `ghcr.io/nextlevelbuilder/goclaw:latest` image is the minimal variant, so missing Python or Node runtimes can be expected there.
+### GitHub Releases
+
+```
+GET /v1/packages/github-releases
+```
+
+Lists available GoClaw GitHub release versions for the update checker.
+
+### Shell Deny Groups
+
+```
+GET /v1/shell-deny-groups
+```
+
+List shell command deny group patterns configured for the gateway.
 
 ---
 
-## 18. Traces & Costs
+## 22. Traces & Costs
 
 LLM call tracing and cost analysis.
 
@@ -755,7 +1143,7 @@ LLM call tracing and cost analysis.
 
 ---
 
-## 19. Usage & Analytics
+## 23. Usage & Analytics
 
 | Method | Path | Description |
 |--------|------|-------------|
@@ -769,7 +1157,7 @@ LLM call tracing and cost analysis.
 
 ---
 
-## 20. Activity & Audit
+## 24. Activity & Audit
 
 | Method | Path | Description |
 |--------|------|-------------|
@@ -777,7 +1165,7 @@ LLM call tracing and cost analysis.
 
 ---
 
-## 21. Storage
+## 25. Storage
 
 Workspace file management.
 
@@ -798,7 +1186,7 @@ Workspace file management.
 
 ---
 
-## 22. Voices & Audio
+## 26. Voices & Audio
 
 Voice discovery for TTS providers (ElevenLabs). All endpoints are tenant-scoped and require tenant admin or operator role.
 
@@ -809,11 +1197,6 @@ Voice discovery for TTS providers (ElevenLabs). All endpoints are tenant-scoped
 
 ### `GET /v1/voices`
 
-Fetch available TTS voices for the current tenant's provider.
-
-**Query Parameters:**
-- None
-
 **Response** (200 OK):
 ```json
 [
@@ -830,24 +1213,12 @@ Fetch available TTS voices for the current tenant's provider.
 ]
 ```
 
-**Errors:**
-- 401: Missing or invalid token
-- 403: Insufficient permissions (requires tenant admin/operator)
-- 500: Provider error (e.g., ElevenLabs API unreachable)
-
-**Caching:**
-- Responses are in-memory cached per tenant with TTL 1h
-- Cache is shared across all HTTP + WebSocket handlers
-- Cache miss triggers immediate fetch from provider
+**Caching:** In-memory cached per tenant with TTL 1h. Cache miss triggers immediate fetch from provider.
 
 ### `POST /v1/voices/refresh`
 
 Invalidate the voice cache for the current tenant, forcing a fresh fetch on the next request.
 
-**Admin-only endpoint.** Useful after voice updates or CDN expiry issues.
-
-**Request body:** (empty)
-
 **Response** (202 Accepted):
 ```json
 { "message": "voice cache invalidated" }
@@ -855,7 +1226,7 @@ Invalidate the voice cache for the current tenant, forcing a fresh fetch on the
 
 ---
 
-## 23. Media
+## 27. Media
 
 | Method | Path | Description |
 |--------|------|-------------|
@@ -864,7 +1235,7 @@ Invalidate the voice cache for the current tenant, forcing a fresh fetch on the
 
 ---
 
-## 24. Files
+## 28. Files
 
 | Method | Path | Description |
 |--------|------|-------------|
@@ -875,7 +1246,7 @@ Auth via Bearer token or `?token=` query param (for `<img>` tags). MIME type aut
 
 ---
 
-## 25. API Keys
+## 29. API Keys
 
 Admin-only endpoints for managing gateway API keys. See [20 — API Keys & Auth](20-api-keys-auth.md) for the full authentication and authorization model.
 
@@ -913,7 +1284,7 @@ Admin-only endpoints for managing gateway API keys. See [20 — API Keys & Auth]
 
 ---
 
-## 26. OAuth
+## 30. OAuth
 
 | Method | Path | Description |
 |--------|------|-------------|
@@ -948,13 +1319,6 @@ Success payload:
       "remaining_percent": 76,
       "reset_after_seconds": 3600,
       "reset_at": "2026-03-24T20:15:00Z"
-    },
-    {
-      "label": "Secondary",
-      "used_percent": 38,
-      "remaining_percent": 62,
-      "reset_after_seconds": 604800,
-      "reset_at": "2026-03-31T19:15:00Z"
     }
   ],
   "core_usage": {
@@ -975,32 +1339,15 @@ Success payload:
 }
 ```
 
-Failure payload:
-
-```json
-{
-  "provider_name": "openai-codex",
-  "success": false,
-  "windows": [],
-  "error": "Quota metadata is missing for this account.",
-  "error_code": "missing_account_id",
-  "action_hint": "Sign in again so GoClaw can restore the ChatGPT account workspace metadata.",
-  "last_updated": "2026-03-24T19:15:00Z"
-}
-```
-
 Notes:
 - Invalid provider slugs return `400`.
-- Missing provider still returns `404`, and provider type conflicts still return `409`.
-- Missing quota metadata, expired workspace access, upstream `402`, upstream `403`, and upstream `429` return `200` with a structured failure payload so the dashboard can render actionable state inline.
-- `needs_reauth`, `is_forbidden`, and `retryable` are boolean hints for UI/state-machine handling.
+- Missing provider returns `404`, provider type conflicts return `409`.
+- Missing quota metadata, expired workspace access, upstream `402`/`403`/`429` return `200` with a structured failure payload.
 - `error_code` can be `missing_account_id`, `reauth_required`, `payment_required`, `quota_api_forbidden`, `quota_endpoint_not_found`, `rate_limited`, `provider_unavailable`, `network_timeout`, `network_error`, `quota_request_failed`, or `unknown_upstream_error`.
-- Failure payloads still include `windows: []` so clients can treat the envelope consistently.
-- `core_usage.five_hour` and `core_usage.weekly` are derived from upstream windows. When labels drift, GoClaw falls back to shortest-reset and longest-reset usage windows.
 
 ---
 
-## 27. Edition
+## 31. Edition
 
 | Method | Path | Description |
 |--------|------|-------------|
@@ -1008,7 +1355,7 @@ Notes:
 
 ---
 
-## 28. Tenants
+## 32. Tenants
 
 Multi-tenant management (admin only).
 
@@ -1024,7 +1371,7 @@ Multi-tenant management (admin only).
 
 ---
 
-## 29. System Configs
+## 33. System Configs
 
 Key-value system configuration store.
 
@@ -1037,7 +1384,7 @@ Key-value system configuration store.
 
 ---
 
-## 30. Team Workspace & Attachments
+## 34. Team Workspace & Attachments
 
 | Method | Path | Description |
 |--------|------|-------------|
@@ -1047,15 +1394,43 @@ Key-value system configuration store.
 
 ---
 
-## 31. Shell Deny Groups
+## 35. Backup & Restore
+
+System-level backup/restore endpoints (admin only). Stream progress via SSE.
+
+### System Backup
 
 | Method | Path | Description |
 |--------|------|-------------|
-| `GET` | `/v1/shell-deny-groups` | List shell command deny group patterns |
+| `POST` | `/v1/system/backup` | Create system backup (streams SSE progress) |
+| `GET` | `/v1/system/backup/preflight` | Check backup prerequisites |
+| `GET` | `/v1/system/backup/download/{token}` | Download backup archive |
+| `POST` | `/v1/system/restore` | Restore from backup archive (streams SSE progress) |
+
+**Query params for restore:** `skip_db=true`, `skip_files=true`, `dry_run=true`
+
+### S3 Backup Integration
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/system/backup/s3/config` | Get S3 backup configuration |
+| `PUT` | `/v1/system/backup/s3/config` | Set S3 backup configuration |
+| `GET` | `/v1/system/backup/s3/list` | List S3 backup objects |
+| `POST` | `/v1/system/backup/s3/upload` | Upload backup to S3 |
+| `POST` | `/v1/system/backup/s3/backup` | Trigger S3 backup |
+
+### Tenant Backup
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/v1/tenant/backup` | Create tenant-scoped backup |
+| `GET` | `/v1/tenant/backup/preflight` | Check tenant backup prerequisites |
+| `GET` | `/v1/tenant/backup/download/{token}` | Download tenant backup archive |
+| `POST` | `/v1/tenant/restore` | Restore tenant from backup |
 
 ---
 
-## 32. System
+## 36. System
 
 | Method | Path | Description |
 |--------|------|-------------|
@@ -1074,7 +1449,7 @@ Key-value system configuration store.
 
 ---
 
-## 33. MCP Bridge
+## 37. MCP Bridge
 
 Exposes GoClaw tools to Claude CLI via streamable HTTP at `/mcp/bridge`. Only listens on localhost. Protected by gateway token with HMAC-signed context headers.
 
@@ -1121,69 +1496,16 @@ The following operations are **only available via WebSocket RPC**, not HTTP:
 - **Cron jobs:** List, create, update, delete, logs (use WebSocket method `cron.*`)
 - **Send messages:** Send to channels (use WebSocket method `send.*`)
 - **Config management:** Get, apply, patch (use WebSocket method `config.*`)
-- **Delegations:** List, get delegation history (use WebSocket method `delegations.*`) — _not currently registered as WS methods either; may be removed_
 
 These endpoints require an active WebSocket connection to the `/ws` endpoint with proper authentication and agent context.
 
 ---
 
-## Notes on V3 Endpoints
+## Module Reference
 
-GoClaw v3 introduces new HTTP endpoints for agent evolution metrics, episodic memory, knowledge vault, and orchestration. These are documented separately in [22 — V3 HTTP Endpoints](22-v3-http-endpoints.md) to keep this document focused on the core REST API. V3 endpoints follow the same authentication, error handling, and header conventions as documented above.
-
----
-
-## File Reference
-
-| File | Purpose |
-|------|---------|
-| `internal/http/chat_completions.go` | OpenAI-compatible chat API |
-| `internal/http/responses.go` | OpenResponses protocol |
-| `internal/http/agents.go` | Agent CRUD + shares + instances + files |
-| `internal/http/skills.go` | Skill management + grants + versions |
-| `internal/http/providers.go` | Provider CRUD + verification + models |
-| `internal/http/mcp.go` | MCP server management + grants + requests |
-| `internal/http/builtin_tools.go` | Built-in tool management |
-| `internal/http/tools_invoke.go` | Direct tool invocation |
-| `internal/http/channel_instances.go` | Channel instance management + contacts |
-| `internal/http/memory_handlers.go` | Memory document management + search + indexing |
-| `internal/http/knowledge_graph.go` | Knowledge graph API (entities, relations, traversal) |
-| `internal/http/traces.go` | LLM trace listing + export |
-| `internal/http/usage.go` | Usage analytics + costs |
-| `internal/http/activity.go` | Activity audit log |
-| `internal/http/storage.go` | Workspace file management + size calculation |
-| `internal/http/media_upload.go` | Media file upload |
-| `internal/http/media_serve.go` | Media file serving |
-| `internal/http/files.go` | Workspace file serving |
-| `internal/http/api_keys.go` | API key management + revoke |
-| `internal/http/team_events.go` | Team event history API |
-| `internal/http/team_attachments.go` | Team attachment downloads |
-| `internal/http/workspace_upload.go` | Team workspace upload + move |
-| `internal/http/secure_cli.go` | CLI credential management |
-| `internal/http/packages.go` | Runtime package management (apk/pip/npm) |
-| `internal/http/pending_messages.go` | Pending message groups + compaction |
-| `internal/http/oauth.go` | OAuth authentication flows |
-| `internal/http/openapi.go` | OpenAPI spec + Swagger UI |
-| `internal/http/auth.go` | Authentication helpers |
-| `internal/gateway/server.go` | HTTP mux and route wiring |
-| `cmd/gateway.go` | Handler instantiation and wiring |
-| `cmd/pkg-helper/main.go` | Root-privileged system package helper (apk add/del) |
-| `internal/skills/package_lister.go` | Query installed packages from apk/pip3/npm |
-| `internal/http/edition.go` | Edition info endpoint |
-| `internal/http/system_configs.go` | System config key-value store |
-| `internal/http/tenants.go` | Multi-tenant management |
-| `internal/http/mcp_user_credentials.go` | MCP per-user credentials |
-| `internal/http/mcp_export.go` | MCP export |
-| `internal/http/mcp_import.go` | MCP import |
-| `internal/http/skills_export.go` | Skills export |
-| `internal/http/skills_import.go` | Skills import |
-| `internal/http/agents_export.go` | Agent export |
-| `internal/http/agents_import.go` | Agent import |
-| `internal/http/contact_merge_handlers.go` | Contact merge/unmerge |
-| `internal/http/user_search.go` | User search |
-| `internal/http/secure_cli_user_credentials.go` | CLI per-user credentials |
-| `internal/http/evolution_handlers.go` | V3: Evolution metrics + suggestions endpoints |
-| `internal/http/episodic_handlers.go` | V3: Episodic memory list + search endpoints |
-| `internal/http/vault_handlers.go` | V3: Vault document + link endpoints |
-| `internal/http/orchestration_handlers.go` | V3: Orchestration mode info endpoint |
-| `internal/http/v3_flags_handlers.go` | V3: Feature flag get/toggle endpoints |
+| Module | Path | Purpose |
+|--------|------|---------|
+| Auth & Routing | `internal/http/`, `internal/gateway/` | Auth middleware, RBAC, request routing, MCP bridge |
+| Chat, Agents & Skills | `internal/http/chat_completions.go`, `agents*.go`, `skills*.go`, `wake.go` | Conversational endpoints, agent CRUD, skill management |
+| Memory, Vault & Knowledge | `internal/http/memory.go`, `vault_handlers*.go`, `knowledge_graph.go`, `episodic_handlers.go` | Persistent knowledge, vector memory, document graph |
+| Evolution, Orchestration & Flags | `internal/http/evolution_handlers.go`, `orchestration_handlers.go`, `v3_flags_handlers.go` | v3 runtime control, metrics, suggestions, feature flags |
diff --git a/docs/21-agent-evolution-and-skill-management.md b/docs/21-agent-evolution-and-skill-management.md
index 34f7aee6..21e4fe0b 100644
--- a/docs/21-agent-evolution-and-skill-management.md
+++ b/docs/21-agent-evolution-and-skill-management.md
@@ -637,7 +637,7 @@ Evolution analysis runs as a periodic cron job (default: daily).
 
 ### 8.5 API & WebSocket
 
-**HTTP Endpoints** (see [22 — V3 HTTP Endpoints](22-v3-http-endpoints.md)):
+**HTTP Endpoints** (see [18 — HTTP REST API](18-http-api.md#14-evolution-metrics--suggestions)):
 - `GET /v1/agents/{agentID}/evolution/metrics` — Query/aggregate metrics
 - `GET /v1/agents/{agentID}/evolution/suggestions` — List suggestions
 - `PATCH /v1/agents/{agentID}/evolution/suggestions/{suggestionID}` — Approve/reject/rollback
@@ -674,4 +674,4 @@ Defaults used if keys absent. Set `evolution_enabled: false` to disable metrics
 - [15 - Core Skills System](./15-core-skills-system.md) — Bundled system skills, startup seeding, dependency checking
 - [16 - Skill Publishing System](./16-skill-publishing.md) — `publish_skill` tool and `skill-creator` core skill
 - [19 - WebSocket RPC Methods](./19-websocket-rpc.md) — V3 WebSocket methods for evolution, episodic, vault
-- [22 - V3 HTTP Endpoints](./22-v3-http-endpoints.md) — HTTP REST endpoints for evolution metrics, suggestions, episodic memory, vault documents
+- [18 - HTTP REST API](./18-http-api.md) — HTTP REST endpoints for evolution metrics, suggestions, episodic memory, vault documents
diff --git a/docs/22-v3-http-endpoints.md b/docs/22-v3-http-endpoints.md
deleted file mode 100644
index 79a1a05d..00000000
--- a/docs/22-v3-http-endpoints.md
+++ /dev/null
@@ -1,565 +0,0 @@
-# 22 — V3 HTTP Endpoints
-
-GoClaw v3 introduces new HTTP endpoints for agent evolution, episodic memory, knowledge vault, and orchestration capabilities. All endpoints follow the standard authentication and error response patterns from [18 — HTTP REST API](18-http-api.md).
-
----
-
-## 1. Evolution Metrics & Suggestions
-
-Per-agent evolution metrics track tool usage, retrieval performance, and user feedback to drive automated agent improvements.
-
-### Get Evolution Metrics
-
-```
-GET /v1/agents/{agentID}/evolution/metrics
-```
-
-**Query Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `type` | string | no | Filter by metric type: `tool`, `retrieval`, `feedback`. Omit for all types. |
-| `aggregate` | boolean | no | Return aggregated metrics (grouped by tool/metric). Default: `false` (raw metrics). |
-| `since` | ISO 8601 | no | Start timestamp (default: 7 days ago). Example: `2026-04-01T00:00:00Z` |
-| `limit` | integer | no | Max results (default: 100, max: 500). |
-
-**Response (raw metrics):**
-
-```json
-[
-  {
-    "id": "uuid",
-    "agent_id": "uuid",
-    "metric_type": "tool",
-    "tool_name": "web_fetch",
-    "metric_key": "invocation_count",
-    "metric_value": 15,
-    "metadata": {"status": "success"},
-    "recorded_at": "2026-04-06T10:30:00Z"
-  },
-  {
-    "id": "uuid",
-    "agent_id": "uuid",
-    "metric_type": "retrieval",
-    "metric_key": "recall_rate",
-    "metric_value": 0.78,
-    "metadata": {"query_count": 42},
-    "recorded_at": "2026-04-06T11:00:00Z"
-  }
-]
-```
-
-**Response (aggregated metrics):**
-
-```json
-{
-  "tool_aggregates": [
-    {
-      "tool_name": "web_fetch",
-      "invocation_count": 15,
-      "success_count": 14,
-      "failure_count": 1,
-      "avg_duration_ms": 2340
-    },
-    {
-      "tool_name": "exec",
-      "invocation_count": 8,
-      "success_count": 8,
-      "failure_count": 0,
-      "avg_duration_ms": 1200
-    }
-  ],
-  "retrieval_aggregates": [
-    {
-      "query_count": 42,
-      "avg_recall": 0.78,
-      "avg_precision": 0.85,
-      "avg_relevance_score": 0.81
-    }
-  ]
-}
-```
-
-**Status codes:** `200` OK, `400` bad request, `404` agent not found, `500` server error.
-
-### List Evolution Suggestions
-
-```
-GET /v1/agents/{agentID}/evolution/suggestions
-```
-
-**Query Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `status` | string | Filter: `pending`, `approved`, `applied`, `rejected`, `rolled_back`. Omit for all. |
-| `limit` | integer | Max results (default: 50, max: 500). |
-
-**Response:**
-
-```json
-[
-  {
-    "id": "uuid",
-    "agent_id": "uuid",
-    "suggestion_type": "low_retrieval_usage",
-    "status": "pending",
-    "title": "Improve retrieval threshold",
-    "description": "Recent queries show low recall. Consider lowering retrieval_threshold from 0.5 to 0.4.",
-    "parameters": {
-      "current_threshold": 0.5,
-      "proposed_threshold": 0.4,
-      "confidence": 0.85
-    },
-    "created_at": "2026-04-06T09:00:00Z",
-    "reviewed_by": null,
-    "reviewed_at": null
-  },
-  {
-    "id": "uuid",
-    "agent_id": "uuid",
-    "suggestion_type": "repeated_tool",
-    "status": "pending",
-    "title": "Tool usage pattern detected",
-    "description": "Tool 'exec' called 5+ times in a row without context change. Consider skill creation.",
-    "parameters": {
-      "tool_name": "exec",
-      "occurrence_count": 12,
-      "pattern_score": 0.92
-    },
-    "created_at": "2026-04-05T14:30:00Z",
-    "reviewed_by": null,
-    "reviewed_at": null
-  }
-]
-```
-
-**Suggestion Types:**
-- `low_retrieval_usage` — Retrieval recall is below threshold for recent queries.
-- `tool_failure` — High failure rate detected for a tool.
-- `repeated_tool` — Tool called repeatedly without context change; candidate for skill.
-
-### Update Suggestion Status
-
-```
-PATCH /v1/agents/{agentID}/evolution/suggestions/{suggestionID}
-```
-
-**Request:**
-
-```json
-{
-  "status": "approved",
-  "reviewed_by": "optional-user-id"
-}
-```
-
-**Valid status transitions:** `pending` → `approved`, `rejected`, `rolled_back`.
-
-**Response:**
-
-```json
-{
-  "status": "ok"
-}
-```
-
----
-
-## 2. Episodic Memory Summaries
-
-Episodic memory captures conversation summaries per user session for long-term context continuity.
-
-### List Episodic Summaries
-
-```
-GET /v1/agents/{agentID}/episodic
-```
-
-**Query Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `user_id` | string | Filter by user ID (optional). |
-| `limit` | integer | Max results (default: 20, max: 500). |
-| `offset` | integer | Pagination offset (default: 0). |
-
-**Response:**
-
-```json
-[
-  {
-    "id": "uuid",
-    "agent_id": "uuid",
-    "user_id": "user-123",
-    "summary": "User asked about deployment pipeline optimization. Discussed GitHub Actions, Docker layers, caching strategies. User implemented multi-stage builds.",
-    "key_entities": ["GitHub Actions", "Docker", "CI/CD"],
-    "sentiment": "positive",
-    "interaction_count": 5,
-    "tokens_exchanged": 4200,
-    "created_at": "2026-04-05T10:00:00Z",
-    "updated_at": "2026-04-05T11:30:00Z"
-  }
-]
-```
-
-### Search Episodic Summaries
-
-```
-POST /v1/agents/{agentID}/episodic/search
-```
-
-**Request:**
-
-```json
-{
-  "query": "Docker optimization strategies",
-  "user_id": "optional-user-id",
-  "max_results": 10,
-  "min_score": 0.5
-}
-```
-
-Runs hybrid search combining BM25 (keyword) and vector (semantic) matching.
-
-**Response:**
-
-```json
-[
-  {
-    "id": "uuid",
-    "agent_id": "uuid",
-    "user_id": "user-123",
-    "summary": "User asked about deployment pipeline optimization...",
-    "similarity_score": 0.92,
-    "created_at": "2026-04-05T10:00:00Z"
-  }
-]
-```
-
----
-
-## 3. Knowledge Vault
-
-Persistent knowledge vault stores documents with vector embeddings and outbound/backlink graph connections.
-
-### List Vault Documents
-
-Cross-agent listing:
-```
-GET /v1/vault/documents
-```
-
-Per-agent listing:
-```
-GET /v1/agents/{agentID}/vault/documents
-```
-
-**Query Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `scope` | string | Filter by scope (e.g., `team`, `user`, `global`). |
-| `doc_type` | string | Comma-separated doc types (e.g., `guide,reference,note`). |
-| `limit` | integer | Max results (default: 20, max: 500). |
-| `offset` | integer | Pagination offset. |
-| `agent_id` | string | (Cross-agent only) Filter by specific agent. |
-
-**Response:**
-
-```json
-[
-  {
-    "id": "uuid",
-    "agent_id": "uuid",
-    "title": "Database Indexing Best Practices",
-    "doc_type": "guide",
-    "scope": "team",
-    "content_preview": "Indexes are crucial for query performance. Types include...",
-    "created_at": "2026-04-01T09:00:00Z",
-    "updated_at": "2026-04-05T14:20:00Z",
-    "outlink_count": 3,
-    "backlink_count": 2
-  }
-]
-```
-
-### Get Single Document
-
-```
-GET /v1/agents/{agentID}/vault/documents/{docID}
-```
-
-**Response:**
-
-```json
-{
-  "id": "uuid",
-  "agent_id": "uuid",
-  "title": "Database Indexing Best Practices",
-  "doc_type": "guide",
-  "scope": "team",
-  "content": "Indexes are crucial for query performance. Types include: B-tree, Hash, Bitmap...",
-  "metadata": {"version": 2, "author": "team-lead"},
-  "created_at": "2026-04-01T09:00:00Z",
-  "updated_at": "2026-04-05T14:20:00Z"
-}
-```
-
-### Search Vault Documents
-
-```
-POST /v1/agents/{agentID}/vault/search
-```
-
-**Request:**
-
-```json
-{
-  "query": "index performance optimization",
-  "scope": "team",
-  "doc_types": ["guide", "reference"],
-  "max_results": 10
-}
-```
-
-Hybrid FTS+vector search combining keyword and semantic matching.
-
-**Response:**
-
-```json
-[
-  {
-    "id": "uuid",
-    "title": "Database Indexing Best Practices",
-    "doc_type": "guide",
-    "relevance_score": 0.94,
-    "snippet": "...Indexes are crucial for query performance. Types include B-tree, Hash, Bitmap...",
-    "created_at": "2026-04-01T09:00:00Z"
-  }
-]
-```
-
-### Get Document Links
-
-```
-GET /v1/agents/{agentID}/vault/documents/{docID}/links
-```
-
-Returns outgoing links and backlinks for a document.
-
-**Response:**
-
-```json
-{
-  "outlinks": [
-    {
-      "target_doc_id": "uuid",
-      "target_title": "Query Optimization Techniques",
-      "link_type": "references"
-    }
-  ],
-  "backlinks": [
-    {
-      "source_doc_id": "uuid",
-      "source_title": "Performance Tuning Guide",
-      "link_type": "referenced_by"
-    }
-  ]
-}
-```
-
----
-
-## 4. Graph Visualization
-
-Lightweight endpoints for rendering vault and knowledge graph relationships.
-
-### Get Vault Graph
-
-```
-GET /v1/vault/graph
-```
-
-**Query Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `agent_id` | string | Filter by agent (optional). |
-| `team_id` | string | Scope by team (optional). |
-| `limit` | integer | Max nodes to return (default: 500, max: 2000). |
-
-**Response:**
-
-```json
-{
-  "nodes": [
-    {
-      "id": "uuid",
-      "label": "Document Title",
-      "type": "document",
-      "agent_id": "uuid",
-      "metadata": {}
-    }
-  ],
-  "edges": [
-    {
-      "id": "link-uuid",
-      "source": "doc-uuid-1",
-      "target": "doc-uuid-2",
-      "type": "wikilink"
-    }
-  ],
-  "total_nodes": 150,
-  "total_edges": 120
-}
-```
-
-Used for vault document relationship visualization with FA2 layout (web worker rendering).
-
-### Get Knowledge Graph (Compact)
-
-```
-GET /v1/agents/{agentID}/kg/graph/compact
-```
-
-**Query Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `limit` | integer | Max nodes (default: 500, max: 2000). Optimized 10k node load. |
-
-**Response:** Same format as vault graph; nodes represent semantic entities, edges represent relationship types.
-
-**Features:**
-- Semantic zoom support
-- Optimized for 10k+ entity graphs
-- FA2 layout computed via web worker
-
----
-
-## 5. Orchestration Mode
-
-Determines how an agent routes requests (standalone, delegation, team-based).
-
-### Get Agent Orchestration Mode
-
-```
-GET /v1/agents/{agentID}/orchestration
-```
-
-**Response:**
-
-```json
-{
-  "mode": "delegate",
-  "delegate_targets": [
-    {
-      "agent_key": "research-agent",
-      "display_name": "Research Specialist"
-    },
-    {
-      "agent_key": "doc-agent",
-      "display_name": "Documentation Expert"
-    }
-  ],
-  "team": null
-}
-```
-
-Or in team mode:
-
-```json
-{
-  "mode": "team",
-  "delegate_targets": [],
-  "team": {
-    "id": "uuid",
-    "name": "Platform Team"
-  }
-}
-```
-
-**Mode values:**
-- `standalone` — No delegation. Agent handles all requests directly.
-- `delegate` — Routes complex requests to specialized agents (via agent links).
-- `team` — Routes to team members via task system.
-
----
-
-## 6. V3 Feature Flags
-
-Per-agent feature flags control v3 system capabilities (evolution, episodic memory, vault, etc.).
-
-### Get V3 Flags
-
-```
-GET /v1/agents/{agentID}/v3-flags
-```
-
-**Response:**
-
-```json
-{
-  "evolution_enabled": true,
-  "episodic_enabled": true,
-  "vault_enabled": true,
-  "orchestration_enabled": false,
-  "skill_evolve": true,
-  "self_evolve": false
-}
-```
-
-### Update V3 Flags
-
-```
-PATCH /v1/agents/{agentID}/v3-flags
-```
-
-Accepts partial updates. Flag keys are validated against recognized v3 flags.
-
-**Request:**
-
-```json
-{
-  "evolution_enabled": true,
-  "episodic_enabled": false,
-  "vault_enabled": true
-}
-```
-
-**Response:**
-
-```json
-{
-  "status": "ok"
-}
-```
-
----
-
-## File Reference
-
-| File | Purpose |
-|------|---------|
-| `internal/http/evolution_handlers.go` | Metrics + suggestions endpoints |
-| `internal/http/episodic_handlers.go` | Episodic memory list + search endpoints |
-| `internal/http/vault_handlers.go` | Knowledge vault document + link endpoints |
-| `internal/http/vault_graph_handler.go` | Vault + KG graph visualization endpoints |
-| `internal/http/orchestration_handlers.go` | Orchestration mode info endpoint |
-| `internal/http/v3_flags_handlers.go` | V3 feature flag get/toggle endpoints |
-| `internal/store/evolution_store.go` | Evolution metrics/suggestions store interface |
-| `internal/store/episodic_store.go` | Episodic memory store interface |
-| `internal/store/vault_store.go` | Knowledge vault store interface |
-| `internal/store/pg/evolution_metrics.go` | PostgreSQL evolution metrics impl |
-| `internal/store/pg/evolution_suggestions.go` | PostgreSQL evolution suggestions impl |
-| `internal/store/pg/episodic.go` | PostgreSQL episodic memory impl |
-| `internal/store/pg/vault.go` | PostgreSQL vault documents/links impl |
-
----
-
-## Cross-References
-
-- [18 — HTTP REST API](18-http-api.md) — Standard authentication, error responses, common headers
-- [19 — WebSocket RPC Methods](19-websocket-rpc.md) — V3 WebSocket methods (evolution, orchestration)
-- [21 — Agent Evolution & Skill Management](21-agent-evolution-and-skill-management.md) — Evolution system architecture and suggestion engine