From 77959b4a88aa2a2b0c872de60533f943d12af39b Mon Sep 17 00:00:00 2001
From: Space-Banane <paulwaehner923@gmail.com>
Date: Fri, 29 May 2026 20:41:24 +0200
Subject: [PATCH] Add AGENTS.md

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

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..53ab556
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,61 @@
+# AGENTS.md
+
+Repository guidance for agents working in `git-activity-merge`.
+
+## Project Snapshot
+
+- FastAPI service that merges GitHub and Gitea contribution data.
+- Main outputs are JSON, SVG, and PNG at `/activity.json`, `/activity.svg`, and `/activity.png`.
+- Source code lives in `app/`; tests live in `tests/`.
+
+## Setup
+
+- Python requirement: `>=3.11`.
+- Install dependencies with:
+  - `pip install -e ".[dev]"`
+- Configure runtime settings through environment variables or `.env`.
+- Required env vars:
+  - `GITHUB_USERNAME`
+  - `GITEA_BASE_URL`
+  - `GITEA_USERNAME`
+- Optional env vars:
+  - `GITHUB_TOKEN`
+  - `GITEA_TOKEN`
+  - `CACHE_DIR`
+  - `CACHE_TTL_SECONDS`
+  - `DEFAULT_THEME`
+  - `SERVICE_TITLE`
+
+## Common Commands
+
+- Run tests:
+  - `pytest -q`
+- Run the app locally:
+  - `uvicorn app.main:app --reload --port 8000`
+- Build the container image:
+  - `docker build -t git-activity-merge .`
+- Run with Compose:
+  - `docker compose up --build`
+
+## Code Layout
+
+- `app/main.py` wires routes, caching, and response rendering.
+- `app/merge.py` normalizes and merges activity counts.
+- `app/settings.py` defines environment-backed configuration.
+- `app/sources/` contains GitHub and Gitea fetchers.
+- `app/render/` contains SVG and PNG rendering helpers.
+
+## Testing Notes
+
+- CI runs `pytest -q` on Ubuntu with Python 3.12.
+- Prefer focused tests in `tests/` when changing behavior.
+- If you touch API behavior, update or add route tests in `tests/test_routes.py`.
+- If you change merge logic, add coverage in `tests/test_merge.py`.
+- If you change cache behavior, add coverage in `tests/test_cache.py`.
+
+## Editing Rules
+
+- Keep changes aligned with the existing minimal FastAPI structure.
+- Avoid introducing new dependencies unless they clearly reduce complexity or fix a real gap.
+- Do not commit secrets or real production environment values.
+- Prefer small, targeted changes over broad refactors unless the user asked for one.