xymeow · xymeow · Jul 11, 2026 · Jul 11, 2026
diff --git a/README.md b/README.md
@@ -62,6 +62,26 @@ See [Configuration and operation](docs/configuration.md) for daily prompts,
 language, support and position behavior, commentary styles, mute controls, and
 standalone-market details.
 
+## System design
+
+![Stack-chan Matchday system design](docs/images/system-design.png)
+
+Kalshi and ESPN are read-only inputs to the Python watcher. The watcher
+discovers fixtures, validates market pairing, parses events into shared facts,
+renders the selected commentary style, and sends options, acknowledgements,
+display, speech, and reaction commands to the Matchday mod.
+
+The mod hosts the phone setup page, forwards pending settings, and plays the
+resulting commands. Commentary styling does not modify the official host
+firmware or TTS module. Optional speech uses a LAN `/say?text=...` service that
+returns a 24 kHz mono 16-bit PCM WAV response.
+
+The device stores a pending phone selection until the watcher validates it,
+atomically updates the local JSON configuration, hot-reloads, and acknowledges
+the device. The phone, watcher, TTS server, and Stack-chan must remain on the
+same trusted LAN; the watcher-hosted `:8788/setup` page is a local fallback,
+not the primary QR flow.
+
 ## Features
 
 - Persistent two-team probability bar, flags, and a bottom market ticker.
@@ -72,28 +92,27 @@ standalone-market details.
 - Separate support and position perspectives, including explicit conflict and
   uncertain-event wording.
 - Phone-based match setup with live Chinese/English switching and hot reload.
+- Automatic fixture discovery, adaptive polling, quiet hours, and standalone
+  market tracking when no match is available.
 - Optional LAN TTS; visual feedback and tone patterns still work without it.
+- A global ESPN athlete-ID catalog with manually verified Chinese names and
+  nicknames.
 
 ## Quick start
 
-### Already installed
+### Daily start
 
-Update the repository and restart the watcher. Support/position wording,
-position-based market selection, and the global player catalog are watcher-only
-changes; an installed 1.5.0 mod and the official host can stay in place.
+From the repository root of an existing, configured checkout, keep the watcher
+computer awake and run:
 
 ```sh
-export MATCHDAY_DIR="$HOME/src/stackchan-matchday"
-cd "$MATCHDAY_DIR"
-git pull
 python3 tools/stackchan_kalshi_watch.py \
   --config config/kalshi_watchlist.json --watch
 ```
 
-Deploy `config/espn_player_catalog.json` with the watcher checkout. For exact
-upgrade boundaries, see the bilingual
-[Matchday MOD 1.5.0 notes](docs/releases/1.5.0.md) and
-[1.4.0 commentary-style notes](docs/releases/1.4.0.md).
+Daily startup does not require cloning, pulling, or reflashing. If speech is
+enabled, also start the optional LAN TTS service described in
+[Getting started](docs/getting-started.md).
 
 ### First installation
 
@@ -107,32 +126,14 @@ revision, one-time host preparation, QR generation, mod installation, watcher
 configuration, TTS, and verification. Host partition and optional CJK-font
 patch details live in [host/README.md](host/README.md).
 
-After installation, starting the watcher normally requires only:
-
-```sh
-python3 tools/stackchan_kalshi_watch.py \
-  --config config/kalshi_watchlist.json --watch
-```
-
-## System design
-
-![Stack-chan Matchday system design](docs/images/system-design.png)
-
-Kalshi and ESPN are read-only inputs to the Python watcher. The watcher
-discovers fixtures, validates market pairing, parses events into shared facts,
-renders the selected commentary style, and sends options, acknowledgements,
-display, speech, and reaction commands to the Matchday mod.
-
-The mod hosts the phone setup page, forwards pending settings, and plays the
-resulting commands. Commentary styling does not modify the official host
-firmware or TTS module. Optional speech uses a LAN `/say?text=...` service that
-returns a 24 kHz mono 16-bit PCM WAV response.
+### Upgrade
 
