AutoFilm-ESP32/AGENTS.md

# Agent conventions — AutoFilm-ESP32

Instructions for humans and coding agents working in this repository.

## Product constraints

- Default temperatures, step times, and CW/CCW rotation counts for C41, E6, ECN-2, B&W, Custom, and B&WREV **do not change** unless a commit message explicitly says so and the recipe table in `docs/CURRENT_STATE.md` is updated in the same change.
- The machine **must always be stoppable** while a step is running: keypad Esc (`'X'`, 4 across / 4 down) and, on the S3 panel, a STOP control. Stop drops motor enable immediately, then offers Resume or return to step select.
- UI must not block on motor motion, OneWire conversion, or melody playback.

## Branch and docs

- Integration branch is **`develop`**. Feature and refactor work is done on a branch cut from `develop`, then opened as a PR **into `develop`**.
- Do not PR this work into `main`. `main` is not the day-to-day integration line.
- Active work branch for this refactor: `refactor/esp-idf-modular-ui` (rebase onto `develop` if the branch still points at `main`).
- Architecture intent: `docs/CURRENT_STATE.md`, `docs/TARGET_ARCHITECTURE.md`, `docs/CICD.md`.
- Implementation sessions: `docs/megaplans/REFACTOR-MEGAPLAN.md` then exactly one `docs/megaplans/refactor/Pxx-*.md`. Do not start the next phase in the same session.
- Do not commit secrets (Git tokens, Wi-Fi passwords, `sdkconfig` with provisioned keys).

## Layout

| Path | Role |
| --- | --- |
| `src/`, `include/` | Legacy Arduino sources; shrink, do not grow, except bugfixes needed for the port |
| `main/` | IDF entry |
| `components/app_*` | Application: process table, machine, UI |
| `components/ui_cmd` | Command/event types only |
| `components/hal_*` | Hardware adapters |
| `components/board_*` | Pin maps and board bring-up |
| `docs/` | Design notes |
| `.gitea/workflows/` | Gitea Actions (tests + firmware builds) |

New behaviour goes into `components/`, not into larger `menu.cpp` files.

## Framework policy

- Build system is **ESP-IDF**. PlatformIO + Arduino remains only until the IDF skeleton compiles both boards.
- **Arduino-as-component** is allowed as a bridge for AccelStepper, Keypad, LiquidCrystal_I2C, OneWire, DallasTemperature.
- Treat Arduino as debt:
  - No Arduino types (`String`, `Keypad`, `AccelStepper`, `LiquidCrystal_I2C`) in headers of `app_machine`, `app_process`, or `ui_cmd`.
  - Do not add new Arduino library dependencies.
  - Prefer IDF drivers (GPIO, RMT, I2C, LEDC, `esp_timer`, `esp_lcd`) for new work.
- Two firmware flavours: `board_wroom` and `board_jc4827w543`. Gate pins and peripherals with board CMake, not `#ifdef` sprinkled through the state machine.

## Concurrency

- One responsibility per task: input, UI, machine, motor, temperature, audio.
- Cross-task data: FreeRTOS queues, task notifications, atomics. No unsynchronised use of `lcd` / `stepper` / `sensors`.
- ISR / stop path: set a flag, disable motor EN, `xQueueSendFromISR` / `xTaskNotifyFromISR`. No heap, no `delay`, no LCD from ISR.
- Do not `vTaskDelete` worker tasks after startup. Do not disable the task watchdog to “make it work”.
- `vTaskDelay` / `esp_timer` instead of busy-wait `millis()` loops.

## UI / machine split

- UI emits commands; machine emits events. See `docs/TARGET_ARCHITECTURE.md`.
- Touch and keypad are input adapters. They produce the same commands.
- Display adapters render events. Machine code must compile with no display driver linked (except in tests that stub HAL).

## Code style

- C11 for new IDF components; C++17 only where an existing Arduino library forces it, isolated in `hal_*`.
- `snake_case` for new functions and files; existing camelCase stays until that file is rewritten.
- 4-space indent to match the current tree.
- No raw `new` / `malloc` for per-frame strings. No `String` concatenation on the control path.
- Log with `ESP_LOGx` tags (`machine`, `motor`, `ui`, `temp`, `input`), not `Serial.print`.
- Errors are `esp_err_t` across HAL boundaries.

## Recipes

- Recipe tables live in `app_process` (or today’s `devSequence.cpp` until moved).
- Session time nudges (±5 s) are RAM overlays, not edits of the const defaults.
- Persistent custom profiles are out of scope until designed; do not half-add NVS.

## Hardware notes

- WROOM pins are defined in the legacy `config` headers; do not silently reuse them on the S3 panel.
- JC4827W543C: NV3041A 480×272 QSPI, GT911 on I²C, limited free IO. Confirm any new GPIO against the board pin table before assigning STEP/DIR/EN/1-Wire.
- Motor enable is active LOW on the current WROOM wiring. Safe state is disabled.

## Commits and review

- Cut work from `develop`. Open PRs against `develop`.
- Imperative commit subjects (`Add machine stop notify`, not `Added`).
- One concern per commit when practical (HAL wrap ≠ UI rewrite ≠ recipe move).
- Do not reformat whole legacy files in the same commit as a behaviour change.
- If defaults would change, fail the change unless the user explicitly asked.

## Tests

- Prefer host-side tests for `app_process` lookup and the machine state machine with a stub motor (`tests/host`, CMake + CTest).
- On-target smoke: select process, start a short Custom step, Esc mid-step, confirm EN high and Resume works.
- CI is Gitea Actions: host tests must pass before either firmware image is built. See `docs/CICD.md`.
- After `tests/host` exists, run it before push. After the IDF skeleton exists, a local `idf.py` build for the board you touched is expected.