# common/ — Shared Utilities

See @../../CLAUDE.md for project-wide patterns.

## What This Is
Foundation package used by every other domain. Contains base HTTP client, FastAPI dependencies, response models, and validation constants.

## Key Patterns
- `BaseAPIClient._request()` returns `dict` on success, `str` on error — all MCP tools rely on this convention
- `None` params are stripped before sending to httpx (line ~68 in base_client.py) — this is why optional filters work
- httpx client is lazily created on first `_get_client()` call, not in `__init__` — required for async event loop compatibility
- `_paginate_all()` defaults to 200 items/page and loops until `has_next == False`

## Constants to Know
- `VALID_TASK_TRANSITIONS` defines the full state machine — `done` is terminal (no transitions out), `cancelled`/`timeout` can return to `todo`
- `MAX_MEMORIES_PER_PROJECT = 50`
- `VALID_MEMORY_CATEGORIES`: env, pattern, gotcha, test, dependency, general

## Gotchas
- If you add a new status or priority value, update BOTH the constants here AND the CHECK constraint in `migrations/versions/`
- `get_db()` dependency accesses `request.app.state.db` — this is set during FastAPI lifespan, not available in MCP tools
- API key auth is optional: if `PEON_API_KEY` env is unset, no header is sent
