README: make troubleshooting FAQ fully bilingual (繁中/EN)

README.md

@@ -1,6 +1,6 @@
 # watchdog-discord-route
 
-> **繁體中文 / English bilingual README** (same file)
+> **繁體中文 / English bilingual README (same file)**
 
 這個 repo 是一個可攜式 OpenClaw skill bundle，用於打通並驗證 **watchdog-b → owner-facing Discord** 回報鏈路。
 
@@ -10,22 +10,24 @@ This repo is a portable OpenClaw skill bundle to deliver and verify the **watchd
 
 ## TL;DR 最短安裝（建議） / Quick Install (recommended)
 
-### 1) 安裝 bundle + 建立設定檔
+### 1) 安裝 bundle + 建立設定檔 / Install + create config
 
 ```bash
 ./scripts/install_watchdog_bundle.sh --install-env-example
 mkdir -p ~/.config/openclaw && cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
 ```
 
-### 2) 設定 Discord 目標（必要）
+### 2) 設定 Discord 目標（必要） / Set Discord target (required)
 
 把 `WATCHDOG_B_OWNER_REPORT_TARGET` 改成真的 channel id（不要留 placeholder）：
 
+Replace `WATCHDOG_B_OWNER_REPORT_TARGET` with a real channel id (do not keep the placeholder):
+
 ```bash
 sed -i 's#^WATCHDOG_B_OWNER_REPORT_TARGET=.*#WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID#' ~/.config/openclaw/watchdog-b.env
 ```
 
-### 3) Bootstrap（通過後才開 timer）
+### 3) Bootstrap（通過後才開 timer） / Bootstrap (enable timer only after pass)
 
 ```bash
 ./scripts/bootstrap_watchdog_bundle.sh
@@ -33,7 +35,7 @@ systemctl --user daemon-reload
 systemctl --user enable --now openclaw-watchdog-b.timer
 ```
 
