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

Author: thieung

advanced/media-generation.md

@@ -41,13 +41,23 @@ Generated files are verified after writing — if the file doesn't exist on disk
 
 **Default provider chain:** Gemini → MiniMax → OpenRouter
 
-**Default models:** Gemini `veo-3.0-generate-preview`, MiniMax `MiniMax-Hailuo-2.3`, OpenRouter `google/veo-3.0-generate-preview`
+**Default models:** Gemini `veo-3.1-lite-generate-preview`, MiniMax `MiniMax-Hailuo-2.3`, OpenRouter `google/veo-3.1-lite-generate-preview`
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `prompt` | string | required | Text description of the video |
 | `duration` | int | `8` | Duration in seconds: `4`, `6`, or `8` |
 | `aspect_ratio` | string | `16:9` | `16:9` or `9:16` |
+| `image_path` | string | — | Path to a workspace image to use as starting frame (image-to-video). Omit for text-to-video. Supported formats: PNG, JPEG, WebP, GIF. Max 20 MB. |
+| `filename_hint` | string | — | Short descriptive filename without extension (e.g. `cat-playing-piano`) |
+
+### Image-to-Video
+
+Provide an `image_path` to generate a video starting from a reference image. The image is encoded as base64 and sent to the provider. When using image-to-video mode, duration is fixed at **8 seconds** (API constraint).
+
+**Example agent prompt:** *"Animate this product photo with a slow zoom and subtle lighting changes"* (with `image_path` pointing to a workspace image)
+
+> **Note:** Not all providers support image-to-video. Gemini (Veo 3.1 Lite) supports it natively. Unsupported providers in the chain are skipped automatically.
 
 Video generation is slow — both Gemini and MiniMax poll up to ~6 minutes. The timeout per provider defaults to 120 seconds but can be increased via chain settings.
 
@@ -182,4 +192,4 @@ Downloaded media files are capped at **200 MB**. Files exceeding this limit will
 - [Custom Tools](/custom-tools) — Build your own tools
 - [Provider Overview](/providers-overview) — Configure API keys
 
-<!-- goclaw-source: 120fc2d | updated: 2026-03-18 -->
+<!-- goclaw-source: c5bfbc96 | updated: 2026-04-02 -->

advanced/scheduling-cron.md

@@ -101,7 +101,7 @@ goclaw cron delete <jobId>
 | `schedule.atMs` | int64 | Unix timestamp in ms (for `at`) |
 | `schedule.everyMs` | int64 | Interval in ms (for `every`) |
 | `schedule.expr` | string | 5-field cron expression (for `cron`) |
-| `schedule.tz` | string | IANA timezone for cron expressions; omit to use the gateway default timezone |
+| `schedule.tz` | string | IANA timezone — applies to **all** schedule kinds (`at`, `every`, `cron`), not just cron expressions. Omit to use the gateway default timezone |
 | `message` | string | Text the agent receives as its input |
 | `stateless` | bool | Run without session history — saves tokens for simple scheduled tasks. Default `false` |
 | `deliver` | bool | `true` = deliver result to a channel; `false` = agent processes silently. Auto-defaults to `true` when the job is created from a real channel (Telegram, etc.) |
@@ -318,4 +318,4 @@ When a session's conversation history exceeds **60% of the context window**, the
 - [Skills](/skills) — inject domain knowledge so scheduled agents are more effective
 - [Sandbox](/sandbox) — isolate code execution during scheduled agent runs
 
-<!-- goclaw-source: a47d7f9f | updated: 2026-03-31 -->
+<!-- goclaw-source: c5bfbc96 | updated: 2026-04-02 -->

channels/overview.md

@@ -95,10 +95,49 @@ The `media_max_bytes` config field enforces a per-channel limit on outbound medi
 | **Media** | Photos, voice, files | Files, embeds | Files (20MB) | Images, files (30MB) | Images (5MB) | -- | JSON |
 | **Reply media** | Yes | Yes | -- | Yes | -- | -- | -- |
 | **Rich format** | HTML | Markdown | mrkdwn | Cards | Plain text | Plain text | Plain |
