docs: add CLAUDE.md and fuzzing section to README

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,49 @@
+# CLAUDE.md
+
+## Project overview
+
+Rust USB/IP server library and CLI tool. Two workspace crates: `lib/` (library) and `cli/` (binary). Linux only.
+
+## Security model
+
+Host is trusted, client (in VM) is untrusted. All USB handling in userspace to minimize kernel attack surface. The host kernel's vhci_hcd driver is downstream of responses — don't assume it handles malformed data gracefully.
+
+## Building
+
+```bash
+nix build              # Nix
+nix develop -c cargo build  # Cargo via nix devShell
+```
+
+## Testing
+
+```bash
+nix develop -c cargo test -p usbip-rs
+```
+
+## Fuzzing
+
+Fuzz targets are in `lib/fuzz/` and exercise host-side codepaths against untrusted client input.
+
+```bash
+nix run .#fuzz-usbip                              # List targets
+nix run .#fuzz-usbip -- fuzz_urb_hid              # Single process
+nix run .#fuzz-usbip -- fuzz_urb_hid --fork=8     # Parallel (overnight)
+nix run .#fuzz-clean-usbip -- fuzz_urb_hid        # Prune fixed artifacts
+```
+
+Crash artifacts: `lib/fuzz/artifacts/<target>/`. Response validation is in `lib/src/fuzz_helpers.rs`.
+
+## Key architecture
+
+- `handle_urb_loop()` — main URB dispatch loop, generic over async transport
+- `handler()` — full connection handler (negotiation + URB loop), takes `UsbIpServer`
+- `UsbInterfaceHandler` trait — implement for new device types
+- Protocol parsing in `usbip_protocol.rs`, device model in `device.rs`
+- `MockSocket` in `util::mock` — used by both tests and fuzz targets
+
+## Conventions
+
+- No backwards compatibility concerns for the library API
+- `pub use` re-exports from `lib.rs` — e.g. `mock` module is available as `usbip_rs::mock::MockSocket`
+- Edition 2024

README.md

@@ -74,12 +74,40 @@ usbip-rs test_uac connect tcp:3240
 
 The UAC1 loopback device advertises 48kHz 16-bit stereo playback and capture. Audio sent to the playback endpoint is looped back to the capture endpoint.
 
+## Fuzzing
+
+Fuzz targets exercise the host-side codepaths that process untrusted client data. Requires nightly Rust (provided by the nix app).
+
+```bash
+# List available fuzz targets
+nix run .#fuzz-usbip
+
+# Run a single fuzz target
+nix run .#fuzz-usbip -- fuzz_urb_hid
+
+# Run with 8 parallel processes, auto-restart on crash (for overnight runs)
+nix run .#fuzz-usbip -- fuzz_urb_hid --fork=8
+
+# Re-check saved crash artifacts and delete the ones that no longer reproduce
+nix run .#fuzz-clean-usbip -- fuzz_urb_hid
+```
+
+Targets:
+- `fuzz_parse_command` — protocol deserialization
+- `fuzz_handle_client` — full connection lifecycle (negotiation + URB loop)
+- `fuzz_urb_hid` — URB loop with HID keyboard device
+- `fuzz_urb_uac` — URB loop with UAC1 audio device (isochronous)
+- `fuzz_urb_cdc` — URB loop with CDC ACM serial device (bulk)
+
+Crash artifacts are saved to `lib/fuzz/artifacts/<target>/`.
+
 ## Project structure
 
 ```
 ├── cli/          CLI binary (usbip-rs)
 ├── lib/          Library crate (usbip-rs)
 │   ├── src/
+│   ├── fuzz/     Fuzz targets (cargo-fuzz)
 │   └── examples/
 └── flake.nix     Nix build
 ```