apress/deploy/uno-q/ONBOARDING.md

APESS onboarding — fully containerized

The setup runbook. For the participant journey (each screen's job, the module→ADD-layer map, open design questions), see WORKSHOP-FLOW.md.

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, Telegram, the LED matrix (text, patterns, and the 0..N counter), 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):

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, matrix_pattern, matrix_count, i2c_scan), the single-default-agent config (those tools allowlisted), the skills, the responder sketch, and the baked token. Telegram ships disabled with an empty token (a tokenless channel would spam startup probes) — the Phase-1 wizard flips it on when a team opts in. 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:

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