Correction du soucis de mise à jour via l'application

Ajout d'une partie spécifique pour des PNJ dans la partie campagne

.env.example

@@ -38,3 +38,15 @@ LLM_MODEL=gemma4:26b
 # 1min.ai (si LLM_PROVIDER=onemin)
 ONEMIN_API_KEY=
 ONEMIN_MODEL=gpt-4o-mini
+
+# --- Mises a jour automatiques (Watchtower) ------------------------------
+# Watchtower verifie les nouvelles versions de core/brain/web et permet
+# le declenchement manuel via l'UI (bouton "Mettre a jour"). Postgres et
+# MinIO sont exclus volontairement.
+#
+# Activer : COMPOSE_PROFILES=autoupdate + WATCHTOWER_TOKEN non vide.
+# COMPOSE_PROFILES=autoupdate
+# WATCHTOWER_TOKEN=change-me-use-openssl-rand-hex-32
+# WATCHTOWER_MONITOR_ONLY=false   # true = detecter sans appliquer
+# WATCHTOWER_SCHEDULE=0 0 4 * * *
+# TZ=Europe/Paris

.gitea/workflows/e2e.yml

@@ -0,0 +1,95 @@
+name: E2E Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: web/package-lock.json
+
+      - name: Create .env for stack
+        run: |
+          cat > .env <<'EOF'
+          POSTGRES_PASSWORD=ci-postgres-pass
+          BRAIN_INTERNAL_SECRET=ci-brain-secret
+          ADMIN_USERNAME=admin
+          ADMIN_PASSWORD=ci-admin-pass
+          WEB_PORT=8081
+          LLM_PROVIDER=ollama
+          EOF
+
+      - name: Build & start stack
+        run: |
+          docker compose -f docker-compose.yml -f docker-compose.e2e.yml up -d --build
+
+      - name: Attach runner to compose network
+        run: |
+          NET=$(docker network ls --format '{{.Name}}' | grep -E '(^|_)loremind(_|$)' | grep -i default | head -1)
+          if [ -z "$NET" ]; then
+            echo "Compose network not found" >&2
+            docker network ls
+            exit 1
+          fi
+          echo "Connecting $(hostname) to network $NET"
+          docker network connect "$NET" "$(hostname)"
+
+      - name: Wait for web to be ready
+        run: |
+          timeout 180 bash -c 'until curl -sf http://web/ > /dev/null; do echo "waiting..."; sleep 3; done'
+
+      - name: Install web deps
+        working-directory: web
+        run: npm ci
+
+      - name: Work around runner clock skew for apt
+        run: |
+          sudo tee /etc/apt/apt.conf.d/99no-check-valid-until >/dev/null <<'EOF'
+          Acquire::Check-Valid-Until "false";
+          Acquire::Check-Date "false";
+          EOF
+
+      - name: Install Playwright browsers
+        working-directory: web
+        run: npx playwright install --with-deps chromium
+
+      - name: Run Playwright tests
+        working-directory: web
+        env:
+          E2E_BASE_URL: http://web
+          CI: 'true'
+        run: npm run e2e
+
+      - name: Dump container logs on failure
+        if: failure()
+        run: docker compose -f docker-compose.yml -f docker-compose.e2e.yml logs --no-color
+
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: web/playwright-report/
+          retention-days: 14
+
+      - name: Stop stack
+        if: always()
+        run: docker compose -f docker-compose.yml -f docker-compose.e2e.yml down -v

.gitea/workflows/release.yml

@@ -6,8 +6,10 @@ on:
       - 'v*'
 
 env:
-  REGISTRY: git.igmlcreation.fr
-  REGISTRY_USER: ietm64
+  GITEA_REGISTRY: git.igmlcreation.fr
+  GITEA_REGISTRY_USER: ietm64
+  GHCR_REGISTRY: ghcr.io
+  GHCR_NAMESPACE: igmlcreation
 
 jobs:
   build:
@@ -26,19 +28,39 @@ jobs:
       - name: Login to Gitea Registry
         uses: docker/login-action@v3
         with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ env.REGISTRY_USER }}
+          registry: ${{ env.GITEA_REGISTRY }}
+          username: ${{ env.GITEA_REGISTRY_USER }}
           password: ${{ secrets.DOCKER_PAT }}
 
+      # Login to GHCR (GitHub Container Registry) pour distribuer les images
+      # publiquement aux utilisateurs finaux. Reputation domaine plus elevee
+      # que git.igmlcreation.fr (mieux pour les antivirus / SmartScreen).
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.GHCR_REGISTRY }}
+          username: ${{ env.GHCR_NAMESPACE }}
+          password: ${{ secrets.GHCR_TOKEN }}
+
       - name: Extract version
         id: meta
         run: echo "version=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
 
+      # Push vers les deux registries en un seul build (build-push-action
+      # accepte une liste de tags ; aucun build supplementaire necessaire).
+      # Naming :
+      #   - Gitea : conserve l'ancien pattern ietm64/<component> pour ne pas
+      #             casser les installs existantes qui ont REGISTRY=git.igmlcreation.fr
+      #             dans leur .env.
+      #   - GHCR  : nouveau pattern igmlcreation/loremind-<component> qui evite
+      #             la collision avec d'autres projets de l'org.
       - name: Build & push ${{ matrix.component }}
         uses: docker/build-push-action@v5
         with:
           context: ./${{ matrix.component }}
           push: true
           tags: |
-            ${{ env.REGISTRY }}/${{ env.REGISTRY_USER }}/${{ matrix.component }}:latest
-            ${{ env.REGISTRY }}/${{ env.REGISTRY_USER }}/${{ matrix.component }}:${{ steps.meta.outputs.version }}
+            ${{ env.GITEA_REGISTRY }}/${{ env.GITEA_REGISTRY_USER }}/${{ matrix.component }}:latest
+            ${{ env.GITEA_REGISTRY }}/${{ env.GITEA_REGISTRY_USER }}/${{ matrix.component }}:${{ steps.meta.outputs.version }}
+            ${{ env.GHCR_REGISTRY }}/${{ env.GHCR_NAMESPACE }}/loremind-${{ matrix.component }}:latest
+            ${{ env.GHCR_REGISTRY }}/${{ env.GHCR_NAMESPACE }}/loremind-${{ matrix.component }}:${{ steps.meta.outputs.version }}

.gitignore

@@ -53,6 +53,12 @@ yarn-error.log*
 .pnpm-debug.log*
 coverage/
 
+# Playwright (E2E)
+web/test-results/
+web/playwright-report/
+web/blob-report/
+web/playwright/.cache/
+
 # ============================================================================
 # IDE / Editeurs
 # ============================================================================
@@ -85,6 +91,7 @@ Thumbs.db
 # Documentation hors-code (conservee hors du repo)
 # ============================================================================
 docs/
+loremind-docs/
 
 # ============================================================================
 # Docker Compose override (dev uniquement, non-distribue aux end users)

INSTALL.md

