diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..bc675e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,72 @@
+# Librodrome
+
+Site vitrine du projet Le Librodrome — livre + chansons sur l'économie du don.
+
+## Stack
+
+- **Nuxt 4** (Vue 3, TypeScript, Nitro)
+- **Modules** : Nuxt Content, Pinia, UnoCSS, VueUse, Nuxt Image
+- **Icônes** : Lucide + Phosphor (via @iconify-json)
+- **Package manager** : pnpm
+- **Déploiement** : Docker + Traefik, CI via Woodpecker
+
+## Structure
+
+```
+app/
+  pages/           # Routes : index, lire/, ecouter/, autonomie, evenement, gratewizard, a-propos, admin/
+  components/      # admin, book, content, home, layout, player, song, ui
+  composables/     # useAudioPlayer, useBookData, useGrateWizard, usePlaylist, usePageContent, useSiteContent...
+  assets/css/      # main.css (UnoCSS)
+data/
+  pages/           # Contenu YAML par page (home, lire, ecouter, autonomie, evenement...)
+  site.yml         # Config globale du site
+server/
+  api/             # Endpoints API (admin, health)
+  middleware/      # Auth middleware
+docker/
+  Dockerfile       # Build multi-stage (dev + prod)
+  docker-compose.yml      # Production (Traefik)
+  docker-compose.dev.yml  # Dev Docker
+```
+
+## Ports dev (CRITIQUE)
+
+Chaque projet a un port fixe pour éviter les conflits Nuxt auto-increment :
+
+| Projet | Port | Config |
+|--------|------|--------|
+| **librodrome** | **3000** | `nuxt.config.ts` → `devServer.port: 3000` |
+| **GrateWizard** | **3001** | `package.json` → `next dev --port 3001` |
+| **SejeteralO frontend** | **3009** | `frontend/nuxt.config.ts` → `devServer.port: 3009` |
+| **SejeteralO backend** | **8000** | Makefile → `uvicorn --port 8000` |
+
+Script de gestion : `/home/yvv/Documents/PROD/DEV/dev-ports.sh` (status/kill/clean/start)
+
+**Ne jamais changer ces ports.** Si un port est occupé, tuer le process parasite plutôt que laisser Nuxt auto-incrémenter.
+
+## Intégration GrateWizard
+
+- URL dev configurée dans `app/app.config.ts` → `localhost:3001`
+- URL prod : `https://gratewizard.ml`
+- Ouverture en popup via `composables/useGrateWizard.ts`
+- GrateWizard est un projet Next.js séparé (`/home/yvv/Documents/PROD/DEV/GrateWizard`)
+
+## Contenu
+
+Le contenu des pages est dans `data/pages/*.yml` et chargé via `composables/usePageContent.ts`. Le contenu riche (articles) utilise Nuxt Content avec des fichiers Markdown.
+
+## Commandes
+
+```bash
+pnpm dev          # Dev server sur :3000
+pnpm build        # Build production
+pnpm generate     # Génération statique
+```
+
+## Conventions
+
+- Langue du site : français
+- Commits en français, style concis
+- CSS via UnoCSS (utility-first), pas de framework CSS externe
+- Composants Vue SFC avec `<script setup lang="ts">`