docs: add read-doc skill, tighten CLAUDE.md and skill docs (#3778)HEADmaster

* docs: add read-doc skill for on-demand datasheet lookup

Search and read MCU datasheets, reference manuals, errata, and the USB
spec from a local Calibre library ($HOME/Documents/calibre-library)
instead of answering register/bitfield/pinout questions from model
memory. Gated on the library's existence, so it no-ops for contributors
who don't have it.

* docs: reference read-doc skill and tighten CLAUDE.md

Point the datasheet/reference entry at the new read-doc skill, and trim
sections that only duplicate a skill already owning the detail:
PVS-Studio and Code Size collapse to pointers; GDB/Build/Flash command
blocks condensed to essentials. 213 -> 129 lines; behavioral guidelines
and the validation checklist unchanged.

* docs: tighten skill redundancy; rename AGENTS.md refs to CLAUDE.md

code-size: fold the step list into a sentence and drop invocation
examples the argument tables already cover. hil: merge the duplicated
self-lock bullets and compress the hifiphile note. usbmon: compress the
group-membership setup paragraph. All commands, flags, lock rules, and
report paths preserved. usb-target-debug and the pvs script only get
stale AGENTS.md references renamed to CLAUDE.md (now the real file);
run_pvs.sh no longer cites a --dump-files mention that CLAUDE.md dropped.

* docs: fix review findings — restore Espressif cd step, ELF placeholder, code-size comment

Codex/Copilot/Claude review of #3778: the condensed Espressif bullet
lost its cd (idf.py resolves the project from CWD, so the command failed
from repo root); the GDB example now uses the build/your_app.elf
placeholder that docs/troubleshooting.rst established; the code-size
invocation comment no longer references --combined, which the shown
command doesn't use.

6 files changed, 77 insertions, 39 deletions

diff --git a/.claude/skills/code-size/SKILL.md b/.claude/skills/code-size/SKILL.md
index f3c51ccfa..0a5305221 100644
--- a/.claude/skills/code-size/SKILL.md
+++ b/.claude/skills/code-size/SKILL.md
@@ -13,14 +13,7 @@ Compare TinyUSB code size between a base ref (default `master`) and the current
 | **all examples, one board** | Per-board regression sweep | `-b BOARD` |
 | **all examples, all CI families (combined)** | Pre-merge full check | `--ci` |
 
-The script handles the full base-vs-branch dance:
-1. Creates a temporary git worktree of the base ref under `cmake-metrics/_worktree/`.
-2. Builds the base in `cmake-metrics/<board>/base/`.
-3. Builds the current tree in `cmake-metrics/<board>/build/`.
-4. Runs `tools/metrics.py compare` and writes `cmake-metrics/<board>/metrics_compare.md`.
-5. Removes the worktree on exit.
-
-`--combined` (auto-set by `--ci`) also produces `cmake-metrics/_combined/metrics_compare.md` aggregating across all boards.
+The script does the whole base-vs-branch dance itself: a temporary git worktree of the base ref under `cmake-metrics/_worktree/` (removed on exit), base + branch builds under `cmake-metrics/<board>/{base,build}/`, then `tools/metrics.py compare` (report paths under Outputs).
 
 ## Choosing arguments
 
@@ -35,29 +28,20 @@ Infer from the user's request:
 ## Common invocations
 
 ```bash
-# Single example, one board (linkermap, fastest):
+# Single example, one board (linkermap, fastest; add --bloaty for section/symbol breakdown):
 python3 tools/metrics_compare_base.py -b raspberry_pi_pico -e device/cdc_msc
 
-# Same with bloaty for section/symbol breakdown:
-python3 tools/metrics_compare_base.py -b raspberry_pi_pico -e device/cdc_msc --bloaty
-
-# All examples for one board:
+# All examples for one board (repeat -b for several boards):
 python3 tools/metrics_compare_base.py -b raspberry_pi_pico
 
-# Multiple boards, one combined report:
-python3 tools/metrics_compare_base.py -b raspberry_pi_pico -b raspberry_pi_pico2 --combined
-
 # Full CI sweep (first board per arm-gcc family, combined):
 python3 tools/metrics_compare_base.py --ci
-
-# Compare against a tag/commit instead of master:
-python3 tools/metrics_compare_base.py -b raspberry_pi_pico --base-branch v0.18.0
 ```
 
 ## Outputs
 
 - **Per-board:** `cmake-metrics/<board>/metrics_compare.md` (and `_<example>.md` when `-e` is set)
-- **Combined (with `--combined`/`--ci`):** `cmake-metrics/_combined/metrics_compare.md`
+- **Combined (`--combined`, auto-set by `--ci`):** `cmake-metrics/_combined/metrics_compare.md`, aggregating all boards
 - **Bloaty:** printed to stdout as section + symbol diffs
 
 ## Timing
diff --git a/.claude/skills/hil/SKILL.md b/.claude/skills/hil/SKILL.md
index 0d3abf1ac..7b76bf1b8 100644
--- a/.claude/skills/hil/SKILL.md
+++ b/.claude/skills/hil/SKILL.md
@@ -15,17 +15,14 @@ Run TinyUSB HIL tests on real boards. **Run `hostname` first** — it tells you
 
 Default to **local**. Use **remote** only when on `htpc` and the user says `remote`/`ci.lan`. Never attempt remote on `ci`.
 
-The `hifiphile` rig is externally hosted by TinyUSB maintainer hifiphile; its board pool is
-`test/hil/hfp.json` and its HIL runs are triggered by GitHub CI (the `hil-tinyusb (hfp.json)`
-matrix job). **Never run HIL against this rig during development unless the user explicitly
-asks for it.**
+`hifiphile` is an external rig (hosted by maintainer hifiphile), exercised by the GitHub CI
+`hil-tinyusb (hfp.json)` matrix job — **never run HIL against it unless the user explicitly asks.**
 
 ## Board locks — the CI runner keeps running
 
 The `ci` rig also hosts a GitHub Actions runner that flashes boards and runs HIL as part of CI. Hardware access is arbitrated **per board** with kernel flocks in `/tmp/tinyusb-hil-locks/` — do NOT stop the runner service.
 
-- `hil_test.py` self-locks each board for the duration of its flash+test (holder reason `hil_test.py`). A locked board fails immediately (`<board>  Failed: board locked: {holder info}`) without flashing — in CI, re-run the failed job once the lock is released.
-- If your `hold` fails and the holder's reason is `hil_test.py`, a CI job is mid-test on that board — wait a few minutes and retry rather than forcing.
+- `hil_test.py` self-locks each board for its flash+test (holder reason `hil_test.py`). A locked board fails immediately (`<board>  Failed: board locked: {holder info}`) without flashing — in CI, re-run the failed job later; if your `hold` is refused with reason `hil_test.py`, a CI job is mid-test — wait a few minutes and retry rather than forcing.
 - For hardware work outside `hil_test.py` (JLink/GDB, manual flashing, `usbtest.py`, serial poking), hold the lock first:
 
 ```bash
@@ -41,7 +38,7 @@ python3 test/hil/board_lock.py release BOARD [BOARD...]
 
 ## Prerequisites
 
-Examples must be built for the target board(s) — see AGENTS.md "Build" → "All examples for a board" (produces `examples/cmake-build-<board>/`). `-B examples` points `hil_test.py` at that parent folder.
+Examples must be built for the target board(s) — see CLAUDE.md "Build" → "All examples for a board" (produces `examples/cmake-build-<board>/`). `-B examples` points `hil_test.py` at that parent folder.
 
 ## Arguments
 
@@ -64,8 +61,6 @@ python3 test/hil/hil_test.py -B examples "$CONFIG"
 python3 test/hil/hil_test.py -b stm32f723disco -B examples "$CONFIG"
 ```
 
-Append pass-through flags (`-v`, `-r 1`, …) to either command as needed.
-
 ## Remote execution (htpc → ci.lan only)
 
 `test/hil/hil_ci.sh` handles dir setup, scp of test scripts, rsync of firmware (`.elf`/`.bin`/`.hex`), and runs `hil_test.py` on `ci.lan` with `tinyusb.json`:
diff --git a/.claude/skills/pvs/run_pvs.sh b/.claude/skills/pvs/run_pvs.sh
index 7406a3b4f..ce2cfd7e7 100755
--- a/.claude/skills/pvs/run_pvs.sh
+++ b/.claude/skills/pvs/run_pvs.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Run PVS-Studio static analysis on TinyUSB for a given BOARD.
 #
-# Mirrors the "Static Analysis (PVS-Studio)" section in AGENTS.md / CLAUDE.md:
+# Implements the build + analyze flow behind CLAUDE.md "Static Analysis (PVS-Studio)":
 #   - build all examples for BOARD with compile_commands.json exported
 #   - run pvs-studio-analyzer against that compile DB using .PVS-Studio/.pvsconfig
 #   - convert the log to human-readable (errorfile) and SARIF output
@@ -64,9 +64,9 @@ fi
 
 # --- Analyze ---------------------------------------------------------------
 echo ">>> Running PVS-Studio analyzer (-j${JOBS})"
-# Note: AGENTS.md shows --dump-files, but that scatters .PVS-Studio.i/.cfg dump
-# files across the source tree (only useful for debugging false positives). It is
-# omitted here to keep the working tree clean; add it back via "$@" if needed.
+# Note: --dump-files scatters .PVS-Studio.i/.cfg dump files across the source
+# tree (only useful for debugging false positives). It is omitted here to keep
+# the working tree clean; add it back via "$@" if needed.
 pvs-studio-analyzer analyze \
   -f "${COMPILE_DB}" \
   -R .PVS-Studio/.pvsconfig \
diff --git a/.claude/skills/read-doc/SKILL.md b/.claude/skills/read-doc/SKILL.md
new file mode 100644
index 000000000..df845e7b5
--- /dev/null
+++ b/.claude/skills/read-doc/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: read-doc
+description: Use when you need authoritative hardware/protocol facts from a primary source rather than model memory — an MCU/peripheral datasheet, reference manual (RM/TRM), errata, pinout, register/bitfield layout, memory map, schematic, or the USB spec — before answering register/electrical/timing/protocol questions from training knowledge or the web; or when the user asks to read/open/look up a manual, datasheet, book, or PDF/EPUB from their Calibre library. Requires a local Calibre library at ~/Documents/calibre-library; no-ops if absent.
+---
+
+# Read Doc
+
+## Overview
+
+Some maintainers keep datasheets, manuals, and books in a Calibre library at
+`$HOME/Documents/calibre-library/`, laid out as
+`AUTHOR/TITLE (id)/TITLE - AUTHOR.pdf|.epub`. For hardware/protocol facts —
+registers, bitfields, memory maps, pinouts, electrical/timing specs, errata, USB
+spec — read the doc instead of answering from training knowledge or the web.
+
+## Gate first
+
+The library is per-user. Check it exists before anything else:
+
+```bash
+[ -d "$HOME/Documents/calibre-library" ] && echo present || echo absent
+```
+
+Absent → the skill does not apply; fall back to normal sources silently (don't
+mention the library unless the user named it).
+
+## When to use
+
+- About to state a register/bitfield/reset-value/memory-map/pinout/timing spec
+  for a specific MCU or peripheral.
+- User says "read the RP2040 datasheet", "open the CH569 manual", "what does the
+  STM32H7 RM say about…".
+
+Not for general concepts, repo/code questions, or when no such doc is likely.
+
+## Find
+
+Keywords from `/read-doc <keywords>`, else derived from the question (part number,
+peripheral, spec name). AND them with chained case-insensitive grep:
+
+```bash
+find "$HOME/Documents/calibre-library/" -maxdepth 3 \( -iname '*.pdf' -o -iname '*.epub' \) | grep -i "kw1" | grep -i "kw2"
+```
+
+One match → read it. Several → list and ask via AskUserQuestion. None → drop the
+weakest keyword and broaden (filenames hold title+author, not tags); still none →
+list the closest author/title matches.
+
+## Read
+
+- **PDF:** Read with `pages`; for >10 pages start `pages: "1-20"` (TOC/overview),
+  report the page count, then read sections on demand.
+- **EPUB:** Read the path directly.
+- Summarize in one line (title, pages, coverage) and keep as reference context.
+
+## Common mistakes
+
+- Skipping the gate on a machine with no library.
+- Answering a register/spec question from memory when the datasheet is on disk.
+- Loading a 1000-page PDF up front instead of TOC-first.
+- Requiring all keywords to match — broaden on zero hits.
diff --git a/.claude/skills/usb-target-debug/SKILL.md b/.claude/skills/usb-target-debug/SKILL.md
index c664bf8fc..71fac98f2 100644
--- a/.claude/skills/usb-target-debug/SKILL.md
+++ b/.claude/skills/usb-target-debug/SKILL.md
@@ -58,7 +58,7 @@ Build with `LOG=2` (`LOG=3` adds per-transfer noise and much more timing skew).
 `LOGGER=rtt` routes it over the debug probe (J-Link only) — no UART wiring:
 
 ```bash
-# RTT: JLinkGDBServer from AGENTS.md "GDB Debugging" + -RTTTelnetPort, then:
+# RTT: JLinkGDBServer from CLAUDE.md "GDB Debugging" + -RTTTelnetPort, then:
 timeout 20s JLinkRTTClient > /tmp/rtt.log        # non-interactive capture
 # UART (board's debug serial, if wired):
 stty -F /dev/ttyACM<N> 115200 raw && timeout 20s cat /dev/ttyACM<N> | tee /tmp/uart.log
@@ -80,10 +80,10 @@ reads don't halt the target.
 ## GDB — state autopsy and watchpoints
 
 Connect/load recipes per probe family (J-Link, OpenOCD for ST-Link /
-CMSIS-DAP / WCH-Link) are in AGENTS.md "GDB Debugging". Release builds keep
+CMSIS-DAP / WCH-Link) are in CLAUDE.md "GDB Debugging". Release builds keep
 DWARF (`MinSizeRel`), so `p`/struct access works on HIL firmware.
 
-**Autopsy of a wedged board: attach and halt ONLY** — skip AGENTS.md's
+**Autopsy of a wedged board: attach and halt ONLY** — skip CLAUDE.md's
 `monitor reset halt` + `load` (those are for fresh starts; a reset destroys
 the evidence). Symbolize with the ELF that is actually flashed —
 `<build root>/cmake-build-<board>/<example>/<example>.elf` from the run that
diff --git a/.claude/skills/usbmon/SKILL.md b/.claude/skills/usbmon/SKILL.md
index 4164dcf2e..85ec33248 100644
--- a/.claude/skills/usbmon/SKILL.md
+++ b/.claude/skills/usbmon/SKILL.md
@@ -7,9 +7,7 @@ description: Use when capturing, analyzing, or debugging USB bus traffic for Tin
 
 `usbmon` records host-side **URBs** — control / bulk / interrupt / isochronous transfers, descriptors, class requests, STALLs, short packets — i.e. exactly what the host exchanged with a device. Use it to debug a TinyUSB device on real hardware. (It's host/URB-level, not wire-level; for SOF/ACK/electrical use a hardware analyzer.)
 
-**Setup (assumed in place):** `usbmon` loaded and a udev rule `SUBSYSTEM=="usbmon", GROUP="wireshark", MODE="0640"` with your user in the `wireshark` group — so `tshark` captures with no `sudo`.
-
-If you were just added to `wireshark` (e.g. `usermod -aG`), the running shell/agent still has the old group set (group adds only apply to a fresh login). Don't restart — wrap each capture in `sg wireshark -c '…'`, which re-reads `/etc/group` immediately: `sg wireshark -c 'tshark -i usbmon3 -s 128 -a duration:30 -w /tmp/cap.pcapng'`. (Reading a finished `.pcapng` with `tshark -r` needs no special group.) For long/high-throughput captures add `-s 128` (snaplen) to keep only URB headers/status, not payloads.
+**Setup (assumed in place):** `usbmon` loaded and a udev rule `SUBSYSTEM=="usbmon", GROUP="wireshark", MODE="0640"` with your user in the `wireshark` group — so `tshark` captures with no `sudo`. Freshly added to the group? The running shell doesn't have it yet (group adds need a new login) — wrap captures in `sg wireshark -c 'tshark -i usbmon3 -s 128 -a duration:30 -w /tmp/cap.pcapng'`; reading a finished `.pcapng` (`tshark -r`) needs no group. `-s 128` (snaplen) keeps only URB headers/status, not payloads — use it for long/high-throughput captures.
 
 ## Capture