docs(uno-q): REQUIREMENTS.md for the self-host USB workshop

Student pre-workshop checklist for the confirmed model: each team runs the Docker
stack locally + board over USB, everything localhost, board auto-connects (no
code, no accounts). Lists the board-laptop prereqs (Docker, adb, git, disk,
pre-fetched bundle), the on-the-day flow, a pre-flight self-check, and an
instructor checklist for the remaining decisions.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

deploy/uno-q/REQUIREMENTS.md

@@ -0,0 +1,102 @@
+# APESS 2026 Workshop — Laptop Prerequisites
+
+**"Design the Agent Your Building Deserves" · 27 July · a 5-hour build session.**
+Do these **before you arrive** so we spend the session building, not installing.
+
+> Companion docs: [`WORKSHOP-FLOW.md`](./WORKSHOP-FLOW.md) (what you'll do) ·
+> [`ONBOARDING.md`](./ONBOARDING.md) (how the board comes up).
+
+---
+
+## How it runs (so the prerequisites make sense)
+Each team runs the **whole platform on its own laptop** — a small Docker stack (web + API) that
+comes up with **one command**. Your **Arduino Uno Q** plugs into that same laptop over **USB**.
+Everything is **localhost**: the browser, the API, and the board all talk on your machine. Once
+the stack is up and the board is plugged in, it **auto-connects to your team — no codes, no
+accounts, nothing over the network.** (WiFi isn't used during the workshop; it's only for a future
+step that registers boards with our production cloud.)
+
+So each team needs **one "board laptop"** with a few things pre-installed. Extra teammates just
+need a browser pointed at that laptop.
+
+---
+
+## TL;DR
+- **Board laptop:** install **Docker**, **adb**, and **git**; pull the workshop bundle ahead of time.
+- **Everyone else:** a modern browser is enough.
+- **No accounts, no API keys** — the AI cloud access is baked into the board app.
+
+---
+
+## What the workshop provides (do NOT install)
+- **Arduino Uno Q (4 GB)** board + **USB-C cable** — one per team.
+- **ADXL355 accelerometer(s)** + wiring — the FabLab kit.
+- **Cloud AI access** — baked into the board app. **No Anthropic/Claude account needed.**
+- The **web app** itself (you run it locally from the bundle below).
+
+---
+
+## The team "board laptop" — pre-install these (large downloads, do them at home)
+1. **Docker** — Docker Desktop (macOS/Windows) or Docker Engine + Compose (Linux).
+   Verify: `docker run hello-world` succeeds.
+2. **adb** (Android platform-tools) — the USB bridge to the board.
+   Verify: `adb version` prints a version. (macOS: `brew install android-platform-tools`.)
+3. **git** — to fetch the workshop bundle. Verify: `git --version`.
+4. **~10 GB free disk** — Docker images (web + API) + the board's App Lab base image (~0.9 GB).
+5. **The workshop bundle, pre-fetched** so you're not downloading on the WiFi at 14:00:
+   ```sh
+   git clone <workshop-repo-url>        # [instructor: final repo/bundle URL]
+   cd <repo>/deploy/lan
+   docker compose up -d --build         # pre-build the images once, at home
+   docker compose down                  # then stop until the day
+   ```
+   (Also pre-pull the App Lab base image on the board — it's fetched on first Run.)
+
+## Everyone else on the team
+- A **current browser** (Chrome/Edge recommended; Firefox works). That's it — you'll open the board
+  laptop's local URL.
+
+---
+
+## What you'll do on the day (no accounts, no claim codes)
+1. **Bring the stack up:** `cd deploy/lan && docker compose up -d` → open **`http://localhost:8090/`**.
+2. **Get the board app:** in Team Registration, click **Download the board app** (served by your own
+   stack), then on the Uno Q: **App Lab → Import an app → pick the zip → Run.** `[instructor: confirm the App Lab access flow for the room]`
+3. **Attach the board:** plug the Uno Q into the board laptop over USB and run
+   **`./deploy/lan/connect-board.sh`** (or `--watch` to keep it auto-attaching).
+4. **It just connects:** type your team name and the board **auto-binds to your team** — no code.
+   Unplug/replug is handled automatically; a **Disconnect / Reconnect** control is there if you need it.
+5. **Build:** walk Modules 1–3, submit your Agent Design Document.
+
+---
+
+## Pre-flight self-check (before you travel)
+- [ ] **(Board laptop)** `docker run hello-world` works.
+- [ ] **(Board laptop)** `adb version` and `git --version` work.
+- [ ] **(Board laptop)** Ran `docker compose up -d --build` once (images built) and opened `localhost:8090`.
+- [ ] Laptop charged + charger packed (5-hour session).
+- [ ] A current browser.
+
+---
+
+## No accounts to create
+- ❌ No Anthropic / Claude account or API key — the cloud key is baked into the board app.
+- ❌ No claim codes — in this local USB setup the board auto-connects.
+- ✅ Everything is localhost; nothing depends on the room WiFi.
+
+---
+
+## Notes for the curious (why these specific tools)
+- **Docker** runs the web + API stack in one command, identically on every laptop.
+- **adb** carries the board over USB; the API (in a container) reaches it via `host.docker.internal`.
+- The web runs on **`:8090`** (not `:8080`) because `:8080` is the board's own port, forwarded over adb.
+
+---
+
+## Instructor checklist (finalize before publishing to students)
+- [ ] **The workshop bundle URL** (git repo or a downloadable archive) students clone/pull.
+- [ ] **Pre-built image distribution** — consider publishing `apess-web`/`apess-api` to a registry (or a
+      USB `docker load` bundle) so teams `docker compose up` without a source build on the day.
+- [ ] **Exact Arduino App Lab access** on the Uno Q for the room (and whether it needs any login).
+- [ ] **Pre-seed** the ~0.9 GB App Lab base image locally so 9 teams don't each pull it live.
+- [ ] Decide whether `connect-board.sh --watch` runs via a small launchd/systemd unit (hands-free re-plug).