# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Claude Code-specific notes for this project. For architecture, hard rules, and full
command reference — see [AGENTS.md](AGENTS.md), and read it before starting work.

## Quick orientation

DeskLock = firmware for a Waveshare ESP32-P4 round-display device (`firmware/`, ESP-IDF/C/LVGL)
plus a voice gateway container (`gateway/`, Python/FastAPI, port 8600) that bridges device
audio to the Tatlock butler API. The device↔gateway WebSocket protocol lives in
`docs/architecture.md` and must stay in sync with both implementations.

## Commands

```bash
# Firmware (requires `source ~/esp-idf/export.sh` first; IDF ≥ 5.4)
cd firmware && idf.py build
idf.py -p /dev/ttyACM0 flash monitor

# Gateway
cd gateway && make setup    # once
make run                    # dev server :8600
make test                   # pytest; single test: .venv/bin/pytest tests/test_health.py -k healthz
make lint typecheck
```

## Gotchas

- **ESP-IDF is not yet installed on this machine** — install instructions in AGENTS.md.
- The firmware scaffold has never been built; treat BSP calls and sdkconfig as
  provisional until first successful `idf.py build` (see warning in AGENTS.md).
- The device flashes over USB-C on this server, but it doesn't currently enumerate
  (`/dev/ttyACM*` empty) and this user lacks the `dialout` group — resolve both before
  attempting to flash.
- Gateway speech deps are optional extras; `make setup` alone runs the app and tests
  without GPU/ML packages.