# Repository Guidelines

## Project Structure & Module Organization
Core application code lives in `src/aegis_gitea_mcp/`:
- `server.py` contains FastAPI routes and MCP/SSE endpoints.
- `auth.py`, `config.py`, `audit.py`, and `gitea_client.py` handle security, settings, logging, and Gitea API access.
- `tools/` contains MCP tool implementations (for example `tools/repository.py`).

Tests are in `tests/` and follow module-level coverage for auth, config, server, and integration flows. Utility scripts (key generation/rotation checks) are in `scripts/`. Container assets are in `docker/` with runtime orchestration in `docker-compose.yml`.

## Build, Test, and Development Commands
- `make install`: install runtime dependencies.
- `make install-dev`: install dev dependencies and pre-commit hooks.
- `make run`: run the server locally (`python -m aegis_gitea_mcp.server`).
- `make test`: run pytest with coverage output.
- `make lint`: run `ruff` + `mypy`.
- `make format`: run `black` and auto-fix lint issues.
- `make docker-up` / `make docker-down`: start/stop local container stack.

## Coding Style & Naming Conventions
Use Python 3.10+ with 4-space indentation and type hints for production code. Keep lines within 100 chars (Black/Ruff setting). Modules and functions use `snake_case`; classes use `PascalCase`; constants use `UPPER_SNAKE_CASE`. Prefer explicit exceptions and preserve exception chaining (`raise ... from exc`) when wrapping errors.

## Testing Guidelines
Framework: `pytest` with `pytest-asyncio` and coverage (`--cov=aegis_gitea_mcp`). Place tests under `tests/` using `test_*.py` naming and `test_*` function names. Add or update tests for behavior changes, especially around authentication, API error paths, and MCP tool responses.

## Commit & Pull Request Guidelines
Prefer Conventional Commit style used in history (`feat:`, `fix:`, `docs:`, `test:`). Keep subjects imperative and specific (avoid messages like `update` or `quick fix`). PRs should include:
- what changed and why,
- linked issue(s) if available,
- test/lint evidence (`make test`, `make lint`),
- notes for config/security impact when touching auth, keys, or `.env` behavior.

## Security & Configuration Tips
Never commit secrets. Use `.env` (see `.env.example`) for `GITEA_TOKEN` and `MCP_API_KEYS`. Use `scripts/generate_api_key.py`, `scripts/rotate_api_key.py`, and `scripts/check_key_age.py` for API key lifecycle management.