diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a7a3886
--- /dev/null
+++ b/README.md
@@ -0,0 +1,372 @@
+<div align="center">
+
+# 🎲 Boidelo
+
+**L'application de jeux de soirée — questions, défis et cartes entre amis**
+
+![Android](https://img.shields.io/badge/Android-7.0%2B-3DDC84?logo=android)
+![Java](https://img.shields.io/badge/Java-8-orange?logo=java)
+![Gradle](https://img.shields.io/badge/Gradle-8.12.0-02303A?logo=gradle)
+![SDK](https://img.shields.io/badge/compileSdk-35-34A853?logo=android)
+![License](https://img.shields.io/badge/License-Private-grey)
+
+</div>
+
+---
+
+## 📖 Description
+
+**Boidelo** est une application Android de jeux de soirée regroupant plusieurs mini-jeux autour d'un hub central. Entrez les noms des joueurs, choisissez un jeu, et laissez l'ambiance opérer !
+
+L'application propose trois jeux distincts ainsi qu'un consulteur de règles de jeux d'ambiance populaires.
+
+---
+
+## 🎮 Jeux disponibles
+
+### 1. Boidelo Classic
+
+Le jeu original de questions et défis. Inspiré de jeux comme *King's Cup* ou *Never Have I Ever*.
+
+- **150+ questions** préchargées depuis un fichier JSON, avec 10 catégories distinctes
+- Questions dynamiques avec remplacement de variables (`<J1>`, `<J2>`, `<J3>`, `<variante>`)
+- **Défis multi-manches** avec compte à rebours et message de fin
+- Gestion intelligente : pas d'accumulation de défis simultanés
+- Système de **gorgées** (boire / distribuer) avec accord grammatical automatique
+- Catégorisation automatique des questions avec couleur de fond dynamique :
+  - Ciblage, Classement, Jugement, Duel, Interactif, Défi, Variante, Caliente, Vote, Classique
+- Paramètres personnalisables : nombre de questions, gorgées supplémentaires, durée des défis
+- **Intégration OpenAI** (optionnelle) pour générer des questions via ChatGPT
+
+### 2. 89++
+
+Un jeu de cartes avec timer et défis spéciaux.
+
+- Objectif : ne pas être celui qui atteint ou dépasse **89**
+- Règles spéciales : Valet (−10), Dame (changement de sens), Roi (choix de valeur)
+- Gorgées distribuées à chaque dizaine atteinte (70 = double !)
+- **9 types de défis** aléatoires :
+  - Changement de sens, Immunité, Gorgée surprise, Joker (passer son tour), Échange de mains, Double prochaine valeur, Compte mystère, Tour générale, Victime au choix
+- Timer configurable pour les défis
+- Suivi des gorgées par joueur
+
+### 3. Papelito (Undercover)
+
+Un jeu de déduction sociale. Trouvez l'Undercover avant qu'il ne soit trop tard !
+
+- **20 paires de mots** préchargées (Pizza/Burger, Chat/Chien, Vin/Bière, etc.)
+- Attribution aléatoire des rôles : **Civil**, **Undercover**, **Mr. White**
+- Mécanique de **discussion → vote → élimination**
+- Conditions de victoire :
+  - Civils gagnent si tous les Undercovers sont éliminés
+  - Undercovers gagnent s'ils sont en nombre ≥ aux Civils
+- Gestion des égalités de votes (personne n'est éliminé)
+- Machine à états avec validation des transitions légales
+
+### 4. Règles de jeux
+
+Consultez les règles des jeux d'ambiance populaires directement dans l'application.
+
+---
+
+## 🏗 Architecture
+
+### Vue d'ensemble
+
+Boidelo suit un pattern **Repository + Séparation des responsabilités**. Chaque jeu est isolé dans son propre package avec sa propre logique métier.
+
+```
+app/src/main/java/com/example/boidelov3/
+├── hub/                           # Hub central
+│   ├── GameSelectionActivity.java # Activité LAUNCHER (point d'entrée)
+│   ├── adapter/
+│   │   └── GameAdapter.java       # RecyclerView adapter
+│   └── model/
+│       └── GameInfo.java          # Modèle (nom, description, icône, type)
+│
+├── games/                         # Jeux isolés par package
+│   ├── boideloclassic/            # Boidelo Classic
+│   │   ├── BoideloClassicSetupActivity.java
+│   │   ├── BoideloClassicParamsActivity.java
+│   │   ├── BoideloClassicGameActivity.java
+│   │   └── manager/
+│   │       ├── BoideloPlayerManager.java
+│   │       └── BoideloPlayerRowManager.java
+│   ├── game89/                    # 89++
+│   │   ├── Game89SetupActivity.java
+│   │   ├── Game89GameActivity.java
+│   │   ├── Game89Player.java      # Modèle joueur
+│   │   └── Game89ChallengeManager.java  # Gestionnaire de défis
+│   └── papelito/                  # Papelito (Undercover)
+│       ├── PapelitoSetupActivity.java
+│       ├── PapelitoGameActivity.java
+│       ├── PapelitoResultActivity.java
+│       ├── PapelitoResultAdapter.java
+│       ├── PapelitoGame.java      # Logique complète du jeu
+│       └── PapelitoPlayer.java    # Modèle joueur (Serializable)
+│
+├── data/                          # Couche d'accès aux données
+│   ├── QuestionRepository.java    # Chargement JSON + SharedPreferences
+│   ├── Result.java                # Wrapper type-safe succès/erreur
+│   ├── PlayerStats.java           # Stats joueur (Parcelable)
+│   └── QuestionCategory.java      # Catégorisation + couleurs
+│
+├── game/                          # Logique métier commune
+│   └── GameEngine.java            # Moteur de jeu (pur Java)
+│
+├── utils/                         # Utilitaires
+│   ├── ErrorHandler.java
+│   ├── SecureConfig.java
+│   ├── SoundManager.java
+│   └── SoundGenerator.java
+│
+├── MainActivity.java              # Legacy (à supprimer)
+├── Jeux.java                      # Legacy (à supprimer)
+├── JeuxParametres.java            # Legacy (à supprimer)
+├── EndGameActivity.java           # Legacy (à supprimer)
+├── OpenAIService.java             # Service OpenAI
+├── ChatGPTTask.java               # Task async OpenAI
+├── DatabaseConnection.java        # Connexion PostgreSQL
+├── Question.java                  # Modèle de question
+├── Questions.java                 # Conteneur de questions (Gson)
+├── PreferencesKeys.java           # Constantes SharedPreferences
+└── BoideloAnimationUtils.java     # Animations UI
+```
+
+### Flux d'une partie
+
+Chaque jeu suit le même schéma d'activité :
+
+```
+Hub (GameSelectionActivity)
+  └─► Setup (saisie des joueurs)
+        └─► Parameters (configuration, optionnel)
+              └─► Game (partie en cours)
+                    └─► End Game (statistiques & résultats)
+```
+
+### Pattern Result<T, E>
+
+Le projet utilise un wrapper type-safe pour la gestion des erreurs, évitant les exceptions non contrôlées :
+
+```java
+Result<Questions, QuestionLoadException> result = repository.loadQuestions();
+if (result.isSuccess()) {
+    Questions questions = result.getData();
+} else {
+    Exception error = result.getError();
+}
+```
+
+---
+
+## 🛠 Stack technique
+
+| Élément | Version / Détail |
+|---|---|
+| **Langage** | Java 8 |
+| **Min SDK** | 24 (Android 7.0) |
+| **Target / Compile SDK** | 35 (Android 15) |
+| **Build system** | Gradle 8.12.0 + AGP 8.12.0 |
+| **UI** | Material Design 3, AppCompat 1.7.0 |
+| **Layout** | ConstraintLayout 2.2.0 |
+| **Réseau** | OkHttp 4.12.0 |
+| **JSON** | Gson 2.11.0 |
+| **Base de données** | pgjdbc-ng 0.8.3 (PostgreSQL, actuellement inutilisé) |
+| **Tests unitaires** | JUnit 4.13.2, Mockito 5.7.0, Robolectric 4.11.1 |
+| **Tests UI** | AndroidX Test JUnit 1.2.1, Espresso 3.6.1 |
+
+---
+
+## 🧪 Tests
+
+Le projet dispose de **11 classes de test** couvrant l'ensemble des jeux et des composants de données :
+
+| Classe de test | Fichier |
+|---|---|
+| `GameEngineTest` | `game/GameEngineTest.java` (15 tests) |
+| `ResultTest` | `data/ResultTest.java` (8 tests) |
+| `PlayerStatsTest` | `data/PlayerStatsTest.java` |
+| `QuestionCategoryTest` | `data/QuestionCategoryTest.java` |
+| `QuestionTest` | `QuestionTest.java` |
+| `QuestionsClassTest` | `QuestionsClassTest.java` |
+| `BoideloPlayerManagerTest` | `games/boideloclassic/manager/BoideloPlayerManagerTest.java` |
+| `Game89PlayerTest` | `games/game89/Game89PlayerTest.java` |
+| `Game89ChallengeManagerTest` | `games/game89/Game89ChallengeManagerTest.java` |
+| `PapelitoPlayerTest` | `games/papelito/PapelitoPlayerTest.java` |
+| `PapelitoGameTest` | `games/papelito/PapelitoGameTest.java` |
+
+---
+
+## 🔨 Compilation et installation
+
+### Prérequis
+
+- **Android Studio** (recommandé) ou **JDK 17-21** + SDK Android
+- Android SDK avec compileSdk 35
+
+### Build depuis la ligne de commande
+
+```bash
+# Cloner le projet
+git clone <url-du-repo>
+cd boidelo
+
+# Build
+./gradlew build
+
+# APK debug
+./gradlew assembleDebug
+
+# Installer sur un appareil connecté
+adb install -r app/build/outputs/apk/debug/app-debug.apk
+```
+
+### Exécuter les tests
+
+```bash
+# Tous les tests unitaires
+./gradlew test
+
+# Tests instrumentés (appareil/émulateur requis)
+./gradlew connectedAndroidTest
+
+# Test spécifique
+./gradlew test --tests com.example.boidelov3.game.GameEngineTest
+```
+
+> ⚠️ **Note :** Un bug connu avec Gradle 8.13 peut causer l'échec des tests unitaires en CLI. Utilisez Android Studio ou un JDK 17-21 pour contourner le problème.
+
+### Clean
+
+```bash
+./gradlew clean
+```
+
+---
+
+## 🎨 Interface
+
+- **Material Design 3** avec composants modernes (MaterialCardView, TextInputLayout, etc.)
+- **Mode sombre** avec thèmes dédiés (`values-night/`)
+- **Animations fluides** : fade in/out, slide, color transition, button press/release
+- **Feedback haptique** et effets sonores via `SoundManager` / `SoundGenerator`
+- **Palette principale** : Violet (`#9395D3`) / Lavande (`#B3B7EE`) sur fond blanc cassé (`#FBF9FF`)
+- Couleurs dynamiques par catégorie de question (10 couleurs distinctes)
+- Toutes les activités en mode **portrait**
+
+---
+
+## 📁 Structure des ressources
+
+```
+app/src/main/res/
+├── anim/          # 10 animations (slide, fade, button, color)
+├── drawable/      # Icônes de jeux, boutons, fonds
+├── layout/        # 19 layouts XML
+│   ├── activity_game_selection.xml       # Hub principal
+│   ├── activity_boidelo_classic_setup.xml
+│   ├── activity_boidelo_classic_params.xml
+│   ├── activity_boidelo_classic_game.xml
+│   ├── activity_game89_setup.xml
+│   ├── activity_game89_game.xml
+│   ├── activity_papelito_setup.xml
+│   ├── activity_papelito_game.xml
+│   ├── activity_papelito_result.xml
+│   ├── dialog_papelito_vote.xml
+│   └── dialog_papelito_word_reveal.xml
+├── values/        # Strings, couleurs, thèmes, styles
+├── values-night/  # Variantes mode sombre
+├── mipmap-*/      # Icônes launcher (mdpi → xxxhdpi)
+└── xml/           # Backup rules, data extraction rules
+```
+
+---
+
+## 📊 Données
+
+Les questions de Boidelo Classic sont stockées dans `app/src/main/assets/question.json`. Chaque question contient :
+
+- `id` — identifiant unique
+- `question` — texte avec placeholders (`<J1>`, `<variante>`, `<manches>`)
+- `gorger` — nombre de gorgées
+- `distribution` / `recois` — flags pour boire ou distribuer
+- `variante` — liste de variantes alternatives
+- `manches` — nombre de manches pour les défis
+- `arret` — message de fin de défi
+
+---
+
+## 🔐 Configuration
+
+### Clé API OpenAI (optionnel)
+
+Les clés sensibles sont stockées dans `local.properties` (non versionné) :
+
+```properties
+OPENAI_API_KEY=sk-votre-cle-ici
+```
+
+La classe `SecureConfig` fournit un accès sécurisé à ces valeurs.
+
+### Base de données PostgreSQL
+
+La connexion PostgreSQL est préparée mais le backend n'est pas encore en production. Les identifiants BuildConfig sont intentionnellement vides — l'usage d'une API backend est recommandé.
+
+---
+
+## 🚀 Ajouter un nouveau jeu
+
+1. Créer un package sous `com.example.boidelov3.games.<nom_du_jeu>`
+2. Implémenter les activités **Setup**, **Game** et **Result** (suivre le flux standard)
+3. Ajouter une valeur à l'enum `GameInfo.GameType`
+4. Enregistrer le jeu dans `GameSelectionActivity.setupGamesList()`
+5. Ajouter le cas dans le `switch` de `GameSelectionActivity.onItemClick()`
+6. Déclarer les activités dans `AndroidManifest.xml` avec `screenOrientation="portrait"`
+7. Ajouter l'icône drawable `ic_<nom_du_jeu>.xml`
+8. Écrire les tests unitaires correspondants
+
+---
+
+## 📝 Conventions
+
+- **Langue métier** : français (`gorgees`, `manches`, `caliente`)
+- **Code technique** : anglais (`allPlayers`, `activeManches`)
+- **Interface utilisateur** : français
+- **Clés SharedPreferences** : centralisées dans `PreferencesKeys.java`
+- **Nommage layouts** : `activity_<jeu>_<écran>.xml`, `dialog_<jeu>_<usage>.xml`
+- **Nommage strings** : préfixe par jeu (`papelito_`, `boidelo_`, `game89_`)
+
+---
+
+## 📋 Statut des fonctionnalités
+
+| Fonctionnalité | Statut |
+|---|---|
+| Hub de sélection de jeux | ✅ Opérationnel |
+| Boidelo Classic (150+ questions) | ✅ Opérationnel |
+| 89++ (cartes + défis) | ✅ Opérationnel |
+| Papelito / Undercover | ✅ Opérationnel |
+| Règles de jeux | 🚧 En cours |
+| Intégration OpenAI (questions IA) | 🚧 En développement |
+| Connexion PostgreSQL | 🔧 Prête (backend requis) |
+| Mode sombre | ✅ Opérationnel |
+| Tests unitaires (11 classes) | ✅ Opérationnel |
+
+---
+
+## 📚 Documentation supplémentaire
+
+- [`ANALYSE_CODE.md`](ANALYSE_CODE.md) — Analyse détaillée du code (ancienne architecture)
+- [`README_ARCHITECTURE.md`](README_ARCHITECTURE.md) — Documentation de l'architecture Repository
+- [`CLAUDE.md`](CLAUDE.md) — Guide de développement pour l'IA
+
+---
+
+## 📄 Licence
+
+Projet privé — tous droits réservés.
+
+---
+
+*Boidelo — buvez responsable* 🍻