feat(onboard): emit an App Lab import zip + host-for-download flow

App Lab's own export/import mechanism is a zip whose top dir is the app
name. package-onboard-app.sh now emits dist/apess-onboard.zip alongside the
bundle — verified to round-trip through `arduino-app-cli app import` (a
mac-built zip imports cleanly; no board needed to package). Distribution is
now: build → host the zip on apess.redclaw.dev/download → student downloads
→ App Lab "Import an app" → Run. Replaces the unverified QR path. ONBOARDING
updated with the download/import steps + first-Run auto-install note.

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

deploy/uno-q/ONBOARDING.md

@@ -13,13 +13,13 @@ matrix, the I2C scan — runs through this. The board never needs the Zephyr fla
 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 the distributable app (once)
+## 1. Instructor — build + host the app (once)
 
-Bake the cloud token + all assets into a shareable App Lab app:
+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              # → deploy/uno-q/dist/apess-onboard
+./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
@@ -28,22 +28,29 @@ 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).
 
-Import it once to smoke-test, or share it to students:
+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
-arduino-app-cli app new --from-app deploy/uno-q/dist/apess-onboard   # instructor test
+# copy dist/apess-onboard.zip to the production static path, e.g.
-# then in App Lab: open the app → Share → QR
+#   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. **Import** the "APESS Onboard" app (scan the QR).
+2. Download the app zip from `apess.redclaw.dev/download/apess-onboard.zip`.
-3. Click **Run**. The node comes up in one container: it flashes the resident
+3. In App Lab → **Import an app** → pick the zip. It's added to your workspace
-   responder, launches the cloud agent, mints its `.secret_key`, self-registers
+   with its files, bricks, and libraries.
-   to the team's APESS laptop, and scrolls a **claim code** on the LED matrix.
+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.
+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)
 

deploy/uno-q/package-onboard-app.sh

@@ -83,14 +83,23 @@ else
   echo "  (no web-dist — the node dashboard link will 404; students use the APESS wizard)"
 fi
 
-echo
 ok "bundle ready: $OUT"
+
+# The App Lab-importable archive: a plain zip whose top dir is the app name.
+# `arduino-app-cli app import <zip>` and the App Lab UI "Import an app" both
+# accept it (verified round-trip). This is what we HOST for students to download.
+ZIP="${ZIP:-$(dirname "$OUT")/$(basename "$OUT").zip}"
+( cd "$(dirname "$OUT")" && rm -f "$ZIP" && zip -rq "$ZIP" "$(basename "$OUT")" -x '*.DS_Store' )
+ok "import archive: $ZIP ($(du -h "$ZIP" | cut -f1))"
+
 cat <<EOF
 
 Distribute it:
-  1. Import onto a board (instructor test):
+  • HOST for students: copy "$ZIP" to the production download path, e.g.
-       arduino-app-cli app new --from-app "$OUT"
+      apess.redclaw.dev/download/apess-onboard.zip
-  2. Or share to students: open the app in App Lab → Share → QR. Students scan to
+    Students download it, open App Lab → "Import an app" → pick the zip → Run.
-     import, then Run. Set APESS_URL per team if not using mDNS
+  • Instructor smoke-test on a board:
-     (edit .zeroclaw/apess-node.env, or point apess-api.local at the laptop).
+      arduino-app-cli app import "$ZIP"
+  • APESS_URL: default is mDNS apess-api.local. Set per team by editing
+    .zeroclaw/apess-node.env before packaging, or pass APESS_URL=http://<laptop>:3000.
 EOF