Omar SobhandClaude Opus 4.8
6c82b79b01
WORKSHOP-FLOW.md is the participant-journey / design-review doc: local-stack launch, the module→ADD-layer map, each screen's job (does/sees/system), and the open design questions. Mirrors the shared flow artifact. ONBOARDING refresh: matrix tools now include matrix_count; Telegram ships disabled (no more tokenless probe spam); drop the removed "Refine" step; cross- link the two docs. Co-Authored-By: Claude Opus 4.8 <[email protected]>
86 lines
3.9 KiB
Markdown
86 lines
3.9 KiB
Markdown
# 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`](./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):
|
|
|
|
```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`, `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:**
|
|
|
|
```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`.
|