feat: implement multi-provider architecture for contribution fetching and add Docker support

CLAUDE.md

@@ -118,20 +118,49 @@ Add to `.claude/settings.json` to run PHPUnit automatically after every file edi
 
 ## Docker
 
+### Development
+
+`docker-compose.override.yml` is picked up automatically and targets the `dev` stage (Xdebug + all deps, source mounted).
+
 ```bash
-# Build and run
+# Start dev container (override applied automatically)
 docker compose up -d --build
 
-# Force cache clear (clears the 1h filesystem cache)
+# Shell into the container to run commands
+docker compose exec graph sh
+
+# Run tests inside the container
+docker compose exec graph php bin/phpunit
+
+# Disable Xdebug for faster test runs
+XDEBUG_MODE=off docker compose up -d
+
+# Force cache clear
 docker compose exec graph rm -rf var/cache/*
 
 # View logs
 docker compose logs -f graph
 ```
 
-There is no `composer.lock` in the repo. If you add or change dependencies, run `composer install` locally and commit the resulting lock file — without it, Docker builds resolve versions fresh each time and may produce inconsistent results.
+**Xdebug:** listens on port `9003`. Configure your IDE to accept connections from Docker. On Linux `host.docker.internal` is resolved via `extra_hosts: host-gateway` in the override file.
 
-The Dockerfile runs `composer install --no-scripts` (skipping Symfony post-install scripts) then `composer dump-autoload --optimize --no-dev` in the final stage. If `bin/console` fails with a missing class error inside the container, the most likely cause is the absent lock file causing an incomplete dependency resolution.
+### Production
+
+Use only the base compose file to skip the dev override:
+
+```bash
+docker compose -f docker-compose.yml up -d --build
+```
+
+The `final` stage runs as a non-root `app` user and contains no Composer binary. The build pipeline is:
+
+```
+base → deps (composer install --no-dev)
+     → build (copy source + dump-autoload)
+     → final (copy vendor + source, chown app, USER app)
+```
+
+There is no `composer.lock` in the repo. If you add or change dependencies, run `composer install` locally and commit the resulting lock file — without it, Docker builds resolve versions fresh each time and may produce inconsistent results.
 
 ## Architecture