diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3d86c6a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,97 @@
+# Rotation de mot de passe SSH/sudo
+
+Petit projet Ansible pour changer le mot de passe d'un compte Linux existant
+sur un ou plusieurs serveurs.
+
+Le playbook demande le nouveau mot de passe au lancement et l'applique sur les
+hotes cibles avec `chpasswd` via `sudo`. Le mot de passe n'est pas stocke dans
+les fichiers du depot et la tache de changement est masquee avec `no_log: true`.
+
+## Fichiers principaux
+
+- `ansible.cfg` : configuration Ansible du projet.
+- `inventories/hosts.yml` : inventaire principal et variables de connexion.
+- `playbooks/change_password.yml` : playbook de changement de mot de passe.
+
+## Configuration
+
+Les variables communes sont definies dans `inventories/hosts.yml`, sous
+`all.vars` :
+
+```yaml
+all:
+  vars:
+    ansible_user: olivier
+    password_target_user: olivier
+```
+
+- `ansible_user` est l'utilisateur SSH utilise pour se connecter aux serveurs.
+- `password_target_user` est le compte dont le mot de passe sera change.
+
+Gardez `password_target_user` identique a `ansible_user` lorsque le compte SSH
+et le compte sudo sont les memes.
+
+Les options propres a un serveur, par exemple une cle SSH dediee, se placent sur
+l'entree de l'hote :
+
+```yaml
+test:
+  hosts:
+    srv-docker-lab-01.maison.bro:
+      ansible_ssh_private_key_file: ~/.ssh/id_ed25519
+```
+
+## Utilisation
+
+Lancez le playbook avec demande du mot de passe `sudo` :
+
+```bash
+ansible-playbook playbooks/change_password.yml --ask-become-pass
+```
+
+Le playbook demandera ensuite le nouveau mot de passe du compte cible, avec
+confirmation.
+
+## Deploiement progressif
+
+Commencez par un petit groupe de test :
+
+```bash
+ansible-playbook playbooks/change_password.yml --ask-become-pass --limit test
+```
+
+Puis ciblez le groupe complet lorsque le test est valide :
+
+```bash
+ansible-playbook playbooks/change_password.yml --ask-become-pass --limit linux_servers
+```
+
+Si certains hotes utilisent un mot de passe SSH au lieu d'une cle SSH, ajoutez
+`--ask-pass` :
+
+```bash
+ansible-playbook playbooks/change_password.yml --ask-pass --ask-become-pass --limit test
+```
+
+## Verification
+
+Verifier que l'inventaire est lisible :
+
+```bash
+ansible-inventory --list
+```
+
+Verifier la syntaxe du playbook :
+
+```bash
+ansible-playbook playbooks/change_password.yml --syntax-check
+```
+
+## Regles de securite
+
+- Ne commitez jamais de mot de passe en clair.
+- Utilisez `vars_prompt`, `ansible-vault` ou une source externe pour les secrets.
+- Conservez `no_log: true` sur les taches qui manipulent un mot de passe ou un
+  hash de mot de passe.
+- Testez toujours sur un groupe restreint avant de cibler tous les serveurs.
+- Ne modifiez pas la politique SSH pendant une rotation de mot de passe.