diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1a496c3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# hello_usb (Pico) — Build & Flash
+
+Quick instructions to compile and flash the `hello_usb` project for Raspberry Pi Pico / RP2-based boards.
+
+## Prerequisites
+
+- GNU Arm Embedded Toolchain (arm-none-eabi)
+- CMake (>= 3.13) and Ninja
+- Pico SDK (included in this repo as `pico-sdk/`) or installed separately
+- `picotool` (optional, for USB flashing) or OpenOCD + SWD adapter (for debugging/flashing)
+- On macOS: install tools via Homebrew where available (e.g. `cmake`, `ninja`, `open-ocd`)
+
+Ensure `arm-none-eabi-gcc`, `cmake`, and `ninja` are available in `PATH`:
+
+```bash
+which arm-none-eabi-gcc cmake ninja
+```
+
+## Build
+
+From the project root (where `CMakeLists.txt` lives):
+
+```bash
+# set PICO_SDK_PATH to the bundled SDK in this repo (adjust if using system SDK)
+export PICO_SDK_PATH=$(pwd)/pico-sdk
+
+mkdir -p build
+cd build
+# configure & generate (Ninja)
+cmake .. -G Ninja
+# build
+ninja
+```
+
+After a successful build you should find artifacts under `build/` such as `hello_usb.uf2` and `hello_usb.elf`.
+
+## Flashing
+
+Choose one of the methods below.
+
+- UF2 (mass-storage) — easiest for Pico in BOOTSEL mode:
+
+  1. Hold BOOTSEL on the Pico and connect it via USB.
+  2. Copy `build/hello_usb.uf2` onto the mounted RPI-RP2 mass storage device.
+
+- picotool (USB) — if `picotool` is installed:
+
+```bash
+# Example (adjust path if needed):
+picotool load build/hello_usb.uf2 -f -x
+```
+
+- OpenOCD + SWD (CMSIS-DAP) — for programmers/debugging:
+
+```bash
+# Example template (adjust openocd script paths and target cfg for your board):
+openocd -s /path/to/openocd/scripts \
+  -f interface/cmsis-dap.cfg \
+  -f target/rp2040.cfg \
+  -c "adapter speed 5000; program \"$(pwd)/build/hello_usb.elf\" verify reset exit"
+```
+
+The VSCode workspace already includes tasks for building and flashing:
+- `Compile Project` — runs `ninja -C build`
+- `Run Project` — uses `picotool` to load the target (see `.vscode/tasks` / your task runner)
+
+## Troubleshooting
+
+- If CMake cannot find the SDK, ensure `PICO_SDK_PATH` points to the `pico-sdk/` folder.
+- Verify the toolchain: `arm-none-eabi-gcc --version`.
+- If UF2 flashing doesn't work, try `picotool` or an SWD programmer (OpenOCD + CMSIS-DAP).
+- For OpenOCD errors, ensure correct interface/target `.cfg` files and that the adapter is connected.
+
+## Notes
+
+- Modify the `cmake` configuration or `CMakeLists.txt` if you need custom board or build options.
+- If using a centralized Pico SDK installation, set `PICO_SDK_PATH` to that location instead of the bundled `pico-sdk/`.
+
+If you want, I can run the build here or add a short `Makefile` or CI job to automate builds.