diff --git a/README.md b/README.md
index 040f84c..b6bfa0f 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,103 @@
 # Coltura
 
-CRM/ERP - Symfony 8 + API Platform 4 + Nuxt 4
+CRM/ERP — Symfony 8 (API Platform 4) + Nuxt 4
+
+## Stack
+
+- **Backend** : PHP 8.4, Symfony 8, API Platform 4, Doctrine ORM, PostgreSQL 16
+- **Frontend** : Nuxt 4 (SPA), Vue 3, Pinia, Tailwind CSS, @malio/layer-ui
+- **Auth** : JWT HTTP-only cookie (Lexik)
+- **Infra** : Docker Compose (dev + prod multi-stage)
+- **CI/CD** : Gitea Actions (auto-tag + build Docker)
 
 ## Quick Start
 
 ```bash
-make start    # Start Docker containers
-make install  # Install dependencies, run migrations, build frontend
+make start           # Demarrer les containers Docker
+make install         # Composer, migrations, fixtures, build Nuxt
 ```
 
-Dev frontend: `make dev-nuxt` (hot reload on port 3003)
+Dev frontend (hot reload) :
+
+```bash
+make dev-nuxt        # Port 3003
+```
 
 ## Ports
 
-| Service  | Port |
-|----------|------|
-| API      | 8083 |
-| Frontend | 3003 |
+| Service    | Port |
+|------------|------|
+| API (Nginx)| 8083 |
+| Frontend   | 3003 |
 | PostgreSQL | 5436 |
 
+## Commandes
+
+| Commande | Description |
+|----------|-------------|
+| `make start` | Demarrer les containers |
+| `make stop` | Arreter les containers |
+| `make restart` | Redemarrer les containers |
+| `make install` | Install complet |
+| `make reset` | Tout supprimer et reinstaller |
+| `make dev-nuxt` | Serveur dev Nuxt (hot reload) |
+| `make shell` | Shell dans le container PHP |
+| `make cache-clear` | Vider le cache Symfony |
+| `make migration-migrate` | Lancer les migrations |
+| `make fixtures` | Charger les fixtures |
+| `make db-reset` | Reset BDD + migrations + fixtures |
+| `make test` | PHPUnit |
+| `make php-cs-fixer-allow-risky` | Fix code style PHP |
+| `make logs-dev` | Tail logs Symfony |
+
+## Structure
+
+```
+src/                 # Backend Symfony
+  Entity/            # Entites Doctrine
+  ApiResource/       # Ressources API Platform
+  State/             # Providers & Processors
+  Repository/        # Repositories Doctrine
+  DataFixtures/      # Fixtures
+config/              # Config Symfony
+migrations/          # Migrations Doctrine
+frontend/            # App Nuxt 4
+  pages/             # Pages Vue
+  layouts/           # Layouts
+  components/        # Composants
+  composables/       # Composables (useApi, useAppVersion)
+  stores/            # Stores Pinia (auth, ui)
+  services/          # Services API + DTOs
+  i18n/              # Traductions
+infra/
+  dev/               # Docker dev (Dockerfile, nginx, php.ini, xdebug)
+  prod/              # Docker prod (multi-stage, nginx, php-prod.ini)
+.gitea/workflows/    # CI Gitea (auto-tag, build Docker)
+```
+
+## CI/CD
+
+- **Auto Tag** : push sur `develop` → bump `config/version.yaml` → tag `vX.Y.Z`
+- **Build Docker** : push tag `v*` → build image multi-stage → push Gitea Registry
+
+Secrets requis dans Gitea :
+- `RELEASE_TOKEN` — PAT avec droits `write:repository`
+- `REGISTRY_TOKEN` — token pour le registry Docker
+
 ## Credentials (dev)
 
-- admin / admin (ROLE_ADMIN)
-- alice / alice (ROLE_USER)
-- bob / bob (ROLE_USER)
+| Username | Password | Role |
+|----------|----------|------|
+| admin | admin | ROLE_ADMIN |
+| alice | alice | ROLE_USER |
+| bob | bob | ROLE_USER |
+
+## Conventions
+
+### Commits
+
+```
+<type>(<scope optionnel>) : <message>
+```
+
+Types : `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test`