Add known troubleshooting FAQ to README

README.md

@@ -186,6 +186,122 @@ When claiming success, distinguish these clearly:
 
 Do not collapse them into one claim.
 
+## Known troubleshooting FAQ
+
+### 1. `bootstrap_watchdog_bundle.sh` says `owner-reporting-system root missing`
+
+Cause:
+- an older bundle / script still expects the old live tree
+- or the host has not refreshed to the fixed portable bundle yet
+
+Fix:
+- refresh the live bundle:
+
+```bash
+./scripts/install_watchdog_bundle.sh --install-env-example --force
+./scripts/bootstrap_watchdog_bundle.sh
+```
+
+Expected fixed behavior:
+- bootstrap should validate the installed live bundle under `scripts/watchdog-b/`
+- it should **not** require a separate `owner-reporting-system/` live directory
+
+### 2. `can't open file .../scripts/scripts/owner_report_producer.py`
+
+Cause:
+- notifier is using the wrong base path for `owner_report_producer.py`
+
+Bad path:
+- `.../workspace/scripts/scripts/owner_report_producer.py`
+
+Correct path:
+- `.../workspace/scripts/watchdog-b/owner_report_producer.py`
+
+Fix:
+- update to a bundle that uses the live script directory correctly
+- then rerun:
+
+```bash
+./scripts/install_watchdog_bundle.sh --install-env-example --force
+cd ~/.openclaw/workspace/scripts/watchdog-b
+./verify_watchdog_b_e2e.sh
+```
+
+### 3. `Unknown agent id "main"`
+
+Cause:
+- stalled / idle path tried to nudge a hard-coded `main` agent id that does not exist on that host
+
+Fix:
+- either leave `WATCHDOG_B_MAIN_AGENT_ID` unset
+- or set it to a real host-local agent id
+
+Example:
+
+```bash
+WATCHDOG_B_MAIN_AGENT_ID=backend
+```
+
+If unset, the fixed bundle skips main-agent nudge instead of failing.
+
+### 4. `~/.config/openclaw/watchdog-b.env` does not exist
+
+Cause:
+- install copied the example, but the live env was never created
+
+Fix:
+
+```bash
+mkdir -p ~/.config/openclaw
+cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
+```
+
+Then edit at least:
+
+```bash
+WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
+```
+
+### 5. Bootstrap passes, but Discord delivery still fails
+
+Check these in order:
+
+1. `WATCHDOG_B_OWNER_REPORT_TARGET` is real, not placeholder
+2. Discord routing actually works on that host
+3. the send was only transport-accepted vs actually channel-readable
+4. `~/.clawteam/owner-reports/pending/` and `sent/` show the expected file movement
+5. `state/watchdog-b-verify-e2e/<run-id>/` contains the expected verification artifacts
+
+### 6. Timer is active, but owner-facing route still did not work
+
+This means:
+- `systemd --user` scheduling is alive
+- but the notification chain may still be broken
+
+Do not stop at `timer active` / `service success`.
+You still need to verify:
+- pending owner report creation
+- sent archive movement
+- Discord send success / message id
+- readback or human-visible evidence if claiming visible delivery
+
+### 7. How do I know whether I should rerun install or just rerun verify?
+
+Use this rule:
+
+- rerun **install** when scripts / env example / units may be stale or incomplete
+- rerun **bootstrap** when you need host-readiness validation
+- rerun **verify** when install is already in place and you need fresh E2E evidence
+
+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
+```
+
 ## Safety / cleanup rules
 
 - Do **not** delete `~/.clawteam/owner-reports/sent/` history unless explicitly asked