@@ -1,311 +0,0 @@
-# Installation de LoreMindMJ
-
-Ce document decrit la procedure d'installation de LoreMindMJ. Temps estime :
-5 a 10 minutes selon la qualite de la connexion reseau.
-
-## 1. Prerequis
-
-- **Docker Desktop** ([Windows](https://www.docker.com/products/docker-desktop/) /
-  [Mac](https://www.docker.com/products/docker-desktop/)) ou
-  **Docker Engine + Compose v2** (Linux). Verification :
-  ```
-  docker --version
-  docker compose version
-  ```
-  Compose v2 est requis : la commande est `docker compose`, non `docker-compose`.
-
-- **Un fournisseur LLM**, au choix :
-  - **[Ollama](https://ollama.com/)** installe sur la machine hote (gratuit,
-    local, necessite environ 6 Go de RAM libre pour les modeles recommandes).
-  - **Une cle API [1min.ai](https://1min.ai)** (hebergement cloud, facturation
-    a l'usage, aucune installation supplementaire requise).
-
-- Environ **2 Go d'espace disque** pour les images Docker, auxquels s'ajoute
-  la taille des modeles Ollama si l'option locale est retenue.
-
-## 2. Recuperation des fichiers
-
-Telecharger les deux fichiers suivants depuis la
-[derniere release](https://git.igmlcreation.fr/ietm64/LoreMindMJ/releases) et
-les placer dans un dossier dedie (par exemple `~/loremind/` ou
-`C:\Programs\loremind\`) :
-
-- `docker-compose.yml`
-- `.env.example`
-
-Le code source n'est pas necessaire : les images sont pre-construites et
-publiees sur le registry Gitea `git.igmlcreation.fr` (non Docker Hub). Le
-premier `docker compose pull` les telechargera automatiquement.
-
-## 3. Configuration du fichier `.env`
-
-Renommer `.env.example` en `.env` et l'ouvrir dans un editeur de texte. **Trois
-variables sont obligatoires** ; sans elles, `docker compose up` refusera de
-demarrer. Ce comportement est volontaire afin d'eviter tout deploiement
-non-securise par defaut.
-
-### `POSTGRES_PASSWORD`
-
-Mot de passe de la base de donnees PostgreSQL. Choisir une valeur robuste.
-Seuls les conteneurs utilisent cette valeur : il n'est pas necessaire de la
-memoriser au-dela du fichier `.env`.
-
-### `ADMIN_PASSWORD`
-
-Protege l'ecran **Parametres** de l'application via HTTP Basic. Cette valeur
-sera demandee par le navigateur lors de toute modification de la configuration
-(changement de modele LLM, saisie de cle API, etc.). Le nom d'utilisateur par
-defaut est `admin`, modifiable via la variable `ADMIN_USERNAME`.
-
-### `BRAIN_INTERNAL_SECRET`
-
-Secret partage entre le service Java (`core`) et le service Python (`brain`).
-Empeche toute requete externe d'atteindre directement le service Brain.
-Generer une valeur aleatoire de 64 caracteres hexadecimaux :
-
-```
-openssl rand -hex 32
-```
-
-Sous Windows sans `openssl`, utiliser PowerShell :
-
-```powershell
--join ((48..57) + (97..102) | Get-Random -Count 64 | % {[char]$_})
-```
-
-### Variables optionnelles
-
-- `WEB_PORT` (defaut `8081`) : port d'ecoute de l'interface web.
-- `ADMIN_USERNAME` (defaut `admin`) : identifiant de la popup Parametres.
-- `LLM_PROVIDER` (defaut `ollama`) : choix du fournisseur LLM (voir
-  section 5).
-
-Les autres variables (`MINIO_USER`/`MINIO_PASSWORD`, `POSTGRES_DB`,
-`POSTGRES_USER`) disposent de valeurs par defaut adaptees a un deploiement
-personnel et peuvent etre conservees en l'etat.
-
-## 4. Lancement de la stack
-
-Depuis le dossier contenant `docker-compose.yml` et `.env` :
-
-```
-docker compose up -d
-```
-
-Le premier demarrage telecharge les images (environ 1 a 2 Go au total) et
-initialise la base. Compter 2 a 5 minutes selon la qualite de la connexion.
-La progression peut etre suivie via :
-
-```
-docker compose logs -f
-```
-
-(`Ctrl+C` pour quitter l'affichage ; les services continuent de fonctionner
-en arriere-plan.)
-
-Une fois les services en etat `healthy`, ouvrir **http://localhost:8081**
-dans un navigateur.
-
-### Verification du fonctionnement
-
-```
-docker compose ps
-```
-
-Cinq conteneurs doivent apparaitre en etat `Up` ou `healthy` :
-`loremind-postgres`, `loremind-minio`, `loremind-core`, `loremind-brain`,
-`loremind-web`. Le conteneur `loremind-minio-init` s'arrete automatiquement
-apres creation du bucket d'images : ce comportement est normal.
-
-## 5. Configuration du fournisseur LLM
-
-### Ollama (local, gratuit)
-
-Installer Ollama sur la machine hote (pas dans Docker), puis telecharger un
-modele :
-
-```
-ollama pull gemma4:26b
-```
-
-Dans `.env` :
-
-```
-LLM_PROVIDER=ollama
-LLM_MODEL=gemma4:26b
-OLLAMA_BASE_URL=http://host.docker.internal:11434
-```
-
-L'adresse `host.docker.internal` permet au conteneur `brain` d'atteindre
-Ollama sur la machine hote. Cette resolution est native sous Docker Desktop
-(Mac / Windows). Sous Linux, le fichier `docker-compose.yml` declare un
-`extra_hosts` equivalent.
-
-### 1min.ai (cloud, paye)
-
-Dans `.env` :
-
-```
-LLM_PROVIDER=onemin
-ONEMIN_API_KEY=sk-...
-ONEMIN_MODEL=gpt-4o-mini
-```
-
-### Modification a chaud
-
-Le fournisseur, le modele et la cle API peuvent etre modifies a chaud depuis
-l'ecran **Parametres** de l'application. Les modifications sont persistees
-dans un volume Docker et survivent aux redemarrages. Les variables d'env du
-fichier `.env` sont uniquement utilisees comme valeurs initiales au premier
-demarrage.
-
-## 6. Mise a jour
-
-```
-docker compose pull
-docker compose up -d
-```
-
-Les donnees (base PostgreSQL, images MinIO, configuration Brain) sont
-stockees dans des volumes Docker et survivent aux mises a jour.
-
-## 7. Sauvegarde
-
-Les donnees sont reparties dans trois volumes Docker :
-
-- `loremindmj_postgres-data` — ensemble des donnees applicatives (lores,
-  campagnes, pages, templates, branches narratives, etc.).
-- `loremindmj_minio-data` — images uploadees.
-- `loremindmj_brain-data` — parametres IA (fournisseur courant, cle API
-  1min.ai).
-
-### Export SQL de la base
-
-```
-docker compose exec postgres pg_dump -U loremind loremind > backup.sql
-```
-
-### Sauvegarde complete des volumes
-
-Arreter la stack au prealable afin de garantir la coherence des donnees :
-
-```
-docker compose stop
-docker run --rm -v loremindmj_postgres-data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-data.tar.gz -C /data .
-docker run --rm -v loremindmj_minio-data:/data -v $(pwd):/backup alpine tar czf /backup/minio-data.tar.gz -C /data .
-docker compose start
-```
-
-Sous Windows PowerShell, remplacer `$(pwd)` par `${PWD}`.
-
-## 8. Resolution des problemes
-
-### Port 8081 deja utilise
-
-Modifier `WEB_PORT=8082` (ou toute autre valeur libre) dans `.env`, puis
-relancer :
-
-```
-docker compose up -d
-```
-
-### Erreur "set POSTGRES_PASSWORD in .env" (ou variable equivalente) au lancement
-
-Une des trois variables obligatoires de l'etape 3 est manquante. Verifier le
-contenu du fichier `.env`.
-
-### Popup "Ce site vous demande de vous connecter" sur l'ecran Parametres
-
-Comportement attendu : il s'agit de l'authentification HTTP Basic. Utiliser
-la valeur de `ADMIN_USERNAME` (par defaut `admin`) et celle de
-`ADMIN_PASSWORD`.
-
-### Erreurs `password authentication failed` en boucle dans les logs Postgres
-
-Si la variable `POSTGRES_PASSWORD` a ete modifiee apres un premier lancement,
-le volume Postgres conserve l'ancien mot de passe (initialise une seule fois).
-Deux options :
-
-- **Redemarrer avec un volume vierge** (entraine la perte des donnees) :
-  ```
-  docker compose down -v
-  docker compose up -d
-  ```
-- **Modifier le mot de passe en base** sans toucher au volume :
-  ```
-  docker compose exec postgres psql -U postgres
-  ```
-  Puis dans le prompt `psql` :
-  ```sql
-  ALTER USER loremind WITH PASSWORD 'valeur_exacte_du_env';
-  \q
-  ```
-  Redemarrer ensuite le Core : `docker compose restart core`.
-
-### Erreur "502 Bad Gateway" ou message d'erreur IA dans l'interface
-
-Le service Brain ne parvient pas a contacter le fournisseur LLM. Verifier :
-
-- **Ollama** : `ollama serve` est-il actif ? Le modele est-il telecharge
-  (`ollama list`) ? La valeur de `LLM_MODEL` correspond-elle exactement au
-  nom d'un modele liste ?
-- **1min.ai** : la cle API est-elle valide ? Le modele existe-t-il ?
-- Consulter les logs du Brain :
-  ```
-  docker compose logs brain
-  ```
-
-### Un service ne demarre pas ou reste en etat `unhealthy`
-
-Consulter les logs du service concerne :
-
-```
-docker compose logs <service>
-```
-
-Services disponibles : `postgres`, `minio`, `core`, `brain`, `web`.
-
-### Redemarrage d'un service apres modification du `.env`
-
-```
-docker compose up -d <service>
-```
-
-Redemarrage complet : `docker compose restart`.
-
-### Remise a zero complete (PERTE DES DONNEES)
-
-```
-docker compose down -v
-```
-
-L'option `-v` supprime les volumes. L'ensemble des lores, campagnes, images
-et parametres est perdu de maniere definitive.
-
-### "No such image" ou "pull access denied" au premier lancement
-
-Le registry Gitea peut necessiter une authentification selon la visibilite
-configuree pour les images. Contacter l'editeur du projet.
-
-## 9. Exposition reseau des services
-
-- **Interface web** : http://localhost:8081 (port configurable via
-  `WEB_PORT`).
-- **PostgreSQL** : accessible uniquement via le reseau Docker interne, non
-  expose vers l'hote.
-- **MinIO** : accessible uniquement via le reseau Docker interne. Les images
-  transitent par le reverse-proxy Java sur `/api/images/{id}/content`. Le
-  binding `127.0.0.1:9000/9001` defini dans `docker-compose.override.yml`
-  n'est actif qu'en developpement.
-- **Brain Python** : accessible uniquement via le reseau Docker interne.
-  Toute requete doit porter l'en-tete `X-Internal-Secret`, injectee
-  automatiquement par le Core Java et jamais exposee au navigateur.
-
-## 10. Desinstallation
-
-```
-docker compose down -v
-docker image rm git.igmlcreation.fr/ietm64/core git.igmlcreation.fr/ietm64/brain git.igmlcreation.fr/ietm64/web
-```
-
-Supprimer ensuite le dossier contenant `docker-compose.yml` et `.env`.

README.md

@@ -1,69 +1,31 @@
 # LoreMind
 
-Application web d'aide aux Maîtres de Jeu (JDR) pour centraliser la gestion de l'univers (Lore) et le suivi des campagnes, avec un moteur IA intégré pour générer du contenu structuré.
+![Tableau de bord](https://raw.githubusercontent.com/IGMLcreation/loremind-docs/main/static/img/screenshots/dashboard.png)
+
+Loremind est une application web angular auto-hébergable afin de venir en aide aux Maîtres de jeu qui souhaitent centraliser leur univers et leurs campagnes.
+Cette dernière intègre un moteur IA qui va ingérer le contenu du lore et de la campagne afin de pouvoir répondre à des questions précises sur l'univers ou la campagne, mais également proposer des idées de création dans le contexte de la campagne et du lore.
+Pour le moment seul Ollama est supporté pour la partie locale, il y-a également une intégration pour 1min.ai. Plus tard, d'autres moteurs seront supportés.
+
+## Documentation
+
+La documentation complète est accessible sur le site [loremind-docs](https://loremind-docs.igmlcreation.fr/)
+
+Pour l'installation, consultez le guide dans cette dernière .
 
 ## Fonctionnalités
 
 - Gestion centralisée du Lore : Lieux, Factions, PNJ, et tous les éléments de votre univers
 - Suivi de campagnes : Sessions, actions des joueurs, chronologie
 - Moteur IA intégré : Génération automatique de contenu (PNJ, Villes, Quêtes) à partir de templates
-- Export vers FoundryVTT : Transfert structuré des données vers votre VTT préféré (en développement)
 
-## Captures d'écran
+## Démo
 
-### Page d'accueil
-![Accueil](docs/maquettes/général/Accueil.png)
+Une démo est disponible sur le site [loremind-demo](https://loremind-demo.igmlcreation.fr/)
 
-### Recherche
-![Recherche](docs/maquettes/général/Ecran de recherche.png)
+!! Attention, la démo est uniquement accessible à 10 personnes à la fois (instances personnalisées). Cette limite est mise en place pour éviter l'overhead sur les ressources serveur.
 
-## Stack Technologique
-
-LoreMind utilise une architecture distribuée pour séparer les responsabilités :
-
-- **Frontend** : Angular (Interface utilisateur, affichage du lore, formulaires de templates)
-- **Backend Core** : Java (Spring Boot) - Orchestration, persistance, export VTT
-- **Backend IA** : Python - Traitement des LLM et génération de contenu
-- **Base de données** : PostgreSQL avec JSONB pour les templates flexibles
-
-## Architecture
-
-### Backend Java (Domain-Driven Design & Hexagonal)
-
-Le Backend Core respecte strictement :
-- **Domain-Driven Design (DDD)** : Séparation en Bounded Contexts autonomes
-- **Architecture Hexagonale (Ports et Adaptateurs)** : Domaine pur sans dépendances techniques
-
-#### Bounded Contexts
-- **LoreContext** : Gestion de l'encyclopédie de l'univers
-- **CampaignContext** : Suivi des sessions et chronologie
-- **GenerationContext** : Gestion des requêtes IA et templates
-
-#### Couches
-- **Domaine (Core)** : Entités métier pures et interfaces (Ports)
-- **Application** : Orchestration des flux (Use Cases)
-- **Infrastructure** : Implémentation technique (Adapters)
-
-## Installation
-
-Pour installer LoreMind chez vous (Docker requis), suivez le guide **[INSTALL.md](INSTALL.md)** — 3 étapes, 5 minutes chrono :
-
-1. Télécharger `docker-compose.yml` + `.env.example` depuis la [dernière release](https://git.igmlcreation.fr/ietm64/LoreMindMJ/releases)
-2. Renommer `.env.example` → `.env` et changer `POSTGRES_PASSWORD`
-3. `docker compose up -d` → ouvrir http://localhost:8081
-
-Mise à jour : `docker compose pull && docker compose up -d`.
-
-## Développement (contributeurs)
-
-Pour builder les images localement depuis les sources :
-
-```bash
-git clone https://git.igmlcreation.fr/ietm64/LoreMindMJ.git
-cd LoreMindMJ
-# Créer un docker-compose.override.yml local (voir docs de contrib)
-docker compose up -d --build
-```
+Cette dernière est utilisable 20 minutes maximum par session avant d'être réinitialiser.
+Vous comprendrez également qu'elle ne contient pas de démo pour la partie IA, pour laquelle il faut configurer un serveur Ollama (et qui ferait donc exploser le serveur) ou utiliser 1min.ai.
 
 ## License
 

brain/app/application/chat.py

@@ -21,6 +21,7 @@ from app.domain.models import (
     ChatMessage,
     ChapterSummary,
     CharacterSummary,
+    NpcSummary,
     GameSystemContext,
     LoreStructuralContext,
     NarrativeEntityContext,
@@ -198,10 +199,12 @@ class ChatUseCase:
             else "\n(Cette campagne n'est associée à aucun univers — tu peux proposer des éléments d'ambiance libres.)"
         )
         characters_block = ChatUseCase._format_characters(ctx.characters)
+        npcs_block = ChatUseCase._format_npcs(ctx.npcs)
         return (
             "--- CAMPAGNE COURANTE ---\n"
             f"Nom : {ctx.campaign_name}{desc}{lore_note}\n"
-            f"{characters_block}\n"
+            f"{characters_block}"
+            f"{npcs_block}\n"
             "Structure narrative (les flèches → indiquent des transitions de scène "
             "déclenchées par un choix des joueurs) :\n"
             f"{arcs_block}"
@@ -231,6 +234,33 @@ class ChatUseCase:
         )
         return "\n".join(lines) + "\n"
 
+    @staticmethod
+    def _format_npcs(npcs: list[NpcSummary]) -> str:
+        """Bloc PNJ — symétrique aux PJ avec sa propre instruction anti-halluci.
+
+        Distinction importante : pour les PNJ, l'IA est ENCOURAGÉE à proposer de
+        nouveaux PNJ (création créative = OK). En revanche, elle ne doit pas
+        référencer comme existant un PNJ qui n'est pas dans la liste ci-dessous.
+        """
+        if not npcs:
+            return (
+                "\nPersonnages non-joueurs (PNJ) : aucun défini pour l'instant. "
+                "Tu peux librement proposer de nouveaux PNJ au MJ, mais ne "
+                "fais pas comme s'ils existaient déjà dans la campagne.\n"
+            )
+        lines = ["\nPersonnages non-joueurs (PNJ) connus :"]
+        for n in npcs:
+            if n.snippet:
+                lines.append(f"- **{n.name}** — {n.snippet}")
+            else:
+                lines.append(f"- **{n.name}** (fiche vide)")
+        lines.append(
+            "Pour une fiche complète d'un PNJ existant (apparence, motivations), "
+            "n'invente rien : demande au MJ d'ouvrir l'éditeur du PNJ. Tu peux "
+            "en revanche proposer librement de NOUVEAUX PNJ."
+        )
+        return "\n".join(lines) + "\n"
+
     @staticmethod
     def _format_arcs(arcs: list[ArcSummary]) -> str:
         if not arcs:
@@ -319,7 +349,8 @@ class ChatUseCase:
             "arc": "ARC",
             "chapter": "CHAPITRE",
             "scene": "SCÈNE",
-            "character": "FICHE DE PERSONNAGE",
+            "character": "FICHE DE PERSONNAGE (PJ)",
+            "npc": "FICHE DE PNJ",
         }.get(ne.entity_type.lower(), ne.entity_type.upper())
         if ne.fields:
             fields_block = "\n".join(

brain/app/domain/models.py

@@ -170,6 +170,7 @@ class CampaignStructuralContext:
     campaign_description: str | None
     arcs: list[ArcSummary]
     characters: list["CharacterSummary"] = field(default_factory=list)
+    npcs: list["NpcSummary"] = field(default_factory=list)
 
 
 @dataclass(frozen=True)
@@ -185,6 +186,19 @@ class CharacterSummary:
     snippet: str
 
 
+@dataclass(frozen=True)
+class NpcSummary:
+    """Résumé d'un PNJ : symétrique à CharacterSummary.
+
+    Permet à l'IA de connaître les PNJ d'une campagne (nom + snippet) sans
+    injecter leurs fiches complètes. Évolution prévue : entity_type="npc"
+    pour focus sur la fiche complète.
+    """
+
+    name: str
+    snippet: str
+
+
 @dataclass(frozen=True)
 class NarrativeEntityContext:
     """Contexte d'une entité narrative précise en cours d'édition.

brain/app/infrastructure/ollama_adapter.py

@@ -61,7 +61,16 @@ class OllamaLLMProvider:
         async with httpx.AsyncClient(timeout=self._timeout) as client:
             try:
                 response = await client.post(url, json=payload)
-                response.raise_for_status()
+                if response.status_code >= 400:
+                    body = response.text
+                    try:
+                        err_obj = json.loads(body)
+                        err_msg = err_obj.get("error") or body
+                    except json.JSONDecodeError:
+                        err_msg = body
+                    raise LLMProviderError(
+                        f"Ollama HTTP {response.status_code} : {err_msg.strip()[:500]}"
+                    )
             except httpx.HTTPError as exc:
                 raise LLMProviderError(
                     f"Erreur lors de l'appel à Ollama : {exc}"
@@ -105,7 +114,20 @@ class OllamaLLMProvider:
         async with httpx.AsyncClient(timeout=self._timeout) as client:
             try:
                 async with client.stream("POST", url, json=payload) as response:
-                    response.raise_for_status()
+                    if response.status_code >= 400:
+                        # On lit le body d'erreur pour le remonter a l'utilisateur,
+                        # sinon on ne voit que "500 Internal Server Error" sans
+                        # savoir POURQUOI Ollama refuse (modele introuvable, OOM,
+                        # num_ctx trop grand pour la VRAM, etc.).
+                        body = (await response.aread()).decode("utf-8", errors="replace")
+                        try:
+                            err_obj = json.loads(body)
+                            err_msg = err_obj.get("error") or body
+                        except json.JSONDecodeError:
+                            err_msg = body
+                        raise LLMProviderError(
+                            f"Ollama HTTP {response.status_code} : {err_msg.strip()[:500]}"
+                        )
                     async for line in response.aiter_lines():
                         if not line.strip():
                             continue

brain/app/main.py

@@ -23,6 +23,7 @@ from app.domain.models import (
     CampaignStructuralContext,
     ChapterSummary,
     CharacterSummary,
+    NpcSummary,
     ChatMessage,
     GameSystemContext,
     LoreStructuralContext,
@@ -40,7 +41,7 @@ from app.infrastructure.onemin_adapter import OneMinAiLLMProvider
 app = FastAPI(
     title="LoreMind Brain",
     description="Backend IA pour la génération de contenu narratif.",
-    version="0.6.1",
+    version="0.6.6",
 )
 
 
@@ -205,6 +206,13 @@ class CharacterSummaryDTO(BaseModel):
     snippet: str = ""
 
 
+class NpcSummaryDTO(BaseModel):
+    """Résumé d'un PNJ : symétrique à CharacterSummaryDTO."""
+
+    name: str
+    snippet: str = ""
+
+
 class CampaignContextDTO(BaseModel):
     """Carte narrative enrichie : arcs → chapitres → scènes avec synopsis."""
 
@@ -212,12 +220,13 @@ class CampaignContextDTO(BaseModel):
     campaign_description: str | None = None
     arcs: list[ArcSummaryDTO] = Field(default_factory=list)
     characters: list[CharacterSummaryDTO] = Field(default_factory=list)
+    npcs: list[NpcSummaryDTO] = Field(default_factory=list)
 
 
 class NarrativeEntityDTO(BaseModel):
     """Entité narrative (arc/chapter/scene/character) en cours d'édition — focus optionnel."""
 
-    entity_type: str = Field(pattern="^(arc|chapter|scene|character)$")
+    entity_type: str = Field(pattern="^(arc|chapter|scene|character|npc)$")
     title: str
     fields: dict[str, str] = Field(default_factory=dict)
 
@@ -553,11 +562,16 @@ def _to_campaign_context(dto: CampaignContextDTO | None) -> CampaignStructuralCo
         CharacterSummary(name=c.name, snippet=c.snippet)
         for c in dto.characters
     ]
+    npcs = [
+        NpcSummary(name=n.name, snippet=n.snippet)
+        for n in dto.npcs
+    ]
     return CampaignStructuralContext(
         campaign_name=dto.campaign_name,
         campaign_description=dto.campaign_description,
         arcs=arcs,
         characters=characters,
+        npcs=npcs,
     )
 
 
@@ -689,6 +703,76 @@ async def get_ollama_model_info(
     return OllamaModelInfoDTO(context_length=0)
 
 
+@app.post("/models/ollama/pull")
+async def pull_ollama_model(
+    body: dict[str, str],
+    settings: Annotated[Settings, Depends(get_settings)],
+) -> StreamingResponse:
+    """Telecharge un modele depuis Ollama et streame la progression.
+
+    Proxifie l'endpoint `/api/pull` d'Ollama qui renvoie du JSON ligne par
+    ligne (NDJSON) avec le statut de chaque etape : manifest, layers,
+    digest, success. On reemet ce flux tel quel au client (le front
+    parsera les lignes et affichera une barre de progression).
+
+    Le timeout est intentionnellement tres long (60 min) car certains
+    modeles font 30+ Go.
+    """
+    name = (body.get("name") or "").strip()
+    if not name:
+        raise HTTPException(status_code=400, detail="name requis")
+    url = f"{settings.ollama_base_url}/api/pull"
+
+    async def stream() -> AsyncIterator[bytes]:
+        # On utilise un timeout long pour la lecture (60 min) mais court pour
+        # la connexion (10s) — si Ollama n'est pas joignable, on echoue vite.
+        timeout = httpx.Timeout(connect=10, read=3600, write=10, pool=10)
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                async with client.stream("POST", url, json={"model": name, "stream": True}) as r:
+                    if r.status_code != 200:
+                        # Ollama renvoie un message JSON d'erreur. On le passe
+                        # tel quel au client en preservant le code HTTP.
+                        body_text = await r.aread()
+                        yield body_text
+                        return
+                    async for chunk in r.aiter_bytes():
+                        yield chunk
+        except httpx.HTTPError as e:
+            # Erreur reseau : on emet une ligne JSON d'erreur compatible
+            # avec le format NDJSON d'Ollama.
+            err = json.dumps({"error": f"Connexion a Ollama impossible : {e}"}) + "\n"
+            yield err.encode("utf-8")
+
+    # application/x-ndjson : un objet JSON par ligne, pas de wrapping SSE.
+    # C'est le format natif d'Ollama, le front le parsera ligne par ligne.
+    return StreamingResponse(stream(), media_type="application/x-ndjson")
+
+
+@app.delete("/models/ollama/{name:path}")
+async def delete_ollama_model(
+    name: str,
+    settings: Annotated[Settings, Depends(get_settings)],
+) -> dict[str, str]:
+    """Supprime un modele du serveur Ollama.
+
+    Le `:path` dans le pattern autorise les `:` du nom (ex: `gemma4:e4b`)
+    sans avoir besoin de URL-encoder cote client.
+    """
+    if not name.strip():
+        raise HTTPException(status_code=400, detail="name requis")
+    url = f"{settings.ollama_base_url}/api/delete"
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            response = await client.request("DELETE", url, json={"model": name})
+            if response.status_code == 404:
+                raise HTTPException(status_code=404, detail=f"Modele '{name}' introuvable")
+            response.raise_for_status()
+    except httpx.HTTPError as e:
+        raise HTTPException(status_code=502, detail=f"Ollama injoignable : {e}")
+    return {"status": "deleted", "name": name}
+
+
 @app.get("/models/onemin")
 def list_onemin_models() -> dict[str, list[dict[str, object]]]:
     """Catalogue statique des modeles 1min.ai, groupes par fournisseur.

core/pom.xml

@@ -14,7 +14,7 @@
 
     <groupId>com.loremind</groupId>
     <artifactId>loremind-core</artifactId>
-    <version>0.6.1</version>
+    <version>0.7.1</version>
     <name>LoreMind Core</name>
     <description>Backend Core - Architecture Hexagonale</description>
 

core/src/main/java/com/loremind/application/campaigncontext/ArcService.java

@@ -36,11 +36,16 @@ public class ArcService {
     public record DeletionImpact(int chapters, int scenes) {}
 
     public Arc createArc(String name, String description, String campaignId, int order) {
+        return createArc(name, description, campaignId, order, null);
+    }
+
+    public Arc createArc(String name, String description, String campaignId, int order, String icon) {
         Arc arc = Arc.builder()
                 .name(name)
                 .description(description)
                 .campaignId(campaignId)
                 .order(order)
+                .icon(icon)
                 .build();
         return arcRepository.save(arc);
     }

core/src/main/java/com/loremind/application/campaigncontext/ChapterService.java

@@ -30,11 +30,16 @@ public class ChapterService {
     public record DeletionImpact(int scenes) {}
 
     public Chapter createChapter(String name, String description, String arcId, int order) {
+        return createChapter(name, description, arcId, order, null);
+    }
+
+    public Chapter createChapter(String name, String description, String arcId, int order, String icon) {
         Chapter chapter = Chapter.builder()
                 .name(name)
                 .description(description)
                 .arcId(arcId)
                 .order(order)
+                .icon(icon)
                 .build();
         return chapterRepository.save(chapter);
     }

core/src/main/java/com/loremind/application/campaigncontext/NpcService.java

@@ -0,0 +1,71 @@
+package com.loremind.application.campaigncontext;
+
+import com.loremind.domain.campaigncontext.Npc;
+import com.loremind.domain.campaigncontext.ports.NpcRepository;
+import org.springframework.stereotype.Service;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Service d'application pour les fiches de PNJ (campagne).
+ */
+@Service
+public class NpcService {
+
+    private final NpcRepository npcRepository;
+
+    public NpcService(NpcRepository npcRepository) {
+        this.npcRepository = npcRepository;
+    }
+
+    /**
+     * Parameter Object pour la création / mise à jour d'un Npc.
+     * `order` est fourni par le controller ; si absent, le service le calcule.
+     */
+    public record NpcData(String name, String markdownContent, String campaignId, Integer order) {}
+
+    public Npc createNpc(NpcData data) {
+        int order = data.order() != null
+                ? data.order()
+                : nextOrderFor(data.campaignId());
+        Npc npc = Npc.builder()
+                .name(data.name())
+                .markdownContent(data.markdownContent())
+                .campaignId(data.campaignId())
+                .order(order)
+                .build();
+        return npcRepository.save(npc);
+    }
+
+    public Optional<Npc> getNpcById(String id) {
+        return npcRepository.findById(id);
+    }
+
+    public List<Npc> getNpcsByCampaignId(String campaignId) {
+        return npcRepository.findByCampaignId(campaignId);
+    }
+
+    public Npc updateNpc(String id, NpcData data) {
+        Npc existing = npcRepository.findById(id)
+                .orElseThrow(() -> new IllegalArgumentException("Npc non trouvé avec l'ID: " + id));
+        existing.setName(data.name());
+        existing.setMarkdownContent(data.markdownContent());
+        if (data.order() != null) {
+            existing.setOrder(data.order());
+        }
+        return npcRepository.save(existing);
+    }
+
+    public void deleteNpc(String id) {
+        npcRepository.deleteById(id);
+    }
+
+    /** Renvoie la prochaine position libre — append en fin de liste. */
+    private int nextOrderFor(String campaignId) {
+        return npcRepository.findByCampaignId(campaignId).stream()
+                .mapToInt(Npc::getOrder)
+                .max()
+                .orElse(-1) + 1;
+    }
+}

core/src/main/java/com/loremind/application/campaigncontext/SceneService.java

@@ -26,11 +26,16 @@ public class SceneService {
     }
 
     public Scene createScene(String name, String description, String chapterId, int order) {
+        return createScene(name, description, chapterId, order, null);
+    }
+
+    public Scene createScene(String name, String description, String chapterId, int order, String icon) {
         Scene scene = Scene.builder()
                 .name(name)
                 .description(description)
                 .chapterId(chapterId)
                 .order(order)
+                .icon(icon)
                 .build();
         return sceneRepository.save(scene);
     }
@@ -93,7 +98,7 @@ public class SceneService {
                 .collect(Collectors.toSet());
 
         for (SceneBranch b : branches) {
-            String target = b.getTargetSceneId();
+            String target = b.targetSceneId();
             if (target == null || target.isBlank()) {
                 throw new IllegalArgumentException("Une branche doit avoir une scène de destination");
             }

core/src/main/java/com/loremind/application/gamesystemcontext/GameSystemContextBuilder.java

@@ -45,11 +45,7 @@ public class GameSystemContextBuilder {
     private GameSystemContext build(GameSystem gs, GenerationIntent intent) {
         Map<String, String> allSections = parseH2Sections(gs.getRulesMarkdown());
         Map<String, String> filtered = filterByIntent(allSections, intent);
-        return GameSystemContext.builder()
-                .systemName(gs.getName())
-                .systemDescription(gs.getDescription())
-                .sections(filtered)
-                .build();
+        return new GameSystemContext(gs.getName(), gs.getDescription(), filtered);
     }
 
     /**

core/src/main/java/com/loremind/application/generationcontext/CampaignStructuralContextBuilder.java

@@ -4,17 +4,20 @@ import com.loremind.domain.campaigncontext.Arc;
 import com.loremind.domain.campaigncontext.Campaign;
 import com.loremind.domain.campaigncontext.Chapter;
 import com.loremind.domain.campaigncontext.Character;
+import com.loremind.domain.campaigncontext.Npc;
 import com.loremind.domain.campaigncontext.Scene;
 import com.loremind.domain.campaigncontext.ports.ArcRepository;
 import com.loremind.domain.campaigncontext.ports.CampaignRepository;
 import com.loremind.domain.campaigncontext.ports.ChapterRepository;
 import com.loremind.domain.campaigncontext.ports.CharacterRepository;
+import com.loremind.domain.campaigncontext.ports.NpcRepository;
 import com.loremind.domain.campaigncontext.ports.SceneRepository;
 import com.loremind.domain.generationcontext.CampaignStructuralContext;
 import com.loremind.domain.generationcontext.CampaignStructuralContext.ArcSummary;
 import com.loremind.domain.generationcontext.CampaignStructuralContext.BranchHint;
 import com.loremind.domain.generationcontext.CampaignStructuralContext.ChapterSummary;
 import com.loremind.domain.generationcontext.CampaignStructuralContext.CharacterSummary;
+import com.loremind.domain.generationcontext.CampaignStructuralContext.NpcSummary;
 import com.loremind.domain.generationcontext.CampaignStructuralContext.SceneSummary;
 import org.springframework.stereotype.Component;
 
@@ -42,21 +45,24 @@ public class CampaignStructuralContextBuilder {
     private final ChapterRepository chapterRepository;
     private final SceneRepository sceneRepository;
     private final CharacterRepository characterRepository;
+    private final NpcRepository npcRepository;
 
     public CampaignStructuralContextBuilder(
             CampaignRepository campaignRepository,
             ArcRepository arcRepository,
             ChapterRepository chapterRepository,
             SceneRepository sceneRepository,
-            CharacterRepository characterRepository) {
+            CharacterRepository characterRepository,
+            NpcRepository npcRepository) {
         this.campaignRepository = campaignRepository;
         this.arcRepository = arcRepository;
         this.chapterRepository = chapterRepository;
         this.sceneRepository = sceneRepository;
         this.characterRepository = characterRepository;
+        this.npcRepository = npcRepository;
     }
 
-    /** Longueur max du snippet de PJ injecté dans le contexte (coût tokens maîtrisé). */
+    /** Longueur max du snippet de PJ/PNJ injecté dans le contexte (coût tokens maîtrisé). */
     private static final int CHARACTER_SNIPPET_MAX_LEN = 160;
 
     /**
@@ -79,12 +85,17 @@ public class CampaignStructuralContextBuilder {
                 .map(this::toCharacterSummary)
                 .collect(Collectors.toList());
 
-        return CampaignStructuralContext.builder()
-                .campaignName(campaign.getName())
-                .campaignDescription(campaign.getDescription())
-                .arcs(arcs)
-                .characters(characters)
-                .build();
+        List<NpcSummary> npcs = npcRepository.findByCampaignId(campaignId).stream()
+                .sorted(Comparator.comparingInt(Npc::getOrder))
+                .map(this::toNpcSummary)
+                .collect(Collectors.toList());
+
+        return new CampaignStructuralContext(
+                campaign.getName(),
+                campaign.getDescription(),
+                arcs,
+                characters,
+                npcs);
     }
 
     /**
@@ -93,10 +104,12 @@ public class CampaignStructuralContextBuilder {
      * sans injecter toute sa fiche.
      */
     private CharacterSummary toCharacterSummary(Character c) {
-        return CharacterSummary.builder()
-                .name(c.getName())
-                .snippet(extractSnippet(c.getMarkdownContent()))
-                .build();
+        return new CharacterSummary(c.getName(), extractSnippet(c.getMarkdownContent()));
+    }
+
+    /** Symétrique à {@link #toCharacterSummary} pour les PNJ. */
+    private NpcSummary toNpcSummary(Npc n) {
+        return new NpcSummary(n.getName(), extractSnippet(n.getMarkdownContent()));
     }
 
     private static String extractSnippet(String markdown) {
@@ -115,12 +128,11 @@ public class CampaignStructuralContextBuilder {
                 .sorted(Comparator.comparingInt(Chapter::getOrder))
                 .map(this::toChapterSummary)
                 .collect(Collectors.toList());
-        return ArcSummary.builder()
-                .name(arc.getName())
-                .description(arc.getDescription())
-                .illustrationCount(countImages(arc.getIllustrationImageIds()))
-                .chapters(chapters)
-                .build();
+        return new ArcSummary(
+                arc.getName(),
+                arc.getDescription(),
+                countImages(arc.getIllustrationImageIds()),
+                chapters);
     }
 
     private ChapterSummary toChapterSummary(Chapter chapter) {
@@ -137,32 +149,28 @@ public class CampaignStructuralContextBuilder {
                 .map(s -> toSceneSummary(s, nameById))
                 .collect(Collectors.toList());
 
-        return ChapterSummary.builder()
-                .name(chapter.getName())
-                .description(chapter.getDescription())
-                .illustrationCount(countImages(chapter.getIllustrationImageIds()))
-                .scenes(summaries)
-                .build();
+        return new ChapterSummary(
+                chapter.getName(),
+                chapter.getDescription(),
+                countImages(chapter.getIllustrationImageIds()),
+                summaries);
     }
 
     private SceneSummary toSceneSummary(Scene scene, Map<String, String> nameById) {
         List<BranchHint> hints = scene.getBranches() == null
                 ? List.of()
                 : scene.getBranches().stream()
-                    .map(b -> BranchHint.builder()
-                            .label(b.getLabel())
-                            .targetSceneName(nameById.getOrDefault(
-                                    b.getTargetSceneId(), "(scène inconnue)"))
-                            .condition(b.getCondition())
-                            .build())
+                    .map(b -> new BranchHint(
+                            b.label(),
+                            nameById.getOrDefault(b.targetSceneId(), "(scène inconnue)"),
+                            b.condition()))
                     .collect(Collectors.toList());
 
-        return SceneSummary.builder()
-                .name(scene.getName())
-                .description(scene.getDescription())
-                .illustrationCount(countImages(scene.getIllustrationImageIds()))
-                .branches(hints)
-                .build();
+        return new SceneSummary(
+                scene.getName(),
+                scene.getDescription(),
+                countImages(scene.getIllustrationImageIds()),
+                hints);
     }
 
     /** Helper defensif : compte les illustrations attachees (null-safe). */

core/src/main/java/com/loremind/application/generationcontext/GeneratePageValuesUseCase.java

@@ -67,16 +67,15 @@ public class GeneratePageValuesUseCase {
 
         requireNonEmptyFields(template);
 
-        GenerationContext context = GenerationContext.builder()
-                .loreName(lore.getName())
-                .loreDescription(lore.getDescription())
-                .folderName(folder.getName())
-                .templateName(template.getName())
-                // Seuls les champs TEXT sont envoyes a l'IA : les champs IMAGE
-                // necessitent un workflow different (pas de generation LLM texte).
-                .templateFields(template.textFieldNames())
-                .pageTitle(page.getTitle())
-                .build();
+        // Seuls les champs TEXT sont envoyes a l'IA : les champs IMAGE
+        // necessitent un workflow different (pas de generation LLM texte).
+        GenerationContext context = new GenerationContext(
+                lore.getName(),
+                lore.getDescription(),
+                folder.getName(),
+                template.getName(),
+                template.textFieldNames(),
+                page.getTitle());
 
         GenerationResult result = aiProvider.generatePage(context);
         return result.values();

core/src/main/java/com/loremind/application/generationcontext/LoreStructuralContextBuilder.java

@@ -82,12 +82,11 @@ public class LoreStructuralContextBuilder {
         Map<String, String> pageTitleById = pages.stream()
                 .collect(Collectors.toMap(Page::getId, Page::getTitle, (a, b) -> a));
 
-        return LoreStructuralContext.builder()
-                .loreName(lore.getName())
-                .loreDescription(lore.getDescription())
-                .folders(buildFoldersMap(nodes, pages, templateNameById, pageTitleById))
-                .tags(extractUniqueTags(pages))
-                .build();
+        return new LoreStructuralContext(
+                lore.getName(),
+                lore.getDescription(),
+                buildFoldersMap(nodes, pages, templateNameById, pageTitleById),
+                extractUniqueTags(pages));
     }
 
     private Map<String, List<PageSummary>> buildFoldersMap(
@@ -118,13 +117,12 @@ public class LoreStructuralContextBuilder {
             Page page,
             Map<String, String> templateNameById,
             Map<String, String> pageTitleById) {
-        return PageSummary.builder()
-                .title(page.getTitle())
-                .templateName(templateNameById.getOrDefault(page.getTemplateId(), "?"))
-                .values(truncatedValues(page.getValues()))
-                .tags(page.getTags() != null ? List.copyOf(page.getTags()) : Collections.emptyList())
-                .relatedPageTitles(resolveRelatedTitles(page.getRelatedPageIds(), pageTitleById))
-                .build();
+        return new PageSummary(
+                page.getTitle(),
+                templateNameById.getOrDefault(page.getTemplateId(), "?"),
+                truncatedValues(page.getValues()),
+                page.getTags() != null ? List.copyOf(page.getTags()) : Collections.emptyList(),
+                resolveRelatedTitles(page.getRelatedPageIds(), pageTitleById));
     }
 
     /**

core/src/main/java/com/loremind/application/generationcontext/NarrativeEntityContextBuilder.java

@@ -3,10 +3,12 @@ package com.loremind.application.generationcontext;
 import com.loremind.domain.campaigncontext.Arc;
 import com.loremind.domain.campaigncontext.Chapter;
 import com.loremind.domain.campaigncontext.Character;
+import com.loremind.domain.campaigncontext.Npc;
 import com.loremind.domain.campaigncontext.Scene;
 import com.loremind.domain.campaigncontext.ports.ArcRepository;
 import com.loremind.domain.campaigncontext.ports.ChapterRepository;
 import com.loremind.domain.campaigncontext.ports.CharacterRepository;
+import com.loremind.domain.campaigncontext.ports.NpcRepository;
 import com.loremind.domain.campaigncontext.ports.SceneRepository;
 import com.loremind.domain.generationcontext.NarrativeEntityContext;
 import org.springframework.stereotype.Component;
@@ -29,22 +31,25 @@ public class NarrativeEntityContextBuilder {
     private final ChapterRepository chapterRepository;
     private final SceneRepository sceneRepository;
     private final CharacterRepository characterRepository;
+    private final NpcRepository npcRepository;
 
     public NarrativeEntityContextBuilder(
             ArcRepository arcRepository,
             ChapterRepository chapterRepository,
             SceneRepository sceneRepository,
-            CharacterRepository characterRepository) {
+            CharacterRepository characterRepository,
+            NpcRepository npcRepository) {
         this.arcRepository = arcRepository;
         this.chapterRepository = chapterRepository;
         this.sceneRepository = sceneRepository;
         this.characterRepository = characterRepository;
+        this.npcRepository = npcRepository;
     }
 
     /**
      * Charge l'entité narrative ciblée et la projette vers un VO du GenerationContext.
      *
-     * @param entityType "arc", "chapter", "scene" ou "character" (insensible à la casse)
+     * @param entityType "arc", "chapter", "scene", "character" ou "npc" (insensible à la casse)
      * @param entityId   l'ID de l'entité
      * @throws IllegalArgumentException si le type est inconnu ou l'entité introuvable
      */
@@ -55,6 +60,7 @@ public class NarrativeEntityContextBuilder {
             case "chapter" -> fromChapter(loadChapter(entityId));
             case "scene" -> fromScene(loadScene(entityId));
             case "character" -> fromCharacter(loadCharacter(entityId));
+            case "npc" -> fromNpc(loadNpc(entityId));
             default -> throw new IllegalArgumentException("Type d'entité narrative inconnu: " + entityType);
         };
     }
@@ -81,6 +87,11 @@ public class NarrativeEntityContextBuilder {
                 .orElseThrow(() -> new IllegalArgumentException("Personnage non trouvé: " + id));
     }
 
+    private Npc loadNpc(String id) {
+        return npcRepository.findById(id)
+                .orElseThrow(() -> new IllegalArgumentException("PNJ non trouvé: " + id));
+    }
+
     // --- Mapping entité → VO ------------------------------------------------
 
     private NarrativeEntityContext fromArc(Arc a) {
@@ -91,11 +102,7 @@ public class NarrativeEntityContextBuilder {
         putField(fields, "rewards",    a.getRewards());
         putField(fields, "resolution", a.getResolution());
         putField(fields, "gmNotes",    a.getGmNotes());
-        return NarrativeEntityContext.builder()
-                .entityType("arc")
-                .title(a.getName())
-                .fields(fields)
-                .build();
+        return new NarrativeEntityContext("arc", a.getName(), fields);
     }
 
     private NarrativeEntityContext fromChapter(Chapter c) {
@@ -104,11 +111,7 @@ public class NarrativeEntityContextBuilder {
         putField(fields, "playerObjectives", c.getPlayerObjectives());
         putField(fields, "narrativeStakes", c.getNarrativeStakes());
         putField(fields, "gmNotes",          c.getGmNotes());
-        return NarrativeEntityContext.builder()
-                .entityType("chapter")
-                .title(c.getName())
-                .fields(fields)
-                .build();
+        return new NarrativeEntityContext("chapter", c.getName(), fields);
     }
 
     private NarrativeEntityContext fromScene(Scene s) {
@@ -122,21 +125,19 @@ public class NarrativeEntityContextBuilder {
         putField(fields, "combatDifficulty",     s.getCombatDifficulty());
         putField(fields, "enemies",              s.getEnemies());
         putField(fields, "gmSecretNotes",        s.getGmSecretNotes());
-        return NarrativeEntityContext.builder()
-                .entityType("scene")
-                .title(s.getName())
-                .fields(fields)
-                .build();
+        return new NarrativeEntityContext("scene", s.getName(), fields);
     }
 
     private NarrativeEntityContext fromCharacter(Character c) {
         Map<String, String> fields = new LinkedHashMap<>();
         putField(fields, "fiche complète (markdown)", c.getMarkdownContent());
-        return NarrativeEntityContext.builder()
-                .entityType("character")
-                .title(c.getName())
-                .fields(fields)
-                .build();
+        return new NarrativeEntityContext("character", c.getName(), fields);
+    }
+
+    private NarrativeEntityContext fromNpc(Npc n) {
+        Map<String, String> fields = new LinkedHashMap<>();
+        putField(fields, "fiche complète (markdown)", n.getMarkdownContent());
+        return new NarrativeEntityContext("npc", n.getName(), fields);
     }
 
     /** Null/blank devient chaîne vide — uniforme côté prompt, pas de NPE côté LLM. */

core/src/main/java/com/loremind/application/generationcontext/StreamChatForLoreUseCase.java

@@ -107,11 +107,6 @@ public class StreamChatForLoreUseCase {
                 ? page.getValues()
                 : Collections.emptyMap();
 
-        return PageContext.builder()
-                .title(page.getTitle())
-                .templateName(templateName)
-                .templateFields(templateFields)
-                .values(values)
-                .build();
+        return new PageContext(page.getTitle(), templateName, templateFields, values);
     }
 }

core/src/main/java/com/loremind/domain/campaigncontext/Arc.java

@@ -21,6 +21,9 @@ public class Arc {
     private String campaignId;       // Référence vers la Campaign parente
     private int order;               // Ordre de l'arc dans la campagne
 
+    /** Cle d'icone choisie par l'utilisateur (cf. CAMPAIGN_ICON_OPTIONS cote front). */
+    private String icon;
+
     // Champs narratifs enrichis (voir docs/maquettes/campagne/détail/)
     private String themes;           // Thèmes principaux explorés dans cet arc
     private String stakes;           // Enjeux globaux pour les personnages

core/src/main/java/com/loremind/domain/campaigncontext/Chapter.java

@@ -21,6 +21,9 @@ public class Chapter {
     private String arcId;              // Référence vers l'Arc parent
     private int order;                 // Ordre du chapitre dans l'arc
 
+    /** Cle d'icone choisie par l'utilisateur (cf. CAMPAIGN_ICON_OPTIONS cote front). */
+    private String icon;
+
     // Champs narratifs enrichis (voir docs/maquettes/campagne/détail/)
     private String gmNotes;            // Notes privées du MJ (non exportées vers FoundryVTT)
     private String playerObjectives;   // Objectifs des joueurs dans ce chapitre

core/src/main/java/com/loremind/domain/campaigncontext/Character.java

@@ -12,9 +12,10 @@ import java.time.LocalDateTime;
  * backstory, équipement). Évolution prévue vers un système templaté par
  * GameSystem (la fiche Nimble n'a pas les mêmes champs qu'une fiche D&D).
  * <p>
- * Scope strict PJ : les PNJ restent dans le Lore (pages templatées) ou
- * dans les scènes elles-mêmes. Si le besoin de PNJ spécifiques à une
- * campagne remonte, on étendra l'entité (ex: type enum PJ/PNJ).
+ * Scope strict PJ : les PNJ sont gérés par l'entité {@link Npc} dédiée
+ * (entité distincte plutôt qu'enum PJ/PNJ — invariants métier divergents).
+ * Évolution prévue : système de templating partagé PJ/PNJ piloté par
+ * GameSystem pour adapter les blocs aux différents systèmes de JDR.
  */
 @Data
 @Builder

core/src/main/java/com/loremind/domain/campaigncontext/Npc.java

@@ -0,0 +1,41 @@
+package com.loremind.domain.campaigncontext;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * Fiche de personnage non-joueur (PNJ) d'une campagne.
+ * <p>
+ * MVP : entité dédiée, distincte de {@link Character} (PJ). Choix DDD assumé —
+ * un PNJ a vocation à porter à terme des invariants métier propres (faction,
+ * statut vivant/mort/disparu, visibilité côté joueurs, relations inter-PNJ)
+ * qui n'ont aucun sens sur un PJ. Mutualiser via un enum aurait pollué l'entité
+ * PJ avec des champs inutiles ({@code if (type == NPC)} partout = anti-pattern).
+ * <p>
+ * Contenu markdown libre comme les PJ. Évolution prévue : templating partagé
+ * PJ/PNJ piloté par GameSystem.
+ * <p>
+ * Scope campagne : les PNJ "univers" (worldboss, figures du Lore) restent
+ * gérés via le système Page/Template du LoreContext.
+ */
+@Data
+@Builder
+public class Npc {
+
+    private String id;
+    private String name;
+
+    /** Contenu libre markdown — description, motivation, stats, notes MJ. Nullable à la création. */
+    private String markdownContent;
+
+    /** Référence vers la Campaign parente (cross-aggregate via ID, jamais d'objet). */
+    private String campaignId;
+
+    /** Ordre d'affichage dans la liste des PNJ de la campagne. */
+    private int order;
+
+    private LocalDateTime createdAt;
+    private LocalDateTime updatedAt;
+}

core/src/main/java/com/loremind/domain/campaigncontext/Scene.java

@@ -21,6 +21,9 @@ public class Scene {
     private String chapterId;              // Référence vers le Chapter parent
     private int order;                     // Ordre de la scène dans le chapitre
 
+    /** Cle d'icone choisie par l'utilisateur (cf. CAMPAIGN_ICON_OPTIONS cote front). */
+    private String icon;
+
     // === Contexte et ambiance ===
     private String location;               // Lieu de la scène (ex: Taverne du Dragon d'Or)
     private String timing;                 // Moment (ex: Soir, à la tombée de la nuit)

core/src/main/java/com/loremind/domain/campaigncontext/SceneBranch.java

@@ -1,31 +1,25 @@
 package com.loremind.domain.campaigncontext;
 
-import lombok.Builder;
-import lombok.Value;
-import lombok.extern.jackson.Jacksonized;
-
 /**
  * Value Object représentant une "sortie" narrative depuis une Scene.
  * Décrit un choix offert aux joueurs et la scène de destination associée.
  * <p>
- * Immuable (@Value) : pour "modifier" une branche on la remplace.
- * @Jacksonized : permet à Jackson (sérialisation JSON via le converter JPA)
- * de reconstruire l'objet en passant par le builder malgré l'absence de setters.
+ * Record Java : immuable par construction, sans aucune dépendance technique
+ * (pas de Lombok, pas de Jackson). Jackson 2.12+ sait sérialiser/désérialiser
+ * les records nativement via le constructeur canonique — c'est ce dont
+ * dépend le SceneBranchListJsonConverter pour le stockage JSONB.
  * <p>
  * Règle métier : targetSceneId DOIT pointer vers une Scene du MÊME Chapter
  * (validation portée par SceneService).
+ *
+ * @param label          Libellé du choix (ex: "Si les joueurs attaquent le garde").
+ * @param targetSceneId  Id de la Scene de destination, intra-chapitre uniquement.
+ * @param condition      Notes MJ privées sur la condition de déclenchement (optionnel).
  */
-@Value
-@Builder
-@Jacksonized
-public class SceneBranch {
+public record SceneBranch(String label, String targetSceneId, String condition) {
 
-    /** Libellé du choix (ex: "Si les joueurs attaquent le garde"). */
-    String label;
-
-    /** Id de la Scene de destination, intra-chapitre uniquement. */
-    String targetSceneId;
-
-    /** Notes MJ privées sur la condition de déclenchement (optionnel). */
-    String condition;
+    /** Raccourci pour construire une branche sans condition (cas le plus courant). */
+    public static SceneBranch of(String label, String targetSceneId) {
+        return new SceneBranch(label, targetSceneId, null);
+    }
 }

core/src/main/java/com/loremind/domain/campaigncontext/ports/NpcRepository.java

@@ -0,0 +1,22 @@
+package com.loremind.domain.campaigncontext.ports;
+
+import com.loremind.domain.campaigncontext.Npc;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Port de sortie pour la persistance des fiches de PNJ (campagne).
+ */
+public interface NpcRepository {
+
+    Npc save(Npc npc);
+
+    Optional<Npc> findById(String id);
+
+    List<Npc> findByCampaignId(String campaignId);
+
+    void deleteById(String id);
+
+    boolean existsById(String id);
+}

core/src/main/java/com/loremind/domain/generationcontext/CampaignStructuralContext.java

@@ -1,9 +1,5 @@
 package com.loremind.domain.generationcontext;
 
-import lombok.Builder;
-import lombok.Singular;
-import lombok.Value;
-
 import java.util.List;
 
 /**
@@ -22,16 +18,18 @@ import java.util.List;
  * <p>
  * La liste `arcs` préserve l'ordre narratif (tri sur `order` ascendant
  * fait par le use case côté application layer).
+ * <p>
+ * Record Java : pur domaine, aucune dépendance technique.
+ *
+ * @param characters Personnages joueurs (PJ) de la campagne. Vide si aucun.
+ * @param npcs       Personnages non-joueurs (PNJ) de la campagne. Vide si aucun.
  */
-@Value
-@Builder
-public class CampaignStructuralContext {
-
-    String campaignName;
-    String campaignDescription;
-    @Singular List<ArcSummary> arcs;
-    /** Personnages joueurs (PJ) de la campagne. Vide si aucun. */
-    @Singular List<CharacterSummary> characters;
+public record CampaignStructuralContext(
+        String campaignName,
+        String campaignDescription,
+        List<ArcSummary> arcs,
+        List<CharacterSummary> characters,
+        List<NpcSummary> npcs) {
 
     /**
      * Résumé d'un PJ : nom + snippet court du markdown.
@@ -40,53 +38,52 @@ public class CampaignStructuralContext {
      * La fiche complète n'est injectée que si le PJ est l'entité focus
      * (via NarrativeEntityContext, entity_type="character").
      */
-    @Value
-    @Builder
-    public static class CharacterSummary {
-        String name;
-        String snippet;
+    public record CharacterSummary(String name, String snippet) {
     }
 
-    /** Résumé d'un arc : nom + description courte + ses chapitres. */
-    @Value
-    @Builder
-    public static class ArcSummary {
-        String name;
-        String description;
-        /** Nombre d'illustrations attachees a cet arc (pour hint dans le prompt IA). */
-        int illustrationCount;
-        @Singular List<ChapterSummary> chapters;
+    /**
+     * Résumé d'un PNJ : symétrique à {@link CharacterSummary}.
+     * Snippet court extrait du markdown — la fiche complète est réservée
+     * à un usage focus (à venir, entity_type="npc").
+     */
+    public record NpcSummary(String name, String snippet) {
+    }
+
+    /**
+     * Résumé d'un arc : nom + description courte + ses chapitres.
+     *
+     * @param illustrationCount Nombre d'illustrations attachees a cet arc (pour hint dans le prompt IA).
+     */
+    public record ArcSummary(
+            String name,
+            String description,
+            int illustrationCount,
+            List<ChapterSummary> chapters) {
     }
 
     /** Résumé d'un chapitre : nom + description courte + ses scènes. */
-    @Value
-    @Builder
-    public static class ChapterSummary {
-        String name;
-        String description;
-        int illustrationCount;
-        @Singular List<SceneSummary> scenes;
+    public record ChapterSummary(
+            String name,
+            String description,
+            int illustrationCount,
+            List<SceneSummary> scenes) {
     }
 
     /** Résumé d'une scène : nom + description courte + branches narratives. */
-    @Value
-    @Builder
-    public static class SceneSummary {
-        String name;
-        String description;
-        int illustrationCount;
-        @Singular List<BranchHint> branches;
+    public record SceneSummary(
+            String name,
+            String description,
+            int illustrationCount,
+            List<BranchHint> branches) {
     }
 
-    /** Indice d'une branche narrative vers une autre scène du même chapitre. */
-    @Value
-    @Builder
-    public static class BranchHint {
-        /** Libellé du choix joueur (ex: "Si les joueurs attaquent le garde"). */
-        String label;
-        /** Nom de la scène cible (résolu depuis targetSceneId côté builder). */
-        String targetSceneName;
-        /** Condition MJ privée (optionnel). */
-        String condition;
+    /**
+     * Indice d'une branche narrative vers une autre scène du même chapitre.
+     *
+     * @param label           Libellé du choix joueur (ex: "Si les joueurs attaquent le garde").
+     * @param targetSceneName Nom de la scène cible (résolu depuis targetSceneId côté builder).
+     * @param condition       Condition MJ privée (optionnel).
+     */
+    public record BranchHint(String label, String targetSceneName, String condition) {
     }
 }

core/src/main/java/com/loremind/domain/generationcontext/ChatRequest.java

@@ -1,8 +1,5 @@
 package com.loremind.domain.generationcontext;
 
-import lombok.Builder;
-import lombok.Value;
-
 import java.util.List;
 
 /**
@@ -21,28 +18,74 @@ import java.util.List;
  * Un chat Lore ne reçoit JAMAIS de campaignContext : un Lore ne voit pas
  * ses campagnes (asymétrie métier : la campagne est l'emprunteur du Lore,
  * pas l'inverse).
+ * <p>
+ * Record Java : pur domaine. Builder manuel fourni en raison des 6 champs
+ * dont 5 sont nullables — l'API fluide reste plus lisible aux call sites
+ * qu'un constructeur à 6 paramètres souvent à null.
+ *
+ * @param loreContext       Optionnel : carte structurelle du Lore. Null si campagne non liée à un Lore.
+ * @param pageContext       Optionnel : contexte d'une page précise en cours d'édition (chat Lore uniquement).
+ * @param campaignContext   Optionnel : carte narrative d'une Campagne (chat Campagne uniquement).
+ * @param narrativeEntity   Optionnel : entité narrative en cours d'édition (arc/chapter/scene).
+ * @param gameSystemContext Optionnel : règles du système de JDR de la campagne (filtrées par intent).
+ *                          Null si la campagne n'a pas de GameSystem associé. Campagne uniquement au MVP.
  */
-@Value
-@Builder
-public class ChatRequest {
+public record ChatRequest(
+        List<ChatMessage> messages,
+        LoreStructuralContext loreContext,
+        PageContext pageContext,
+        CampaignStructuralContext campaignContext,
+        NarrativeEntityContext narrativeEntity,
+        GameSystemContext gameSystemContext) {
 
-    List<ChatMessage> messages;
+    public static Builder builder() {
+        return new Builder();
+    }
 
-    /** Optionnel : carte structurelle du Lore. Null si campagne non liée à un Lore. */
-    LoreStructuralContext loreContext;
+    /** Builder fluide : permet d'omettre les contextes non pertinents. */
+    public static final class Builder {
+        private List<ChatMessage> messages;
+        private LoreStructuralContext loreContext;
+        private PageContext pageContext;
+        private CampaignStructuralContext campaignContext;
+        private NarrativeEntityContext narrativeEntity;
+        private GameSystemContext gameSystemContext;
 
-    /** Optionnel : contexte d'une page précise en cours d'édition (chat Lore uniquement). */
-    PageContext pageContext;
+        private Builder() {}
 
-    /** Optionnel : carte narrative d'une Campagne (chat Campagne uniquement). */
-    CampaignStructuralContext campaignContext;
+        public Builder messages(List<ChatMessage> messages) {
+            this.messages = messages;
+            return this;
+        }
 
-    /** Optionnel : entité narrative en cours d'édition (arc/chapter/scene). */
-    NarrativeEntityContext narrativeEntity;
+        public Builder loreContext(LoreStructuralContext loreContext) {
+            this.loreContext = loreContext;
+            return this;
+        }
 
-    /**
-     * Optionnel : règles du système de JDR de la campagne (filtrées par intent).
-     * Null si la campagne n'a pas de GameSystem associé. Campagne uniquement au MVP.
-     */
-    GameSystemContext gameSystemContext;
+        public Builder pageContext(PageContext pageContext) {
+            this.pageContext = pageContext;
+            return this;
+        }
+
+        public Builder campaignContext(CampaignStructuralContext campaignContext) {
+            this.campaignContext = campaignContext;
+            return this;
+        }
+
+        public Builder narrativeEntity(NarrativeEntityContext narrativeEntity) {
+            this.narrativeEntity = narrativeEntity;
+            return this;
+        }
+
+        public Builder gameSystemContext(GameSystemContext gameSystemContext) {
+            this.gameSystemContext = gameSystemContext;
+            return this;
+        }
+
+        public ChatRequest build() {
+            return new ChatRequest(messages, loreContext, pageContext,
+                    campaignContext, narrativeEntity, gameSystemContext);
+        }
+    }
 }

core/src/main/java/com/loremind/domain/generationcontext/GameSystemContext.java

@@ -1,8 +1,5 @@
 package com.loremind.domain.generationcontext;
 
-import lombok.Builder;
-import lombok.Value;
-
 import java.util.Map;
 
 /**
@@ -11,20 +8,14 @@ import java.util.Map;
  * Contient uniquement les sections pertinentes pour l'intent de génération
  * en cours (sélection effectuée par GameSystemContextBuilder). Les sections
  * sont indexées par leur titre H2 original (ex : "Combat", "Classes").
+ *
+ * @param systemName        Nom du système de JDR (ex : "Nimble", "D&D 5.1 SRD").
+ * @param systemDescription Description courte du système (nullable).
+ * @param sections          Sections de règles pertinentes, indexées par titre H2.
+ *                          Vide si le GameSystem n'a aucune règle ou si aucune section ne matche l'intent.
  */
-@Value
-@Builder
-public class GameSystemContext {
-
-    /** Nom du système de JDR (ex : "Nimble", "D&D 5.1 SRD"). */
-    String systemName;
-
-    /** Description courte du système (nullable). */
-    String systemDescription;
-
-    /**
-     * Sections de règles pertinentes, indexées par titre H2.
-     * Vide si le GameSystem n'a aucune règle ou si aucune section ne matche l'intent.
-     */
-    Map<String, String> sections;
+public record GameSystemContext(
+        String systemName,
+        String systemDescription,
+        Map<String, String> sections) {
 }

core/src/main/java/com/loremind/domain/generationcontext/GenerationContext.java

@@ -1,8 +1,5 @@
 package com.loremind.domain.generationcontext;
 
-import lombok.Builder;
-import lombok.Value;
-
 import java.util.List;
 
 /**
@@ -10,19 +7,16 @@ import java.util.List;
  * pour remplir une Page à partir d'un Template.
  * <p>
  * Équivalent Java du PageGenerationContext Python (brain/app/domain/models.py).
- * Entité pure du domaine : aucune dépendance technique.
- * <p>
- * Immuable via @Value (Lombok) : pas de setters, tous les champs final.
- * C'est un DTO de domaine entrant dans le port AiProvider.
+ * Record Java : pur domaine, aucune dépendance technique.
+ *
+ * @param templateFields Champs à générer (clés attendues dans la réponse).
+ * @param folderName     Nom du LoreNode parent (ex: "PNJ", "Lieux").
  */
-@Value
-@Builder
-public class GenerationContext {
-
-    String loreName;
-    String loreDescription;
-    String folderName;            // Nom du LoreNode parent (ex: "PNJ", "Lieux")
-    String templateName;
-    List<String> templateFields;  // Champs à générer (clés attendues dans la réponse)
-    String pageTitle;
+public record GenerationContext(
+        String loreName,
+        String loreDescription,
+        String folderName,
+        String templateName,
+        List<String> templateFields,
+        String pageTitle) {
 }

core/src/main/java/com/loremind/domain/generationcontext/LoreStructuralContext.java

@@ -1,9 +1,5 @@
 package com.loremind.domain.generationcontext;
 
-import lombok.Builder;
-import lombok.Singular;
-import lombok.Value;
-
 import java.util.List;
 import java.util.Map;
 
@@ -16,15 +12,14 @@ import java.util.Map;
  * <p>
  * La map `folders` est indexée par nom de dossier et mappe vers la liste
  * des pages qu'il contient (liste vide autorisée pour les dossiers vides).
+ * <p>
+ * Record Java : pur domaine, aucune dépendance technique.
  */
-@Value
-@Builder
-public class LoreStructuralContext {
-
-    String loreName;
-    String loreDescription;
-    Map<String, List<PageSummary>> folders;
-    @Singular List<String> tags;
+public record LoreStructuralContext(
+        String loreName,
+        String loreDescription,
+        Map<String, List<PageSummary>> folders,
+        List<String> tags) {
 
     /**
      * Résumé projeté d'une page pour l'IA.
@@ -40,13 +35,11 @@ public class LoreStructuralContext {
      * uniquement ce qui est partageable en narration — les secrets MJ
      * restent confinés à leur page d'édition).
      */
-    @Value
-    @Builder
-    public static class PageSummary {
-        String title;
-        String templateName;
-        Map<String, String> values;
-        List<String> tags;
-        List<String> relatedPageTitles;
+    public record PageSummary(
+            String title,
+            String templateName,
+            Map<String, String> values,
+            List<String> tags,
+            List<String> relatedPageTitles) {
     }
 }

core/src/main/java/com/loremind/domain/generationcontext/NarrativeEntityContext.java

@@ -1,8 +1,5 @@
 package com.loremind.domain.generationcontext;
 
-import lombok.Builder;
-import lombok.Value;
-
 import java.util.Map;
 
 /**
@@ -17,13 +14,11 @@ import java.util.Map;
  * `fields` associe le nom d'un champ (ex: "themes", "playerNarration")
  * à sa valeur actuelle (chaîne vide si non renseigné). Utiliser une
  * LinkedHashMap à la construction pour un prompt lisible (ordre préservé).
+ *
+ * @param entityType "arc", "chapter" ou "scene" — utilisé pour libeller le bloc du prompt.
  */
-@Value
-@Builder
-public class NarrativeEntityContext {
-
-    /** "arc", "chapter" ou "scene" — utilisé pour libeller le bloc du prompt. */
-    String entityType;
-    String title;
-    Map<String, String> fields;
+public record NarrativeEntityContext(
+        String entityType,
+        String title,
+        Map<String, String> fields) {
 }

core/src/main/java/com/loremind/domain/generationcontext/PageContext.java

@@ -1,8 +1,5 @@
 package com.loremind.domain.generationcontext;
 
-import lombok.Builder;
-import lombok.Value;
-
 import java.util.List;
 import java.util.Map;
 
@@ -14,14 +11,11 @@ import java.util.Map;
  * à l'IA de focaliser ses suggestions sur les bons champs sans déborder
  * sur d'autres pages/templates.
  * <p>
- * Object de valeur immuable, pur domaine — aucune dépendance technique.
+ * Record Java : immuable, pur domaine, aucune dépendance technique.
  */
-@Value
-@Builder
-public class PageContext {
-
-    String title;
-    String templateName;
-    List<String> templateFields;
-    Map<String, String> values;
+public record PageContext(
+        String title,
+        String templateName,
+        List<String> templateFields,
+        Map<String, String> values) {
 }

core/src/main/java/com/loremind/infrastructure/ai/BrainAiClient.java

@@ -53,12 +53,12 @@ public class BrainAiClient implements AiProvider {
 
     private BrainGeneratePageRequest toBrainRequest(GenerationContext context) {
         return new BrainGeneratePageRequest(
-                context.getLoreName(),
-                context.getLoreDescription(),
-                context.getFolderName(),
-                context.getTemplateName(),
-                context.getTemplateFields(),
-                context.getPageTitle()
+                context.loreName(),
+                context.loreDescription(),
+                context.folderName(),
+                context.templateName(),
+                context.templateFields(),
+                context.pageTitle()
         );
     }
 

core/src/main/java/com/loremind/infrastructure/ai/BrainChatPayloadBuilder.java

@@ -5,6 +5,7 @@ import com.loremind.domain.generationcontext.CampaignStructuralContext.ArcSummar
 import com.loremind.domain.generationcontext.CampaignStructuralContext.BranchHint;
 import com.loremind.domain.generationcontext.CampaignStructuralContext.ChapterSummary;
 import com.loremind.domain.generationcontext.CampaignStructuralContext.CharacterSummary;
+import com.loremind.domain.generationcontext.CampaignStructuralContext.NpcSummary;
 import com.loremind.domain.generationcontext.CampaignStructuralContext.SceneSummary;
 import com.loremind.domain.generationcontext.ChatMessage;
 import com.loremind.domain.generationcontext.ChatRequest;
@@ -38,35 +39,35 @@ public class BrainChatPayloadBuilder {
 
     public Map<String, Object> build(ChatRequest request) {
         Map<String, Object> root = new LinkedHashMap<>();
-        root.put("messages", request.getMessages().stream()
+        root.put("messages", request.messages().stream()
                 .map(this::messageToMap)
                 .collect(Collectors.toList()));
 
-        if (request.getLoreContext() != null) {
-            root.put("lore_context", loreContextToMap(request.getLoreContext()));
+        if (request.loreContext() != null) {
+            root.put("lore_context", loreContextToMap(request.loreContext()));
         }
-        if (request.getPageContext() != null) {
-            root.put("page_context", pageContextToMap(request.getPageContext()));
+        if (request.pageContext() != null) {
+            root.put("page_context", pageContextToMap(request.pageContext()));
         }
-        if (request.getCampaignContext() != null) {
-            root.put("campaign_context", campaignContextToMap(request.getCampaignContext()));
+        if (request.campaignContext() != null) {
+            root.put("campaign_context", campaignContextToMap(request.campaignContext()));
         }
-        if (request.getNarrativeEntity() != null) {
-            root.put("narrative_entity", narrativeEntityToMap(request.getNarrativeEntity()));
+        if (request.narrativeEntity() != null) {
+            root.put("narrative_entity", narrativeEntityToMap(request.narrativeEntity()));
         }
-        if (request.getGameSystemContext() != null) {
-            root.put("game_system_context", gameSystemContextToMap(request.getGameSystemContext()));
+        if (request.gameSystemContext() != null) {
+            root.put("game_system_context", gameSystemContextToMap(request.gameSystemContext()));
         }
         return root;
     }
 
     private Map<String, Object> gameSystemContextToMap(GameSystemContext gs) {
         Map<String, Object> map = new LinkedHashMap<>();
-        map.put("system_name", gs.getSystemName());
-        if (gs.getSystemDescription() != null && !gs.getSystemDescription().isBlank()) {
-            map.put("system_description", gs.getSystemDescription());
+        map.put("system_name", gs.systemName());
+        if (gs.systemDescription() != null && !gs.systemDescription().isBlank()) {
+            map.put("system_description", gs.systemDescription());
         }
-        map.put("sections", gs.getSections() != null ? gs.getSections() : Map.of());
+        map.put("sections", gs.sections() != null ? gs.sections() : Map.of());
         return map;
     }
 
@@ -79,67 +80,82 @@ public class BrainChatPayloadBuilder {
 
     private Map<String, Object> loreContextToMap(LoreStructuralContext ctx) {
         Map<String, Object> map = new LinkedHashMap<>();
-        map.put("lore_name", ctx.getLoreName());
-        map.put("lore_description", ctx.getLoreDescription());
+        map.put("lore_name", ctx.loreName());
+        map.put("lore_description", ctx.loreDescription());
 
         Map<String, Object> foldersMap = new LinkedHashMap<>();
-        for (Map.Entry<String, List<PageSummary>> e : ctx.getFolders().entrySet()) {
+        for (Map.Entry<String, List<PageSummary>> e : ctx.folders().entrySet()) {
             foldersMap.put(e.getKey(), e.getValue().stream()
                     .map(this::pageSummaryToMap)
                     .collect(Collectors.toList()));
         }
         map.put("folders", foldersMap);
-        map.put("tags", ctx.getTags());
+        map.put("tags", ctx.tags());
         return map;
     }
 
     private Map<String, Object> pageSummaryToMap(PageSummary ps) {
         Map<String, Object> map = new LinkedHashMap<>();
-        map.put("title", ps.getTitle());
-        map.put("template_name", ps.getTemplateName());
+        map.put("title", ps.title());
+        map.put("template_name", ps.templateName());
         // values/tags/related_page_titles : omis si vides pour alléger le payload.
-        if (ps.getValues() != null && !ps.getValues().isEmpty()) {
-            map.put("values", ps.getValues());
+        if (ps.values() != null && !ps.values().isEmpty()) {
+            map.put("values", ps.values());
         }
-        if (ps.getTags() != null && !ps.getTags().isEmpty()) {
-            map.put("tags", ps.getTags());
+        if (ps.tags() != null && !ps.tags().isEmpty()) {
+            map.put("tags", ps.tags());
         }
-        if (ps.getRelatedPageTitles() != null && !ps.getRelatedPageTitles().isEmpty()) {
-            map.put("related_page_titles", ps.getRelatedPageTitles());
+        if (ps.relatedPageTitles() != null && !ps.relatedPageTitles().isEmpty()) {
+            map.put("related_page_titles", ps.relatedPageTitles());
         }
         return map;
     }
 
     private Map<String, Object> pageContextToMap(PageContext pc) {
         Map<String, Object> map = new LinkedHashMap<>();
-        map.put("title", pc.getTitle());
-        map.put("template_name", pc.getTemplateName());
-        map.put("template_fields", pc.getTemplateFields());
-        map.put("values", pc.getValues());
+        map.put("title", pc.title());
+        map.put("template_name", pc.templateName());
+        map.put("template_fields", pc.templateFields());
+        map.put("values", pc.values());
         return map;
     }
 
     private Map<String, Object> campaignContextToMap(CampaignStructuralContext ctx) {
         Map<String, Object> map = new LinkedHashMap<>();
-        map.put("campaign_name", ctx.getCampaignName());
-        map.put("campaign_description", ctx.getCampaignDescription());
-        map.put("arcs", ctx.getArcs().stream()
+        map.put("campaign_name", ctx.campaignName());
+        map.put("campaign_description", ctx.campaignDescription());
+        map.put("arcs", ctx.arcs().stream()
                 .map(this::arcSummaryToMap)
                 .collect(Collectors.toList()));
         // Liste des PJ : omise si aucun pour alléger le prompt des campagnes sans fiches.
-        if (ctx.getCharacters() != null && !ctx.getCharacters().isEmpty()) {
-            map.put("characters", ctx.getCharacters().stream()
+        if (ctx.characters() != null && !ctx.characters().isEmpty()) {
+            map.put("characters", ctx.characters().stream()
                     .map(this::characterSummaryToMap)
                     .collect(Collectors.toList()));
         }
+        // Liste des PNJ : symétrique aux PJ, omise si vide pour alléger le payload.
+        if (ctx.npcs() != null && !ctx.npcs().isEmpty()) {
+            map.put("npcs", ctx.npcs().stream()
+                    .map(this::npcSummaryToMap)
+                    .collect(Collectors.toList()));
+        }
         return map;
     }
 
     private Map<String, Object> characterSummaryToMap(CharacterSummary c) {
         Map<String, Object> map = new LinkedHashMap<>();
-        map.put("name", c.getName());
-        if (c.getSnippet() != null && !c.getSnippet().isBlank()) {
-            map.put("snippet", c.getSnippet());
+        map.put("name", c.name());
+        if (c.snippet() != null && !c.snippet().isBlank()) {
+            map.put("snippet", c.snippet());
+        }
+        return map;
+    }
+
+    private Map<String, Object> npcSummaryToMap(NpcSummary n) {
+        Map<String, Object> map = new LinkedHashMap<>();
+        map.put("name", n.name());
+        if (n.snippet() != null && !n.snippet().isBlank()) {
+            map.put("snippet", n.snippet());
         }
         return map;
     }
@@ -167,10 +183,10 @@ public class BrainChatPayloadBuilder {
     private Map<String, Object> arcSummaryToMap(ArcSummary a) {
         return structuralSummaryToMap(
                 a,
-                ArcSummary::getName,
-                ArcSummary::getDescription,
-                ArcSummary::getIllustrationCount,
-                (map, arc) -> map.put("chapters", arc.getChapters().stream()
+                ArcSummary::name,
+                ArcSummary::description,
+                ArcSummary::illustrationCount,
+                (map, arc) -> map.put("chapters", arc.chapters().stream()
                         .map(this::chapterSummaryToMap)
                         .collect(Collectors.toList())));
     }
@@ -178,10 +194,10 @@ public class BrainChatPayloadBuilder {
     private Map<String, Object> chapterSummaryToMap(ChapterSummary c) {
         return structuralSummaryToMap(
                 c,
-                ChapterSummary::getName,
-                ChapterSummary::getDescription,
-                ChapterSummary::getIllustrationCount,
-                (map, chapter) -> map.put("scenes", chapter.getScenes().stream()
+                ChapterSummary::name,
+                ChapterSummary::description,
+                ChapterSummary::illustrationCount,
+                (map, chapter) -> map.put("scenes", chapter.scenes().stream()
                         .map(this::sceneSummaryToMap)
                         .collect(Collectors.toList())));
     }
@@ -189,13 +205,13 @@ public class BrainChatPayloadBuilder {
     private Map<String, Object> sceneSummaryToMap(SceneSummary s) {
         return structuralSummaryToMap(
                 s,
-                SceneSummary::getName,
-                SceneSummary::getDescription,
-                SceneSummary::getIllustrationCount,
+                SceneSummary::name,
+                SceneSummary::description,
+                SceneSummary::illustrationCount,
                 (map, scene) -> {
                     // Branches narratives : omises si absentes (scènes linéaires classiques).
-                    if (s.getBranches() != null && !s.getBranches().isEmpty()) {
-                        map.put("branches", s.getBranches().stream()
+                    if (s.branches() != null && !s.branches().isEmpty()) {
+                        map.put("branches", s.branches().stream()
                                 .map(this::branchHintToMap)
                                 .collect(Collectors.toList()));
                     }
@@ -204,19 +220,19 @@ public class BrainChatPayloadBuilder {
 
     private Map<String, Object> branchHintToMap(BranchHint b) {
         Map<String, Object> map = new LinkedHashMap<>();
-        map.put("label", b.getLabel());
-        map.put("target_scene_name", b.getTargetSceneName());
-        if (b.getCondition() != null && !b.getCondition().isBlank()) {
-            map.put("condition", b.getCondition());
+        map.put("label", b.label());
+        map.put("target_scene_name", b.targetSceneName());
+        if (b.condition() != null && !b.condition().isBlank()) {
+            map.put("condition", b.condition());
         }
         return map;
     }
 
     private Map<String, Object> narrativeEntityToMap(NarrativeEntityContext ne) {
         Map<String, Object> map = new LinkedHashMap<>();
-        map.put("entity_type", ne.getEntityType());
-        map.put("title", ne.getTitle());
-        map.put("fields", ne.getFields());
+        map.put("entity_type", ne.entityType());
+        map.put("title", ne.title());
+        map.put("fields", ne.fields());
         return map;
     }
 }

core/src/main/java/com/loremind/infrastructure/persistence/entity/ArcJpaEntity.java

@@ -37,6 +37,9 @@ public class ArcJpaEntity {
     @Column(name = "\"order\"", nullable = false)
     private int order;
 
+    @Column
+    private String icon;
+
     // Champs narratifs enrichis — ajoutés automatiquement par Hibernate DDL (ddl-auto=update)
     @Column(columnDefinition = "TEXT")
     private String themes;

core/src/main/java/com/loremind/infrastructure/persistence/entity/ChapterJpaEntity.java

@@ -37,6 +37,9 @@ public class ChapterJpaEntity {
     @Column(name = "\"order\"", nullable = false)
     private int order;
 
+    @Column
+    private String icon;
+
     // Champs narratifs enrichis — ajoutés automatiquement par Hibernate DDL (ddl-auto=update)
     @Column(name = "gm_notes", columnDefinition = "TEXT")
     private String gmNotes;

core/src/main/java/com/loremind/infrastructure/persistence/entity/NpcJpaEntity.java

@@ -0,0 +1,55 @@
+package com.loremind.infrastructure.persistence.entity;
+
+import jakarta.persistence.*;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.time.LocalDateTime;
+
+/**
+ * Entité JPA pour les fiches de PNJ d'une campagne.
+ * Pas de FK physique vers campaigns (weak reference cross-agrégat intra-contexte).
+ */
+@Entity
+@Table(name = "npcs")
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class NpcJpaEntity {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false)
+    private String name;
+
+    @Column(name = "markdown_content", columnDefinition = "TEXT")
+    private String markdownContent;
+
+    @Column(name = "campaign_id", nullable = false)
+    private Long campaignId;
+
+    @Column(name = "\"order\"", nullable = false)
+    private int order;
+
+    @Column(name = "created_at", nullable = false, updatable = false)
+    private LocalDateTime createdAt;
+
+    @Column(name = "updated_at", nullable = false)
+    private LocalDateTime updatedAt;
+
+    @PrePersist
+    protected void onCreate() {
+        createdAt = LocalDateTime.now();
+        updatedAt = LocalDateTime.now();
+    }
+
+    @PreUpdate
+    protected void onUpdate() {
+        updatedAt = LocalDateTime.now();
+    }
+}

core/src/main/java/com/loremind/infrastructure/persistence/entity/SceneJpaEntity.java

@@ -39,6 +39,9 @@ public class SceneJpaEntity {
     @Column(name = "\"order\"", nullable = false)
     private int order;
 
+    @Column
+    private String icon;
+
     // Champs narratifs enrichis — ajoutés automatiquement par Hibernate (ddl-auto=update)
 
     // Contexte et ambiance

core/src/main/java/com/loremind/infrastructure/persistence/jpa/NpcJpaRepository.java

@@ -0,0 +1,13 @@
+package com.loremind.infrastructure.persistence.jpa;
+
+import com.loremind.infrastructure.persistence.entity.NpcJpaEntity;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.stereotype.Repository;
+
+import java.util.List;
+
+@Repository
+public interface NpcJpaRepository extends JpaRepository<NpcJpaEntity, Long> {
+
+    List<NpcJpaEntity> findByCampaignIdOrderByOrderAsc(Long campaignId);
+}

core/src/main/java/com/loremind/infrastructure/persistence/postgres/PostgresArcRepository.java

@@ -71,6 +71,7 @@ public class PostgresArcRepository implements ArcRepository {
                 .description(jpaEntity.getDescription())
                 .campaignId(jpaEntity.getCampaignId().toString())
                 .order(jpaEntity.getOrder())
+                .icon(jpaEntity.getIcon())
                 .themes(jpaEntity.getThemes())
                 .stakes(jpaEntity.getStakes())
                 .gmNotes(jpaEntity.getGmNotes())
@@ -99,6 +100,7 @@ public class PostgresArcRepository implements ArcRepository {
                 .description(arc.getDescription())
                 .campaignId(Long.parseLong(arc.getCampaignId()))
                 .order(arc.getOrder())
+                .icon(arc.getIcon())
                 .themes(arc.getThemes())
                 .stakes(arc.getStakes())
                 .gmNotes(arc.getGmNotes())

core/src/main/java/com/loremind/infrastructure/persistence/postgres/PostgresChapterRepository.java

@@ -71,6 +71,7 @@ public class PostgresChapterRepository implements ChapterRepository {
                 .description(jpaEntity.getDescription())
                 .arcId(jpaEntity.getArcId().toString())
                 .order(jpaEntity.getOrder())
+                .icon(jpaEntity.getIcon())
                 .gmNotes(jpaEntity.getGmNotes())
                 .playerObjectives(jpaEntity.getPlayerObjectives())
                 .narrativeStakes(jpaEntity.getNarrativeStakes())
@@ -96,6 +97,7 @@ public class PostgresChapterRepository implements ChapterRepository {
                 .description(chapter.getDescription())
                 .arcId(Long.parseLong(chapter.getArcId()))
                 .order(chapter.getOrder())
+                .icon(chapter.getIcon())
                 .gmNotes(chapter.getGmNotes())
                 .playerObjectives(chapter.getPlayerObjectives())
                 .narrativeStakes(chapter.getNarrativeStakes())

core/src/main/java/com/loremind/infrastructure/persistence/postgres/PostgresNpcRepository.java

@@ -0,0 +1,75 @@
+package com.loremind.infrastructure.persistence.postgres;
+
+import com.loremind.domain.campaigncontext.Npc;
+import com.loremind.domain.campaigncontext.ports.NpcRepository;
+import com.loremind.infrastructure.persistence.entity.NpcJpaEntity;
+import com.loremind.infrastructure.persistence.jpa.NpcJpaRepository;
+import org.springframework.stereotype.Repository;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.stream.Collectors;
+
+@Repository
+public class PostgresNpcRepository implements NpcRepository {
+
+    private final NpcJpaRepository jpaRepository;
+
+    public PostgresNpcRepository(NpcJpaRepository jpaRepository) {
+        this.jpaRepository = jpaRepository;
+    }
+
+    @Override
+    public Npc save(Npc npc) {
+        NpcJpaEntity entity = toJpaEntity(npc);
+        NpcJpaEntity saved = jpaRepository.save(entity);
+        return toDomainEntity(saved);
+    }
+
+    @Override
+    public Optional<Npc> findById(String id) {
+        return jpaRepository.findById(Long.parseLong(id)).map(this::toDomainEntity);
+    }
+
+    @Override
+    public List<Npc> findByCampaignId(String campaignId) {
+        return jpaRepository.findByCampaignIdOrderByOrderAsc(Long.parseLong(campaignId)).stream()
+                .map(this::toDomainEntity)
+                .collect(Collectors.toList());
+    }
+
+    @Override
+    public void deleteById(String id) {
+        jpaRepository.deleteById(Long.parseLong(id));
+    }
+
+    @Override
+    public boolean existsById(String id) {
+        return jpaRepository.existsById(Long.parseLong(id));
+    }
+
+    private Npc toDomainEntity(NpcJpaEntity e) {
+        return Npc.builder()
+                .id(e.getId().toString())
+                .name(e.getName())
+                .markdownContent(e.getMarkdownContent())
+                .campaignId(e.getCampaignId().toString())
+                .order(e.getOrder())
+                .createdAt(e.getCreatedAt())
+                .updatedAt(e.getUpdatedAt())
+                .build();
+    }
+
+    private NpcJpaEntity toJpaEntity(Npc n) {
+        Long id = n.getId() != null ? Long.parseLong(n.getId()) : null;
+        return NpcJpaEntity.builder()
+                .id(id)
+                .name(n.getName())
+                .markdownContent(n.getMarkdownContent())
+                .campaignId(Long.parseLong(n.getCampaignId()))
+                .order(n.getOrder())
+                .createdAt(n.getCreatedAt())
+                .updatedAt(n.getUpdatedAt())
+                .build();
+    }
+}

core/src/main/java/com/loremind/infrastructure/persistence/postgres/PostgresSceneRepository.java

@@ -71,6 +71,7 @@ public class PostgresSceneRepository implements SceneRepository {
                 .description(jpaEntity.getDescription())
                 .chapterId(jpaEntity.getChapterId().toString())
                 .order(jpaEntity.getOrder())
+                .icon(jpaEntity.getIcon())
                 .location(jpaEntity.getLocation())
                 .timing(jpaEntity.getTiming())
                 .atmosphere(jpaEntity.getAtmosphere())
@@ -104,6 +105,7 @@ public class PostgresSceneRepository implements SceneRepository {
                 .description(scene.getDescription())
                 .chapterId(Long.parseLong(scene.getChapterId()))
                 .order(scene.getOrder())
+                .icon(scene.getIcon())
                 .location(scene.getLocation())
                 .timing(scene.getTiming())
                 .atmosphere(scene.getAtmosphere())

core/src/main/java/com/loremind/infrastructure/updates/UpdateCheckService.java

@@ -0,0 +1,367 @@
+package com.loremind.infrastructure.updates;
+
+import jakarta.annotation.PostConstruct;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.web.client.RestTemplateBuilder;
+import org.springframework.http.HttpEntity;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpMethod;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.stereotype.Service;
+import org.springframework.web.client.HttpClientErrorException;
+import org.springframework.web.client.RestTemplate;
+
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Detection des mises a jour disponibles + declenchement via Watchtower.
+ *
+ * Strategie :
+ *  - Au demarrage, on interroge le registry pour le digest courant de chaque
+ *    image suivie ({@code update-check.images}). On stocke ces digests comme
+ *    "baseline" (= ce que le conteneur en cours d'execution est cense faire
+ *    tourner, puisque le `docker compose pull` precede toujours `up -d`).
+ *  - Si l'init echoue (reseau Docker pas encore pret, registry transitoirement
+ *    indisponible), un thread daemon de retry avec backoff complete les
+ *    baselines manquantes en arriere-plan.
+ *  - {@link #check()} re-interroge le registry et compare. Si un digest a
+ *    change, une mise a jour est disponible. Si la baseline manque (echec
+ *    de tous les retries), retourne {@link ImageStatusKind#UNKNOWN} pour
+ *    cette image — JAMAIS d'alignement silencieux (eviterait des MAJ ratees).
+ *  - {@link #apply()} POST sur /v1/update de Watchtower (qui doit etre lance
+ *    avec WATCHTOWER_HTTP_API_UPDATE=true et le meme token).
+ *
+ * Apres un apply reussi, Watchtower redemarre core => ce service est
+ * re-instancie => baseline re-aligne sur le registry => check renvoie
+ * "pas de MAJ" (etat coherent).
+ *
+ * La feature est <b>desactivee silencieusement</b> si {@code WATCHTOWER_TOKEN}
+ * n'est pas defini : check/apply renvoient des reponses neutres et l'UI
+ * masque le badge / bouton.
+ */
+@Service
+public class UpdateCheckService {
+
+    private static final Logger log = LoggerFactory.getLogger(UpdateCheckService.class);
+
+    private static final List<MediaType> MANIFEST_ACCEPT = List.of(
+            MediaType.parseMediaType("application/vnd.docker.distribution.manifest.v2+json"),
+            MediaType.parseMediaType("application/vnd.docker.distribution.manifest.list.v2+json"),
+            MediaType.parseMediaType("application/vnd.oci.image.manifest.v1+json"),
+            MediaType.parseMediaType("application/vnd.oci.image.index.v1+json")
+    );
+
+    private final RestTemplate http;
+    private final String registry;
+    private final List<String> images;
+    private final String tag;
+    private final String watchtowerUrl;
+    private final String watchtowerToken;
+
+    private final Map<String, String> baselineDigests = new ConcurrentHashMap<>();
+
+    public UpdateCheckService(
+            RestTemplateBuilder builder,
+            @Value("${update-check.registry:}") String registry,
+            @Value("${update-check.images:}") String imagesCsv,
+            @Value("${update-check.tag:latest}") String tag,
+            @Value("${update-check.watchtower-url:http://watchtower:8080}") String watchtowerUrl,
+            @Value("${update-check.watchtower-token:}") String watchtowerToken) {
+        this.http = builder
+                .setConnectTimeout(Duration.ofSeconds(5))
+                .setReadTimeout(Duration.ofSeconds(15))
+                .build();
+        this.registry = normalizeRegistry(registry);
+        this.images = parseImages(imagesCsv);
+        this.tag = tag;
+        this.watchtowerUrl = watchtowerUrl;
+        this.watchtowerToken = watchtowerToken;
+    }
+
+    /** Backoff progressif (ms) pour retry de baseline en cas d'echec initial. */
+    private static final long[] BASELINE_RETRY_BACKOFFS_MS = {2_000, 5_000, 15_000, 30_000, 60_000};
+
+    @PostConstruct
+    void initBaseline() {
+        if (!isEnabled()) {
+            log.info("Update check disabled (WATCHTOWER_TOKEN not set)");
+            return;
+        }
+        log.info("Update check enabled - registry={} images={} tag={}", registry, images, tag);
+        boolean complete = tryBaselineMissing();
+        if (!complete) {
+            startBaselineRetryThread();
+        }
+    }
+
+    /**
+     * Tente de poser la baseline pour les images qui ne l'ont pas encore.
+     * @return true si TOUTES les images ont leur baseline apres cet essai.
+     */
+    private boolean tryBaselineMissing() {
+        for (String image : images) {
+            if (baselineDigests.containsKey(image)) continue;
+            try {
+                String digest = fetchRemoteDigest(image);
+                if (digest != null) {
+                    baselineDigests.put(image, digest);
+                    log.debug("Baseline digest for {} = {}", image, digest);
+                }
+            } catch (Exception e) {
+                log.warn("Cannot baseline digest for {}: {}", image, e.getMessage());
+            }
+        }
+        return baselineDigests.size() == images.size();
+    }
+
+    /**
+     * Lance un thread daemon qui retente de poser les baselines manquantes
+     * avec backoff. Le thread s'arrete des que toutes les baselines sont
+     * posees, ou apres epuisement des backoffs (et alors {@link #check()}
+     * retournera UNKNOWN pour ces images jusqu'au prochain redemarrage).
+     */
+    private void startBaselineRetryThread() {
+        Thread t = new Thread(() -> {
+            for (long backoff : BASELINE_RETRY_BACKOFFS_MS) {
+                try {
+                    Thread.sleep(backoff);
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    return;
+                }
+                if (tryBaselineMissing()) {
+                    log.info("Baseline complete after retry");
+                    return;
+                }
+            }
+            log.warn("Baseline incomplete after all retries; check() will return UNKNOWN for missing images");
+        }, "update-baseline-retry");
+        t.setDaemon(true);
+        t.start();
+    }
+
+    public boolean isEnabled() {
+        return watchtowerToken != null && !watchtowerToken.isBlank() && !images.isEmpty();
+    }
+
+    public UpdateStatus check() {
+        if (!isEnabled()) {
+            return new UpdateStatus(false, false, false, List.of(), Instant.now());
+        }
+        List<ImageStatus> statuses = new ArrayList<>();
+        boolean anyUpdate = false;
+        boolean anyUnknown = false;
+        for (String image : images) {
+            String baseline = baselineDigests.get(image);
+            String remote = null;
+            try {
+                remote = fetchRemoteDigest(image);
+            } catch (Exception e) {
+                log.warn("Check failed for {}: {}", image, e.getMessage());
+            }
+            // PAS d'alignement lazy si baseline absente : ce serait un faux negatif
+            // silencieux. On reporte UNKNOWN pour que l'UI le signale.
+            ImageStatusKind kind;
+            if (baseline == null || remote == null) {
+                kind = ImageStatusKind.UNKNOWN;
+                anyUnknown = true;
+            } else if (baseline.equals(remote)) {
+                kind = ImageStatusKind.UP_TO_DATE;
+            } else {
+                kind = ImageStatusKind.UPDATE_AVAILABLE;
+                anyUpdate = true;
+            }
+            statuses.add(new ImageStatus(image, baseline, remote, kind));
+        }
+        return new UpdateStatus(true, anyUpdate, anyUnknown, statuses, Instant.now());
+    }
+
+    public void apply() {
+        if (!isEnabled()) {
+            throw new IllegalStateException("Update apply not configured (WATCHTOWER_TOKEN missing)");
+        }
+        HttpHeaders headers = new HttpHeaders();
+        headers.setBearerAuth(watchtowerToken);
+        // Watchtower /v1/update declenche un scan+update immediat de tous les
+        // conteneurs labellises. La reponse est synchrone et peut prendre
+        // plusieurs secondes; en cas de redemarrage de core, le client
+        // recevra une connexion coupee — c'est attendu, l'UI le gere.
+        http.exchange(
+                watchtowerUrl + "/v1/update",
+                HttpMethod.POST,
+                new HttpEntity<>(headers),
+                Void.class);
+    }
+
+    // -----------------------------------------------------------------------
+    // Registry HTTP API v2
+    // -----------------------------------------------------------------------
+
+    private String fetchRemoteDigest(String image) {
+        String url = registry + "/v2/" + image + "/manifests/" + tag;
+        HttpHeaders headers = new HttpHeaders();
+        headers.setAccept(MANIFEST_ACCEPT);
+        try {
+            return digestCall(url, headers);
+        } catch (HttpClientErrorException.Unauthorized e) {
+            String www = e.getResponseHeaders() == null ? null
+                    : e.getResponseHeaders().getFirst(HttpHeaders.WWW_AUTHENTICATE);
+            String token = obtainBearerToken(www);
+            if (token == null) {
+                log.warn("Cannot obtain bearer token for {} (registry response: {})", image, www);
+                return null;
+            }
+            headers.setBearerAuth(token);
+            return digestCall(url, headers);
+        }
+    }
+
+    private String digestCall(String url, HttpHeaders headers) {
+        ResponseEntity<Void> resp = http.exchange(
+                url, HttpMethod.HEAD, new HttpEntity<>(headers), Void.class);
+        return resp.getHeaders().getFirst("Docker-Content-Digest");
+    }
+
+    /**
+     * Suit le challenge {@code WWW-Authenticate: Bearer realm="...",service="...",scope="..."}
+     * pour obtenir un jeton (anonyme — suffisant pour les images publiques).
+     */
+    @SuppressWarnings("rawtypes")
+    private String obtainBearerToken(String wwwAuth) {
+        if (wwwAuth == null) return null;
+        String prefix = "Bearer ";
+        if (!wwwAuth.regionMatches(true, 0, prefix, 0, prefix.length())) return null;
+        Map<String, String> params = parseAuthParams(wwwAuth.substring(prefix.length()));
+        String realm = params.get("realm");
+        if (realm == null) return null;
+        StringBuilder url = new StringBuilder(realm);
+        boolean hasQuery = realm.contains("?");
+        for (String key : new String[]{"service", "scope"}) {
+            String v = params.get(key);
+            if (v != null) {
+                // URLEncoder fait du "form encoding" qui transforme `:` et `/`
+                // en %3A et %2F. La plupart des registries (Docker Hub, Gitea)
+                // acceptent les deux, mais GHCR est strict et rejette le scope
+                // encode (403 DENIED). On preserve donc `:` et `/` dans la
+                // valeur, conformement a ce que GHCR attend
+                // (et que docker pull lui-meme envoie).
+                String encoded = URLEncoder.encode(v, StandardCharsets.UTF_8)
+                        .replace("%3A", ":")
+                        .replace("%2F", "/");
+                url.append(hasQuery ? '&' : '?')
+                   .append(key).append('=')
+                   .append(encoded);
+                hasQuery = true;
+            }
+        }
+        try {
+            ResponseEntity<Map> resp = http.getForEntity(url.toString(), Map.class);
+            Map<?, ?> body = resp.getBody();
+            if (body == null) return null;
+            Object t = body.get("token");
+            if (t == null) t = body.get("access_token");
+            return t == null ? null : t.toString();
+        } catch (Exception e) {
+            log.warn("Bearer token request failed: {}", e.getMessage());
+            return null;
+        }
+    }
+
+    /** Parser minimaliste pour {@code key="value", key2="value2"}. */
+    private static Map<String, String> parseAuthParams(String s) {
+        Map<String, String> out = new HashMap<>();
+        int i = 0;
+        int n = s.length();
+        while (i < n) {
+            while (i < n && (s.charAt(i) == ',' || s.charAt(i) == ' ')) i++;
+            int eq = s.indexOf('=', i);
+            if (eq < 0) break;
+            String key = s.substring(i, eq).trim();
+            int valStart = eq + 1;
+            String val;
+            if (valStart < n && s.charAt(valStart) == '"') {
+                int valEnd = s.indexOf('"', valStart + 1);
+                if (valEnd < 0) break;
+                val = s.substring(valStart + 1, valEnd);
+                i = valEnd + 1;
+            } else {
+                int valEnd = s.indexOf(',', valStart);
+                if (valEnd < 0) valEnd = n;
+                val = s.substring(valStart, valEnd).trim();
+                i = valEnd;
+            }
+            out.put(key, val);
+        }
+        return out;
+    }
+
+    private static String normalizeRegistry(String value) {
+        if (value == null || value.isBlank()) return "";
+        String v = value.trim();
+        if (!v.startsWith("http://") && !v.startsWith("https://")) {
+            v = "https://" + v;
+        }
+        if (v.endsWith("/")) v = v.substring(0, v.length() - 1);
+        return v;
+    }
+
+    private static List<String> parseImages(String csv) {
+        if (csv == null || csv.isBlank()) return List.of();
+        List<String> out = new ArrayList<>();
+        for (String part : csv.split(",")) {
+            String p = part.trim();
+            if (!p.isEmpty()) out.add(p);
+        }
+        return out;
+    }
+
+    // -----------------------------------------------------------------------
+    // Records de retour (sortis sous forme JSON par Jackson)
+    // -----------------------------------------------------------------------
+
+    /**
+     * Etat tri-state d'une image vis-a-vis du registry.
+     * <ul>
+     *   <li>{@link #UP_TO_DATE} : digest local == digest remote.</li>
+     *   <li>{@link #UPDATE_AVAILABLE} : digests differents, MAJ disponible.</li>
+     *   <li>{@link #UNKNOWN} : impossible de comparer (baseline ou remote manquant).
+     *       L'UI doit afficher un avertissement plutot que de declarer "a jour".</li>
+     * </ul>
+     */
+    public enum ImageStatusKind { UP_TO_DATE, UPDATE_AVAILABLE, UNKNOWN }
+
+    public record UpdateStatus(
+            boolean enabled,
+            boolean updateAvailable,
+            boolean anyUnknown,
+            List<ImageStatus> images,
+            Instant checkedAt) {}
+
+    /**
+     * Le champ {@code updateAvailable} est conserve pour la compatibilite
+     * avec les anciens clients ; il est strictement derive de {@code status}
+     * dans le constructeur compact.
+     */
+    public record ImageStatus(
+            String image,
+            String localDigest,
+            String remoteDigest,
+            ImageStatusKind status,
+            boolean updateAvailable) {
+
+        public ImageStatus(String image, String localDigest, String remoteDigest, ImageStatusKind status) {
+            this(image, localDigest, remoteDigest, status, status == ImageStatusKind.UPDATE_AVAILABLE);
+        }
+    }
+}

core/src/main/java/com/loremind/infrastructure/web/config/SecurityConfig.java

@@ -66,6 +66,7 @@ public class SecurityConfig {
                 // Preflight CORS toujours libre (le browser n'envoie pas Authorization sur OPTIONS)
                 .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
                 .requestMatchers("/api/settings/**").hasRole("ADMIN")
+                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                 .anyRequest().permitAll()
             )
             .httpBasic(basic -> {});

core/src/main/java/com/loremind/infrastructure/web/controller/ArcController.java

@@ -28,7 +28,7 @@ public class ArcController {
     @PostMapping
     public ResponseEntity<ArcDTO> createArc(@RequestBody ArcDTO arcDTO) {
         Arc arc = arcMapper.toDomain(arcDTO);
-        Arc createdArc = arcService.createArc(arc.getName(), arc.getDescription(), arc.getCampaignId(), arc.getOrder());
+        Arc createdArc = arcService.createArc(arc.getName(), arc.getDescription(), arc.getCampaignId(), arc.getOrder(), arc.getIcon());
         return ResponseEntity.ok(arcMapper.toDTO(createdArc));
     }
 
@@ -40,17 +40,11 @@ public class ArcController {
     }
 
     @GetMapping
-    public ResponseEntity<List<ArcDTO>> getAllArcs() {
-        List<Arc> arcs = arcService.getAllArcs();
-        List<ArcDTO> arcDTOs = arcs.stream()
-                .map(arcMapper::toDTO)
-                .collect(Collectors.toList());
-        return ResponseEntity.ok(arcDTOs);
-    }
-
-    @GetMapping("/campaign/{campaignId}")
-    public ResponseEntity<List<ArcDTO>> getArcsByCampaignId(@PathVariable String campaignId) {
-        List<Arc> arcs = arcService.getArcsByCampaignId(campaignId);
+    public ResponseEntity<List<ArcDTO>> getAllArcs(
+            @RequestParam(value = "campaignId", required = false) String campaignId) {
+        List<Arc> arcs = (campaignId != null && !campaignId.isBlank())
+                ? arcService.getArcsByCampaignId(campaignId)
+                : arcService.getAllArcs();
         List<ArcDTO> arcDTOs = arcs.stream()
                 .map(arcMapper::toDTO)
                 .collect(Collectors.toList());

core/src/main/java/com/loremind/infrastructure/web/controller/ChapterController.java

@@ -28,7 +28,7 @@ public class ChapterController {
     @PostMapping
     public ResponseEntity<ChapterDTO> createChapter(@RequestBody ChapterDTO chapterDTO) {
         Chapter chapter = chapterMapper.toDomain(chapterDTO);
-        Chapter createdChapter = chapterService.createChapter(chapter.getName(), chapter.getDescription(), chapter.getArcId(), chapter.getOrder());
+        Chapter createdChapter = chapterService.createChapter(chapter.getName(), chapter.getDescription(), chapter.getArcId(), chapter.getOrder(), chapter.getIcon());
         return ResponseEntity.ok(chapterMapper.toDTO(createdChapter));
     }
 
@@ -40,17 +40,11 @@ public class ChapterController {
     }
 
     @GetMapping
-    public ResponseEntity<List<ChapterDTO>> getAllChapters() {
-        List<Chapter> chapters = chapterService.getAllChapters();
-        List<ChapterDTO> chapterDTOs = chapters.stream()
-                .map(chapterMapper::toDTO)
-                .collect(Collectors.toList());
-        return ResponseEntity.ok(chapterDTOs);
-    }
-
-    @GetMapping("/arc/{arcId}")
-    public ResponseEntity<List<ChapterDTO>> getChaptersByArcId(@PathVariable String arcId) {
-        List<Chapter> chapters = chapterService.getChaptersByArcId(arcId);
+    public ResponseEntity<List<ChapterDTO>> getAllChapters(
+            @RequestParam(value = "arcId", required = false) String arcId) {
+        List<Chapter> chapters = (arcId != null && !arcId.isBlank())
+                ? chapterService.getChaptersByArcId(arcId)
+                : chapterService.getAllChapters();
         List<ChapterDTO> chapterDTOs = chapters.stream()
                 .map(chapterMapper::toDTO)
                 .collect(Collectors.toList());

core/src/main/java/com/loremind/infrastructure/web/controller/ConfigController.java

@@ -0,0 +1,36 @@
+package com.loremind.infrastructure.web.controller;
+
+import com.loremind.infrastructure.updates.UpdateCheckService;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.Map;
+
+/**
+ * Expose la configuration publique consommee par le frontend au demarrage.
+ * Activer le mode demo via la variable d'env DEMO_MODE=true : le front
+ * masque alors Settings / Export VTT, et les endpoints sensibles sont
+ * verrouilles cote serveur (cf. SettingsController).
+ */
+@RestController
+@RequestMapping("/api/config")
+public class ConfigController {
+
+    private final boolean demoMode;
+    private final UpdateCheckService updates;
+
+    public ConfigController(@Value("${app.demo-mode:false}") boolean demoMode,
+                            UpdateCheckService updates) {
+        this.demoMode = demoMode;
+        this.updates = updates;
+    }
+
+    @GetMapping
+    public Map<String, Object> getPublicConfig() {
+        return Map.of(
+                "demoMode", demoMode,
+                "updateCheckEnabled", updates.isEnabled());
+    }
+}

core/src/main/java/com/loremind/infrastructure/web/controller/NpcController.java

@@ -0,0 +1,62 @@
+package com.loremind.infrastructure.web.controller;
+
+import com.loremind.application.campaigncontext.NpcService;
+import com.loremind.domain.campaigncontext.Npc;
+import com.loremind.infrastructure.web.dto.campaigncontext.NpcDTO;
+import com.loremind.infrastructure.web.mapper.NpcMapper;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+@RestController
+@RequestMapping("/api/npcs")
+public class NpcController {
+
+    private final NpcService npcService;
+    private final NpcMapper npcMapper;
+
+    public NpcController(NpcService npcService, NpcMapper npcMapper) {
+        this.npcService = npcService;
+        this.npcMapper = npcMapper;
+    }
+
+    @PostMapping
+    public ResponseEntity<NpcDTO> createNpc(@RequestBody NpcDTO dto) {
+        Npc created = npcService.createNpc(
+                new NpcService.NpcData(dto.getName(), dto.getMarkdownContent(), dto.getCampaignId(), null)
+        );
+        return ResponseEntity.ok(npcMapper.toDTO(created));
+    }
+
+    @GetMapping("/{id}")
+    public ResponseEntity<NpcDTO> getNpcById(@PathVariable String id) {
+        return npcService.getNpcById(id)
+                .map(n -> ResponseEntity.ok(npcMapper.toDTO(n)))
+                .orElse(ResponseEntity.notFound().build());
+    }
+
+    @GetMapping("/campaign/{campaignId}")
+    public ResponseEntity<List<NpcDTO>> getNpcsByCampaign(@PathVariable String campaignId) {
+        List<NpcDTO> dtos = npcService.getNpcsByCampaignId(campaignId).stream()
+                .map(npcMapper::toDTO)
+                .collect(Collectors.toList());
+        return ResponseEntity.ok(dtos);
+    }
+
+    @PutMapping("/{id}")
+    public ResponseEntity<NpcDTO> updateNpc(@PathVariable String id, @RequestBody NpcDTO dto) {
+        Npc updated = npcService.updateNpc(
+                id,
+                new NpcService.NpcData(dto.getName(), dto.getMarkdownContent(), dto.getCampaignId(), dto.getOrder())
+        );
+        return ResponseEntity.ok(npcMapper.toDTO(updated));
+    }
+
+    @DeleteMapping("/{id}")
+    public ResponseEntity<Void> deleteNpc(@PathVariable String id) {
+        npcService.deleteNpc(id);
+        return ResponseEntity.noContent().build();
+    }
+}

core/src/main/java/com/loremind/infrastructure/web/controller/SceneController.java

@@ -28,7 +28,7 @@ public class SceneController {
     @PostMapping
     public ResponseEntity<SceneDTO> createScene(@RequestBody SceneDTO sceneDTO) {
         Scene scene = sceneMapper.toDomain(sceneDTO);
-        Scene createdScene = sceneService.createScene(scene.getName(), scene.getDescription(), scene.getChapterId(), scene.getOrder());
+        Scene createdScene = sceneService.createScene(scene.getName(), scene.getDescription(), scene.getChapterId(), scene.getOrder(), scene.getIcon());
         return ResponseEntity.ok(sceneMapper.toDTO(createdScene));
     }
 
@@ -40,17 +40,11 @@ public class SceneController {
     }
 
     @GetMapping
-    public ResponseEntity<List<SceneDTO>> getAllScenes() {
-        List<Scene> scenes = sceneService.getAllScenes();
-        List<SceneDTO> sceneDTOs = scenes.stream()
-                .map(sceneMapper::toDTO)
-                .collect(Collectors.toList());
-        return ResponseEntity.ok(sceneDTOs);
-    }
-
-    @GetMapping("/chapter/{chapterId}")
-    public ResponseEntity<List<SceneDTO>> getScenesByChapterId(@PathVariable String chapterId) {
-        List<Scene> scenes = sceneService.getScenesByChapterId(chapterId);
+    public ResponseEntity<List<SceneDTO>> getAllScenes(
+            @RequestParam(value = "chapterId", required = false) String chapterId) {
+        List<Scene> scenes = (chapterId != null && !chapterId.isBlank())
+                ? sceneService.getScenesByChapterId(chapterId)
+                : sceneService.getAllScenes();
         List<SceneDTO> sceneDTOs = scenes.stream()
                 .map(sceneMapper::toDTO)
                 .collect(Collectors.toList());

core/src/main/java/com/loremind/infrastructure/web/controller/SettingsController.java

@@ -4,16 +4,28 @@ import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.HttpEntity;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpMethod;
+import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.DeleteMapping;
 import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.client.RestTemplate;
+import org.springframework.web.server.ResponseStatusException;
+import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;
 
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.time.Duration;
 import java.util.Map;
 
 /**
@@ -32,20 +44,28 @@ public class SettingsController {
 
     private final RestTemplate restTemplate;
     private final String brainBaseUrl;
+    private final String brainInternalSecret;
+    private final boolean demoMode;
 
     public SettingsController(RestTemplate restTemplate,
-                              @Value("${brain.base-url}") String brainBaseUrl) {
+                              @Value("${brain.base-url}") String brainBaseUrl,
+                              @Value("${brain.internal-secret}") String brainInternalSecret,
+                              @Value("${app.demo-mode:false}") boolean demoMode) {
         this.restTemplate = restTemplate;
         this.brainBaseUrl = brainBaseUrl;
+        this.brainInternalSecret = brainInternalSecret;
+        this.demoMode = demoMode;
     }
 
     @GetMapping
     public ResponseEntity<Map<String, Object>> getSettings() {
+        guardDemoMode();
         return forward(HttpMethod.GET, "/settings", null);
     }
 
     @PutMapping
     public ResponseEntity<Map<String, Object>> updateSettings(@RequestBody Map<String, Object> patch) {
+        guardDemoMode();
         return forward(HttpMethod.PUT, "/settings", patch);
     }
 
@@ -59,11 +79,98 @@ public class SettingsController {
         return forward(HttpMethod.POST, "/models/ollama/info", body);
     }
 
+    /**
+     * Telecharge un modele Ollama et streame la progression au client.
+     * <p>
+     * On bypass RestTemplate (qui bufferise toute la reponse) au profit du
+     * client HTTP standard de Java en mode streaming. Le Brain renvoie du
+     * NDJSON ligne par ligne ; on relaie chaque chunk tel quel pour que le
+     * frontend voie la progression en temps reel.
+     */
+    @PostMapping(value = "/models/ollama/pull", produces = "application/x-ndjson")
+    public ResponseEntity<StreamingResponseBody> pullOllamaModel(@RequestBody Map<String, Object> body) {
+        guardDemoMode();
+        StreamingResponseBody stream = output -> {
+            // Force HTTP/1.1 : le HttpClient JDK essaie HTTP/2 par defaut,
+            // mais uvicorn (Brain) ne supporte que HTTP/1.1 et rejette la
+            // tentative d'upgrade ("Unsupported upgrade request") -> la
+            // requete n'arrive jamais a notre endpoint Python.
+            HttpClient http = HttpClient.newBuilder()
+                    .version(HttpClient.Version.HTTP_1_1)
+                    .connectTimeout(Duration.ofSeconds(10))
+                    .build();
+            // Le RestTemplate auto-injecte X-Internal-Secret via un interceptor,
+            // mais on bypass RestTemplate pour le streaming -> on doit ajouter
+            // l'entete a la main, sinon le Brain repond 401.
+            HttpRequest.Builder reqBuilder = HttpRequest.newBuilder()
+                    .uri(URI.create(brainBaseUrl + "/models/ollama/pull"))
+                    .timeout(Duration.ofMinutes(60))
+                    .header("Content-Type", "application/json")
+                    .POST(HttpRequest.BodyPublishers.ofString(toJson(body)));
+            if (brainInternalSecret != null && !brainInternalSecret.isBlank()) {
+                reqBuilder.header("X-Internal-Secret", brainInternalSecret);
+            }
+            HttpRequest req = reqBuilder.build();
+            try {
+                HttpResponse<InputStream> resp = http.send(req, HttpResponse.BodyHandlers.ofInputStream());
+                try (InputStream in = resp.body()) {
+                    byte[] buf = new byte[4096];
+                    int n;
+                    while ((n = in.read(buf)) != -1) {
+                        output.write(buf, 0, n);
+                        output.flush();
+                    }
+                }
+            } catch (InterruptedException ie) {
+                Thread.currentThread().interrupt();
+                throw new IOException("Pull interrompu", ie);
+            }
+        };
+        return ResponseEntity.ok().contentType(MediaType.parseMediaType("application/x-ndjson")).body(stream);
+    }
+
+    @DeleteMapping("/models/ollama/{name}")
+    public ResponseEntity<Map<String, Object>> deleteOllamaModel(@PathVariable("name") String name) {
+        guardDemoMode();
+        return forward(HttpMethod.DELETE, "/models/ollama/" + name, null);
+    }
+
     @GetMapping("/models/onemin")
     public ResponseEntity<Map<String, Object>> listOneMinModels() {
         return forward(HttpMethod.GET, "/models/onemin", null);
     }
 
+    /**
+     * Serialiseur JSON minimal pour eviter d'instancier ObjectMapper a chaque
+     * appel. Suffisant pour notre cas d'usage : Map<String,Object> avec des
+     * String/Number/Boolean en valeur.
+     */
+    private static String toJson(Map<String, Object> m) {
+        StringBuilder sb = new StringBuilder("{");
+        boolean first = true;
+        for (Map.Entry<String, Object> e : m.entrySet()) {
+            if (!first) sb.append(",");
+            sb.append("\"").append(escape(e.getKey())).append("\":");
+            Object v = e.getValue();
+            if (v == null) sb.append("null");
+            else if (v instanceof Number || v instanceof Boolean) sb.append(v);
+            else sb.append("\"").append(escape(v.toString())).append("\"");
+            first = false;
+        }
+        return sb.append("}").toString();
+    }
+
+    private static String escape(String s) {
+        return s.replace("\\", "\\\\").replace("\"", "\\\"")
+                .replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t");
+    }
+
+    private void guardDemoMode() {
+        if (demoMode) {
+            throw new ResponseStatusException(HttpStatus.FORBIDDEN, "Settings disabled in demo mode");
+        }
+    }
+
     @SuppressWarnings({"rawtypes", "unchecked"})
     private ResponseEntity<Map<String, Object>> forward(HttpMethod method, String path, Object body) {
         HttpHeaders headers = new HttpHeaders();

core/src/main/java/com/loremind/infrastructure/web/controller/UpdatesController.java

@@ -0,0 +1,76 @@
+package com.loremind.infrastructure.web.controller;
+
+import com.loremind.infrastructure.updates.UpdateCheckService;
+import com.loremind.infrastructure.updates.UpdateCheckService.UpdateStatus;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.util.Map;
+
+/**
+ * Endpoints admin pour la verification et le declenchement des mises a jour
+ * des conteneurs LoreMind (core/brain/web).
+ *
+ * Protege par HTTP Basic via SecurityConfig (path /api/admin/**).
+ * Si la feature n'est pas configuree (WATCHTOWER_TOKEN vide), check renvoie
+ * {enabled:false} et apply repond 503.
+ */
+@RestController
+@RequestMapping("/api/admin/updates")
+public class UpdatesController {
+
+    private static final Logger log = LoggerFactory.getLogger(UpdatesController.class);
+
+    private final UpdateCheckService updates;
+    private final boolean demoMode;
+
+    public UpdatesController(UpdateCheckService updates,
+                             @Value("${app.demo-mode:false}") boolean demoMode) {
+        this.updates = updates;
+        this.demoMode = demoMode;
+    }
+
+    @GetMapping("/check")
+    public UpdateStatus check() {
+        guardDemoMode();
+        return updates.check();
+    }
+
+    @PostMapping("/apply")
+    public ResponseEntity<Map<String, Object>> apply() {
+        guardDemoMode();
+        if (!updates.isEnabled()) {
+            return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
+                    .body(Map.of("error", "Update apply not configured"));
+        }
+        try {
+            updates.apply();
+            return ResponseEntity.accepted()
+                    .body(Map.of("status", "triggered",
+                                 "message", "Watchtower va telecharger et redemarrer les conteneurs."));
+        } catch (Exception e) {
+            log.error("Apply update failed", e);
+            return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
+                    .body(Map.of("error", "Watchtower unreachable: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * En mode demo, les instances ne doivent pas se mettre a jour ni meme
+     * exposer leur statut (pas de surface d'attaque, et pas de redemarrage
+     * intempestif d'une demo en cours). Cohérent avec SettingsController.
+     */
+    private void guardDemoMode() {
+        if (demoMode) {
+            throw new ResponseStatusException(HttpStatus.FORBIDDEN, "Updates disabled in demo mode");
+        }
+    }
+}

core/src/main/java/com/loremind/infrastructure/web/dto/campaigncontext/ArcDTO.java

@@ -17,6 +17,9 @@ public class ArcDTO {
     private String campaignId;
     private int order;
 
+    /** Cle d'icone (cf. CAMPAIGN_ICON_OPTIONS cote front). */
+    private String icon;
+
     // Champs narratifs enrichis
     private String themes;
     private String stakes;

core/src/main/java/com/loremind/infrastructure/web/dto/campaigncontext/ChapterDTO.java

@@ -17,6 +17,9 @@ public class ChapterDTO {
     private String arcId;
     private int order;
 
+    /** Cle d'icone (cf. CAMPAIGN_ICON_OPTIONS cote front). */
+    private String icon;
+
     // Champs narratifs enrichis
     private String gmNotes;
     private String playerObjectives;

core/src/main/java/com/loremind/infrastructure/web/dto/campaigncontext/NpcDTO.java

@@ -0,0 +1,16 @@
+package com.loremind.infrastructure.web.dto.campaigncontext;
+
+import lombok.Data;
+
+/**
+ * DTO pour les fiches de PNJ d'une campagne.
+ */
+@Data
+public class NpcDTO {
+
+    private String id;
+    private String name;
+    private String markdownContent;
+    private String campaignId;
+    private int order;
+}

core/src/main/java/com/loremind/infrastructure/web/dto/campaigncontext/SceneDTO.java

@@ -17,6 +17,9 @@ public class SceneDTO {
     private String chapterId;
     private int order;
 
+    /** Cle d'icone (cf. CAMPAIGN_ICON_OPTIONS cote front). */
+    private String icon;
+
     // Champs narratifs enrichis
     private String location;
     private String timing;

core/src/main/java/com/loremind/infrastructure/web/mapper/ArcMapper.java

@@ -24,6 +24,7 @@ public class ArcMapper {
         dto.setDescription(arc.getDescription());
         dto.setCampaignId(arc.getCampaignId());
         dto.setOrder(arc.getOrder());
+        dto.setIcon(arc.getIcon());
         dto.setThemes(arc.getThemes());
         dto.setStakes(arc.getStakes());
         dto.setGmNotes(arc.getGmNotes());
@@ -46,6 +47,7 @@ public class ArcMapper {
                 .description(dto.getDescription())
                 .campaignId(dto.getCampaignId())
                 .order(dto.getOrder())
+                .icon(dto.getIcon())
                 .themes(dto.getThemes())
                 .stakes(dto.getStakes())
                 .gmNotes(dto.getGmNotes())

core/src/main/java/com/loremind/infrastructure/web/mapper/ChapterMapper.java

@@ -24,6 +24,7 @@ public class ChapterMapper {
         dto.setDescription(chapter.getDescription());
         dto.setArcId(chapter.getArcId());
         dto.setOrder(chapter.getOrder());
+        dto.setIcon(chapter.getIcon());
         dto.setGmNotes(chapter.getGmNotes());
         dto.setPlayerObjectives(chapter.getPlayerObjectives());
         dto.setNarrativeStakes(chapter.getNarrativeStakes());
@@ -44,6 +45,7 @@ public class ChapterMapper {
                 .description(dto.getDescription())
                 .arcId(dto.getArcId())
                 .order(dto.getOrder())
+                .icon(dto.getIcon())
                 .gmNotes(dto.getGmNotes())
                 .playerObjectives(dto.getPlayerObjectives())
                 .narrativeStakes(dto.getNarrativeStakes())

core/src/main/java/com/loremind/infrastructure/web/mapper/NpcMapper.java

@@ -0,0 +1,31 @@
+package com.loremind.infrastructure.web.mapper;
+
+import com.loremind.domain.campaigncontext.Npc;
+import com.loremind.infrastructure.web.dto.campaigncontext.NpcDTO;
+import org.springframework.stereotype.Component;
+
+@Component
+public class NpcMapper {
+
+    public NpcDTO toDTO(Npc n) {
+        if (n == null) return null;
+        NpcDTO dto = new NpcDTO();
+        dto.setId(n.getId());
+        dto.setName(n.getName());
+        dto.setMarkdownContent(n.getMarkdownContent());
+        dto.setCampaignId(n.getCampaignId());
+        dto.setOrder(n.getOrder());
+        return dto;
+    }
+
+    public Npc toDomain(NpcDTO dto) {
+        if (dto == null) return null;
+        return Npc.builder()
+                .id(dto.getId())
+                .name(dto.getName())
+                .markdownContent(dto.getMarkdownContent())
+                .campaignId(dto.getCampaignId())
+                .order(dto.getOrder())
+                .build();
+    }
+}

core/src/main/java/com/loremind/infrastructure/web/mapper/SceneMapper.java

@@ -27,6 +27,7 @@ public class SceneMapper {
         dto.setDescription(scene.getDescription());
         dto.setChapterId(scene.getChapterId());
         dto.setOrder(scene.getOrder());
+        dto.setIcon(scene.getIcon());
         dto.setLocation(scene.getLocation());
         dto.setTiming(scene.getTiming());
         dto.setAtmosphere(scene.getAtmosphere());
@@ -59,6 +60,7 @@ public class SceneMapper {
                 .description(dto.getDescription())
                 .chapterId(dto.getChapterId())
                 .order(dto.getOrder())
+                .icon(dto.getIcon())
                 .location(dto.getLocation())
                 .timing(dto.getTiming())
                 .atmosphere(dto.getAtmosphere())
@@ -85,18 +87,14 @@ public class SceneMapper {
     private List<SceneBranchDTO> toBranchDTOs(List<SceneBranch> branches) {
         if (branches == null) return new ArrayList<>();
         return branches.stream()
-                .map(b -> new SceneBranchDTO(b.getLabel(), b.getTargetSceneId(), b.getCondition()))
+                .map(b -> new SceneBranchDTO(b.label(), b.targetSceneId(), b.condition()))
                 .collect(Collectors.toList());
     }
 
     private List<SceneBranch> toBranchDomain(List<SceneBranchDTO> dtos) {
         if (dtos == null) return new ArrayList<>();
         return dtos.stream()
-                .map(d -> SceneBranch.builder()
-                        .label(d.getLabel())
-                        .targetSceneId(d.getTargetSceneId())
-                        .condition(d.getCondition())
-                        .build())
+                .map(d -> new SceneBranch(d.getLabel(), d.getTargetSceneId(), d.getCondition()))
                 .collect(Collectors.toList());
     }
 }

core/src/main/resources/application.properties

@@ -5,6 +5,12 @@ server.port=8080
 # de WebFlux (utilisé uniquement pour WebClient côté adapter SSE vers le Brain).
 spring.main.web-application-type=servlet
 
+# Pas de timeout sur les requetes async (StreamingResponseBody, SSE).
+# Le defaut Tomcat coupe a 30s, ce qui interrompt le streaming d'un pull
+# de modele Ollama (peut durer des dizaines de minutes pour un GGUF de 10+ Go).
+# -1 = pas de timeout, on s'appuie sur la fermeture cote client ou cote upstream.
+spring.mvc.async.request-timeout=-1
+
 # Configuration de la base de donnees PostgreSQL
 # Valeurs surchargeables via variables d'env (cf. docker-compose.yml).
 # En dev local, creez un fichier .env a la racine de core/ OU definissez les
@@ -21,13 +27,13 @@ spring.jpa.show-sql=true
 spring.jpa.properties.hibernate.format_sql=true
 
 # Configuration CORS pour autoriser le Frontend Angular
-spring.web.cors.allowed-origins=http://localhost:4200
+spring.web.cors.allowed-origins=${CORS_ALLOWED_ORIGINS:http://localhost:4200}
 spring.web.cors.allowed-methods=GET,POST,PUT,DELETE,OPTIONS
 spring.web.cors.allowed-headers=*
 spring.web.cors.allow-credentials=true
 
 # Configuration du Brain (service IA Python)
-brain.base-url=http://localhost:8000
+brain.base-url=${BRAIN_BASE_URL:http://localhost:8000}
 brain.timeout-seconds=120
 
 # Secret partage Core <-> Brain (auth inter-service via entete X-Internal-Secret).
@@ -50,3 +56,15 @@ minio.bucket=${MINIO_BUCKET:loremind-images}
 # Limites d'upload d'images (MB)
 spring.servlet.multipart.max-file-size=10MB
 spring.servlet.multipart.max-request-size=10MB
+
+# Mode demo : masque Settings/Export cote front et bloque les PUT /api/settings
+# cote serveur. Activer via DEMO_MODE=true sur les deploiements publics.
+app.demo-mode=${DEMO_MODE:false}
+
+# Detection des mises a jour des conteneurs Docker (registry HTTP API + Watchtower).
+# Feature desactivee si UPDATE_CHECK_WATCHTOWER_TOKEN est vide.
+update-check.registry=${UPDATE_CHECK_REGISTRY:}
+update-check.images=${UPDATE_CHECK_IMAGES:}
+update-check.tag=${UPDATE_CHECK_TAG:latest}
+update-check.watchtower-url=${WATCHTOWER_URL:http://watchtower:8080}
+update-check.watchtower-token=${WATCHTOWER_TOKEN:}

core/src/test/java/com/loremind/application/campaigncontext/NpcServiceTest.java

@@ -0,0 +1,159 @@
+package com.loremind.application.campaigncontext;
+
+import com.loremind.domain.campaigncontext.Npc;
+import com.loremind.domain.campaigncontext.ports.NpcRepository;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import java.util.List;
+import java.util.Optional;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.*;
+
+/**
+ * Test unitaire pour NpcService.
+ * Couvre la création (avec auto-calcul de l'order), la lecture, la mise à jour
+ * (incl. cas non trouvé), la suppression, et le calcul d'order.
+ */
+@ExtendWith(MockitoExtension.class)
+public class NpcServiceTest {
+
+    @Mock
+    private NpcRepository npcRepository;
+
+    @InjectMocks
+    private NpcService npcService;
+
+    private Npc testNpc;
+
+    @BeforeEach
+    void setUp() {
+        testNpc = Npc.builder()
+                .id("npc-1")
+                .name("Borin le forgeron")
+                .markdownContent("# Borin\nForgeron nain")
+                .campaignId("camp-1")
+                .order(1)
+                .build();
+    }
+
+    @Test
+    void testCreateNpc_WithExplicitOrder() {
+        when(npcRepository.save(any(Npc.class))).thenReturn(testNpc);
+
+        Npc result = npcService.createNpc(
+                new NpcService.NpcData("Borin le forgeron", "# Borin", "camp-1", 5));
+
+        assertNotNull(result);
+        ArgumentCaptor<Npc> captor = ArgumentCaptor.forClass(Npc.class);
+        verify(npcRepository).save(captor.capture());
+        assertEquals(5, captor.getValue().getOrder());
+    }
+
+    @Test
+    void testCreateNpc_AutoComputesNextOrder_WhenNullProvided() {
+        // Existant : 2 PNJ avec orders 0 et 3 → next = 4
+        Npc a = Npc.builder().id("a").campaignId("camp-1").order(0).build();
+        Npc b = Npc.builder().id("b").campaignId("camp-1").order(3).build();
+        when(npcRepository.findByCampaignId("camp-1")).thenReturn(List.of(a, b));
+        when(npcRepository.save(any(Npc.class))).thenReturn(testNpc);
+
+        npcService.createNpc(new NpcService.NpcData("Nouveau", null, "camp-1", null));
+
+        ArgumentCaptor<Npc> captor = ArgumentCaptor.forClass(Npc.class);
+        verify(npcRepository).save(captor.capture());
+        assertEquals(4, captor.getValue().getOrder());
+    }
+
+    @Test
+    void testCreateNpc_FirstNpcGetsOrderZero() {
+        when(npcRepository.findByCampaignId("camp-1")).thenReturn(List.of());
+        when(npcRepository.save(any(Npc.class))).thenReturn(testNpc);
+
+        npcService.createNpc(new NpcService.NpcData("Premier", null, "camp-1", null));
+
+        ArgumentCaptor<Npc> captor = ArgumentCaptor.forClass(Npc.class);
+        verify(npcRepository).save(captor.capture());
+        assertEquals(0, captor.getValue().getOrder());
+    }
+
+    @Test
+    void testGetNpcById_Found() {
+        when(npcRepository.findById("npc-1")).thenReturn(Optional.of(testNpc));
+
+        Optional<Npc> result = npcService.getNpcById("npc-1");
+
+        assertTrue(result.isPresent());
+        assertEquals("Borin le forgeron", result.get().getName());
+    }
+
+    @Test
+    void testGetNpcById_NotFound() {
+        when(npcRepository.findById("missing")).thenReturn(Optional.empty());
+
+        Optional<Npc> result = npcService.getNpcById("missing");
+
+        assertFalse(result.isPresent());
+    }
+
+    @Test
+    void testGetNpcsByCampaignId_DelegatesToRepository() {
+        Npc a = Npc.builder().id("a").campaignId("camp-1").order(1).build();
+        Npc b = Npc.builder().id("b").campaignId("camp-1").order(2).build();
+        when(npcRepository.findByCampaignId("camp-1")).thenReturn(List.of(a, b));
+
+        List<Npc> result = npcService.getNpcsByCampaignId("camp-1");
+
+        assertEquals(2, result.size());
+        verify(npcRepository).findByCampaignId("camp-1");
+    }
+
+    @Test
+    void testUpdateNpc_Success() {
+        when(npcRepository.findById("npc-1")).thenReturn(Optional.of(testNpc));
+        when(npcRepository.save(any(Npc.class))).thenAnswer(inv -> inv.getArgument(0));
+
+        Npc result = npcService.updateNpc("npc-1",
+                new NpcService.NpcData("Borin renommé", "# v2", "camp-1", 7));
+
+        assertEquals("Borin renommé", result.getName());
+        assertEquals("# v2", result.getMarkdownContent());
+        assertEquals(7, result.getOrder());
+    }
+
+    @Test
+    void testUpdateNpc_OrderNullPreservesExistingOrder() {
+        when(npcRepository.findById("npc-1")).thenReturn(Optional.of(testNpc));
+        when(npcRepository.save(any(Npc.class))).thenAnswer(inv -> inv.getArgument(0));
+
+        Npc result = npcService.updateNpc("npc-1",
+                new NpcService.NpcData("Borin", "# txt", "camp-1", null));
+
+        // testNpc avait order=1 → préservé
+        assertEquals(1, result.getOrder());
+    }
+
+    @Test
+    void testUpdateNpc_NotFoundThrows() {
+        when(npcRepository.findById("missing")).thenReturn(Optional.empty());
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> npcService.updateNpc("missing",
+                        new NpcService.NpcData("x", null, "camp-1", null)));
+        assertTrue(ex.getMessage().contains("missing"));
+        verify(npcRepository, never()).save(any());
+    }
+
+    @Test
+    void testDeleteNpc_DelegatesToRepository() {
+        npcService.deleteNpc("npc-1");
+        verify(npcRepository).deleteById("npc-1");
+    }
+}

core/src/test/java/com/loremind/application/campaigncontext/SceneServiceTest.java

@@ -178,10 +178,7 @@ public class SceneServiceTest {
     @Test
     void testUpdateScene_WithValidBranches() {
         // Arrange
-        SceneBranch branch = SceneBranch.builder()
-                .targetSceneId("scene-2")
-                .label("Go to scene 2")
-                .build();
+        SceneBranch branch = SceneBranch.of("Go to scene 2", "scene-2");
         Scene updatedScene = Scene.builder()
                 .name("Updated Scene")
                 .branches(List.of(branch))
@@ -203,10 +200,7 @@ public class SceneServiceTest {
     @Test
     void testUpdateScene_WithBranchToSelf() {
         // Arrange
-        SceneBranch branch = SceneBranch.builder()
-                .targetSceneId("scene-1")
-                .label("Self-reference")
-                .build();
+        SceneBranch branch = SceneBranch.of("Self-reference", "scene-1");
         Scene updatedScene = Scene.builder()
                 .name("Updated Scene")
                 .branches(List.of(branch))
@@ -228,10 +222,7 @@ public class SceneServiceTest {
     @Test
     void testUpdateScene_WithBranchToDifferentChapter() {
         // Arrange
-        SceneBranch branch = SceneBranch.builder()
-                .targetSceneId("scene-other-chapter")
-                .label("Go to other chapter")
-                .build();
+        SceneBranch branch = SceneBranch.of("Go to other chapter", "scene-other-chapter");
         Scene updatedScene = Scene.builder()
                 .name("Updated Scene")
                 .branches(List.of(branch))
@@ -253,10 +244,7 @@ public class SceneServiceTest {
     @Test
     void testUpdateScene_WithBranchNullTarget() {
         // Arrange
-        SceneBranch branch = SceneBranch.builder()
-                .targetSceneId(null)
-                .label("Null target")
-                .build();
+        SceneBranch branch = SceneBranch.of("Null target", null);
         Scene updatedScene = Scene.builder()
                 .name("Updated Scene")
                 .branches(List.of(branch))
@@ -277,10 +265,7 @@ public class SceneServiceTest {
     @Test
     void testUpdateScene_WithBranchBlankTarget() {
         // Arrange
-        SceneBranch branch = SceneBranch.builder()
-                .targetSceneId("   ")
-                .label("Blank target")
-                .build();
+        SceneBranch branch = SceneBranch.of("Blank target", "   ");
         Scene updatedScene = Scene.builder()
                 .name("Updated Scene")
                 .branches(List.of(branch))

core/src/test/java/com/loremind/application/generationcontext/CampaignStructuralContextBuilderTest.java

@@ -3,12 +3,15 @@ package com.loremind.application.generationcontext;
 import com.loremind.domain.campaigncontext.Arc;
 import com.loremind.domain.campaigncontext.Campaign;
 import com.loremind.domain.campaigncontext.Chapter;
+import com.loremind.domain.campaigncontext.Character;
+import com.loremind.domain.campaigncontext.Npc;
 import com.loremind.domain.campaigncontext.Scene;
 import com.loremind.domain.campaigncontext.SceneBranch;
 import com.loremind.domain.campaigncontext.ports.ArcRepository;
 import com.loremind.domain.campaigncontext.ports.CampaignRepository;
 import com.loremind.domain.campaigncontext.ports.ChapterRepository;
 import com.loremind.domain.campaigncontext.ports.CharacterRepository;
+import com.loremind.domain.campaigncontext.ports.NpcRepository;
 import com.loremind.domain.campaigncontext.ports.SceneRepository;
 import com.loremind.domain.generationcontext.CampaignStructuralContext;
 import org.junit.jupiter.api.BeforeEach;
@@ -43,6 +46,8 @@ public class CampaignStructuralContextBuilderTest {
     private SceneRepository sceneRepository;
     @Mock
     private CharacterRepository characterRepository;
+    @Mock
+    private NpcRepository npcRepository;
 
     @InjectMocks
     private CampaignStructuralContextBuilder builder;
@@ -74,9 +79,9 @@ public class CampaignStructuralContextBuilderTest {
 
         CampaignStructuralContext ctx = builder.build("camp-1");
 
-        assertEquals("Les Terres Brisées", ctx.getCampaignName());
-        assertEquals("Campagne dark fantasy", ctx.getCampaignDescription());
-        assertTrue(ctx.getArcs().isEmpty());
+        assertEquals("Les Terres Brisées", ctx.campaignName());
+        assertEquals("Campagne dark fantasy", ctx.campaignDescription());
+        assertTrue(ctx.arcs().isEmpty());
     }
 
     @Test
@@ -100,19 +105,19 @@ public class CampaignStructuralContextBuilderTest {
 
         CampaignStructuralContext ctx = builder.build("camp-1");
 
-        assertEquals(2, ctx.getArcs().size());
-        assertEquals("Arc A", ctx.getArcs().get(0).getName());
-        assertEquals("Arc B", ctx.getArcs().get(1).getName());
+        assertEquals(2, ctx.arcs().size());
+        assertEquals("Arc A", ctx.arcs().get(0).name());
+        assertEquals("Arc B", ctx.arcs().get(1).name());
 
         // Chapitres tries : ch2 (order 1) avant ch1 (order 2)
-        assertEquals(2, ctx.getArcs().get(0).getChapters().size());
-        assertEquals("Ch B", ctx.getArcs().get(0).getChapters().get(0).getName());
-        assertEquals("Ch A", ctx.getArcs().get(0).getChapters().get(1).getName());
+        assertEquals(2, ctx.arcs().get(0).chapters().size());
+        assertEquals("Ch B", ctx.arcs().get(0).chapters().get(0).name());
+        assertEquals("Ch A", ctx.arcs().get(0).chapters().get(1).name());
 
         // Scenes dans ch-1 : s2 (order 1) avant s1 (order 2)
-        var chADto = ctx.getArcs().get(0).getChapters().get(1);
-        assertEquals("Scene B", chADto.getScenes().get(0).getName());
-        assertEquals("Scene A", chADto.getScenes().get(1).getName());
+        var chADto = ctx.arcs().get(0).chapters().get(1);
+        assertEquals("Scene B", chADto.scenes().get(0).name());
+        assertEquals("Scene A", chADto.scenes().get(1).name());
     }
 
     @Test
@@ -120,15 +125,8 @@ public class CampaignStructuralContextBuilderTest {
         Arc arc = Arc.builder().id("arc-1").name("Arc").description("").order(1).build();
         Chapter ch = Chapter.builder().id("ch-1").arcId("arc-1").name("Ch").description("").order(1).build();
 
-        SceneBranch validBranch = SceneBranch.builder()
-                .label("Si les joueurs fuient")
-                .targetSceneId("s-2")
-                .condition("en cas de combat perdu")
-                .build();
-        SceneBranch danglingBranch = SceneBranch.builder()
-                .label("Vers l'inconnu")
-                .targetSceneId("s-inconnu")
-                .build();
+        SceneBranch validBranch = new SceneBranch("Si les joueurs fuient", "s-2", "en cas de combat perdu");
+        SceneBranch danglingBranch = SceneBranch.of("Vers l'inconnu", "s-inconnu");
 
         Scene s1 = Scene.builder().id("s-1").chapterId("ch-1").name("Entrée").description("")
                 .order(1)
@@ -143,12 +141,72 @@ public class CampaignStructuralContextBuilderTest {
 
         CampaignStructuralContext ctx = builder.build("camp-1");
 
-        var scene1Summary = ctx.getArcs().get(0).getChapters().get(0).getScenes().get(0);
-        assertEquals(2, scene1Summary.getBranches().size());
-        assertEquals("Fuite", scene1Summary.getBranches().get(0).getTargetSceneName());
-        assertEquals("en cas de combat perdu", scene1Summary.getBranches().get(0).getCondition());
+        var scene1Summary = ctx.arcs().get(0).chapters().get(0).scenes().get(0);
+        assertEquals(2, scene1Summary.branches().size());
+        assertEquals("Fuite", scene1Summary.branches().get(0).targetSceneName());
+        assertEquals("en cas de combat perdu", scene1Summary.branches().get(0).condition());
         // ID inconnu → libellé de fallback
-        assertEquals("(scène inconnue)", scene1Summary.getBranches().get(1).getTargetSceneName());
+        assertEquals("(scène inconnue)", scene1Summary.branches().get(1).targetSceneName());
+    }
+
+    @Test
+    void testBuild_ProjectsCharactersAndNpcsWithSnippets() {
+        Character pj1 = Character.builder().id("c-1").campaignId("camp-1").order(1)
+                .name("Aragorn")
+                .markdownContent("# Aragorn\n\nRôdeur du Nord, héritier d'Isildur.")
+                .build();
+        Character pj2 = Character.builder().id("c-2").campaignId("camp-1").order(2)
+                .name("Legolas")
+                .markdownContent(null) // pas de snippet → string vide
+                .build();
+        Npc npc1 = Npc.builder().id("n-1").campaignId("camp-1").order(2)
+                .name("Borin le forgeron")
+                .markdownContent("# Borin\n\nNain barbu au regard perçant, ancien clan Feuillefer.")
+                .build();
+        Npc npc2 = Npc.builder().id("n-2").campaignId("camp-1").order(1)
+                .name("Dame Elara")
+                .markdownContent("")
+                .build();
+
+        when(campaignRepository.findById("camp-1")).thenReturn(Optional.of(campaign));
+        when(arcRepository.findByCampaignId("camp-1")).thenReturn(List.of());
+        when(characterRepository.findByCampaignId("camp-1")).thenReturn(List.of(pj2, pj1));
+        when(npcRepository.findByCampaignId("camp-1")).thenReturn(List.of(npc1, npc2));
+
+        CampaignStructuralContext ctx = builder.build("camp-1");
+
+        // PJ triés par order croissant
+        assertEquals(2, ctx.characters().size());
+        assertEquals("Aragorn", ctx.characters().get(0).name());
+        assertEquals("Rôdeur du Nord, héritier d'Isildur.", ctx.characters().get(0).snippet());
+        assertEquals("Legolas", ctx.characters().get(1).name());
+        assertEquals("", ctx.characters().get(1).snippet());
+
+        // PNJ triés par order croissant : Elara (1) avant Borin (2)
+        assertEquals(2, ctx.npcs().size());
+        assertEquals("Dame Elara", ctx.npcs().get(0).name());
+        assertEquals("", ctx.npcs().get(0).snippet());
+        assertEquals("Borin le forgeron", ctx.npcs().get(1).name());
+        assertEquals("Nain barbu au regard perçant, ancien clan Feuillefer.",
+                ctx.npcs().get(1).snippet());
+    }
+
+    @Test
+    void testBuild_TruncatesLongSnippet() {
+        // Snippet > 160 chars : doit être tronqué à 159 + "…"
+        String longLine = "x".repeat(200);
+        Npc longNpc = Npc.builder().id("n-1").campaignId("camp-1").order(1)
+                .name("Verbeux").markdownContent(longLine).build();
+
+        when(campaignRepository.findById("camp-1")).thenReturn(Optional.of(campaign));
+        when(arcRepository.findByCampaignId("camp-1")).thenReturn(List.of());
+        when(npcRepository.findByCampaignId("camp-1")).thenReturn(List.of(longNpc));
+
+        CampaignStructuralContext ctx = builder.build("camp-1");
+
+        String snippet = ctx.npcs().get(0).snippet();
+        assertEquals(160, snippet.length());
+        assertTrue(snippet.endsWith("…"));
     }
 
     @Test
@@ -170,9 +228,9 @@ public class CampaignStructuralContextBuilderTest {
 
         CampaignStructuralContext ctx = builder.build("camp-1");
 
-        assertEquals(2, ctx.getArcs().get(0).getIllustrationCount());
-        assertEquals(0, ctx.getArcs().get(0).getChapters().get(0).getIllustrationCount());
-        assertEquals(1, ctx.getArcs().get(0).getChapters().get(0).getScenes().get(0).getIllustrationCount());
-        assertTrue(ctx.getArcs().get(0).getChapters().get(0).getScenes().get(0).getBranches().isEmpty());
+        assertEquals(2, ctx.arcs().get(0).illustrationCount());
+        assertEquals(0, ctx.arcs().get(0).chapters().get(0).illustrationCount());
+        assertEquals(1, ctx.arcs().get(0).chapters().get(0).scenes().get(0).illustrationCount());
+        assertTrue(ctx.arcs().get(0).chapters().get(0).scenes().get(0).branches().isEmpty());
     }
 }

core/src/test/java/com/loremind/application/generationcontext/GeneratePageValuesUseCaseTest.java

@@ -89,13 +89,13 @@ public class GeneratePageValuesUseCaseTest {
         verify(aiProvider).generatePage(captor.capture());
         GenerationContext ctx = captor.getValue();
 
-        assertEquals("Aetheria", ctx.getLoreName());
-        assertEquals("monde aérien", ctx.getLoreDescription());
-        assertEquals("PNJ", ctx.getFolderName());
-        assertEquals("Personnage", ctx.getTemplateName());
-        assertEquals("Alice", ctx.getPageTitle());
+        assertEquals("Aetheria", ctx.loreName());
+        assertEquals("monde aérien", ctx.loreDescription());
+        assertEquals("PNJ", ctx.folderName());
+        assertEquals("Personnage", ctx.templateName());
+        assertEquals("Alice", ctx.pageTitle());
         // Seuls les champs TEXT doivent etre envoyes (pas "Portrait" IMAGE).
-        assertEquals(List.of("Histoire", "Apparence"), ctx.getTemplateFields());
+        assertEquals(List.of("Histoire", "Apparence"), ctx.templateFields());
     }
 
     @Test

core/src/test/java/com/loremind/application/generationcontext/LoreStructuralContextBuilderTest.java

@@ -71,10 +71,10 @@ public class LoreStructuralContextBuilderTest {
 
         LoreStructuralContext ctx = builder.build("lore-1");
 
-        assertEquals("Aetheria", ctx.getLoreName());
-        assertEquals("Monde aérien", ctx.getLoreDescription());
-        assertTrue(ctx.getFolders().isEmpty());
-        assertTrue(ctx.getTags().isEmpty());
+        assertEquals("Aetheria", ctx.loreName());
+        assertEquals("Monde aérien", ctx.loreDescription());
+        assertTrue(ctx.folders().isEmpty());
+        assertTrue(ctx.tags().isEmpty());
     }
 
     @Test
@@ -110,32 +110,32 @@ public class LoreStructuralContextBuilderTest {
 
         LoreStructuralContext ctx = builder.build("lore-1");
 
-        assertEquals(2, ctx.getFolders().size());
-        assertTrue(ctx.getFolders().containsKey("PNJ"));
-        assertTrue(ctx.getFolders().containsKey("Lieux"));
+        assertEquals(2, ctx.folders().size());
+        assertTrue(ctx.folders().containsKey("PNJ"));
+        assertTrue(ctx.folders().containsKey("Lieux"));
 
-        var pnjPages = ctx.getFolders().get("PNJ");
+        var pnjPages = ctx.folders().get("PNJ");
         assertEquals(1, pnjPages.size());
         var aliceSummary = pnjPages.get(0);
-        assertEquals("Alice", aliceSummary.getTitle());
-        assertEquals("Personnage", aliceSummary.getTemplateName());
+        assertEquals("Alice", aliceSummary.title());
+        assertEquals("Personnage", aliceSummary.templateName());
         // Blank/null filtrés
-        assertEquals(1, aliceSummary.getValues().size());
-        assertEquals("Il était une fois...", aliceSummary.getValues().get("Histoire"));
-        assertEquals(List.of("hero", "magic"), aliceSummary.getTags());
+        assertEquals(1, aliceSummary.values().size());
+        assertEquals("Il était une fois...", aliceSummary.values().get("Histoire"));
+        assertEquals(List.of("hero", "magic"), aliceSummary.tags());
         // p-2 resolved into title, p-ghost dropped silently
-        assertEquals(List.of("La Forêt"), aliceSummary.getRelatedPageTitles());
+        assertEquals(List.of("La Forêt"), aliceSummary.relatedPageTitles());
 
-        var forestSummary = ctx.getFolders().get("Lieux").get(0);
+        var forestSummary = ctx.folders().get("Lieux").get(0);
         // Template introuvable → "?"
-        assertEquals("?", forestSummary.getTemplateName());
-        assertTrue(forestSummary.getValues().isEmpty());
-        assertTrue(forestSummary.getRelatedPageTitles().isEmpty());
+        assertEquals("?", forestSummary.templateName());
+        assertTrue(forestSummary.values().isEmpty());
+        assertTrue(forestSummary.relatedPageTitles().isEmpty());
 
         // Tags uniques entre les 2 pages
-        assertEquals(2, ctx.getTags().size());
-        assertTrue(ctx.getTags().contains("hero"));
-        assertTrue(ctx.getTags().contains("magic"));
+        assertEquals(2, ctx.tags().size());
+        assertTrue(ctx.tags().contains("hero"));
+        assertTrue(ctx.tags().contains("magic"));
     }
 
     @Test
@@ -160,7 +160,7 @@ public class LoreStructuralContextBuilderTest {
 
         LoreStructuralContext ctx = builder.build("lore-1");
 
-        String truncated = ctx.getFolders().get("PNJ").get(0).getValues().get("Histoire");
+        String truncated = ctx.folders().get("PNJ").get(0).values().get("Histoire");
         assertNotNull(truncated);
         assertEquals(500 + 1, truncated.length()); // 500 + ellipse
         assertTrue(truncated.endsWith("…"));
@@ -185,9 +185,9 @@ public class LoreStructuralContextBuilderTest {
 
         LoreStructuralContext ctx = builder.build("lore-1");
 
-        var summary = ctx.getFolders().get("PNJ").get(0);
-        assertTrue(summary.getValues().isEmpty());
-        assertTrue(summary.getTags().isEmpty());
-        assertTrue(summary.getRelatedPageTitles().isEmpty());
+        var summary = ctx.folders().get("PNJ").get(0);
+        assertTrue(summary.values().isEmpty());
+        assertTrue(summary.tags().isEmpty());
+        assertTrue(summary.relatedPageTitles().isEmpty());
     }
 }

core/src/test/java/com/loremind/application/generationcontext/NarrativeEntityContextBuilderTest.java

@@ -2,9 +2,13 @@ package com.loremind.application.generationcontext;
 
 import com.loremind.domain.campaigncontext.Arc;
 import com.loremind.domain.campaigncontext.Chapter;
+import com.loremind.domain.campaigncontext.Character;
+import com.loremind.domain.campaigncontext.Npc;
 import com.loremind.domain.campaigncontext.Scene;
 import com.loremind.domain.campaigncontext.ports.ArcRepository;
 import com.loremind.domain.campaigncontext.ports.ChapterRepository;
+import com.loremind.domain.campaigncontext.ports.CharacterRepository;
+import com.loremind.domain.campaigncontext.ports.NpcRepository;
 import com.loremind.domain.campaigncontext.ports.SceneRepository;
 import com.loremind.domain.generationcontext.NarrativeEntityContext;
 import org.junit.jupiter.api.Test;
@@ -30,6 +34,8 @@ public class NarrativeEntityContextBuilderTest {
     @Mock private ArcRepository arcRepository;
     @Mock private ChapterRepository chapterRepository;
     @Mock private SceneRepository sceneRepository;
+    @Mock private CharacterRepository characterRepository;
+    @Mock private NpcRepository npcRepository;
 
     @InjectMocks private NarrativeEntityContextBuilder builder;
 
@@ -44,14 +50,14 @@ public class NarrativeEntityContextBuilderTest {
 
         NarrativeEntityContext ctx = builder.build("arc", "arc-1");
 
-        assertEquals("arc", ctx.getEntityType());
-        assertEquals("L'arc sombre", ctx.getTitle());
-        assertEquals("synopsis", ctx.getFields().get("description (synopsis)"));
-        assertEquals("trahison", ctx.getFields().get("themes"));
-        assertEquals("vie ou mort", ctx.getFields().get("stakes"));
-        assertEquals("pouvoir", ctx.getFields().get("rewards"));
-        assertEquals("le roi meurt", ctx.getFields().get("resolution"));
-        assertEquals("secret", ctx.getFields().get("gmNotes"));
+        assertEquals("arc", ctx.entityType());
+        assertEquals("L'arc sombre", ctx.title());
+        assertEquals("synopsis", ctx.fields().get("description (synopsis)"));
+        assertEquals("trahison", ctx.fields().get("themes"));
+        assertEquals("vie ou mort", ctx.fields().get("stakes"));
+        assertEquals("pouvoir", ctx.fields().get("rewards"));
+        assertEquals("le roi meurt", ctx.fields().get("resolution"));
+        assertEquals("secret", ctx.fields().get("gmNotes"));
     }
 
     @Test
@@ -64,12 +70,12 @@ public class NarrativeEntityContextBuilderTest {
 
         NarrativeEntityContext ctx = builder.build("chapter", "ch-1");
 
-        assertEquals("chapter", ctx.getEntityType());
-        assertEquals("Chapitre 1", ctx.getTitle());
-        assertEquals("", ctx.getFields().get("description (synopsis)"));
-        assertEquals("", ctx.getFields().get("playerObjectives"));
-        assertEquals("haut", ctx.getFields().get("narrativeStakes"));
-        assertEquals("", ctx.getFields().get("gmNotes"));
+        assertEquals("chapter", ctx.entityType());
+        assertEquals("Chapitre 1", ctx.title());
+        assertEquals("", ctx.fields().get("description (synopsis)"));
+        assertEquals("", ctx.fields().get("playerObjectives"));
+        assertEquals("haut", ctx.fields().get("narrativeStakes"));
+        assertEquals("", ctx.fields().get("gmNotes"));
     }
 
     @Test
@@ -85,17 +91,17 @@ public class NarrativeEntityContextBuilderTest {
 
         NarrativeEntityContext ctx = builder.build("scene", "s-1");
 
-        assertEquals("scene", ctx.getEntityType());
-        assertEquals("L'auberge", ctx.getTitle());
-        assertEquals("lieu calme", ctx.getFields().get("description"));
-        assertEquals("Taverne", ctx.getFields().get("location"));
-        assertEquals("Soir", ctx.getFields().get("timing"));
-        assertEquals("tendue", ctx.getFields().get("atmosphere"));
-        assertEquals("Vous entrez...", ctx.getFields().get("playerNarration"));
-        assertEquals("option A...", ctx.getFields().get("choicesConsequences"));
-        assertEquals("moyen", ctx.getFields().get("combatDifficulty"));
-        assertEquals("3 bandits", ctx.getFields().get("enemies"));
-        assertEquals("trésor caché", ctx.getFields().get("gmSecretNotes"));
+        assertEquals("scene", ctx.entityType());
+        assertEquals("L'auberge", ctx.title());
+        assertEquals("lieu calme", ctx.fields().get("description"));
+        assertEquals("Taverne", ctx.fields().get("location"));
+        assertEquals("Soir", ctx.fields().get("timing"));
+        assertEquals("tendue", ctx.fields().get("atmosphere"));
+        assertEquals("Vous entrez...", ctx.fields().get("playerNarration"));
+        assertEquals("option A...", ctx.fields().get("choicesConsequences"));
+        assertEquals("moyen", ctx.fields().get("combatDifficulty"));
+        assertEquals("3 bandits", ctx.fields().get("enemies"));
+        assertEquals("trésor caché", ctx.fields().get("gmSecretNotes"));
     }
 
     @Test
@@ -104,14 +110,62 @@ public class NarrativeEntityContextBuilderTest {
         when(arcRepository.findById("arc-1")).thenReturn(Optional.of(arc));
 
         NarrativeEntityContext ctx = builder.build("  ARC  ", "arc-1");
-        assertEquals("arc", ctx.getEntityType());
+        assertEquals("arc", ctx.entityType());
+    }
+
+    @Test
+    void testBuild_Character_MarkdownProjected() {
+        Character c = Character.builder()
+                .id("c-1").name("Aragorn").markdownContent("# Aragorn\nRôdeur")
+                .build();
+        when(characterRepository.findById("c-1")).thenReturn(Optional.of(c));
+
+        NarrativeEntityContext ctx = builder.build("character", "c-1");
+
+        assertEquals("character", ctx.entityType());
+        assertEquals("Aragorn", ctx.title());
+        assertEquals("# Aragorn\nRôdeur", ctx.fields().get("fiche complète (markdown)"));
+    }
+
+    @Test
+    void testBuild_Npc_MarkdownProjected() {
+        Npc n = Npc.builder()
+                .id("n-1").name("Borin le forgeron")
+                .markdownContent("# Borin\n**Faction :** Clan Feuillefer")
+                .build();
+        when(npcRepository.findById("n-1")).thenReturn(Optional.of(n));
+
+        NarrativeEntityContext ctx = builder.build("npc", "n-1");
+
+        assertEquals("npc", ctx.entityType());
+        assertEquals("Borin le forgeron", ctx.title());
+        assertEquals("# Borin\n**Faction :** Clan Feuillefer",
+                ctx.fields().get("fiche complète (markdown)"));
+    }
+
+    @Test
+    void testBuild_Npc_NormalizesCase() {
+        Npc n = Npc.builder().id("n-1").name("Elara").markdownContent("desc").build();
+        when(npcRepository.findById("n-1")).thenReturn(Optional.of(n));
+
+        NarrativeEntityContext ctx = builder.build("  NPC  ", "n-1");
+        assertEquals("npc", ctx.entityType());
+    }
+
+    @Test
+    void testBuild_NpcNotFoundThrows() {
+        when(npcRepository.findById("missing")).thenReturn(Optional.empty());
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> builder.build("npc", "missing"));
+        assertTrue(ex.getMessage().contains("missing"));
     }
 
     @Test
     void testBuild_UnknownTypeThrows() {
         IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
-                () -> builder.build("npc", "id"));
-        assertTrue(ex.getMessage().contains("npc"));
+                () -> builder.build("alien", "id"));
+        assertTrue(ex.getMessage().contains("alien"));
     }
 
     @Test

core/src/test/java/com/loremind/application/generationcontext/StreamChatForCampaignUseCaseTest.java

@@ -55,9 +55,7 @@ public class StreamChatForCampaignUseCaseTest {
     @SuppressWarnings("unchecked")
     @BeforeEach
     void setUp() {
-        campaignCtx = CampaignStructuralContext.builder()
-                .campaignName("X").campaignDescription("d")
-                .build();
+        campaignCtx = new CampaignStructuralContext("X", "d", List.of(), List.of(), List.of());
         messages = List.of();
         onUsage = mock(Consumer.class);
         onToken = mock(Consumer.class);
@@ -85,10 +83,10 @@ public class StreamChatForCampaignUseCaseTest {
         ArgumentCaptor<ChatRequest> captor = ArgumentCaptor.forClass(ChatRequest.class);
         verify(aiChatProvider).streamChat(captor.capture(), eq(onUsage), eq(onToken), eq(onComplete), eq(onError));
         ChatRequest req = captor.getValue();
-        assertSame(campaignCtx, req.getCampaignContext());
-        assertNull(req.getLoreContext());
-        assertNull(req.getNarrativeEntity());
-        assertNull(req.getPageContext());
+        assertSame(campaignCtx, req.campaignContext());
+        assertNull(req.loreContext());
+        assertNull(req.narrativeEntity());
+        assertNull(req.pageContext());
         verifyNoInteractions(loreContextBuilder);
         verifyNoInteractions(narrativeEntityContextBuilder);
     }
@@ -96,8 +94,8 @@ public class StreamChatForCampaignUseCaseTest {
     @Test
     void testExecute_LinkedCampaign_LoadsLoreContext() {
         Campaign linked = Campaign.builder().id("c-1").name("C").loreId("lore-1").build();
-        LoreStructuralContext loreCtx = LoreStructuralContext.builder()
-                .loreName("L").loreDescription("d").folders(Collections.emptyMap()).build();
+        LoreStructuralContext loreCtx = new LoreStructuralContext(
+                "L", "d", Collections.emptyMap(), List.of());
 
         when(campaignRepository.findById("c-1")).thenReturn(Optional.of(linked));
         when(campaignContextBuilder.build("c-1")).thenReturn(campaignCtx);
@@ -107,7 +105,7 @@ public class StreamChatForCampaignUseCaseTest {
 
         ArgumentCaptor<ChatRequest> captor = ArgumentCaptor.forClass(ChatRequest.class);
         verify(aiChatProvider).streamChat(captor.capture(), any(), any(), any(), any());
-        assertSame(loreCtx, captor.getValue().getLoreContext());
+        assertSame(loreCtx, captor.getValue().loreContext());
     }
 
     @Test
@@ -122,15 +120,14 @@ public class StreamChatForCampaignUseCaseTest {
 
         ArgumentCaptor<ChatRequest> captor = ArgumentCaptor.forClass(ChatRequest.class);
         verify(aiChatProvider).streamChat(captor.capture(), any(), any(), any(), any());
-        assertNull(captor.getValue().getLoreContext());
+        assertNull(captor.getValue().loreContext());
         // La requete doit tout de meme partir (pas d'exception).
     }
 
     @Test
     void testExecute_WithEntityFocus_BuildsNarrativeEntity() {
         Campaign standalone = Campaign.builder().id("c-1").name("C").loreId(null).build();
-        NarrativeEntityContext entity = NarrativeEntityContext.builder()
-                .entityType("scene").title("L'auberge").fields(Map.of()).build();
+        NarrativeEntityContext entity = new NarrativeEntityContext("scene", "L'auberge", Map.of());
 
         when(campaignRepository.findById("c-1")).thenReturn(Optional.of(standalone));
         when(campaignContextBuilder.build("c-1")).thenReturn(campaignCtx);
@@ -140,7 +137,7 @@ public class StreamChatForCampaignUseCaseTest {
 
         ArgumentCaptor<ChatRequest> captor = ArgumentCaptor.forClass(ChatRequest.class);
         verify(aiChatProvider).streamChat(captor.capture(), any(), any(), any(), any());
-        assertSame(entity, captor.getValue().getNarrativeEntity());
+        assertSame(entity, captor.getValue().narrativeEntity());
     }
 
     @Test
@@ -153,7 +150,7 @@ public class StreamChatForCampaignUseCaseTest {
 
         ArgumentCaptor<ChatRequest> captor = ArgumentCaptor.forClass(ChatRequest.class);
         verify(aiChatProvider).streamChat(captor.capture(), any(), any(), any(), any());
-        assertNull(captor.getValue().getNarrativeEntity());
+        assertNull(captor.getValue().narrativeEntity());
         verifyNoInteractions(narrativeEntityContextBuilder);
     }
 }

core/src/test/java/com/loremind/application/generationcontext/StreamChatForLoreUseCaseTest.java

@@ -55,10 +55,7 @@ public class StreamChatForLoreUseCaseTest {
     @SuppressWarnings("unchecked")
     @BeforeEach
     void setUp() {
-        loreCtx = LoreStructuralContext.builder()
-                .loreName("Aetheria").loreDescription("d")
-                .folders(Collections.emptyMap())
-                .build();
+        loreCtx = new LoreStructuralContext("Aetheria", "d", Collections.emptyMap(), List.of());
         messages = List.of();
         onUsage = mock(Consumer.class);
         onToken = mock(Consumer.class);
@@ -75,9 +72,9 @@ public class StreamChatForLoreUseCaseTest {
         ArgumentCaptor<ChatRequest> captor = ArgumentCaptor.forClass(ChatRequest.class);
         verify(aiChatProvider).streamChat(captor.capture(), eq(onUsage), eq(onToken), eq(onComplete), eq(onError));
         ChatRequest req = captor.getValue();
-        assertSame(loreCtx, req.getLoreContext());
-        assertNull(req.getPageContext());
-        assertNull(req.getCampaignContext());
+        assertSame(loreCtx, req.loreContext());
+        assertNull(req.pageContext());
+        assertNull(req.campaignContext());
     }
 
     @Test
@@ -88,7 +85,7 @@ public class StreamChatForLoreUseCaseTest {
 
         ArgumentCaptor<ChatRequest> captor = ArgumentCaptor.forClass(ChatRequest.class);
         verify(aiChatProvider).streamChat(captor.capture(), any(), any(), any(), any());
-        assertNull(captor.getValue().getPageContext());
+        assertNull(captor.getValue().pageContext());
         verifyNoInteractions(pageRepository);
     }
 
@@ -116,12 +113,12 @@ public class StreamChatForLoreUseCaseTest {
         ArgumentCaptor<ChatRequest> captor = ArgumentCaptor.forClass(ChatRequest.class);
         verify(aiChatProvider).streamChat(captor.capture(), any(), any(), any(), any());
         ChatRequest req = captor.getValue();
-        assertNotNull(req.getPageContext());
-        assertEquals("Alice", req.getPageContext().getTitle());
-        assertEquals("Personnage", req.getPageContext().getTemplateName());
+        assertNotNull(req.pageContext());
+        assertEquals("Alice", req.pageContext().title());
+        assertEquals("Personnage", req.pageContext().templateName());
         // Seuls les champs TEXT exposes
-        assertEquals(List.of("Histoire"), req.getPageContext().getTemplateFields());
-        assertEquals(values, req.getPageContext().getValues());
+        assertEquals(List.of("Histoire"), req.pageContext().templateFields());
+        assertEquals(values, req.pageContext().values());
     }
 
     @Test
@@ -137,12 +134,12 @@ public class StreamChatForLoreUseCaseTest {
 
         ArgumentCaptor<ChatRequest> captor = ArgumentCaptor.forClass(ChatRequest.class);
         verify(aiChatProvider).streamChat(captor.capture(), any(), any(), any(), any());
-        var pageCtx = captor.getValue().getPageContext();
+        var pageCtx = captor.getValue().pageContext();
         assertNotNull(pageCtx);
-        assertEquals("Orphan", pageCtx.getTitle());
-        assertEquals("?", pageCtx.getTemplateName());
-        assertTrue(pageCtx.getTemplateFields().isEmpty());
-        assertTrue(pageCtx.getValues().isEmpty());
+        assertEquals("Orphan", pageCtx.title());
+        assertEquals("?", pageCtx.templateName());
+        assertTrue(pageCtx.templateFields().isEmpty());
+        assertTrue(pageCtx.values().isEmpty());
         verifyNoInteractions(templateRepository);
     }
 
@@ -160,9 +157,9 @@ public class StreamChatForLoreUseCaseTest {
 
         ArgumentCaptor<ChatRequest> captor = ArgumentCaptor.forClass(ChatRequest.class);
         verify(aiChatProvider).streamChat(captor.capture(), any(), any(), any(), any());
-        var pageCtx = captor.getValue().getPageContext();
-        assertEquals("?", pageCtx.getTemplateName());
-        assertTrue(pageCtx.getTemplateFields().isEmpty());
+        var pageCtx = captor.getValue().pageContext();
+        assertEquals("?", pageCtx.templateName());
+        assertTrue(pageCtx.templateFields().isEmpty());
     }
 
     @Test

core/src/test/java/com/loremind/domain/campaigncontext/SceneBranchTest.java

@@ -9,48 +9,36 @@ import static org.junit.jupiter.api.Assertions.assertNull;
 /**
  * Tests unitaires pour SceneBranch (Value Object).
  * Verifie :
- *  - l'immuabilite (pas de setters : seul le builder permet la construction),
- *  - l'egalite structurelle generee par @Value (equals/hashCode sur tous les
+ *  - l'immuabilite (record : aucun setter, constructeur canonique uniquement),
+ *  - l'egalite structurelle generee par record (equals/hashCode sur tous les
  *    champs) — deux branches aux memes champs sont strictement egales,
  *  - le support du champ optionnel {@code condition}.
  */
 class SceneBranchTest {
 
     @Test
-    void builder_exposesAllFields() {
-        SceneBranch branch = SceneBranch.builder()
-                .label("Si les joueurs attaquent le garde")
-                .targetSceneId("sc-combat")
-                .condition("initiative > 15")
-                .build();
+    void constructor_exposesAllFields() {
+        SceneBranch branch = new SceneBranch(
+                "Si les joueurs attaquent le garde",
+                "sc-combat",
+                "initiative > 15");
 
-        assertEquals("Si les joueurs attaquent le garde", branch.getLabel());
-        assertEquals("sc-combat", branch.getTargetSceneId());
-        assertEquals("initiative > 15", branch.getCondition());
+        assertEquals("Si les joueurs attaquent le garde", branch.label());
+        assertEquals("sc-combat", branch.targetSceneId());
+        assertEquals("initiative > 15", branch.condition());
     }
 
     @Test
     void condition_isOptional() {
-        SceneBranch branch = SceneBranch.builder()
-                .label("sortie par la porte")
-                .targetSceneId("sc-corridor")
-                .build();
+        SceneBranch branch = SceneBranch.of("sortie par la porte", "sc-corridor");
 
-        assertNull(branch.getCondition());
+        assertNull(branch.condition());
     }
 
     @Test
     void twoBranches_withSameFields_areEqual() {
-        SceneBranch a = SceneBranch.builder()
-                .label("fuite")
-                .targetSceneId("sc-2")
-                .condition(null)
-                .build();
-        SceneBranch b = SceneBranch.builder()
-                .label("fuite")
-                .targetSceneId("sc-2")
-                .condition(null)
-                .build();
+        SceneBranch a = new SceneBranch("fuite", "sc-2", null);
+        SceneBranch b = new SceneBranch("fuite", "sc-2", null);
 
         assertEquals(a, b);
         assertEquals(a.hashCode(), b.hashCode());
@@ -58,16 +46,16 @@ class SceneBranchTest {
 
     @Test
     void twoBranches_differingOnTargetSceneId_areNotEqual() {
-        SceneBranch a = SceneBranch.builder().label("X").targetSceneId("sc-1").build();
-        SceneBranch b = SceneBranch.builder().label("X").targetSceneId("sc-2").build();
+        SceneBranch a = SceneBranch.of("X", "sc-1");
+        SceneBranch b = SceneBranch.of("X", "sc-2");
 
         assertNotEquals(a, b);
     }
 
     @Test
     void twoBranches_differingOnCondition_areNotEqual() {
-        SceneBranch a = SceneBranch.builder().label("X").targetSceneId("sc-1").condition("A").build();
-        SceneBranch b = SceneBranch.builder().label("X").targetSceneId("sc-1").condition("B").build();
+        SceneBranch a = new SceneBranch("X", "sc-1", "A");
+        SceneBranch b = new SceneBranch("X", "sc-1", "B");
 
         assertNotEquals(a, b);
     }

core/src/test/java/com/loremind/domain/campaigncontext/SceneTest.java

@@ -60,15 +60,15 @@ class SceneTest {
 
     @Test
     void builder_preservesBranches_whenProvided() {
-        SceneBranch b1 = SceneBranch.builder().label("fuite").targetSceneId("sc-2").build();
-        SceneBranch b2 = SceneBranch.builder().label("combat").targetSceneId("sc-3").build();
+        SceneBranch b1 = SceneBranch.of("fuite", "sc-2");
+        SceneBranch b2 = SceneBranch.of("combat", "sc-3");
 
         Scene scene = Scene.builder()
                 .branches(List.of(b1, b2))
                 .build();
 
         assertEquals(2, scene.getBranches().size());
-        assertEquals("fuite", scene.getBranches().get(0).getLabel());
-        assertEquals("sc-3", scene.getBranches().get(1).getTargetSceneId());
+        assertEquals("fuite", scene.getBranches().get(0).label());
+        assertEquals("sc-3", scene.getBranches().get(1).targetSceneId());
     }
 }

core/src/test/java/com/loremind/domain/generationcontext/CampaignStructuralContextTest.java

@@ -6,108 +6,98 @@ import com.loremind.domain.generationcontext.CampaignStructuralContext.ChapterSu
 import com.loremind.domain.generationcontext.CampaignStructuralContext.SceneSummary;
 import org.junit.jupiter.api.Test;
 
+import java.util.List;
+
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNull;
-import static org.junit.jupiter.api.Assertions.assertTrue;
 
 /**
  * Tests unitaires pour CampaignStructuralContext et ses types imbriques.
- * Focus sur les annotations @Singular (chapters/scenes/branches/arcs) qui
- * permettent une construction incrementale du graphe narratif.
+ * Records purs : aucune dependance technique.
  */
 class CampaignStructuralContextTest {
 
     @Test
-    void builder_constructsFullNarrativeTree() {
-        BranchHint branch = BranchHint.builder()
-                .label("si les PJ fuient")
-                .targetSceneName("La poursuite")
-                .condition("PJ < moitie des HP")
-                .build();
+    void constructor_buildsFullNarrativeTree() {
+        BranchHint branch = new BranchHint("si les PJ fuient", "La poursuite", "PJ < moitie des HP");
 
-        SceneSummary scene = SceneSummary.builder()
-                .name("L'auberge")
-                .description("Rencontre tendue avec le tavernier")
-                .illustrationCount(2)
-                .branch(branch)
-                .build();
+        SceneSummary scene = new SceneSummary(
+                "L'auberge",
+                "Rencontre tendue avec le tavernier",
+                2,
+                List.of(branch));
 
-        ChapterSummary chapter = ChapterSummary.builder()
-                .name("L'arrivee")
-                .description("Les PJ decouvrent la ville")
-                .scene(scene)
-                .build();
+        ChapterSummary chapter = new ChapterSummary(
+                "L'arrivee",
+                "Les PJ decouvrent la ville",
+                0,
+                List.of(scene));
 
-        ArcSummary arc = ArcSummary.builder()
-                .name("Acte I")
-                .description("Mise en place")
-                .illustrationCount(1)
-                .chapter(chapter)
-                .build();
+        ArcSummary arc = new ArcSummary(
+                "Acte I",
+                "Mise en place",
+                1,
+                List.of(chapter));
 
-        CampaignStructuralContext ctx = CampaignStructuralContext.builder()
-                .campaignName("Les Ombres")
-                .campaignDescription("Une campagne dark fantasy")
-                .arc(arc)
-                .build();
+        CampaignStructuralContext ctx = new CampaignStructuralContext(
+                "Les Ombres",
+                "Une campagne dark fantasy",
+                List.of(arc),
+                List.of(),
+                List.of());
 
-        assertEquals("Les Ombres", ctx.getCampaignName());
-        assertEquals(1, ctx.getArcs().size());
-        assertEquals(1, ctx.getArcs().get(0).getChapters().size());
-        assertEquals(1, ctx.getArcs().get(0).getChapters().get(0).getScenes().size());
-        assertEquals(1, ctx.getArcs().get(0).getChapters().get(0).getScenes().get(0).getBranches().size());
+        assertEquals("Les Ombres", ctx.campaignName());
+        assertEquals(1, ctx.arcs().size());
+        assertEquals(1, ctx.arcs().get(0).chapters().size());
+        assertEquals(1, ctx.arcs().get(0).chapters().get(0).scenes().size());
+        assertEquals(1, ctx.arcs().get(0).chapters().get(0).scenes().get(0).branches().size());
     }
 
     // --- BranchHint ---------------------------------------------------------
 
     @Test
     void branchHint_preservesAllFields() {
-        BranchHint b = BranchHint.builder()
-                .label("combat")
-                .targetSceneName("La confrontation")
-                .condition("initiative > 15")
-                .build();
+        BranchHint b = new BranchHint("combat", "La confrontation", "initiative > 15");
 
-        assertEquals("combat", b.getLabel());
-        assertEquals("La confrontation", b.getTargetSceneName());
-        assertEquals("initiative > 15", b.getCondition());
+        assertEquals("combat", b.label());
+        assertEquals("La confrontation", b.targetSceneName());
+        assertEquals("initiative > 15", b.condition());
     }
 
     @Test
     void branchHint_conditionIsOptional() {
-        BranchHint b = BranchHint.builder()
-                .label("suite normale")
-                .targetSceneName("Scene 2")
-                .build();
+        BranchHint b = new BranchHint("suite normale", "Scene 2", null);
 
-        assertNull(b.getCondition());
+        assertNull(b.condition());
     }
 
     // --- illustrationCount --------------------------------------------------
 
     @Test
     void illustrationCount_defaultsToZero_onAllSummaryTypes() {
-        ArcSummary arc = ArcSummary.builder().name("X").build();
-        ChapterSummary chapter = ChapterSummary.builder().name("X").build();
-        SceneSummary scene = SceneSummary.builder().name("X").build();
+        ArcSummary arc = new ArcSummary("X", null, 0, List.of());
+        ChapterSummary chapter = new ChapterSummary("X", null, 0, List.of());
+        SceneSummary scene = new SceneSummary("X", null, 0, List.of());
 
-        assertEquals(0, arc.getIllustrationCount());
-        assertEquals(0, chapter.getIllustrationCount());
-        assertEquals(0, scene.getIllustrationCount());
+        assertEquals(0, arc.illustrationCount());
+        assertEquals(0, chapter.illustrationCount());
+        assertEquals(0, scene.illustrationCount());
     }
 
-    // --- @Singular : accumulation incrementale -----------------------------
+    // --- Construction incrementale (chapitres multiples) -------------------
 
     @Test
-    void singular_accumulatesMultipleCalls() {
-        ArcSummary arc = ArcSummary.builder()
-                .name("Acte I")
-                .chapter(ChapterSummary.builder().name("Ch1").build())
-                .chapter(ChapterSummary.builder().name("Ch2").build())
-                .chapter(ChapterSummary.builder().name("Ch3").build())
-                .build();
+    void multipleChapters_arePreserved() {
+        ArcSummary arc = new ArcSummary(
+                "Acte I",
+                null,
+                0,
+                List.of(
+                        new ChapterSummary("Ch1", null, 0, List.of()),
+                        new ChapterSummary("Ch2", null, 0, List.of()),
+                        new ChapterSummary("Ch3", null, 0, List.of())));
 
-        assertEquals(3, arc.getChapters().size());
-        assertTrue(arc.getChapters().stream().anyMatch(c -> "Ch2".equals(c.getName())));
+        assertEquals(3, arc.chapters().size());
+        assertEquals("Ch2", arc.chapters().get(1).name());
     }
 }

core/src/test/java/com/loremind/domain/generationcontext/ChatRequestTest.java

@@ -3,6 +3,7 @@ package com.loremind.domain.generationcontext;
 import org.junit.jupiter.api.Test;
 
 import java.util.List;
+import java.util.Map;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
@@ -26,57 +27,45 @@ class ChatRequestTest {
     void buildLoreOnly_leavesCampaignAndEntityNull() {
         ChatRequest request = ChatRequest.builder()
                 .messages(sampleMessages)
-                .loreContext(LoreStructuralContext.builder()
-                        .loreName("Ithoril")
-                        .loreDescription("Royaume sombre")
-                        .folders(java.util.Map.of())
-                        .build())
+                .loreContext(new LoreStructuralContext("Ithoril", "Royaume sombre", Map.of(), List.of()))
                 .build();
 
-        assertEquals(1, request.getMessages().size());
-        assertNotNull(request.getLoreContext());
-        assertEquals("Ithoril", request.getLoreContext().getLoreName());
-        assertNull(request.getPageContext());
-        assertNull(request.getCampaignContext());
-        assertNull(request.getNarrativeEntity());
+        assertEquals(1, request.messages().size());
+        assertNotNull(request.loreContext());
+        assertEquals("Ithoril", request.loreContext().loreName());
+        assertNull(request.pageContext());
+        assertNull(request.campaignContext());
+        assertNull(request.narrativeEntity());
     }
 
     @Test
     void buildLoreWithPageFocus_hasBothContexts() {
         ChatRequest request = ChatRequest.builder()
                 .messages(sampleMessages)
-                .loreContext(LoreStructuralContext.builder().folders(java.util.Map.of()).build())
-                .pageContext(PageContext.builder()
-                        .title("Thorin")
-                        .templateName("PNJ")
-                        .build())
+                .loreContext(new LoreStructuralContext(null, null, Map.of(), List.of()))
+                .pageContext(new PageContext("Thorin", "PNJ", null, null))
                 .build();
 
-        assertNotNull(request.getLoreContext());
-        assertNotNull(request.getPageContext());
-        assertEquals("Thorin", request.getPageContext().getTitle());
+        assertNotNull(request.loreContext());
+        assertNotNull(request.pageContext());
+        assertEquals("Thorin", request.pageContext().title());
     }
 
     @Test
     void buildCampaignWithNarrativeEntity_hasBothContexts() {
         ChatRequest request = ChatRequest.builder()
                 .messages(sampleMessages)
-                .campaignContext(CampaignStructuralContext.builder()
-                        .campaignName("Les Ombres")
-                        .campaignDescription("...")
-                        .build())
-                .narrativeEntity(NarrativeEntityContext.builder()
-                        .entityType("scene")
-                        .title("L'auberge")
-                        .fields(java.util.Map.of("location", "Taverne"))
-                        .build())
+                .campaignContext(new CampaignStructuralContext(
+                        "Les Ombres", "...", List.of(), List.of(), List.of()))
+                .narrativeEntity(new NarrativeEntityContext(
+                        "scene", "L'auberge", Map.of("location", "Taverne")))
                 .build();
 
-        assertNotNull(request.getCampaignContext());
-        assertNotNull(request.getNarrativeEntity());
-        assertEquals("scene", request.getNarrativeEntity().getEntityType());
-        assertNull(request.getLoreContext());
-        assertNull(request.getPageContext());
+        assertNotNull(request.campaignContext());
+        assertNotNull(request.narrativeEntity());
+        assertEquals("scene", request.narrativeEntity().entityType());
+        assertNull(request.loreContext());
+        assertNull(request.pageContext());
     }
 
     @Test
@@ -86,10 +75,10 @@ class ChatRequestTest {
                 .messages(sampleMessages)
                 .build();
 
-        assertEquals(1, request.getMessages().size());
-        assertNull(request.getLoreContext());
-        assertNull(request.getPageContext());
-        assertNull(request.getCampaignContext());
-        assertNull(request.getNarrativeEntity());
+        assertEquals(1, request.messages().size());
+        assertNull(request.loreContext());
+        assertNull(request.pageContext());
+        assertNull(request.campaignContext());
+        assertNull(request.narrativeEntity());
     }
 }

core/src/test/java/com/loremind/domain/generationcontext/GenerationContextTest.java

@@ -9,41 +9,38 @@ import static org.junit.jupiter.api.Assertions.assertNotEquals;
 
 /**
  * Tests unitaires pour GenerationContext (Value Object pour la generation one-shot).
- * Verifie la construction via builder et l'egalite structurelle.
+ * Verifie la construction et l'egalite structurelle (record).
  */
 class GenerationContextTest {
 
     @Test
-    void builder_preservesAllFields() {
-        GenerationContext ctx = GenerationContext.builder()
-                .loreName("Ithoril")
-                .loreDescription("Royaume sombre")
-                .folderName("PNJ")
-                .templateName("Fiche PNJ")
-                .templateFields(List.of("histoire", "motto", "apparence"))
-                .pageTitle("Thorin")
-                .build();
+    void constructor_preservesAllFields() {
+        GenerationContext ctx = new GenerationContext(
+                "Ithoril",
+                "Royaume sombre",
+                "PNJ",
+                "Fiche PNJ",
+                List.of("histoire", "motto", "apparence"),
+                "Thorin");
 
-        assertEquals("Ithoril", ctx.getLoreName());
-        assertEquals("PNJ", ctx.getFolderName());
-        assertEquals("Fiche PNJ", ctx.getTemplateName());
-        assertEquals(3, ctx.getTemplateFields().size());
-        assertEquals("Thorin", ctx.getPageTitle());
+        assertEquals("Ithoril", ctx.loreName());
+        assertEquals("PNJ", ctx.folderName());
+        assertEquals("Fiche PNJ", ctx.templateName());
+        assertEquals(3, ctx.templateFields().size());
+        assertEquals("Thorin", ctx.pageTitle());
     }
 
     @Test
     void twoContexts_withSameFields_areEqual() {
-        GenerationContext a = GenerationContext.builder()
-                .loreName("X").pageTitle("A").templateFields(List.of("f1")).build();
-        GenerationContext b = GenerationContext.builder()
-                .loreName("X").pageTitle("A").templateFields(List.of("f1")).build();
+        GenerationContext a = new GenerationContext("X", null, null, null, List.of("f1"), "A");
+        GenerationContext b = new GenerationContext("X", null, null, null, List.of("f1"), "A");
         assertEquals(a, b);
     }
 
     @Test
     void twoContexts_differingOnPageTitle_areNotEqual() {
-        GenerationContext a = GenerationContext.builder().pageTitle("A").build();
-        GenerationContext b = GenerationContext.builder().pageTitle("B").build();
+        GenerationContext a = new GenerationContext(null, null, null, null, null, "A");
+        GenerationContext b = new GenerationContext(null, null, null, null, null, "B");
         assertNotEquals(a, b);
     }
 }

core/src/test/java/com/loremind/domain/generationcontext/LoreStructuralContextTest.java

@@ -12,66 +12,61 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
 
 /**
  * Tests unitaires pour LoreStructuralContext et son type imbrique PageSummary.
- * Valide le @Singular de Lombok sur {@code tags} (alimentation incrementale via
- * {@code tag(...)} vs initialisation groupee via {@code tags(...)}).
+ * Records purs : aucune dependance technique.
  */
 class LoreStructuralContextTest {
 
     @Test
-    void builder_preservesFoldersAndTags() {
-        PageSummary pnj = PageSummary.builder()
-                .title("Thorin")
-                .templateName("PNJ")
-                .values(Map.of("histoire", "Nee sous une etoile rouge"))
-                .tags(List.of("pnj", "allie"))
-                .relatedPageTitles(List.of("Taverne du Dragon d'Or"))
-                .build();
+    void constructor_preservesFoldersAndTags() {
+        PageSummary pnj = new PageSummary(
+                "Thorin",
+                "PNJ",
+                Map.of("histoire", "Nee sous une etoile rouge"),
+                List.of("pnj", "allie"),
+                List.of("Taverne du Dragon d'Or"));
 
-        LoreStructuralContext ctx = LoreStructuralContext.builder()
-                .loreName("Ithoril")
-                .loreDescription("Royaume sombre")
-                .folders(Map.of("PNJ", List.of(pnj)))
-                .tag("royaume")
-                .tag("dark-fantasy")
-                .build();
+        LoreStructuralContext ctx = new LoreStructuralContext(
+                "Ithoril",
+                "Royaume sombre",
+                Map.of("PNJ", List.of(pnj)),
+                List.of("royaume", "dark-fantasy"));
 
-        assertEquals("Ithoril", ctx.getLoreName());
-        assertEquals(1, ctx.getFolders().size());
-        assertEquals(1, ctx.getFolders().get("PNJ").size());
-        assertEquals(2, ctx.getTags().size(), "@Singular doit accumuler les appels tag()");
-        assertTrue(ctx.getTags().contains("royaume"));
-        assertTrue(ctx.getTags().contains("dark-fantasy"));
+        assertEquals("Ithoril", ctx.loreName());
+        assertEquals(1, ctx.folders().size());
+        assertEquals(1, ctx.folders().get("PNJ").size());
+        assertEquals(2, ctx.tags().size());
+        assertTrue(ctx.tags().contains("royaume"));
+        assertTrue(ctx.tags().contains("dark-fantasy"));
     }
 
     @Test
     void emptyFolders_areAllowed() {
         // Dossier vide : legitime (ex: dossier "Lieux" cree mais pas encore peuple).
-        LoreStructuralContext ctx = LoreStructuralContext.builder()
-                .loreName("Vide")
-                .loreDescription("")
-                .folders(Map.of("Lieux", List.of()))
-                .build();
+        LoreStructuralContext ctx = new LoreStructuralContext(
+                "Vide",
+                "",
+                Map.of("Lieux", List.of()),
+                List.of());
 
-        assertNotNull(ctx.getFolders().get("Lieux"));
-        assertTrue(ctx.getFolders().get("Lieux").isEmpty());
+        assertNotNull(ctx.folders().get("Lieux"));
+        assertTrue(ctx.folders().get("Lieux").isEmpty());
     }
 
     // --- PageSummary --------------------------------------------------------
 
     @Test
     void pageSummary_preservesAllFields() {
-        PageSummary ps = PageSummary.builder()
-                .title("Le Donjon du Chaos")
-                .templateName("Lieu")
-                .values(Map.of("histoire", "Bati il y a 1000 ans..."))
-                .tags(List.of("donjon", "ancien"))
-                .relatedPageTitles(List.of("Thorin", "Garde royale"))
-                .build();
+        PageSummary ps = new PageSummary(
+                "Le Donjon du Chaos",
+                "Lieu",
+                Map.of("histoire", "Bati il y a 1000 ans..."),
+                List.of("donjon", "ancien"),
+                List.of("Thorin", "Garde royale"));
 
-        assertEquals("Le Donjon du Chaos", ps.getTitle());
-        assertEquals("Lieu", ps.getTemplateName());
-        assertEquals(1, ps.getValues().size());
-        assertEquals(2, ps.getTags().size());
-        assertEquals(2, ps.getRelatedPageTitles().size());
+        assertEquals("Le Donjon du Chaos", ps.title());
+        assertEquals("Lieu", ps.templateName());
+        assertEquals(1, ps.values().size());
+        assertEquals(2, ps.tags().size());
+        assertEquals(2, ps.relatedPageTitles().size());
     }
 }

core/src/test/java/com/loremind/domain/generationcontext/NarrativeEntityContextTest.java

@@ -16,21 +16,17 @@ import static org.junit.jupiter.api.Assertions.assertNotEquals;
 class NarrativeEntityContextTest {
 
     @Test
-    void builder_preservesAllFields() {
+    void constructor_preservesAllFields() {
         Map<String, String> fields = new LinkedHashMap<>();
         fields.put("themes", "trahison");
         fields.put("stakes", "la survie du royaume");
 
-        NarrativeEntityContext ctx = NarrativeEntityContext.builder()
-                .entityType("arc")
-                .title("Acte I")
-                .fields(fields)
-                .build();
+        NarrativeEntityContext ctx = new NarrativeEntityContext("arc", "Acte I", fields);
 
-        assertEquals("arc", ctx.getEntityType());
-        assertEquals("Acte I", ctx.getTitle());
-        assertEquals(2, ctx.getFields().size());
-        assertEquals("trahison", ctx.getFields().get("themes"));
+        assertEquals("arc", ctx.entityType());
+        assertEquals("Acte I", ctx.title());
+        assertEquals(2, ctx.fields().size());
+        assertEquals("trahison", ctx.fields().get("themes"));
     }
 
     @Test
@@ -41,19 +37,15 @@ class NarrativeEntityContextTest {
         fields.put("timing", "Soir");
         fields.put("atmosphere", "fumee");
 
-        NarrativeEntityContext ctx = NarrativeEntityContext.builder()
-                .entityType("scene")
-                .title("L'auberge")
-                .fields(fields)
-                .build();
+        NarrativeEntityContext ctx = new NarrativeEntityContext("scene", "L'auberge", fields);
 
-        assertEquals("[location, timing, atmosphere]", ctx.getFields().keySet().toString());
+        assertEquals("[location, timing, atmosphere]", ctx.fields().keySet().toString());
     }
 
     @Test
     void twoContexts_differingOnEntityType_areNotEqual() {
-        NarrativeEntityContext a = NarrativeEntityContext.builder().entityType("arc").title("X").build();
-        NarrativeEntityContext b = NarrativeEntityContext.builder().entityType("scene").title("X").build();
+        NarrativeEntityContext a = new NarrativeEntityContext("arc", "X", Map.of());
+        NarrativeEntityContext b = new NarrativeEntityContext("scene", "X", Map.of());
         assertNotEquals(a, b);
     }
 }

core/src/test/java/com/loremind/domain/generationcontext/PageContextTest.java

@@ -14,31 +14,29 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
 class PageContextTest {
 
     @Test
-    void builder_preservesAllFields() {
-        PageContext ctx = PageContext.builder()
-                .title("Thorin")
-                .templateName("PNJ")
-                .templateFields(List.of("histoire", "apparence", "motto"))
-                .values(Map.of("histoire", "Nee sous une etoile rouge"))
-                .build();
+    void constructor_preservesAllFields() {
+        PageContext ctx = new PageContext(
+                "Thorin",
+                "PNJ",
+                List.of("histoire", "apparence", "motto"),
+                Map.of("histoire", "Nee sous une etoile rouge"));
 
-        assertEquals("Thorin", ctx.getTitle());
-        assertEquals("PNJ", ctx.getTemplateName());
-        assertEquals(3, ctx.getTemplateFields().size());
-        assertEquals(1, ctx.getValues().size());
+        assertEquals("Thorin", ctx.title());
+        assertEquals("PNJ", ctx.templateName());
+        assertEquals(3, ctx.templateFields().size());
+        assertEquals(1, ctx.values().size());
     }
 
     @Test
     void emptyValues_areAllowed() {
         // Page vierge : template defini mais aucun champ rempli (cas generation ex-nihilo).
-        PageContext ctx = PageContext.builder()
-                .title("Nouveau PNJ")
-                .templateName("PNJ")
-                .templateFields(List.of("histoire", "apparence"))
-                .values(Map.of())
-                .build();
+        PageContext ctx = new PageContext(
+                "Nouveau PNJ",
+                "PNJ",
+                List.of("histoire", "apparence"),
+                Map.of());
 
-        assertTrue(ctx.getValues().isEmpty());
-        assertEquals(2, ctx.getTemplateFields().size());
+        assertTrue(ctx.values().isEmpty());
+        assertEquals(2, ctx.templateFields().size());
     }
 }

core/src/test/java/com/loremind/infrastructure/ai/BrainChatPayloadBuilderTest.java

@@ -83,12 +83,8 @@ class BrainChatPayloadBuilderTest {
     @Test
     @SuppressWarnings("unchecked")
     void build_loreContext_includesBasicFields() {
-        LoreStructuralContext lore = LoreStructuralContext.builder()
-                .loreName("Ithoril")
-                .loreDescription("Royaume sombre")
-                .folders(Map.of())
-                .tag("dark-fantasy")
-                .build();
+        LoreStructuralContext lore = new LoreStructuralContext(
+                "Ithoril", "Royaume sombre", Map.of(), List.of("dark-fantasy"));
         ChatRequest req = ChatRequest.builder().messages(sampleMessages).loreContext(lore).build();
 
         Map<String, Object> payload = builder.build(req);
@@ -103,17 +99,10 @@ class BrainChatPayloadBuilderTest {
     @Test
     @SuppressWarnings("unchecked")
     void build_pageSummary_omitsEmptyValuesTagsAndRelated() {
-        PageSummary minimal = PageSummary.builder()
-                .title("Thorin")
-                .templateName("PNJ")
-                .values(Map.of())
-                .tags(List.of())
-                .relatedPageTitles(List.of())
-                .build();
-        LoreStructuralContext lore = LoreStructuralContext.builder()
-                .loreName("X").loreDescription("")
-                .folders(Map.of("PNJ", List.of(minimal)))
-                .build();
+        PageSummary minimal = new PageSummary("Thorin", "PNJ",
+                Map.of(), List.of(), List.of());
+        LoreStructuralContext lore = new LoreStructuralContext(
+                "X", "", Map.of("PNJ", List.of(minimal)), List.of());
         ChatRequest req = ChatRequest.builder().messages(sampleMessages).loreContext(lore).build();
 
         Map<String, Object> payload = builder.build(req);
@@ -132,17 +121,12 @@ class BrainChatPayloadBuilderTest {
     @Test
     @SuppressWarnings("unchecked")
     void build_pageSummary_includesNonEmptyValuesTagsAndRelated() {
-        PageSummary full = PageSummary.builder()
-                .title("Thorin")
-                .templateName("PNJ")
-                .values(Map.of("histoire", "Nee sous une etoile rouge"))
-                .tags(List.of("pnj", "allie"))
-                .relatedPageTitles(List.of("Taverne du Dragon d'Or"))
-                .build();
-        LoreStructuralContext lore = LoreStructuralContext.builder()
-                .loreName("X").loreDescription("")
-                .folders(Map.of("PNJ", List.of(full)))
-                .build();
+        PageSummary full = new PageSummary("Thorin", "PNJ",
+                Map.of("histoire", "Nee sous une etoile rouge"),
+                List.of("pnj", "allie"),
+                List.of("Taverne du Dragon d'Or"));
+        LoreStructuralContext lore = new LoreStructuralContext(
+                "X", "", Map.of("PNJ", List.of(full)), List.of());
         ChatRequest req = ChatRequest.builder().messages(sampleMessages).loreContext(lore).build();
 
         Map<String, Object> payload = builder.build(req);
@@ -161,12 +145,8 @@ class BrainChatPayloadBuilderTest {
     @Test
     @SuppressWarnings("unchecked")
     void build_pageContext_includesAllFields() {
-        PageContext pc = PageContext.builder()
-                .title("Thorin")
-                .templateName("PNJ")
-                .templateFields(List.of("histoire", "motto"))
-                .values(Map.of("histoire", "..."))
-                .build();
+        PageContext pc = new PageContext("Thorin", "PNJ",
+                List.of("histoire", "motto"), Map.of("histoire", "..."));
         ChatRequest req = ChatRequest.builder().messages(sampleMessages).pageContext(pc).build();
 
         Map<String, Object> payload = builder.build(req);
@@ -182,17 +162,12 @@ class BrainChatPayloadBuilderTest {
     @Test
     @SuppressWarnings("unchecked")
     void build_campaignContext_serializesFullNarrativeTree() {
-        BranchHint branch = BranchHint.builder()
-                .label("fuite").targetSceneName("La poursuite").condition("HP < 50%").build();
-        SceneSummary scene = SceneSummary.builder()
-                .name("L'auberge").description("Rencontre tendue")
-                .illustrationCount(3).branch(branch).build();
-        ChapterSummary chapter = ChapterSummary.builder()
-                .name("L'arrivee").description("...").scene(scene).build();
-        ArcSummary arc = ArcSummary.builder()
-                .name("Acte I").description("Mise en place").illustrationCount(1).chapter(chapter).build();
-        CampaignStructuralContext camp = CampaignStructuralContext.builder()
-                .campaignName("Les Ombres").campaignDescription("dark fantasy").arc(arc).build();
+        BranchHint branch = new BranchHint("fuite", "La poursuite", "HP < 50%");
+        SceneSummary scene = new SceneSummary("L'auberge", "Rencontre tendue", 3, List.of(branch));
+        ChapterSummary chapter = new ChapterSummary("L'arrivee", "...", 0, List.of(scene));
+        ArcSummary arc = new ArcSummary("Acte I", "Mise en place", 1, List.of(chapter));
+        CampaignStructuralContext camp = new CampaignStructuralContext(
+                "Les Ombres", "dark fantasy", List.of(arc), List.of(), List.of());
         ChatRequest req = ChatRequest.builder().messages(sampleMessages).campaignContext(camp).build();
 
         Map<String, Object> payload = builder.build(req);
@@ -223,9 +198,9 @@ class BrainChatPayloadBuilderTest {
     @Test
     @SuppressWarnings("unchecked")
     void build_arcSummary_omitsIllustrationCount_whenZero() {
-        ArcSummary arc = ArcSummary.builder().name("A").description("").illustrationCount(0).build();
-        CampaignStructuralContext camp = CampaignStructuralContext.builder()
-                .campaignName("X").campaignDescription("").arc(arc).build();
+        ArcSummary arc = new ArcSummary("A", "", 0, List.of());
+        CampaignStructuralContext camp = new CampaignStructuralContext(
+                "X", "", List.of(arc), List.of(), List.of());
         ChatRequest req = ChatRequest.builder().messages(sampleMessages).campaignContext(camp).build();
 
         Map<String, Object> payload = builder.build(req);
@@ -238,11 +213,11 @@ class BrainChatPayloadBuilderTest {
     @Test
     @SuppressWarnings("unchecked")
     void build_sceneSummary_omitsBranches_whenEmpty() {
-        SceneSummary scene = SceneSummary.builder().name("S").description("").build();
-        ChapterSummary chapter = ChapterSummary.builder().name("Ch").description("").scene(scene).build();
-        ArcSummary arc = ArcSummary.builder().name("A").description("").chapter(chapter).build();
-        CampaignStructuralContext camp = CampaignStructuralContext.builder()
-                .campaignName("X").campaignDescription("").arc(arc).build();
+        SceneSummary scene = new SceneSummary("S", "", 0, List.of());
+        ChapterSummary chapter = new ChapterSummary("Ch", "", 0, List.of(scene));
+        ArcSummary arc = new ArcSummary("A", "", 0, List.of(chapter));
+        CampaignStructuralContext camp = new CampaignStructuralContext(
+                "X", "", List.of(arc), List.of(), List.of());
         ChatRequest req = ChatRequest.builder().messages(sampleMessages).campaignContext(camp).build();
 
         Map<String, Object> payload = builder.build(req);
@@ -256,12 +231,12 @@ class BrainChatPayloadBuilderTest {
     @Test
     @SuppressWarnings("unchecked")
     void build_branchHint_omitsCondition_whenBlank() {
-        BranchHint branch = BranchHint.builder().label("X").targetSceneName("Y").condition("   ").build();
-        SceneSummary scene = SceneSummary.builder().name("S").description("").branch(branch).build();
-        ChapterSummary chapter = ChapterSummary.builder().name("Ch").description("").scene(scene).build();
-        ArcSummary arc = ArcSummary.builder().name("A").description("").chapter(chapter).build();
-        CampaignStructuralContext camp = CampaignStructuralContext.builder()
-                .campaignName("X").campaignDescription("").arc(arc).build();
+        BranchHint branch = new BranchHint("X", "Y", "   ");
+        SceneSummary scene = new SceneSummary("S", "", 0, List.of(branch));
+        ChapterSummary chapter = new ChapterSummary("Ch", "", 0, List.of(scene));
+        ArcSummary arc = new ArcSummary("A", "", 0, List.of(chapter));
+        CampaignStructuralContext camp = new CampaignStructuralContext(
+                "X", "", List.of(arc), List.of(), List.of());
         ChatRequest req = ChatRequest.builder().messages(sampleMessages).campaignContext(camp).build();
 
         Map<String, Object> payload = builder.build(req);
@@ -278,10 +253,8 @@ class BrainChatPayloadBuilderTest {
     @Test
     @SuppressWarnings("unchecked")
     void build_narrativeEntity_includesAllFields() {
-        NarrativeEntityContext entity = NarrativeEntityContext.builder()
-                .entityType("scene").title("L'auberge")
-                .fields(Map.of("location", "Taverne", "timing", "Soir"))
-                .build();
+        NarrativeEntityContext entity = new NarrativeEntityContext("scene", "L'auberge",
+                Map.of("location", "Taverne", "timing", "Soir"));
         ChatRequest req = ChatRequest.builder().messages(sampleMessages).narrativeEntity(entity).build();
 
         Map<String, Object> payload = builder.build(req);
@@ -295,10 +268,9 @@ class BrainChatPayloadBuilderTest {
 
     @Test
     void build_campaignScenario_includesBothContextsAndEntity() {
-        CampaignStructuralContext camp = CampaignStructuralContext.builder()
-                .campaignName("X").campaignDescription("").build();
-        NarrativeEntityContext entity = NarrativeEntityContext.builder()
-                .entityType("arc").title("T").fields(Map.of()).build();
+        CampaignStructuralContext camp = new CampaignStructuralContext(
+                "X", "", List.of(), List.of(), List.of());
+        NarrativeEntityContext entity = new NarrativeEntityContext("arc", "T", Map.of());
         ChatRequest req = ChatRequest.builder()
                 .messages(sampleMessages)
                 .campaignContext(camp)

core/src/test/java/com/loremind/infrastructure/persistence/converter/SceneBranchListJsonConverterTest.java

@@ -48,27 +48,21 @@ class SceneBranchListJsonConverterTest {
 
     @Test
     void roundTrip_preservesAllBranchFields() {
-        // Test critique : depend de @Jacksonized sur SceneBranch.
+        // Test critique : Jackson doit reconstruire SceneBranch (record) via
+        // son constructeur canonique sans aucune annotation.
         List<SceneBranch> source = List.of(
-                SceneBranch.builder()
-                        .label("si les joueurs attaquent")
-                        .targetSceneId("sc-combat")
-                        .condition("initiative > 15")
-                        .build(),
-                SceneBranch.builder()
-                        .label("si les joueurs fuient")
-                        .targetSceneId("sc-poursuite")
-                        .build()
+                new SceneBranch("si les joueurs attaquent", "sc-combat", "initiative > 15"),
+                SceneBranch.of("si les joueurs fuient", "sc-poursuite")
         );
 
         String json = converter.convertToDatabaseColumn(source);
         List<SceneBranch> back = converter.convertToEntityAttribute(json);
 
         assertEquals(2, back.size());
-        assertEquals("si les joueurs attaquent", back.get(0).getLabel());
-        assertEquals("sc-combat", back.get(0).getTargetSceneId());
-        assertEquals("initiative > 15", back.get(0).getCondition());
-        assertEquals("sc-poursuite", back.get(1).getTargetSceneId());
-        assertNull(back.get(1).getCondition(), "condition absente doit rester null apres round-trip");
+        assertEquals("si les joueurs attaquent", back.get(0).label());
+        assertEquals("sc-combat", back.get(0).targetSceneId());
+        assertEquals("initiative > 15", back.get(0).condition());
+        assertEquals("sc-poursuite", back.get(1).targetSceneId());
+        assertNull(back.get(1).condition(), "condition absente doit rester null apres round-trip");
     }
 }

core/src/test/java/com/loremind/infrastructure/persistence/postgres/PostgresSceneRepositoryTest.java

@@ -70,13 +70,13 @@ class PostgresSceneRepositoryTest {
 
     @Test
     void save_scenePreservesBranches_viaJsonbRoundTrip() {
-        // Le critique : le @Jacksonized de SceneBranch doit permettre la
-        // reconstruction via builder apres serialisation Jackson.
+        // Le critique : SceneBranch (record) doit etre reconstructible par
+        // Jackson via le constructeur canonique apres serialisation JSON.
         Scene scene = Scene.builder()
                 .chapterId(chapterId).name("Decision").order(0)
                 .branches(List.of(
-                        SceneBranch.builder().label("fuite").targetSceneId("sc-2").condition("HP bas").build(),
-                        SceneBranch.builder().label("combat").targetSceneId("sc-3").build()
+                        new SceneBranch("fuite", "sc-2", "HP bas"),
+                        SceneBranch.of("combat", "sc-3")
                 ))
                 .build();
 
@@ -84,10 +84,10 @@ class PostgresSceneRepositoryTest {
         Scene r = repository.findById(saved.getId()).orElseThrow();
 
         assertEquals(2, r.getBranches().size());
-        assertEquals("fuite", r.getBranches().get(0).getLabel());
-        assertEquals("sc-2", r.getBranches().get(0).getTargetSceneId());
-        assertEquals("HP bas", r.getBranches().get(0).getCondition());
-        assertEquals("combat", r.getBranches().get(1).getLabel());
+        assertEquals("fuite", r.getBranches().get(0).label());
+        assertEquals("sc-2", r.getBranches().get(0).targetSceneId());
+        assertEquals("HP bas", r.getBranches().get(0).condition());
+        assertEquals("combat", r.getBranches().get(1).label());
     }
 
     @Test

core/src/test/java/com/loremind/infrastructure/updates/UpdateCheckServiceTest.java

@@ -0,0 +1,202 @@
+package com.loremind.infrastructure.updates;
+
+import com.loremind.infrastructure.updates.UpdateCheckService.ImageStatus;
+import com.loremind.infrastructure.updates.UpdateCheckService.ImageStatusKind;
+import com.loremind.infrastructure.updates.UpdateCheckService.UpdateStatus;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.web.client.RestTemplateBuilder;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.ResponseEntity;
+import org.springframework.test.util.ReflectionTestUtils;
+import org.springframework.web.client.RestTemplate;
+
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.*;
+
+/**
+ * Test unitaire pour UpdateCheckService.
+ *
+ * Couvre les invariants critiques de la detection de MAJ :
+ *  - feature desactivee si token absent
+ *  - status UP_TO_DATE quand baseline == remote
+ *  - status UPDATE_AVAILABLE quand baseline != remote
+ *  - status UNKNOWN quand baseline manque (PAS d'alignement lazy — invariant
+ *    central, regression historique)
+ *  - status UNKNOWN quand remote impossible a fetcher
+ *  - drapeaux top-level updateAvailable / anyUnknown coherents
+ *  - back-compat : champ updateAvailable sur ImageStatus = (status == UPDATE_AVAILABLE)
+ */
+public class UpdateCheckServiceTest {
+
+    private static UpdateCheckService newService(String token) {
+        return new UpdateCheckService(
+                new RestTemplateBuilder(),
+                "ghcr.io",
+                "igmlcreation/loremind-core,igmlcreation/loremind-brain",
+                "latest",
+                "http://watchtower:8080",
+                token
+        );
+    }
+
+    /**
+     * Injecte un RestTemplate moque dans le service deja construit, et pose
+     * directement les baselines pour eviter les vrais appels HTTP.
+     */
+    @SuppressWarnings("unchecked")
+    private static void setBaselines(UpdateCheckService svc, Map<String, String> baselines) {
+        ((Map<String, String>) ReflectionTestUtils.getField(svc, "baselineDigests")).putAll(baselines);
+    }
+
+    private static RestTemplate stubHttp(UpdateCheckService svc) {
+        RestTemplate http = mock(RestTemplate.class);
+        ReflectionTestUtils.setField(svc, "http", http);
+        return http;
+    }
+
+    private static void stubRemoteDigest(RestTemplate http, String image, String digest) {
+        HttpHeaders headers = new HttpHeaders();
+        if (digest != null) headers.add("Docker-Content-Digest", digest);
+        ResponseEntity<Void> resp = new ResponseEntity<>(headers, org.springframework.http.HttpStatus.OK);
+        when(http.exchange(eq("https://ghcr.io/v2/" + image + "/manifests/latest"),
+                eq(org.springframework.http.HttpMethod.HEAD), any(), eq(Void.class)))
+                .thenReturn(resp);
+    }
+
+    private static void stubRemoteFailure(RestTemplate http, String image) {
+        when(http.exchange(eq("https://ghcr.io/v2/" + image + "/manifests/latest"),
+                eq(org.springframework.http.HttpMethod.HEAD), any(), eq(Void.class)))
+                .thenThrow(new RuntimeException("network down"));
+    }
+
+    @Test
+    void disabledWhenTokenMissing() {
+        UpdateCheckService svc = newService("");
+        UpdateStatus status = svc.check();
+        assertFalse(status.enabled());
+        assertFalse(status.updateAvailable());
+        assertFalse(status.anyUnknown());
+        assertTrue(status.images().isEmpty());
+    }
+
+    @Test
+    void upToDate_whenBaselineEqualsRemote() {
+        UpdateCheckService svc = newService("token");
+        ReflectionTestUtils.setField(svc, "baselineDigests", new ConcurrentHashMap<>());
+        setBaselines(svc, Map.of(
+                "igmlcreation/loremind-core", "sha256:aaa",
+                "igmlcreation/loremind-brain", "sha256:bbb"
+        ));
+        RestTemplate http = stubHttp(svc);
+        stubRemoteDigest(http, "igmlcreation/loremind-core", "sha256:aaa");
+        stubRemoteDigest(http, "igmlcreation/loremind-brain", "sha256:bbb");
+
+        UpdateStatus status = svc.check();
+
+        assertTrue(status.enabled());
+        assertFalse(status.updateAvailable());
+        assertFalse(status.anyUnknown());
+        for (ImageStatus img : status.images()) {
+            assertEquals(ImageStatusKind.UP_TO_DATE, img.status());
+            assertFalse(img.updateAvailable(), "back-compat bool");
+        }
+    }
+
+    @Test
+    void updateAvailable_whenRemoteDiffers() {
+        UpdateCheckService svc = newService("token");
+        ReflectionTestUtils.setField(svc, "baselineDigests", new ConcurrentHashMap<>());
+        setBaselines(svc, Map.of(
+                "igmlcreation/loremind-core", "sha256:OLD",
+                "igmlcreation/loremind-brain", "sha256:bbb"
+        ));
+        RestTemplate http = stubHttp(svc);
+        stubRemoteDigest(http, "igmlcreation/loremind-core", "sha256:NEW");
+        stubRemoteDigest(http, "igmlcreation/loremind-brain", "sha256:bbb");
+
+        UpdateStatus status = svc.check();
+
+        assertTrue(status.updateAvailable());
+        assertFalse(status.anyUnknown());
+        ImageStatus core = status.images().stream()
+                .filter(i -> i.image().endsWith("core")).findFirst().orElseThrow();
+        assertEquals(ImageStatusKind.UPDATE_AVAILABLE, core.status());
+        assertTrue(core.updateAvailable(), "back-compat bool");
+        ImageStatus brain = status.images().stream()
+                .filter(i -> i.image().endsWith("brain")).findFirst().orElseThrow();
+        assertEquals(ImageStatusKind.UP_TO_DATE, brain.status());
+    }
+
+    @Test
+    void unknown_whenBaselineMissing_DOES_NOT_lazyAlign() {
+        // INVARIANT CENTRAL : si la baseline est absente (echec init au boot),
+        // on NE DOIT PAS aligner lazy sur le remote courant — sinon une MAJ
+        // pousse APRES le boot serait declaree "a jour" silencieusement.
+        UpdateCheckService svc = newService("token");
+        ReflectionTestUtils.setField(svc, "baselineDigests", new ConcurrentHashMap<>());
+        // baseline DELIBEREMENT vide
+        RestTemplate http = stubHttp(svc);
+        stubRemoteDigest(http, "igmlcreation/loremind-core", "sha256:remote-now");
+        stubRemoteDigest(http, "igmlcreation/loremind-brain", "sha256:remote-now-2");
+
+        UpdateStatus status = svc.check();
+
+        assertTrue(status.enabled());
+        assertFalse(status.updateAvailable());
+        assertTrue(status.anyUnknown());
+        for (ImageStatus img : status.images()) {
+            assertEquals(ImageStatusKind.UNKNOWN, img.status());
+            assertNull(img.localDigest());
+            assertNotNull(img.remoteDigest()); // remote OK, baseline manquante
+        }
+
+        // VERIFICATION CRITIQUE : la baseline ne doit PAS avoir ete posee.
+        @SuppressWarnings("unchecked")
+        Map<String, String> baselines = (Map<String, String>) ReflectionTestUtils.getField(svc, "baselineDigests");
+        assertTrue(baselines.isEmpty(),
+                "check() ne doit JAMAIS aligner lazy la baseline sur le remote — "
+              + "regression de bug historique (faux negatif silencieux).");
+    }
+
+    @Test
+    void unknown_whenRemoteFetchFails() {
+        UpdateCheckService svc = newService("token");
+        ReflectionTestUtils.setField(svc, "baselineDigests", new ConcurrentHashMap<>());
+        setBaselines(svc, Map.of("igmlcreation/loremind-core", "sha256:aaa",
+                                 "igmlcreation/loremind-brain", "sha256:bbb"));
+        RestTemplate http = stubHttp(svc);
+        stubRemoteFailure(http, "igmlcreation/loremind-core");
+        stubRemoteDigest(http, "igmlcreation/loremind-brain", "sha256:bbb");
+
+        UpdateStatus status = svc.check();
+
+        assertFalse(status.updateAvailable());
+        assertTrue(status.anyUnknown());
+        ImageStatus core = status.images().stream()
+                .filter(i -> i.image().endsWith("core")).findFirst().orElseThrow();
+        assertEquals(ImageStatusKind.UNKNOWN, core.status());
+        assertNull(core.remoteDigest());
+        assertEquals("sha256:aaa", core.localDigest()); // baseline preservee
+    }
+
+    @Test
+    void mixedStatuses_anyUnknownAndAnyUpdateBothTrue() {
+        UpdateCheckService svc = newService("token");
+        ReflectionTestUtils.setField(svc, "baselineDigests", new ConcurrentHashMap<>());
+        setBaselines(svc, Map.of("igmlcreation/loremind-core", "sha256:OLD"));
+        // brain n'a pas de baseline -> UNKNOWN
+        RestTemplate http = stubHttp(svc);
+        stubRemoteDigest(http, "igmlcreation/loremind-core", "sha256:NEW");
+        stubRemoteFailure(http, "igmlcreation/loremind-brain");
+
+        UpdateStatus status = svc.check();
+
+        assertTrue(status.updateAvailable(), "core a une MAJ disponible");
+        assertTrue(status.anyUnknown(), "brain est UNKNOWN");
+    }
+}

core/src/test/java/com/loremind/infrastructure/web/controller/ArcControllerTest.java

@@ -79,7 +79,7 @@ class ArcControllerTest {
     @Test
     void getByCampaign_pathVariant() throws Exception {
         arcRepository.save(Arc.builder().campaignId(campaignId).name("A").order(0).build());
-        mockMvc.perform(get("/api/arcs/campaign/{id}", campaignId))
+        mockMvc.perform(get("/api/arcs").param("campaignId", campaignId))
                 .andExpect(status().isOk())
                 .andExpect(jsonPath("$").isArray());
     }

core/src/test/java/com/loremind/infrastructure/web/controller/ChapterControllerTest.java

@@ -81,7 +81,7 @@ class ChapterControllerTest {
     @Test
     void getByArc_pathVariant() throws Exception {
         chapterRepository.save(Chapter.builder().arcId(arcId).name("A").order(0).build());
-        mockMvc.perform(get("/api/chapters/arc/{id}", arcId))
+        mockMvc.perform(get("/api/chapters").param("arcId", arcId))
                 .andExpect(status().isOk())
                 .andExpect(jsonPath("$").isArray());
     }

core/src/test/java/com/loremind/infrastructure/web/controller/SceneControllerTest.java

@@ -85,7 +85,7 @@ class SceneControllerTest {
     @Test
     void getByChapter_pathVariant() throws Exception {
         sceneRepository.save(Scene.builder().chapterId(chapterId).name("A").order(0).build());
-        mockMvc.perform(get("/api/scenes/chapter/{id}", chapterId))
+        mockMvc.perform(get("/api/scenes").param("chapterId", chapterId))
                 .andExpect(status().isOk())
                 .andExpect(jsonPath("$").isArray());
     }

demo/.env.example

@@ -0,0 +1,27 @@
+# Copie en .env sur le serveur (jamais commite).
+
+# Registre et tag des images core / brain a spawner par session.
+REGISTRY=git.igmlcreation.fr
+TAG=latest
+
+# Secret partage entre core et brain (genere aleatoirement au build de chaque
+# session, mais un defaut est utile pour les checks de sante au boot).
+BRAIN_INTERNAL_SECRET_DEFAULT=change-me-on-server
+
+# Capacite
+MAX_SESSIONS=10
+SESSION_TTL_MINUTES=20
+
+# Rate limiting : 1 creation de session par IP par fenetre (secondes).
+RATE_LIMIT_WINDOW_SECONDS=60
+
+# Limites par conteneur de session (Docker API)
+CORE_MEMORY_MB=700
+BRAIN_MEMORY_MB=300
+POSTGRES_MEMORY_MB=200
+
+# Nom du reseau Docker externe Traefik (doit exister avant docker compose up)
+TRAEFIK_NETWORK=traefik
+
+# Domaine expose par Traefik
+DEMO_HOST=loremind-demo.igmlcreation.fr

demo/.gitignore

@@ -0,0 +1,2 @@
+.env
+*.log

demo/README.md

@@ -0,0 +1,46 @@
+# Demo publique LoreMind
+
+Deploiement d'une instance de demo ephemere pour `loremind-demo.igmlcreation.fr`.
+
+## Principe
+
+Chaque visiteur recoit un environnement isole spawne a la volee, detruit apres
+un court delai d'inactivite. Les donnees ne sont jamais persistees.
+
+Le mode demo (variable d'env `DEMO_MODE=true` sur le core) masque les ecrans
+de configuration qui n'ont pas de sens en vitrine.
+
+## Deploiement
+
+Prerequis :
+- Reseau Traefik existant cote host
+- Images `core` et `brain` pushees au registre
+
+```bash
+cp .env.example .env
+# Ajuster .env
+docker compose -f docker-compose.infra.yml up -d --build
+```
+
+Premier build : 5-10 min. Suivants : incrementaux.
+
+## Mise a jour
+
+```bash
+docker compose -f docker-compose.infra.yml pull
+docker compose -f docker-compose.infra.yml up -d --build
+```
+
+Les sessions en cours sont tuees au redemarrage.
+
+## Observations
+
+- `docker logs loremind-demo-orchestrator -f`
+- `docker ps --filter "name=demo-"`
+
+## Desactiver
+
+```bash
+docker compose -f docker-compose.infra.yml down
+docker ps -q --filter "name=demo-" | xargs -r docker rm -f
+```

demo/docker-compose.infra.yml

@@ -0,0 +1,80 @@
+# ==========================================================================
+# LoreMind Demo - Infra permanente
+# --------------------------------------------------------------------------
+# - dockerproxy : expose un subset restreint de l'API Docker a l'orchestrateur
+#   (lecture seule sauf containers/images/networks). Remplace le mount direct
+#   de /var/run/docker.sock : meme avec RCE sur l'orchestrateur, un attaquant
+#   ne peut pas exec sur l'hote, creer des volumes, ni lire le daemon.
+# - orchestrator : sert l'Angular et proxy les /api/* vers les sessions.
+#
+# Les conteneurs de session sont crees dynamiquement par l'orchestrateur.
+# ==========================================================================
+
+services:
+  dockerproxy:
+    image: tecnativa/docker-socket-proxy:latest
+    container_name: loremind-demo-dockerproxy
+    restart: unless-stopped
+    environment:
+      # Minimum requis par l'orchestrateur.
+      CONTAINERS: 1
+      IMAGES: 1
+      NETWORKS: 1
+      POST: 1
+      # Tout le reste reste a 0 (defaut) : pas d'EXEC, VOLUMES, BUILD, AUTH,
+      # SYSTEM, INFO, SWARM, SECRETS, CONFIGS, NODES, etc.
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    networks:
+      - socket-proxy
+    # Pas de ports exposes : accessible uniquement via le reseau socket-proxy.
+
+  orchestrator:
+    container_name: loremind-demo-orchestrator
+    depends_on:
+      - dockerproxy
+    build:
+      context: ../
+      dockerfile: demo/orchestrator/Dockerfile
+    restart: unless-stopped
+    environment:
+      # L'orchestrateur parle a dockerproxy au lieu du socket direct.
+      DOCKER_HOST: tcp://dockerproxy:2375
+      REGISTRY: ${REGISTRY:-git.igmlcreation.fr}
+      TAG: ${TAG:-latest}
+      MAX_SESSIONS: ${MAX_SESSIONS:-10}
+      SESSION_TTL_MINUTES: ${SESSION_TTL_MINUTES:-20}
+      CORE_MEMORY_MB: ${CORE_MEMORY_MB:-700}
+      BRAIN_MEMORY_MB: ${BRAIN_MEMORY_MB:-300}
+      POSTGRES_MEMORY_MB: ${POSTGRES_MEMORY_MB:-200}
+      SESSIONS_NETWORK: loremind-demo-sessions
+      BRAIN_INTERNAL_SECRET_DEFAULT: ${BRAIN_INTERNAL_SECRET_DEFAULT:-change-me}
+      # Rate limit : 1 creation par IP par fenetre (en secondes).
+      RATE_LIMIT_WINDOW_SECONDS: ${RATE_LIMIT_WINDOW_SECONDS:-60}
+      # Domaine public : propage aux cores de session pour configurer CORS.
+      DEMO_HOST: ${DEMO_HOST:-loremind-demo.igmlcreation.fr}
+    networks:
+      - traefik
+      - sessions
+      - socket-proxy
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.loremind-demo.rule=Host(`${DEMO_HOST:-loremind-demo.igmlcreation.fr}`)"
+      - "traefik.http.routers.loremind-demo.entrypoints=websecure"
+      - "traefik.http.routers.loremind-demo.tls.certresolver=letsencrypt"
+      - "traefik.http.services.loremind-demo.loadbalancer.server.port=80"
+
+networks:
+  traefik:
+    external: true
+    name: ${TRAEFIK_NETWORK:-traefik}
+  sessions:
+    # Reseau interne pour les trios de session. Pas d'acces Internet direct
+    # (sauf via le DNS Docker), pas expose au host.
+    name: loremind-demo-sessions
+    driver: bridge
+  socket-proxy:
+    # Reseau prive entre dockerproxy et orchestrateur. Isole du reste.
+    name: loremind-demo-socket-proxy
+    driver: bridge
+    internal: true

demo/orchestrator/Dockerfile

@@ -0,0 +1,32 @@
+# syntax=docker/dockerfile:1.6
+# Build context attendu : racine du repo LoreMind.
+# Appele depuis demo/docker-compose.infra.yml avec context: ../
+
+# --- Etage 1 : build Angular statique ---
+FROM node:20-alpine AS web-build
+WORKDIR /build
+COPY web/package*.json ./
+RUN npm ci
+COPY web/ .
+RUN npm run build -- --configuration production
+
+# --- Etage 2 : build orchestrateur Go ---
+# go 1.25+ requis par une dependance transitive de github.com/docker/docker
+# (otelhttp v0.68+ impose cette version minimale).
+FROM golang:1.25-alpine AS go-build
+WORKDIR /src
+COPY demo/orchestrator/ ./
+# go mod tidy resout le go.sum au build pour eviter d'avoir a le committer.
+RUN go mod tidy && CGO_ENABLED=0 go build -o /orchestrator .
+
+# --- Etage final : runtime minimal ---
+FROM alpine:3.20
+RUN apk add --no-cache ca-certificates
+WORKDIR /app
+COPY --from=go-build /orchestrator /app/orchestrator
+COPY --from=web-build /build/dist/web /app/static
+COPY demo/orchestrator/preparing.html /app/preparing.html
+EXPOSE 80
+ENV STATIC_DIR=/app/static \
+    PREPARING_PAGE=/app/preparing.html
+ENTRYPOINT ["/app/orchestrator"]

demo/orchestrator/config.go

@@ -0,0 +1,68 @@
+package main
+
+import (
+	"log"
+	"os"
+	"strconv"
+	"time"
+)
+
+// Config centralise les parametres lus depuis les variables d'env au boot.
+type Config struct {
+	Registry           string
+	Tag                string
+	MaxSessions        int
+	SessionTTL         time.Duration
+	CoreMemoryBytes    int64
+	BrainMemoryBytes   int64
+	PostgresMemoryBytes int64
+	SessionsNetwork    string
+	BrainSecretDefault string
+	StaticDir          string
+	PreparingPage      string
+	RateLimitWindow    time.Duration
+	MaxBodyBytes       int64
+	DemoHost           string
+}
+
+func loadConfig() *Config {
+	return &Config{
+		Registry:           envStr("REGISTRY", "git.igmlcreation.fr"),
+		Tag:                envStr("TAG", "latest"),
+		MaxSessions:        envInt("MAX_SESSIONS", 10),
+		SessionTTL:         time.Duration(envInt("SESSION_TTL_MINUTES", 20)) * time.Minute,
+		CoreMemoryBytes:    int64(envInt("CORE_MEMORY_MB", 700)) * 1024 * 1024,
+		BrainMemoryBytes:   int64(envInt("BRAIN_MEMORY_MB", 300)) * 1024 * 1024,
+		PostgresMemoryBytes: int64(envInt("POSTGRES_MEMORY_MB", 200)) * 1024 * 1024,
+		SessionsNetwork:    envStr("SESSIONS_NETWORK", "loremind-demo-sessions"),
+		BrainSecretDefault: envStr("BRAIN_INTERNAL_SECRET_DEFAULT", "change-me"),
+		StaticDir:          envStr("STATIC_DIR", "/app/static"),
+		PreparingPage:      envStr("PREPARING_PAGE", "/app/preparing.html"),
+		RateLimitWindow:    time.Duration(envInt("RATE_LIMIT_WINDOW_SECONDS", 60)) * time.Second,
+		// 10 Mo : aligne avec la limite d'upload d'image cote core.
+		MaxBodyBytes: int64(envInt("MAX_BODY_MB", 10)) * 1024 * 1024,
+		// Utilise pour injecter APP_CORS_ALLOWED_ORIGINS dans les cores spawnes :
+		// sans ca, Spring bloque les POST avec 403 (origine rejetee).
+		DemoHost: envStr("DEMO_HOST", "loremind-demo.igmlcreation.fr"),
+	}
+}
+
+func envStr(key, def string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return def
+}
+
+func envInt(key string, def int) int {
+	v := os.Getenv(key)
+	if v == "" {
+		return def
+	}
+	i, err := strconv.Atoi(v)
+	if err != nil {
+		log.Printf("warning: env %s=%q not a number, using default %d", key, v, def)
+		return def
+	}
+	return i
+}

demo/orchestrator/docker.go

@@ -0,0 +1,339 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+)
+
+// DockerClient parle a l'API Engine Docker en HTTP brut via le dockerproxy.
+// Pas de SDK externe : evite les conflits de versions transitives qui
+// rendaient github.com/docker/docker v27/v28 ininstallable proprement.
+//
+// L'API Engine v1.43 est exposee par Docker Engine 24+ (et le dockerproxy
+// la supporte sans config supplementaire).
+type DockerClient struct {
+	baseURL string
+	http    *http.Client
+}
+
+func newDockerClient() (*DockerClient, error) {
+	base := os.Getenv("DOCKER_HOST")
+	if base == "" {
+		return nil, fmt.Errorf("DOCKER_HOST non defini (attendu : tcp://dockerproxy:2375)")
+	}
+	// tcp://host:port -> http://host:port (le dockerproxy parle HTTP en clair).
+	base = strings.Replace(base, "tcp://", "http://", 1)
+	return &DockerClient{
+		baseURL: strings.TrimRight(base, "/") + "/v1.43",
+		http:    &http.Client{Timeout: 60 * time.Second},
+	}, nil
+}
+
+// --- Types serialises vers l'API Engine ---
+
+type containerSpec struct {
+	Image            string            `json:"Image"`
+	Env              []string          `json:"Env,omitempty"`
+	Labels           map[string]string `json:"Labels,omitempty"`
+	HostConfig       hostConfig        `json:"HostConfig"`
+	NetworkingConfig networkingConfig  `json:"NetworkingConfig"`
+}
+
+type hostConfig struct {
+	Memory        int64             `json:"Memory,omitempty"`
+	NanoCPUs      int64             `json:"NanoCPUs,omitempty"`
+	PidsLimit     int64             `json:"PidsLimit,omitempty"`
+	Tmpfs         map[string]string `json:"Tmpfs,omitempty"`
+	SecurityOpt   []string          `json:"SecurityOpt,omitempty"`
+	RestartPolicy restartPolicy     `json:"RestartPolicy"`
+}
+
+type restartPolicy struct {
+	Name string `json:"Name"`
+}
+
+type networkingConfig struct {
+	EndpointsConfig map[string]endpointSettings `json:"EndpointsConfig,omitempty"`
+}
+
+type endpointSettings struct {
+	Aliases []string `json:"Aliases,omitempty"`
+}
+
+// runSpec : forme intermediate cote orchestrateur, mappee sur containerSpec
+// au moment d'envoyer la requete.
+type runSpec struct {
+	Name   string
+	Image  string
+	Env    []string
+	Labels map[string]string
+	Memory int64
+	Tmpfs  map[string]string
+	Net    string
+	Alias  string
+}
+
+// --- Operations de haut niveau ---
+
+// SpawnTrio cree postgres + brain + core pour une session.
+func (d *DockerClient) SpawnTrio(ctx context.Context, sessionID string, cfg *Config) error {
+	pgName := "demo-" + sessionID + "-postgres"
+	brainName := "demo-" + sessionID + "-brain"
+	coreName := "demo-" + sessionID + "-core"
+	pgPassword := randomHex(16)
+	brainSecret := randomHex(32)
+	adminPassword := randomHex(16)
+
+	labels := map[string]string{"demo-session": sessionID}
+
+	if err := d.runContainer(ctx, runSpec{
+		Name:   pgName,
+		Image:  "postgres:16-alpine",
+		Env:    []string{"POSTGRES_DB=loremind", "POSTGRES_USER=loremind", "POSTGRES_PASSWORD=" + pgPassword},
+		Labels: copyLabels(labels, "postgres"),
+		Memory: cfg.PostgresMemoryBytes,
+		Tmpfs:  map[string]string{"/var/lib/postgresql/data": "rw,size=200m"},
+		Net:    cfg.SessionsNetwork,
+		Alias:  pgName,
+	}); err != nil {
+		return fmt.Errorf("spawn postgres: %w", err)
+	}
+
+	if err := d.runContainer(ctx, runSpec{
+		Name:  brainName,
+		Image: cfg.Registry + "/ietm64/brain:" + cfg.Tag,
+		Env: []string{
+			"INTERNAL_SHARED_SECRET=" + brainSecret,
+			// Pas de provider LLM configure en demo : les features IA echoueront
+			// proprement, la demo sert principalement a explorer l'edition.
+			"LLM_PROVIDER=ollama",
+			"OLLAMA_BASE_URL=http://localhost:1",
+		},
+		Labels: copyLabels(labels, "brain"),
+		Memory: cfg.BrainMemoryBytes,
+		Net:    cfg.SessionsNetwork,
+		Alias:  brainName,
+	}); err != nil {
+		return fmt.Errorf("spawn brain: %w", err)
+	}
+
+	if err := d.runContainer(ctx, runSpec{
+		Name:  coreName,
+		Image: cfg.Registry + "/ietm64/core:" + cfg.Tag,
+		Env: []string{
+			"SPRING_DATASOURCE_URL=jdbc:postgresql://" + pgName + ":5432/loremind",
+			"SPRING_DATASOURCE_USERNAME=loremind",
+			"SPRING_DATASOURCE_PASSWORD=" + pgPassword,
+			"BRAIN_BASE_URL=http://" + brainName + ":8000",
+			"BRAIN_INTERNAL_SECRET=" + brainSecret,
+			"ADMIN_USERNAME=admin",
+			"ADMIN_PASSWORD=" + adminPassword,
+			"DEMO_MODE=true",
+			// CorsConfig.java lit app.cors.allowed-origins (= APP_CORS_ALLOWED_ORIGINS
+			// via le relaxed binding Spring). Necessaire meme en same-origin car
+			// le browser envoie Origin sur les POST et le CorsFilter 403 les
+			// origines inconnues.
+			"APP_CORS_ALLOWED_ORIGINS=https://" + cfg.DemoHost,
+		},
+		Labels: copyLabels(labels, "core"),
+		Memory: cfg.CoreMemoryBytes,
+		Net:    cfg.SessionsNetwork,
+		Alias:  coreName,
+	}); err != nil {
+		return fmt.Errorf("spawn core: %w", err)
+	}
+
+	return nil
+}
+
+func (d *DockerClient) runContainer(ctx context.Context, s runSpec) error {
+	// Pull best-effort : si l'image est deja locale, ContainerCreate la reprendra.
+	_ = d.pullImage(ctx, s.Image)
+
+	spec := containerSpec{
+		Image:  s.Image,
+		Env:    s.Env,
+		Labels: s.Labels,
+		HostConfig: hostConfig{
+			Memory:        s.Memory,
+			NanoCPUs:      1_000_000_000, // 1 vCPU par conteneur
+			PidsLimit:     200,           // anti fork-bomb
+			Tmpfs:         s.Tmpfs,
+			SecurityOpt:   []string{"no-new-privileges:true"},
+			RestartPolicy: restartPolicy{Name: "no"},
+		},
+		NetworkingConfig: networkingConfig{
+			EndpointsConfig: map[string]endpointSettings{
+				s.Net: {Aliases: []string{s.Alias}},
+			},
+		},
+	}
+	body, err := json.Marshal(spec)
+	if err != nil {
+		return err
+	}
+
+	createResp, err := d.do(ctx, "POST", "/containers/create?name="+url.QueryEscape(s.Name), body)
+	if err != nil {
+		return fmt.Errorf("create %s: %w", s.Name, err)
+	}
+	var created struct {
+		ID string `json:"Id"`
+	}
+	if err := json.Unmarshal(createResp, &created); err != nil {
+		return fmt.Errorf("parse create %s: %w", s.Name, err)
+	}
+	if _, err := d.do(ctx, "POST", "/containers/"+created.ID+"/start", nil); err != nil {
+		return fmt.Errorf("start %s: %w", s.Name, err)
+	}
+	return nil
+}
+
+// pullImage drain le flux de progression. Erreur silencieuse : si le pull
+// echoue (registre prive sans auth, image deja locale), runContainer aura un
+// retour clair via ContainerCreate.
+func (d *DockerClient) pullImage(ctx context.Context, img string) error {
+	req, err := http.NewRequestWithContext(ctx, "POST",
+		d.baseURL+"/images/create?fromImage="+url.QueryEscape(img), nil)
+	if err != nil {
+		return err
+	}
+	resp, err := d.http.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	_, _ = io.Copy(io.Discard, resp.Body)
+	if resp.StatusCode >= 400 {
+		return fmt.Errorf("pull %s: status %d", img, resp.StatusCode)
+	}
+	return nil
+}
+
+// WaitReady poll l'endpoint /api/config du core jusqu'a 200 ou timeout.
+func (d *DockerClient) WaitReady(ctx context.Context, sessionID string, timeout time.Duration) bool {
+	deadline := time.Now().Add(timeout)
+	target := "http://demo-" + sessionID + "-core:8080/api/config"
+	c := &http.Client{Timeout: 2 * time.Second}
+	for time.Now().Before(deadline) {
+		resp, err := c.Get(target)
+		if err == nil {
+			resp.Body.Close()
+			if resp.StatusCode == 200 {
+				return true
+			}
+		}
+		select {
+		case <-ctx.Done():
+			return false
+		case <-time.After(2 * time.Second):
+		}
+	}
+	return false
+}
+
+// KillTrio supprime tous les conteneurs labellises demo-session=<id>.
+func (d *DockerClient) KillTrio(ctx context.Context, sessionID string) error {
+	containers, err := d.listContainersWithLabel(ctx, "demo-session="+sessionID)
+	if err != nil {
+		return err
+	}
+	for _, c := range containers {
+		_, _ = d.do(ctx, "DELETE", "/containers/"+c.ID+"?force=true", nil)
+	}
+	return nil
+}
+
+// ListSessionIDs : utilise au boot pour retrouver les conteneurs orphelins.
+func (d *DockerClient) ListSessionIDs(ctx context.Context) ([]string, error) {
+	containers, err := d.listContainersWithLabel(ctx, "demo-session")
+	if err != nil {
+		return nil, err
+	}
+	seen := map[string]bool{}
+	for _, c := range containers {
+		if v, ok := c.Labels["demo-session"]; ok && v != "" {
+			seen[v] = true
+		}
+	}
+	out := make([]string, 0, len(seen))
+	for id := range seen {
+		out = append(out, id)
+	}
+	return out, nil
+}
+
+type containerInfo struct {
+	ID     string            `json:"Id"`
+	Labels map[string]string `json:"Labels"`
+}
+
+func (d *DockerClient) listContainersWithLabel(ctx context.Context, label string) ([]containerInfo, error) {
+	filters := map[string][]string{"label": {label}}
+	filtersJSON, _ := json.Marshal(filters)
+	q := url.Values{}
+	q.Set("all", "true")
+	q.Set("filters", string(filtersJSON))
+	body, err := d.do(ctx, "GET", "/containers/json?"+q.Encode(), nil)
+	if err != nil {
+		return nil, err
+	}
+	var list []containerInfo
+	if err := json.Unmarshal(body, &list); err != nil {
+		return nil, err
+	}
+	return list, nil
+}
+
+// do envoie une requete et renvoie le body. Une reponse 4xx/5xx est convertie
+// en erreur avec le contenu pour faciliter le debug.
+func (d *DockerClient) do(ctx context.Context, method, path string, body []byte) ([]byte, error) {
+	var rdr io.Reader
+	if body != nil {
+		rdr = bytes.NewReader(body)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, d.baseURL+path, rdr)
+	if err != nil {
+		return nil, err
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := d.http.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	out, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode >= 400 {
+		return nil, fmt.Errorf("%s %s: HTTP %d %s", method, path, resp.StatusCode, out)
+	}
+	return out, nil
+}
+
+// --- helpers ---
+
+func copyLabels(base map[string]string, role string) map[string]string {
+	out := make(map[string]string, len(base)+1)
+	for k, v := range base {
+		out[k] = v
+	}
+	out["demo-role"] = role
+	return out
+}
+
+func randomHex(n int) string {
+	b := make([]byte, n)
+	_, _ = rand.Read(b)
+	return hex.EncodeToString(b)
+}

demo/orchestrator/go.mod

@@ -0,0 +1,8 @@
+module github.com/loremind/demo-orchestrator
+
+go 1.23
+
+// Aucune dependance externe : on parle a Docker Engine en HTTP brut
+// (cf. docker.go) plutot que d'utiliser github.com/docker/docker, dont le
+// graphe transitif est instable d'une version a l'autre (sockets.DialPipe,
+// errors.As/Is, otelhttp...).

demo/orchestrator/main.go

@@ -0,0 +1,231 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const cookieName = "loremind-demo-session"
+
+func main() {
+	cfg := loadConfig()
+
+	docker, err := newDockerClient()
+	if err != nil {
+		log.Fatalf("docker init: %v", err)
+	}
+
+	mgr := newManager(docker, cfg)
+	limiter := newRateLimiter(cfg.RateLimitWindow)
+
+	// Nettoyage des sessions residuelles au boot (redemarrage orchestrateur).
+	cleanCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	mgr.CleanupOrphans(cleanCtx)
+	cancel()
+
+	go mgr.RunGC(context.Background())
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/_demo/ready", readyHandler(mgr))
+	mux.HandleFunc("/api/", apiHandler(mgr, cfg))
+	mux.HandleFunc("/", rootHandler(mgr, limiter, cfg))
+
+	srv := &http.Server{
+		Addr:    ":80",
+		Handler: mux,
+		// Timeouts anti-slowloris. WriteTimeout laisse de la marge pour le
+		// streaming SSE (ai/chat/stream) qui peut durer plusieurs minutes.
+		ReadHeaderTimeout: 10 * time.Second,
+		ReadTimeout:       60 * time.Second,
+		WriteTimeout:      10 * time.Minute,
+		IdleTimeout:       120 * time.Second,
+		// Headers max : 1 Mo (defaut Go), suffisant.
+	}
+
+	log.Printf("orchestrator listening on :80 (max sessions=%d, ttl=%s, rate window=%s)",
+		cfg.MaxSessions, cfg.SessionTTL, cfg.RateLimitWindow)
+	if err := srv.ListenAndServe(); err != nil {
+		log.Fatalf("http server: %v", err)
+	}
+}
+
+// rootHandler gere toutes les routes non-API : sert l'Angular statique si le
+// visiteur a deja une session prete, sinon cree une session (sous rate limit)
+// et renvoie la page de preparation.
+func rootHandler(mgr *Manager, limiter *rateLimiter, cfg *Config) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		sess := currentSession(r, mgr)
+
+		// Visiteur connu et session prete -> sert l'app normalement.
+		if sess != nil && sess.Status == StatusReady {
+			serveStatic(w, r, cfg.StaticDir)
+			return
+		}
+
+		// On ne spawn qu'a la navigation initiale (GET d'un document HTML).
+		// Les assets secondaires (JS/CSS/favicon) ne doivent pas declencher
+		// de nouvelle session.
+		if r.Method != http.MethodGet {
+			http.Error(w, "No session", http.StatusUnauthorized)
+			return
+		}
+		if !acceptsHTML(r) {
+			http.Error(w, "No session", http.StatusUnauthorized)
+			return
+		}
+
+		// Session inexistante (ou expiree) -> en creer une, sous rate limit.
+		if sess == nil {
+			ip := clientIP(r)
+			if !limiter.Allow(ip) {
+				http.Error(w, "Trop de tentatives. Merci d'attendre "+
+					strconv.Itoa(int(cfg.RateLimitWindow.Seconds()))+"s.",
+					http.StatusTooManyRequests)
+				return
+			}
+			newSess, err := mgr.Create(r.Context())
+			if err != nil {
+				if errors.Is(err, ErrCapacity) {
+					http.Error(w, "La demo est pleine (max "+
+						strconv.Itoa(cfg.MaxSessions)+
+						" sessions simultanees). Merci de reessayer plus tard.",
+						http.StatusServiceUnavailable)
+					return
+				}
+				http.Error(w, "Impossible de creer la session : "+err.Error(),
+					http.StatusInternalServerError)
+				return
+			}
+			sess = newSess
+			setCookie(w, sess.ID, cfg.SessionTTL)
+		}
+
+		servePreparingPage(w, cfg.PreparingPage)
+	}
+}
+
+// apiHandler proxifie /api/* vers le core de la session.
+// Bride la taille des bodies a MaxBodyBytes pour limiter les DoS memoire.
+func apiHandler(mgr *Manager, cfg *Config) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		sess := currentSession(r, mgr)
+		if sess == nil {
+			http.Error(w, "No session", http.StatusUnauthorized)
+			return
+		}
+		if sess.Status != StatusReady {
+			http.Error(w, "Session not ready", http.StatusServiceUnavailable)
+			return
+		}
+		if r.Body != nil {
+			r.Body = http.MaxBytesReader(w, r.Body, cfg.MaxBodyBytes)
+		}
+		proxy := sessionProxy(sess)
+		proxy.ServeHTTP(w, r)
+	}
+}
+
+// sessionProxy renvoie (et cree si besoin) un reverse proxy cache dans la
+// session via sync.Once : garantit une seule creation meme sous requetes
+// concurrentes, sans mutex explicite.
+func sessionProxy(sess *Session) *httputil.ReverseProxy {
+	sess.proxyOnce.Do(func() {
+		target, _ := url.Parse("http://" + sess.CoreHost + ":8080")
+		p := httputil.NewSingleHostReverseProxy(target)
+		p.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
+			log.Printf("proxy error session=%s: %v", sess.ID, err)
+			http.Error(w, "Upstream error", http.StatusBadGateway)
+		}
+		sess.proxy = p
+	})
+	return sess.proxy.(*httputil.ReverseProxy)
+}
+
+// readyHandler renvoie l'etat de la session en JSON pour le polling client.
+// N'expose aucun ID de session ni d'information sur les autres sessions.
+func readyHandler(mgr *Manager) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		sess := currentSession(r, mgr)
+		w.Header().Set("Content-Type", "application/json")
+		if sess == nil {
+			json.NewEncoder(w).Encode(map[string]any{"status": "none"})
+			return
+		}
+		json.NewEncoder(w).Encode(map[string]any{
+			"status": string(sess.Status),
+			"error":  sess.Err,
+		})
+	}
+}
+
+// currentSession lit le cookie et retrouve la session en memoire.
+// Si le cookie pointe vers une session disparue (redemarrage orchestrateur ou
+// TTL expire), retourne nil -> le handler traitera comme un nouveau visiteur.
+func currentSession(r *http.Request, mgr *Manager) *Session {
+	c, err := r.Cookie(cookieName)
+	if err != nil || c.Value == "" {
+		return nil
+	}
+	return mgr.Get(c.Value)
+}
+
+func setCookie(w http.ResponseWriter, id string, ttl time.Duration) {
+	http.SetCookie(w, &http.Cookie{
+		Name:     cookieName,
+		Value:    id,
+		Path:     "/",
+		HttpOnly: true,
+		Secure:   true, // Traefik termine le TLS ; le browser ne doit envoyer ce cookie qu'en HTTPS.
+		SameSite: http.SameSiteLaxMode,
+		MaxAge:   int(ttl.Seconds()),
+	})
+}
+
+// serveStatic sert les fichiers de l'Angular build avec fallback sur index.html
+// pour que le routeur cote client fonctionne (SPA).
+// Le check HasPrefix apres Join + Clean empeche les path traversals (..).
+func serveStatic(w http.ResponseWriter, r *http.Request, dir string) {
+	reqPath := r.URL.Path
+	if reqPath == "/" || reqPath == "" {
+		reqPath = "/index.html"
+	}
+	fullPath := filepath.Join(dir, filepath.Clean(reqPath))
+	if !strings.HasPrefix(fullPath, dir) {
+		http.Error(w, "bad path", http.StatusBadRequest)
+		return
+	}
+	if info, err := os.Stat(fullPath); err == nil && !info.IsDir() {
+		http.ServeFile(w, r, fullPath)
+		return
+	}
+	http.ServeFile(w, r, filepath.Join(dir, "index.html"))
+}
+
+// servePreparingPage sert la page de chargement statique. Le cookie vient
+// d'etre pose, le JS de la page utilisera sessionId implicitement via le
+// cookie pour poller /_demo/ready.
+func servePreparingPage(w http.ResponseWriter, path string) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		http.Error(w, "Preparing page not found", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write(data)
+}
+
+func acceptsHTML(r *http.Request) bool {
+	accept := r.Header.Get("Accept")
+	return strings.Contains(accept, "text/html") || accept == "" || accept == "*/*"
+}

demo/orchestrator/preparing.html

@@ -0,0 +1,127 @@
+<!DOCTYPE html>
+<html lang="fr">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>LoreMind — Demo en preparation</title>
+  <style>
+    :root {
+      color-scheme: dark;
+    }
+    body {
+      margin: 0;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: #1a1625;
+      color: #e4def5;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 100vh;
+      text-align: center;
+    }
+    .card {
+      max-width: 440px;
+      padding: 2.5rem 2rem;
+    }
+    .logo {
+      font-size: 2rem;
+      color: #b794f4;
+      margin-bottom: 0.5rem;
+    }
+    .subtitle {
+      letter-spacing: 0.2em;
+      font-size: 0.75rem;
+      color: #9880c4;
+      margin-bottom: 2rem;
+    }
+    h1 {
+      font-size: 1.35rem;
+      font-weight: 500;
+      margin: 0 0 1rem;
+    }
+    p {
+      color: #aaa0c5;
+      line-height: 1.6;
+      font-size: 0.95rem;
+    }
+    .spinner {
+      width: 36px;
+      height: 36px;
+      margin: 1.5rem auto 0;
+      border: 3px solid rgba(183, 148, 244, 0.2);
+      border-top-color: #b794f4;
+      border-radius: 50%;
+      animation: spin 1s linear infinite;
+    }
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+    .error {
+      display: none;
+      margin-top: 1rem;
+      padding: 0.75rem 1rem;
+      background: rgba(239, 68, 68, 0.1);
+      border: 1px solid rgba(239, 68, 68, 0.3);
+      color: #fca5a5;
+      border-radius: 6px;
+      font-size: 0.85rem;
+    }
+    .error.visible { display: block; }
+  </style>
+</head>
+<body>
+  <main class="card">
+    <div class="logo">✦ LoreMind</div>
+    <div class="subtitle">THE DIGITAL CODEX</div>
+    <h1>Preparation de votre demo…</h1>
+    <p>
+      Nous initialisons une instance isolee rien que pour vous.
+      Cela prend generalement 20 a 40 secondes.
+    </p>
+    <p style="font-size: 0.8rem; color: #7d6ba0; margin-top: 1rem;">
+      Votre session sera automatiquement reinitialisee au bout de 20 minutes.
+    </p>
+    <div class="spinner"></div>
+    <div id="err" class="error"></div>
+  </main>
+  <script>
+    (function () {
+      var errBox = document.getElementById('err');
+      var attempts = 0;
+      var maxAttempts = 90; // 90 * 2s = 3 min max
+
+      function poll() {
+        attempts++;
+        fetch('/_demo/ready', { credentials: 'same-origin' })
+          .then(function (r) { return r.json(); })
+          .then(function (data) {
+            if (data.status === 'ready') {
+              window.location.href = '/';
+              return;
+            }
+            if (data.status === 'failed') {
+              errBox.textContent = 'Echec du demarrage : ' + (data.error || 'raison inconnue') + '. Rechargez la page pour reessayer.';
+              errBox.classList.add('visible');
+              return;
+            }
+            if (attempts >= maxAttempts) {
+              errBox.textContent = 'Timeout. Rechargez la page pour reessayer.';
+              errBox.classList.add('visible');
+              return;
+            }
+            setTimeout(poll, 2000);
+          })
+          .catch(function () {
+            if (attempts >= maxAttempts) {
+              errBox.textContent = 'Connexion perdue. Rechargez la page pour reessayer.';
+              errBox.classList.add('visible');
+              return;
+            }
+            setTimeout(poll, 2000);
+          });
+      }
+      poll();
+    })();
+  </script>
+</body>
+</html>

demo/orchestrator/ratelimit.go

@@ -0,0 +1,79 @@
+package main
+
+import (
+	"net"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+)
+
+// rateLimiter autorise au plus une action par IP dans une fenetre glissante.
+// Pas de token bucket : pour un endpoint de creation de session, "1 par
+// fenetre" est largement suffisant et plus simple a raisonner.
+type rateLimiter struct {
+	mu       sync.Mutex
+	lastSeen map[string]time.Time
+	window   time.Duration
+}
+
+func newRateLimiter(window time.Duration) *rateLimiter {
+	rl := &rateLimiter{
+		lastSeen: make(map[string]time.Time),
+		window:   window,
+	}
+	go rl.cleanupLoop()
+	return rl
+}
+
+// Allow renvoie true si l'IP n'a pas deja declenche d'action dans la fenetre.
+// Sur true, l'horloge de l'IP est reinitialisee.
+func (rl *rateLimiter) Allow(ip string) bool {
+	rl.mu.Lock()
+	defer rl.mu.Unlock()
+	now := time.Now()
+	if last, ok := rl.lastSeen[ip]; ok && now.Sub(last) < rl.window {
+		return false
+	}
+	rl.lastSeen[ip] = now
+	return true
+}
+
+// cleanupLoop purge les entrees plus anciennes que 2x la fenetre pour eviter
+// la croissance non bornee de la map sous trafic varie.
+func (rl *rateLimiter) cleanupLoop() {
+	ticker := time.NewTicker(5 * time.Minute)
+	defer ticker.Stop()
+	for range ticker.C {
+		cutoff := time.Now().Add(-2 * rl.window)
+		rl.mu.Lock()
+		for ip, t := range rl.lastSeen {
+			if t.Before(cutoff) {
+				delete(rl.lastSeen, ip)
+			}
+		}
+		rl.mu.Unlock()
+	}
+}
+
+// clientIP extrait l'IP reelle du visiteur en tenant compte du setup reverse-proxy.
+// Ordre de priorite :
+//  1. CF-Connecting-IP : defini par Cloudflare sur la base de SA propre vue du
+//     peer TCP, non-forgeable par le client, ecrase toute valeur entrante.
+//  2. X-Forwarded-For, derniere entree : quand seul Traefik est en front (pas
+//     de Cloudflare), Traefik append l'IP qu'il observe. Prendre la premiere
+//     serait une faille (header forgeable).
+//  3. RemoteAddr : fallback si aucun header de proxy n'est present.
+func clientIP(r *http.Request) string {
+	if cfIP := r.Header.Get("CF-Connecting-IP"); cfIP != "" {
+		return strings.TrimSpace(cfIP)
+	}
+	if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
+		parts := strings.Split(xff, ",")
+		return strings.TrimSpace(parts[len(parts)-1])
+	}
+	if host, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {
+		return host
+	}
+	return r.RemoteAddr
+}

demo/orchestrator/sessions.go

@@ -0,0 +1,177 @@
+package main
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"log"
+	"sync"
+	"time"
+)
+
+// SessionStatus reflete l'etat du cycle de vie d'un trio de session.
+type SessionStatus string
+
+const (
+	StatusStarting SessionStatus = "starting"
+	StatusReady    SessionStatus = "ready"
+	StatusFailed   SessionStatus = "failed"
+)
+
+// Session represente une demo isolee pour un visiteur.
+// CoreHost est le hostname Docker interne du conteneur core de cette session
+// (ex: "demo-abc123-core"), vers lequel l'orchestrateur proxifie les /api/*.
+type Session struct {
+	ID        string
+	CreatedAt time.Time
+	Status    SessionStatus
+	CoreHost  string
+	Err       string
+	// proxy et proxyOnce : reverse-proxy cache, cree au plus une fois via
+	// sync.Once (evite la race entre deux requetes concurrentes sur la meme
+	// session). proxy est typee any pour ne pas contraindre sessions.go a
+	// importer net/http/httputil.
+	proxy     any
+	proxyOnce sync.Once
+}
+
+// Manager gere le cycle de vie des sessions (creation, acces, cleanup).
+// Thread-safe : le mutex protege la map contre les acces concurrents (HTTP
+// handlers + goroutine de GC).
+type Manager struct {
+	mu       sync.Mutex
+	sessions map[string]*Session
+	docker   *DockerClient
+	cfg      *Config
+}
+
+func newManager(docker *DockerClient, cfg *Config) *Manager {
+	return &Manager{
+		sessions: make(map[string]*Session),
+		docker:   docker,
+		cfg:      cfg,
+	}
+}
+
+// ErrCapacity est retournee quand MAX_SESSIONS est atteint.
+var ErrCapacity = errors.New("demo at capacity")
+
+// Create reserve un slot et lance le spawn des conteneurs en arriere-plan.
+// Retourne immediatement avec Status=starting. L'etat bascule a "ready" quand
+// les conteneurs sont up et que core repond a /api/config.
+func (m *Manager) Create(ctx context.Context) (*Session, error) {
+	m.mu.Lock()
+	if len(m.sessions) >= m.cfg.MaxSessions {
+		m.mu.Unlock()
+		return nil, ErrCapacity
+	}
+	id := newShortID()
+	sess := &Session{
+		ID:        id,
+		CreatedAt: time.Now(),
+		Status:    StatusStarting,
+		CoreHost:  "demo-" + id + "-core",
+	}
+	m.sessions[id] = sess
+	m.mu.Unlock()
+
+	// Spawn asynchrone : l'utilisateur voit immediatement la page "preparation".
+	go func() {
+		spawnCtx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+		defer cancel()
+		if err := m.docker.SpawnTrio(spawnCtx, id, m.cfg); err != nil {
+			log.Printf("session %s spawn failed: %v", id, err)
+			m.mu.Lock()
+			sess.Status = StatusFailed
+			sess.Err = err.Error()
+			m.mu.Unlock()
+			// Nettoyage best-effort des conteneurs partiellement crees.
+			_ = m.docker.KillTrio(context.Background(), id)
+			return
+		}
+		// Attente que core reponde (sinon proxy retourne 502 aux premieres requetes).
+		if m.docker.WaitReady(spawnCtx, id, 90*time.Second) {
+			m.mu.Lock()
+			sess.Status = StatusReady
+			m.mu.Unlock()
+			log.Printf("session %s ready", id)
+		} else {
+			log.Printf("session %s never became ready", id)
+			m.mu.Lock()
+			sess.Status = StatusFailed
+			sess.Err = "timeout waiting for core"
+			m.mu.Unlock()
+			_ = m.docker.KillTrio(context.Background(), id)
+		}
+	}()
+
+	return sess, nil
+}
+
+// Get renvoie la session associee a un ID, ou nil si elle n'existe plus.
+func (m *Manager) Get(id string) *Session {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.sessions[id]
+}
+
+// RunGC boucle toutes les minutes pour supprimer les sessions expirees.
+// A lancer en goroutine au demarrage.
+func (m *Manager) RunGC(ctx context.Context) {
+	ticker := time.NewTicker(time.Minute)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			m.gcOnce()
+		}
+	}
+}
+
+func (m *Manager) gcOnce() {
+	cutoff := time.Now().Add(-m.cfg.SessionTTL)
+	m.mu.Lock()
+	var expired []string
+	for id, s := range m.sessions {
+		if s.CreatedAt.Before(cutoff) {
+			expired = append(expired, id)
+		}
+	}
+	for _, id := range expired {
+		delete(m.sessions, id)
+	}
+	m.mu.Unlock()
+
+	for _, id := range expired {
+		log.Printf("session %s expired, killing containers", id)
+		if err := m.docker.KillTrio(context.Background(), id); err != nil {
+			log.Printf("kill %s: %v", id, err)
+		}
+	}
+}
+
+// CleanupOrphans tue les conteneurs demo-* qui ne correspondent a aucune
+// session en memoire. Appele au demarrage pour gerer un redemarrage brutal.
+func (m *Manager) CleanupOrphans(ctx context.Context) {
+	ids, err := m.docker.ListSessionIDs(ctx)
+	if err != nil {
+		log.Printf("list orphans: %v", err)
+		return
+	}
+	for _, id := range ids {
+		log.Printf("cleaning orphan session %s", id)
+		_ = m.docker.KillTrio(ctx, id)
+	}
+}
+
+// newShortID genere un identifiant hexadecimal de 32 caracteres (128 bits).
+// 128 bits d'entropie rendent les collisions et le brute-force statistiquement
+// impossibles, meme si un attaquant pouvait tenter des millions de cookies.
+func newShortID() string {
+	b := make([]byte, 16)
+	_, _ = rand.Read(b)
+	return hex.EncodeToString(b)
+}

docker-compose.e2e.yml

@@ -0,0 +1,17 @@
+# Override pour la CI E2E : build les images depuis les sources au lieu de les puller.
+# Usage : docker compose -f docker-compose.yml -f docker-compose.e2e.yml up -d --build
+services:
+  core:
+    build:
+      context: ./core
+    image: loremind-core:e2e
+
+  brain:
+    build:
+      context: ./brain
+    image: loremind-brain:e2e
+
+  web:
+    build:
+      context: ./web
+    image: loremind-web:e2e