# APESS 2026 — Workshop flow **From a cold laptop to a shipped agent design.** The end-to-end path a team walks today — every screen, the job it does, what the person *does* versus what they *see*, and the spots we think the flow can get better. > Shared for design review. Companion to [`ONBOARDING.md`](./ONBOARDING.md) (the > operational runbook) — this doc is the *journey*, that one is the *setup*. `Arduino Uno Q · 4GB` · `ZeroClaw edge agent` · `FabLab Torino` · `27 Jul 2026` --- ## Before the room fills — launch the local stack The workshop runs **on the team's own laptop**, right next to the board — a cloud API can't reach devices behind the room's NAT. One command brings up the web app and the API together. ```sh # bring up web + API on the team laptop (same WiFi as the board) cd deploy/lan cp .env.example .env # set ADMIN_CODE, JUDGE_CODE, FLEET_SECRET docker compose --env-file .env -f docker-compose.yml up -d --build # → web on :80 · API proxied same-origin at /api · board app served at /download/ # ✓ everyone (team · board · judge) opens http:/// ``` - **Local-first** — autonomous and offline-capable; nothing depends on the cloud during the session. - **Shared secret** — `FLEET_SECRET` must match the value baked into the board app, or self-registration is rejected. - **The board app** — the same laptop serves `/download/apess-onboard.zip`, the one-click App Lab app the team imports next. --- ## The through-line — one document, built five layers deep Every screen after setup adds a layer to the team's **Agent Design Document (ADD)**. The live board proves each capability as they design it — the modules aren't lessons, they're the ADD taking shape. | Layer | What it captures | Where | |-------|------------------|-------| | **Layer 1** | Domain & events | Module 1 | | **Layer 2** | Skills | Module 2 | | **Layer 3** | Policies & failure | Module 2 | | **Layer 4** | Harness | Module 3 | | **Layer 5** | Loops | Module 3 | --- ## The path, screen by screen ### ◦ Landing — `/` Sets the frame: a Claude agent on the edge, on real hardware. One door in. - **Does** — clicks **Start the workshop**. - **Sees** — the pitch, the presenter, the single call to action — nothing else competing. ### ① Team registration — `/workshop` · Phase 1 Claim a name, and claim a board — the moment the physical device becomes *this team's* agent. - **Does** — enters team name + members → downloads the board app → App Lab **Import → Run** → types the code the matrix scrolls → **Bind board**. - **Sees** — the board light up and scroll its claim code; on bind, three cards: *Say hi*, *Set up Telegram*, *Enable voice*. - **System** — node self-registers to the laptop; the bearer token moves pool→bridge and never touches the browser. - ⚠ **Watch** — first-connection is the busiest moment in the flow: binding plus three optional channel cards all land at once. Worth sequencing. ### ② Meet your agent — `/workshop/setup` · Phase 2 Introduce the agent, then name the **domain** it will serve — the seed the whole ADD grows from. - **Does** — opens the agent dashboard to explore, then **picks a domain** (e.g. "structural stress"). - **Sees** — the live ZeroClaw dashboard on the board; a single domain input that gates progress. - ⚠ **Watch** — the domain drives every later layer but is introduced almost in passing. Does it deserve more weight this early? ### ③ Module 1 — Domain & events — `/workshop/module1` · ADD Layer 1 Turn the chosen domain into the world the agent lives in and the events it reacts to. - **Sees** — their domain carried over, read-only. - **Does** — drafts Layer 1 of the Agent Design Document. ### ④ Module 2 — Skills & policies — `/workshop/module2` · ADD Layers 2–3 The hands-on core: talk to the agent, watch it use real tools on the board, then codify what it can do and what governs it. | Prompt | Tool | What it proves | |--------|------|----------------| | List the I2C devices on the bus | `i2c_scan` | reads real hardware | | Count to 100, once a second, on the matrix | `matrix_count` | a timed loop on the MCU | | Scroll GO CLAWS on the matrix | `matrix_text` | instant runtime display | - **Sees** — each tool's *actual result* stream back into the chat — no flashing, all in-container. - **Does** — runs all three → **What's next** unlocks Layers 2 & 3 (Skills, Policies & failure). - ⚠ **Watch** — Module 2 alone carries two ADD layers plus the only live-hardware moment — heavier than 1 and 3. Prompts must be phrased as commands, since that's what reliably drives tools. ### ⑤ Module 3 — Harness, loops & submit — `/workshop/add` · ADD Layers 4–5 Finish the design: where each decision runs, how it repeats, and what happens when a cycle fails — then ship it. - **Does** — drafts Layer 4 (Harness) & Layer 5 (Loops), reviews the assembled document, hits **Submit ADD**. - **Sees** — all five layers in one place; a confirmed submission. - **System** — the ADD lands in the API, ready for judging at `/judge`. --- ## Behind the scenes - **Fleet & scoring** — `/admin` shows every team, their phase and board health; `/judge` scores the submitted ADDs across the cohort. - **Persistence** — team, board binding and progress live in the browser; a refresh or nav-away resumes where they left off, until an explicit Disconnect. - **Reachability** — board and laptop share WiFi; the board self-registers over mDNS. If the room WiFi isolates clients, USB tethering is the fallback path. - **One agent, no flashing** — a single agent with all skills. Matrix and I2C run on a resident MCU responder over a socket — instant, in-container, nothing to re-flash mid-workshop. --- ## For the designer — where the flow could get better The honest open questions — where the current path works but feels uneven. This is what we'd love a fresh eye on. 1. **The first-connection pile-up** — binding the board and three optional channel setups (say-hi, Telegram, voice) all appear at the same instant. What's the right sequence — celebrate the connection first, then offer channels? 2. **Uneven module weight** — layers map 1 → 2·3 → 4·5 across the three modules, so Module 2 does double duty *and* owns the only live-hardware moment. Rebalance the pacing, or split Module 2? 3. **The domain's quiet debut** — the domain seeds all five layers yet is chosen in one small field during "Meet your agent." Does it need a stronger framing moment? 4. **Feedback for a slow agent** — a cloud round-trip can take seconds; a tool result streams back as plain lines. What does "the agent is thinking / working" look like so waiting never reads as broken? 5. **When the board drops** — USB unplugs and WiFi isolation are real. The recovery path exists but is invisible to the team — how should a disconnect surface, and guide them back? --- *Current-state workflow — APESS 2026 · RedClaw · Uno Q + ZeroClaw.* *A rendered version of this doc is available as a shareable web page (ask the presenter for the link).*