-The device stores a pending phone selection until the watcher validates it,
-atomically updates the local JSON configuration, hot-reloads, and acknowledges
-the device. The phone, watcher, TTS server, and Stack-chan must remain on the
-same trusted LAN; the watcher-hosted `:8788/setup` page is a local fallback,
-not the primary QR flow.
+Before updating, open the [release notes directory](docs/releases/) and check
+which boundary changed: watcher, Matchday mod, or official host. Preserve the
+local watcher configuration and update only the affected layer. Watcher-only
+changes normally need a repository update and watcher restart, while mod or
+host changes must follow the version-specific build and flash instructions.
+The currently documented device release is [Matchday Mod 1.5.0](docs/releases/1.5.0.md).
 
 ## Documentation
 
@@ -144,8 +145,8 @@ not the primary QR flow.
 | [Development](docs/development.md) | Repository map, tests, archive builds, and replay tooling |
 | [Host preparation](host/README.md) | Partition and optional CJK-font patches |
 | [Commentary styles PRD](docs/commentary-styles-prd.md) | Product rules and implementation contract |
-| [Release notes](docs/releases/1.5.0.md) | Version-specific upgrade boundaries |
-| [GitHub Wiki](https://github.com/xymeow/stackchan-matchday/wiki) | Human- and agent-friendly navigation, FAQ, and field debugging |
+| [Release notes](docs/releases/) | Version-specific changes and upgrade boundaries |
+| [Troubleshooting Wiki](https://github.com/xymeow/stackchan-matchday/wiki/Troubleshooting) | FAQ, networking checks, and field debugging |
 
 English guides link to their Chinese counterparts at the top of each page.
 Repository documentation is the versioned source of truth; the Wiki is the

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -71,6 +71,29 @@ watcher，可把 CoreS3 机器人变成世界杯陪看搭子：屏幕持续显
   </tr>
 </table>
 
+## 系统设计
+
+![Stack-chan Matchday 系统设计](docs/images/system-design.png)
+
+Kalshi 和 ESPN 只作为 Python watcher 的只读数据源。watcher 负责解析统一的比赛
+事实、生成三档文案，并向设备发送显示、语音和动作命令；Mod 负责手机设置转发与设备
+反馈，不修改官方 host runtime 或 TTS 模块。
+
+手机访问 Stack-chan 自己的 `/setup` 页面。设备先保存待处理选择，watcher 再完成
+校验、原子更新本地 JSON、热重载并确认设备。可选的局域网 TTS 接收设备发出的
+`/say?text=...` 请求，返回 24 kHz、单声道、16-bit PCM WAV。
+
+watcher 电脑上的 `:8788/setup` 只是默认绑定回环地址的本机管理后备页，不是设备
+二维码的主流程。
+
+```text
+Kalshi + ESPN ──只读──> Python watcher ──HTTP──> Stack-chan Matchday Mod
+                              │                         │
+                              └── 配置校验与确认 <── 手机 /setup
+                                                        │
+                                                        └── 可选局域网 TTS
+```
+
 ## 功能
 
 - 常驻双方概率条、球队旗帜与底部市场 ticker。
@@ -84,65 +107,38 @@ watcher，可把 CoreS3 机器人变成世界杯陪看搭子：屏幕持续显
 
 ## 快速开始
 
-### 环境要求
+### 日常启动
 
-- 基于 CoreS3、配备 16 MB Flash 的 Stack-chan，以及一根可传数据的 USB 线。
-- Git、Python 3.10+、Node.js 20+、npm、`xz`、Moddable SDK 与 ESP-IDF。
-- 手机、watcher 电脑和 Stack-chan 位于同一个可信局域网。
-- 只有生成设备专属二维码时需要 `qrencode`；仓库自带的 TTS 服务仅支持 macOS。
-
-首次安装需要准备并烧录一次官方 host、生成设备二维码、安装 Matchday Mod，再配置
-watcher。完整、可复现的命令见[安装与升级](docs/getting-started.zh-CN.md)；host 的分区
-和可选 CJK 字体步骤以 [host/README.zh-CN.md](host/README.zh-CN.md) 为准。
-
-### 首次安装路径
-
-1. 在固定的上游 Stack-chan commit 上应用 `xs` 分区补丁；中文界面再加入 CJK 字体，
-   然后烧录一次 host。
-2. 给设备保留稳定的局域网地址，生成不超过 168 px 的设置二维码，构建并安装 Mod。
-3. 复制示例 watcher 配置，填写设备地址并启动 `--watch`。
-4. 从设备扫码选择比赛；需要语音时，再启动可选的 macOS 局域网 TTS。
-
-这四步的版本绑定命令只在详细文档中维护，避免 README 与实际分区、构建参数漂移。
-
-已有可用的 host 与 Mod 时，启动 watcher 的最短路径是：
+已有仓库和有效配置时，在仓库根目录保持 watcher 电脑唤醒并运行：
 
 ```sh
-git clone https://github.com/xymeow/stackchan-matchday.git
-cd stackchan-matchday
-cp config/kalshi_watchlist.example.json config/kalshi_watchlist.json
-# 编辑 stackchan_host，然后：
 python3 tools/stackchan_kalshi_watch.py \
   --config config/kalshi_watchlist.json --watch
 ```
 
-示例 ticker 是占位值；从手机设置页选择真实比赛后，watcher 会校验 ESPN 与 Kalshi
-的双方匹配并原子更新配置。旧版升级前请查看
-[Matchday Mod 1.5.0 说明](docs/releases/1.5.0.md)及[全部版本说明](docs/releases/)；
-watcher-only 更新不应触发不必要的刷机。
+日常启动不需要 `git pull`、重新克隆或刷机。需要语音时，再启动
+[安装与升级](docs/getting-started.zh-CN.md)中说明的可选局域网 TTS 服务。
 
-## 系统设计
+### 首次安装
 
-![Stack-chan Matchday 系统设计](docs/images/system-design.png)
+- 基于 CoreS3、配备 16 MB Flash 的 Stack-chan，以及一根可传数据的 USB 线。
+- Git、Python 3.10+、Node.js 20+、npm、`xz`、Moddable SDK 与 ESP-IDF。
+- 手机、watcher 电脑和 Stack-chan 位于同一个可信局域网。
+- 只有生成设备专属二维码时需要 `qrencode`；仓库自带的 TTS 服务仅支持 macOS。
 
-Kalshi 和 ESPN 只作为 Python watcher 的只读数据源。watcher 负责解析统一的比赛
-事实、生成三档文案，并向设备发送显示、语音和动作命令；Mod 负责手机设置转发与设备
-反馈，不修改官方 host runtime 或 TTS 模块。
+首次安装需要准备并烧录一次官方 host、生成设备二维码、安装 Matchday Mod，再配置
+watcher。完整、可复现的命令见[安装与升级](docs/getting-started.zh-CN.md)；host 的分区
+和可选 CJK 字体步骤以 [host/README.zh-CN.md](host/README.zh-CN.md) 为准。
 
-手机访问 Stack-chan 自己的 `/setup` 页面。设备先保存待处理选择，watcher 再完成
-校验、原子更新本地 JSON、热重载并确认设备。可选的局域网 TTS 接收设备发出的
-`/say?text=...` 请求，返回 24 kHz、单声道、16-bit PCM WAV。
+示例 ticker 是占位值；从手机设置页选择真实比赛后，watcher 会校验 ESPN 与 Kalshi
+的双方匹配并原子更新配置。
 
-watcher 电脑上的 `:8788/setup` 只是默认绑定回环地址的本机管理后备页，不是设备
-二维码的主流程。
+### 升级
 
-```text
-Kalshi + ESPN ──只读──> Python watcher ──HTTP──> Stack-chan Matchday Mod
-                              │                         │
-                              └── 配置校验与确认 <── 手机 /setup
-                                                        │
-                                                        └── 可选局域网 TTS
-```
+更新前先查看[全部版本说明](docs/releases/)，确认变化属于 watcher、Matchday Mod
+还是官方 host，并保留本地 watcher 配置，只更新受影响的层。watcher-only 变化通常只需
+更新仓库并重启 watcher；涉及 Mod 或 host 时，必须按对应版本说明构建和刷写。当前
+设备版本的直接入口是 [Matchday Mod 1.5.0](docs/releases/1.5.0.md)。
 
 ## 文档
 
@@ -155,7 +151,7 @@ Kalshi + ESPN ──只读──> Python watcher ──HTTP──> Stack-chan Ma
 | 运行测试、构建归档和回放比赛 | [开发指南](docs/development.zh-CN.md) |
 | 理解三档语气的产品规则 | [播报语气 PRD](docs/commentary-styles-prd.md) |
 | 查看版本差异与升级边界 | [版本说明](docs/releases/) |
-| 处理联网、二维码、TTS、xsbug 等常见问题 | [排障与 FAQ（Wiki）](https://github.com/xymeow/stackchan-matchday/wiki) |
+| 处理联网、二维码、TTS、xsbug 等常见问题 | [排障与 FAQ（Wiki）](https://github.com/xymeow/stackchan-matchday/wiki/Troubleshooting) |
 
 ### 兼容性说明
 

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -68,9 +68,12 @@ copy at `config/kalshi_watchlist.json`, and validate it with
 `python3 -m json.tool` before starting the watcher.
 
 The setup service normally binds `127.0.0.1:8788`; its `/setup` page is a local
-admin fallback rather than the primary on-device QR flow. Once per local day,
-the watcher can ask you to scan and choose a match. Configure that behavior
-with `setup_server.daily_prompt_hour` (`-1` disables it),
+admin fallback rather than the primary on-device QR flow. To expose that
+optional page on a trusted LAN, explicitly set `setup_server.host` to
+`0.0.0.0`; never port-forward it. The bundled server accepts IPv4 addresses
+and hostnames, not IPv6 literals. Once per local day, the watcher can ask you
+to scan and choose a match. Configure that behavior with
+`setup_server.daily_prompt_hour` (`-1` disables it),
 `prompt_minutes_before`, `quiet_hours`, and `lookahead_days`.
 
 ## Player catalog and naming

diff --git a/docs/configuration.zh-CN.md b/docs/configuration.zh-CN.md
@@ -15,6 +15,10 @@
 | watcher `http://127.0.0.1:8788/setup` | watcher 电脑上的本机管理后备页 |
 | `config/kalshi_watchlist.json` | 轮询、提醒开关、市场、TTS 和高级 ESPN 配置 |
 
+watcher 设置服务默认只监听 `127.0.0.1`。确实需要从可信局域网访问这个可选后备页时，
+再把 `setup_server.host` 显式设为 `0.0.0.0`；不要做公网端口转发。内置服务目前只接受
+IPv4 地址或主机名，不支持 IPv6 字面地址。
+
 手机设置流程使用 pending/ack：设备先保存待处理选择，watcher 校验 ESPN 与 Kalshi
 双方匹配，原子更新 JSON、热重载，再确认设备。只切换语气时不会重置 ESPN 已读事件、
 盘口基线、告警队列或轮询状态。

diff --git a/docs/development.md b/docs/development.md
@@ -75,7 +75,7 @@ Use `$MODDABLE/tools/xsbug-log` when you need logs without breakpoint freezes.
 For a deterministic reinstall, follow the debugger-free build and esptool path
 in [Getting started](getting-started.md). Field symptoms and short recovery
 recipes are indexed in the
-[GitHub Wiki](https://github.com/xymeow/stackchan-matchday/wiki).
+[Debugging and recovery Wiki page](https://github.com/xymeow/stackchan-matchday/wiki/Debugging-and-recovery).
 
 ## Documentation synchronization checklist
 
@@ -88,8 +88,9 @@ When behavior changes, update the applicable items together:
    summaries and links there.
 4. Release notes under `docs/releases/`.
 5. `docs/commentary-styles-prd.md` when product rules change.
-6. Environment-specific troubleshooting in the Wiki when useful, linked from
-   the README documentation index.
+6. Environment-specific troubleshooting in the
+   [Troubleshooting Wiki page](https://github.com/xymeow/stackchan-matchday/wiki/Troubleshooting)
+   when useful, linked from the README documentation index.
 
 English and Chinese headings, commands, and facts should remain aligned. The
 Chinese text may use natural phrasing rather than translating sentence by

diff --git a/docs/development.zh-CN.md b/docs/development.zh-CN.md
@@ -78,7 +78,8 @@ python3 "$MATCHDAY_DIR/tools/stackchan_match_replay.py" \
 需要不触发断点暂停的日志时，使用 `$MODDABLE/tools/xsbug-log`。需要确定性重装时，
 按照[安装与升级](getting-started.zh-CN.md)中的无调试器构建与 esptool 流程操作。
 现场症状与安全恢复顺序由
-[GitHub Wiki](https://github.com/xymeow/stackchan-matchday/wiki) 维护。
+[调试与恢复 Wiki 页面](https://github.com/xymeow/stackchan-matchday/wiki/Debugging-and-recovery)
+维护。
 
 ## 文档同步清单
 
@@ -89,7 +90,9 @@ python3 "$MATCHDAY_DIR/tools/stackchan_match_replay.py" \
 3. 用户入口 `README.md` 与 `README.zh-CN.md`，但只保留摘要和链接。
 4. 版本说明 `docs/releases/`。
 5. 如果产品规则变化，更新 `docs/commentary-styles-prd.md`。
-6. 环境型排障经验可补到 Wiki，并从 README 文档索引链接。
+6. 环境型排障经验可补到
+   [常见问题与排障 Wiki 页面](https://github.com/xymeow/stackchan-matchday/wiki/Troubleshooting)，
+   并从 README 文档索引链接。
 
 中英文文档的标题、命令和事实应保持一致；中文可以自然表达，不需要逐句直译。
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -79,8 +79,14 @@ file "$MATCHDAY_DIR/mod/assets/setup/setup-qr.png"
 
 If `file` reports an edge larger than 168 px, regenerate with `-s 3`.
 
+Changing `stackchan_host` or the URL shown elsewhere does not rewrite this
+compiled PNG. If the device address changes, regenerate the QR and reinstall
+the mod.
+
 ## 4. Build and install the mod
 
+### Debug-protocol installation
+
 From the upstream `firmware/` directory:
 
 ```sh
@@ -93,18 +99,25 @@ npm run mod --target=esp32:./platforms/m5stackchan_cores3 -- -f rgb565be \
 
 `npm run mod` installs over the xsbug debug protocol. It needs an xsbug
 listener and may stall mid-write if the device is busy; a killed or stalled
-write leaves the mod unavailable until it is reinstalled. A debugger-free
-alternative is to build only and write the archive directly to `xs`:
+write leaves the mod unavailable until it is reinstalled.
+
+### Preferred without a debugger: write directly to `xs`
+
+When no debugger is needed, prefer building the archive and writing it
+directly to `xs` for a deterministic installation path:
 
 ```sh
+cd "$STACKCHAN_DIR/firmware"
 mcrun -d -m -p esp32:./platforms/m5stackchan_cores3 -t build -f rgb565be \
   "$MATCHDAY_DIR/mod/manifest.json"
 python3 -m esptool --chip esp32s3 --before default-reset --after hard-reset \
   write-flash 0xDF0000 "$MODDABLE/build/bin/esp32/debug/mod/mod.xsa"
 ```
 
 `0xDF0000` is the `xs` partition offset created by the host patch. esptool
-verifies the write; the host mounts the archive after the following reset.
+verifies the write; the host mounts the archive after the following reset. Do
+not use this offset with other hardware or host builds unless their partition
+table is confirmed to match.
 
 Verify the device from the watcher computer:
 
@@ -182,7 +195,9 @@ selection moves from pending to acknowledged while the watcher is running.
 Preserve the watcher output and status response before restarting or
 reflashing anything.
 
-Use the [GitHub Wiki](https://github.com/xymeow/stackchan-matchday/wiki) for
-symptom-first checks covering networking, setup, QR, TTS, CJK text, markets,
-and debugger freezes. This versioned guide remains the canonical reference for
-commands and partition-dependent values.
+Use [Troubleshooting](https://github.com/xymeow/stackchan-matchday/wiki/Troubleshooting)
+for symptom-first checks covering networking, setup, QR, TTS, CJK text, and
+markets. For xsbug freezes, interrupted installs, and device recovery, use
+[Debugging and recovery](https://github.com/xymeow/stackchan-matchday/wiki/Debugging-and-recovery).
+This versioned guide remains the canonical reference for commands and
+partition-dependent values.