chore: agentic upgrade

AGENTS.md

@@ -1,15 +1,59 @@
-# AGENTS.md — Coffee Project Backend
+# Repository Guidelines
 
-Primary workflow guidance lives in `../AGENTS.md`.
+## Project Structure & Module Organization
 
-Use `./CLAUDE.md` as the service-specific source of truth for:
+This FastAPI backend lives in `cpv3/`. The app entry point is `cpv3/main.py`;
+versioned routes are collected in `cpv3/api/v1/router.py`. Feature code lives in
+`cpv3/modules/<feature>/` and should stay flat: `models.py`, `schemas.py`,
+`repository.py`, `service.py`, and `router.py`. Shared infrastructure is in
+`cpv3/infrastructure/`, database setup in `cpv3/db/`, migrations in `alembic/`,
+docs in `docs/`, and tests in `tests/unit/` and `tests/integration/`.
 
-- backend commands
-- module architecture
-- backend patterns and gotchas
+## Build, Test, and Development Commands
 
-OpenCode/Codex notes:
+- `uv sync` installs locked dependencies.
+- `uv run uvicorn cpv3.main:app --reload` runs the API on `localhost:8000`.
+- `docker compose -f docker-compose.local.yml up --build` starts Postgres, Redis,
+  MinIO, the API, and the Dramatiq worker.
+- `uv run dramatiq cpv3.modules.tasks.service` starts the worker without Docker.
+- `uv run alembic upgrade head` applies database migrations.
+- `uv run alembic revision --autogenerate -m "add table"` creates a migration.
 
-- Keep `../AGENTS.md` as the workflow and delegation source of truth.
-- Treat `CLAUDE.md` as architecture, commands, and conventions only.
-- Do not rely on `.claude/` directory contents.
+## Coding Style & Naming Conventions
+
+Use Python 3.11+ with absolute imports such as
+`from cpv3.modules.media.schemas import MediaRead`. Keep Ruff formatting with a
+100-character line length: `uv run ruff format cpv3 tests` and
+`uv run ruff check cpv3 tests`. Put HTTP concerns in `router.py`, DTOs in
+`schemas.py`, business orchestration in `service.py`, and SQLAlchemy queries in
+`repository.py`. Pydantic schemas should inherit from `cpv3.common.schemas.Schema`.
+Define reusable error strings as module-level `ERROR_...` constants.
+
+## Testing Guidelines
+
+Pytest is configured in `pyproject.toml` with `pytest-asyncio` auto mode. Name test
+files `test_*.py`, classes `Test*`, and functions `test_*`. Run all tests with
+`uv run pytest`; run a slice with `uv run pytest tests/unit/test_task_service.py`.
+Prefer unit tests for service/repository logic and integration tests for endpoint
+contracts. Shared async clients, users, storage mocks, and SQLite fixtures live in
+`tests/conftest.py`.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses short imperative subjects, often with Conventional Commit
+prefixes: `fix: add cors endpoints`, `feat: add swagger auth`, `chore: add pipeline`.
+Keep commits focused and mention migrations or config changes in the body. Pull
+requests should include a summary, linked issue or task, test results, and notes for
+API, migration, Docker, or environment-variable changes.
+
+## Security & Configuration Tips
+
+Runtime settings come from `.env` through `cpv3/infrastructure/settings.py`. Do not
+commit real secrets, service keys, or certificates. Local defaults expose Postgres on
+`5332`, Redis on `6379`, MinIO on `9000/9001`, and the API on `8000`.
+
+## Agent-Specific Instructions
+
+Use Context7 for current library, SDK, CLI, framework, or cloud-service documentation.
+Treat committed project files as source of truth when available, and do not rely on
+`.claude/` directory contents.