diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7a4e794
--- /dev/null
+++ b/README.md
@@ -0,0 +1,116 @@
+# Cockpit Jira — Migration / suivi
+
+Application **React + Vite + TypeScript** qui interroge **Jira Cloud** (REST API v3) pour afficher stories, sous-tâches, burnup, vues board / sprint / Gantt, jalons, etc. Les secrets **ne doivent pas** être exposés dans des variables `VITE_*` en production.
+
+---
+
+## Prérequis
+
+- **Node.js** 20 ou 22 (LTS recommandé)
+- **npm** (fourni avec Node)
+- Un compte **Jira Cloud** avec **jeton API** Atlassian
+- En **développement** : pas de `VITE_JIRA_BASE_URL` obligatoire (proxy Vite, voir ci-dessous)
+
+---
+
+## Installation (une fois)
+
+```bash
+git clone <url-du-depot>
+cd jira-descours
+npm install
+```
+
+---
+
+## Configuration locale
+
+1. Copie le modèle d’environnement :
+
+   ```bash
+   copy .env.example .env
+   ```
+
+   Sous macOS / Linux : `cp .env.example .env`
+
+2. Édite **`.env`** (fichier **non versionné**) et renseigne au minimum :
+
+| Variable | Obligatoire en local | Rôle |
+|----------|----------------------|------|
+| `JIRA_DOMAIN` | Oui | Sous-domaine Atlassian sans `https`, ex. `mon-entreprise` → `https://mon-entreprise.atlassian.net` |
+| `JIRA_EMAIL` | Oui | E-mail du compte Atlassian utilisé pour l’API |
+| `JIRA_API_KEY` | Oui | [Jeton API](https://id.atlassian.com/manage-profile/security/api-tokens) |
+
+3. Variables **optionnelles** utiles (voir commentaires dans `.env.example`) :
+
+   - `VITE_JIRA_EPIC_KEY`, `VITE_JIRA_BOARD_ID`, `VITE_JIRA_SPRINT_FIELD`, `VITE_JIRA_STORY_POINTS_FIELD`, `VITE_JIRA_PAGE_SIZE`
+   - `VITE_MY_JIRA_ACCOUNT_ID` / `VITE_MY_JIRA_EMAIL` pour le filtre « Ma vue »
+   - `VITE_JIRA_BROWSE_BASE_URL` pour les liens « ouvrir dans Jira » si tu veux forcer une URL précise
+
+**Important :** en local, **`VITE_JIRA_BASE_URL` n’est pas utilisée** pour les appels API : Vite sert les requêtes sous **`/jira-api`**, qui sont proxifiées vers Jira avec l’en-tête **Basic** (`JIRA_EMAIL` + `JIRA_API_KEY`). Ne mets **jamais** `JIRA_API_KEY` dans une variable `VITE_*` (elles sont intégrées au bundle client).
+
+---
+
+## Lancer le projet en local
+
+```bash
+npm run dev
+```
+
+Puis ouvre l’URL affichée dans le terminal (en général **http://localhost:5173**).
+
+- Hot reload activé tant que le serveur Vite tourne.
+- Arrêt : `Ctrl+C` dans le terminal.
+
+---
+
+## Autres commandes npm
+
+| Commande | Usage |
+|----------|--------|
+| `npm run build` | Vérification TypeScript + build de production dans `dist/` |
+| `npm run preview` | Sert le contenu de `dist/` en local (après un `build`) — utile pour tester le rendu « prod » sans Docker |
+
+---
+
+## Production (rappel court)
+
+- Le build **bake** les variables `VITE_*` au moment de `npm run build`.
+- **`VITE_JIRA_BASE_URL`** doit alors pointer vers un **proxy HTTPS** (même domaine ou sous-domaine) qui relaie vers Jira et ajoute l’auth **côté serveur** — pas le jeton dans le navigateur.
+- Déploiement Docker / NAS / Gitea : voir **`docs/DEPLOY_SYNOLOGY_GITEA.md`** et **`.env.deploy.example`**.
+
+---
+
+## Réglages persistants (navigateur)
+
+Une partie de la configuration (jalons, buckets de statuts, sprints exclus, jours non travaillés Gantt, etc.) est stockée dans **localStorage** après sauvegarde depuis l’UI « Réglages ».
+
+---
+
+## Dépannage express
+
+| Problème | Piste |
+|----------|--------|
+| Erreur du type « URL Jira absente » en **preview** / prod | Définir `VITE_JIRA_BASE_URL` vers ton proxy HTTPS (inutile en `npm run dev` si le proxy `/jira-api` est configuré). |
+| 401 / 403 sur les appels en dev | Vérifier `JIRA_EMAIL`, `JIRA_API_KEY`, et que `JIRA_DOMAIN` correspond bien à ton site Atlassian. |
+| CORS en prod si tu pointes directement sur `*.atlassian.net` | Normal : utiliser un **proxy** sur ton domaine. |
+| `npm run build` échoue | Lancer `npm run build` et lire la sortie TypeScript / Vite ; vérifier les `VITE_*` si tu les as définies pour un build de test. |
+
+---
+
+## Structure utile du dépôt
+
+| Chemin | Rôle |
+|--------|------|
+| `src/` | Application React |
+| `src/api/jiraClient.ts` | Client HTTP Jira (`/jira-api` en dev) |
+| `vite.config.js` | Proxy dev + `__JIRA_ORIGIN__` depuis `JIRA_DOMAIN` |
+| `.env.example` | Modèle des variables d’environnement |
+| `Dockerfile` / `docker-compose.yml` | Image Nginx + build Vite pour déploiement |
+| `docs/DEPLOY_SYNOLOGY_GITEA.md` | Déploiement NAS / Gitea / Docker |
+
+---
+
+## Licence / usage interne
+
+Projet privé orienté usage interne (Descours & Cabaud / migration). Adapter le JQL et les clés d’épopée selon ton instance si tu dupliques le dépôt.