docs: sync with goclaw source changes a47d7f9f..c388364d (EN+VI+ZH) (#44)

- Fix REST API: remove Sessions (WS-only, fixes #618), add 33 missing endpoints,
  add MCP Bridge + Edition sections, fix Tenants PUT→PATCH
- Expand WebSocket-Only section with 15 method groups
- Update schema version 33→34, add subagent_tasks table (migration 034)
- Fix MCP hybrid search mode description (first 40 inline, rest deferred)
- Fix KG extraction temp 0.0→0.2, add 3 entity types, bidirectional traversal
- Add subagent enhancements: WaitAll, auto-retry, token tracking, SubagentDenyAlways
- Add /subagents commands to Telegram, attachment URL + stop-typing to Discord
- Add structured compaction summary and tool output cap to context-pruning
- Add provider_type immutability, schema normalization, reasoning effort controls
- Update installation for embedded Web UI (embedui build tag, 2-file compose)

Author: thieung

advanced/context-pruning.md

@@ -208,10 +208,22 @@ Pruning only acts on tool results. If long user messages or system prompt compon
 
 ---
 
+## Pipeline Improvements
+
+### Structured Compaction Summary
+
+When context is compacted, the summary now preserves key identifiers — agent IDs, task IDs, and session keys — in a structured format. This ensures that agents can continue referencing their active tasks and sessions after compaction without losing critical tracking context.
+
+### Tool Output Capping at Source
+
+Tool output is now capped at the source before being added to context. Rather than waiting for the pruning pipeline to trim oversized results after the fact, GoClaw limits tool output size at ingestion time. This reduces unnecessary memory pressure and makes the pruning pipeline more predictable.
+
+---
+
 ## What's Next
 
 - [Sessions & History](/sessions-and-history) — session compaction, history limits
 - [Memory System](/memory-system) — persistent memory across sessions
 - [Configuration Reference](/config-reference) — full agent config reference
 
-<!-- goclaw-source: e7afa832 | updated: 2026-03-30 -->
+<!-- goclaw-source: c388364d | updated: 2026-04-01 -->

advanced/knowledge-graph.md

@@ -17,7 +17,7 @@ The graph is scoped per agent and per user — each agent builds its own graph f
 
 After a conversation, GoClaw sends the text to an LLM with a structured extraction prompt. For long texts (over 12,000 characters), GoClaw splits the input into chunks, extracts from each, and merges results by deduplicating entities and relations. The LLM returns:
 
-- **Entities** — People, projects, tasks, events, concepts, locations, organizations
+- **Entities** — People, organizations, projects, products, technologies, tasks, events, documents, concepts, locations
 - **Relations** — Typed connections between entities (e.g., `works_on`, `reports_to`)
 
 Each entity and relation has a **confidence score** (0.0–1.0). Only items at or above the threshold (default **0.75**) are stored.
@@ -26,7 +26,7 @@ Each entity and relation has a **confidence score** (0.0–1.0). Only items at o
 - 3–15 entities per extraction, depending on text density
 - Entity IDs are lowercase with hyphens (e.g., `john-doe`, `project-alpha`)
 - Descriptions are one sentence maximum
-- Temperature 0.0 for deterministic results
+- Temperature 0.2 for consistent yet slightly flexible results
 
 ### Extract API
 
@@ -155,15 +155,15 @@ Marks the pair as not-duplicate — it won't appear in future review queues.
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `query` | string | Entity name, keyword, or `*` to list all (required) |
-| `entity_type` | string | Filter: `person`, `project`, `task`, `event`, `concept`, `location`, `organization` |
+| `entity_type` | string | Filter: `person`, `organization`, `project`, `product`, `technology`, `task`, `event`, `document`, `concept`, `location` |
 | `entity_id` | string | Start point for relationship traversal |
 | `max_depth` | int | Traversal depth (default 2, max 3) |
 
 ### 3-Tier Search Fallback
 
 The tool uses a 3-tier fallback strategy to ensure results are always returned:
 
-1. **Traversal** (when `entity_id` provided) — BFS outgoing traversal up to `max_depth`, returns up to 20 results with path info and relation types
+1. **Traversal** (when `entity_id` provided) — Bidirectional multi-hop traversal up to `max_depth`, returns up to 20 results with path info and relation types
 2. **Direct connections** (fallback if traversal returns nothing) — Bidirectional 1-hop relations, capped at 10
 3. **Text search** (fallback if no connections) — Full-text search on entity names/descriptions, returns up to 10 results with their relations (5 per entity)
 
@@ -181,7 +181,7 @@ query: "John"
 query: "*"
 ```
 
-**Traverse relationships** — Start from an entity and follow outgoing connections:
+**Traverse relationships** — Start from an entity and follow connections in both directions:
 ```
 query: "*"
 entity_id: "project-alpha"
@@ -266,12 +266,15 @@ Relations are directional: `source --relation_type--> target`. Deleting an entit
 | Type | Examples |
 |------|----------|
 | `person` | Team members, contacts, stakeholders |
-| `project` | Products, initiatives, codebases |
+| `organization` | Companies, teams, departments |
+| `project` | Initiatives, codebases, programs |
+| `product` | Software products, services, features |
+| `technology` | Languages, frameworks, platforms |
 | `task` | Action items, tickets, assignments |
 | `event` | Meetings, deadlines, milestones |
-| `concept` | Technologies, methodologies, ideas |
+| `document` | Reports, specs, wikis, runbooks |
+| `concept` | Methodologies, ideas, principles |
 | `location` | Offices, cities, regions |
-| `organization` | Companies, teams, departments |
 
 ---
 
@@ -378,4 +381,4 @@ An agent can then answer questions like *"Who is working on Project Alpha?"* by
 - [Memory System](/memory-system) — Vector-based long-term memory
 - [Sessions & History](/sessions-and-history) — Conversation storage
 
-<!-- goclaw-source: a47d7f9f | updated: 2026-03-31 -->
+<!-- goclaw-source: c388364d | updated: 2026-04-01 -->

advanced/mcp-integration.md

@@ -24,7 +24,7 @@ graph LR
     Registry --> Agent
 ```
 
-GoClaw runs a health-check loop every 30 seconds and reconnects with exponential backoff (initial delay 2 s, up to 10 attempts, capped at 60 s between retries) if a server goes down.
+GoClaw runs a health-check loop every 30 seconds. A server is only marked disconnected after **3 consecutive ping failures** — transient network blips do not trigger a reconnect. When a server does go down, GoClaw reconnects with exponential backoff (initial delay 2 s, up to 10 attempts, capped at 60 s between retries).
 
 ## Registering an MCP Server
 
@@ -103,13 +103,13 @@ If no prefix is set and a name collision is detected, GoClaw logs a warning (`mc
 
 ## Search Mode (large tool sets)
 
-When the total number of MCP tools across all servers exceeds **40**, GoClaw automatically enters **search mode**: tools are no longer registered inline in the tool registry. Instead, only the built-in `mcp_tool_search` tool is exposed. The agent uses `mcp_tool_search` to find and activate specific MCP tools on demand.
+When the total number of MCP tools across all servers exceeds **40**, GoClaw automatically enters **hybrid mode**: the first 40 tools remain registered inline in the tool registry, while the remainder are deferred to search mode. In hybrid mode, the built-in `mcp_tool_search` tool is also exposed so the agent can find and activate the deferred tools on demand.
 
 This keeps the tool list manageable when connecting many MCP servers. There is no configuration required — the switch is automatic.
 
 ### Lazy activation
 
-In search mode, if an agent calls a deferred MCP tool directly by name (without searching first), GoClaw **auto-activates** it. The tool is resolved from the MCP server, registered on the fly, and executed — no extra search step needed. This enables compatibility with agents that already know the tool name from prior context.
+In hybrid mode, if an agent calls a deferred MCP tool directly by name (without searching first), GoClaw **auto-activates** it. The tool is resolved from the MCP server, registered on the fly, and executed — no extra search step needed. This enables compatibility with agents that already know the tool name from prior context.
 
 ## Per-Agent Access Grants
 
@@ -297,4 +297,4 @@ Requires admin role. The credentials are encrypted at rest using `GOCLAW_ENCRYPT
 - [Custom Tools](../advanced/custom-tools.md) — build shell-backed tools without an MCP server
 - [Skills](../advanced/skills.md) — inject reusable knowledge into agent system prompts
 
-<!-- goclaw-source: e7afa832 | updated: 2026-03-30 -->
+<!-- goclaw-source: c388364d | updated: 2026-04-01 -->

channels/discord.md

@@ -76,15 +76,15 @@ In servers (channels), the bot requires being mentioned by default (`require_men
 
 ### Typing Indicator
 
-While the agent processes, a typing indicator is shown (9-second keepalive).
+While the agent processes, a typing indicator is shown (9-second keepalive). The typing indicator stops automatically after successful message delivery.
 
 ### Thread Support
 
 The bot automatically detects and responds in Discord threads. Responses stay in the same thread.
 
 ### Media from Replied-to Messages
 
-When a user replies to a message that contains media attachments, GoClaw extracts those attachments and includes them in the inbound message context. This lets the agent see and process media even when it was originally shared in a previous turn.
+When a user replies to a message that contains media attachments, GoClaw extracts those attachments and includes them in the inbound message context. This lets the agent see and process media even when it was originally shared in a previous turn. Attachment source URLs are preserved in media tags, so agents can reference the original Discord CDN URL.
 
 ### Group Media History
 
@@ -135,4 +135,4 @@ Per-guild/channel overrides are not yet supported in the Discord channel impleme
 - [Larksuite](/channel-feishu) — Larksuite integration with streaming cards
 - [Browser Pairing](/channel-browser-pairing) — Pairing flow
 
-<!-- goclaw-source: 120fc2d | updated: 2026-03-18 -->
+<!-- goclaw-source: c388364d | updated: 2026-04-01 -->

channels/telegram.md

@@ -243,6 +243,8 @@ Commands processed before message enrichment:
 | `/status` | Bot status + username | -- |
 | `/tasks` | Team task list | -- |
 | `/task_detail <id>` | View task | -- |
+| `/subagents` | List all active subagent tasks with status | -- |
+| `/subagent <id>` | Show detailed view of a subagent task from DB | -- |
 | `/addwriter` | Add group file writer | Writers only |
 | `/removewriter` | Remove group file writer | Writers only |
 | `/writers` | List group writers | -- |
@@ -291,4 +293,4 @@ Each Telegram instance maintains an isolated HTTP transport — no shared connec
 - [Browser Pairing](/channel-browser-pairing) — Pairing flow
 - [Sessions & History](/sessions-and-history) — Conversation history
 
-<!-- goclaw-source: a47d7f9f | updated: 2026-03-31 -->
+<!-- goclaw-source: c388364d | updated: 2026-04-01 -->

core-concepts/agents-explained.md

@@ -169,10 +169,45 @@ After each conversation run, GoClaw evaluates whether to compact session history
 
 Predefined agents have built-in protection against social engineering. If a user tries to convince the agent to ignore its SOUL.md or act outside its defined identity, the agent is designed to resist. Shared identity files are injected into the system prompt at a level that takes precedence over user instructions.
 
+## Subagent Enhancements
+
+When an agent spawns subagents via the `spawn` tool, the following capabilities apply:
+
+### Per-Edition Rate Limiting
+
+The `Edition` struct enforces two tenant-scoped limits on subagent usage:
+
+| Field | Description |
+|-------|-------------|
+| `MaxSubagentConcurrent` | Max number of subagents running in parallel per tenant |
+| `MaxSubagentDepth` | Max nesting depth — prevents unbounded delegation chains |
+
+These are set per edition and enforced at spawn time.
+
+### Token Cost Tracking
+
+Each subagent accumulates per-call input and output token counts. Totals are persisted in the database and included in announce messages, giving the parent agent full visibility into delegation cost.
+
+### WaitAll Orchestration
+
+`spawn(action=wait, timeout=N)` blocks the parent until all previously spawned children complete. This enables fan-out/fan-in patterns without polling.
+
+### Auto-Retry with Backoff
+
+Configurable `MaxRetries` (default `2`) with linear backoff handles transient LLM failures automatically. The parent is only notified on permanent failure after all retries are exhausted.
+
+### SubagentDenyAlways
+
+Subagents cannot spawn nested subagents — the `team_tasks` tool is blocked in subagent context. All delegation must originate from a top-level agent.
+
+### Producer-Consumer Announce Queue
+
+Staggered subagent results are queued and merged into a single LLM run announcement on the parent side. This reduces unnecessary parent wake-ups when multiple subagents finish at different times.
+
 ## What's Next
 
 - [Sessions and History](/sessions-and-history) — How conversations persist
 - [Tools Overview](/tools-overview) — What tools agents can use
 - [Memory System](/memory-system) — Long-term memory and search
 
-<!-- goclaw-source: c70e50c9 | updated: 2026-03-28 -->
+<!-- goclaw-source: c388364d | updated: 2026-04-01 -->

core-concepts/tools-overview.md

@@ -184,6 +184,25 @@ Admins can disable specific groups per agent:
 
 The `tools.exec_approval` setting adds an additional approval layer (`full`, `light`, or `none`).
 
+## spawn — Subagent Orchestration
+
+The `spawn` tool (part of `group:sessions`) creates and runs subagents. Key capabilities:
+
+| Capability | Detail |
+|-----------|--------|
+| **WaitAll** | `spawn(action=wait, timeout=N)` blocks the parent until all previously spawned children complete. Useful for fan-out/fan-in patterns. |
+| **Auto-retry** | Configurable `MaxRetries` (default `2`) with linear backoff on LLM failures. Transient errors are retried automatically. |
+| **Token tracking** | Each subagent accumulates per-call input/output token counts. Totals are included in announce messages so the parent can account for cost. |
+| **SubagentDenyAlways** | Subagents cannot spawn nested subagents — the `team_tasks` tool is blocked in subagent context. Prevents unbounded delegation chains. |
+| **Producer-consumer announce queue** | Staggered subagent results are queued and merged into a single LLM run announcement on the parent side, reducing unnecessary wake-ups. |
+
+```jsonc
+// Example: fan-out then wait
+spawn(action=start, prompt="Summarize part A")
+spawn(action=start, prompt="Summarize part B")
+spawn(action=wait, timeout=120)  // blocks until both finish
+```
+
 ## Session Tool Security
 
 Session tools (`sessions_list`, `sessions_history`, `sessions_send`) are hardened with fail-closed validation:
@@ -234,4 +253,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: 4d31fe0 | updated: 2026-03-28 -->
+<!-- goclaw-source: c388364d | updated: 2026-04-01 -->

deployment/upgrading.md

@@ -9,7 +9,7 @@ A GoClaw upgrade has two parts:
 1. **SQL migrations** — schema changes applied by `golang-migrate` (idempotent, versioned)
 2. **Data hooks** — optional Go-based data transformations that run after schema migrations (e.g. backfilling a new column)
 
-The `./goclaw upgrade` command handles both in the correct order. It is safe to run multiple times — it is fully idempotent. The current required schema version is **33**.
+The `./goclaw upgrade` command handles both in the correct order. It is safe to run multiple times — it is fully idempotent. The current required schema version is **34**.
 
 ```mermaid
 graph LR
@@ -226,6 +226,7 @@ These five migrations are auto-applied on startup when upgrading to v2.x. No man
 | 031 | Adds `tsv tsvector` generated column + GIN index to `kg_entities` for full-text search; creates `kg_dedup_candidates` table for entity deduplication review |
 | 032 | Creates `secure_cli_user_credentials` for per-user CLI credential injection; adds `contact_type` column to `channel_contacts` |
 | 033 | Cron payload columns | Promotes `stateless`, `deliver`, `deliver_channel`, `deliver_to`, `wake_heartbeat` from `payload` JSONB to dedicated columns on `cron_jobs` |
+| 034 | `subagent_tasks` | Subagent task persistence for DB-backed task tracking |
 
 ### Breaking Changes in v2.x
 
@@ -278,4 +279,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: a47d7f9f | updated: 2026-03-31 -->
+<!-- goclaw-source: c388364d | updated: 2026-04-01 -->