diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ba64e55
--- /dev/null
+++ b/README.md
@@ -0,0 +1,69 @@
+# pointeuse-optimisator
+
+Saisie des horaires de travail avec calcul en temps réel de l'heure de sortie optimale pour finir la semaine à **exactement 0h d'heures supplémentaires**.
+
+---
+
+## Principe
+
+La semaine cible est **39h** (7h48 / jour). Les directives imposent des plages de présence minimum :
+
+| Demi-journée | Plage minimale |
+|---|---|
+| Matin | 09:00 → 12:00 |
+| Après-midi | 14:00 → 17:00 |
+
+L'outil calcule — sans arrondi — **l'heure précise à laquelle partir** chaque jour pour que le total de la semaine tombe pile sur 39h00.
+
+---
+
+## Ce que tu vois dans le tableau
+
+| Colonne | Ce qu'elle dit |
+|---|---|
+| **Travaillé** | Heures effectivement saisies ce jour |
+| **Δ jour** | Écart par rapport aux 7h48 dus (affiché dès qu'une heure est enregistrée) |
+| **Δ sem.** | Solde cumulé depuis lundi — visible uniquement quand la journée est complète et sans jour manquant |
+| **Fin cible** | L'heure de sortie aprem pour finir la semaine à 0h sup |
+
+Les plages qui ne respectent pas les minimums sont signalées en rouge dès la saisie.
+
+---
+
+## Lancement
+
+```bash
+docker compose up -d
+```
+
+Ouvre [http://localhost:8000](http://localhost:8000).
+
+Les données (pointages, congés) sont stockées dans `data/` et ignorées par git.\
+Seul `data/config.json` est versionné.
+
+---
+
+## Configuration
+
+`data/config.json` :
+
+```json
+{
+  "heures_jour": 7.8
+}
+```
+
+`7.8` = 7h48 = 39h ÷ 5 jours. Modifier cette valeur recentre tous les calculs.
+
+---
+
+## Congés
+
+Trois boutons par ligne : **MA** (matin), **AM** (après-midi), **J** (journée entière).\
+Ils réduisent les heures dues et recalculent la **Fin cible** pour les jours restants.
+
+---
+
+## Stack
+
+`FastAPI` · `HTMX` · `Jinja2` · fichiers JSON · `Docker`