diff --git a/docs/mail-cron-setup.md b/docs/mail-cron-setup.md
new file mode 100644
index 0000000..0193cd1
--- /dev/null
+++ b/docs/mail-cron-setup.md
@@ -0,0 +1,92 @@
+# Mail Integration — Configuration cron OS
+
+## Vue d'ensemble
+
+La synchronisation IMAP est déclenchée par un cron OS toutes les 10 minutes.
+Elle appelle la commande Symfony `app:mail:sync` qui s'exécute dans le container PHP.
+
+Un Symfony Lock (`mail.sync`, TTL 10 min, store `flock` via `LOCK_DSN=flock`) empêche
+les runs de se chevaucher si une sync prend plus de 10 min.
+
+## Prérequis
+
+- Container `php-lesstime-fpm` démarré (`make start`)
+- `MailConfiguration.enabled = true` (configurable depuis l'admin — Phase 7)
+- `ENCRYPTION_KEY` défini dans `infra/dev/.env.docker.local` (ou production env)
+
+## Installation du cron
+
+Sur la **machine hôte** (pas dans le container) :
+
+```bash
+crontab -e
+```
+
+Ajouter la ligne suivante (adapter le chemin) :
+
+```cron
+*/10 * * * * cd /home/r-dev/malio-dev/Lesstime && make mail-sync >> /var/log/lesstime-mail-sync.log 2>&1
+```
+
+Ou directement via `docker exec` (sans dépendance à `make`) :
+
+```cron
+*/10 * * * * docker exec php-lesstime-fpm php bin/console app:mail:sync >> /var/log/lesstime-mail-sync.log 2>&1
+```
+
+### Avec un utilisateur système dédié
+
+Si le cron est configuré pour un utilisateur système spécifique (ex: `www-data` ou `deploy`) :
+
+```bash
+sudo crontab -u deploy -e
+```
+
+## Variables d'environnement nécessaires
+
+| Variable | Description | Exemple |
+|---|---|---|
+| `ENCRYPTION_KEY` | Clé hex 32 bytes pour déchiffrer le password IMAP | `$(php -r "echo bin2hex(random_bytes(32));")` |
+| `LOCK_DSN` | DSN du store de verrous Symfony | `flock` (défaut, fichier local) |
+
+La clé doit être la même que celle utilisée pour chiffrer le password lors de la configuration.
+
+## Commandes utiles
+
+```bash
+# Sync complète (toutes les boîtes)
+make mail-sync
+
+# Sync d'un seul dossier (le dossier doit déjà exister en base)
+make mail-sync FOLDER=INBOX
+
+# Simulation (dry-run, pas d'écriture BDD)
+make mail-sync DRYRUN=1
+
+# Directement dans le container
+docker exec php-lesstime-fpm php bin/console app:mail:sync
+docker exec php-lesstime-fpm php bin/console app:mail:sync --folder=INBOX
+docker exec php-lesstime-fpm php bin/console app:mail:sync --dry-run
+```
+
+## Logs
+
+Les logs Symfony sont dans `var/log/dev.log` (ou `prod.log` en production).
+Suivre les logs en temps réel :
+
+```bash
+make logs-dev
+```
+
+Les messages loggés par `MailSyncService` sont préfixés `mail.sync`.
+
+## Sécurité
+
+- Le password IMAP est **toujours stocké chiffré** (libsodium secretbox)
+- Les corps de mails, passwords et pièces jointes ne sont **jamais loggés**
+- Le lock `flock` évite les runs parallèles (fichier dans `/tmp/sf.mail.sync.<hash>.lock`)
+
+## Production
+
+En production, préférer un cron système ou un job scheduler (Kubernetes CronJob, ECS Scheduled Task, etc.).
+La commande est idempotente : relancer plusieurs fois ne duplique pas les données (UIDs uniques en base).