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]>

3 files changed, 122 insertions, 0 deletions

diff --git a/examples/dual/dynamic_switch/README.md b/examples/dual/dynamic_switch/README.md
index 034787f18..94b161480 100644
--- a/examples/dual/dynamic_switch/README.md
+++ b/examples/dual/dynamic_switch/README.md
@@ -9,6 +9,17 @@ This example demonstrates TinyUSB's dual-role capability by allowing runtime swi
 - **Host Mode**: Enumerates connected USB devices and prints device information
 - **Dynamic switching**: Deinitializes the current stack and reinitializes in the new mode
 
+## Configuration
+
+Notable `tusb_config.h` settings:
+
+```c
+#define CFG_TUD_CDC 1
+#define CFG_TUH_HUB 1
+#define CFG_TUH_DEVICE_MAX (CFG_TUH_HUB ? 4 : 1)
+#define CFG_TUH_ENUMERATION_BUFSIZE 256
+```
+
 ## Usage
 
 1. **Build and flash** the example to your board
diff --git a/examples/dual/host_hid_to_device_cdc/README.md b/examples/dual/host_hid_to_device_cdc/README.md
new file mode 100644
index 000000000..dfa0d75af
--- /dev/null
+++ b/examples/dual/host_hid_to_device_cdc/README.md
@@ -0,0 +1,55 @@
+# Dual: USB HID Host → CDC Device
+
+A dual-role bridge: the board acts as a USB host on one root-hub port and a USB device on another at the same time, forwarding input from a connected HID keyboard/mouse to the host PC as text over a virtual serial port.
+
+## What it does
+
+- Host side: enumerates a connected USB HID device (boot keyboard and/or mouse), including devices behind a hub, and requests its interrupt reports.
+- Device side: presents a single CDC (virtual serial) interface to the PC.
+- Data flow: incoming keyboard reports are converted from HID keycodes to ASCII (with shift handling) and written to the CDC serial port; mouse reports are formatted as `[addr] LMR x y wheel` text lines. HID mount/unmount events are also announced over the CDC port. Data received from the PC on the CDC port is read and discarded (LED control is a TODO).
+
+## USB Descriptors
+
+(DEVICE-side interfaces only)
+
+| Interface | Class driver |
+|-----------|--------------|
+| 0–1 | CDC (virtual serial) |
+
+## Configuration
+
+Notable `tusb_config.h` settings:
+
+```c
+#define CFG_TUD_CDC              1
+#define CFG_TUH_HUB              1
+#define CFG_TUH_DEVICE_MAX       (CFG_TUH_HUB ? 4 : 1)
+#define CFG_TUH_HID              (3*CFG_TUH_DEVICE_MAX)
+#define CFG_TUH_ENUMERATION_BUFSIZE 256
+```
+
+## Requirements
+
+The board needs two usable USB ports: one acting as host (for the HID device) and one acting as device (to the PC).
+
+## Building
+
+CMake:
+
+```bash
+mkdir build && cd build
+cmake -DBOARD=raspberry_pi_pico ..
+cmake --build .
+```
+
+Make:
+
+```bash
+make BOARD=raspberry_pi_pico all
+```
+
+## How to use
+
+1. Plug a USB keyboard or mouse into the board's host port.
+2. Connect the board's device port to the PC and open the CDC serial port it enumerates (e.g. `/dev/ttyACMx` on Linux, a COM port on Windows).
+3. Type on the keyboard: the characters appear in the serial terminal. Move/click the mouse: lines like `[1] L-- 3 -2 0` appear. Connecting or removing a HID device prints a mount/unmount message.
diff --git a/examples/dual/host_info_to_device_cdc/README.md b/examples/dual/host_info_to_device_cdc/README.md
new file mode 100644
index 000000000..10f1dd0c2
--- /dev/null
+++ b/examples/dual/host_info_to_device_cdc/README.md
@@ -0,0 +1,56 @@
+# Dual: USB Host Device-Info → CDC Device
+
+A dual-role bridge: the board acts as a USB host on one root-hub port and a USB device on another at the same time, printing information about any device plugged into the host port out to the PC over a virtual serial port.
+
+## What it does
+
+- Host side: enumerates any USB device attached to the host port (including devices behind a hub) and captures its device descriptor during enumeration.
+- Device side: presents a single CDC (virtual serial) interface to the PC.
+- Data flow: when a device is mounted on the host port, the board reads its descriptor fields (VID/PID, bcdUSB, class/subclass/protocol, max packet size, configuration count) plus the manufacturer, product, and serial-number string descriptors (UTF-16 converted to UTF-8) and prints them as formatted text to the CDC serial port. Mount and unmount events are also reported. Optionally runs the host/device/main work as FreeRTOS tasks.
+
+## USB Descriptors
+
+(DEVICE-side interfaces only)
+
+| Interface | Class driver |
+|-----------|--------------|
+| 0–1 | CDC (virtual serial) |
+
+## Configuration
+
+Notable `tusb_config.h` settings:
+
+```c
+#define CFG_TUD_CDC              1
+#define CFG_TUD_CDC_RX_BUFSIZE   (TUD_OPT_HIGH_SPEED ? 512 : 64)
+#define CFG_TUD_CDC_TX_BUFSIZE   (TUD_OPT_HIGH_SPEED ? 512 : 256)
+#define CFG_TUH_HUB              1
+#define CFG_TUH_DEVICE_MAX       (CFG_TUH_HUB ? 4 : 1)
+#define CFG_TUH_ENUMERATION_BUFSIZE 256
+```
+
+## Requirements
+
+The board needs two usable USB ports: one acting as host (for the device to inspect) and one acting as device (to the PC).
+
+## Building
+
+CMake:
+
+```bash
+mkdir build && cd build
+cmake -DBOARD=raspberry_pi_pico ..
+cmake --build .
+```
+
+Make:
+
+```bash
+make BOARD=raspberry_pi_pico all
+```
+
+## How to use
+
+1. Connect the board's device port to the PC and open the CDC serial port it enumerates (e.g. `/dev/ttyACMx` on Linux, a COM port on Windows).
+2. Plug any USB device into the board's host port.
+3. The serial terminal shows a `mounted device N` line followed by a full device-descriptor dump (IDs, strings, and field values). Removing the device prints an `unmounted device N` line.