update

AGENTS.md

@@ -0,0 +1,34 @@
+# 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.