From e39f930cf9f762611c927ffb662b8bcffbf4e8b5 Mon Sep 17 00:00:00 2001
From: Jacob Hagstedt <jacob.hagstedt@gmail.com>
Date: Wed, 3 Jun 2026 22:35:38 +0200
Subject: [PATCH] Update agents

---
 AGENTS.md | 47 +++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 39 insertions(+), 8 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b1ce8a7..5be8a01 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,7 +6,6 @@ Baby monitor - self-hosted web app for tracking infant sleep. Dual-stack monorep
 
 ## STRUCTURE
 
-
 ```
 ./
 ├── frontend/           # React 19 SPA
@@ -37,6 +36,9 @@ Baby monitor - self-hosted web app for tracking infant sleep. Dual-stack monorep
 | UI components | `frontend/src/components/` | tracker/, stats/ subdirs |
 | Backend models | `backend/app/models.py` | SQLModel definitions |
 | API schemas | `backend/app/schemas.py` | Pydantic request/response |
+| Settings / env vars | `backend/app/config.py` | Pydantic-settings, reads `.env` |
+| Database init | `backend/app/database.py` | Engine setup, `init_db()` |
+| Timezone logic | `backend/app/utils/time_utils.py` | Historical bug source — handle with care |
 
 ## CONVENTIONS
 
@@ -61,8 +63,13 @@ Baby monitor - self-hosted web app for tracking infant sleep. Dual-stack monorep
 ```bash
 cd backend
 uv sync
-uv run uvicorn app.main:app --reload
+uv run uvicorn app.main:app --reload   # runs on http://localhost:8000
+
+# Run all tests
 uv run pytest
+
+# Run a specific test file (preferred during debugging)
+uv run pytest tests/test_stats.py -v
 ```
 
 ### Frontend Development
@@ -70,27 +77,51 @@ uv run pytest
 ```bash
 cd frontend
 npm install
-npm run dev
+npm run dev    # runs on http://localhost:5173
 
-# WARNING: 'npm test' may hang if run globally. Use specific file paths or vitest flags.
+# Unit tests (Vitest)
 npm run test
+
+# Unit + e2e tests (Vitest + Playwright)
+npm run test:all
+
+# Lint
+npm run lint
 ```
 
+### Docker (production-like, ARM64)
+
+```bash
+# Full stack — frontend served on http://localhost:8080
+docker compose up --build
+```
+
+## ENVIRONMENT VARIABLES
+
+Backend reads from `backend/.env` (optional — all have defaults):
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `DATABASE_URL` | `sqlite+aiosqlite:///./data/sleep.db` | SQLite DB path |
+| `CORS_ORIGINS` | `http://localhost:5173` | Allowed CORS origins (comma-separated) |
+| `LOG_LEVEL` | `info` | Uvicorn log level |
+
+In Docker the DB is persisted via a bind-mount at `./backend/data/`.
+
 ## 🛑 DIRECTORY NAVIGATION & FILE DISCOVERY
 
 **Context:** This is a full-stack monorepo containing massive generated/dependency folders (`node_modules`, `dist`, `venv`, `.venv`, `__pycache__`, etc.). Unrestricted file listings will bloat your context window, crash your session, and cause severe token waste.
 
 * **NEVER use `ls -R`:** This command is strictly forbidden in this repository.
-* **Primary Discovery:** To map out files or explore the project tree, **ALWAYS use `git ls-files**`. This is your default command and ensures you only interact with human-written source code.
+* **NEVER use `find` without `-maxdepth`:** Unbounded `find` crawls dependency trees just like `ls -R`. Always add `-maxdepth 3` or tighter.
+* **Primary Discovery:** To map out files or explore the project tree, **ALWAYS use `git ls-files`**. This is your default command and ensures you only interact with human-written source code.
 * **Structural Context:** If you explicitly need a visual directory layout to understand architecture, use `tree` appended with the mandatory ignore flags:
 ```bash
 tree -I 'node_modules|.git|dist|build|__pycache__|venv|.venv|env|.pytest_cache|.mypy_cache|.ruff_cache|*.egg-info'
-
 ```
+* **Searching Code:** If you need to search for text or code blocks across the repo, **ALWAYS use `git grep "search_term"`** instead of standard `grep -r` to avoid crawling ignored or minified assets.
 
 
-* **Searching Code:** If you need to search for text or code blocks across the repo, **ALWAYS use `git grep "search_term"**` instead of standard `grep -r` to avoid crawling ignored or minified assets.
-
 ## 🧠 TASK DELEGATION & CONTEXT PRESERVATION
 
 **Context:** The main OpenCode agent context window is our most critical resource. Executing complex tasks, debugging cross-file issues, or writing massive features directly in the main thread causes severe context bloat, leading to code hallucinations and dropped instructions.