diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d545ccf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,268 @@
+
+
+# ✨ NixOS First Login
+
+### Assistant de première connexion pour postes NixOS / KDE Plasma
+
+
+
+
+
+
+
+
+**Une expérience de première connexion plein écran, claire et moderne, pensée pour industrialiser la préparation des postes NixOS.**
+
+
+
+---
+
+## 🚀 Objectif
+
+**NixOS First Login** fournit un assistant graphique de première connexion inspiré des assistants d'installation d'un système d'exploitation.
+
+L'utilisateur est accompagné pas à pas pour préparer son environnement :
+
+> 👋 **Bienvenue** → 🔐 **Mot de passe** → 🔑 **YubiKey** → ✅ **Poste prêt**
+
+L'interface est développée en **Qt Quick / QML**, s'intègre naturellement à **KDE Plasma 6** et fonctionne en plein écran.
+
+---
+
+## 🧭 Parcours utilisateur
+
+| Étape | Fonction |
+|---|---|
+| 👋 **Bienvenue** | Présentation de l'assistant et du processus de configuration |
+| 🔐 **Mot de passe** | Saisie du mot de passe temporaire, choix du nouveau mot de passe et confirmation |
+| 🛡️ **Robustesse** | Indicateur visuel de qualité du mot de passe, sans blocage d'un mot de passe faible |
+| 👁️ **Affichage des secrets** | Bouton œil pour afficher ou masquer mots de passe et PIN |
+| 🔑 **YubiKey** | Saisie du PIN temporaire, choix du nouveau PIN et confirmation |
+| ✅ **Poste prêt** | Synthèse visuelle de la configuration terminée |
+
+---
+
+## ✨ UX / UI
+
+### 🖥️ Interface plein écran
+
+L'assistant occupe l'écran afin de créer un parcours simple et sans distraction, proche d'un assistant d'installation classique.
+
+### 🧩 Navigation guidée
+
+Les étapes sont présentées dans des colonnes de largeur fixe afin de conserver un alignement propre, quel que soit le libellé.
+
+### 👁️ Affichage des mots de passe et PIN
+
+Chaque champ secret possède un bouton permettant de basculer entre :
+
+```text
+•••••••• 👁
+ ↓
+MonSecret ◉
+```
+
+### 📊 Robustesse du mot de passe
+
+Le mot de passe reçoit une indication visuelle :
+
+- 🔴 **Faible**
+- 🟠 **Moyen**
+- 🔵 **Bon**
+- 🟢 **Très bon**
+
+> 💡 **Cette indication est informative uniquement.** Un mot de passe faible n'est volontairement pas bloqué.
+
+### 🔒 Parcours verrouillé
+
+Tant que les informations nécessaires ne sont pas renseignées :
+
+- ⛔ impossible de passer à l'étape suivante ;
+- ⛔ impossible de quitter depuis l'interface ;
+- ⛔ `Ctrl+Q` n'est pas proposé ;
+- ⛔ une tentative de fermeture de la fenêtre avant la fin est interceptée ;
+- ✅ les confirmations doivent correspondre avant de continuer.
+
+---
+
+## 🏗️ Architecture
+
+```text
+nixos-workstations/
+├── configuration.nix
+├── LICENSE
+├── COMMERCIAL-LICENSE.md
+├── first-login-ui/
+│ ├── CMakeLists.txt
+│ ├── org.raspot.nixosfirstlogin.desktop
+│ └── src/
+│ ├── CMakeLists.txt
+│ ├── main.cpp
+│ └── Main.qml
+└── modules/
+ └── first-login-ui.nix
+```
+
+Le matériel propre à chaque poste **n'est pas stocké dans le dépôt commun** :
+
+```text
+/etc/nixos/hardware-configuration.nix
+```
+
+reste généré localement par NixOS.
+
+---
+
+## ⚙️ Intégration NixOS
+
+Le module est importé depuis `configuration.nix` :
+
+```nix
+imports = [
+ /etc/nixos/hardware-configuration.nix
+ ./modules/software.nix
+ ./modules/users.nix
+ ./modules/security.nix
+ ./modules/yubikey-first-login.nix
+ ./modules/first-login-ui.nix
+];
+```
+
+---
+
+## 🧪 Validation d'une nouvelle version
+
+Pour conserver une procédure de déploiement prudente :
+
+### 1️⃣ Construire sans activer
+
+```bash
+sudo nixos-rebuild build \
+ -I nixos-config=/home/localadm/nixos-workstations/configuration.nix
+```
+
+### 2️⃣ Vérifier l'activation prévue
+
+```bash
+sudo nixos-rebuild dry-activate \
+ -I nixos-config=/home/localadm/nixos-workstations/configuration.nix
+```
+
+### 3️⃣ Activer temporairement
+
+```bash
+sudo nixos-rebuild test \
+ -I nixos-config=/home/localadm/nixos-workstations/configuration.nix
+```
+
+### 4️⃣ Lancer l'interface
+
+```bash
+nixos-first-login-ui
+```
+
+### 5️⃣ Rendre la configuration persistante après validation
+
+```bash
+sudo nixos-rebuild switch \
+ -I nixos-config=/home/localadm/nixos-workstations/configuration.nix
+```
+
+---
+
+## 🛡️ Sécurité
+
+
+
+**🔐 Les mécanismes sensibles doivent rester séparés de l'interface graphique.**
+
+
+
+L'architecture cible conserve une séparation claire :
+
+```text
+┌───────────────────────────────┐
+│ Qt Quick / QML │
+│ Interface utilisateur │
+└───────────────┬───────────────┘
+ │
+ ▼
+┌───────────────────────────────┐
+│ Backend contrôlé │
+├───────────────────────────────┤
+│ Mot de passe → passwd NixOS │
+│ PIN YubiKey → ykman │
+└───────────────────────────────┘
+```
+
+L'interface ne doit jamais modifier directement `/etc/shadow` ni réimplémenter PAM.
+
+> ⚠️ **État de cette V4 :** l'interface graphique est validée, mais ce nouveau frontend n'exécute encore directement ni `passwd` ni `ykman`. Le module historique `yubikey-first-login.nix` reste distinct tant que le backend de la nouvelle UI n'a pas été intégré et testé.
+
+---
+
+## 🧰 Technologies
+
+
+
+
+
+
+
+
+
+
+
+---
+
+## 📜 Licence
+
+
+
+Le projet est distribué sous **PolyForm Noncommercial License 1.0.0**.
+
+### ✅ Autorisé
+
+- utilisation non commerciale ;
+- étude du code ;
+- modification ;
+- partage dans les limites prévues par la licence.
+
+### 🚫 Exploitation commerciale
+
+Toute exploitation commerciale nécessite **une autorisation ou une licence commerciale distincte accordée par le titulaire des droits**.
+
+Voir :
+
+- [`LICENSE`](./LICENSE)
+- [`COMMERCIAL-LICENSE.md`](./COMMERCIAL-LICENSE.md)
+
+> ℹ️ PolyForm Noncommercial est une licence **source-available non commerciale** et non une licence open source au sens OSI.
+
+---
+
+## 🎯 Vision
+
+L'objectif à terme est de pouvoir préparer un poste de manière industrialisée :
+
+```text
+💻 Installation NixOS
+ ↓
+📦 Déploiement de la configuration commune
+ ↓
+👤 Première connexion utilisateur
+ ↓
+🔐 Personnalisation du mot de passe
+ ↓
+🔑 Personnalisation de la YubiKey
+ ↓
+✅ Poste opérationnel
+```
+
+
+
+### 💙 NixOS • KDE Plasma • FIDO2
+
+**Des postes reproductibles sans sacrifier l'expérience utilisateur.**
+
+