+| **Thread support** | Yes | -- | -- | -- | -- | -- | -- |
 | **Reactions** | Yes | -- | Yes | Yes | -- | -- | -- |
 | **Pairing** | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
 | **Message limit** | 4,096 | 2,000 | 4,000 | 4,000 | 2,000 | 2,000 | N/A |
 
+## Channel Health Diagnostics
+
+GoClaw tracks the runtime health of each channel instance and provides actionable diagnostics when issues occur. Health state is exposed via the `channels.status` WebSocket method and the dashboard overview page.
+
+### Health States
+
+| State | Meaning |
+|-------|---------|
+| `registered` | Channel is configured but not yet started |
+| `starting` | Channel is initializing |
+| `healthy` | Running normally |
+| `degraded` | Running with issues |
+| `failed` | Stopped due to an error |
+| `stopped` | Manually stopped |
+
+### Failure Classification
+
+When a channel fails, GoClaw classifies the error into one of four categories:
+
+| Kind | Typical Cause | Remediation |
+|------|---------------|-------------|
+| `auth` | Invalid or expired token/secret | Review credentials or re-authenticate |
+| `config` | Missing required settings, invalid proxy | Complete required fields in channel settings |
+| `network` | Timeout, connection refused, DNS failure | Check upstream service reachability and proxy settings |
+| `unknown` | Unrecognized error | Inspect server logs for the full error |
+
+Each failure includes a **remediation hint** — a short operator instruction pointing to the specific UI surface (credentials panel, advanced settings, or details page) where the issue can be resolved. The dashboard surfaces these hints directly on channel cards.
+
+### Health Tracking
+
+The health system tracks failure history per channel:
+- **Consecutive failures** — resets when the channel recovers
+- **Total failure count** — lifetime counter
+- **First/last failure timestamps** — for diagnosing intermittent issues
+- **Last healthy timestamp** — when the channel was last operational
+
+---
+
 ## Implementation Checklist
 
 When adding a new channel, implement these methods:
@@ -156,4 +195,4 @@ Channels may enforce per-user rate limits. Configure via channel settings or imp
 - [WebSocket](/channel-websocket) — Direct agent API via WS
 - [Browser Pairing](/channel-browser-pairing) — 8-char code pairing flow
 
-<!-- goclaw-source: 120fc2d | updated: 2026-03-19 -->
+<!-- goclaw-source: c5bfbc96 | updated: 2026-04-02 -->

channels/telegram.md

@@ -223,11 +223,25 @@ Disabled by default. When enabled with `reasoning_stream: true` (default), reaso
 
 Show emoji status on user messages. Set `reaction_level`:
 
-> Typing indicator reactions are now handled with better error recovery — invalid reaction types are caught gracefully instead of causing errors.
-
-- `off` — No reactions
-- `minimal` — Only ⏳ (thinking)
-- `full` — ⏳ (thinking) → 🛠️ (tool) → ✅ (done) or ❌ (error)
+- `off` — No reactions (default)
+- `minimal` — Only terminal states (done/error)
+- `full` — All status transitions with debouncing and stall detection
+
+**Status → Emoji mapping** (use `/reactions` in chat to see this legend):
+
+| Status | Emoji | Description |
+|--------|-------|-------------|
+| queued | 👀 | Waiting to process |
+| thinking | 🤔 | Processing your request |
+| tool | ✍ | Executing a tool |
+| coding | 👨‍💻 | Running code |
+| web | ⚡ | Browsing / API call |
+| done | 👍 | Completed |
+| error | 💔 | Something went wrong |
+| stallSoft | 🥱 | No activity for 10s |
+| stallHard | 😨 | No activity for 30s |
+
+Each status has fallback emoji variants in case the primary emoji is restricted by the chat's allowed reactions. Intermediate states (thinking, tool, etc.) are debounced at 700ms to avoid reaction spam.
 
 ### Bot Commands
 
