# AGENTS.md

Calendink Provider — ESP32-S3 firmware + Svelte 5 web dashboard.
Uses **ESP-IDF** (not Arduino). Serves UI from LittleFS flash partitions over Ethernet/WiFi.

---

## Build Commands

```powershell
# Backend (from project root)
idf.py build
idf.py flash monitor

# Frontend (from frontend/)
npm run dev            # Dev server — calls real ESP32 API (set VITE_API_BASE in .env.development)
npm run build          # Production build → dist/index.html
npm run build:esp32    # Build + gzip → dist/index.html.gz
npm run ota:deploy     # OTA deploy frontend to device
```

There are no automated tests. Verify by building and inspecting on-device.

---

## Project Layout

```
main/                   C++ firmware (Unity Build — one translation unit)
main/api/<domain>/      HTTP endpoint files, one per verb
main/http_server.cpp    Server setup, static file serving, scratch buffer pool
main/connect.cpp        Ethernet + WiFi management
frontend/src/           Svelte 5 components + api.js
frontend/src/app.css    TailwindCSS v4 @theme design tokens
tdd/                    Technical Design Documents — read before major changes
.agents/rules/          Coding guidelines
```

---

## Backend Rules (C++ / ESP-IDF)

- **Unity Build**: `main.cpp` `#include`s all `.cpp` files. Do NOT add files to `CMakeLists.txt`.
- **C-style only**: no classes, no `std::`, no RAII, no exceptions. `template`, `auto`, `constexpr` are fine.
- **`internal`** (= `static`) on all file-scoped symbols — defined in `main/types.hpp`.
- **Logging**: use `ESP_LOGI` / `ESP_LOGW` / `ESP_LOGE` only — never `printf()`.
  - Because of Unity Build, tag variables must have unique names per file: `kTagHttpServer`, `kTagMain`, etc. — never use a shared `TAG`.
- **Seed data**: `seed_users()` / `seed_tasks()` must be inside `#ifndef NDEBUG` guards.
- **API handler pattern**: set CORS header + response type → parse request → call store function → build cJSON response → `free()` strings, `cJSON_Delete()` objects.
- **Data is in-RAM only** (`g_Users[8]`, `g_Tasks[32]`). This is intentional — persistence is a future milestone. Don't add it without a TDD.

---

## Frontend Rules (Svelte 5 + TailwindCSS v4)

- **Tailwind only** — no `<style>` blocks in components. Design tokens are in `frontend/src/app.css` (`@theme`).
- **Svelte 5 runes only** — `$state`, `$derived`, `$effect`, `$props`, `$bindable`. No `export let`, `onMount`, `onDestroy`, `writable`, or `.subscribe()`.
- **`$state()`** for values the template reads. **Plain `let`** for script-only handles/flags the template never reads.
- **`$effect()` with no reactive deps** runs once on mount — add a comment saying so.
- All API calls through `lib/api.js` via `trackedFetch()` — never raw `fetch()`.
- Shared utilities (formatters, helpers) in `lib/utils.js`. Never duplicate functions across components.

---

## Technical Design Documents

Read the relevant TDD before any major architectural change:

| TDD | Read when |
|---|---|
| `tdd/backend_architecture.md` | Changing server setup, adding API groups |
| `tdd/frontend_technology_choices.md` | Changing build tools or dependencies |
| `tdd/todo_list.md` | Changing task/user data model or API contracts |
| `tdd/firmware_ota.md` | Touching OTA partition logic |
| `tdd/frontend_ota.md` | Touching frontend OTA upload or versioning |
| `tdd/concurrent_requests.md` | Changing HTTP server socket/connection config |

---

## Working with the User

- After finishing a task: explain what changed, what you recommend next, and wait for approval.
- Never make changes beyond the agreed scope without asking first.
- Write a TDD (see `.agents/rules/how-to-write-tdd.md`) before major architectural changes.
- **Keep `AGENTS.md` and `GEMINI.md` up to date.** If a task changes the architecture, adds new rules, introduces new build commands, or modifies the project layout — update both files before closing the task.