Bringup target: AI-Thinker ESP32-A1S Audio Kit V2.2
(ES8388 codec). End target: custom PLIP PCB with Si3210
SLIC + RJ9 retro handset (per
docs/superpowers/specs/2026-04-08-plip-telephone-design.md).
Three FreeRTOS tasks share state via a queue:
- phone_task (core 1): off-hook GPIO interrupt + ring
- audio_task (core 0): drains command queue, routes to
ES8388 (dev kit) / Si3210 (PCB) via ESP32-audioI2S
- network_task (core 0): WiFi station + REST server
REST contract for the Zacus master ESP32 to drive PLIP:
- POST /ring {duration_ms}
- POST /play {source: "sd:/..." | "http://tower:8001/..."}
- POST /stop
- GET /status -> {off_hook, playing}
Pin assignments live in platformio.ini build_flags so the
dev kit -> PCB swap stays mechanical (just rewire to
Si3210 SPI + INT and switch the codec init in
audio_task).
MVP scope (option b in the brainstorm):
- ring on demand
- off-hook GPIO -> notify master
- MP3 playback from SD
- WiFi REST endpoint
Out of v1 (deliberately deferred):
- Bluetooth Classic A2DP/HFP (still in the design doc)
- Si3210 driver (when PCB lands)
- OTA via desktop FirmwareManager (after bringup stable)
Files:
- platformio.ini (espressif32@6.5.0, esp32dev board with
custom partitions + ESP32-A1S build flags)
- partitions/plip_4mb.csv (2x OTA app slots + LittleFS)
- src/main.cpp + 3 task .cpp files (skeleton, log-only)
- README.md (architecture, REST contract, pin map,
9-step roadmap, submodule conversion)
- CLAUDE.md (nested guidance for Claude Code)
- .gitignore
Inlined for now; convert to a git submodule once a remote
URL is provisioned (procedure documented in README).
Root CLAUDE.md "Firmware" surface and "Where to Look"
table updated.
Acceptance: directory layout + build config + skeleton
sources land. No compile validation in this commit
(PlatformIO not on the workstation per the Q1=ESP32-A1S
dev kit bringup decision).
Phase 4 of the V3 fusion plan. The atelier app now embeds
the real R3F 3D simulation in its right pane. P6 also
absorbed (apps/simulation removed, desktop bundle updated).
Migrated from apps/simulation/src (via git mv to preserve
history):
- scene/{Room, RoomScene, PuzzleStation, PuzzleStations,
RtcPhone, NpcBubble} (6 files)
- puzzles/{P1Sound, P5Morse, P6Symbols, P7Coffre}
- modes/{Sandbox, Demo, Test}Mode (Tailwind classes
replaced with inline styles since Tailwind was never
configured in V3)
- store/simStore.ts -> stores/simStore.ts (matches
atelier's plural convention)
Atelier wiring:
- StagePane: lazy(R3F Canvas + RoomScene) + lazy mode HUD
selected by simStore.mode. Stale badge still consumed
from runtimeStore.isStale (P5 will trigger).
- ConsolePane: switched mode binding from runtimeStore to
simStore (mode is a sim concern, not editor↔stage sync).
- runtimeStore: dropped `mode` field (now in simStore).
Kept currentIr/pendingIr/isStale/setPendingIr/
commitPendingIr for the live-diff flow (P5).
- atelier tsconfig: types: ["@react-three/fiber"] for JSX
intrinsics.
- @types/three added to atelier devDeps.
scenario-engine bug fixes (the 3 tests skipped in P0):
- yaml-parser now converts puzzles dict (YAML format) to
array (TS contract) at parse time. The YAML keeps puzzles
as a keyed dict for human readability; consumers expect
PuzzleConfig[]. This fixes 2 tests that called
scenario.puzzles.find/.reduce.
- getScore test realigned with engine implementation:
fast-completion bonus applies continuously when elapsed
is below 80% of target, so total at t=0 is base + bonus
= 1200, not just base = 1000. The test name + body now
documents this behaviour. (Whether engine should only
apply the bonus on game end is a separate question for
future engine refactor.)
Decommission (early P6 for simulation):
- git rm -r apps/simulation/
- desktop/scripts/build-frontends.sh: now iterates over
[atelier, dashboard] and uses pnpm instead of npm
- frontend-v3/CLAUDE.md: now describes 2 apps + 3 packages
- root CLAUDE.md: Authoring line lists atelier + dashboard
Acceptance:
- pnpm typecheck: 8/8 green
- pnpm test: 9/9 (atelier:0, dashboard:5, scenario-engine:9
ALL passing including the 3 previously skipped)
- pnpm build: 5/5 green
- Atelier production chunks: shell 76 kB, blockly 698 kB
(lazy), three 1.25 MB (lazy), R3F scene 10 kB, mode HUDs
~1 kB each (lazy)
Phase 6 scope reduced to: nothing left. The "decommission +
propagation" work was absorbed into P3 (editor) and P4
(simulation + desktop bundle + CLAUDE.md). Phase 5 (live-
diff wiring) is the only remaining phase.
V2 was the legacy single-app Vite playground. Per the
2026-05-01 atelier design brainstorm, V3 is the sole
authoring target going forward. MediaManager and
NetworkPanel features explicitly retired (no porting).
Removed:
- frontend-scratch-v2/ entirely (50 files, ~11k LOC)
Retargeted to frontend-v3 + pnpm:
- Makefile: FRONTEND_DIR, frontend-typecheck/test/build
(renamed from frontend-lint as eslint not yet wired in V3)
- tools/dev/zacus.sh: FRONTEND_ROOT, action commands
- tools/dev/zacus_tui.py: action_frontend_tests + build cwd
- .github/workflows/validate.yml: pnpm/action-setup,
cache: pnpm, --frozen-lockfile, typecheck step added
Documentation cleanup:
- Root CLAUDE.md: Architecture, Where to Look, Nested
Guidance lines purged of V2; pointer to atelier design
doc added
- frontend-v3/CLAUDE.md: V2 vs V3 section removed; editor
description points to fusion design doc
- desktop/CLAUDE.md: V2 anti-pattern removed
- specs/CLAUDE.md: cross-stack pair example updated to
packages/scenario-engine
Archive: tag archive/frontend-scratch-v2-final on the
commit immediately preceding deletion preserves the last
state where V2 still worked.
Acceptance:
- rg "frontend-scratch-v2" in code paths -> 0 hits
- make frontend-test -> 11/11 green (3 skipped)
- make frontend-build -> 6/6 green
- npc_phrases.yaml: full phrase bank (hints, personality,
adaptation, bridges, false leads, ambiance) in French
- generate_npc_pool.py: batch TTS generator (Piper API)
- test_npc_engine.py: 21 unit tests for trigger logic
- test_npc_phrases_schema.py: YAML schema validation (12 tests)
- Fix FAST_PROGRESS guard: use absolute time limit to prevent
false positives after several minutes on a scene
Impact: Sprint 3 NPC data layer complete. 33 tests passing.
L'électron rare