# 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).