# APESS onboarding — fully containerized

A team needs two things running: the **APESS stack on their laptop** and the
**ZeroClaw node on their Uno Q**. Both are containers. Nothing installs to a host.

```
LAPTOP:  docker compose up  →  apess-api + apess-web        (deploy/lan)
BOARD :  App Lab → Run       →  ONE container = daemon + relay + responder
```

Everything a team does — say-hi, the module chat, Refine, Telegram, the LED
matrix, the I2C scan — runs through this. The board never needs the Zephyr flash
toolchain or Linux `/dev/i2c`: the matrix is driven by a resident responder and
I2C is scanned on the MCU (Wire), both over the RouterBridge relay.

## 1. Instructor — build + host the app (once)

Bake the cloud token + all assets into an App Lab **import archive** (a zip):

```sh
export ANTHROPIC_OAUTH_TOKEN=sk-ant-oat01-…        # baked into the bundle
./deploy/uno-q/package-onboard-app.sh              # → dist/apess-onboard/ + dist/apess-onboard.zip
```

The bundle contains: the ZeroClaw binary (matrix_text + i2c_scan), the
single-`default`-agent config (matrix + i2c_scan allowlisted, Telegram-ready),
the skills, the responder sketch, and the baked token. It ships **without** a
`.secret_key` (each board mints its own on first Run) and **without** any team's
Telegram token. The `dist/` output is gitignored (it holds the token).

The zip is a standard App Lab export archive (top dir = app name) — verified to
round-trip through `arduino-app-cli app import`. **Host it for download:**

```sh
# copy dist/apess-onboard.zip to the production static path, e.g.
#   apess.redclaw.dev/download/apess-onboard.zip
```

## 2. Student — bring up their board (fresh OR pre-existing)

1. Open **App Lab** on the Uno Q (it ships with the board).
2. Download the app zip from `apess.redclaw.dev/download/apess-onboard.zip`.
3. In App Lab → **Import an app** → pick the zip. It's added to your workspace
   with its files, bricks, and libraries.
4. Click **Run**. The node comes up in one container: on first Run it
   auto-installs the sketch's core + libraries (RouterBridge, ArduinoGraphics),
   flashes the resident responder, launches the cloud agent, mints its
   `.secret_key`, self-registers to the team's APESS laptop, and scrolls a
   **claim code** on the LED matrix.

Fresh or pre-existing board is identical — Run is idempotent; it just (re)starts
the node. (First Run also pulls the ~839 MB `python-apps-base` image — pre-seed
that on the room's network if 15 teams start at once.)

## 3. Student — the wizard (laptop)

- Open `http://<laptop>/` → **Start the workshop**.
- **Phase 1:** team name + members → type the **claim code** the matrix is
  scrolling → board bound (state persists in `localStorage`; a Disconnect button
  is the only thing that drops it).
- Say hi to the agent, optionally set up **Telegram** (writes the token to the
  node and reloads it), toggle **Voice**.
- **Phase 2:** open the node, name the domain. Then the modules.

## `APESS_URL` — how the board finds the laptop

The board self-registers to `APESS_URL` (default `http://apess-api.local:3000`).
Options, easiest first:
- **mDNS:** have the `deploy/lan` box advertise `apess-api.local` (zero-config
  for students).
- **Per-team:** set `APESS_URL` in the app's `.zeroclaw/apess-node.env`, or pass
  `APESS_URL=http://<laptop-ip>:3000` when packaging.

## Reachability

The laptop's API must reach the board over the workshop WiFi. Verify the AP
allows **client-to-client** traffic (many guest networks isolate clients). See
`deploy/lan/README.md`.