docs: refresh CLAUDE.md architecture and test prerequisites

Procrastinate, context providers and the heartbeat thread were missing
from the architecture map, and both test commands understated what they
need to run.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: snopoke

CLAUDE.md

@@ -6,8 +6,8 @@ Official Python client for [Task Badger](https://taskbadger.net/). Public packag
 
 ```bash
 uv sync --frozen          # Install deps (incl. dev + cli extras via dependency-groups)
-uv run pytest             # Run unit tests (integration_tests/ is excluded by default)
-uv run pytest integration_tests -vs   # Run integration tests (needs Redis + TASKBADGER_API_KEY)
+uv run pytest             # Run unit tests (needs Redis; integration_tests/ excluded by default)
+uv run pytest integration_tests -vs   # Run integration tests (needs Redis + Postgres + API key)
 uv run ruff check . --fix # Lint
 uv run ruff format .      # Format
 uv build                  # Build sdist + wheel
@@ -20,7 +20,10 @@ Pre-commit runs ruff-check + ruff-format; install with `uv run pre-commit instal
 - `taskbadger/` — SDK source
   - `sdk.py`, `mug.py`, `safe_sdk.py` — public API surface (re-exported from `__init__.py`)
   - `decorators.py` — `@track` decorator
-  - `systems/`, `celery.py` — Celery integration (optional extra)
+  - `celery.py`, `procrastinate.py` — per-queue integrations (optional extras)
+  - `systems/`, `_integrations.py` — auto-tracking layer (`BaseSystemIntegration`) wired onto a Celery/Procrastinate app
+  - `context_providers/`, `_error_context.py` — pluggable error context (e.g. Sentry issue links) via `init(context_providers=[...])`
+  - `_heartbeat.py` — background thread pinging long-running tasks
   - `cli/`, `cli_main.py` — Typer-based CLI (optional `[cli]` extra)
   - `internal/` — **generated** by `openapi-python-client`; do not hand-edit
 - `tests/` — unit tests (pytest, pytest-httpx)
@@ -40,7 +43,7 @@ The `update-api` invoke task curls `localhost:8000/api/schema.json` by default 
 
 - Ruff: line-length 120, target Python 3.10, rules `E F I UP DJ PT`.
 - Supports Python 3.10–3.14 — don't use 3.11+ syntax (e.g. `Self`, `LiteralString`).
-- Celery and CLI deps are optional; guard imports inside `taskbadger/celery.py`, `taskbadger/systems/celery.py`, `taskbadger/cli/`.
+- Extras (`celery`, `procrastinate`, `cli`, `sentry`) are all optional; keep their imports inside the corresponding module (`taskbadger/celery.py`, `taskbadger/procrastinate.py`, `taskbadger/systems/`, `taskbadger/cli/`, `taskbadger/context_providers/sentry.py`).
 - `taskbadger/internal/*` is generator output — lint is best-effort, don't reformat manually.
 
 ## Releasing
@@ -54,5 +57,8 @@ GitHub Actions then drafts a release; publishing the release triggers `publish.y
 ## Gotchas
 
 - `pytest` skips `integration_tests/` via `norecursedirs` — name them explicitly to run.
-- Integration tests need `TASKBADGER_ORG`, `TASKBADGER_PROJECT`, `TASKBADGER_API_KEY` env vars and a running Redis.
-- Imports of `celery`, `typer`, `rich` must stay optional — only the core httpx/attrs deps are guaranteed.
+- Integration tests need `TASKBADGER_ORG`, `TASKBADGER_PROJECT`, `TASKBADGER_API_KEY`, a running Redis, and Postgres via `PROCRASTINATE_DSN` (defaults to `postgresql://postgres:postgres@localhost:5432/procrastinate`).
+- Unit tests also need Redis — `tests/conftest.py` points Celery at `redis://localhost:6379` so serialization is exercised for real.
+- Don't unpin `openapi-python-client<0.29` — 0.29 generates `datetime.fromisoformat` calls that can't parse the API's `Z`-suffixed timestamps on Python 3.10.
+- User-facing features are documented in `README.md`, not a docs site — add a section there when adding one.
+- Only the core httpx/attrs/dateutil/tomlkit deps are guaranteed at runtime.