feat(data): flashing/upload troubleshooting coverage

- new linux-port-permission entry (dialout group + reboot, fuser -k,
  ModemManager) - 'Permission denied'/'串口被占用' routed to it
- new flash-success-but-no-run entry (RESET after upload, USB CDC On
  Boot, wrong-board check, brownout, Blink sanity check)
- knowledge: manual rescue flashing (esptool erase_flash/write_flash,
  bossac for SAMD) for boards the IDE refuses
- Chinese symptom vocabulary on all flashing entries; routing verified
  10/10 for the real-world battery (一直Connecting / 烧录失败 / 找不到
  串口 / 烧录成功但没反应 / 怎么进入烧录模式 ...)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: LynnL4

packages/xiao-assistant/data/docs/troubleshooting.yaml

@@ -6,6 +6,14 @@
   - connecting timeout
   - no serial port
   - cannot flash
+  - 怎么进入烧录模式
+  - 进入下载模式
+  - 无法进入bootloader
+  - 按键烧录
+  - 烧录模式
+  - boot模式
+  - download mode
+  - enter bootloader
   boards:
   - esp32c3
   - esp32s3
@@ -40,6 +48,10 @@
   - device descriptor failed
   - unknown device
   - driver error
+  - 找不到串口
+  - 没有串口
+  - 识别不到设备
+  - 未知设备
   boards:
   - esp32c3
   - esp32s3
@@ -67,6 +79,11 @@
   - espcomm_open
   - failed to connect
   - sync failed
+  - 烧录失败
+  - 刷机失败
+  - 上传超时
+  - 连接开发板失败
+  - 一直显示Connecting
   boards:
   - esp32c3
   - esp32s3
@@ -116,6 +133,9 @@
   - blank serial monitor
   - serial not working
   - no data in monitor
+  - 串口监视器没有输出
+  - 串口没有数据
+  - 监视器空白
   boards:
   - esp32c3
   - esp32s3
@@ -282,3 +302,66 @@
   - 'Increase connection interval: BLE.setConnectionInterval(0x06, 0x12)'
   - Avoid WiFi and BLE simultaneous use on ESP32 (shared radio)
   wikiUrl: https://wiki.seeedstudio.com/XIAO_BLE/
+- id: linux-port-permission
+  title: Serial port permission denied or busy (Linux)
+  symptoms:
+  - permission denied
+  - access denied
+  - could not open port
+  - device or resource busy
+  - port busy
+  - 无法打开串口
+  - 串口被占用
+  - 没有权限
+  - permission denied opening serial port
+  boards: &id001
+  - rp2040
+  - rp2350
+  - ra4m1
+  - samd21
+  - esp32c6
+  - esp32c3
+  - mg24
+  - mg24-sense
+  - nrf52840
+  - nrf52840-sense
+  - nrf54l15
+  - nrf54l15-sense
+  - esp32c5
+  - nrf54lm20a
+  - nrf54lm20a-sense
+  - esp32s3
+  - esp32s3-sense
+  category: usb
+  diagnosis:
+  - 'Run: ls -l /dev/ttyACM* - the group is usually dialout; your user is probably not in it'
+  - 'If the port exists but upload says busy: another program (serial monitor, previous upload, ModemManager) holds it'
+  - 'Confirm with: groups - dialout must be listed'
+  solutions:
+  - 'Add yourself to the dialout group and REBOOT (logging out is often not enough): sudo usermod -aG dialout $USER && sudo reboot'
+  - 'Free a busy port: sudo fuser -k /dev/ttyACM0 (or close the other serial monitor)'
+  - 'Disable ModemManager if it grabs the port on plug-in: sudo systemctl stop ModemManager'
+  wikiUrl: https://wiki.seeedstudio.com/SeeedStudio_XIAO_Series_Introduction/
+- id: flash-success-but-no-run
+  title: Upload succeeds but the board does nothing (dead after flash)
+  symptoms:
+  - upload success but nothing happens
+  - board dead after flash
+  - program not running
+  - flash ok but no output
+  - 烧录成功但没反应
+  - 上传成功但程序不运行
+  - 烧录后没反应
+  boards: *id001
+  category: upload
+  diagnosis:
+  - The flash almost certainly succeeded - the sketch is just not starting or its output is invisible
+  - 'ESP32 series: after flashing, USB CDC On Boot must be Enabled (Tools menu) or Serial output never appears'
+  - Wrong board selected in the IDE compiles+uploads fine for a different chip and appears dead
+  - Insufficient USB power can brown-out the MCU right after boot
+  solutions:
+  - Press RESET once after upload (some boards halt in the bootloader until reset)
+  - 'ESP32: Tools > USB CDC On Boot > Enabled, then re-upload'
+  - Verify Tools > Board matches your exact XIAO model, and the COM port still belongs to the board
+  - Try a different USB port/cable (prefer a rear motherboard port or powered hub); watch the power LED
+  - 'Sanity check: upload the plain Blink example - if it runs, the issue is in your sketch (e.g. blocking while(!Serial))'

packages/xiao-assistant/data/knowledge/esp32-gotchas.yaml

@@ -102,3 +102,42 @@
   code: "const int LED = 10; // external LED via 150ohm on D10\n\nvoid setup() {\n  pinMode(LED, OUTPUT);\n}\n\nvoid loop() {\n  digitalWrite(LED, HIGH);\n  delay(500);\n  digitalWrite(LED, LOW);\n  delay(500);\n\
     }"
   workaround: 'On the wiki: "there is no LED_BUILTIN available for the XIAO ESP32C3, you can use an external LED instead."'
+- id: manual-flash-rescue
+  title: Manual rescue flashing when the IDE cannot upload at all
+  tags:
+  - upload
+  - flash
+  - esptool
+  - bossac
+  - rescue
+  - 烧录
+  - 刷机
+  - 救援
+  boards:
+  - esp32c3
+  - esp32s3
+  - esp32s3-sense
+  - esp32c6
+  - esp32c5
+  - samd21
+  - ra4m1
+  category: upload
+  severity: medium
+  source: support-ticket
+  summary: When the IDE repeatedly fails to connect, flashing manually with esptool (ESP32) or bossac (SAMD) rescues the board.
+  problem: IDE upload loops on "Connecting..." and never succeeds; the board may have a half-erased firmware and looks bricked.
+  solution: Force download mode (hold BOOT / for SAMD21 double-tap reset) and flash or erase manually.
+  code: '# ESP32 series: full erase, then let the IDE retry
+
+    esptool.py --port /dev/ttyACM0 erase_flash
+
+
+    # ESP32: flash a known-good binary manually at slow speed
+
+    esptool.py --port /dev/ttyACM0 --baud 115200 write_flash 0x0 firmware.bin
+
+
+    # SAMD21 (bossac comes with the Seeeduino core)
+
+    bossac -d --port=/dev/ttyACM0 -U -i -e -w firmware.bin -R'
+  workaround: If esptool still cannot open the port on Linux, check the dialout group and that no serial monitor holds it.