docs: add build-doc tooling and a README for every example

Documentation tooling:
- Add the `build-doc` skill and `tools/build_doc.py` wrapper for local
  Sphinx builds (clean / -W / open).
- Enable Markdown (MyST) in conf.py and auto-collect
  examples/{device,host,dual}/*/README.md into a 3-level Examples nav
  (Examples > Device/Host/Dual > example), noting each page's source
  location and normalizing headings to a single H1.
- Remove the stale `.claude/commands/build-doc.md`; point the AGENTS.md
  Documentation section at the skill.

Example docs:
- Add a README.md for every device/host/dual example: what it does, USB
  interface table, notable tusb_config.h settings, generic CMake + Make
  build steps, and how to try it.
- Fold each *_freertos variant into its base README, noting the FreeRTOS
  source path and any RTOS-specific behavior.

Generated docs/examples/ output is git-ignored. Builds clean with
`sphinx-build -W`.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

2 files changed, 32 insertions, 24 deletions

diff --git a/.claude/commands/build-doc.md b/.claude/commands/build-doc.md
deleted file mode 100644
index c9ad9f539..000000000
--- a/.claude/commands/build-doc.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# build-doc
-
-Scan all example READMEs and build the Sphinx documentation.
-
-## Instructions
-
-1. Install docs dependencies:
-   ```bash
-   pip install -r docs/requirements.txt
-   ```
-
-2. Build the docs from the repo root:
-   ```bash
-   sphinx-build -b html docs docs/_build
-   ```
-   `conf.py` automatically scans all `examples/{device,host,dual}/*/README.md`, copies them into `docs/examples/`, and regenerates `examples.rst` with the toctree.
-
-3. Use a timeout of at least 60 seconds.
-
-4. After the build completes:
-   - Show the build output to the user.
-   - Report total warnings and errors.
-   - List which example READMEs were discovered and included.
-   - If there are errors, suggest fixes.
diff --git a/.claude/skills/build-doc/SKILL.md b/.claude/skills/build-doc/SKILL.md
new file mode 100644
index 000000000..401cb31ad
--- /dev/null
+++ b/.claude/skills/build-doc/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: build-doc
+description: Use when building, previewing, or testing the TinyUSB Sphinx docs locally (docs/ → HTML), chasing Sphinx warnings, understanding how example READMEs get into the docs, or regenerating the auto-generated reference files after adding a board or dependency (boards.rst, dependencies.rst, BoardPresets.json, CMakePresets.json).
+---
+
+# Build TinyUSB Docs
+
+## Build & preview
+
+```bash
+pip install -r docs/requirements.txt    # one-time
+python3 tools/build_doc.py -o            # build docs/_build/ and open it
+```
+
+`tools/build_doc.py` wraps `sphinx-build`: `-c` clean, `-W` fail on warnings, `-o` open. Raw form: `sphinx-build -b html docs docs/_build`.
+
+- Pages can be `.rst` or `.md` (MyST). Example `README.md`s under `examples/{device,host,dual}/*/` are **auto-collected** at build time into `docs/examples/` + `examples.rst` (both git-ignored) — add/rename an example and just rebuild; edit the source README, never the generated copies.
+- Watch the output for `WARNING:` (broken refs, missing toctree entries).
+
+## Regenerate after adding a board or dependency
+
+Run from the repo root; `docs/reference/*.rst` and the preset JSONs are **generated** — don't hand-edit.
+
+| Added | Run |
+|---|---|
+| Board (`hw/bsp/FAMILY/boards/`) | `python3 tools/gen_doc.py` + `python3 tools/gen_presets.py` |
+| Dependency (edited `tools/get_deps.py`) | `python3 tools/gen_doc.py` |
+
+- `gen_doc.py` → `docs/reference/boards.rst` + `dependencies.rst`. Needs `pandas` + `tabulate` (not in `requirements.txt`) — `pip install pandas tabulate` if it errors.
+- `gen_presets.py` → `hw/bsp/BoardPresets.json` + per-example `CMakePresets.json`.
+
+Then rebuild and `git diff` the regenerated files; commit them with the board/dep change.