docs: move development notes to NOTES.md and describe the CLI in the README

NOTES.md

@@ -1,18 +1,32 @@
-# IDE Setup (Windows)
+## Layout
 
-- Installed Intel Quartus Lite from https://www.intel.com/content/www/us/en/software-kit/825278/intel-quartus-prime-lite-edition-design-software-version-23-1-1-for-windows.html
-- Installed Arduino IDE 2 `choco install arduino`
+- `fpga/rtl/`: Verilog sources; `fpga/sim/`: testbenches; `fpga/src/`: Quartus project
+- `arduino/strix/`: device firmware
+- `arduino/strix_capture/`: characterization tool firmware, used by `tools/jitter.py`
+- `arduino/strix_nina_passthrough/`: connects USB to the WiFi module's UART for flashing its firmware
+- `arduino/libraries/`: `StrixFPGA` (FPGA boot, SPI access, embedded FPGA image), `VidorBoot` (vendored subset of Arduino's VidorPeripherals), and Arduino's `WiFiNINA`, `Arduino_SpiNINA` and `ArduinoBLE`, patched to drive the WiFi module through the FPGA's pin pass-through (see `arduino/libraries/STRIX-NINA-LIBRARIES.md`)
+- `tools/`: `strix.py` command-line client, FPGA image converter, jitter and statistics experiments, API check
 
-# Project Setup
+## Development (Linux)
 
-based on https://docs.arduino.cc/tutorials/mkr-vidor-4000/vidor-quartus-vhdl/
+The toolchain is managed by [devbox](https://www.jetify.com/devbox): `arduino-cli`, Intel Quartus Prime Lite (Cyclone 10 LP only, through a Nix flake in `nix/`), Icarus Verilog, Rust, and [uv](https://docs.astral.sh/uv/) for the Python tools (`pyproject.toml`, `uv.lock`).
 
-- New Project Wizard
-    - 'strix' for name and top level design entity
-    - Skip next screen
-    - Family, Device, Board Settings > Name filter: `10CL016YU256C8G`
-    - Finish
+1. `devbox run setup`: install the Arduino SAMD core (libraries are vendored in `arduino/libraries/`)
+2. `devbox run sim`: run the FPGA testbenches
+3. `devbox run fpga`: build the FPGA bitstream (about 10 minutes)
+4. `devbox run image`: embed the bitstream in the `StrixFPGA` library
+5. `devbox run build`, then `devbox run upload`: build and flash the firmware (`PORT` defaults to `/dev/ttyACM0`)
+6. `devbox run api-check`: end-to-end check of the USB API
+7. `devbox run strix <command>`: command-line client over USB (see the README)
 
-- Import Pin Settings:
-    - Menu > Assignments > Import Assignments > vidor_s_pins.qsf 
-        - from https://github.com/vidor-libraries/VidorFPGA/blob/master/constraints/MKRVIDOR4000/vidor_s_pins.qsf 
+Serial access requires membership in the `dialout` group. If a firmware leaves the board unable to stay on USB, enter the bootloader: hold reset while plugging in, release, then tap reset once quickly. For characterization, flash the capture tool with `devbox run upload-capture` and use `devbox run jitter <freq|rings|sweep|output|health|stats|amp|pairs>`. `devbox run onod-build` builds the onod3000 test suite used by `jitter output` and `api-check`.
+
+### WiFi module firmware
+
+BLE needs NINA firmware 3.0.0 or newer (the board shipped with 1.0.0). To flash Arduino's [nina-fw](https://github.com/arduino/nina-fw/releases) `NINA.bin`:
+
+1. Flash the passthrough: `devbox run -- arduino-cli compile -u -p /dev/ttyACM0 --fqbn arduino:samd:mkrvidor4000 --libraries arduino/libraries arduino/strix_nina_passthrough`
+2. `devbox run -- uv run esptool --chip esp32 --port /dev/ttyACM0 --baud 115200 write-flash 0 NINA.bin`
+3. Flash the STRIX firmware again (`devbox run upload`); `wifi probe` reports the module firmware version.
+
+The passthrough forwards reliably at 115200 baud, not at 460800.