m5-onboard: cap esptool < 5; document PEP 668 / Homebrew Python

[lisabee123]

Summary

Two fixes hit while provisioning a Cardputer-Adv with m5-onboard go:

• esptool 5.x crashes mid-write_flash on Cardputer-Adv — Serial data stream stopped followed by StopIteration in the SLIP reader during the --after watchdog_reset teardown. 4.11.0 flashes the same firmware to the same device cleanly. requirements.txt was previously esptool>=4.11 (no upper bound), so a fresh install pulled 5.2.0 and burned ~4 minutes per attempt before failing. Now pinned >=4.11,<5, with a new _MAX_ESPTOOL_EXCLUSIVE constant in onboard.py so the preflight enforces the cap before the button dance rather than crashing mid-flash.
• PEP 668 / Homebrew Python on macOS — the documented pip install --user -r requirements.txt fails with error: externally-managed-environment when python3 resolves to a Homebrew install (most current macOS dev setups). The preflight then prints pip install failed (exit 1) and bails. Documented the venv recovery path in SKILL.md (the preflight already detects venvs and drops --user, so once you're inside it the auto-install works again). Apple's /usr/bin/python3 is unaffected.

What changed

• requirements.txt — esptool>=4.11,<5, with rationale comments and the macOS venv recipe inline.
• .claude/skills/m5-onboard/scripts/onboard.py — new _MAX_ESPTOOL_EXCLUSIVE = (5, 0). Wired into the preflight version gate (both pre- and post-install). New error message tells the user to downgrade with the exact pip spec.
• .claude/skills/m5-onboard/SKILL.md — Dependencies section notes the cap and why; auto-install command lines updated to 'esptool>=4.11,<5'; new PEP 668 paragraph in the macOS Platform notes.

Repro of the underlying esptool 5.x failure

Cardputer-Adv (ESP32-S3, native USB), esptool 5.2.0, fresh m5-onboard go. After ~4:15 of write_flash at 115200 baud no-stub:

A fatal error occurred: The chip stopped responding.
File ".../esptool/loader.py", line 431, in read
    return next(self._slip_reader)
StopIteration
esptool.util.FatalError: Serial data stream stopped: Possible serial noise or corruption.

Downgrading to 4.11.0 with no other changes flashes the same uiflow2_*.bin to the same physical device cleanly (Wrote 8384512 bytes at 0x00000000 in 86.6 seconds; Hash of data verified).

Test plan

• python -c "import py_compile; py_compile.compile('.claude/skills/m5-onboard/scripts/onboard.py', doraise=True)" passes
• End-to-end m5-onboard go on a Cardputer-Adv with esptool 4.11.0 reaches ==== DONE ==== and the device boots into the launcher
• (Not tested by this PR) preflight rejection path when esptool 5.x is pre-installed — covered by the new _MAX_ESPTOOL_EXCLUSIVE branch but worth a manual smoke test
• (Not tested by this PR) repro on Linux + Windows is unchanged
• When esptool 5.x is validated end-to-end on the full board matrix and flash.py's Hash of data verified parser is re-confirmed against 5.x stdout wording, lift the cap

🤖 Generated with Claude Code