coding guidelines, agents and gemini.md

Provider/AGENTS.md

@@ -0,0 +1,85 @@
+# 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.