diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dcf9930
--- /dev/null
+++ b/README.md
@@ -0,0 +1,124 @@
+# lions-user-manager-server-api
+
+> Contrats partagés entre le serveur et le client — DTOs, interfaces de services, enums, validations
+
+## Rôle
+
+Ce module constitue la couche de contrats (API layer) du projet Lions User Manager. Il est compilé en JAR et publié sur le **Gitea Package Registry** pour être consommé par `server-impl` et `client` comme dépendance Maven.
+
+---
+
+## Contenu
+
+### DTOs
+
+| DTO | Description |
+|-----|-------------|
+| `UserDTO` | Représentation complète d'un utilisateur Keycloak |
+| `UserCreationDTO` | Données de création d'un utilisateur |
+| `UserUpdateDTO` | Données de mise à jour |
+| `RoleDTO` | Rôle Keycloak |
+| `RealmDTO` | Realm Keycloak |
+| `RealmAssignmentDTO` | Assignation d'un utilisateur à un realm |
+| `AuditLogDTO` | Entrée de journal d'audit |
+| `SyncHistoryDTO` | Historique de synchronisation |
+| `SyncConsistencyDTO` | Rapport de cohérence sync |
+| `ImportResultDTO` | Résultat d'import CSV |
+
+### Interfaces de services
+
+| Interface | Responsabilité |
+|-----------|----------------|
+| `UserService` | CRUD utilisateurs, export/import CSV |
+| `RoleService` | Gestion des rôles par realm |
+| `AuditService` | Consultation et export des logs d'audit |
+| `SyncService` | Synchronisation Keycloak ↔ base de données |
+| `RealmAuthorizationService` | Gestion des realms autorisés |
+
+### Interfaces de ressources (JAX-RS)
+
+| Interface | Path |
+|-----------|------|
+| `UserResourceApi` | `/api/users` |
+| `RoleResourceApi` | `/api/roles` |
+| `AuditResourceApi` | `/api/audit` |
+| `SyncResourceApi` | `/api/sync` |
+| `RealmResourceApi` | `/api/realms` |
+| `RealmAssignmentResourceApi` | `/api/realm-assignments` |
+
+### Enums
+
+- `StatutUser` — ACTIF, INACTIF, SUSPENDU
+- `TypeRole` — ADMIN, USER, VIEWER
+- `TypeActionAudit` — CREATE, UPDATE, DELETE, LOGIN, LOGOUT, SYNC
+
+### Validations
+
+- `ValidationConstants` — Constantes partagées (longueurs, patterns regex)
+
+---
+
+## Dépôt Git
+
+`https://git.lions.dev/lionsdev/lions-user-manager-server-api`
+
+---
+
+## Maven Registry
+
+Le jar est disponible sur le **Gitea Package Registry** :
+
+```
+groupId    : dev.lions.user.manager
+artifactId : lions-user-manager-server-api
+version    : 1.0.0
+registry   : https://git.lions.dev/api/packages/lionsdev/maven
+```
+
+### Consommer ce module (server-impl / client)
+
+```xml
+<dependency>
+    <groupId>dev.lions.user.manager</groupId>
+    <artifactId>lions-user-manager-server-api</artifactId>
+    <version>1.0.0</version>
+</dependency>
+```
+
+```xml
+<repositories>
+    <repository>
+        <id>gitea-lionsdev</id>
+        <url>https://git.lions.dev/api/packages/lionsdev/maven</url>
+    </repository>
+</repositories>
+```
+
+---
+
+## Publier une nouvelle version
+
+1. Incrémenter la version dans `../pom.xml` (parent)
+2. Exécuter depuis la racine du monorepo :
+
+```bash
+# Windows
+script\publish-api.bat
+
+# Linux / macOS
+./script/publish-api.sh
+```
+
+---
+
+## Build local
+
+```bash
+mvn clean install -DskipTests
+```
+
+---
+
+## Licence
+
+Propriétaire — Lions Dev © 2025