# 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.