diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index 9368d782..52d08e38 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -124,6 +124,8 @@ All vars are set in `.env` at the repo root (copy from `.env.example`). The back
 | `POSTGRES_PASSWORD` | DB password | `change-me` | YES | YES |
 | `POSTGRES_DB` | Database name | `family_archive_db` | YES | — |
 
+> **PgBouncer pooling mode:** The `journey_items.position_seq` dedup constraint uses `DEFERRABLE INITIALLY DEFERRED`. This requires PgBouncer in **transaction-mode** (not statement-mode) pooling. Do not switch to statement-level pooling — deferred constraints only work within a single transaction session.
+
 ### MinIO container
 
 | Variable | Purpose | Default | Required? | Sensitive? |