docs: sync with goclaw source changes b1f6eadf..b9670555 (EN+VI+ZH) (#57)

P0 Breaking Changes:
- tools-overview: web_search now tenant-only, removed config.json5 format
- upgrading: add migrations 000048-055, tools.web.* removal callout

P1 New Features:
- security-hardening: exec grant enforcement section
- skills: github:owner/repo[@tag] installer type
- pancake: auto_react_options fields (allow/deny post/user IDs)
- tts-voice: Voices API (GET/POST /v1/voices) + STT section

P2 Accuracy Fixes:
- context-pruning: fix pipeline diagram (remove pruneContextMessages)
- docker-compose: chromedp/headless-shell:latest image
- knowledge-vault: scope/ownership invariant section
- rest-api: cancel-summon, system-prompt-preview, Voices endpoints

Author: thieung

advanced/context-pruning.md

@@ -20,9 +20,11 @@ Context pruning is distinct from [session compaction](../core-concepts/sessions-
 Pruning is **opt-in** — it only runs when `mode: "cache-ttl"` is set on the agent. The flow:
 
 ```
-history → limitHistoryTurns → pruneContextMessages → sanitizeHistory → LLM
+history → limitHistoryTurns → sanitizeHistory → LLM
 ```
 
+> **Note:** `pruneContextMessages` (PruneStage) is **not** part of the main pipeline above. It runs opt-in and separately — only when `mode: "cache-ttl"` is set. The diagram above reflects the standard history preparation path.
+
 Before each LLM call, GoClaw:
 
 1. Counts tokens in all messages using the tiktoken BPE tokenizer (falls back to `chars / 4` heuristic when tiktoken is unavailable).
@@ -274,4 +276,4 @@ Tool output is now capped at the source before being added to context. Rather th
 - [Memory System](../core-concepts/memory-system.md) — 3-tier memory architecture and consolidation pipeline
 - [Configuration Reference](/config-reference) — full agent config reference
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-09 -->
+<!-- goclaw-source: b9670555 | updated: 2026-04-19 -->

advanced/knowledge-vault.md

@@ -50,6 +50,28 @@ Documents are scoped by **tenant** (isolation boundary), **agent** (namespace),
 | `team` | Team workspace documents shared across team members |
 | `shared` | Cross-tenant shared knowledge (future) |
 
+### Document Scope & Ownership Invariant
+
+The `scope` field has a strict ownership invariant enforced at the database level by migration `000055` (`vault_documents_scope_consistency` CHECK constraint):
+
+| `scope` | `agent_id` | `team_id` | Visibility |
+|---------|------------|-----------|------------|
+| `personal` | set | NULL | Owning agent only (within tenant) |
+| `team` | NULL | set | Members of the team (within tenant) |
+| `shared` | NULL | NULL | All agents within the tenant |
+| `custom` | any | any | User-defined via `custom_scope` |
+
+The CHECK constraint rejects any INSERT or UPDATE that violates the `scope × agent_id × team_id` relationship above. `scope='custom'` is the exception — it is intentionally unconstrained, allowing user-defined ownership semantics.
+
+#### Agent Read Semantics
+
+`vault_search`, `ListDocuments`, and `CountDocuments` always return:
+
+- Documents owned by the querying agent (`agent_id = <agent>`)
+- PLUS shared documents (`agent_id IS NULL`)
+
+Within a team context (a `RunContext` with `TeamID` set), results also include team-scoped documents for that team (`scope = 'team'` with `team_id = <team>`). Tenant isolation (`tenant_id = <tenant>`) is always enforced regardless of scope.
+
 ---
 
 ## Data Model
@@ -391,4 +413,4 @@ No feature flag. Vault is active if the migration ran and VaultStore initialized
 - [Memory System](../core-concepts/memory-system.md) — Vector-based long-term memory
 - [Context Files](../agents/context-files.md) — Static documents injected into agent context
 
-<!-- goclaw-source: 1296cdbf | updated: 2026-04-15 -->
+<!-- goclaw-source: b9670555 | updated: 2026-04-19 -->

advanced/skills.md

@@ -219,7 +219,29 @@ GoClaw auto-detects and installs missing skill dependencies:
 
 1. **Scanner** — statically analyzes `scripts/` subdirectory for Python (`import X`, `from X import`) and Node.js (`require('X')`, `import from 'X'`) imports
 2. **Checker** — verifies each import resolves at runtime via subprocess (`python3 -c "import X"` / `node -e "require.resolve('X')"`)
-3. **Installer** — installs by prefix: `pip:name` → `pip3 install`, `npm:name` → `npm install -g`, `apk:name` → `doas apk add`
+3. **Installer** — installs by prefix:
+
+| Prefix | Effect |
+|--------|--------|
+| `pip:name` | `pip3 install` (Python package) |
+| `npm:name` | `npm install -g` (Node.js package) |
+| `system:name` | `apk add` via pkg-helper (system package) |
+| `github:owner/repo[@tag]` | GitHub Releases installer — admin-only, SHA256-verified, ELF-validated. Binary lands in `/app/data/.runtime/bin/` (on `$PATH`). |
+
+Example SKILL.md frontmatter using `github:`:
+
+```yaml
+---
+name: my-skill
+description: Does things using ripgrep and gh CLI.
+deps:
+  - github:BurntSushi/ripgrep@14.1.0
+  - github:cli/cli@v2.40.0
+  - pip:requests
+---
+```
+
+The `github:` installer fetches the release from GitHub Releases, auto-selects the `linux` + arch-matching asset (amd64 / arm64), verifies SHA256 if the publisher ships `checksums.txt`, validates ELF magic bytes, and extracts to `/app/data/.runtime/bin/`. If no `@tag` is specified, the latest release is used.
 
 Dep checks run in a background goroutine at startup (non-blocking). Skills with missing deps are archived automatically; they are re-activated after deps are installed. You can also trigger a rescan via **Skills → Rescan Deps** in the Dashboard or `POST /v1/skills/rescan-deps`.
 
@@ -399,4 +421,4 @@ See [Agent Evolution](agent-evolution.md) for full details on the `skill_manage`
 - [Custom Tools](/custom-tools) — add shell-backed tools to your agents
 - [Scheduling & Cron](/scheduling-cron) — run agents on a schedule
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-15 -->
+<!-- goclaw-source: b9670555 | updated: 2026-04-19 -->

advanced/tts-voice.md

@@ -255,6 +255,91 @@ Each agent can override the global TTS voice and model via its `other_config` JS
 
 ---
 
+## Voices API
+
+GoClaw exposes HTTP endpoints for discovering available TTS voices. These are tenant-scoped and require tenant admin or operator role.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/voices` | List available voices (in-memory cached, TTL 1h) |
+| `POST` | `/v1/voices/refresh` | Force-invalidate the voice cache (admin only) |
+
+### `GET /v1/voices`
+
+Returns the voice list for the current tenant's configured ElevenLabs provider. Results are cached in-memory per tenant with a 1-hour TTL — shared across all HTTP and WebSocket handlers.
+
+```json
+[
+  {
+    "voice_id": "pMsXgVXv3BLzUgSXRplE",
+    "name": "Alice",
+    "preview_url": "https://...",
+    "category": "premade",
+    "labels": {
+      "use_case": "conversational",
+      "accent": "american"
+    }
+  }
+]
+```
+
+A cache miss triggers an immediate fetch from ElevenLabs. Returns `500` if the provider is unreachable.
+
+### `POST /v1/voices/refresh`
+
+Invalidates the voice cache for the current tenant so the next `GET /v1/voices` request fetches a fresh list from the provider. Useful after adding voices to your ElevenLabs account or after CDN expiry.
+
+```json
+{ "message": "voice cache invalidated" }
+```
+
+Response is `202 Accepted`.
+
+---
+
+## Speech-to-Text (STT)
+
+GoClaw routes all voice/audio transcription through a unified `audio.Manager` with a provider chain. Channels (Telegram, Discord, Feishu, WhatsApp) share the same STT infrastructure.
+
+### Unified Transcription Flow
+
+```mermaid
+flowchart TD
+    VOICE["Voice/audio message"] --> ROUTE{Channel type?}
+
+    ROUTE -->|Telegram / Discord / Feishu| DOWNLOAD["Download audio file"]
+    ROUTE -->|WhatsApp| WA_CHECK{"whatsapp_enabled\nin settings?"}
+
+    WA_CHECK -->|No| WA_FALLBACK["[Voice message]\n(default opt-out)"]
+    WA_CHECK -->|Yes| DOWNLOAD
+
+    DOWNLOAD --> STT_CHECK{"STT providers\nconfigured?"}
+    STT_CHECK -->|Yes| STT_CHAIN["Try providers in order:\nelevenlabs_scribe, proxy"]
+    STT_CHECK -->|No| FALLBACK["[Voice message]"]
+
+    STT_CHAIN -->|Success| TEXT["Transcribed text\n→ agent context"]
+    STT_CHAIN -->|Fail / 10s timeout| FALLBACK
+```
+
+### WhatsApp Opt-In
+
+WhatsApp STT is **off by default** (`whatsapp_enabled: false`). Rationale: WhatsApp voice messages are end-to-end encrypted. Sending audio bytes to an external STT provider breaks E2E encryption. Admins must explicitly enable it in **Config → Audio → STT** and acknowledge the E2E breaking change.
+
+When disabled (default): voice messages appear in agent context as `[Voice message]` — no audio leaves the device.
+When enabled: audio is transcribed via the configured STT chain; falls back to `[Voice message]` on failure or timeout (10 s wall clock).
+
+### STT Provider Chain
+
+| Setting | Behavior |
+|---------|----------|
+| `providers: ["elevenlabs_scribe", "proxy_stt"]` | Try ElevenLabs Scribe first; fall back to legacy proxy |
+| `providers: []` (empty) | Skip all STT; voice → `[Voice message]` |
+| `providers` missing (nil) | Check for legacy `STTProxyURL` bridge at startup |
+
+Configure via **Config → Audio → STT** in the web UI (stored in `builtin_tools[stt].settings.providers`). When this list is present it overrides all legacy channel-specific STT configs.
+
+---
+
 ## STT Builtin Tool
 
 The `stt` builtin tool (seeded by migration 050) enables agents to transcribe voice/audio input using ElevenLabs Scribe or a compatible proxy — see [Tools Overview](/tools-overview) for how to enable and configure it.
@@ -280,4 +365,4 @@ The `stt` builtin tool (seeded by migration 050) enables agents to transcribe vo
 - [Scheduling & Cron](/scheduling-cron) — trigger agents on a schedule
 - [Extended Thinking](/extended-thinking) — deeper reasoning for complex replies
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-17 -->
+<!-- goclaw-source: b9670555 | updated: 2026-04-19 -->

channels/pancake.md

@@ -89,6 +89,10 @@ For config-file-based channels (instead of DB instances):
 | `features.comment_reply` | bool | -- | Enable comment replies |
 | `features.first_inbox` | bool | -- | Send a one-time DM to a commenter after their first comment reply |
 | `features.auto_react` | bool | -- | Auto-like user comments on Facebook (Facebook only) |
+| `auto_react_options.allow_post_ids` | list | -- | Only react to comments on these post IDs (nil = all posts) |
+| `auto_react_options.deny_post_ids` | list | -- | Never react to comments on these post IDs (overrides allow) |
+| `auto_react_options.allow_user_ids` | list | -- | Only react to comments from these user IDs (nil = all users) |
+| `auto_react_options.deny_user_ids` | list | -- | Never react to comments from these user IDs (overrides allow) |
 | `comment_reply_options.include_post_context` | bool | false | Prepend post text to comment content sent to the agent |
 | `comment_reply_options.filter` | string | `"all"` | Comment filter mode: `"all"` or `"keyword"` |
 | `comment_reply_options.keywords` | list | -- | Required when `filter="keyword"` — only process comments containing these keywords |
@@ -232,6 +236,17 @@ When `features.comment_reply: true`, additional options control comment handling
 
 **Auto-react** (`features.auto_react: true`): automatically likes every valid incoming comment on Facebook (Facebook platform only). Fires independently of `comment_reply` — you can react without replying.
 
+Scope the reactions further with `auto_react_options`:
+
+| Field | Type | Behavior |
+|-------|------|----------|
+| `allow_post_ids` | list | React only on comments for these post IDs (nil = all posts) |
+| `deny_post_ids` | list | Never react on these post IDs (overrides allow) |
+| `allow_user_ids` | list | React only to comments from these user IDs (nil = all users) |
+| `deny_user_ids` | list | Never react to comments from these user IDs (overrides allow) |
+
+Deny lists always take precedence over allow lists. Omitting `auto_react_options` entirely means no scope filter (react to all valid comments).
+
 **First inbox** (`features.first_inbox: true`): after replying to a comment, sends a one-time private DM to the commenter inviting them to continue via inbox. Only sent once per sender per session restart. Customize the DM text with `first_inbox_message`.
 
 ### Channel Health
@@ -268,4 +283,4 @@ Application-level failures (HTTP 200 with `success: false` in JSON body) are als
 - [Telegram](/channel-telegram) — Telegram bot setup
 - [Multi-Channel Setup](/recipe-multi-channel) — Configure multiple channels
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-17 -->
+<!-- goclaw-source: b9670555 | updated: 2026-04-19 -->

core-concepts/tools-overview.md

@@ -38,19 +38,21 @@ Tools are how agents interact with the world beyond generating text. An agent ca
 | **Brave** | Requires `BRAVE_API_KEY` |
 | **DuckDuckGo** | Free fallback — used last if no API keys for the others |
 
-Configure provider order via `provider_order` in tool settings:
+> **Breaking change (v3.2+):** `config.json5 tools.web.*` has been removed. Configuration is now tenant-only. Existing keys are auto-migrated on first startup (data hook 055).
 
-```json
+Configure `web_search` via the dashboard (**Config → Tools → Web Search**) or the API:
+
+```bash
+# Set provider order via tenant-config API
+PUT /v1/tools/builtin/web_search/tenant-config
 {
-  "tools": {
-    "web_search": {
-      "provider_order": ["exa", "tavily", "brave", "duckduckgo"]
-    }
-  }
+  "provider_order": ["exa", "tavily", "brave", "duckduckgo"],
+  "brave": { "enabled": true, "max_results": 5 },
+  "exa": { "enabled": false }
 }
 ```
 
-DuckDuckGo requires no API key and is always available as the final fallback.
+DuckDuckGo requires no API key and is always available as the final fallback — it cannot be disabled.
 
 ### v3 Memory & Vault Tools
 
@@ -310,4 +312,4 @@ All parameters are optional — defaults apply when not configured.
 - [Multi-Tenancy](/multi-tenancy) — Per-user tool access and isolation
 - [Custom Tools](/custom-tools) — Build your own tools
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-09 -->
+<!-- goclaw-source: b9670555 | updated: 2026-04-19 -->

deployment/docker-compose.md

@@ -185,7 +185,7 @@ Mounts `/var/run/docker.sock` so GoClaw can spin up isolated containers for agen
 
 ### `docker-compose.browser.yml`
 
-Starts `zenika/alpine-chrome:124` with CDP enabled on port 9222. GoClaw connects via `GOCLAW_BROWSER_REMOTE_URL=ws://chrome:9222`.
+Starts `chromedp/headless-shell:latest` with CDP enabled on port 9222. GoClaw connects via `GOCLAW_BROWSER_REMOTE_URL=ws://chrome:9222`.
 
 ### `docker-compose.otel.yml`
 
@@ -464,4 +464,4 @@ docker pull ghcr.io/nextlevelbuilder/goclaw:otel
 - [Observability](/deploy-observability) — OpenTelemetry and Jaeger configuration
 - [Tailscale](/deploy-tailscale) — secure remote access via Tailscale
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-09 -->
+<!-- goclaw-source: b9670555 | updated: 2026-04-19 -->

deployment/security-hardening.md

@@ -152,6 +152,28 @@ For tools that need credentials (e.g., `gh`, `aws`), GoClaw uses direct process
 
 Shell metacharacters (`;`, `|`, `&`, `$()`, backticks) are detected and rejected before execution.
 
+### Exec grant enforcement
+
+Agent-level grant enforcement runs **before** any process spawn, blocking ungranted agents from executing registered binaries:
+
+| Control | Detail |
+|---------|--------|
+| **Grant lookup** | `store.SecureCLIStore.IsRegisteredBinary()` checks the `secure_cli_agent_grants` table. Non-global binaries require a row for the calling agent. |
+| **Fail-closed** | If the grant lookup errors (DB down, timeout), exec is denied with a retry message. Per-lookup timeout: 2 seconds. |
+| **Env scrubbing** | When a command bypasses the credentialed path (e.g., via adversarial use of the `exec` tool), the child process environment is scrubbed of all credential keys before spawn — static deny list plus dynamic keys from every registered binary in the tenant. |
+| **Wrapper unwrap** | Shell wrappers (`sh -c`, `bash -c`, etc.) that attempt to evade binary path matching are blocked. GoClaw checks up to 3 levels of nesting; deeper chains are rejected as adversarial. |
+| **Subagent wiring** | Subagent `ExecTool`s use the same `SecureCLIStore` via `buildSubagentToolsRegistry`. Parent agents cannot bypass the gate by delegating exec to spawned subagents. |
+
+Security log events emitted by the grant gate:
+
+| Event | Meaning |
+|-------|---------|
+| `security.credentialed_binary_denied` | Agent attempted to run a binary it has no grant for |
+| `security.credentialed_binary_gate_error` | Grant lookup failed (DB error); exec denied |
+| `security.credentialed_binary_wrapper_too_deep` | Shell wrapper nesting exceeded 3 levels; rejected as adversarial |
+
+All three events include: `binary`, `wrapper`, `agent_id`, `tenant_id`, and `command` prefix fields.
+
 ### Shell output limit
 
 Host-executed commands have stdout and stderr capped at **1 MB** each. If a command exceeds this limit, output is truncated with a flag to prevent further writes. Sandboxed execution uses Docker container limits instead.
@@ -478,6 +500,9 @@ All security events log at `slog.Warn` with a `security.*` prefix:
 | `security.rate_limited` | Request rejected by rate limiter |
 | `security.cors_rejected` | WebSocket connection rejected by CORS policy |
 | `security.message_truncated` | Message truncated at `max_message_chars` |
+| `security.credentialed_binary_denied` | Agent attempted exec without a grant |
+| `security.credentialed_binary_gate_error` | Grant lookup failed; exec denied fail-closed |
+| `security.credentialed_binary_wrapper_too_deep` | Shell wrapper nesting > 3 levels rejected |
 
 Filter all security events:
 
@@ -509,4 +534,4 @@ journalctl -u goclaw | grep 'security\.'
 - [Docker Compose](./docker-compose.md) — deploying with security settings via compose overlays
 - [Database Setup](./database-setup.md) — PostgreSQL TLS and encrypted secret storage
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-09 -->
+<!-- goclaw-source: b9670555 | updated: 2026-04-19 -->

deployment/upgrading.md

@@ -208,10 +208,12 @@ Only do this if you understand what the failed migration was doing. When in doub
 
 ## Recent Migrations
 
-### v3 Migrations (037–044) — v2→v3 Upgrade Guide
+### v3 Migrations (037–055) — v2→v3 Upgrade Guide
 
 These migrations are applied automatically via `./goclaw upgrade`. They constitute the **v3 major release**. Read the breaking changes below before upgrading from v2.
 
+Migrations 048–055 introduce the vault media linking, vault scope consistency enforcement, agent hooks system (phases 1–4), and the `web_search` tenant-config migration. No manual steps are required — data hook 055 auto-migrates any API keys from legacy `config.json5 tools.web.*` and `builtin_tool_tenant_configs.settings` blobs to `config_secrets` on first startup.
+
 | Version | What changed |
 |---------|-------------|
 | 037 | **V3 memory evolution** — creates `episodic_summaries`, `agent_evolution_metrics`, `agent_evolution_suggestions`; adds `valid_from`/`valid_until` to KG tables; promotes 12 agent fields from `other_config` JSONB to dedicated columns |
@@ -247,6 +249,7 @@ These migrations are applied automatically via `./goclaw upgrade`. They constitu
 | Team workspace files: file tools auto-resolve | `read_file`/`write_file` targeting team workspace paths work directly | None — transparent |
 | Store unification (`internal/store/base/`) | Internal refactor only | None — no schema or config changes |
 | Gateway decomposed into modules | Internal refactor only | None |
+| `config.json5 tools.web.*` removed | `web_search` is now tenant-only; global path no longer parsed | Remove `tools.web.*` from `config.json5`; configure via **Config → Tools → Web Search** UI or `/v1/tools/builtin/web_search/tenant-config` API. API keys auto-migrated on startup (hook 055) |
 
 ### v2.x Migrations (024–032)
 
@@ -321,4 +324,4 @@ Before each upgrade, check the release notes for:
 - [Database Setup](/deploy-database) — PostgreSQL and pgvector setup
 - [Observability](/deploy-observability) — monitor your gateway post-upgrade
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-17 -->
+<!-- goclaw-source: b9670555 | updated: 2026-04-19 -->