apress/deploy/uno-q/WORKSHOP-FLOW.md

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

# 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://<laptop-ip>/

• 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).