Add AGENTS.md for project documentation and agent rules

AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md
+
+## Purpose
+This repository contains EggDuino firmware (EggBot protocol emulation) for an ESP32 build target using PlatformIO.
+Use this file as the working contract for code agents in this repo.
+
+## Repository Map
+- `src/main.cpp`: firmware entrypoint (`setup`/`loop`), serial command processing, optional button/test toggles.
+- `src/Functions.cpp`: EggBot command handlers (`SM`, `SP`, `EM`, `SC`, `QP`, etc.) and command registration.
+- `src/Helper_Functions.cpp`: hardware init, motor/servo control, move preparation, ACK/error responses.
+- `src/Config_Web.cpp`: optional Wi-Fi web UI and JSON config persistence via SPIFFS.
+- `src/Logging.cpp`: ring-buffer log collection and `/api/logs` JSON serialization.
+- `include/EggDuino.h`: global declarations, pin/microstep constants, cross-file API.
+- `lib/SerialCommand/src/*`: local serial command parser implementation.
+- `platformio.ini`: single build environment (`[env:uno]`) that actually targets `esp32dev`.
+
+## Build, Flash, Monitor
+- Build: `~/.platformio/penv/bin/pio run -e uno`
+- Upload: `~/.platformio/penv/bin/pio run -e uno -t upload`
+- Serial monitor: `~/.platformio/penv/bin/pio device monitor -b 115200`
+
+Notes:
+- `platformio.ini` currently pins `upload_port = /dev/tty.usbserial-110`; treat this as machine-local and change only when required.
+- There are no unit tests in this repository; a successful PlatformIO build is the minimum validation.
+
+## Local Config And Secrets
+- Wi-Fi config is provided by `src/credentials.h`.
+- Keep `src/credentials.h` local-only; `.gitignore` already excludes it.
+- For default behavior (no Wi-Fi web server), keep:
+  - `const char *kWifiSsid = 0;`
+  - `const char *kWifiPassword = 0;`
+
+## Agent Rules For Code Changes
+1. Preserve EggBot serial protocol behavior.
+   - Commands are wired in `makeComInterface()`.
+   - ACK/error responses are protocol-significant (`"OK\\r\\n"` and `"unknown CMD\\r\\n"`).
+2. Keep movement math semantics intact.
+   - `prepareMove()` handles microstep correction and step error accumulation (`g_iRotStepError`, `g_iPenStepError`).
+   - Do not replace this with naive float-heavy logic unless explicitly requested.
+3. Respect real-time loop constraints.
+   - `loop()` must remain non-blocking except for protocol-required waits.
+   - Avoid adding expensive dynamic allocation in high-frequency paths.
+4. Keep hardware mapping centralized.
+   - Pin and microstep constants belong in `include/EggDuino.h`.
+   - If changing pinouts, update only there and keep ESP32/non-ESP32 guards coherent.
+5. Do not hand-edit generated IDE metadata.
+   - `.vscode/c_cpp_properties.json` and `.vscode/launch.json` are generated by PlatformIO.
+   - Prefer edits in `platformio.ini` instead.
+6. Keep edits minimal and targeted.
+   - Match existing style (global `g_*` variables, Arduino types, simple free functions).
+   - Avoid broad refactors unless explicitly requested.
+
+## When Adding Config Parameters To Web UI
+`Config_Web.cpp` currently has an empty `configParameters[]` array. To add persisted parameters:
+1. Add the backing global variable (typically in existing global state).
+2. Add a `ConfigParameter` entry to `configParameters[]` with key, pointer, description, default.
+3. Ensure defaults are safe in `applyDefaults()` flow.
+4. Rebuild and verify `GET/POST /api/config` still round-trips.
+
+## Definition Of Done For Agents
+Before finishing, run:
+1. `~/.platformio/penv/bin/pio run -e uno`
+2. Summarize changed files and any behavior-impacting protocol/hardware implications.