L'électron rare
d7e4e52fd3
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
1.7 KiB
1.7 KiB
Specs
Contracts between firmware, frontends, tooling, and AI agents. Treat each spec as a versioned interface — a breaking change here triggers work in 2+ subsystems.
Canonical Specs
| Spec | Governs |
|---|---|
ZACUS_RUNTIME_3_SPEC.md |
Scenario IR + execution semantics |
AI_INTEGRATION_SPEC.md |
Agent layer (hints, voice, vision, TTS, audio_gen, MCP) |
FIRMWARE_WEB_DATA_CONTRACT.md |
ESP32 ↔ frontend HTTP/WebSocket payloads |
MCP_HARDWARE_SERVER_SPEC.md |
MCP stdio tools (6) for hardware interaction |
MEDIA_MANAGER_* |
Media manager (firmware/frontend/runtime/sync) |
STORY_DESIGNER_SCRATCH_LIKE_SPEC.md |
Frontend Blockly-like authoring |
STORY_RUNTIME_API_JSON_CONTRACT.md |
Runtime API JSON shape |
LOCAL_AI_STUDIO_SPEC.md |
Local AI studio integration |
QA_TEST_MATRIX_SPEC.md |
QA matrix + acceptance criteria |
Editing Rules
- A spec change is a contract change. List affected consumers in the PR description.
- Bump the version header at the top of the file when altering existing fields; never silently rename keys.
- New spec docs must be linked from root
CLAUDE.md"Canonical Files" if they introduce a new contract. - Pair runtime/frontend spec changes — the matching
tools/scenario/compile_runtime3.pyandfrontend-v3/packages/scenario-engine/src/engine.tsupdates ship in the same PR.
Anti-Patterns
- "Implementation detail" comments in specs — if it's not part of the contract, remove it
- Adding fields without specifying optionality, defaults, and version
- Letting the IR drift between Python compiler and TS runtime without updating the spec first
- Documenting hardware pins/ports here — they belong in
ESP32_ZACUS/firmware sources