-### 4)（可選）跑 E2E 驗證
+### 4)（可選）跑 E2E 驗證 / (Optional) run E2E verification
 
 ```bash
 cd ~/.openclaw/workspace/scripts/watchdog-b
@@ -59,7 +61,9 @@ flowchart TD
 
 ---
 
-## 這是用來做什麼的（中文）
+## 這是用來做什麼的 / What this is for
+
+### 中文
 
 用這個 bundle 來：
 
@@ -68,67 +72,45 @@ flowchart TD
 - 修復 `owner_report_*` routing 路徑錯誤
 - 刷新 live bundle（`~/.openclaw/workspace/scripts/watchdog-b/`）
 
-### 包含內容
+### English
-
-- Skill 文件：`SKILL.md`
-- Scripts：`scripts/*.sh`, `scripts/*.py`, `scripts/watchdog-b.env.example`
-- systemd user units：`scripts/openclaw-watchdog-b.service`, `scripts/openclaw-watchdog-b.timer`
-- References：`references/*.md`
-
-### 重要設定（單一來源）
-
-設定檔：
-- `~/.config/openclaw/watchdog-b.env`
-
-最低必填：
-
-```bash
-WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
-```
-
-可選（只有 host 上真的存在該 agent id 才設）：
-
-```bash
-WATCHDOG_B_MAIN_AGENT_ID=backend
-```
-
-> 未設定時，stalled/idle 的 main-agent nudge 會被 skip，避免因 `Unknown agent id` 直接 fail。
-
----
-
-## What this is for (English)
 
 Use this bundle to:
 
 - deploy watchdog-b on a new OpenClaw host (via `systemd --user timer`)
-- verify the owner-facing Discord delivery end-to-end
+- verify owner-facing Discord delivery end-to-end
 - fix broken `owner_report_*` routing / path issues
 - refresh the live install under `~/.openclaw/workspace/scripts/watchdog-b/`
 
-### Included
+---
+
+## 包含內容 / Included
 
 - Skill doc: `SKILL.md`
 - Scripts: `scripts/*.sh`, `scripts/*.py`, `scripts/watchdog-b.env.example`
 - systemd user units: `scripts/openclaw-watchdog-b.service`, `scripts/openclaw-watchdog-b.timer`
 - References: `references/*.md`
 
-### Single source of config
+---
 
-Config file:
+## 重要設定（單一來源） / Single source of config
+
+設定檔 / Config file:
 - `~/.config/openclaw/watchdog-b.env`
 
-Minimum required:
+最低必填 / Minimum required:
 
 ```bash
 WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
 ```
 
-Optional (only set if the agent id exists on the host):
+可選（只有 host 上真的存在該 agent id 才設）/ Optional (only set if the agent id exists on the host):
 
 ```bash
 WATCHDOG_B_MAIN_AGENT_ID=backend
 ```
 
+未設定時，stalled/idle 的 main-agent nudge 會被 skip，避免因 `Unknown agent id` 直接 fail。
+
 If unset, stalled/idle main-agent nudge is skipped to avoid `Unknown agent id` failures.
 
 ---
@@ -141,39 +123,228 @@ If unset, stalled/idle main-agent nudge is skipped to avoid `Unknown agent id` f
 - **channel-readable**：可以從 target channel 讀回
 - **human-confirmed**：Eric 確認在 Discord 看到
 
-最低 E2E 成功訊號（verify script 期待的）：
+Do not collapse “success” into one claim:
 
-- `~/.clawteam/owner-reports/pending/` 產生 pending
+- **transport accepted**: send returned success / message id
-- pending 進入 `~/.clawteam/owner-reports/sent/`
+- **channel-readable**: message can be read back from the target channel
+- **human-confirmed**: Eric confirmed it is visible in Discord
+
+最低 E2E 成功訊號 / Minimum E2E success signals:
+
+- `~/.clawteam/owner-reports/pending/` pending created
+- pending moved into `~/.clawteam/owner-reports/sent/`
 - Discord send success / message id
-- artifacts 寫入 `state/watchdog-b-verify-e2e/<run-id>/`
+- artifacts written under `state/watchdog-b-verify-e2e/<run-id>/`
 
 ---
 
-## 已知故障排查 FAQ / Troubleshooting FAQ
+## 已知故障排查 FAQ（雙語對照） / Troubleshooting FAQ (bilingual)
 
-### Q1: `.../scripts/scripts/owner_report_producer.py` 找不到
+### Q1（中文）
-A: 代表路徑基準錯了。正確應該在 `.../scripts/watchdog-b/owner_report_producer.py`。
+**錯誤：** `can't open file .../scripts/scripts/owner_report_producer.py`
 
-修正：
+**原因：** notifier 使用了錯誤的 base path。
+
+**正確路徑：** `.../scripts/watchdog-b/owner_report_producer.py`
+
+**處理：** 先強制刷新 bundle，再跑 bootstrap：
 
 ```bash
 ./scripts/install_watchdog_bundle.sh --install-env-example --force
 ./scripts/bootstrap_watchdog_bundle.sh
 ```
 
-### Q2: `Unknown agent id "main"`
+### Q1 (English)
-A: 不要硬編碼 `main`。改用 `WATCHDOG_B_MAIN_AGENT_ID`（或不設讓它 skip）。
+**Error:** `can't open file .../scripts/scripts/owner_report_producer.py`
 
-### Q3: timer active 但 owner-facing 沒送到
+**Cause:** the notifier is using a wrong base path.
-A: timer 只代表排程活著，不代表鏈路通。請跑：
+
+**Correct path:** `.../scripts/watchdog-b/owner_report_producer.py`
+
+**Fix:** force refresh the bundle, then rerun bootstrap:
+
+```bash
+./scripts/install_watchdog_bundle.sh --install-env-example --force
+./scripts/bootstrap_watchdog_bundle.sh
+```
+
+---
+
+### Q2（中文）
+**錯誤：** `bootstrap_watchdog_bundle.sh` 說 `owner-reporting-system root missing`
+
+**原因：** host 上仍是舊版 bootstrap（期待舊的 live tree）。
+
+**處理：** 刷新 bundle 之後再 bootstrap：
+
+```bash
+./scripts/install_watchdog_bundle.sh --install-env-example --force
+./scripts/bootstrap_watchdog_bundle.sh
+```
+
+**期待行為：** bootstrap 只檢查 `scripts/watchdog-b/*.py`，不再要求獨立的 `owner-reporting-system/` 目錄。
+
+### Q2 (English)
+**Error:** `bootstrap_watchdog_bundle.sh` says `owner-reporting-system root missing`
+
+**Cause:** you are still running an older bootstrap that expects the legacy live tree.
+
+**Fix:** refresh the bundle, then rerun bootstrap:
+
+```bash
+./scripts/install_watchdog_bundle.sh --install-env-example --force
+./scripts/bootstrap_watchdog_bundle.sh
+```
+
+**Expected behavior:** bootstrap validates only the installed live bundle under `scripts/watchdog-b/*.py` and no longer requires a separate `owner-reporting-system/` directory.
+
+---
+
+### Q3（中文）
+**錯誤：** `Unknown agent id "main"`
+
+**原因：** 某些路徑（stalled/idle）嘗試 nudge hard-coded `main`，但該 host 上不存在。
+
+**處理：**
+- 最保守：不要設定 `WATCHDOG_B_MAIN_AGENT_ID`（讓它自動 skip）
+- 或：設定為 host 上真的存在的 agent id（例如 `backend`）
+
+```bash
+WATCHDOG_B_MAIN_AGENT_ID=backend
+```
+
+### Q3 (English)
+**Error:** `Unknown agent id "main"`
+
+**Cause:** stalled/idle path attempted to nudge a hard-coded `main`, which does not exist on this host.
+
+**Fix:**
+- safest: leave `WATCHDOG_B_MAIN_AGENT_ID` unset (it will be skipped)
+- or set it to a real host-local agent id (e.g. `backend`)
+
+```bash
+WATCHDOG_B_MAIN_AGENT_ID=backend
+```
+
+---
+
+### Q4（中文）
+**問題：** `~/.config/openclaw/watchdog-b.env` 不存在
+
+**原因：** 只有產生 example，但沒有建立 live env。
+
+**處理：**
+
+```bash
+mkdir -p ~/.config/openclaw
+cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
+```
+
+然後至少設定：
+
+```bash
+WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
+```
+
+### Q4 (English)
+**Problem:** `~/.config/openclaw/watchdog-b.env` does not exist
+
+**Cause:** the example exists, but the live env file was never created.
+
+**Fix:**
+
+```bash
+mkdir -p ~/.config/openclaw
+cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
+```
+
+Then set at least:
+
+```bash
+WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
+```
+
+---
+
+### Q5（中文）
+**問題：** bootstrap 通過，但 Discord 還是沒送到
+
+**檢查順序：**
+1. `WATCHDOG_B_OWNER_REPORT_TARGET` 是否真實（不是 placeholder）
+2. `pending/` 是否有檔、是否有進 `sent/`
+3. send 是否只有 transport accepted（有 message id）但其實你看不到（非 channel-readable）
+4. `state/watchdog-b-verify-e2e/<run-id>/` artifacts 是否齊全
+
+**建議動作：**
 
 ```bash
 cd ~/.openclaw/workspace/scripts/watchdog-b
 ./verify_watchdog_b_e2e.sh
 ```
 
-並檢查 `pending/`→`sent/` 移動與 send 回傳。
+### Q5 (English)
+**Problem:** bootstrap passes, but Discord delivery still fails
+
+**Check in order:**
+1. `WATCHDOG_B_OWNER_REPORT_TARGET` is real (not placeholder)
+2. a pending file exists and moves from `pending/` to `sent/`
+3. distinguish transport accepted (message id) vs channel-readable visibility
+4. verify artifacts exist under `state/watchdog-b-verify-e2e/<run-id>/`
+
+**Suggested action:**
+
+```bash
+cd ~/.openclaw/workspace/scripts/watchdog-b
+./verify_watchdog_b_e2e.sh
+```
+
+---
+
+### Q6（中文）
+**問題：** timer active / service success，但 owner-facing route 仍不通
+
+**解釋：** timer 代表排程活著，不代表鏈路通。仍需以 verify/evidence 為準。
+
+### Q6 (English)
+**Problem:** timer is active / service is successful, but owner-facing route still doesn’t work
+
+**Explanation:** a live scheduler does not guarantee the delivery chain works. Verify using E2E evidence.
+
+---
+
+### Q7（中文）
+**問題：** 我該 rerun install 還是只跑 verify？
+
+**規則：**
+- scripts/env/units 可能舊了 → rerun **install**
+- 要做 host readiness 檢查 → rerun **bootstrap**
+- 安裝都在，只需要新證據 → rerun **verify**
+
+**實務順序：**
+
+```bash
+./scripts/install_watchdog_bundle.sh --install-env-example --force
+./scripts/bootstrap_watchdog_bundle.sh
+cd ~/.openclaw/workspace/scripts/watchdog-b
+./verify_watchdog_b_e2e.sh
+```
+
+### Q7 (English)
+**Problem:** should I rerun install or just rerun verify?
+
+**Rule:**
+- scripts/env/units may be stale → rerun **install**
+- need host readiness validation → rerun **bootstrap**
+- install is fine, need fresh evidence → rerun **verify**
+
+**Practical order:**
+
+```bash
+./scripts/install_watchdog_bundle.sh --install-env-example --force
+./scripts/bootstrap_watchdog_bundle.sh
+cd ~/.openclaw/workspace/scripts/watchdog-b
+./verify_watchdog_b_e2e.sh
+```
 
 ---