diff --git a/docs/onboarding/01-demarrage.md b/docs/onboarding/01-demarrage.md
new file mode 100644
index 0000000..a2e6632
--- /dev/null
+++ b/docs/onboarding/01-demarrage.md
@@ -0,0 +1,130 @@
+# 01 — Démarrage local
+
+Objectif : app qui tourne sur `http://localhost:3000` avec une DB, l'auth, et
+(optionnellement) le LLM et Stripe.
+
+## Prérequis
+
+- **Node ≥ 20** (le repo tourne en pratique sur Node 24)
+- **pnpm 10** (`packageManager` épinglé dans le `package.json` racine)
+- **Docker** (pour le PostgreSQL local via `docker-compose.yml`)
+- Pour le PDF : un **Chromium/Chrome** installé (dev macOS : Chrome suffit ; sinon variable `CHROMIUM_EXECUTABLE_PATH`)
+- Optionnel : le **CLI Stripe** (`stripe`) pour tester le paiement en local
+
+## Étapes
+
+```bash
+# 0. Dépendances (postinstall lance `nuxt prepare`)
+pnpm install
+
+# 1. Fichier d'environnement (voir la table ci-dessous)
+cp apps/app/.env.example apps/app/.env
+#   → puis édite apps/app/.env avec tes vraies clés
+
+# 2. PostgreSQL local (conteneur postgres:16 sur :5432)
+pnpm db:up
+
+# 3. Applique le schéma (crée toutes les tables)
+pnpm --filter @cvo/app prisma:migrate:deploy
+
+# 4. Lance l'app (front Vue + API Nitro dans le même process)
+pnpm dev            # http://localhost:3000
+```
+
+> `pnpm dev` lance `prisma generate && nuxt dev`. Nuxt charge automatiquement
+> `apps/app/.env` en dev.
+
+## Variables d'environnement (`apps/app/.env`)
+
+Toutes lues **côté serveur uniquement** (jamais exposées au client).
+
+| Variable | Rôle | Requis ? |
+|---|---|---|
+| `DATABASE_URL` | Connexion PostgreSQL (matche `docker-compose.yml`) | **Oui** |
+| `BETTER_AUTH_SECRET` | Secret de signature des sessions/tokens (min 32 chars) | **Oui** (en prod : fail-fast si absent, voir [08](./08-securite.md)) |
+| `APP_URL` | URL de base de l'app (magic-links, cookies) — **`https://…` en prod** | **Oui** |
+| `ANTHROPIC_API_KEY` | Clé API Claude (analyse/score/génération). Sans elle, `/api/candidature/*` répond 502 | Oui pour le flux CV |
+| `ANTHROPIC_BASE_URL` | Origine de l'API Anthropic (le code ajoute `/v1/messages`) | Non (défaut fourni) |
+| `DISABLE_GENERATION_LIMIT` | `true` = désactive le gate de crédits à la génération (**dev only**) | Non |
+| `STRIPE_SECRET_KEY` | Clé Stripe (test `sk_test_…`/`rk_test_…`) — checkout & webhook | Oui pour le billing |
+| `STRIPE_WEBHOOK_SECRET` | Secret de signature du webhook (`whsec_…`) | Oui pour le billing |
+| `SMTP_HOST` / `SMTP_PORT` / `SMTP_USER` / `SMTP_PASS` / `MAIL_FROM` | Envoi d'e-mail (magic-link). **Absent en dev → le lien est loggé dans la console** | Oui en **prod** |
+| `CHROMIUM_EXECUTABLE_PATH` | Chemin du binaire Chromium pour le rendu PDF (Docker/CI) | Non en dev macOS |
+
+## Se connecter en local (magic-link sans SMTP)
+
+Sans `SMTP_HOST`, l'e-mail n'est pas envoyé : le lien magic-link est **écrit dans la
+console du serveur dev**. Récupère-le dans les logs :
+
+```
+[DEV] Magic-link pour toi@example.com:
+  http://localhost:3000/api/auth/magic-link/verify?token=...&callbackURL=%2Fprofil
+```
+
+Colle l'URL dans le navigateur → tu es connecté. Le lien est **à usage unique** et
+expire en **10 min**. Le sign-in est **rate-limité à 3/min** (voir [08](./08-securite.md)).
+
+## Tester le paiement Stripe en local ⚠️ (piège vécu)
+
+Les crédits ne sont accordés **que par le webhook** `checkout.session.completed`. En
+local, Stripe ne peut pas joindre `localhost` seul : il faut le relais du CLI.
+
+```bash
+# 1. Crée les produits/prix des packs dans Stripe (idempotent)
+pnpm --filter @cvo/app stripe:seed
+
+# 2. Laisse tourner CE terminal pendant tout le dev billing :
+stripe listen --api-key <TA_CLÉ_.env> --forward-to localhost:3000/api/billing/webhook
+```
+
+**Deux pièges qui font que « le paiement passe mais les crédits n'augmentent pas » :**
+1. `stripe listen` **pas lancé** → l'événement n'atteint jamais le serveur.
+2. `stripe listen` connecté à un **autre compte Stripe** que ta clé `.env` (utilise
+   `--api-key <clé .env>` pour forcer le bon compte) — sinon les events partent ailleurs.
+
+Copie le `whsec_…` imprimé par `stripe listen` dans `STRIPE_WEBHOOK_SECRET`, puis
+**redémarre Nuxt** (l'env n'est lu qu'au boot). Détails complets : [07 — Billing](./07-billing-credits.md).
+
+## Scripts utiles
+
+### Racine (`package.json`)
+| Commande | Effet |
+|---|---|
+| `pnpm dev` | Lance l'app Nuxt (`apps/app`) |
+| `pnpm build` | Build `@cvo/shared` puis l'app (Nuxt/Nitro) |
+| `pnpm typecheck` | Build shared + `typecheck` récursif (vue-tsc + tsc strict) |
+| `pnpm test` | Build shared + tests Vitest récursifs |
+| `pnpm lint` | ESLint sur tout le repo |
+| `pnpm format` / `pnpm format:write` | Prettier (check / write) |
+| `pnpm db:up` / `pnpm db:down` | PostgreSQL local (Docker) |
+
+### App (`apps/app`, via `pnpm --filter @cvo/app <script>`)
+| Commande | Effet |
+|---|---|
+| `prisma:migrate:dev` | Crée une migration en dev (schéma modifié) |
+| `prisma:migrate:deploy` | Applique les migrations existantes |
+| `prisma:generate` | (Re)génère le client Prisma |
+| `stripe:seed` | Crée les produits/prix Stripe des packs |
+| `dev` / `build` / `start` / `preview` | Cycle de vie Nuxt |
+| `typecheck` / `test` | Qualité (par package) |
+
+## Gate qualité avant de merger
+
+Le repo est **PR-only** (aucun push direct sur `main`, seul l'owner merge). Un script
+rejoue les jobs CI en local :
+
+```bash
+bash scripts/pre-merge.sh            # lint · typecheck · build · test
+bash scripts/pre-merge.sh --health   # + boot Nuxt + probe /api/health (Postgres requis)
+```
+
+> ℹ️ La CI GitHub-hosted peut être rouge pour une raison **d'infra** (facturation
+> Actions au niveau du compte, pas de SMTP). On valide **en local**. Voir
+> [`docs/ci-gate.md`](../ci-gate.md).
+
+## Preuve de vie
+
+```bash
+curl -s http://localhost:3000/api/health
+# {"status":"ok","db":"up","service":"cvo-app","timestamp":"…"}
+```
diff --git a/docs/onboarding/02-architecture.md b/docs/onboarding/02-architecture.md
new file mode 100644
index 0000000..8640ccc
--- /dev/null
+++ b/docs/onboarding/02-architecture.md
@@ -0,0 +1,130 @@
+# 02 — Architecture
+
+## Le monorepo
+
+```
+cv-optimizer/
+├─ apps/
+│  └─ app/                    # L'application Nuxt 3 full-stack
+│     ├─ pages/               # Routes Vue (front)
+│     ├─ components/          # Composants Vue (ui/, cv/, landing/)
+│     ├─ composables/         # Logique front réutilisable (useAuth, useToast…)
+│     ├─ layouts/ middleware/ # Layout global + garde de navigation (auth)
+│     ├─ config/ i18n/        # Marque, pricing, textes FR
+│     ├─ assets/css/          # Tokens de design Tailwind v4
+│     ├─ utils/               # Utils front (photo-crop, health-label)
+│     ├─ server/              # ⬅️ L'API (serveur Nitro) — voir plus bas
+│     ├─ prisma/              # schema.prisma + migrations
+│     ├─ scripts/             # stripe-seed.ts
+│     └─ test/                # Tests unitaires Vitest (côté app)
+├─ packages/
+│  └─ shared/                 # @cvo/shared : types & logique partagés client ↔ serveur
+├─ docs/                      # Documentation (dont ce dossier onboarding/)
+├─ scripts/                   # pre-merge.sh, mock-llm.mjs
+└─ docker-compose.yml         # PostgreSQL local
+```
+
+### `apps/app/server/` — l'API (Nitro)
+
+C'est le cœur backend. Nitro mappe l'arborescence de fichiers sur des routes.
+
+```
+server/
+├─ api/                # Endpoints HTTP (le nom du fichier = la route + la méthode)
+│  ├─ auth/[...all].ts        # tout /api/auth/** délégué à Better Auth
+│  ├─ profile/…               # CRUD profil candidat
+│  ├─ candidature/…           # analyze + generate (LLM)
+│  ├─ candidatures/…          # CRUD des candidatures persistées
+│  ├─ cv/…                    # preview (HTML) + export-pdf
+│  ├─ billing/…               # checkout + webhook + summary (Stripe)
+│  ├─ usage/current.get.ts    # compteurs d'usage
+│  ├─ health.get.ts           # preuve de vie
+│  └─ csp-report.post.ts      # collecteur de violations CSP
+├─ middleware/auth.ts   # s'exécute sur CHAQUE requête : pose event.context.userId
+├─ plugins/00.validate-env.ts # fail-fast au boot (secrets prod)
+├─ routes/sitemap.xml.ts# routes non-/api (sitemap)
+├─ services/            # logique métier LLM (offer-analysis, matching, match-report…)
+└─ utils/               # briques serveur (prisma, auth, stripe, pdf, credits, cv-html…)
+```
+
+> **Convention Nitro** : `server/api/foo/bar.post.ts` → `POST /api/foo/bar`.
+> `[id]` = paramètre dynamique (`getRouterParam(event, 'id')`).
+> `[...all]` = catch-all (toutes les sous-routes).
+
+### `packages/shared` (`@cvo/shared`)
+
+Types TypeScript et **logique pure** partagés entre le front et le serveur : contrats
+d'API, types du CV, garde-fou de provenance, quotas, pricing. Importé partout via
+`@cvo/shared` (workspace pnpm). **Doit être buildé** (`tsc`) avant l'app — c'est fait
+automatiquement par `pnpm build`/`typecheck`/`test`. Voir [03](./03-modele-de-donnees.md)
+et [06](./06-pipeline-candidature.md).
+
+## Principe directeur : tout le sensible est côté serveur
+
+Le navigateur ne voit **jamais** : les clés API (Anthropic, Stripe), les prompts, les
+données brutes d'un autre utilisateur. Le front appelle des endpoints `/api/*` ; le
+serveur Nitro fait le travail (DB, LLM, Stripe, PDF) et ne renvoie que le strict
+nécessaire. C'est aussi une exigence RGPD (voir [`docs/rgpd.md`](../rgpd.md)).
+
+## Cycle de vie d'une requête API
+
+```
+Navigateur ──HTTP──▶ Nitro
+                       │
+                       ├─ 1. server/middleware/auth.ts
+                       │      résout la session Better Auth (cookie)
+                       │      → pose event.context.userId (ou undefined)
+                       │      ⚠️ NON bloquant : ne lève jamais 401 lui-même
+                       │
+                       ├─ 2. nuxt-security (headers, CSP, size limiter)
+                       │
+                       └─ 3. le handler de l'endpoint
+                              ├─ requireUserId(event) ── si besoin d'auth → 401 si absent
+                              ├─ validation Zod du body
+                              ├─ Prisma (DB) / services LLM / Stripe / PDF
+                              └─ réponse JSON (ou binaire pour le PDF)
+```
+
+### Le modèle d'authentification (à bien comprendre)
+
+C'est un modèle **opt-in par route**, en deux temps :
+
+1. **Producteur** — `server/middleware/auth.ts` tourne sur *toutes* les requêtes,
+   résout la session et **pose `event.context.userId`** (ou le laisse `undefined`).
+   Il **ne bloque jamais**.
+2. **Consommateur** — chaque endpoint qui exige l'auth appelle
+   **`requireUserId(event)`** (`server/utils/session.ts`), qui lit
+   `event.context.userId` et **lève une 401** s'il est absent.
+
+> ⚠️ **Conséquence pour toi** : un endpoint qui **oublie** `requireUserId` est
+> **ouvert au public**. C'est déjà arrivé (l'export PDF, corrigé dans l'audit sécu).
+> Réflexe : tout nouvel endpoint qui lit/écrit des données d'un user **commence** par
+> `const userId = requireUserId(event)`.
+
+### Le flux magic-link (Better Auth)
+
+```
+1. POST /api/auth/sign-in/magic-link  { email }   → envoie un lien (mail ou log dev)
+2. GET  /api/auth/magic-link/verify?token=…       → valide, pose le cookie de session,
+                                                     redirige vers callbackURL (ex. /profil)
+3. Requêtes suivantes : le cookie `better-auth.session_token` authentifie l'utilisateur
+```
+
+Better Auth stocke ses données dans les tables `sessions` / `accounts` / `verifications`
+(voir [03](./03-modele-de-donnees.md)). Côté front, le composable `useAuth()`
+enveloppe le client Better Auth.
+
+## Stack technique (récap)
+
+| Couche | Techno | Où |
+|---|---|---|
+| Front | Vue 3 (SFC), Nuxt 3 | `apps/app/pages`, `components`, `composables` |
+| Styles | Tailwind v4 (tokens `@theme`) | `apps/app/assets/css/main.css` |
+| API | Nitro (Nuxt server) | `apps/app/server` |
+| DB | PostgreSQL + Prisma | `apps/app/prisma`, `server/utils/prisma.ts` |
+| Auth | Better Auth (magic-link) | `server/utils/auth.ts` |
+| LLM | Claude (Anthropic) | `server/utils/anthropic.ts`, `server/services/*` |
+| PDF | Chromium (playwright-core) | `server/utils/pdf.ts` |
+| Paiement | Stripe Checkout | `server/utils/stripe.ts`, `server/api/billing/*` |
+| Types partagés | `@cvo/shared` | `packages/shared` |
+| Sécurité HTTP | nuxt-security (headers, CSP) | `apps/app/nuxt.config.ts` |
diff --git a/docs/onboarding/03-modele-de-donnees.md b/docs/onboarding/03-modele-de-donnees.md
new file mode 100644
index 0000000..997cc7f
--- /dev/null
+++ b/docs/onboarding/03-modele-de-donnees.md
@@ -0,0 +1,110 @@
+# 03 — Modèle de données (Prisma / PostgreSQL)
+
+Fichier : [`apps/app/prisma/schema.prisma`](../../apps/app/prisma/schema.prisma).
+Client Prisma exposé en singleton par [`server/utils/prisma.ts`](../../apps/app/server/utils/prisma.ts).
+
+> **Convention** : les modèles sont en `PascalCase` côté Prisma mais **mappés en
+> `snake_case` en base** via `@@map` (ex. `Candidature` → table `candidatures`,
+> `CreditLedger` → `credit_ledger`, `User` → `users`). ⚠️ En SQL direct (psql), utilise
+> les noms **snake_case**, pas les noms Prisma.
+
+## Deux invariants transverses
+
+1. **Soft-delete RGPD** — la plupart des tables métier ont un `deletedAt DateTime?`.
+   Une ligne avec `deletedAt` non nul = **supprimée logiquement**, à exclure des
+   lectures. Le helper `NOT_DELETED` (`server/utils/profile-serialize.ts`) sert de
+   filtre standard (`{ deletedAt: null }`). La purge physique est un futur job de
+   rétention (voir `DataGovernanceEvent`).
+2. **`userId` opaque sur les tables « additives »** — `Candidature`, `UsageEvent`,
+   `UsageCounter`, `CreditLedger` stockent un `userId` **sans FK Prisma** vers `users`.
+   C'était un choix pour que ces lots restent indépendants de l'ordre de merge. La
+   sécurité d'accès repose donc sur le **filtrage applicatif par `userId`** dans chaque
+   endpoint (voir [04](./04-backend-api.md)), pas sur une contrainte DB.
+
+## Domaines du schéma
+
+### 1. Profil candidat (la source de vérité du moteur)
+
+```
+User (1) ──1:1── Profile (1) ──1:n── Experience
+                              ├──1:n── Skill
+                              ├──1:n── Education
+                              └──1:n── Language
+```
+
+| Modèle | Table | Rôle & champs notables |
+|---|---|---|
+| `User` | `users` | Compte. `email` unique, `emailVerified`, `name`, `image`, `stripeCustomerId` (unique, créé à la 1re intention d'achat), `deletedAt`. Relations : `profile`, `sessions`, `accounts`. |
+| `Profile` | `profiles` | 1-1 avec User. **Identité factuelle** du CV : `fullName`, `email`, `phone`, `location`, `links[]`. `keySkills[]` = « compétences clés » (phrases verbe d'action). `headline`, `summary`. `baseCvDesign Json?` = thème « CV de base » capturé d'un PDF (style seul, **jamais le contenu**, le PDF n'est jamais stocké). |
+| `Experience` | `experiences` | `title`, `company`, `startDate`/`endDate` (`Date`, endDate null = en cours), `description`, `skillsUsed[]`, `orderIndex` (ordre d'affichage). |
+| `Skill` | `skills` | `label`, `level` (`SkillLevel` enum), `years?`, `orderIndex`. **Compétence RÉELLE déclarée** = source de vérité du moteur. |
+| `Education` | `education` | `degree`, `school`, dates, `description`, `orderIndex`. |
+| `Language` | `languages` | `label`, `level` (`LanguageLevel` = CEFR A1→C2 + `NATIVE`), `orderIndex`. |
+
+> 🔑 **À retenir** : le contenu du CV généré **ne peut venir que de ces tables**. Le
+> garde-fou de provenance (voir [06](./06-pipeline-candidature.md)) rejette tout élément
+> de CV qui ne pointe pas vers un `id` réel du profil.
+
+### 2. Candidature (CV persisté + suivi)
+
+| Modèle | Table | Rôle & champs notables |
+|---|---|---|
+| `Candidature` | `candidatures` | Une candidature = une offre analysée + un CV généré éditable + un suivi. `userId` (opaque), `label` (dénormalisé = `offer.title`), `status` (`CandidatureStatus`: DRAFT/SUBMITTED/INTERVIEW/REJECTED/ACCEPTED), `offerSnapshot Json` (`AnalyzedOffer` figée), `matchScore Int` (dénormalisé, tri/badge), `matchReport Json`, `generatedCv Json` (`RenderableCv`, **copie de travail éditable**), `design Json?` (`CvDesign` par-candidature, null = fallback profil/défaut). Index `[userId, deletedAt]`. |
+
+### 3. Metering (usage — base du billing freemium)
+
+On mesure l'usage **dès le MVP**, même gratuit. **Jamais de contenu** — que des
+compteurs et des volumes de tokens.
+
+| Modèle | Table | Rôle |
+|---|---|---|
+| `UsageEvent` | `usage_events` | 1 ligne par action. `type` (`UsageEventType`: GENERATION/EXPORT_PDF/EXTRACTION), `period` (yyyymm dénormalisé), `tokensIn`/`tokensOut`, `billable`. |
+| `UsageCounter` | `usage_counters` | Agrégat `(userId, period)` — incrémenté par upsert atomique à chaque événement. Unique `[userId, period]`. Sert au quota `export_pdf` (voir [`usage.ts`](#quotas)). |
+
+### 4. Billing — le ledger de crédits ⭐
+
+Modèle **grand livre append-only** : le **solde = somme des `delta`**. On n'écrit
+**jamais** un solde directement — chaque octroi/consommation est **une ligne**. Ça
+garantit l'audit et l'invariant « **jamais déficitaire** ».
+
+| Modèle | Table | Champs |
+|---|---|---|
+| `CreditLedger` | `credit_ledger` | `userId`, `delta Int` (jamais 0 : +N octroi/achat, −1 génération), `reason` (`CreditReason`), `idempotencyKey String?` (unique), `packKey String?`, `createdAt`. |
+
+**Les `reason` et leur idempotence :**
+
+| reason | delta | idempotencyKey | Signification |
+|---|---|---|---|
+| `FREE_GRANT` | +N | `free:<userId>` | Crédits offerts (1 seule ligne par user) |
+| `PURCHASE` | +N | id de session Stripe | 1 achat = 1 ligne (rejeu webhook sans effet) |
+| `GENERATION` | −1 | `null` | Consommation à la génération d'un CV |
+| `ADJUSTMENT` | ±N | `null` | Correction manuelle (SAV) |
+
+> La contrainte `@@unique([idempotencyKey])` fait tout le travail d'idempotence :
+> deux `PURCHASE` avec le même `sessionId` ⇒ le 2e est rejeté (Postgres autorise
+> plusieurs `NULL` distincts, donc les GENERATION/ADJUSTMENT ne se gênent pas). Détails
+> dans [07 — Billing](./07-billing-credits.md).
+
+### 5. Better Auth (tables satellites)
+
+Schéma imposé par Better Auth v1 (adaptateur Prisma). **Pas de soft-delete** (géré en
+dur par Better Auth). Champs en `camelCase` imposés par l'adaptateur.
+
+| Modèle | Table | Rôle |
+|---|---|---|
+| `Session` | `sessions` | Sessions actives (`token` unique, `expiresAt`, `ipAddress`, `userAgent`). |
+| `Account` | `accounts` | Comptes liés (OAuth/credentials ; ici = magic-link). |
+| `Verification` | `verifications` | Tokens de vérification — **le plugin magic-link y stocke ses tokens**. |
+
+### 6. RGPD (placeholder structurel)
+
+| Modèle | Table | Rôle |
+|---|---|---|
+| `DataGovernanceEvent` | `data_governance_event` | Trace des actions de gouvernance (`DataGovernanceAction`: RETENTION_APPLIED / ERASURE_REQUESTED / EXPORT_REQUESTED). `subjectRef` = référence opaque (ex. userId), pas de FK. **Placeholder** : la couche conformité réelle est cadrée par [`docs/rgpd.md`](../rgpd.md). |
+
+## Migrations
+
+- Dossier : `apps/app/prisma/migrations/`.
+- Créer une migration en dev : `pnpm --filter @cvo/app prisma:migrate:dev`.
+- Appliquer en CI/prod : `pnpm --filter @cvo/app prisma:migrate:deploy`.
+- Après changement de schéma : `pnpm --filter @cvo/app prisma:generate` (fait aussi par `dev`/`build`).
diff --git a/docs/onboarding/04-backend-api.md b/docs/onboarding/04-backend-api.md
new file mode 100644
index 0000000..36cf074
--- /dev/null
+++ b/docs/onboarding/04-backend-api.md
@@ -0,0 +1,120 @@
+# 04 — Backend & API (Nitro)
+
+Tout est dans `apps/app/server/`. Rappel de la convention Nitro : le **chemin du
+fichier = la route**, le **suffixe = la méthode** (`.get.ts`, `.post.ts`, `.put.ts`,
+`.patch.ts`, `.delete.ts`). `[id]` = param dynamique, `[...all]` = catch-all.
+
+## Table des endpoints
+
+Légende auth : 🔒 = `requireUserId` obligatoire · 🌐 = public.
+
+### Auth
+| Route | Auth | Fichier | Rôle |
+|---|---|---|---|
+| `ALL /api/auth/**` | 🌐 | `api/auth/[...all].ts` | Délègue **tout** à Better Auth (`sign-in/magic-link`, `magic-link/verify`, `get-session`, `sign-out`…). |
+
+### Profil (`api/profile/`)
+| Route | Auth | Rôle |
+|---|---|---|
+| `GET /api/profile` | 🔒 | Profil complet de l'utilisateur (`ProfileDTO`). |
+| `PUT /api/profile` | 🔒 | Met à jour l'en-tête/identité/résumé/keySkills (validation zod, champs bornés). |
+| `POST /api/profile/experiences` · `DELETE …/experiences/:id` | 🔒 | Ajoute / supprime (soft-delete) une expérience. |
+| `POST /api/profile/skills` · `DELETE …/skills/:id` | 🔒 | Idem compétences. |
+| `POST /api/profile/education` · `DELETE …/education/:id` | 🔒 | Idem formations. |
+| `POST /api/profile/languages` · `DELETE …/languages/:id` | 🔒 | Idem langues. |
+| `POST /api/profile/import-text` | 🔒 | Parse un CV **collé** (texte, ≤10 000 chars) en proposition éditable — **aucune écriture DB**, regex linéaires. |
+| `POST /api/profile/cv-design/extract` | 🔒 | Reçoit un **PDF multipart** (≤8 Mo), lance `extractCvContent` + `extractCvDesign` en parallèle. PDF jamais stocké. |
+| `PUT /api/profile/cv-design` · `DELETE /api/profile/cv-design` | 🔒 | Définit / retire le thème « CV de base » du profil. |
+
+> **Anti-IDOR** : les suppressions de sous-ressources filtrent par propriétaire —
+> `where: { id, profile: { userId } }`. Un `id` d'autrui renvoie **404** (ne divulgue pas
+> l'existence).
+
+### Candidature — pipeline LLM (`api/candidature/`)
+| Route | Auth | Rôle |
+|---|---|---|
+| `POST /api/candidature/analyze` | 🔒 | Offre collée → `{ offer, match }`. 2 appels LLM. **Hors gate crédits.** |
+| `POST /api/candidature/generate` | 🔒 | `{ offer, match }` → `{ cv, candidatureId }`. **Gate crédits + provenance + débit.** |
+
+Détails complets : [06 — Pipeline candidature](./06-pipeline-candidature.md).
+
+### Candidatures — CRUD (`api/candidatures/`)
+| Route | Auth | Rôle |
+|---|---|---|
+| `GET /api/candidatures` | 🔒 | Liste (scopée `userId`). |
+| `GET /api/candidatures/:id` | 🔒 | Une candidature complète (`findFirst { id, userId }` → 404 sinon). |
+| `PATCH /api/candidatures/:id` | 🔒 | Met à jour `cv`/`design`/`status`/`label`. Le `cv` **repasse le garde-fou de provenance** ; `status` validé contre l'enum. |
+| `DELETE /api/candidatures/:id` | 🔒 | Soft-delete. |
+
+### CV — rendu (`api/cv/`)
+| Route | Auth | Rôle |
+|---|---|---|
+| `POST /api/cv/preview` | 🔒 | `RenderableCv` (ou `{cv, design}`) → **HTML** (aperçu iframe). |
+| `POST /api/cv/export-pdf` | 🔒 | Idem → **PDF binaire** (Chromium). Gate quota `export_pdf` + metering. |
+
+> ⚠️ Ces deux endpoints exigent l'auth **depuis l'audit sécu** (avant, l'export était
+> public = DoS Chromium). Voir [08](./08-securite.md).
+
+### Billing (`api/billing/`)
+| Route | Auth | Rôle |
+|---|---|---|
+| `GET /api/billing/summary` | 🔒 | Solde de crédits (`{ creditBalance }`) + octroi gratuit idempotent au 1er accès. |
+| `POST /api/billing/checkout` | 🔒 | Crée une session Stripe Checkout pour un `packKey` → `{ url }`. |
+| `POST /api/billing/webhook` | 🌐* | Reçoit les événements Stripe (**signés** — voir [07](./07-billing-credits.md)). Crédite sur paiement confirmé. |
+
+\* Public au sens « pas de session utilisateur », mais **authentifié par signature Stripe**.
+
+### Divers
+| Route | Auth | Rôle |
+|---|---|---|
+| `GET /api/usage/current` | 🔒 | Compteurs d'usage de la période + état des quotas. |
+| `GET /api/health` | 🌐 | Preuve de vie (`{ status, db, service, timestamp }`). |
+| `POST /api/csp-report` | 🌐 | Collecteur de violations CSP (monitoring, logge). |
+| `GET /sitemap.xml` | 🌐 | `server/routes/sitemap.xml.ts` — sitemap SEO. |
+
+## `server/utils/` — les briques serveur
+
+| Fichier | Rôle |
+|---|---|
+| `prisma.ts` | Client Prisma **singleton** (réutilisé entre requêtes / HMR). |
+| `auth.ts` | Instance **Better Auth** (magic-link, adaptateur Prisma, cookies Secure, rate-limit). |
+| `session.ts` | **`requireUserId(event)`** (→ 401) et `getAuthSession(event)`. ⚠️ Passe `event.headers` directement (ne pas convertir en Request : verrouille le body). |
+| `auth-context.ts` | `resolveUserId(getSession, headers)` — logique pure injectable (testée sans Better Auth). |
+| `stripe.ts` | Client Stripe (singleton paresseux) ; `StripeNotConfiguredError`. |
+| `credits.ts` | **Le ledger de crédits** : `getCreditBalance`, `ensureFreeGrant`, `getOrInitBalance`, `consumeOneCredit` (transactionnel), `grantPurchasedCredits`. Voir [07](./07-billing-credits.md). |
+| `metering.ts` | Usage : `recordUsageEvent` (upsert atomique), `readUsageSummary`, `isUsageAllowed`. Logique de mapping **pure** et testée. |
+| `anthropic.ts` | Client Claude (structured output, tokens, erreurs). Voir [06](./06-pipeline-candidature.md). |
+| `mailer.ts` | Envoi e-mail (nodemailer). SMTP en prod ; **log console en dev** ; **échec explicite en prod sans SMTP** (ne logge jamais le token). |
+| `pdf.ts` | `renderHtmlToPdf(html)` — lance **Chromium headless** (playwright-core), print-to-PDF A4. |
+| `cv-html.ts` | `buildCvHtml(cv, design)` — génère le HTML du CV. **Échappe toutes les données user** (`esc()`). |
+| `cv-render-input.ts` | `parseRenderInput` / `parseRenderableCvBody` — validation zod **bornée** + garde-fou provenance du CV reçu. |
+| `cv-design.ts` / `cv-design-tokens.ts` | `loadBaseCvDesign`, `normalizeDesign`, `sanitizeColor/Font/Number/DataImage` (assainissement des tokens de design). |
+| `cv-render-input.ts` | (voir ci-dessus) bornes de taille anti-DoS. |
+| `profile-serialize.ts` | `toProfileDTO`, `NOT_DELETED` (filtre soft-delete). |
+| `candidature-serialize.ts` | `toCandidatureDTO` / `toListItemDTO`. |
+| `health.ts` | `checkDb` (ping `SELECT 1`) — interface `DbPinger` injectable. |
+
+## Plugins & middleware serveur
+
+- **`server/middleware/auth.ts`** — tourne sur **chaque** requête, pose
+  `event.context.userId` (non bloquant). Producteur consommé par `requireUserId`.
+- **`server/plugins/00.validate-env.ts`** — **fail-fast au boot** : en prod, refuse de
+  démarrer si `BETTER_AUTH_SECRET` est absent/faible ou si `APP_URL` n'est pas `https://`.
+- **`server/routes/sitemap.xml.ts`** — génère le sitemap (route hors `/api`).
+
+## Le patron d'un endpoint (à copier pour un nouveau)
+
+```ts
+export default defineEventHandler(async (event) => {
+  const userId = requireUserId(event)               // 1. auth (sauf endpoint public assumé)
+  const parsed = bodySchema.safeParse(await readBody(event))  // 2. validation zod
+  if (!parsed.success) throw createError({ statusCode: 400, message: '…' })
+
+  // 3. accès ressource TOUJOURS filtré par userId (anti-IDOR)
+  const row = await prisma.candidature.findFirst({ where: { id, userId, ...NOT_DELETED } })
+  if (!row) throw createError({ statusCode: 404, message: 'Introuvable.' })
+
+  // 4. travail (DB / service LLM / Stripe / PDF)
+  return toCandidatureDTO(row)                        // 5. réponse (DTO, pas la row brute)
+})
+```
diff --git a/docs/onboarding/05-frontend.md b/docs/onboarding/05-frontend.md
new file mode 100644
index 0000000..0dfa6c0
--- /dev/null
+++ b/docs/onboarding/05-frontend.md
@@ -0,0 +1,109 @@
+# 05 — Frontend (Nuxt 3 / Vue 3)
+
+Front en Vue 3 `<script setup lang="ts">`, Tailwind v4, Better Auth (magic-link),
+icônes `@lucide/vue`. **Tous les textes** viennent de `i18n/fr.ts` et **tous les
+contrats d'API** (chemins, codes, DTO) de `@cvo/shared` — jamais d'URL ni de string en dur.
+
+> **Auto-imports Nuxt** : les composables (`useAuth`, `useToast`…), le contenu de
+> `utils/`, et les composants `Ui*`/`Cv*` sont disponibles **sans import** dans les
+> templates.
+
+## Pages (`apps/app/pages/`)
+
+| Fichier | Route | Auth | Rôle | Endpoints appelés |
+|---|---|---|---|---|
+| `index.vue` | `/` | — | Landing marketing (hero, problème, étapes, garde-fou, pricing, FAQ). SEO + JSON-LD. | aucun |
+| `connexion.vue` | `/connexion` | — (`layout: false`, plein écran) | Saisie e-mail → envoi magic-link → écran « vérifie ta boîte ». | `useAuth().signIn` → Better Auth |
+| `profil.vue` | `/profil` | **Oui** | **Édition du profil** (en-tête, expériences, formations, compétences, langues, « compétences clés »), import copier-coller, import CV PDF (capture design + pré-remplissage). ~1700 lignes. | `GET/PUT /api/profile` ; `POST/DELETE /api/profile/{experiences,skills,languages,education}[/:id]` ; `POST /api/profile/import-text` ; `POST /api/profile/cv-design/extract` ; `PUT/DELETE /api/profile/cv-design` |
+| `candidature.vue` | `/candidature` | **Oui** | **Parcours candidature** : colle une offre → analyse + score → génération. Machine à états `input/analyzing/scored/generating`, gating crédits, garde profil vide. | `GET /api/billing/summary` ; `GET /api/profile` ; `POST /api/candidature/analyze` ; `POST /api/candidature/generate` |
+| `candidatures/index.vue` | `/candidatures` | **Oui** | Liste des candidatures (badge statut + score). | `GET /api/candidatures` |
+| `candidatures/[id].vue` | `/candidatures/:id` | **Oui** | **Éditeur CV in-app** : édition sections (provenance-safe), panneau design + photo, aperçu live débouncé (iframe), avertissement « 1 page », sauvegarde, statut, export PDF, suppression. | `GET/PATCH/DELETE /api/candidatures/:id` ; `POST /api/cv/preview` ; `POST /api/cv/export-pdf` |
+| `cv/demo.vue` | `/cv/demo` | — | Aperçu statique d'un `RenderableCv` de démo + export PDF. Page vitrine. | `POST /api/cv/export-pdf` |
+
+> ⚠️ **Note sécu** : `cv/demo` est **publique** mais l'export PDF exige désormais
+> l'auth (voir [08](./08-securite.md)) — l'export ne marche donc que connecté.
+
+## Composants (`apps/app/components/`)
+
+### `ui/` — le design system (préfixe auto-import `Ui*`)
+Briques génériques, sans logique métier :
+- **`Button.vue`** + **`button-classes.ts`** — le bouton délègue ses classes à la
+  fonction **pure** `buttonClasses(variant, size)` (variants `primary/secondary/ghost/danger`,
+  tailles `sm/md/lg`) → testable hors Vue (`test/button-classes.spec.ts`).
+- **`Input.vue`** / **`Textarea.vue`** — champs `v-model`, câblés a11y via `useField`,
+  habillés par **`FormField.vue`** (label + hint/erreur, ids `-error`/`-hint`).
+- **`Card.vue`** (conteneur `rounded-card`), **`Badge.vue`** (pastille), **`Dialog.vue`**
+  (modale de confirmation : `Teleport`, focus trap, Escape), **`State.vue`**
+  (loading/error/empty), **`Toaster.vue`** (pile de toasts, montée une fois dans `app.vue`),
+  **`Spinner.vue`**, **`Skeleton.vue`**.
+
+### `landing/`
+- **`MagicLinkForm.vue`** — formulaire e-mail (monté 2× sur la landing, ids via `useId`).
+  Prop `onSubmit` surchargeable, sinon `useAuth().signIn`.
+- **`CvMockup.vue`** — visuel hero « avant/après » (décoratif, `aria-hidden`).
+
+### `cv/` — le cœur métier CV
+- **`CvTemplate.vue`** ⭐ — **rendu déterministe d'un `RenderableCv`, seule source de
+  vérité du style à l'écran.** Rend le header (identité + contacts) puis chaque
+  `CvSection` typée par `kind` (narrowing exhaustif : `summary`/`keyskills`/`experience`/
+  `skills`/`education`/`languages`). L'élément `#cv-render` est la **cible du Chromium
+  headless** à l'export ; `.cv-page` = cible `@media print`. Tokens Tailwind uniquement.
+- **`CvDesignPanel.vue`** — panneau de tokens de design (`defineModel<CvDesign>`) :
+  disposition (`single`/`sidebar-left`), couleurs (accent, sidebar), `sidebarRadius`,
+  photo (position/taille/marge/padding), police (liste alignée sur `sanitizeFont` côté serveur).
+- **`CvPhotoInput.vue`** — upload + **recadrage carré client-side** (`defineModel<string|null>`
+  = data-URL JPEG). Cropper maison (drag + zoom), s'appuie sur `utils/photo-crop.ts`.
+  Sortie bornée (256–768 px, qualité JPEG dégradée pour rester sous ~620k chars, plafond serveur 700k).
+
+### Racine
+- **`HealthCheck.vue`** — appelle `/api/health`, affiche l'état via `healthLabel()`.
+
+## Composables (`apps/app/composables/`)
+
+| Composable | API exposée | Rôle |
+|---|---|---|
+| **`useAuth`** | `{ session, signIn(email)→bool, signOut(), pending, error }` | Enveloppe le **client** Better Auth (plugin magic-link). `signIn` envoie le lien (`callbackURL: '/profil'`). |
+| **`useField`** | `{ id, describedBy }` | Helper a11y pur (ids SSR-safe, `aria-describedby`). Consommé par `Input`/`Textarea`. |
+| **`useLanding`** | `{ m, brand, packs, freeGenerations, faqJsonLd }` | Interpole `{brand}`/`{freeGenerations}` dans la copy `fr`. |
+| **`useToast`** | `{ toasts, dismiss, success, error, info }` | État partagé (`useState`, SSR-safe). Auto-dismiss (6 s erreur / 4 s autres). Rendu par `UiToaster`. |
+
+## Layout & garde de navigation
+
+- **`layouts/default.vue`** — chrome global (header sticky + footer). Nav (si connecté) :
+  `/candidature`, `/profil`, `/candidatures`, `/credits`. Menu compte (dropdown maison),
+  `handleSignOut` → `/`. S'abonne à l'atom nanostores de Better Auth pour recopier `user`.
+- **`middleware/auth.ts`** (client) — `defineNuxtRouteMiddleware` : appelle
+  `GET /api/auth/get-session` (transfère les cookies en SSR), redirige vers `/connexion`
+  si absent. **Volontairement** il n'utilise **pas** l'atom `useAuth()` (toujours truthy,
+  hydraté trop tard → laissait passer des non-connectés).
+
+> Une page devient protégée en ajoutant `definePageMeta({ middleware: 'auth' })`.
+
+## Config & i18n
+
+- **`config/brand.ts`** — `export const BRAND = 'Teven'` (token de naming unique).
+- **`config/pricing.ts`** — `FREE_GENERATIONS = 5` (générations offertes à vie),
+  `CREDIT_PACKS` (`starter` 5 €/5 crédits, `standard` 12 €/15, featured) + helpers purs
+  **partagés avec le backend Stripe** (`packLookupKey`, `resolveCreditPack`, `packAmountCents`).
+- **`i18n/fr.ts`** — **toute la copy FR** (source unique, aucun texte en dur). `export const fr`
+  avec clés `brand/meta/nav/hero/problem/how/guardrail/audience/pricing/faq/finalCta/signup/footer`.
+  Placeholders `{brand}`/`{freeGenerations}` résolus par `useLanding`. Structuré pour devenir
+  le locale `fr` d'un futur module i18n.
+
+> ⚠️ **Écart doc/code à connaître** : la mémoire projet mentionne « 2 générations
+> offertes », mais **le code fait foi : `FREE_GENERATIONS = 5`**.
+
+## `utils/` front
+- **`photo-crop.ts`** — géométrie **pure** du recadrage carré (sans DOM, testée).
+- **`health-label.ts`** — `healthLabel(status)` → libellé FR (testé).
+
+## Styling — `assets/css/main.css`
+- **Tailwind v4** (`@import 'tailwindcss'`), **design tokens via `@theme`** = source
+  unique de vérité. **Règle d'équipe : aucune valeur en dur dans les composants**, tout
+  passe par les classes générées (`bg-brand-600`, `text-ink-700`, `rounded-card`…).
+- Direction « Chaleur professionnelle » : `brand` = indigo, `ink` = stone (neutres chauds),
+  échelles `success/warning/danger`, surfaces, ombres douces multi-couches. Police
+  **Plus Jakarta Sans** (via `@nuxt/fonts`, self-hosted au build).
+- **Bloc `@media print`** = la mise en page A4 de l'export PDF (cible Chromium) :
+  masque tout hors `.cv-print-root`/`.cv-page`, force le fond blanc, `break-inside: avoid`,
+  `print-color-adjust: exact`.
diff --git a/docs/onboarding/06-pipeline-candidature.md b/docs/onboarding/06-pipeline-candidature.md
new file mode 100644
index 0000000..f28c02a
--- /dev/null
+++ b/docs/onboarding/06-pipeline-candidature.md
@@ -0,0 +1,151 @@
+# 06 — Pipeline candidature (le cœur métier LLM)
+
+C'est **la** partie à comprendre avant de toucher à la génération. Elle transforme
+un texte d'offre + le profil réel en un CV structuré, **sans jamais inventer**.
+
+## Vue d'ensemble
+
+```
+   Texte d'offre (collé)                       Profil réel (DB)
+          │                                          │
+          ▼                                          │
+  ┌──────────────────────  POST /api/candidature/analyze  ─────────────┐
+  │  analyzeOffer() ─▶ AnalyzedOffer {title, requiredSkills, keywords}  │
+  │  buildMatchReport() ─▶ MatchReport {score, reasons, matched/missing}│
+  └────────────────────────────────────────────────────────────────────┘
+          │  { offer, match }  (rien n'est encore généré, ~peu de tokens)
+          ▼
+  ┌─────────────────────  POST /api/candidature/generate  ─────────────┐
+  │  ① gate crédits (solde ≥ 1)                                         │
+  │  ② matchProfileToOffer() ─▶ RenderableCv  (+ garde-fou provenance)  │
+  │  ③ identité factuelle écrasée côté serveur                         │
+  │  ④ adaptKeySkills() ─▶ section « compétences clés »                │
+  │  ⑤ recordUsageEvent + consumeOneCredit + persist Candidature       │
+  └────────────────────────────────────────────────────────────────────┘
+          │  { cv, candidatureId }  ─▶  éditeur /candidatures/:id
+```
+
+Deux étapes séparées **par design** : le score est calculé **avant** la génération
+(peu de tokens) pour prévenir l'utilisateur d'un match faible **avant** de consommer
+un crédit. C'est un garde-fou **économique**.
+
+## Le garde-fou d'honnêteté : la PROVENANCE (à ne jamais casser)
+
+Le principe « on n'invente rien » n'est **pas** qu'une consigne de prompt — c'est un
+**contrôle de code déterministe**, dans `packages/shared/src/provenance.ts`.
+
+- Chaque élément du CV généré (`header`, chaque bullet, chaque entrée d'expérience/
+  skill/formation/langue) porte une **`Provenance`** :
+  `{ profileItemId: string, reformulated: boolean }`.
+- `profileItemId` **doit** référencer un `id` **réel** du profil. `reformulated: true`
+  signale seulement que le libellé a été reformulé (transparence), jamais ajouté.
+- **`checkProvenance(cv, validIds)`** parcourt tout le CV et liste les violations
+  (`missing` = pas de provenance / id vide ; `unknown` = id absent du profil). Il **ne
+  fait pas confiance aux types TS** : la sortie LLM est une donnée externe, revalidée au
+  runtime.
+- **`assertValidCv(cv, validIds)`** est la version stricte : elle **lève
+  `ProvenanceError`** si le CV n'est pas 100 % sourcé. **Un CV non conforme n'atteint
+  jamais l'utilisateur.**
+
+L'ensemble des ids valides vient de **`collectProfileItemIds(profile)`** (`matching.ts`) :
+`profile.id` (header) + tous les ids d'expériences / skills / formations / langues.
+
+> 💡 Conséquence : même si le LLM « hallucine » une compétence, elle n'aura pas d'id de
+> provenance valide → le CV est rejeté (422). L'invention est impossible **par
+> construction**, pas par confiance dans le modèle.
+
+## Le client LLM — `server/utils/anthropic.ts`
+
+Tous les services passent par le type injectable **`LlmComplete = (req) => Promise<unknown>`**
+(réel = `anthropicComplete` ; faux en test → pas de réseau ni de clé).
+
+- **Modèle** : constante `DEFAULT_MODEL` dans `anthropic.ts` (surchargable par `req.model`).
+  Table `PRICING` (USD/M tokens) par modèle pour estimer le coût.
+- **Sortie structurée** : le body pose `output_config.format = { type: 'json_schema', schema }`.
+  Le LLM est **forcé** de répondre selon le JSON Schema fourni.
+- **Multimodal** : `LlmContentBlock` gère `text`, `document` (PDF base64), `image` — le
+  bloc document/image doit précéder le texte.
+- **Mesure des tokens** : lit `usage.input/output_tokens`, logge le coût (`event: 'llm_cost'`),
+  puis appelle `req.onUsage({ inputTokens, outputTokens })` → les endpoints cumulent pour
+  le metering. **Jamais de contenu loggé** (RGPD).
+- **Erreurs** : tout échec (clé manquante, HTTP non-ok, refus, JSON invalide) devient une
+  **`LlmError`**, convertie en **502 générique** par les endpoints (ne divulgue pas la config).
+
+> ⚠️ **Règle de schéma Anthropic** (déjà rencontrée, cause de 400→502) : `additionalProperties: false`
+> partout ; un champ nullable + enum s'écrit **`anyOf: [{enum:…}, {type:'null'}]`** (jamais
+> `type: ['string','null']`) ; et une grammaire trop grosse est factorisée en **`$defs` + `$ref`**
+> (cf. `RENDERABLE_CV_SCHEMA`). Voir la mémoire projet « anthropic-structured-output-schema-rules ».
+
+## Les services (`apps/app/server/services/`)
+
+Chaque service impose un JSON Schema **et** revalide/borne la sortie côté code.
+
+| Service | Fonction | Rôle | Modèle/effort | Bornage code |
+|---|---|---|---|---|
+| `offer-analysis.ts` | `analyzeOffer(text, deps)` | Texte brut → `AnalyzedOffer` | `effort: low`, 1024 tok, `ANALYZED_OFFER_SCHEMA` | tronque à 20 000 chars ; remap défensif |
+| `match-report.ts` | `buildMatchReport(profile, offer, deps)` | Score de match | `effort: low`, `MATCH_SCORE_SCHEMA` (LLM ne rend que `{score, reasons}`) | `clampScore`, `sanitizeReasons` (≤4), `computeKeywordCoverage` **déterministe** ; plafonne à 60 si score>70 mais 0 mot-clé couvert |
+| `matching.ts` | `matchProfileToOffer(profile, offer, deps)` | Génère le `RenderableCv` | `effort: medium`, 16000 tok, `RENDERABLE_CV_SCHEMA` (`$defs`/`$ref`) | `capCvLength` (max 6 exp, 4 bullets) puis **`assertValidCv`** |
+| `keyskills-adapt.ts` | `adaptKeySkills(keySkills, offer, deps)` | Adapte les phrases « compétences clés » réelles | `effort: low`, schéma local | filtre/trim/`.slice(0, keySkills.length)` (jamais plus que fourni) ; repli **verbatim** |
+| `cv-content-extract.ts` | `extractCvContent(pdfB64, deps)` | Extrait le **contenu** d'un CV PDF → `ParsedCvProfile` | `document`+`text`, `CV_CONTENT_SCHEMA` | `null→''`, keySkills bornées |
+| `cv-design-extract.ts` | `extractCvDesign(pdfB64, deps)` | Capture le **style** → `CvDesign` | `document`+`text`, `CV_DESIGN_SCHEMA` | `normalizeDesign` (hex/police/layout validés) |
+
+> Les deux derniers ne font **pas** partie du flux offre→CV : ils sont consommés par
+> **`POST /api/profile/cv-design/extract`** (import d'un CV PDF au profil), qui les lance
+> **en parallèle** (`Promise.all`) sur le même PDF. Le PDF n'est **jamais stocké ni loggé**.
+
+### Détail important dans `matching.ts`
+- `keySkills` est **retiré du profil envoyé au LLM** (`const { keySkills: _k, ...profilReel }`)
+  pour éviter que le modèle les recopie — elles sont réinjectées déterministe-ment à l'étape ④.
+- `RENDERABLE_CV_SCHEMA` est factorisé en `$defs`/`$ref` car inliner provenance × entrées
+  × 5 variantes de section dépasse la limite de grammaire compilée d'Anthropic (« compiled
+  grammar too large » → 400/502).
+
+## Étape 1 — `POST /api/candidature/analyze`
+
+Fichier : `server/api/candidature/analyze.post.ts`.
+1. `requireUserId` + validation zod `{ offerText }` (50–20 000 chars).
+2. Charge le `ProfileDTO` (`NOT_DELETED`, relations triées). **409 `profile_empty`** si
+   pas de profil, ou ni expérience ni skill.
+3. `complete` qui **cumule les tokens** des deux appels via `onUsage`.
+4. `analyzeOffer(offerText)` → `AnalyzedOffer` ; `buildMatchReport(profile, offer)` → `MatchReport`.
+5. `recordUsageEvent(type: 'extraction', billable: false)` (les 2 appels = 1 événement).
+6. Renvoie `{ offer, match }`. `LlmError` → **502**.
+
+> ⚠️ **`/analyze` n'est PAS derrière le gate de crédits** (il fait 2 appels LLM). C'est
+> un point d'abus économique connu (finding sécu #5) — une limite par utilisateur reste
+> à ajouter. Voir [08](./08-securite.md).
+
+## Étape 2 — `POST /api/candidature/generate`
+
+Fichier : `server/api/candidature/generate.post.ts`.
+1. `requireUserId` + validation zod `{ offer, match }` (renvoyés par /analyze, persistés
+   **sans recalcul LLM**).
+2. **Gate crédits AVANT tout appel LLM** : sauf `DISABLE_GENERATION_LIMIT=true`,
+   `getOrInitBalance(userId)` (octroi idempotent des générations offertes) ; si `balance < 1`
+   → **403** `data.code = 'quota_exceeded'`. Zéro token consommé si pas de crédit.
+3. Recharge le profil (**409 `profile_empty`**). Résout `fullName` (profil sinon compte)
+   → **409 `profile_name_missing`** si vide (évite un header vide / export cassé, avant le LLM).
+4. `matchProfileToOffer(profile, offer)` → `RenderableCv` (`capCvLength` + `assertValidCv`
+   déjà appliqués dans le service).
+5. **Identité écrasée côté serveur** (factuelle, jamais du LLM) : `cv.header.fullName` et
+   `cv.header.contacts = buildContacts(profile, account.email)`.
+6. **Compétences clés** : si `profile.keySkills.length`, `adaptKeySkills(...)` (repli
+   verbatim sur `catch`) → section `keyskills` (provenance = `profile.id`) insérée **juste
+   avant** la section `experience`.
+7. `recordUsageEvent(type: 'generation')` puis (sauf bypass) **`consumeOneCredit(userId)`**
+   — débit transactionnel **après succès**, jamais déficitaire.
+8. Persiste la `Candidature` (offre figée, score, report, CV, design seedé depuis
+   `profile.baseCvDesign`). Renvoie `{ cv, candidatureId }`.
+- Erreurs : `InsufficientCreditsError` (course sur le dernier crédit) → **403** ;
+  `ProvenanceError` → **422** ; `LlmError` → **502**.
+
+## Qui décide de quoi : LLM vs code
+
+| Le **LLM** fournit | Le **code** garde le contrôle sur |
+|---|---|
+| L'analyse d'offre (titre, skills, keywords) | La couverture de mots-clés (déterministe) |
+| `{score, reasons}` du match | Le bornage/plafonnement du score |
+| Le CV structuré priorisé | La troncature 1 page (`capCvLength`) |
+| L'adaptation des « compétences clés » | L'identité factuelle du header |
+| | Le débit de crédit |
+| | **Le garde-fou de provenance (`assertValidCv`)** |
diff --git a/docs/onboarding/07-billing-credits.md b/docs/onboarding/07-billing-credits.md
new file mode 100644
index 0000000..3f2c20f
--- /dev/null
+++ b/docs/onboarding/07-billing-credits.md
@@ -0,0 +1,99 @@
+# 07 — Billing & crédits
+
+Modèle économique acté : **packs de crédits one-shot** via **Stripe Checkout hébergé**.
+Pas d'abonnement, pas d'illimité. **1 crédit = 1 génération de CV.**
+
+- Catalogue (source de vérité) : `apps/app/config/pricing.ts`
+  - `FREE_GENERATIONS = 5` (générations offertes à vie, via le ledger)
+  - `starter` : 5 € / 5 crédits · `standard` : 12 € / 15 crédits (featured)
+- Contrats partagés : `packages/shared/src/billing.ts`
+- Fichiers serveur : `server/utils/{credits,stripe}.ts`, `server/api/billing/*`, `scripts/stripe-seed.ts`
+
+## Le ledger de crédits (append-only) ⭐
+
+Le solde n'est **jamais** une colonne : c'est la **somme des `delta`** de la table
+`credit_ledger` (voir [03](./03-modele-de-donnees.md)). Chaque octroi/consommation est
+**une ligne**. Avantages : audit complet + invariant « **jamais déficitaire** ».
+
+Fonctions clés — `server/utils/credits.ts` :
+
+| Fonction | Rôle |
+|---|---|
+| `getCreditBalance(db, userId)` | Solde = `SUM(delta)` (≥ 0 par construction). |
+| `ensureFreeGrant(db, userId)` | Insère la ligne `FREE_GRANT` **une seule fois** (idempotent via `idempotencyKey = free:<userId>` ; avale le P2002). |
+| `getOrInitBalance(userId)` | `ensureFreeGrant` puis lit le solde. |
+| `consumeOneCredit(userId)` | **Transaction** : relit le solde, insère `−1` seulement si `≥ 1`, sinon lève `InsufficientCreditsError`. |
+| `grantPurchasedCredits({userId, sessionId, packKey, credits})` | Insère `PURCHASE +credits` avec `idempotencyKey = sessionId` (rejeu webhook sans effet). |
+
+## Flux d'achat (Checkout hébergé)
+
+```
+Front (/credits) ──POST /api/billing/checkout {packKey}──▶ Serveur
+                                                             │ résout le prix par lookup_key
+                                                             │ (aucun prix piloté par le client)
+                                                             ▼
+                                              crée une session Stripe Checkout
+                     ◀────────────── { url } ──────────────
+Front redirige vers l'URL Stripe (paiement hébergé)
+                                                             │
+       Stripe ──POST /api/billing/webhook (signé)──────────▶ Serveur
+                     checkout.session.completed / paid       │ grantPurchasedCredits()
+                                                             ▼
+                                              +N crédits (ligne PURCHASE)
+```
+
+Points de sécurité importants :
+- **Prix/crédits déterminés côté serveur** depuis le catalogue (`resolveCreditPack`) — le
+  client n'envoie qu'un `packKey`. Le prix Stripe est retrouvé par **`lookup_key`**
+  (`teven_credits_<pack>`), aucun ID Stripe stocké en base.
+- **Les crédits ne sont accordés QUE par le webhook**, sur `checkout.session.completed`
+  avec `payment_status === 'paid'`. Jamais depuis un appel client.
+- **Webhook signé** : la signature est vérifiée sur le **corps brut** (`readRawBody` +
+  `constructEvent`) avec `STRIPE_WEBHOOK_SECRET`. Signature invalide → 400.
+- **Idempotence** : `grantPurchasedCredits` s'appuie sur `@@unique([idempotencyKey])` =
+  `session.id` → un rejeu de webhook ne crédite pas deux fois.
+
+## Le seed Stripe
+
+`scripts/stripe-seed.ts` (lancé par `pnpm --filter @cvo/app stripe:seed`) crée les
+**produits + prix** dans Stripe depuis `CREDIT_PACKS`. **Idempotent** : cherche le prix
+par `lookup_key`, ne recrée pas s'il existe. Le checkout retrouve ensuite le prix par
+cette même clé.
+
+## Consommation à la génération
+
+À `POST /api/candidature/generate`, après une génération **réussie**, `consumeOneCredit`
+débite 1 crédit **dans une transaction** (relit le solde, insère `−1` si `≥ 1`). Le gate
+d'entrée (`balance < 1` → 403) évite de lancer le LLM sans crédit. Bypass dev :
+`DISABLE_GENERATION_LIMIT=true`.
+
+## ⚠️ Tester en local — les pièges vécus
+
+Symptôme classique : **« le paiement passe mais les crédits n'augmentent pas »**. Le
+webhook n'atteint pas le serveur. Causes, par ordre de fréquence :
+
+1. **`stripe listen` pas lancé** → l'événement n'est jamais forwardé à `localhost`.
+2. **`STRIPE_WEBHOOK_SECRET` ≠ secret imprimé par `stripe listen`** → signature invalide → 400.
+3. **`stripe listen` connecté à un AUTRE compte Stripe que `STRIPE_SECRET_KEY`** — le plus
+   fourbe : un `stripe trigger` marche (même compte que la CLI) mais les **vrais achats**
+   de l'app partent sur l'autre compte → jamais forwardés.
+
+**La bonne commande** (force le bon compte + imprime le secret à coller dans `.env`) :
+```bash
+stripe listen --api-key <ta clé sk_test .env> --forward-to localhost:3000/api/billing/webhook
+```
+Puis **redémarre Nuxt** (l'env n'est lu qu'au boot).
+
+Diagnostic compte : `curl .../v1/account -u sk:` vs `stripe get /v1/account` — les deux
+doivent renvoyer le **même** `acct_…`.
+
+Rattraper un achat déjà payé (sans re-payer) :
+```bash
+stripe events resend <evt_id> --api-key <clé>   # idempotent par session id
+```
+
+## Côté front (`pages/credits.vue`)
+
+Le webhook crédite de façon **asynchrone**. La page mémorise le solde avant la
+redirection (localStorage) et **poll** le solde au retour (`?status=success`) avec un
+backoff, jusqu'à ce qu'il augmente — sinon l'utilisateur verrait un solde figé.
diff --git a/docs/onboarding/08-securite.md b/docs/onboarding/08-securite.md
new file mode 100644
index 0000000..7266501
--- /dev/null
+++ b/docs/onboarding/08-securite.md
@@ -0,0 +1,70 @@
+# 08 — Sécurité
+
+> 📄 **La référence complète est [`SECURITY-AUDIT.md`](../../SECURITY-AUDIT.md)** à la
+> racine (12 findings détaillés + correctifs). Ce fichier est le résumé « ce qu'un dev
+> doit savoir au quotidien ».
+
+## Ce qui est en place (ne pas casser)
+
+### Authentification & autorisation
+- Modèle **opt-in par route** : `requireUserId(event)` sur tout endpoint qui touche des
+  données user (voir [02](./02-architecture.md) et [04](./04-backend-api.md)).
+- **Anti-IDOR** : chaque accès par `id` filtre par propriétaire
+  (`findFirst({ where: { id, userId } })` ou `{ id, profile: { userId } }`). Un id
+  d'autrui → **404**.
+- **Cookies de session** : `HttpOnly` + `SameSite=Lax` (défauts Better Auth) + **`Secure`
+  forcé en prod** (`useSecureCookies`) + `trustedOrigins` explicite.
+- **Fail-fast au boot** (`server/plugins/00.validate-env.ts`) : en prod, l'app **refuse
+  de démarrer** si `BETTER_AUTH_SECRET` est absent/faible ou si `APP_URL` n'est pas `https://`.
+
+### Headers HTTP (nuxt-security, dans `nuxt.config.ts`)
+- **CSP active** (bloquante), HSTS, `X-Frame-Options: DENY`, `X-Content-Type-Options:
+  nosniff`, Referrer-Policy, Permissions-Policy.
+- `img-src` autorise `data:` (photos de CV) ; `font-src`/`style-src` autorisent Google
+  Fonts (utilisées par le rendu CV — voir note plus bas).
+- Violations CSP remontées à **`/api/csp-report`** (monitoring). Pour re-valider après un
+  changement, repasser la CSP en Report-Only (`contentSecurityPolicyReportOnly: true`),
+  naviguer, lire les logs, puis réactiver.
+- **`requestSizeLimiter`** réglé au-dessus de 8 Mo pour ne pas casser l'upload PDF de
+  `cv-design/extract`.
+
+### Rate limiting
+- **Magic-link** : `POST /api/auth/sign-in/magic-link` bridé à **3/min** (Better Auth
+  `rateLimit.customRules`) — anti email-bombing / énumération.
+- ⚠️ **Stockage en mémoire par instance** : en multi-instance/serverless, il faut un store
+  partagé (Redis/DB), sinon la limite est contournable.
+
+### Injection & rendu
+- **Pas de SQL brut** : Prisma paramétré partout.
+- **Rendu CV échappé** : `cv-html.ts` passe **toutes** les données user par `esc()`. Les
+  tokens de design sont assainis (`sanitizeColor/Font/Number`). La **photo** n'accepte que
+  des **data-URL raster** (SVG rejeté → pas de script, pas de SSRF).
+- **Provenance** : le garde-fou anti-invention est aussi une barrière d'intégrité (voir
+  [06](./06-pipeline-candidature.md)).
+
+### Billing
+- Webhook Stripe **signé** (corps brut), montants **server-side**, idempotence par
+  `session.id`. Voir [07](./07-billing-credits.md).
+
+### Secrets
+- `.env` / `.output` / `.nuxt` **gitignorés** ; aucun secret réel committé ; `.env.example`
+  ne contient que des placeholders `changeme`.
+
+## Ce qui reste à faire (avant/juste après prod)
+
+| Sujet | Détail |
+|---|---|
+| **Limite `/analyze` par user** | `/api/candidature/analyze` fait 2 appels LLM **hors gate crédits** → abus de coût possible. Ajouter une limite par `userId` (table metering). |
+| **Sandbox Chromium** | `pdf.ts` lance Chromium avec `--no-sandbox`. En conteneur, préférer un user non-root / egress filtré. |
+| **Polices CV auto-hébergées** | Retirer les hôtes Google Fonts de la CSP (rendu CV) — durcit encore. |
+| **Store rate-limit partagé** | Redis/DB si multi-instance. |
+| **Mises à jour** | Prisma 6→7, Nuxt 3→4 (majeures, à planifier). |
+
+## Réflexes quand tu codes
+
+1. Nouvel endpoint qui touche des données user ? → **`requireUserId` en première ligne**.
+2. Accès par `id` ? → **filtre par `userId`**, renvoie 404 (pas 403).
+3. Nouvel input ? → **valide avec zod + borne les tailles** (anti-DoS).
+4. Tu affiches/rends de la donnée user en HTML ? → **échappe** (utilise `esc()` / le gabarit codé).
+5. Tu logges ? → **jamais** de contenu (offre, profil, CV), de token, ni de clé (RGPD).
+6. Tu changes la CSP ? → **repasse en Report-Only**, valide au navigateur, puis réactive.
diff --git a/docs/onboarding/09-conventions.md b/docs/onboarding/09-conventions.md
new file mode 100644
index 0000000..304e4cc
--- /dev/null
+++ b/docs/onboarding/09-conventions.md
@@ -0,0 +1,75 @@
+# 09 — Conventions & workflow
+
+## Règles d'ingénierie (non négociables)
+
+- **PR-only** — aucun push direct sur `main`. **Seul l'owner (Thibault) merge.**
+- **PR > 400 lignes → split.**
+- **CI/gate vert obligatoire** avant merge (lint · typecheck · build · test).
+- **TypeScript strict** des deux côtés (front Vue + serveur Nitro). Pas de `any` non justifié.
+- **Tailwind : design tokens uniquement** (`assets/css/main.css`), **aucune valeur en dur**
+  dans les composants (voir [05](./05-frontend.md)).
+- **FR-first** — toute la copy passe par `i18n/fr.ts` (pas de texte en dur dans les templates).
+- **Contrats via `@cvo/shared`** — jamais d'URL d'API ni de type dupliqué en dur ; importe
+  les chemins/DTO/constantes depuis le package partagé.
+
+## Les garde-fous produit (à respecter dans le code)
+
+1. **Honnêteté** — on ne fabrique jamais de fausses compétences/expériences. Concrètement :
+   le garde-fou de **provenance** (`assertValidCv`) doit rester en place sur toute écriture
+   de CV (génération **et** `PATCH /api/candidatures/:id`). Voir [06](./06-pipeline-candidature.md).
+2. **Jamais déficitaire** — les crédits passent **toujours** par le ledger (une ligne par
+   mouvement), jamais d'écriture directe d'un solde. Voir [07](./07-billing-credits.md).
+3. **RGPD** — tout le traitement sensible reste **côté serveur** ; on ne **logge jamais**
+   de contenu (offre, profil, CV), de token d'auth, ni de clé API. Le soft-delete
+   (`deletedAt`) est la règle sur les tables métier. Voir [`docs/rgpd.md`](../rgpd.md).
+
+## Tests (Vitest)
+
+- Emplacements : `apps/app/test/` (logique app) et `packages/shared/test/` (contrats/garde-fou).
+- Lancer : `pnpm test` (racine, build shared + tests récursifs) ou
+  `pnpm --filter @cvo/app test`.
+- **Philosophie** : la logique **pure** est extraite pour être testée sans Vue ni base ni
+  réseau. Exemples : `button-classes.ts`, `usage.ts` (quotas), `provenance.ts` (garde-fou),
+  `photo-crop.ts`, `metering.ts` (builders purs), `match.ts` (score déterministe).
+- **Services LLM** : testés par **injection** d'un faux `LlmComplete` (pas d'appel réseau
+  ni de clé). Voir `scripts/mock-llm.mjs` et les `*.spec.ts` des services.
+- Le test « **item sans provenance → rejeté** » protège le garde-fou anti-invention : il
+  **doit** rester vert (c'est le cœur de la promesse produit).
+
+## CI & gate
+
+- Workflow : `.github/workflows/ci.yml` — 2 jobs sur les PR vers `main` :
+  - **quality** : lint · typecheck · build · test.
+  - **health** : boot Nuxt + probe `/api/health` contre un Postgres éphémère.
+- ⚠️ La CI GitHub-hosted peut être **rouge pour une raison d'infra** (facturation Actions
+  au niveau du compte, pas de SMTP). Dans ce cas, on **valide en local** :
+  ```bash
+  bash scripts/pre-merge.sh            # rejoue lint·typecheck·build·test
+  bash scripts/pre-merge.sh --health   # + boot + probe santé (Postgres requis)
+  ```
+  Détails : [`docs/ci-gate.md`](../ci-gate.md).
+
+## Git & commits
+
+- Branches : `feat/…`, `fix/…`, `chore/…`, `docs/…`.
+- Messages de commit en **français**, format type `type(scope): résumé` (ex.
+  `fix(security): …`, `feat(billing): …`). Corps explicatif si non trivial.
+- Ouvre une PR vers `main`, colle une exécution verte du gate, laisse l'owner merger.
+
+## Nommage & marque
+
+- Le nom de marque est un **token unique** : `config/brand.ts` (`BRAND = 'Teven'`). Aucune
+  autre occurrence en dur ; les messages i18n portent `{brand}`, interpolé par `useLanding`.
+
+## Où ajouter quoi (aide-mémoire)
+
+| Tu veux… | Va dans… |
+|---|---|
+| Un nouvel endpoint | `apps/app/server/api/…` (+ `requireUserId`, zod, filtre `userId`) |
+| Un type/contrat partagé client↔serveur | `packages/shared/src/…` (+ ré-export dans `index.ts` avec `.js`) |
+| De la logique LLM | `apps/app/server/services/…` (injecte `LlmComplete`, impose un JSON Schema, borne la sortie) |
+| Un composant UI générique | `apps/app/components/ui/…` |
+| Un écran | `apps/app/pages/…` (+ `definePageMeta({ middleware: 'auth' })` si protégé) |
+| Du texte affiché | `apps/app/i18n/fr.ts` |
+| Un token de style | `apps/app/assets/css/main.css` (`@theme`) |
+| Un changement de schéma DB | `apps/app/prisma/schema.prisma` + migration |
diff --git a/docs/onboarding/README.md b/docs/onboarding/README.md
new file mode 100644
index 0000000..732324a
--- /dev/null
+++ b/docs/onboarding/README.md
@@ -0,0 +1,50 @@
+# Onboarding — Teven (cv-optimizer)
+
+> Bienvenue 👋 Cette doc est écrite pour qu'un dev qui arrive sur le projet soit
+> **autonome en une demi-journée** : comprendre l'archi, lancer le projet, savoir
+> où se trouve quoi, et pouvoir modifier une feature sans casser les garde-fous.
+
+## C'est quoi Teven ?
+
+Un **SaaS web français** qui génère un CV **reformulé et hiérarchisé** à partir du
+profil réel d'un candidat et d'une offre d'emploi collée. On adapte le CV à l'offre,
+on **n'invente jamais** de compétences ou d'expériences.
+
+> ### ⛔ Le garde-fou produit non négociable : l'honnêteté
+> La plateforme **reformule et priorise l'existant**, elle ne fabrique jamais de faux.
+> Ce principe est appliqué **techniquement** par un garde-fou de « provenance »
+> (voir [06 — Pipeline candidature](./06-pipeline-candidature.md)). Si tu touches à la
+> génération, ce garde-fou doit rester intact.
+
+## Comment lire cette doc
+
+Lis dans l'ordre si tu débarques ; sinon pioche par sujet.
+
+| # | Fichier | Pour… |
+|---|---|---|
+| 01 | [Démarrage](./01-demarrage.md) | Installer, configurer l'`.env`, lancer l'app en local |
+| 02 | [Architecture](./02-architecture.md) | Vue d'ensemble : monorepo, Nuxt/Nitro, cycle d'une requête, auth |
+| 03 | [Modèle de données](./03-modele-de-donnees.md) | Le schéma Prisma expliqué modèle par modèle |
+| 04 | [Backend & API](./04-backend-api.md) | Tous les endpoints, les `server/utils`, les plugins/middleware |
+| 05 | [Frontend](./05-frontend.md) | Pages, composants, composables, styling |
+| 06 | [Pipeline candidature (LLM)](./06-pipeline-candidature.md) | Le cœur métier : offre → analyse → match → génération → design |
+| 07 | [Billing & crédits](./07-billing-credits.md) | Stripe, le ledger de crédits, le webhook |
+| 08 | [Sécurité](./08-securite.md) | Durcissement, CSP, rate-limit, secrets |
+| 09 | [Conventions & workflow](./09-conventions.md) | Règles d'ingénierie, PR, tests, RGPD, i18n |
+
+## Le projet en 30 secondes
+
+- **Monorepo pnpm** : `apps/app` (l'app Nuxt 3 full-stack) + `packages/shared` (types & logique partagés client ↔ serveur, alias `@cvo/shared`).
+- **Full-stack Nuxt 3** : le front Vue 3 et l'API (serveur **Nitro**, dossier `apps/app/server/`) vivent dans le même projet. **Tout le sensible** (profil, offre, appels au LLM Claude, génération, Stripe) est **côté serveur** — aucune clé ni donnée brute n'atteint le navigateur.
+- **PostgreSQL** via **Prisma** (ORM + migrations).
+- **Auth** : Better Auth, **magic-link** (pas de mot de passe).
+- **LLM** : Claude (API Anthropic) pour analyser l'offre, scorer le match et générer le CV.
+- **PDF** : Chromium headless (playwright-core), rendu HTML → PDF côté serveur.
+- **Paiement** : Stripe Checkout (packs de crédits one-shot, pas d'abonnement).
+
+## Fichiers de référence à la racine
+
+- [`README.md`](../../README.md) — présentation courte + démarrage.
+- [`SECURITY-AUDIT.md`](../../SECURITY-AUDIT.md) — audit sécu complet (12 findings + correctifs).
+- [`docs/rgpd.md`](../rgpd.md) — cadrage RGPD (placeholder structurel).
+- [`docs/ci-gate.md`](../ci-gate.md) — la CI et le gate qualité.