diff --git a/README.md b/README.md
index efa868a..b99d97e 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,53 @@
 # Stack metalfrom.eu
-test 4
+
+Carte des groupes de metal européens, données issues de Metal Archives
+(avec accord du propriétaire du site source).
+
+## Services
+
+| Service            | Rôle                                                            |
+|--------------------|-----------------------------------------------------------------|
+| `web`              | Site public (carte Leaflet)                                     |
+| `admin`            | Back-office (nginx + reverse-proxy vers l'API)                  |
+| `api`              | API Fastify (public + routes admin), migrations DB              |
+| `crawler`          | Scraping incrémental/complet de Metal Archives via FlareSolverr |
+| `flaresolverr`     | Contournement Cloudflare (Chrome headless) pour le crawler      |
+| `geocoder-enqueue` | Peuple `band_locations` depuis `bands.location_text`            |
+| `geocoder-worker`  | Géocodage Geoapify                                              |
+| `groq-worker`      | Désambiguïsation LLM (Groq) des lieux non géocodés              |
+
+`crawler` et `flaresolverr` ne tournent **qu'en dev** pour l'instant : ils sont
+absents de `docker-compose.yml`. La prod partage la même base, alimentée depuis
+l'environnement de dev.
+
+## Déploiement
+
+- `docker-compose.yml` : production
+- `docker-compose.dev.yml` : environnement de dev (branche `dev`, auto-déployé
+  via webhook Forgejo → Coolify)
+
+Base PostgreSQL + PostGIS gérée séparément par Coolify. Variables d'env : voir
+`infra/.env.example`.
+
+## Qualité
+
+Le déploiement se déclenche sur webhook à chaque push : rien ne s'interpose
+entre `git push` et la mise en ligne. La porte de qualité est donc **locale**,
+et doit être installée une fois par clone :
+
+```
+npm install
+npm run hooks:install
+```
+
+| Commande                       | Portée                                                     |
+|--------------------------------|------------------------------------------------------------|
+| `npm run check`                | lint + types + tests JS + ruff + pytest (~6 s)             |
+| `npm run test:e2e`             | parcours Playwright du dashboard admin (~22 s)             |
+| `npm run test:integration:full`| SQL validé contre un vrai PostgreSQL+PostGIS (exige Docker)|
+| `npm run check:full`           | tout ci-dessus + mutation + audits de dépendances          |
+
+Le hook `pre-push` lance `check` puis `test:e2e`. `.forgejo/workflows/ci.yml`
+existe mais reste inerte tant qu'aucun runner Forgejo n'est enregistré.
+
+Outillage Python de test : `pip install -r requirements-dev.txt`.