[feat] setup master from fork with fastapi + otel

AGENTS.md

@@ -0,0 +1,85 @@
+# Project Guide
+
+## Project
+- Python clean architecture template
+- FastAPI is the current HTTP adapter
+- The web layer must stay replaceable
+- Repository and usecase instances are created once at startup
+- Config comes from YAML plus env into one dataclass tree
+- Logs metrics and traces stay behind interfaces and use OTel adapters
+- Request logging middleware is used
+- Metrics middleware is used
+- Custom trace middleware is not used
+- API versioning lives under `/api/v1`
+
+## Structure
+- `domain/` core model and domain errors
+- `domain/error.py` domain errors
+- `domain/user.py` example domain model
+- `usecase/` interfaces and usecases
+- `usecase/interface.py` repository and observability interfaces
+- `usecase/user.py` example user usecase
+- `repository/` repository implementations
+- `repository/user.py` example in-memory repository
+- `adapter/config/` config models and loader
+- `adapter/otel/` logger metrics tracer and OTel setup
+- `adapter/di/` container and startup wiring
+- `adapter/http/fastapi/` app dependencies lifespan middleware routers
+- `config/` app YAML and OTel collector config
+- `docs/` ADR files
+- `tasks.md` task list
+- `main.py` local entrypoint
+
+## Boundaries
+- Keep dependency direction inward
+- `domain` imports nothing internal
+- `usecase` may import `domain`
+- `repository` may import `usecase` and `domain`
+- `adapter` may import `usecase` and `domain`
+- Do not import FastAPI into `domain` or `usecase`
+- Do not import OpenTelemetry into `domain` or `usecase`
+- Keep HTTP models and middleware inside `adapter/http/fastapi/`
+
+## Workflow
+- Use `tasks.md` for planning
+- Do not use Beads
+- Do not use `bd`
+- Use `uv` for Python commands and dependency management
+- Do not create commits on your own
+- Work on one task at a time
+- Prefer delegation for implementation
+- Delegate only one task at a time
+- After one task return to the user with result verification and next options
+- Wait for the user before the next task commit or fix
+
+## Makefile
+- `make install` install deps with `uv`
+- `make run` start the app locally
+- `make run-otel` start the app with OTel env
+- `make lint` run `ruff`
+- `make typecheck` run `mypy`
+- `make test` run `pytest`
+- `make pre-commit` run lint typecheck test
+- `make compose-build` build the containers
+- `make compose-up` start app and collector
+- `make compose-down` stop the stack
+- `make compose-logs` show app and collector logs
+- `make compose-ps` show compose status
+
+## Runtime
+- Local run needs `APP_API_TOKEN` and `APP_SIGNING_KEY`
+- Base config lives in `config/app.yaml`
+- Env overrides come from shell vars or `.env`
+- OTel collector config lives in `config/otel-collector.yaml`
+
+## Style
+- Comments are short and have no trailing period
+- Error messages are short and have no trailing period
+- Use single-word comments when possible
+- Use single-word error messages when possible
+- Keep names simple
+- Keep adapters thin
+- Keep `__init__.py` empty
+- Prefer explicit wiring over magic
+- Do not expand scope without user approval
+- Do not `from __future__ import annotations`