diff --git a/CLAUDE.md b/CLAUDE.md
index aa68424..5f5fec6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -243,6 +243,20 @@ manquantes), mais pourraient etre simplifies.
   fichiers statiques servis par `ServeStaticModule` (pas seulement les routes `@Controller`), malgre
   le fait que `ServeStaticModule` s'enregistre via le systeme de modules Nest plutot que directement
   sur l'instance `app`. Desactivable si `AUTH_USERNAME`/`AUTH_PASSWORD_HASH` absents (dev local).
+- **Piege `.env` + hash bcrypt** : un hash bcrypt contient des `$` (`$2a$10$eg...`). Docker Compose
+  interprete `$` dans un fichier `.env` comme le debut d'une substitution de variable — sans
+  echappement, `AUTH_PASSWORD_HASH=$2a$10$eg...` est tronque silencieusement a `$2a$10.` (verifie via
+  `docker compose config` : la valeur affichee etait bien tronquee, le reste du hash disparaissait
+  sans aucune erreur). **Fix** : dans `.env`, doubler chaque `$` du hash (`$$2a$$10$$eg...`) ;
+  `docker compose` les collapse en `$` uniques au runtime (reverifie via `docker exec ...
+  printenv AUTH_PASSWORD_HASH` : le conteneur recoit bien le hash original complet, un seul `$`).
+  Documente dans `.env.example`. Coolify (qui n'utilise pas de fichier `.env` mais son propre
+  formulaire "Environment Variables") n'a probablement pas ce probleme puisqu'il n'y a pas de fichier
+  `.env` a parser — a confirmer au premier deploiement avec l'auth active.
+  - **Autre piege distinct rencontre en testant** : apres `docker compose up -d` (sans `--build`),
+    le conteneur peut tourner sur une **image cachee obsolete** ne contenant pas les derniers
+    changements de code (auth absente, etc.) sans aucun avertissement. Toujours utiliser
+    `docker compose up -d --build` en local pour etre sur de tester le code courant.
 
 ## Constantes du pipeline (voir `src/config.ts`)