@@ -245,6 +259,7 @@ Commands processed before message enrichment:
 | `/task_detail <id>` | View task | -- |
 | `/subagents` | List all active subagent tasks with status | -- |
 | `/subagent <id>` | Show detailed view of a subagent task from DB | -- |
+| `/reactions` | Show reaction emoji legend (status → emoji mapping) | -- |
 | `/addwriter` | Add group file writer | Writers only |
 | `/removewriter` | Remove group file writer | Writers only |
 | `/writers` | List group writers | -- |
@@ -293,4 +308,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: c388364d | updated: 2026-04-01 -->
+<!-- goclaw-source: c5bfbc96 | updated: 2026-04-02 -->

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 **34**.
+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 **35**.
 
 ```mermaid
 graph LR
@@ -227,6 +227,7 @@ These five migrations are auto-applied on startup when upgrading to v2.x. No man
 | 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 |
+| 035 | `contact_thread_id` | Adds `thread_id VARCHAR(100)` and `thread_type VARCHAR(20)` to `channel_contacts`; cleans up `sender_id` by stripping `\|username` suffixes; rebuilds unique index as `(tenant_id, channel_type, sender_id, COALESCE(thread_id, ''))` |
 
 ### Breaking Changes in v2.x
 
@@ -279,4 +280,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: c388364d | updated: 2026-04-01 -->
+<!-- goclaw-source: c5bfbc96 | updated: 2026-04-02 -->

reference/database-schema.md

@@ -645,11 +645,13 @@ Global unified contact directory auto-collected from all channel interactions. N
 | `avatar_url` | TEXT | | Profile image URL |
 | `peer_kind` | VARCHAR(20) | | e.g. `user`, `bot`, `group` |
 | `metadata` | JSONB | DEFAULT `{}` | Extra platform-specific data |
+| `thread_id` | VARCHAR(100) | | Thread/topic identifier within a chat (migration 035) |
+| `thread_type` | VARCHAR(20) | | Thread type classifier (migration 035) |
 | `merged_id` | UUID | | Canonical contact after de-duplication |
 | `first_seen_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
 | `last_seen_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
 
-**Unique:** `(channel_type, sender_id)`
+**Unique:** `(tenant_id, channel_type, sender_id, COALESCE(thread_id, ''))`
 
 **Indexes:** `channel_instance` (partial non-null), `merged_id` (partial non-null), `(display_name, username)`
 
@@ -993,6 +995,7 @@ Centralized key-value store for per-tenant system settings. Falls back to master
 | 32 | Creates `secure_cli_user_credentials` for per-user credential injection (mirrors `mcp_user_credentials` pattern); adds `contact_type VARCHAR(20) DEFAULT 'user'` to `channel_contacts` |
 | 33 | Promotes `stateless`, `deliver`, `deliver_channel`, `deliver_to`, `wake_heartbeat` from `payload` JSONB to dedicated columns on `cron_jobs` |
 | 34 | `subagent_tasks` — subagent task persistence for DB-backed task lifecycle tracking, cost attribution, and restart recovery |
+| 35 | `contact_thread_id` — adds `thread_id` and `thread_type` to `channel_contacts`; cleans `sender_id` format; rebuilds unique index to include thread scope |
 
 ---
 
@@ -1085,4 +1088,4 @@ Persists subagent task lifecycle for audit trail, cost attribution, and restart
 - [Config Reference](/config-reference) — how database config maps to `config.json`
 - [Glossary](/glossary) — Session, Compaction, Lane, and other key terms
 
-<!-- goclaw-source: c388364d | updated: 2026-04-01 -->
+<!-- goclaw-source: c5bfbc96 | updated: 2026-04-02 -->