From 7bf00ee2e3c0db9fd2dc229b6109ca24fe940883 Mon Sep 17 00:00:00 2001
From: agentbox <agentbox@cozytren.ch>
Date: Sat, 1 Aug 2026 06:05:44 +0000
Subject: [PATCH] Add AGENTS.md for AI agent context

---
 AGENTS.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6bfb05a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,66 @@
+# AGENTS.md — Meal Tracker
+
+## Overview
+
+Flask web app for tracking household meal attendance. Users register into households, then mark **yes/no** for lunch & dinner each day. A dashboard shows all members' responses. SQLite backend, Docker deployment behind Caddy reverse proxy.
+
+- **Repo:** `https://gitea.ct.cozytren.ch/romane/agentbox-test`
+- **Production:** `https://meals.ct.cozytren.ch`
+- **Auto-deploy:** `watch-for-updates.sh` polls for new commits every 20s, rebuilds via `docker compose`, redeploys. Push-to-deploy in ~1 min.
+
+## Files — What Goes Where
+
+| File | Role |
+|---|---|
+| `app.py` | Flask factory (`create_app()`), registers blueprints and i18n |
+| `auth.py` | Auth blueprint: `/login`, `/register`, `/logout`. Session-based. |
+| `meals.py` | Meals blueprint: `/dashboard`, `/respond`, `/history`, `/delete-account`, `/admin/*` |
+| `models.py` | All DB access. SQLite via `sqlite3`. 4 tables: `households`, `users`, `meal_periods`, `responses`. |
+| `i18n.py` | Translation module. `t(key)` helper for en/fr/de. Detects `Accept-Language`, session override via `?lang=`. All user-visible strings flow through `t()`. |
+| `templates/` | Jinja2: `base.html` (nav, lang footer), `login.html`, `register.html`, `dashboard.html` |
+| `static/style.css` | All CSS (no framework) |
+| `tests/` | Pytest suite (47 tests): `conftest.py` sets up in-memory DB per test |
+| `Dockerfile` | Python 3.13-alpine. **Must list every `.py` file in the COPY line.** |
+| `docker-compose.yml` | Single service `meal-tracker` on external `caddy` network, volume `meal-data` at `/data` |
+| `watch-for-updates.sh` | Polls git remote, rebuilds on change. Uses `docker compose` with env vars from `.env`. |
+| `doc/index.md` | Full project documentation |
+| `README.md` | Symlink → `doc/index.md` |
+
+## Key Conventions
+
+- **Blueprints:** `auth_bp` and `meals_bp` registered in `app.py`. Decorator `@login_required` on protected routes.
+- **Session keys:** `user_id`, `username`, `is_admin`, `household_id`, `household_name`, `lang`.
+- **i18n:** Every user-visible string in templates uses `{{ t('English text') }}`. In Python, `flash(t("message"), "category")`. Translations live in `TRANSLATIONS` dict in `i18n.py`. English string is the key; only non-English translations stored. When adding new user-facing text, add it to `TRANSLATIONS` for fr/de.
+- **DB:** All access through `get_db()` context manager in `models.py`. Returns `sqlite3.Row` objects accessed as dicts. Path via `DB_PATH` env var (defaults to `/data/meals.db` in Docker, `./meals.db` locally).
+- **CSS:** No framework. Variables in `:root`. Use existing utility classes (`.btn`, `.chip`, `.badge`, etc.).
+
+## Common Pitfalls
+
+1. **Dockerfile COPY must include every `.py` file.** If you add a new Python module, add it to the COPY line. Missing files cause `ModuleNotFoundError` → container crash → 502.
+2. **`meal_type` values are lowercase** (`lunch`, `dinner`) in DB/forms. Templates capitalize them for display: `period.meal_type|capitalize`.
+3. **Past dates are read-only.** The respond route rejects dates before today. Dashboard shows badges instead of buttons for other users' rows.
+4. **`changed_at` logic:** Set only when flipping between `yes` ↔ `no`. First answer and `not_answered` transitions leave it NULL.
+5. **Response status values:** `yes`, `no`, `not_answered` (stored in DB; CSS classes and display strings derived from these).
+
+## Running Locally (no Docker)
+
+```bash
+pip install -r requirements.txt
+python app.py          # or: flask --app 'app:create_app()' run --debug
+pytest tests/ -v
+```
+
+## Running with Docker
+
+```bash
+docker compose up -d --build    # needs caddy network
+# or standalone:
+docker build -t meal-tracker .
+docker run -p 5000:5000 meal-tracker
+```
+
+## Adding a New Language
+
+1. Add the language code and name to `LANGUAGES` in `i18n.py`.
+2. Add translations for every key in `TRANSLATIONS` (keys are the English strings).
+3. Add the language to the footer loop in `templates/base.html`.