## What this skill fixes

Failure modes that appear when building paired HMI + USB CDC firmware on Octolux. Cross off as the upstream platform / firmware ships a fix.

- **Web Serial picker shows *"No compatible devices found"*** — `lsusb` confirms the device. Cause: missing Chromium `SerialAllowAllPortsForUrls` policy or `/dev/ttyACM*` not world-readable.
- **`requestPort()` rejects with `NotFoundError: No port selected by the user`** — every session. Cause: picker is wrong UX for a kiosk; use `getPorts()` + VID filter.
- **`port.open()` throws *"Failed to execute 'open' on 'SerialPort'"*** — open `ports[0]` is a platform UART, not the USB CDC device. Always filter by VID.
- **`getPorts().length === 0`** — policy path wrong, Chromium not restarted, or `/dev/ttyACM0` still root-only.
- **Tap on the HMI does nothing visible** — Chromium permission dialogs don't render in the VNC stream. Use a visible debug strip on the page + CDP-via-SSH.
- **`octolux deploy push` times out** — SCP + chromium-restart + screencast-bounce shell sequence is the workaround.
- **`ps aux \| grep screencast` returns nothing on the device** — busybox `ps` truncates cmdlines. Use `/proc/[0-9]*/cmdline` matching.
- **DANGER: walking `/proc/[0-9]*/net/tcp` to find a port owner mass-kills system PIDs.** Lost SSH and Chromium during this session. Use cmdline matching instead.
- **`/tmp/screencast.js` or `/tmp/node_modules/ws/` missing after a bad kill** — both in tmpfs. SCP-restore from `~/ntx-embedded/apps/octolux/`.
- **Dashboard VNC tile frozen after Chromium restart** — screencast's CDP binding died with the old target. Bounce the screencast.
- **`error code: 502` no-body on the Adom proxy** — strips 5xx bodies. Return HTTP 200 with `{ok:false, error, hint}` instead. (Cross-ref: [octolux-app-server-debug](/caleb/octolux-app-server-debug).)

## Install

```bash
adompkg install caleb/octolux-web-serial-hmi
# or the whole NTX bundle:
adompkg install caleb/ntx-octolux-toolkit
```

Lands at `~/.claude/skills/octolux-web-serial-hmi/` and becomes discoverable to Claude on the next run.

## Full reference

Browse `SKILL.md` in the **Files** tab — Quick-start recipe for new HMI projects, Pico SDK firmware template, full Web Serial HMI template, Chromium policy install, udev rule, deploy sequence, CDP diagnostics, 12-row failure-mode table.