Document protocol modes

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

README.md

@@ -103,19 +103,62 @@ Filters you can use:
 ## Building and flashing firmware
 Prereqs: Pico SDK + CMake toolchain set up.
 
-### One-shot build + flash (picotool)
+### Protocol selection
+
+The default `legacy` protocol is the existing wired Switch Pro implementation. Omitting `--protocol` from `build.py` or `SWITCH_PICO_PROTOCOL` from CMake preserves that default.
+
+Build and flash the default legacy firmware with picotool:
+
 ```sh
 python3 build.py
 ```
+
+Build without flashing, either implicitly or explicitly selecting legacy:
+
+```sh
+python3 build.py --build-only
+python3 build.py --protocol legacy --build-only
+```
+
+Manual legacy build:
+
+```sh
+cmake -S . -B build -DSWITCH_PICO_PROTOCOL=legacy -DSWITCH_PICO_LOG=OFF
+cmake --build build -j
+```
+
+Build the experimental Switch 2 protocol without flashing:
+
+```sh
+python3 build.py --protocol switch2 --build-only
+```
+
+Manual experimental Switch 2 build:
+
+```sh
+cmake -S . -B build -DSWITCH_PICO_PROTOCOL=switch2 -DSWITCH_PICO_LOG=OFF
+cmake --build build -j
+```
+
+To build and flash that experimental image, omit `--build-only`:
+
+```sh
+python3 build.py --protocol switch2
+```
+
+`--build-only` confirms and prints `build/switch-pico.elf` and `build/switch-pico.uf2`, then exits without invoking `picotool load` or flashing hardware. Pico SDK may still use picotool internally while generating build outputs. Without that flag, existing build-and-flash behavior is unchanged.
+
 - Requires `picotool` on your `PATH` (or set `PICOTOOL_PATH=/path/to/picotool`) and a connected Pico in BOOTSEL mode to automatically flash.
 - Set `ELF_PATH` to override the default `build/switch-pico.elf`.
 
-### Manual build
-```sh
-cmake -S . -B build -DSWITCH_PICO_LOG=OFF
-cmake --build build -j
-```
-This produces a `.uf2` you can flash (typically `build/switch-pico.uf2`).
+### Experimental Switch 2 scope
+
+- Uses VID:PID `057E:2069` and a reduced two-interface USB configuration: interface 0 is HID with 64-byte interrupt IN/OUT endpoints, and interface 1 is vendor-specific with 64-byte bulk IN/OUT endpoints.
+- Omits the captured audio interfaces, so it is not the full five-interface controller topology.
+- Supports only USB initialization and selection of input reports `0x05` and `0x09`. Other vendor command families are unsupported.
+- Packs buttons and sticks only. Switch 2 IMU data is not packed, and native HD-rumble output is not mapped to the legacy UART rumble path.
+- Has been validated only for compilation and descriptor consistency. PC enumeration and Nintendo Switch 2 console compatibility remain unverified.
+- Changes only the USB protocol facade. Existing UART1 wiring (GPIO4 TX, GPIO5 RX), 921600 baud rate, and UART report framing are unchanged.
 
 ### Manual UF2 flashing (BOOTSEL, no tools)
 If you already have a built (or use the pre-built one in `firmware/`) `.uf2`, you can flash it without rebuilding:
@@ -135,6 +178,7 @@ Flags:
 `build.py` can optionally update the **grip** colours in `controller_color_config.h` before building/flashing (default leaves the file unchanged):
 - Random grip colours: `python3 build.py --random-grip-color`
 - Set grip colours: `python3 build.py --grip-color FF00AA`
+- Grip colour overrides apply only to `legacy`; `build.py` rejects them when `--protocol switch2` is selected.
 
 ## Python bridge (recommended)
 Works on macOS, Windows, Linux. Uses SDL2 + pyserial.