diff --git a/docs/03-implementation/configuration/module-versioning.md b/docs/03-implementation/configuration/module-versioning.md
new file mode 100644
index 0000000..1a491a0
--- /dev/null
+++ b/docs/03-implementation/configuration/module-versioning.md
@@ -0,0 +1,677 @@
+# Module Versioning System
+
+## Vue d'Ensemble
+
+Le système de versioning des modules utilise un format **MAJOR.MINOR.PATCH.BUILD** automatiquement généré par CMake lors de la compilation. Ce système permet de :
+
+- **Tracer les versions** : Identifier précisément quelle version du code a créé une save
+- **Détecter incompatibilités** : Alerter si une save utilise une version différente
+- **Debugging** : Reproduire bugs avec la version exacte du module
+- **Développement** : Versions incrémentales automatiques sans maintenance manuelle
+
+## Format de Version
+
+### Structure : MAJOR.MINOR.PATCH.BUILD
+
+```
+0.1.15.3847
+│ │ │  │
+│ │ │  └─── BUILD    : Auto-increment à chaque build (hash sources)
+│ │ └────── PATCH    : Auto-increment à chaque commit
+│ └──────── MINOR    : Manuel (fonctionnalités nouvelles)
+└────────── MAJOR    : Manuel (breaking changes)
+```
+
+### Composantes
+
+#### MAJOR (Manuel)
+- **Incrémenté** : Breaking changes, incompatibilités majeures
+- **Exemples** : Refonte complète architecture, changement format save incompatible
+- **Gestion** : Modifié manuellement dans fichier `VERSION`
+- **Valeur initiale** : `0` (pré-release), `1` (première version stable)
+
+#### MINOR (Manuel)
+- **Incrémenté** : Nouvelles fonctionnalités, ajouts non-breaking
+- **Exemples** : Nouveau type de tank, nouveau système économique
+- **Gestion** : Modifié manuellement dans fichier `VERSION`
+- **Valeur initiale** : `1`
+
+#### PATCH (Automatique)
+- **Incrémenté** : À chaque commit Git
+- **Calcul** : Nombre de commits depuis le début du projet
+- **Exemples** : Bugfixes, optimisations, refactoring mineur
+- **Gestion** : Calculé automatiquement par CMake via `git rev-list --count HEAD`
+
+#### BUILD (Automatique)
+- **Incrémenté** : À chaque rebuild (si sources modifiées)
+- **Calcul** : Hash MD5 des fichiers sources (`.cpp`, `.h`)
+- **But** : Distinguer builds de dev avec code non-commité
+- **Gestion** : Calculé automatiquement par CMake
+
+### Exemples de Versions
+
+```
+0.1.0.0      → Première version dev (MAJOR.MINOR manuel, PATCH/BUILD = 0)
+0.1.5.1234   → Après 5 commits, build 1234
+0.1.5.1235   → Même commit, sources modifiées → nouveau build
+0.1.6.1235   → Nouveau commit, sources identiques → même build (théorique)
+0.2.10.3847  → MINOR bump (nouvelle feature) + 10 commits
+1.0.0.0      → Release stable, reset PATCH/BUILD
+```
+
+## Implémentation CMake
+
+### Fichier VERSION
+
+Chaque module contient un fichier `VERSION` à la racine :
+
+```
+modules/tank/VERSION
+```
+
+Contenu du fichier :
+```
+0.1
+```
+
+Ce fichier contient uniquement `MAJOR.MINOR`. Les composantes `PATCH.BUILD` sont calculées automatiquement.
+
+### CMakeLists.txt du Module
+
+```cmake
+cmake_minimum_required(VERSION 3.20)
+project(TankModule)
+
+# ============================================================================
+# MODULE VERSIONING
+# ============================================================================
+
+# 1. Lire MAJOR.MINOR depuis fichier VERSION
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/VERSION")
+    file(READ "${CMAKE_CURRENT_SOURCE_DIR}/VERSION" BASE_VERSION)
+    string(STRIP "${BASE_VERSION}" BASE_VERSION)
+else()
+    set(BASE_VERSION "0.1")
+    message(WARNING "No VERSION file found, using default: ${BASE_VERSION}")
+endif()
+
+# 2. Calculer PATCH : nombre de commits Git
+execute_process(
+    COMMAND git rev-list --count HEAD
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    OUTPUT_VARIABLE PATCH_COUNT
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    ERROR_QUIET
+    RESULT_VARIABLE GIT_RESULT
+)
+
+if(NOT GIT_RESULT EQUAL 0)
+    set(PATCH_COUNT "0")
+    message(WARNING "Git not available, PATCH set to 0")
+endif()
+
+# 3. Calculer BUILD : hash des fichiers sources
+file(GLOB_RECURSE MODULE_SOURCES
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/*.cpp"
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/*.h"
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/*.h"
+)
+
+# Concaténer contenu de tous les fichiers
+set(SOURCES_CONTENT "")
+foreach(SOURCE_FILE ${MODULE_SOURCES})
+    file(READ ${SOURCE_FILE} FILE_CONTENT)
+    string(APPEND SOURCES_CONTENT ${FILE_CONTENT})
+endforeach()
+
+# Hash MD5 du contenu total
+string(MD5 SOURCES_HASH "${SOURCES_CONTENT}")
+
+# Convertir hash hex en nombre décimal (4 premiers caractères)
+string(SUBSTRING ${SOURCES_HASH} 0 4 BUILD_HEX)
+# Calculer valeur numérique (modulo 10000 pour limiter à 4 chiffres)
+math(EXPR BUILD_NUM "0x${BUILD_HEX} % 10000")
+
+# 4. Assembler version complète
+set(MODULE_VERSION "${BASE_VERSION}.${PATCH_COUNT}.${BUILD_NUM}")
+
+message(STATUS "Module version: ${MODULE_VERSION}")
+message(STATUS "  BASE: ${BASE_VERSION} (from VERSION file)")
+message(STATUS "  PATCH: ${PATCH_COUNT} (git commits)")
+message(STATUS "  BUILD: ${BUILD_NUM} (sources hash)")
+
+# 5. Définir macro C++ pour accès au runtime
+add_definitions(-DMODULE_VERSION="${MODULE_VERSION}")
+
+# ============================================================================
+# MODULE BUILD
+# ============================================================================
+
+# Inclure sources
+file(GLOB_RECURSE TANK_SOURCES src/*.cpp)
+
+# Créer bibliothèque partagée (.so)
+add_library(tank-module SHARED ${TANK_SOURCES})
+
+# Configuration compilation
+target_include_directories(tank-module PRIVATE include)
+target_compile_features(tank-module PRIVATE cxx_std_20)
+
+# Sortie
+set_target_properties(tank-module PROPERTIES
+    OUTPUT_NAME "tank"
+    PREFIX ""
+    SUFFIX ".so"
+)
+
+message(STATUS "Building TankModule v${MODULE_VERSION}")
+```
+
+### Utilisation dans le Code C++
+
+```cpp
+// src/TankModule.h
+#ifndef MODULE_VERSION
+#define MODULE_VERSION "unknown"
+#endif
+
+class TankModule : public IModule, public IModuleSave {
+public:
+    std::string getVersion() const override {
+        return MODULE_VERSION;  // Défini par CMake
+    }
+
+    nlohmann::json serialize() override {
+        json data;
+        data["module_name"] = "tank";
+        data["module_version"] = getVersion();  // "0.1.15.3847"
+        // ... reste de la sérialisation
+        return data;
+    }
+};
+```
+
+### Affichage au Runtime
+
+```cpp
+void TankModule::initialize() {
+    LOG_INFO("TankModule v{} initializing...", getVersion());
+}
+```
+
+Sortie console :
+```
+[INFO] TankModule v0.1.15.3847 initializing...
+```
+
+## Workflow de Développement
+
+### 1. Création Nouveau Module
+
+```bash
+# Créer structure module
+mkdir -p modules/new_module/src
+cd modules/new_module
+
+# Créer fichier VERSION
+echo "0.1" > VERSION
+
+# Créer CMakeLists.txt avec système versioning
+# (copier template ci-dessus)
+```
+
+**Première compilation** :
+```bash
+cmake . && make
+```
+
+Sortie :
+```
+-- Module version: 0.1.0.0
+--   BASE: 0.1 (from VERSION file)
+--   PATCH: 0 (git commits)
+--   BUILD: 0 (sources hash)
+-- Building NewModule v0.1.0.0
+```
+
+### 2. Développement Itératif
+
+**Scénario 1 : Modifier code sans commit**
+
+```bash
+# Éditer src/NewModule.cpp
+nano src/NewModule.cpp
+
+# Rebuild
+make
+```
+
+Sortie :
+```
+-- Module version: 0.1.0.4582
+--   PATCH: 0 (aucun commit)
+--   BUILD: 4582 (hash sources a changé)
+```
+
+**Scénario 2 : Commit modifications**
+
+```bash
+git add .
+git commit -m "Add feature X"
+
+# Rebuild
+make
+```
+
+Sortie :
+```
+-- Module version: 0.1.1.4582
+--   PATCH: 1 (nouveau commit)
+--   BUILD: 4582 (sources identiques au commit)
+```
+
+**Scénario 3 : Rebuild sans modification**
+
+```bash
+# Rebuild immédiat
+make
+```
+
+Sortie :
+```
+-- Module version: 0.1.1.4582
+   (version identique, aucun changement)
+```
+
+### 3. Release Mineure (Nouvelle Feature)
+
+```bash
+# Bump MINOR version
+echo "0.2" > VERSION
+
+# Commit
+git add VERSION
+git commit -m "Bump version to 0.2 (new feature: advanced tactics)"
+
+# Rebuild
+cmake . && make
+```
+
+Sortie :
+```
+-- Module version: 0.2.2.5123
+--   BASE: 0.2 (nouvelle version)
+--   PATCH: 2 (commits depuis début projet)
+--   BUILD: 5123 (hash actuel)
+```
+
+### 4. Release Majeure (Breaking Change)
+
+```bash
+# Bump MAJOR version
+echo "1.0" > VERSION
+
+git add VERSION
+git commit -m "Release 1.0.0 - Stable API"
+
+cmake . && make
+```
+
+Sortie :
+```
+-- Module version: 1.0.3.5123
+--   BASE: 1.0 (version stable)
+--   PATCH: 3 (total commits)
+--   BUILD: 5123
+```
+
+## Comparaison de Versions
+
+### Dans le Système de Save
+
+Lors du chargement d'une save, comparaison des versions :
+
+```cpp
+bool SaveSystem::loadModule(const std::string& moduleName) {
+    auto module = moduleSystem->getModule(moduleName);
+
+    json moduleData = readJsonFile(modulePath);
+    std::string savedVersion = moduleData["module_version"];
+    std::string currentVersion = module->getVersion();
+
+    if (savedVersion != currentVersion) {
+        LOG_WARN("Module {} version mismatch:", moduleName);
+        LOG_WARN("  Save version:    {}", savedVersion);
+        LOG_WARN("  Current version: {}", currentVersion);
+
+        // Analyser différences
+        VersionInfo saved = parseVersion(savedVersion);
+        VersionInfo current = parseVersion(currentVersion);
+
+        if (saved.major != current.major) {
+            LOG_ERROR("  MAJOR version mismatch - likely incompatible!");
+            return false;  // Incompatibilité critique
+        }
+        else if (saved.minor != current.minor) {
+            LOG_WARN("  MINOR version mismatch - some features may differ");
+            // Continuer avec warning
+        }
+        else if (saved.patch != current.patch) {
+            LOG_INFO("  PATCH version mismatch - minor changes only");
+            // Sûr, juste bugfixes
+        }
+        else {
+            LOG_DEBUG("  BUILD version mismatch - dev builds differ");
+            // Totalement sûr
+        }
+    }
+
+    return module->deserialize(moduleData);
+}
+```
+
+### Structure VersionInfo
+
+```cpp
+struct VersionInfo {
+    int major;
+    int minor;
+    int patch;
+    int build;
+
+    static VersionInfo parse(const std::string& versionStr) {
+        VersionInfo info;
+        std::sscanf(versionStr.c_str(), "%d.%d.%d.%d",
+                    &info.major, &info.minor, &info.patch, &info.build);
+        return info;
+    }
+
+    bool isCompatibleWith(const VersionInfo& other) const {
+        // Compatible si MAJOR identique
+        return major == other.major;
+    }
+
+    bool hasBreakingChanges(const VersionInfo& other) const {
+        return major != other.major;
+    }
+};
+```
+
+## Gestion Multi-Modules
+
+### Script CMake Global
+
+Pour centraliser la logique de versioning, créer un fichier CMake réutilisable :
+
+```cmake
+# cmake/ModuleVersioning.cmake
+
+function(setup_module_versioning)
+    # Lire VERSION
+    if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/VERSION")
+        file(READ "${CMAKE_CURRENT_SOURCE_DIR}/VERSION" BASE_VERSION)
+        string(STRIP "${BASE_VERSION}" BASE_VERSION)
+    else()
+        set(BASE_VERSION "0.1")
+    endif()
+
+    # Calculer PATCH
+    execute_process(
+        COMMAND git rev-list --count HEAD
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        OUTPUT_VARIABLE PATCH_COUNT
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        ERROR_QUIET
+        RESULT_VARIABLE GIT_RESULT
+    )
+    if(NOT GIT_RESULT EQUAL 0)
+        set(PATCH_COUNT "0")
+    endif()
+
+    # Calculer BUILD
+    file(GLOB_RECURSE MODULE_SOURCES
+        "${CMAKE_CURRENT_SOURCE_DIR}/src/*.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/src/*.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/*.h"
+    )
+    set(SOURCES_CONTENT "")
+    foreach(SOURCE_FILE ${MODULE_SOURCES})
+        file(READ ${SOURCE_FILE} FILE_CONTENT)
+        string(APPEND SOURCES_CONTENT ${FILE_CONTENT})
+    endforeach()
+    string(MD5 SOURCES_HASH "${SOURCES_CONTENT}")
+    string(SUBSTRING ${SOURCES_HASH} 0 4 BUILD_HEX)
+    math(EXPR BUILD_NUM "0x${BUILD_HEX} % 10000")
+
+    # Assembler version
+    set(MODULE_VERSION "${BASE_VERSION}.${PATCH_COUNT}.${BUILD_NUM}" PARENT_SCOPE)
+
+    # Log
+    message(STATUS "Module version: ${BASE_VERSION}.${PATCH_COUNT}.${BUILD_NUM}")
+endfunction()
+```
+
+### Utilisation dans Module
+
+```cmake
+# modules/tank/CMakeLists.txt
+cmake_minimum_required(VERSION 3.20)
+project(TankModule)
+
+# Importer fonction versioning
+include(${CMAKE_SOURCE_DIR}/cmake/ModuleVersioning.cmake)
+
+# Setup version automatique
+setup_module_versioning()
+
+# Définir macro
+add_definitions(-DMODULE_VERSION="${MODULE_VERSION}")
+
+# ... reste du CMakeLists
+```
+
+## Best Practices
+
+### 1. Quand Bumper MAJOR ?
+
+**Situations justifiant MAJOR bump** :
+- Changement format save incompatible
+- Refonte API du module (signatures fonctions changent)
+- Suppression de fonctionnalités existantes
+- Changement architecture fondamentale
+
+**Exemple** :
+```bash
+# Avant : TankModule v0.8.x utilise grille 10x10
+# Après : TankModule v1.0.0 utilise grille 16x16 (incompatible)
+echo "1.0" > VERSION
+```
+
+### 2. Quand Bumper MINOR ?
+
+**Situations justifiant MINOR bump** :
+- Ajout nouveau type de tank/composant
+- Nouvelle fonctionnalité (mode formation, tactiques AI)
+- Amélioration significative sans breaking change
+
+**Exemple** :
+```bash
+# Ajout système de camouflage → 0.1 → 0.2
+echo "0.2" > VERSION
+```
+
+### 3. PATCH et BUILD sont Automatiques
+
+**Ne jamais modifier manuellement** :
+- PATCH suit automatiquement les commits
+- BUILD suit automatiquement les modifications code
+
+### 4. Versioning pour Tests
+
+En environnement de test, fixer une version stable :
+
+```cmake
+if(DEFINED ENV{CI_BUILD})
+    # Build CI : version fixe pour reproductibilité
+    set(MODULE_VERSION "0.0.0.0")
+else()
+    # Build normal : versioning automatique
+    setup_module_versioning()
+endif()
+```
+
+### 5. Affichage Version au Démarrage
+
+```cpp
+void logModuleVersions() {
+    LOG_INFO("=== Module Versions ===");
+    for (auto& module : moduleSystem->getAllModules()) {
+        LOG_INFO("  {}: v{}", module->getName(), module->getVersion());
+    }
+    LOG_INFO("=======================");
+}
+```
+
+Sortie :
+```
+[INFO] === Module Versions ===
+[INFO]   tank: v0.1.15.3847
+[INFO]   economy: v0.2.8.1203
+[INFO]   factory: v0.1.20.4512
+[INFO]   transport: v0.1.5.982
+[INFO] =======================
+```
+
+## Debugging avec Versions
+
+### Reproduire un Bug
+
+Si un bug est reporté avec une save :
+
+1. **Lire version du module dans la save** :
+```bash
+cat saves/abc123/server_1/tank.json | grep module_version
+# "module_version": "0.1.15.3847"
+```
+
+2. **Retrouver commit correspondant** :
+```bash
+# PATCH = 15 commits
+git log --oneline | head -n 15 | tail -n 1
+```
+
+3. **Vérifier hash sources** :
+```bash
+# BUILD = 3847 correspond à un certain hash
+# Comparer avec hashes de commits proches
+```
+
+4. **Checkout version exacte pour debugging** :
+```bash
+git checkout <commit_hash>
+cmake . && make
+# Version devrait matcher ou être proche
+```
+
+### Logs de Version
+
+```cpp
+void TankModule::initialize() {
+    LOG_INFO("TankModule v{} initializing", getVersion());
+    LOG_DEBUG("  Compiled: {} {}", __DATE__, __TIME__);
+    LOG_DEBUG("  Compiler: {}", __VERSION__);
+}
+```
+
+## Alternatives et Limitations
+
+### Alternative 1 : Semantic Versioning Manuel
+
+**Avantage** : Contrôle total sur versions
+**Inconvénient** : Maintenance manuelle, oublis fréquents
+
+### Alternative 2 : Git Tags Only
+
+```cmake
+execute_process(
+    COMMAND git describe --tags --always
+    OUTPUT_VARIABLE MODULE_VERSION
+)
+```
+
+**Avantage** : Simple, suit git
+**Inconvénient** : Nécessite tags, pas de granularité build
+
+### Limitation Actuelle : Hash Non-Déterministe
+
+Le hash des sources peut varier selon :
+- Ordre de lecture des fichiers (filesystem dépendant)
+- Encodage des fichiers
+- Whitespace differences
+
+**Solution future** : Hash déterministe avec tri des fichiers et normalisation.
+
+## Migration depuis Système Existant
+
+Si des modules existants utilisent un autre système :
+
+```cmake
+# Détecter ancien système
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/version.txt")
+    file(READ "${CMAKE_CURRENT_SOURCE_DIR}/version.txt" OLD_VERSION)
+    message(WARNING "Found old version.txt, migrating to VERSION file")
+
+    # Extraire MAJOR.MINOR
+    string(REGEX MATCH "^[0-9]+\\.[0-9]+" BASE_VERSION ${OLD_VERSION})
+    file(WRITE "${CMAKE_CURRENT_SOURCE_DIR}/VERSION" "${BASE_VERSION}")
+
+    message(STATUS "Migration complete: ${OLD_VERSION} -> ${BASE_VERSION}.x.x")
+endif()
+```
+
+## Références Croisées
+
+- `systeme-sauvegarde.md` : Utilisation des versions dans le système de save
+- `architecture-modulaire.md` : Interface IModule, contraintes modules
+- `claude-code-integration.md` : Optimisation builds pour développement AI
+
+## Exemples Complets
+
+### Module Complet avec Versioning
+
+Voir structure complète dans :
+```
+modules/tank/
+├── VERSION              # "0.1"
+├── CMakeLists.txt       # Setup versioning + build
+├── src/
+│   ├── TankModule.cpp   # Utilise MODULE_VERSION
+│   └── Tank.cpp
+└── include/
+    └── TankModule.h     # Déclare getVersion()
+```
+
+### Test Versioning
+
+```cpp
+#ifdef TESTING
+#include <cassert>
+
+void testVersioning() {
+    TankModule module;
+
+    std::string version = module.getVersion();
+    assert(!version.empty());
+    assert(version != "unknown");
+
+    // Parse version
+    VersionInfo info = VersionInfo::parse(version);
+    assert(info.major >= 0);
+    assert(info.minor >= 0);
+    assert(info.patch >= 0);
+    assert(info.build >= 0);
+
+    std::cout << "Versioning test passed: " << version << std::endl;
+}
+#endif
+```
diff --git a/docs/ai-framework.md b/docs/ai-framework.md
new file mode 100644
index 0000000..3525726
--- /dev/null
+++ b/docs/ai-framework.md
@@ -0,0 +1,1414 @@
+# AI Framework - Unified Decision System
+
+## Philosophie
+
+Le système d'IA de Warfactory repose sur un **framework unifié de prise de décision par scoring**. Tous les types d'IA (tactique, opérationnelle, économique, diplomatique) utilisent le même pattern fondamental :
+
+1. **Générer options** disponibles dans le contexte actuel
+2. **Scorer chaque option** selon poids configurables et situation
+3. **Choisir la meilleure option** (highest score)
+4. **Exécuter l'action** correspondante
+
+Ce pattern unifié permet :
+- **Cohérence** : Même logique à travers tous les systèmes IA
+- **Configurabilité** : Comportements ajustables via JSON
+- **Apprentissage** : Reinforcement Learning ajuste les poids
+- **Modularité** : Nouveaux types de décisions ajoutables facilement
+- **Testabilité** : Chaque décision isolée et vérifiable
+
+## Architecture Globale
+
+### Hiérarchie des Modules IA
+
+```
+AI Framework
+├── Core Decision System
+│   ├── IDecision (interface de base)
+│   ├── Decision Factory (création objets)
+│   └── Scoring Engine (évaluation uniforme)
+│
+├── Helper Modules (services, pas de décisions)
+│   ├── PathfinderModule (calcul chemins)
+│   ├── AcquisitionModule (sélection cibles)
+│   └── MovementModule (exécution mouvement)
+│
+├── Decision Modules (utilisent helpers)
+│   ├── TacticalModule (combat temps-réel)
+│   ├── OperationalModule (stratégie bataille)
+│   ├── CompanyAIModule (business)
+│   └── StateAIModule (politique)
+│
+└── Data Modules (consultés par tous)
+    ├── DiplomacyModule (relations, traités)
+    └── EconomyModule (marché, prix)
+```
+
+### Flux de Décision Type
+
+```
+OperationalModule
+    ↓ (donne posture: "rush blindé")
+TacticalModule
+    ↓ (demande chemins pour flanking)
+PathfinderModule → retourne 3 chemins possibles
+    ↓ (demande cibles prioritaires)
+AcquisitionModule → retourne 5 cibles scorées
+    ↓ (choisit meilleure tactique)
+TacticalModule → décision: flanking par chemin 2, cible 1
+    ↓ (exécute mouvement)
+MovementModule → unités se déplacent
+```
+
+## Interface IDecision - Core Pattern
+
+### Définition
+
+Toutes les décisions IA implémentent cette interface :
+
+```cpp
+class IDecision {
+public:
+    virtual ~IDecision() = default;
+
+    // 1. Générer toutes les options disponibles
+    virtual std::vector<Option> generateOptions() = 0;
+
+    // 2. Évaluer score d'une option dans le contexte
+    virtual float scoreOption(const Option& opt, const Context& ctx) = 0;
+
+    // 3. Choisir la meilleure option
+    virtual Option chooseBest() = 0;
+
+    // 4. Exécuter l'option choisie
+    virtual Action execute(const Option& opt) = 0;
+
+    // 5. Obtenir les poids configurés
+    virtual Weights getWeights() const = 0;
+
+    // 6. Définir nouveaux poids (pour RL)
+    virtual void setWeights(const Weights& weights) = 0;
+};
+```
+
+### Pattern d'Usage : Decision Objects Éphémères
+
+**Principe** : New → Use → Delete
+
+```cpp
+// Création décision éphémère
+IDecision* decision = DecisionFactory::create(
+    "flanking_maneuver",
+    context,
+    weights
+);
+
+// Évaluation et choix
+Option best = decision->chooseBest();
+
+// Exécution
+Action action = decision->execute(best);
+
+// Destruction immédiate
+delete decision;
+```
+
+**Avantages** :
+- **Pas d'état persistant** : Chaque décision isolée
+- **Parallélisation** : Évaluer N décisions simultanément sans conflits
+- **Hot-reload** : Charger nouveaux types depuis modules .so
+- **Memory safety** : Objets détruits après usage
+
+**Alternative avec smart pointers** :
+```cpp
+auto decision = DecisionFactory::createUnique("flanking_maneuver", ctx, weights);
+Option best = decision->chooseBest();
+Action action = decision->execute(best);
+// Auto-delete à la sortie de scope
+```
+
+### Structures de Données
+
+#### Option
+
+Représente une action possible :
+
+```cpp
+struct Option {
+    std::string type;              // "flanking", "frontal_assault", etc.
+    json parameters;               // Paramètres spécifiques
+    float base_score;              // Score de base (avant modifiers)
+    std::vector<Modifier> modifiers; // Bonus/malus contextuels
+};
+```
+
+#### Context
+
+État du monde pertinent pour la décision :
+
+```cpp
+struct Context {
+    json world_state;              // État général (terrain, météo, etc.)
+    json entities;                 // Entités pertinentes (unités, ennemis)
+    json objectives;               // Objectifs actuels
+    json constraints;              // Contraintes (budget, temps, etc.)
+    Doctrine* doctrine;            // Doctrine appliquée (USSR, OTAN, etc.)
+};
+```
+
+#### Weights
+
+Poids configurables pour le scoring :
+
+```cpp
+struct Weights {
+    std::map<std::string, float> values;  // "aggression": 0.8, "caution": 0.3
+
+    float get(const std::string& key, float default_val = 0.5f) const {
+        auto it = values.find(key);
+        return (it != values.end()) ? it->second : default_val;
+    }
+};
+
+// Chargement depuis JSON
+Weights Weights::fromJson(const json& data) {
+    Weights w;
+    for (auto& [key, val] : data.items()) {
+        w.values[key] = val.get<float>();
+    }
+    return w;
+}
+```
+
+## Système de Scoring Unifié
+
+### Formule Générale
+
+```cpp
+float IDecision::scoreOption(const Option& opt, const Context& ctx) {
+    float score = opt.base_score;
+
+    // Application des poids
+    for (auto& [factor, importance] : weights.values) {
+        float factor_value = evaluateFactor(factor, opt, ctx);
+        score += factor_value * importance;
+    }
+
+    // Application des modifiers contextuels
+    for (auto& modifier : opt.modifiers) {
+        score *= modifier.multiplier;
+    }
+
+    // Normalisation (optionnelle)
+    return std::clamp(score, 0.0f, 1.0f);
+}
+```
+
+### Exemple Concret : PathfinderModule
+
+**Options** : 5 chemins possibles vers objectif
+
+```cpp
+class PathDecision : public IDecision {
+    std::vector<Option> generateOptions() override {
+        std::vector<Option> paths;
+
+        // Générer chemins alternatifs
+        for (auto& path : pathfinder->findAllPaths(start, end)) {
+            Option opt;
+            opt.type = "path";
+            opt.parameters["route"] = path.waypoints;
+            opt.parameters["distance"] = path.length;
+            opt.parameters["safety"] = path.threat_level;
+            opt.parameters["cover"] = path.cover_percentage;
+            opt.base_score = 0.5f;
+
+            // Modifiers contextuels
+            if (path.crosses_open_terrain) {
+                opt.modifiers.push_back({"open_terrain", 0.7f});
+            }
+            if (path.has_chokepoints) {
+                opt.modifiers.push_back({"chokepoint", 0.85f});
+            }
+
+            paths.push_back(opt);
+        }
+
+        return paths;
+    }
+
+    float scoreOption(const Option& opt, const Context& ctx) override {
+        float score = opt.base_score;
+
+        // Facteurs de scoring
+        float distance = opt.parameters["distance"];
+        float safety = opt.parameters["safety"];
+        float cover = opt.parameters["cover"];
+
+        // Application poids configurables
+        score += (1.0f - distance / max_distance) * weights.get("speed");
+        score += safety * weights.get("safety");
+        score += cover * weights.get("stealth");
+
+        // Modifiers
+        for (auto& mod : opt.modifiers) {
+            score *= mod.multiplier;
+        }
+
+        return score;
+    }
+};
+```
+
+**Configuration Poids (JSON)** :
+```json
+{
+  "pathfinder_weights": {
+    "speed": 0.6,
+    "safety": 0.3,
+    "stealth": 0.1
+  }
+}
+```
+
+**Usage** :
+```cpp
+auto decision = new PathDecision(start, end, context, weights);
+Option bestPath = decision->chooseBest();
+Action moveAction = decision->execute(bestPath);
+delete decision;
+```
+
+### Exemple : AcquisitionModule
+
+**Options** : Cibles ennemies visibles
+
+```cpp
+class AcquisitionDecision : public IDecision {
+    std::vector<Option> generateOptions() override {
+        std::vector<Option> targets;
+
+        for (auto& enemy : visibleEnemies) {
+            Option opt;
+            opt.type = "target";
+            opt.parameters["entity_id"] = enemy.id;
+            opt.parameters["threat"] = enemy.calculateThreat();
+            opt.parameters["vulnerability"] = enemy.calculateVulnerability();
+            opt.parameters["priority"] = enemy.strategic_value;
+            opt.base_score = 0.5f;
+
+            // Modifiers
+            if (enemy.is_wounded) {
+                opt.modifiers.push_back({"wounded", 1.2f});
+            }
+            if (enemy.has_cover) {
+                opt.modifiers.push_back({"covered", 0.8f});
+            }
+
+            targets.push_back(opt);
+        }
+
+        return targets;
+    }
+
+    float scoreOption(const Option& opt, const Context& ctx) override {
+        float score = opt.base_score;
+
+        float threat = opt.parameters["threat"];
+        float vulnerability = opt.parameters["vulnerability"];
+        float priority = opt.parameters["priority"];
+
+        // Poids doctrine
+        score += threat * weights.get("threat_priority");
+        score += vulnerability * weights.get("opportunism");
+        score += priority * weights.get("strategic_focus");
+
+        // Modifiers
+        for (auto& mod : opt.modifiers) {
+            score *= mod.multiplier;
+        }
+
+        return score;
+    }
+};
+```
+
+**Configuration** :
+```json
+{
+  "acquisition_weights": {
+    "threat_priority": 0.7,
+    "opportunism": 0.2,
+    "strategic_focus": 0.1
+  }
+}
+```
+
+## Modules Spécialisés
+
+### Helper Modules (Services)
+
+Ces modules **ne prennent pas de décisions**, ils fournissent des services aux decision modules.
+
+#### PathfinderModule
+
+**Responsabilité** : Calculer chemins navigables entre deux points
+
+**Interface** :
+```cpp
+class PathfinderModule : public IModule {
+public:
+    // Trouver meilleur chemin unique
+    Path findPath(Position start, Position end, PathConstraints constraints);
+
+    // Trouver tous les chemins alternatifs
+    std::vector<Path> findAllPaths(Position start, Position end, int max_paths = 5);
+
+    // Vérifier si chemin encore valide
+    bool validatePath(const Path& path);
+};
+
+struct Path {
+    std::vector<Position> waypoints;
+    float length;
+    float threat_level;        // Exposition ennemie
+    float cover_percentage;    // % du chemin avec couvert
+    bool crosses_open_terrain;
+    bool has_chokepoints;
+};
+```
+
+**Utilisé par** : TacticalModule, OperationalModule
+
+#### AcquisitionModule
+
+**Responsabilité** : Identifier et scorer cibles potentielles
+
+**Interface** :
+```cpp
+class AcquisitionModule : public IModule {
+public:
+    // Obtenir toutes les cibles visibles
+    std::vector<Target> getVisibleTargets(Unit observer);
+
+    // Scorer une cible selon contexte
+    float scoreTarget(Target target, Context ctx, Weights weights);
+
+    // Filtrer cibles selon critères
+    std::vector<Target> filterTargets(std::vector<Target> targets, FilterCriteria criteria);
+};
+
+struct Target {
+    EntityId id;
+    Position position;
+    float threat;              // Dangerosité
+    float vulnerability;       // Facilité élimination
+    float strategic_value;     // Importance stratégique
+    bool is_wounded;
+    bool has_cover;
+};
+```
+
+**Utilisé par** : TacticalModule
+
+#### MovementModule
+
+**Responsabilité** : Exécuter déplacements d'unités
+
+**Interface** :
+```cpp
+class MovementModule : public IModule {
+public:
+    // Déplacer unité selon chemin
+    void moveUnit(Unit unit, Path path);
+
+    // Déplacer formation
+    void moveFormation(std::vector<Unit> units, Path path, FormationType formation);
+
+    // Vérifier si mouvement possible
+    bool canMove(Unit unit, Position target);
+};
+```
+
+**Utilisé par** : TacticalModule
+
+### Decision Modules
+
+Ces modules **prennent des décisions** en utilisant les helpers.
+
+#### TacticalModule
+
+**Responsabilité** : Décisions combat temps-réel (secondes/minutes)
+
+**Décisions prises** :
+- Choix tactique (flanking, frontal assault, suppression, retreat)
+- Sélection cibles
+- Positionnement unités
+- Utilisation couvert
+- Timing engagements
+
+**Dépendances** :
+- PathfinderModule (chemins)
+- AcquisitionModule (cibles)
+- MovementModule (exécution)
+
+**Exemple Décision** :
+```cpp
+class FlankingDecision : public IDecision {
+    std::vector<Option> generateOptions() override {
+        std::vector<Option> options;
+
+        // Pour chaque flanc possible
+        for (auto& flankPosition : identifyFlankPositions(enemy)) {
+            // Demander chemins au PathfinderModule
+            auto paths = pathfinder->findAllPaths(myPosition, flankPosition);
+
+            for (auto& path : paths) {
+                // Demander cibles à AcquisitionModule
+                auto targets = acquisition->getVisibleTargets(myUnit);
+
+                Option opt;
+                opt.type = "flanking";
+                opt.parameters["path"] = path;
+                opt.parameters["flank_side"] = flankPosition.side; // "left"/"right"
+                opt.parameters["targets"] = targets;
+                opt.base_score = 0.6f; // Flanking généralement bon
+
+                // Modifiers
+                if (path.crosses_open_terrain) {
+                    opt.modifiers.push_back({"exposed_approach", 0.7f});
+                }
+                if (targets.size() > 3) {
+                    opt.modifiers.push_back({"many_targets", 1.2f});
+                }
+
+                options.push_back(opt);
+            }
+        }
+
+        return options;
+    }
+
+    float scoreOption(const Option& opt, const Context& ctx) override {
+        // Récupérer poids doctrine
+        Doctrine* doctrine = ctx.doctrine;
+        float flanking_preference = doctrine->tactical_weights["flanking"];
+
+        float score = opt.base_score * flanking_preference;
+
+        // Facteurs tactiques
+        Path path = opt.parameters["path"];
+        score += path.cover_percentage * weights.get("safety");
+        score -= path.threat_level * weights.get("caution");
+
+        // Modifiers
+        for (auto& mod : opt.modifiers) {
+            score *= mod.multiplier;
+        }
+
+        return score;
+    }
+};
+```
+
+**Configuration Poids** :
+```json
+{
+  "tactical_weights": {
+    "safety": 0.4,
+    "caution": 0.3,
+    "aggression": 0.7
+  }
+}
+```
+
+#### OperationalModule
+
+**Responsabilité** : Choix stratégie/posture bataille (heures/jours)
+
+**Décisions prises** :
+- Posture opérationnelle (rush blindé, raid cavalerie, défense en profondeur)
+- Allocation forces entre secteurs
+- Timing offensives
+- Objectifs prioritaires
+
+**Dépendances** :
+- TacticalModule (exécution tactique)
+- DiplomacyModule (contexte stratégique)
+
+**Exemple Décision** :
+```cpp
+class OperationalPostureDecision : public IDecision {
+    std::vector<Option> generateOptions() override {
+        std::vector<Option> postures;
+
+        // Postures disponibles selon doctrine
+        for (auto& [posture_name, posture_weight] : doctrine->operational_weights) {
+            Option opt;
+            opt.type = "posture";
+            opt.parameters["name"] = posture_name;
+            opt.base_score = posture_weight;
+
+            // Évaluer faisabilité
+            if (posture_name == "rush_blinde" && terrain.is_open) {
+                opt.modifiers.push_back({"favorable_terrain", 1.3f});
+            }
+            if (posture_name == "infiltration" && units.has_infantry) {
+                opt.modifiers.push_back({"suitable_units", 1.2f});
+            }
+
+            postures.push_back(opt);
+        }
+
+        return postures;
+    }
+
+    Action execute(const Option& opt) override {
+        std::string posture = opt.parameters["name"];
+
+        // Donner directive au TacticalModule
+        tacticalModule->setPosture(posture);
+
+        // Ajuster poids tactiques selon posture
+        if (posture == "rush_blinde") {
+            tacticalModule->adjustWeights({
+                {"flanking", 1.5f},      // Boost flanking
+                {"caution", 0.5f}        // Réduire caution
+            });
+        }
+
+        return Action{posture, opt.parameters};
+    }
+};
+```
+
+**Doctrines Opérationnelles** :
+
+```json
+// doctrines/ussr.json
+{
+  "name": "USSR Deep Battle",
+  "operational_weights": {
+    "deep_battle": 0.8,
+    "overwhelming_assault": 0.9,
+    "mobile_defense": 0.4,
+    "raid_cavalry": 0.3,
+    "infiltration": 0.2
+  },
+  "tactical_weights": {
+    "frontal_assault": 0.8,
+    "flanking": 0.5,
+    "combined_arms": 0.7,
+    "retreat_threshold": 0.2
+  }
+}
+
+// doctrines/nato.json
+{
+  "name": "NATO AirLand Battle",
+  "operational_weights": {
+    "airland_battle": 0.9,
+    "maneuver_warfare": 0.8,
+    "deep_strike": 0.7,
+    "overwhelming_assault": 0.4,
+    "mobile_defense": 0.6
+  },
+  "tactical_weights": {
+    "frontal_assault": 0.3,
+    "flanking": 0.9,
+    "combined_arms": 0.9,
+    "retreat_threshold": 0.6
+  }
+}
+```
+
+#### CompanyAIModule
+
+**Responsabilité** : Décisions business (jours/semaines)
+
+**Décisions prises** :
+- Investissements R&D
+- Production (quoi produire, combien)
+- Prix et stratégie commerciale
+- Lobbying états
+- Acquisitions/expansions
+
+**Dépendances** :
+- EconomyModule (prix marché, demande)
+- DiplomacyModule (relations, influence)
+
+**Exemple Décision** :
+```cpp
+class CompanyInvestmentDecision : public IDecision {
+    std::vector<Option> generateOptions() override {
+        std::vector<Option> investments;
+
+        // R&D options
+        for (auto& tech : availableTechnologies) {
+            Option opt;
+            opt.type = "research";
+            opt.parameters["tech_id"] = tech.id;
+            opt.parameters["cost"] = tech.research_cost;
+            opt.parameters["expected_profit"] = estimateProfit(tech);
+            opt.base_score = 0.5f;
+
+            if (tech.is_breakthrough) {
+                opt.modifiers.push_back({"breakthrough", 1.5f});
+            }
+
+            investments.push_back(opt);
+        }
+
+        // Production expansion
+        Option expand;
+        expand.type = "expand_production";
+        expand.parameters["cost"] = calculate_expansion_cost();
+        expand.parameters["capacity_increase"] = 0.3f;
+        expand.base_score = 0.4f;
+        investments.push_back(expand);
+
+        // Lobbying
+        for (auto& state : states) {
+            float influence = diplomacy->getInfluence(company_id, state.id);
+            if (influence < 0.8f) {
+                Option lobby;
+                lobby.type = "lobbying";
+                lobby.parameters["state_id"] = state.id;
+                lobby.parameters["cost"] = calculateLobbyCost(state);
+                lobby.parameters["influence_gain"] = 0.1f;
+                lobby.base_score = 0.3f;
+                investments.push_back(lobby);
+            }
+        }
+
+        return investments;
+    }
+
+    float scoreOption(const Option& opt, const Context& ctx) override {
+        float score = opt.base_score;
+
+        if (opt.type == "research") {
+            float expected_profit = opt.parameters["expected_profit"];
+            float cost = opt.parameters["cost"];
+            float roi = expected_profit / cost;
+
+            score += roi * weights.get("innovation");
+            score -= (cost / company_budget) * weights.get("risk_aversion");
+        }
+        else if (opt.type == "lobbying") {
+            float influence_gain = opt.parameters["influence_gain"];
+            score += influence_gain * weights.get("political_focus");
+        }
+
+        for (auto& mod : opt.modifiers) {
+            score *= mod.multiplier;
+        }
+
+        return score;
+    }
+};
+```
+
+**Configuration Company** :
+```json
+{
+  "company_ai_weights": {
+    "innovation": 0.7,
+    "risk_aversion": 0.4,
+    "political_focus": 0.6,
+    "profit_maximization": 0.8,
+    "quality_focus": 0.6
+  }
+}
+```
+
+#### StateAIModule
+
+**Responsabilité** : Décisions étatiques (semaines/mois)
+
+**Décisions prises** :
+- Achats militaires
+- Alliances diplomatiques
+- Budgets sectoriels
+- Objectifs stratégiques
+
+**Dépendances** :
+- DiplomacyModule (relations)
+- EconomyModule (budget disponible)
+- OperationalModule (besoins militaires)
+
+**Exemple Décision** :
+```cpp
+class StateMilitaryPurchaseDecision : public IDecision {
+    std::vector<Option> generateOptions() override {
+        std::vector<Option> purchases;
+
+        // Pour chaque Company
+        for (auto& company : companies) {
+            // Vérifier relation diplomatique
+            float relation = diplomacy->getRelation(state_id, company.id);
+            if (relation < 0.3f) continue; // Trop mauvaise relation
+
+            // Pour chaque véhicule disponible
+            for (auto& vehicle : company.catalog) {
+                Option opt;
+                opt.type = "purchase";
+                opt.parameters["company_id"] = company.id;
+                opt.parameters["vehicle_id"] = vehicle.id;
+                opt.parameters["price"] = vehicle.price;
+                opt.parameters["performance"] = vehicle.combat_rating;
+                opt.base_score = 0.5f;
+
+                // Modifiers
+                if (relation > 0.8f) {
+                    opt.modifiers.push_back({"good_relations", 1.2f});
+                }
+                if (company.reputation > 0.9f) {
+                    opt.modifiers.push_back({"trusted_brand", 1.1f});
+                }
+
+                purchases.push_back(opt);
+            }
+        }
+
+        return purchases;
+    }
+
+    float scoreOption(const Option& opt, const Context& ctx) override {
+        float score = opt.base_score;
+
+        float price = opt.parameters["price"];
+        float performance = opt.parameters["performance"];
+        float value = performance / price;
+
+        score += value * weights.get("cost_effectiveness");
+        score += performance * weights.get("quality_priority");
+
+        // Influence politique
+        CompanyId company = opt.parameters["company_id"];
+        float influence = diplomacy->getInfluence(company, state_id);
+        score += influence * weights.get("lobbying_susceptibility");
+
+        for (auto& mod : opt.modifiers) {
+            score *= mod.multiplier;
+        }
+
+        return score;
+    }
+};
+```
+
+**Configuration State** :
+```json
+{
+  "state_ai_weights": {
+    "cost_effectiveness": 0.6,
+    "quality_priority": 0.7,
+    "lobbying_susceptibility": 0.4,
+    "strategic_autonomy": 0.5
+  }
+}
+```
+
+## Decision Factory
+
+### Création Dynamique
+
+```cpp
+class DecisionFactory {
+public:
+    // Enregistrer types de décisions
+    static void registerDecision(const std::string& type, DecisionCreator creator);
+
+    // Créer décision par nom
+    static IDecision* create(
+        const std::string& type,
+        const Context& ctx,
+        const Weights& weights
+    );
+
+    // Créer avec smart pointer
+    static std::unique_ptr<IDecision> createUnique(
+        const std::string& type,
+        const Context& ctx,
+        const Weights& weights
+    );
+
+private:
+    static std::map<std::string, DecisionCreator> registry;
+};
+
+// Type pour fonction de création
+using DecisionCreator = std::function<IDecision*(const Context&, const Weights&)>;
+```
+
+### Enregistrement Décisions
+
+```cpp
+// Dans l'initialisation du module
+void TacticalModule::initialize() {
+    DecisionFactory::registerDecision("flanking", [](auto ctx, auto weights) {
+        return new FlankingDecision(ctx, weights);
+    });
+
+    DecisionFactory::registerDecision("frontal_assault", [](auto ctx, auto weights) {
+        return new FrontalAssaultDecision(ctx, weights);
+    });
+
+    DecisionFactory::registerDecision("retreat", [](auto ctx, auto weights) {
+        return new RetreatDecision(ctx, weights);
+    });
+}
+```
+
+### Chargement depuis Modules .so
+
+```cpp
+// Hot-reload de nouveaux types de décisions
+void AIFramework::loadDecisionModule(const std::string& module_path) {
+    void* handle = dlopen(module_path.c_str(), RTLD_LAZY);
+
+    // Récupérer fonction d'enregistrement
+    auto registerFunc = (RegisterDecisionsFunc)dlsym(handle, "registerDecisions");
+
+    // Enregistrer les décisions du module
+    registerFunc(DecisionFactory::getInstance());
+}
+```
+
+## Reinforcement Learning Integration
+
+### Ajustement des Poids
+
+Le système RL ajuste les poids selon résultats des décisions :
+
+```cpp
+class RLEngine {
+public:
+    // Enregistrer une décision et son outcome
+    void recordDecision(
+        const std::string& decision_type,
+        const Weights& weights_used,
+        const Option& chosen_option,
+        float outcome_reward  // -1.0 à +1.0
+    );
+
+    // Ajuster poids selon historical performance
+    Weights adjustWeights(
+        const std::string& decision_type,
+        const Weights& current_weights,
+        float learning_rate = 0.1f
+    );
+
+    // Obtenir poids optimisés pour contexte
+    Weights getOptimizedWeights(
+        const std::string& decision_type,
+        const Context& ctx
+    );
+
+private:
+    struct DecisionRecord {
+        Weights weights;
+        Option option;
+        float reward;
+        Context context;
+    };
+
+    std::map<std::string, std::vector<DecisionRecord>> history;
+};
+```
+
+### Exemple RL Tactique
+
+```cpp
+// Enregistrer décision
+auto decision = new FlankingDecision(ctx, current_weights);
+Option best = decision->chooseBest();
+Action action = decision->execute(best);
+delete decision;
+
+// Observer résultat combat
+float outcome = evaluateCombatOutcome(); // -1.0 (défaite) à +1.0 (victoire)
+
+// Enregistrer pour RL
+rlEngine->recordDecision("flanking", current_weights, best, outcome);
+
+// Ajuster poids pour prochaine fois
+Weights new_weights = rlEngine->adjustWeights("flanking", current_weights);
+saveWeights("tactical_flanking_weights.json", new_weights);
+```
+
+### Poids Initiaux (Manuels)
+
+**Important** : En V1, pas de training automatique. Poids configurés manuellement dans JSON.
+
+```json
+// config/ai/tactical_initial_weights.json
+{
+  "flanking": {
+    "safety": 0.4,
+    "caution": 0.3,
+    "aggression": 0.7,
+    "speed": 0.6
+  },
+  "frontal_assault": {
+    "safety": 0.2,
+    "caution": 0.1,
+    "aggression": 0.9,
+    "overwhelming_force": 0.8
+  },
+  "retreat": {
+    "safety": 0.9,
+    "caution": 0.8,
+    "preservation": 0.9
+  }
+}
+```
+
+Le RL ajuste ces valeurs au fil du temps selon expérience.
+
+## Performance et Optimisation
+
+### Object Pooling
+
+Pour éviter new/delete fréquents :
+
+```cpp
+class DecisionPool {
+public:
+    template<typename T>
+    T* acquire(const Context& ctx, const Weights& weights) {
+        if (pool.empty()) {
+            return new T(ctx, weights);
+        }
+        T* obj = pool.back();
+        pool.pop_back();
+        obj->reset(ctx, weights);
+        return obj;
+    }
+
+    template<typename T>
+    void release(T* obj) {
+        pool.push_back(obj);
+    }
+
+private:
+    std::vector<IDecision*> pool;
+};
+```
+
+**Usage** :
+```cpp
+auto decision = decisionPool->acquire<FlankingDecision>(ctx, weights);
+Option best = decision->chooseBest();
+decisionPool->release(decision);
+```
+
+### Parallélisation
+
+Évaluer plusieurs décisions simultanément :
+
+```cpp
+std::vector<Option> evaluateDecisionsParallel(
+    const std::vector<std::string>& decision_types,
+    const Context& ctx,
+    const Weights& weights
+) {
+    std::vector<std::future<Option>> futures;
+
+    for (auto& type : decision_types) {
+        futures.push_back(std::async(std::launch::async, [&]() {
+            auto decision = DecisionFactory::createUnique(type, ctx, weights);
+            return decision->chooseBest();
+        }));
+    }
+
+    std::vector<Option> results;
+    for (auto& future : futures) {
+        results.push_back(future.get());
+    }
+
+    return results;
+}
+```
+
+### Performance Targets
+
+- **TacticalModule** : 60 décisions/seconde (temps-réel combat)
+- **OperationalModule** : 10 décisions/seconde (moins fréquent)
+- **CompanyAI** : 1 décision/seconde (batch processing)
+- **StateAI** : 0.1 décision/seconde (décisions rares)
+
+## Intégration Architecture Modulaire
+
+### AI Framework comme Module
+
+```cpp
+class AIFrameworkModule : public IModule {
+public:
+    void initialize() override {
+        // Charger configurations
+        loadDoctrines("config/doctrines/");
+        loadWeights("config/ai/");
+
+        // Enregistrer décisions
+        registerAllDecisions();
+
+        // Initialiser RL engine
+        rlEngine = new RLEngine();
+    }
+
+    json process(const json& input) override {
+        // Traiter requêtes de décision
+        std::string decision_type = input["decision_type"];
+        Context ctx = Context::fromJson(input["context"]);
+        Weights weights = getWeights(decision_type);
+
+        auto decision = DecisionFactory::createUnique(decision_type, ctx, weights);
+        Option best = decision->chooseBest();
+
+        json output;
+        output["chosen_option"] = best.toJson();
+        return output;
+    }
+
+    void shutdown() override {
+        delete rlEngine;
+    }
+};
+```
+
+### Communication avec Autres Modules
+
+**TacticalModule demande décision** :
+
+```cpp
+// TacticalModule process()
+json request;
+request["decision_type"] = "flanking";
+request["context"] = currentContext.toJson();
+
+json response = sendToModule("ai_framework", request);
+Option chosen = Option::fromJson(response["chosen_option"]);
+
+// Exécuter
+executeOption(chosen);
+```
+
+**OperationalModule configure TacticalModule** :
+
+```cpp
+// OperationalModule choisit posture
+auto decision = new OperationalPostureDecision(ctx, weights);
+Option posture = decision->chooseBest();
+
+// Envoyer directive à TacticalModule
+json directive;
+directive["posture"] = posture.parameters["name"];
+directive["weight_adjustments"] = calculateAdjustments(posture);
+
+sendToModule("tactical", directive);
+```
+
+## Configuration et Données
+
+### Structure Fichiers Config
+
+```
+config/
+├── ai/
+│   ├── tactical_weights.json
+│   ├── operational_weights.json
+│   ├── company_weights.json
+│   └── state_weights.json
+├── doctrines/
+│   ├── ussr.json
+│   ├── nato.json
+│   ├── china.json
+│   └── guerrilla.json
+└── rl/
+    ├── learning_rates.json
+    └── reward_functions.json
+```
+
+### Exemple Configuration Complète
+
+**config/ai/tactical_weights.json** :
+```json
+{
+  "flanking": {
+    "safety": 0.4,
+    "caution": 0.3,
+    "aggression": 0.7,
+    "speed": 0.6,
+    "stealth": 0.5
+  },
+  "frontal_assault": {
+    "safety": 0.2,
+    "caution": 0.1,
+    "aggression": 0.9,
+    "overwhelming_force": 0.8,
+    "speed": 0.4
+  },
+  "suppression": {
+    "safety": 0.6,
+    "rate_of_fire": 0.9,
+    "ammunition_conservation": 0.3,
+    "area_denial": 0.8
+  },
+  "retreat": {
+    "safety": 0.9,
+    "caution": 0.8,
+    "preservation": 0.9,
+    "speed": 0.7,
+    "covering_fire": 0.6
+  }
+}
+```
+
+**config/doctrines/ussr.json** (complet) :
+```json
+{
+  "name": "USSR Deep Battle Doctrine",
+  "description": "Emphasis on overwhelming force, combined arms, and continuous offensive operations",
+
+  "operational_weights": {
+    "deep_battle": 0.8,
+    "overwhelming_assault": 0.9,
+    "echeloned_attack": 0.7,
+    "mobile_defense": 0.4,
+    "raid_cavalry": 0.3,
+    "infiltration": 0.2,
+    "attritional_warfare": 0.6
+  },
+
+  "tactical_weights": {
+    "frontal_assault": 0.8,
+    "flanking": 0.5,
+    "combined_arms": 0.7,
+    "artillery_preparation": 0.9,
+    "retreat_threshold": 0.2,
+    "counterattack": 0.7,
+    "urban_combat": 0.6
+  },
+
+  "resource_priorities": {
+    "armor_quantity": 0.9,
+    "artillery": 0.8,
+    "infantry_mass": 0.7,
+    "air_support": 0.5,
+    "logistics": 0.6
+  },
+
+  "special_characteristics": {
+    "accepts_high_casualties": true,
+    "prefers_night_operations": true,
+    "emphasizes_political_officers": true
+  }
+}
+```
+
+**config/doctrines/nato.json** (complet) :
+```json
+{
+  "name": "NATO AirLand Battle Doctrine",
+  "description": "Deep strike, maneuver warfare, and combined arms with heavy air integration",
+
+  "operational_weights": {
+    "airland_battle": 0.9,
+    "maneuver_warfare": 0.8,
+    "deep_strike": 0.7,
+    "defensive_depth": 0.6,
+    "overwhelming_assault": 0.4,
+    "mobile_defense": 0.6,
+    "decapitation_strike": 0.7
+  },
+
+  "tactical_weights": {
+    "frontal_assault": 0.3,
+    "flanking": 0.9,
+    "combined_arms": 0.9,
+    "artillery_preparation": 0.6,
+    "retreat_threshold": 0.6,
+    "air_strikes": 0.9,
+    "precision_engagement": 0.8
+  },
+
+  "resource_priorities": {
+    "armor_quality": 0.9,
+    "air_superiority": 0.9,
+    "precision_munitions": 0.8,
+    "C4ISR": 0.9,
+    "logistics": 0.8
+  },
+
+  "special_characteristics": {
+    "accepts_high_casualties": false,
+    "prefers_technology_advantage": true,
+    "emphasizes_initiative": true
+  }
+}
+```
+
+## Évolution Future
+
+### Version 2 : Apprentissage Actif
+
+- **Auto-training** : RL s'entraîne via simulations automatiques
+- **Meta-learning** : Adaptation rapide à nouvelles situations
+- **Transfer learning** : Connaissances transférées entre doctrines
+
+### Version 3 : Comportements Émergents
+
+- **Genetic algorithms** : Companies/States évoluent génération par génération
+- **Multi-agent RL** : Plusieurs IA apprennent en compétition/coopération
+- **Adaptive doctrines** : Doctrines mutent selon expérience
+
+### Version 4 : Neural Networks
+
+- **Deep RL** : Réseaux neurones pour décisions complexes
+- **Pattern recognition** : Reconnaître situations similaires historiques
+- **Predictive modeling** : Anticiper actions adversaires
+
+## Références Croisées
+
+- `systeme-militaire.md` : Combat, véhicules, doctrines militaires
+- `economie-logistique.md` : Marché, pricing, supply chains
+- `architecture-modulaire.md` : Intégration modules, hot-reload
+- `systeme-sauvegarde.md` : Persistence états IA, poids RL
+
+## Exemples Pratiques
+
+### Exemple Complet : Décision Tactique
+
+```cpp
+// Contexte bataille
+Context ctx;
+ctx.world_state = {
+    {"terrain", "open_plains"},
+    {"weather", "clear"},
+    {"time_of_day", "dawn"}
+};
+ctx.entities = {
+    {"my_units", {{"tanks", 10}, {"ifv", 5}}},
+    {"enemy_units", {{"tanks", 8}, {"infantry", 20}}}
+};
+ctx.objectives = {
+    {"primary", "secure_hill"},
+    {"secondary", "minimize_casualties"}
+};
+ctx.doctrine = doctrineManager->getDoctrine("nato");
+
+// Charger poids
+Weights weights = loadWeights("config/ai/tactical_weights.json", "flanking");
+
+// Créer décision
+auto decision = DecisionFactory::createUnique("flanking", ctx, weights);
+
+// Générer et évaluer options
+std::vector<Option> options = decision->generateOptions();
+for (auto& opt : options) {
+    float score = decision->scoreOption(opt, ctx);
+    LOG_DEBUG("Option: {} - Score: {}", opt.type, score);
+}
+
+// Choisir meilleure
+Option best = decision->chooseBest();
+LOG_INFO("Chosen: {} (score: {})", best.type, best.base_score);
+
+// Exécuter
+Action action = decision->execute(best);
+
+// Observer résultat et apprendre
+float outcome = waitForBattleResult();
+rlEngine->recordDecision("flanking", weights, best, outcome);
+```
+
+### Exemple : Company AI Investment
+
+```cpp
+// Contexte company
+Context ctx;
+ctx.world_state = {
+    {"market_demand", "high"},
+    {"tech_level", "gen3"},
+    {"competition", "moderate"}
+};
+ctx.entities = {
+    {"budget", 1000000},
+    {"reputation", 0.75},
+    {"research_capacity", 5}
+};
+
+Weights weights = companyProfile.weights; // Profil company unique
+
+auto decision = new CompanyInvestmentDecision(ctx, weights);
+Option investment = decision->chooseBest();
+
+if (investment.type == "research") {
+    TechId tech = investment.parameters["tech_id"];
+    startResearch(tech);
+}
+else if (investment.type == "lobbying") {
+    StateId state = investment.parameters["state_id"];
+    float cost = investment.parameters["cost"];
+    lobbyState(state, cost);
+}
+
+delete decision;
+```
+
+## Testing et Validation
+
+### Test Unitaire Decision
+
+```cpp
+#ifdef TESTING
+void testFlankingDecision() {
+    // Setup contexte test
+    Context ctx = createTestContext();
+    Weights weights = {{"safety", 0.5}, {"aggression", 0.8}};
+
+    // Créer décision
+    auto decision = new FlankingDecision(ctx, weights);
+
+    // Vérifier génération options
+    auto options = decision->generateOptions();
+    assert(options.size() > 0);
+
+    // Vérifier scoring
+    for (auto& opt : options) {
+        float score = decision->scoreOption(opt, ctx);
+        assert(score >= 0.0f && score <= 1.0f);
+    }
+
+    // Vérifier choix cohérent
+    Option best = decision->chooseBest();
+    assert(best.type == "flanking");
+
+    delete decision;
+}
+#endif
+```
+
+### Benchmark Performance
+
+```cpp
+void benchmarkDecisionSpeed() {
+    Context ctx = createBenchmarkContext();
+    Weights weights = loadWeights("tactical_weights.json", "flanking");
+
+    auto start = std::chrono::high_resolution_clock::now();
+
+    for (int i = 0; i < 1000; i++) {
+        auto decision = new FlankingDecision(ctx, weights);
+        Option best = decision->chooseBest();
+        delete decision;
+    }
+
+    auto end = std::chrono::high_resolution_clock::now();
+    auto duration = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
+
+    std::cout << "1000 decisions in " << duration.count() << "μs\n";
+    std::cout << "Average: " << (duration.count() / 1000.0f) << "μs per decision\n";
+}
+```
diff --git a/docs/calcul-menace.md b/docs/calcul-menace.md
new file mode 100644
index 0000000..979797e
--- /dev/null
+++ b/docs/calcul-menace.md
@@ -0,0 +1,752 @@
+# Calcul de Menace Contextuelle
+
+## Vue d'Ensemble
+
+Le système de calcul de menace évalue la **dangerosité qu'une entité représente pour une autre** en analysant non seulement les forces brutes, mais aussi les capacités défensives, la qualité des équipements, et la production industrielle.
+
+### Principes Fondamentaux
+
+- **Contextuel** : Menace calculée selon capacités **des deux parties**
+- **Asymétrique** : A menace B ≠ B menace A
+- **Sword & Shield** : Qualité défenses peut annuler supériorité numérique
+- **Production** : Capacité industrielle = menace future
+- **Multi-domaines** : Terre, air, mer évalués séparément puis agrégés
+
+## Échelle de Menace
+
+**Valeurs** : `0` à `2 000 000+` (pas de maximum strict, type `int32_t`)
+
+**Ordres de grandeur** :
+- `0` : Aucune menace
+- `100 - 1 000` : PMC petit
+- `5 000 - 50 000` : Company moyenne
+- `100 000` : État petit
+- `500 000` : État moyen (France, UK, Allemagne)
+- `900 000` : Superpower (USA, Chine, Russie)
+- `1 000 000+` : Menace existentielle
+
+## Architecture Calcul
+
+### Formule Globale
+
+```cpp
+int calculateThreat(Entity attacker, Entity defender) {
+    auto params = attacker.getThreatParams();
+
+    // Composantes
+    int current_military = evaluateCurrentForces(attacker, defender);
+    int production_capacity = evaluateProduction(attacker, defender, params.projection_months);
+
+    // Pondération configurable par entité
+    return current_military * params.current_weight +
+           production_capacity * params.production_weight;
+}
+
+struct ThreatCalculationParams {
+    int projection_months = 12;      // Horizon projection (défaut 12 mois)
+    float current_weight = 0.6f;     // Poids forces actuelles (60%)
+    float production_weight = 0.4f;  // Poids production (40%)
+};
+```
+
+**Personnalisation par entité** :
+- Company **agressive** : `current: 0.8, production: 0.2` (focus court-terme)
+- State **prudent** : `current: 0.4, production: 0.6` (focus long-terme)
+- PMC **réactif** : `current: 0.9, production: 0.1` (menace immédiate prioritaire)
+
+## Évaluation Forces Actuelles
+
+### Principe : Sword & Shield
+
+Pour chaque domaine (terre, air, mer), on évalue :
+1. **Sword** (attaquant) : Capacités offensives
+2. **Shield** (défenseur) : Capacités défensives
+3. **Effectiveness** : Dans quelle mesure le shield arrête le sword
+
+```cpp
+int evaluateCurrentForces(Entity attacker, Entity defender) {
+    int land_threat = evaluateLandThreat(attacker, defender);
+    int air_threat = evaluateAirThreat(attacker, defender);
+    int naval_threat = evaluateNavalThreat(attacker, defender);
+
+    return land_threat + air_threat + naval_threat;
+}
+```
+
+### Évaluation Domaine Terrestre
+
+#### Inventaire Forces
+
+**Attaquant** :
+```cpp
+struct LandForces {
+    std::vector<Tank> tanks;
+    std::vector<IFV> ifvs;
+    std::vector<APC> apcs;
+    std::vector<Artillery> artillery;
+    std::vector<Infantry> infantry;
+};
+```
+
+**Défenseur** :
+```cpp
+struct LandDefenses {
+    std::vector<ATSystem> anti_tank;      // Systèmes anti-char
+    std::vector<Tank> counter_tanks;      // Tanks défensifs
+    std::vector<Infantry> anti_tank_inf;  // Infanterie AT
+    std::vector<Fortification> fortifications;
+};
+```
+
+#### Couples Équipement ↔ Contre-mesures
+
+**Principe** : Chaque type d'équipement offensif a des contre-mesures spécifiques.
+
+```cpp
+struct EquipmentCounters {
+    std::map<EquipmentType, std::vector<CounterType>> counters = {
+        {TANK, {AT_MISSILE, AT_GUN, COUNTER_TANK, AT_INFANTRY}},
+        {IFV, {AT_MISSILE, AT_GUN, AUTOCANNON}},
+        {APC, {AUTOCANNON, MACHINE_GUN, RPG}},
+        {INFANTRY, {MACHINE_GUN, ARTILLERY, AUTOCANNON}},
+        {ARTILLERY, {COUNTER_BATTERY, AIR_STRIKE}}
+    };
+};
+```
+
+#### Évaluation Sword vs Shield
+
+**Étape 1 : Match-making**
+
+Pour chaque équipement offensif, identifier contre-mesures défensives applicables :
+
+```cpp
+std::vector<Defense> findApplicableDefenses(
+    Equipment sword,
+    std::vector<Defense> available_defenses
+) {
+    std::vector<Defense> applicable;
+
+    auto counters = EquipmentCounters::counters[sword.type];
+
+    for (auto& defense : available_defenses) {
+        // Vérifier si défense peut contrer cet équipement
+        if (std::find(counters.begin(), counters.end(), defense.type) != counters.end()) {
+            // Vérifier compatibilité génération/qualité
+            if (canCounter(defense, sword)) {
+                applicable.push_back(defense);
+            }
+        }
+    }
+
+    return applicable;
+}
+
+bool canCounter(Defense defense, Equipment sword) {
+    // Exemple : AT missile Gen2 ne peut pas contrer tank Gen4 avec armure avancée
+    if (defense.generation < sword.generation - 1) {
+        return false;  // Trop ancien
+    }
+
+    // Vérifier spécificités
+    if (sword.has_reactive_armor && defense.type == AT_MISSILE_OLD) {
+        return false;  // ERA bloque missiles anciens
+    }
+
+    return true;
+}
+```
+
+**Étape 2 : Calcul Defensive Effectiveness**
+
+```cpp
+float calculateDefensiveEffectiveness(
+    std::vector<Equipment> swords,
+    std::vector<Defense> shields
+) {
+    float total_sword_value = 0;
+    float neutralized_value = 0;
+
+    for (auto& sword : swords) {
+        float sword_value = sword.quantity * sword.quality;
+        total_sword_value += sword_value;
+
+        // Trouver défenses applicables
+        auto applicable_shields = findApplicableDefenses(sword, shields);
+
+        // Calculer valeur défensive totale contre ce sword
+        float shield_value = 0;
+        for (auto& shield : applicable_shields) {
+            float shield_effectiveness = calculateShieldEffectiveness(shield, sword);
+            shield_value += shield.quantity * shield.quality * shield_effectiveness;
+        }
+
+        // Neutralisation proportionnelle
+        float neutralization = min(1.0f, shield_value / sword_value);
+        neutralized_value += sword_value * neutralization;
+    }
+
+    return total_sword_value > 0 ? (neutralized_value / total_sword_value) : 0.0f;
+}
+```
+
+**Étape 3 : Score Final**
+
+```cpp
+int evaluateLandThreat(Entity attacker, Entity defender) {
+    auto swords = attacker.getLandForces();
+    auto shields = defender.getLandDefenses();
+
+    // Menace brute (sans défenses)
+    int raw_threat = 0;
+    for (auto& sword : swords) {
+        raw_threat += sword.quantity * sword.combat_value;
+    }
+
+    // Réduction par défenses
+    float defensive_effectiveness = calculateDefensiveEffectiveness(swords, shields);
+
+    // Menace finale
+    int final_threat = raw_threat * (1.0f - defensive_effectiveness);
+
+    return final_threat;
+}
+```
+
+### Exemples Concrets Terre
+
+#### Exemple 1 : Qualité Domine Quantité
+
+**Attaquant** :
+- 20 tanks Gen4 (Leopard 2A7)
+  - Armure composite avancée
+  - Génération 4
+  - Combat value : 1000/tank
+  - Menace brute : 20 × 1000 = 20 000
+
+**Défenseur** :
+- 100 000 AT missiles Gen2
+  - Anciens, inefficaces contre armure Gen4
+  - `canCounter()` retourne `false`
+  - Défense applicable : 0
+
+**Résultat** :
+```
+defensive_effectiveness = 0 / 20000 = 0%
+final_threat = 20000 × (1 - 0) = 20 000
+```
+→ **Menace élevée** : Défenses obsolètes inefficaces
+
+#### Exemple 2 : Quantité + Qualité Écrasent
+
+**Attaquant** :
+- 1000 tanks Gen2
+  - Armure standard
+  - Combat value : 400/tank
+  - Menace brute : 1000 × 400 = 400 000
+
+**Défenseur** :
+- 500 AT missiles Gen4 (Javelin)
+  - Top-attack, très efficaces
+  - Combat value : 800/missile
+  - `canCounter()` retourne `true`
+  - Shield effectiveness : 0.9 (très efficace)
+  - Shield value : 500 × 800 × 0.9 = 360 000
+
+**Résultat** :
+```
+defensive_effectiveness = 360000 / 400000 = 90%
+final_threat = 400000 × (1 - 0.9) = 40 000
+```
+→ **Menace faible** : Défenses qualitatives réduisent massavement
+
+#### Exemple 3 : Masse Insuffisante
+
+**Attaquant** :
+- 1000 tanks Gen2
+  - Combat value : 400/tank
+  - Menace brute : 400 000
+
+**Défenseur** :
+- 20 AT missiles Gen4
+  - Très efficaces mais **pas assez nombreux**
+  - Shield value : 20 × 800 × 0.9 = 14 400
+
+**Résultat** :
+```
+defensive_effectiveness = 14400 / 400000 = 3.6%
+final_threat = 400000 × (1 - 0.036) = 385 440
+```
+→ **Menace reste élevée** : Pas assez de défenses pour couvrir la masse
+
+### Évaluation Domaine Aérien
+
+#### Spécificités Air
+
+**Complexité supplémentaire** :
+- **Qualité prime** : Quelques jets furtifs Gen4 dominent des centaines AA Gen2
+- **ECM/ECCM** : Guerre électronique critique
+- **Compatibilité stricte** : AA anti-hélicoptère ne touche pas jets
+
+```cpp
+struct AirForces {
+    std::vector<Fighter> fighters;
+    std::vector<Bomber> bombers;
+    std::vector<Helicopter> helicopters;
+    std::vector<Drone> drones;
+
+    // Capacités spéciales
+    bool has_stealth;
+    bool has_ecm;           // Electronic Counter-Measures
+    int electronic_warfare_level;
+};
+
+struct AirDefenses {
+    std::vector<AAMissile> aa_missiles;
+    std::vector<AAGun> aa_guns;
+    std::vector<Fighter> interceptors;
+
+    // Capacités
+    bool has_eccm;          // Electronic Counter-Counter-Measures
+    int radar_quality;
+    std::map<AASystem, TargetCapability> capabilities;  // Quoi peut toucher quoi
+};
+
+enum TargetCapability {
+    HELICOPTER_ONLY,        // Seulement hélicoptères
+    LOW_ALTITUDE,           // Avions basse altitude
+    HIGH_ALTITUDE,          // Avions haute altitude
+    ALL_AIRCRAFT            // Tous types
+};
+```
+
+#### Compatibilité Systèmes
+
+```cpp
+bool canEngageAircraft(AASystem aa, Aircraft aircraft) {
+    // Vérifier compatibilité type
+    switch (aa.capability) {
+        case HELICOPTER_ONLY:
+            return aircraft.type == HELICOPTER;
+
+        case LOW_ALTITUDE:
+            return aircraft.altitude < 5000;  // mètres
+
+        case HIGH_ALTITUDE:
+            return aircraft.altitude > 5000;
+
+        case ALL_AIRCRAFT:
+            return true;
+    }
+
+    // Vérifier guerre électronique
+    if (aircraft.has_ecm && !aa.has_eccm) {
+        // ECM peut brouiller AA sans ECCM
+        float jam_probability = aircraft.ecm_power / (aa.radar_quality + 1);
+        if (randomFloat() < jam_probability) {
+            return false;  // Brouillé
+        }
+    }
+
+    // Vérifier furtivité
+    if (aircraft.has_stealth) {
+        float detection_range = aa.radar_range * (1.0f - aircraft.stealth_rating);
+        if (distance(aa, aircraft) > detection_range) {
+            return false;  // Pas détecté
+        }
+    }
+
+    return true;
+}
+```
+
+#### Exemple Air : Furtivité Domine
+
+**Attaquant** :
+- 20 jets furtifs Gen4 (F-35)
+  - Stealth rating : 0.9 (réduit détection 90%)
+  - ECM avancé
+  - Combat value : 2000/jet
+  - Menace brute : 40 000
+
+**Défenseur** :
+- 100 000 AA missiles Gen2
+  - Radar standard
+  - Pas ECCM
+  - Seulement 5% peuvent détecter/engager les furtifs
+  - Shield value effectif : 100000 × 0.05 × 300 = 1 500 000... mais avec ECM :
+  - Shield value final : 1 500 000 × 0.1 (jam rate) = 150 000
+
+```
+defensive_effectiveness = 150000 / 40000 = ... wait, > 1.0 !
+→ Plafonné à min(1.0, value)
+defensive_effectiveness = min(1.0, 150000/40000) = 1.0...
+
+ERREUR dans mon calcul !
+```
+
+**Correction** : Le shield value doit être calculé par aircraft, pas globalement.
+
+```cpp
+// Pour chaque jet
+for (auto& jet : jets) {
+    float jet_value = jet.combat_value;
+
+    // Combien de AA peuvent l'engager ?
+    int applicable_aa = 0;
+    for (auto& aa : aa_systems) {
+        if (canEngageAircraft(aa, jet)) {
+            applicable_aa++;
+        }
+    }
+
+    // Shield value pour ce jet spécifique
+    float shield_value = applicable_aa * aa_combat_value;
+    float neutralization = min(1.0f, shield_value / jet_value);
+
+    threat_reduced += jet_value * neutralization;
+}
+```
+
+**Résultat corrigé** :
+- 5000 AA peuvent engager (sur 100k)
+- Pour 1 jet : shield = 5000 × 300 = 1 500 000 vs jet = 2000
+- Neutralization = 100% par jet
+- Mais ils peuvent pas tous tirer simultanément !
+
+**Contrainte simultanéité** :
+
+```cpp
+// Limite engagement simultané
+int max_simultaneous = min(applicable_aa, ENGAGEMENT_LIMIT);
+// Exemple : Max 100 missiles simultanés par cible
+
+float shield_value = max_simultaneous * aa_combat_value;
+```
+
+Avec limite 100 simultanés :
+- Shield = 100 × 300 = 30 000 vs jet = 2000
+- Neutralization = 100% par jet
+- Mais 20 jets → seulement 2000 engagements simultanés total
+- Si AA rate coordination : menace reste
+
+**C'est complexe !** Donc en pratique :
+
+```cpp
+float calculateAirDefenseEffectiveness(
+    std::vector<Aircraft> aircraft,
+    std::vector<AASystem> aa_systems
+) {
+    float total_threat = 0;
+    float neutralized = 0;
+
+    for (auto& ac : aircraft) {
+        total_threat += ac.combat_value;
+
+        // Compter AA applicables
+        int applicable_count = 0;
+        for (auto& aa : aa_systems) {
+            if (canEngageAircraft(aa, ac)) {
+                applicable_count++;
+            }
+        }
+
+        // Engagement limité
+        int engaged = min(applicable_count, MAX_SIMULTANEOUS_PER_TARGET);
+
+        // Probabilité kill
+        float kill_probability = engaged / float(ENGAGEMENTS_NEEDED_FOR_KILL);
+        kill_probability = min(1.0f, kill_probability);
+
+        neutralized += ac.combat_value * kill_probability;
+    }
+
+    return total_threat > 0 ? (neutralized / total_threat) : 0.0f;
+}
+```
+
+### Évaluation Domaine Naval
+
+**Similaire à terrestre/aérien** mais avec spécificités :
+- **Torpilles vs sonars** (submersibles)
+- **Anti-ship missiles vs CIWS** (Close-In Weapon Systems)
+- **Portée extrême** : Naval combat à 100+ km
+
+Structure identique avec couples spécifiques.
+
+## Évaluation Production
+
+### Principe
+
+La menace ne vient pas seulement des forces actuelles, mais aussi de la **capacité à produire** plus d'équipements.
+
+```cpp
+int evaluateProduction(Entity attacker, Entity defender, int projection_months) {
+    int production_threat = 0;
+
+    // Pour chaque type d'équipement
+    for (auto& equipment_type : all_equipment_types) {
+        // Taux production attaquant
+        int attacker_rate = attacker.getProductionRate(equipment_type);  // unités/mois
+
+        // Taux production défenses défenseur
+        int defender_rate = defender.getProductionRate(getCounterType(equipment_type));
+
+        // Projection future
+        int attacker_produced = attacker_rate * projection_months;
+        int defender_produced = defender_rate * projection_months;
+
+        // Menace nette production
+        int net_production = attacker_produced - defender_produced;
+        if (net_production > 0) {
+            int equipment_value = getEquipmentValue(equipment_type);
+            production_threat += net_production * equipment_value;
+        }
+    }
+
+    return production_threat;
+}
+```
+
+### Exemple Production
+
+**État A** :
+- Production actuelle : 50 tanks/mois
+- Projection 12 mois : 600 tanks
+- Combat value : 400/tank
+- Production threat : 600 × 400 = 240 000
+
+**État B** (défenseur) :
+- Production AT : 100 missiles/mois
+- Projection 12 mois : 1200 missiles
+- Combat value : 300/missile
+- Défense production : 1200 × 300 = 360 000
+
+**Net production threat** :
+```
+Attacker gain : 240 000
+Defender gain : 360 000
+Net : 240 000 - 360 000 = -120 000 (négatif = défenseur gagne)
+
+production_threat = max(0, net) = 0
+```
+
+→ État B a **meilleure production**, donc menace production de A est nulle.
+
+**Si inverse** :
+
+**État A** :
+- Production : 200 tanks/mois → 2400 tanks/an
+- Threat : 2400 × 400 = 960 000
+
+**État B** :
+- Production AT : 50 missiles/mois → 600 missiles/an
+- Défense : 600 × 300 = 180 000
+
+**Net** : 960 000 - 180 000 = 780 000
+
+→ État A a **production écrasante**, menace industrielle massive.
+
+## Agrégation Finale
+
+### Formule Complète
+
+```cpp
+int calculateThreat(Entity attacker, Entity defender) {
+    auto params = attacker.getThreatParams();
+
+    // Forces actuelles (sword & shield par domaine)
+    int land_threat = evaluateLandThreat(attacker, defender);
+    int air_threat = evaluateAirThreat(attacker, defender);
+    int naval_threat = evaluateNavalThreat(attacker, defender);
+
+    int current_military = land_threat + air_threat + naval_threat;
+
+    // Production future
+    int production_threat = evaluateProduction(
+        attacker,
+        defender,
+        params.projection_months
+    );
+
+    // Pondération finale
+    int total_threat = current_military * params.current_weight +
+                       production_threat * params.production_weight;
+
+    return total_threat;
+}
+```
+
+### Exemples Complets
+
+#### Superpower vs État Moyen
+
+**USA vs France**
+
+**USA forces** :
+- Tanks : 8000 (Gen3-4) → 3 200 000
+- Aircraft : 2000 (Gen4, furtifs) → 4 000 000
+- Naval : 500 ships → 2 500 000
+- **Total brut** : 9 700 000
+
+**France défenses** :
+- AT systems : 3000 (Gen3) → Shield 50% tanks
+- AA systems : 1500 (Gen3) → Shield 30% aircraft
+- Naval defenses : 200 → Shield 40% naval
+
+**Après sword & shield** :
+- Land : 3 200 000 × 0.5 = 1 600 000
+- Air : 4 000 000 × 0.7 = 2 800 000
+- Naval : 2 500 000 × 0.6 = 1 500 000
+- **Current threat** : 5 900 000
+
+**Production (12 mois)** :
+- USA : +600 tanks, +100 aircraft → 360 000
+- France : +100 tanks, +50 aircraft → 70 000
+- **Net production** : 290 000
+
+**Total (60% current, 40% prod)** :
+```
+5 900 000 × 0.6 + 290 000 × 0.4 = 3 656 000
+```
+
+→ **Menace colossale**, mais France peut tenir avec alliances
+
+#### PMC vs Company
+
+**PMC_Alpha vs RheinmetallCorp**
+
+**PMC forces** :
+- Infantry : 500 (léger armement)
+- Vehicles : 20 APCs
+- **Total** : 50 000
+
+**Rheinmetall défenses** :
+- Security : 100 guards
+- Fortifications : minimal
+- **Shield** : 5%
+
+**Threat** : 50 000 × 0.95 = 47 500
+
+→ PMC peut menacer installations Company, mais pas capacités production
+
+## Cas Spéciaux
+
+### Menace Économique Pure
+
+Pour Companies sans capacités militaires :
+
+```cpp
+int calculateEconomicThreat(Company attacker, Company defender) {
+    // Part de marché
+    float market_dominance = attacker.market_share / (defender.market_share + 0.01f);
+
+    // Capacité production
+    float production_ratio = attacker.production_capacity / defender.production_capacity;
+
+    // Qualité produits
+    float quality_advantage = attacker.avg_product_quality / defender.avg_product_quality;
+
+    // Menace économique
+    int economic_threat = (market_dominance * 100000) +
+                          (production_ratio * 80000) +
+                          (quality_advantage * 50000);
+
+    return economic_threat;
+}
+```
+
+### Menace Géographique
+
+Distance géographique module menace :
+
+```cpp
+float getGeographicModifier(Entity attacker, Entity defender) {
+    float distance_km = calculateDistance(attacker.position, defender.position);
+
+    // Projection power diminue avec distance
+    if (distance_km < 500) {
+        return 1.0f;  // Menace pleine
+    }
+    else if (distance_km < 2000) {
+        return 0.7f;  // 30% réduction
+    }
+    else if (distance_km < 5000) {
+        return 0.4f;  // 60% réduction
+    }
+    else {
+        return 0.1f;  // 90% réduction (trop loin)
+    }
+}
+```
+
+## Performance et Optimisation
+
+### Cache Threat
+
+```cpp
+class ThreatCache {
+private:
+    struct CachedThreat {
+        int value;
+        int timestamp;
+        int ttl = 3600;  // 1 heure
+    };
+
+    std::map<std::pair<EntityId, EntityId>, CachedThreat> cache;
+
+public:
+    int getThreat(EntityId attacker, EntityId defender) {
+        auto key = std::make_pair(attacker, defender);
+
+        if (cache.contains(key)) {
+            auto& cached = cache[key];
+            if (getCurrentTime() - cached.timestamp < cached.ttl) {
+                return cached.value;
+            }
+        }
+
+        // Recalculer
+        int threat = calculateThreat(attacker, defender);
+        cache[key] = {threat, getCurrentTime()};
+        return threat;
+    }
+
+    void invalidate(EntityId entity) {
+        // Invalider tous les caches impliquant cette entité
+        for (auto it = cache.begin(); it != cache.end();) {
+            if (it->first.first == entity || it->first.second == entity) {
+                it = cache.erase(it);
+            } else {
+                ++it;
+            }
+        }
+    }
+};
+```
+
+### Invalidation Cache
+
+Événements invalidant cache :
+- Production nouvelle unité
+- Perte unité au combat
+- Nouvelle recherche technologique
+- Changement doctrine militaire
+
+### Calcul Lazy
+
+```cpp
+// Ne calculer que si demandé par IA
+int getThreatOnDemand(EntityId attacker, EntityId defender) {
+    return threatCache.getThreat(attacker, defender);
+}
+
+// Pas de recalcul automatique chaque tick
+```
+
+## Références Croisées
+
+- `systeme-diplomatique.md` : Utilisation menace dans relations diplomatiques
+- `ai-framework.md` : Menace influence décisions IA (achats, alliances)
+- `systeme-militaire.md` : Valeurs combat équipements, générations
+- `economie-logistique.md` : Production rates, capacités industrielles
diff --git a/docs/systeme-diplomatique.md b/docs/systeme-diplomatique.md
new file mode 100644
index 0000000..daeebe6
--- /dev/null
+++ b/docs/systeme-diplomatique.md
@@ -0,0 +1,1090 @@
+# Système Diplomatique
+
+## Vue d'Ensemble
+
+Le système diplomatique de Warfactory gère les relations entre toutes les entités du jeu : États (States), Compagnies (Companies), et PMCs. Il repose sur **quatre indicateurs numériques** distincts qui interagissent pour créer des comportements diplomatiques émergents et réalistes.
+
+### Principes de Design
+
+- **Relations partagées** : Une seule valeur relation entre deux entités, état actuel de la relation
+- **Intentions bilatérales** : Chaque entité a sa propre intention envers l'autre
+- **Intentions génèrent événements** : Intentions modifient le score relation partagé via événements
+- **Menace contextuelle** : Évaluation sophistiquée des forces selon capacités défensives
+- **Fiabilité globale** : Réputation qui se construit/détruit avec le temps
+- **Traités comme objets** : Accords formalisés avec impact mécanique
+
+## Les Quatre Indicateurs
+
+### 1. Relations (Score Partagé)
+
+**Définition** : Score unique représentant l'état actuel de la relation entre deux entités.
+
+**Échelle** : `-1000` à `+1000`
+- `-1000` : Hostilité maximale, guerre totale
+- `-500` : Relations très mauvaises, sanctions, embargo
+- `0` : Neutre, aucune relation particulière
+- `+500` : Relations bonnes, coopération active
+- `+1000` : Alliance parfaite, confiance totale
+
+**Caractéristiques** :
+- **Partagé** : `A ↔ B` = **une seule valeur** pour les deux entités
+- **Par événements** : Score modifié uniquement via événements discrets
+- **Entiers** : Valeurs entières pour garantir balance exacte
+- **Persistant** : Sauvegardé avec historique événements
+- **État, pas intention** : Représente situation actuelle, pas désirs futurs
+
+#### Structure Données
+
+```cpp
+struct Relationship {
+    std::pair<EntityId, EntityId> entities;  // Paire ordonnée (smaller_id, larger_id)
+    int score;                               // -1000 à +1000
+    std::vector<Event> events;               // Historique complet
+    int decay_target;                        // Calculé depuis traités
+};
+
+struct Event {
+    EventType type;
+    int value;                    // Impact sur score (-500 à +500)
+    EntityId source;              // Qui a généré l'événement
+    int date;                     // Timestamp événement
+    std::string description;      // Pour logs/UI
+};
+
+// Accès relation (ordre des IDs n'importe pas)
+int getRelation(EntityId a, EntityId b) {
+    auto key = makeRelationKey(a, b);  // Ordre normalisé
+    return relationships[key].score;
+}
+
+std::pair<EntityId, EntityId> makeRelationKey(EntityId a, EntityId b) {
+    return (a < b) ? std::make_pair(a, b) : std::make_pair(b, a);
+}
+```
+
+#### Exemples Événements
+
+**Événements Positifs** :
+- `contract_fulfilled` : +100 (livraison contrat à temps)
+- `military_aid` : +200 (aide militaire fournie)
+- `tech_sharing` : +150 (partage technologie)
+- `lobbying_success` : +50 (campagne lobbying réussie)
+- `joint_operation` : +180 (opération militaire conjointe)
+- `trade_agreement` : +120 (nouvel accord commercial)
+
+**Événements Négatifs** :
+- `contract_breach` : -150 (contrat non-honoré)
+- `espionage_caught` : -300 (espionnage découvert)
+- `reverse_engineering` : -200 (reverse-engineer produit acheté)
+- `civilian_casualties` : -250 (dommages collatéraux)
+- `embargo_violation` : -180 (violation embargo)
+- `treaty_broken` : -500 (rupture traité formel)
+
+**Événements Massifs** :
+- `declaration_war` : -800
+- `peace_treaty` : +400
+- `alliance_formed` : +600
+
+#### Decay Relations
+
+Les relations ne restent pas fixes, elles **decay vers un score cible** déterminé par les traités actifs.
+
+**Formule Decay Target** :
+
+```cpp
+int calculateDecayTarget(EntityId a, EntityId b) {
+    int target = 0;  // Base neutre
+
+    // Somme bonus traités entre a et b
+    for (auto& treaty : getTreaties(a, b)) {
+        if (treaty.is_active) {
+            target += treaty.getDecayBonus();
+        }
+    }
+
+    return target;
+}
+
+// Exemples bonus traités
+Alliance:               +250
+Partenariat militaire:  +20
+Accord commercial:      +10
+Non-agression:          +5
+```
+
+**Application Decay** :
+
+```cpp
+void applyRelationDecay(Relationship& rel, float decay_rate) {
+    int target = calculateDecayTarget(rel.entities.first, rel.entities.second);
+    int delta = target - rel.score;
+
+    // Decay linéaire dans les deux sens
+    if (delta > 0) {
+        rel.score += min(delta, (int)(decay_rate * abs(delta)));
+    }
+    else if (delta < 0) {
+        rel.score += max(delta, -(int)(decay_rate * abs(delta)));
+    }
+}
+```
+
+**Exemple Concret** :
+
+```
+USA ↔ France : Alliance active
+Decay target = +250
+Relation actuelle = +750
+
+Sans nouveaux événements :
+→ Decay vers 250 (descend progressivement)
+→ Relation se normalise vers baseline alliance
+
+Si relation = -100 (scandal temporaire) :
+→ Decay vers 250 (remonte)
+→ Alliance structure force retour relation positive
+```
+
+### 2. Intentions (Volonté Bilatérale)
+
+**Définition** : Volonté d'une entité d'améliorer ou détériorer la relation partagée avec une autre.
+
+**Échelle** : `-1000` à `+1000`
+- `-1000` : Veut activement détruire la relation
+- `-500` : Veut détériorer significativement
+- `0` : Maintient status quo, neutre
+- `+500` : Veut améliorer activement
+- `+1000` : Veut maximiser la relation
+
+**Caractéristiques** :
+- **Bilatéral** : `A → B` différent de `B → A`
+- **Indépendant du score** : Intention ≠ relation actuelle
+- **Génère événements** : Intentions modifient le score relation partagé
+- **Asymétrique** : Les deux entités peuvent avoir intentions opposées
+- **Configurable** : IA ajuste intentions selon stratégie
+
+#### Structure Données
+
+```cpp
+struct Intention {
+    EntityId from;
+    EntityId to;
+    int value;        // -1000 à +1000
+};
+
+// Stockage séparé (deux intentions par paire d'entités)
+std::map<std::pair<EntityId, EntityId>, int> intentions;
+
+// Accès (ordre compte !)
+int getIntention(EntityId from, EntityId to) {
+    return intentions[{from, to}];
+}
+
+void setIntention(EntityId from, EntityId to, int value) {
+    intentions[{from, to}] = clamp(value, -1000, 1000);
+}
+```
+
+#### Génération Événements Automatique
+
+Les intentions **génèrent des événements** qui modifient le score relation partagé :
+
+```cpp
+void processDailyIntentions() {
+    for (auto& [from_to, intention] : intentions) {
+        if (intention == 0) continue;  // Neutre
+
+        EntityId from = from_to.first;
+        EntityId to = from_to.second;
+
+        // Probabilité événement proportionnelle à intention
+        float probability = abs(intention) / 1000.0f;
+
+        if (randomFloat() < probability * DAILY_EVENT_BASE_RATE) {
+            if (intention > 0) {
+                generatePositiveEvent(from, to, intention);
+            }
+            else {
+                generateNegativeEvent(from, to, abs(intention));
+            }
+        }
+    }
+}
+
+void generatePositiveEvent(EntityId from, EntityId to, int intention) {
+    // Magnitude événement selon force intention
+    int magnitude = (intention / 200) * 10;  // 0-50 par event
+
+    EventType type = selectPositiveEvent(from, to);
+
+    // Modifier la relation PARTAGÉE
+    addRelationEvent(from, to, {type, magnitude, from, getCurrentDate()});
+}
+
+void addRelationEvent(EntityId a, EntityId b, Event event) {
+    auto key = makeRelationKey(a, b);
+    auto& rel = relationships[key];
+
+    rel.score = clamp(rel.score + event.value, -1000, 1000);
+    rel.events.push_back(event);
+}
+```
+
+#### Exemple Émergence : "Trump Effect"
+
+```
+Situation initiale :
+USA ↔ Europe : score = +600 (alliance historique)
+
+Intentions :
+USA → Europe : -400 (Trump : protectionnisme)
+Europe → USA : +200 (veut maintenir alliance)
+
+Évolution sur 12 mois :
+
+Mois 1-3 :
+- USA intention -400 génère : tarifs (-30), critiques OTAN (-20)
+- Europe intention +200 génère : concessions (+25), coopération (+15)
+- Net : -30 -20 +25 +15 = -10
+- Score : 600 → 590
+
+Mois 4-6 :
+- USA : nouvelles sanctions (-40), retrait accord (-30)
+- Europe : aide militaire (+40), compromis commercial (+20)
+- Net : -70 +60 = -10
+- Score : 590 → 580
+
+Mois 7-12 :
+- Pattern continue, balance légèrement négative
+- Score : 580 → 550
+
+Résultat final :
+USA ↔ Europe : score = +550
+USA → Europe : intention = -400 (inchangée)
+Europe → USA : intention = +200 (inchangée)
+
+= Relation tendue mais alliance maintenue !
+  Europe compense partiellement hostilité USA
+```
+
+#### Balance des Intentions
+
+```cpp
+void evaluateRelationDynamics(EntityId a, EntityId b) {
+    int relation = getRelation(a, b);
+    int intention_a = getIntention(a, b);
+    int intention_b = getIntention(b, a);
+
+    // Prédire évolution
+    int net_intention = intention_a + intention_b;
+
+    if (net_intention > 0) {
+        // Relation va probablement s'améliorer
+    }
+    else if (net_intention < 0) {
+        // Relation va probablement se détériorer
+    }
+    else {
+        // Équilibre, relation stable (avec decay vers traités)
+    }
+}
+```
+
+#### Facteurs Influençant Intentions
+
+**Pour Companies** :
+- Opportunités commerciales (+)
+- Concurrence marché (-)
+- Influence politique désirée (+)
+- Scandales récents (-)
+- Relation actuelle (feedback)
+
+**Pour States** :
+- Alignement idéologique (+/-)
+- Intérêts géopolitiques (+/-)
+- Pression publique interne (+/-)
+- Menace perçue (voir section Menace) (-)
+- Dépendance économique (+)
+
+**Pour PMCs** :
+- Contrats disponibles (+)
+- Réputation avec client (+)
+- Compétition autres PMCs (-)
+
+### 3. Menace (Score Contextuel)
+
+**Définition** : Évaluation de la dangerosité qu'une entité représente pour une autre, basée sur capacités militaires ET industrielles.
+
+**Échelle** : `0` à `2 000 000+` (pas de maximum strict)
+- `0` : Aucune menace
+- `1 000` : PMC petit
+- `10 000` : Company moyenne
+- `100 000` : État petit
+- `500 000` : État moyen
+- `900 000` : Superpower
+- `1 000 000+` : Menace existentielle
+
+**Caractéristiques** :
+- **Contextuelle** : Calculée dynamiquement selon capacités des deux parties
+- **Asymétrique** : A menace B ≠ B menace A
+- **Multi-facteurs** : Forces actuelles + production + qualité
+- **Non-persistée** : Recalculée à la demande
+
+**Note** : Voir `calcul-menace.md` pour détails complets du système d'évaluation.
+
+#### Impact Menace sur Intentions
+
+```cpp
+void adjustIntentionsByThreat(EntityId from, EntityId to) {
+    int threat = calculateThreat(to, from);  // Menace de 'to' envers 'from'
+
+    if (threat > 500000) {
+        // Menace existentielle → chercher alliance ou confrontation
+        if (canAlly(from, to)) {
+            adjustIntention(from, to, +200);  // Appeasement
+        } else {
+            adjustIntention(from, to, -300);  // Préparation guerre
+        }
+    }
+    else if (threat > 200000) {
+        // Menace significative → prudence
+        adjustIntention(from, to, -100);
+    }
+}
+```
+
+### 4. Fiabilité (Réputation Globale)
+
+**Définition** : Réputation globale d'une entité, visible par tous. Représente la confiance générale dans le respect des engagements.
+
+**Échelle** : `0` à `10 000`
+- `0` : Totalement non-fiable, rompt tous engagements
+- `2 500` : Réputation très mauvaise
+- `5 000` : Neutre, moyenne
+- `7 500` : Fiable, respecte engagements
+- `10 000` : Parfaitement fiable, jamais rompu traité
+
+**Caractéristiques** :
+- **Globale** : Une seule valeur par entité, vue par tous
+- **Lente à changer** : Événements ont impact modéré
+- **Decay vers target** : Basé sur traités actifs et leur ancienneté
+- **Critique pour diplomatie** : Influence volonté autres entités à traiter
+
+#### Calcul Decay Target Fiabilité
+
+```cpp
+float calculateFiabilityTarget(Entity entity) {
+    float target = 0.50f;  // Base 50% sans traités
+
+    for (auto& treaty : entity.getActiveTreaties()) {
+        int years = treaty.getDurationYears();
+        float bonus = min(years, 5) * 0.01f;  // Max 5% par traité
+        target += bonus;
+    }
+
+    return min(target, 1.0f);  // Plafonné à 100%
+}
+```
+
+**Exemples** :
+
+```
+Aucun traité : 50% (5000)
+
+1 alliance 1 an : 50% + 1% = 51% (5100)
+1 alliance 5 ans : 50% + 5% = 55% (5500)
+1 alliance 10 ans : 50% + 5% = 55% (5500)  [plafond 5% atteint]
+
+7 alliances 2 ans chacune : 50% + (7 × 2%) = 64% (6400)
+10 alliances 5 ans chacune : 50% + (10 × 5%) = 100% (10000) [max]
+```
+
+#### Application Decay Fiabilité
+
+```cpp
+void applyFiabilityDecay(Entity& entity, float decay_rate) {
+    int target = calculateFiabilityTarget(entity) * 10000;
+    int delta = target - entity.fiability;
+
+    // Decay linéaire vers target
+    if (delta > 0) {
+        entity.fiability += min(delta, (int)(decay_rate * abs(delta)));
+    }
+    else if (delta < 0) {
+        entity.fiability += max(delta, -(int)(decay_rate * abs(delta)));
+    }
+}
+```
+
+#### Événements Impactant Fiabilité
+
+**Positifs (lents)** :
+- `treaty_honored` : +10 (honorer traité existant)
+- `contract_on_time` : +5 (livraison à temps)
+- `transparency` : +15 (révélation volontaire problème)
+
+**Négatifs (brutaux)** :
+- `treaty_broken` : -500 (rupture traité formel)
+- `contract_breach` : -200 (non-respect contrat)
+- `espionage_caught` : -150 (espionnage allié découvert)
+- `scandal` : -100 (scandale qualité/corruption)
+
+#### Impact Fiabilité sur Intentions
+
+```cpp
+void adjustIntentionsBasedOnFiability(EntityId from, EntityId to) {
+    int fiability = getFiability(to);
+
+    // Fiabilité très haute → bonus intention
+    if (fiability > 8000) {
+        adjustIntention(from, to, +50);
+    }
+
+    // Fiabilité très basse → malus intention
+    if (fiability < 2000) {
+        adjustIntention(from, to, -50);  // Méfiance
+    }
+}
+```
+
+## Traités (Treaties)
+
+### Définition
+
+Les traités sont des **accords formalisés** entre deux entités, avec impact mécanique sur relations, decay, et fiabilité.
+
+### Structure
+
+```cpp
+enum TreatyType {
+    ALLIANCE,              // Alliance militaire complète
+    MILITARY_PARTNERSHIP,  // Coopération militaire limitée
+    TRADE_AGREEMENT,       // Accord commercial
+    NON_AGGRESSION,        // Pacte non-agression
+    VASSALAGE,             // Relation hiérarchique
+    EMBARGO,               // Interdiction commerce
+    // ... autres types à définir
+};
+
+struct Treaty {
+    TreatyType type;
+    EntityId party_a;
+    EntityId party_b;
+    int start_date;
+    bool is_active;
+    json terms;            // Conditions spécifiques
+
+    int getDurationYears() const {
+        if (!is_active) return 0;
+        return (getCurrentDate() - start_date) / 365;
+    }
+
+    float getFiabilityBonus() const {
+        if (!is_active) return 0.0f;
+        int years = getDurationYears();
+        return min(years, 5) * 0.01f;
+    }
+
+    int getDecayBonus() const {
+        switch (type) {
+            case ALLIANCE: return 250;
+            case MILITARY_PARTNERSHIP: return 20;
+            case TRADE_AGREEMENT: return 10;
+            case NON_AGGRESSION: return 5;
+            default: return 0;
+        }
+    }
+};
+```
+
+### Cycle de Vie Traité
+
+**1. Proposition** :
+```cpp
+TreatyProposal proposal = {
+    .type = ALLIANCE,
+    .proposer = entity_a,
+    .target = entity_b,
+    .terms = {...}
+};
+```
+
+**2. Évaluation** :
+```cpp
+bool evaluateTreatyProposal(EntityId evaluator, TreatyProposal proposal) {
+    // Vérifier fiabilité proposeur
+    if (getFiability(proposal.proposer) < 4000) return false;
+
+    // Vérifier relation actuelle
+    int relation = getRelation(evaluator, proposal.proposer);
+    if (relation < 200) return false;
+
+    // Vérifier menace
+    int threat = calculateThreat(proposal.proposer, evaluator);
+    if (threat > 600000) return false;
+
+    // Vérifier intention
+    int intention = getIntention(evaluator, proposal.proposer);
+    return intention > 300;
+}
+```
+
+**3. Activation** :
+```cpp
+void activateTreaty(Treaty& treaty) {
+    treaty.is_active = true;
+    treaty.start_date = getCurrentDate();
+
+    // Événement relation massif (modifie score partagé)
+    addRelationEvent(treaty.party_a, treaty.party_b, {
+        TREATY_SIGNED,
+        +400,
+        treaty.party_a,  // Source événement
+        getCurrentDate()
+    });
+
+    // Impact fiabilité positif (les deux parties)
+    adjustFiability(treaty.party_a, +50);
+    adjustFiability(treaty.party_b, +50);
+
+    // Intentions deviennent positives
+    adjustIntention(treaty.party_a, treaty.party_b, +200);
+    adjustIntention(treaty.party_b, treaty.party_a, +200);
+}
+```
+
+**4. Maintenance** :
+```cpp
+void maintainTreaty(Treaty& treaty) {
+    if (!treaty.is_active) return;
+
+    // Chaque année, petit bonus fiabilité
+    int years = treaty.getDurationYears();
+    if (years > last_check_year) {
+        adjustFiability(treaty.party_a, +5);
+        adjustFiability(treaty.party_b, +5);
+        last_check_year = years;
+    }
+}
+```
+
+**5. Rupture** :
+```cpp
+void breakTreaty(Treaty& treaty, EntityId breaker) {
+    treaty.is_active = false;
+
+    EntityId victim = (breaker == treaty.party_a) ? treaty.party_b : treaty.party_a;
+
+    // Événement relation massif négatif (modifie score partagé)
+    addRelationEvent(breaker, victim, {
+        TREATY_BROKEN,
+        -500,
+        breaker,
+        getCurrentDate()
+    });
+
+    // Impact fiabilité brutal
+    adjustFiability(breaker, -500);
+
+    // Intentions deviennent hostiles
+    adjustIntention(victim, breaker, -400);
+    // Breaker peut garder intention positive (opportunisme)
+}
+```
+
+## Interactions Entre Indicateurs
+
+### Relations ↔ Intentions
+
+```cpp
+void updateIntentionsBasedOnRelations(EntityId from, EntityId to) {
+    int relation = getRelation(from, to);
+    int current_intention = getIntention(from, to);
+
+    // Si relation très basse mais intention neutre → générer hostilité
+    if (relation < -400 && current_intention > -200) {
+        adjustIntention(from, to, -150);
+    }
+
+    // Si relation très haute mais intention négative → ajuster (rare)
+    if (relation > 600 && current_intention < -200) {
+        // Situation incohérente, normaliser
+        adjustIntention(from, to, +100);
+    }
+}
+```
+
+### Intentions → Relations (via événements)
+
+C'est le flux principal : intentions génèrent événements qui modifient relations.
+
+```cpp
+// Chaque jour/tick
+void processDailyDiplomacy() {
+    // 1. Intentions génèrent événements
+    processDailyIntentions();
+
+    // 2. Relations decay vers traités
+    for (auto& rel : relationships) {
+        applyRelationDecay(rel, DECAY_RATE);
+    }
+
+    // 3. Fiabilité decay vers target
+    for (auto& entity : entities) {
+        applyFiabilityDecay(entity, FIABILITY_DECAY_RATE);
+    }
+
+    // 4. Ajustements feedback
+    for (auto& rel : relationships) {
+        updateIntentionsBasedOnRelations(rel.entities.first, rel.entities.second);
+        updateIntentionsBasedOnRelations(rel.entities.second, rel.entities.first);
+    }
+}
+```
+
+### Menace → Intentions
+
+```cpp
+void updateIntentionsBasedOnThreat(EntityId from, EntityId to) {
+    int threat = calculateThreat(to, from);
+
+    if (threat > 700000) {
+        // Menace existentielle → chercher alliances défensives
+        for (auto& potential_ally : getAllEntities()) {
+            if (isEnemyOf(potential_ally, to)) {
+                adjustIntention(from, potential_ally, +200);
+            }
+        }
+
+        // Hostile envers menaçant
+        adjustIntention(from, to, -300);
+    }
+}
+```
+
+### Fiabilité → Intentions
+
+```cpp
+void adjustIntentionsBasedOnFiability(EntityId from, EntityId to) {
+    int fiability = getFiability(to);
+
+    if (fiability > 8000) {
+        adjustIntention(from, to, +30);  // Confiance
+    }
+    else if (fiability < 2000) {
+        adjustIntention(from, to, -50);  // Méfiance
+    }
+}
+```
+
+## Actions Diplomatiques
+
+### Lobbying (Company → State)
+
+```cpp
+struct LobbyingAction {
+    CompanyId company;
+    StateId state;
+    int investment;
+    int duration_days;
+};
+
+void executeLobbyingCampaign(LobbyingAction action) {
+    int relation = getRelation(action.company, action.state);
+    int fiability = getFiability(action.company);
+
+    float success_chance =
+        (action.investment / 100000.0f) * 0.4f +
+        (relation / 1000.0f) * 0.3f +
+        (fiability / 10000.0f) * 0.3f;
+
+    if (randomFloat() < success_chance) {
+        // Succès : améliore relation partagée
+        addRelationEvent(action.company, action.state, {
+            LOBBYING_SUCCESS,
+            +50 + (action.investment / 10000),
+            action.company,
+            getCurrentDate()
+        });
+
+        // Augmente intention state envers company
+        adjustIntention(action.state, action.company, +30);
+    }
+}
+```
+
+### Sanctions (State → State/Company)
+
+```cpp
+void imposeSanctions(EntityId from, EntityId to, SanctionType type) {
+    // Impact relation partagée
+    addRelationEvent(from, to, {
+        SANCTIONS_IMPOSED,
+        -300,
+        from,
+        getCurrentDate()
+    });
+
+    // Impact économique
+    economyModule->applySanctions(to, type);
+
+    // Ajuste intentions (bilatéral)
+    adjustIntention(to, from, -200);  // Victime hostile
+    adjustIntention(from, to, -100);  // Sanctionneur aussi hostile
+}
+```
+
+### Aide Militaire
+
+```cpp
+void provideMilitaryAid(EntityId from, EntityId to, MilitaryAid aid) {
+    int value = calculateAidValue(aid);
+
+    // Impact relation partagée
+    addRelationEvent(from, to, {
+        MILITARY_AID,
+        value / 1000,
+        from,
+        getCurrentDate()
+    });
+
+    // Améliore intention bénéficiaire
+    adjustIntention(to, from, +50);
+}
+```
+
+## Intégration Architecture Modulaire
+
+### DiplomacyModule Interface
+
+```cpp
+class DiplomacyModule : public IModule {
+public:
+    // Relations (partagées)
+    int getRelation(EntityId a, EntityId b);
+    void addRelationEvent(EntityId a, EntityId b, Event event);
+
+    // Intentions (bilatérales)
+    int getIntention(EntityId from, EntityId to);
+    void setIntention(EntityId from, EntityId to, int intention);
+    void adjustIntention(EntityId from, EntityId to, int delta);
+
+    // Menace (calculée à la demande)
+    int calculateThreat(EntityId attacker, EntityId defender);
+
+    // Fiabilité (globale)
+    int getFiability(EntityId entity);
+    void adjustFiability(EntityId entity, int delta);
+
+    // Traités
+    std::vector<Treaty> getTreaties(EntityId entity);
+    bool proposeTreaty(TreatyProposal proposal);
+    void activateTreaty(Treaty& treaty);
+    void breakTreaty(Treaty& treaty, EntityId breaker);
+
+    // Process cycle
+    json process(const json& input) override;
+};
+```
+
+### Communication avec Autres Modules
+
+**CompanyAI consulte DiplomacyModule** :
+
+```cpp
+// Vérifier relation avant action
+json request;
+request["action"] = "get_relation";
+request["entity_a"] = company_id;
+request["entity_b"] = state_id;
+
+json response = sendToModule("diplomacy", request);
+int relation = response["relation"];
+
+if (relation < 300) {
+    // Relation trop basse, lobbying prioritaire
+    adjustIntention(company_id, state_id, +300);  // Améliorer intention
+}
+```
+
+**StateAI utilise menace** :
+
+```cpp
+json request;
+request["action"] = "calculate_threat";
+request["attacker"] = potential_enemy_id;
+request["defender"] = state_id;
+
+json response = sendToModule("diplomacy", request);
+int threat = response["threat"];
+
+if (threat > 600000) {
+    // Menace haute, ajuster intentions défensives
+    adjustIntention(state_id, potential_enemy_id, -400);
+}
+```
+
+## Sérialisation et Sauvegarde
+
+### Format Relations
+
+```json
+{
+  "relations": {
+    "company_123 ↔ state_456": {
+      "score": 750,
+      "decay_target": 270,
+      "events": [
+        {
+          "type": "contract_fulfilled",
+          "value": 100,
+          "source": "company_123",
+          "date": 1735689600,
+          "description": "Livraison 50 tanks à temps"
+        },
+        {
+          "type": "lobbying_success",
+          "value": 50,
+          "source": "company_123",
+          "date": 1738368000,
+          "description": "Campagne lobbying réussie"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Format Intentions
+
+```json
+{
+  "intentions": {
+    "company_123 → state_456": 200,
+    "state_456 → company_123": -100
+  }
+}
+```
+
+### Format Fiabilité
+
+```json
+{
+  "fiability": {
+    "company_123": {
+      "score": 6400,
+      "target": 6400,
+      "active_treaties_count": 7
+    }
+  }
+}
+```
+
+### Format Traités
+
+```json
+{
+  "treaties": [
+    {
+      "id": "treaty_001",
+      "type": "ALLIANCE",
+      "party_a": "state_usa",
+      "party_b": "state_france",
+      "start_date": 1672531200,
+      "is_active": true,
+      "duration_years": 3,
+      "terms": {
+        "mutual_defense": true,
+        "trade_bonus": 0.15
+      }
+    }
+  ]
+}
+```
+
+## Performance et Optimisation
+
+### Cache Menace
+
+```cpp
+class ThreatCache {
+private:
+    struct CachedThreat {
+        int value;
+        int timestamp;
+        int ttl = 3600;
+    };
+
+    std::map<std::pair<EntityId, EntityId>, CachedThreat> cache;
+
+public:
+    int getThreat(EntityId attacker, EntityId defender) {
+        auto key = std::make_pair(attacker, defender);
+
+        if (cache.contains(key) &&
+            getCurrentTime() - cache[key].timestamp < cache[key].ttl) {
+            return cache[key].value;
+        }
+
+        int threat = calculateThreat(attacker, defender);
+        cache[key] = {threat, getCurrentTime()};
+        return threat;
+    }
+};
+```
+
+### Batch Processing Intentions
+
+```cpp
+void processDailyIntentions() {
+    std::vector<std::pair<EntityId, EntityId>> to_process;
+
+    // Collecter intentions non-nulles
+    for (auto& [from_to, intention] : intentions) {
+        if (intention != 0) {
+            to_process.push_back(from_to);
+        }
+    }
+
+    // Traiter en batch
+    for (auto& [from, to] : to_process) {
+        int intention = intentions[{from, to}];
+        processIntention(from, to, intention);
+    }
+}
+```
+
+### Decay Incrémental
+
+```cpp
+void applyDecayIncremental(int relations_per_tick = 10) {
+    static int current_index = 0;
+
+    auto& rel_list = getAllRelations();
+    int end_index = min(current_index + relations_per_tick, (int)rel_list.size());
+
+    for (int i = current_index; i < end_index; i++) {
+        applyRelationDecay(rel_list[i], DECAY_RATE);
+    }
+
+    current_index = (end_index >= rel_list.size()) ? 0 : end_index;
+}
+```
+
+## Exemples Complets
+
+### Exemple 1 : Cycle Vie Alliance
+
+```cpp
+// Année 0 : Proposition alliance
+State usa, france;
+
+// Relation initiale
+int initial_relation = getRelation(usa, france);  // 400
+
+// Intentions initiales
+setIntention(usa, france, +600);   // USA veut alliance
+setIntention(france, usa, +500);   // France aussi
+
+TreatyProposal proposal = {
+    .type = ALLIANCE,
+    .proposer = usa,
+    .target = france
+};
+
+if (evaluateTreatyProposal(france, proposal)) {
+    // Accepté !
+    Treaty alliance = activateTreaty(proposal);
+
+    // Impact immédiat sur relation partagée
+    int relation = getRelation(usa, france);  // 400 + 400 = 800
+
+    // Fiabilité augmente
+    adjustFiability(usa, +50);
+    adjustFiability(france, +50);
+}
+
+// Années 1-3 : Maintenance
+for (int year = 1; year <= 3; year++) {
+    maintainTreaty(alliance);
+}
+
+// Année 3 : Scandales (événements externes)
+addRelationEvent(usa, france, {SCANDAL, -200, usa, getCurrentDate()});
+// Relation : 800 → 600
+
+// Decay vers 250 (alliance baseline) commence
+
+// Année 4 : USA intention devient négative (nouveau gouvernement)
+setIntention(usa, france, -300);
+// Génère événements négatifs automatiques
+// France continue events positifs (intention +500)
+// Balance : relation descend lentement
+
+// Année 5 : USA rompt alliance
+breakTreaty(alliance, usa);
+// Relation : 600 - 500 = 100
+// Fiabilité USA : -500
+// Intention France → USA : -400 (devient hostile)
+```
+
+### Exemple 2 : Lobbying Company
+
+```cpp
+Company rheinmetall;
+State germany;
+
+// État initial
+int relation = getRelation(rheinmetall, germany);  // 300
+setIntention(rheinmetall, germany, +500);  // Veut améliorer
+setIntention(germany, rheinmetall, 0);     // Neutre
+
+// Campagne lobbying 6 mois
+for (int month = 0; month < 6; month++) {
+    LobbyingAction action = {
+        .company = rheinmetall,
+        .state = germany,
+        .investment = 50000,
+        .duration_days = 30
+    };
+
+    executeLobbyingCampaign(action);
+    // 4 succès : +50 chacun sur relation partagée
+    // 2 échecs : pas d'impact
+}
+
+// Résultat : relation = 300 + (4 × 50) = 500
+
+// Lobbying a aussi ajusté intention Germany
+int germany_intention = getIntention(germany, rheinmetall);  // 0 + (4 × 30) = 120
+
+// Germany commence à générer events positifs aussi
+// Synergie : relation continue d'améliorer
+```
+
+## Évolutions Futures
+
+### Version 2 : Factions et Blocs
+
+- Alliances multi-entités (OTAN, Pacte de Varsovie)
+- Relations transitives (ami de mon ami)
+- Pression peer group (alignement bloc)
+
+### Version 3 : Opinion Publique
+
+- Fiabilité vue différemment selon idéologie
+- Pression interne pour maintenir/rompre relations
+- Scandales médiatiques impactent relations
+
+### Version 4 : Espionnage et Influence
+
+- Actions cachées affectant relations
+- Découverte espionnage = événement massif
+- Manipulation opinion publique adverse
+
+## Références Croisées
+
+- `calcul-menace.md` : Détails système évaluation menace contextuelle
+- `ai-framework.md` : Utilisation diplomatie dans décisions IA
+- `economie-logistique.md` : Impact sanctions, embargos, accords commerciaux
+- `systeme-sauvegarde.md` : Persistence relations, traités, événements
diff --git a/docs/systeme-sauvegarde.md b/docs/systeme-sauvegarde.md
new file mode 100644
index 0000000..eb2b043
--- /dev/null
+++ b/docs/systeme-sauvegarde.md
@@ -0,0 +1,715 @@
+# Système de Sauvegarde
+
+## Philosophie
+
+Le système de sauvegarde suit la philosophie du projet : **évolution itérative avec versioning des systèmes**. Chaque version améliore progressivement les performances et fonctionnalités tout en maintenant la compatibilité.
+
+Le système est conçu pour être **modulaire et autonome**, chaque module gérant sa propre persistence de manière indépendante.
+
+## Version 1 : Save JSON Local Sans Versioning de Format
+
+### Principes de Base
+
+- **Format** : JSON pur pour lisibilité, debugging et édition manuelle
+- **Granularité** : Un fichier par module
+- **Distribution** : Chaque serveur sauvegarde localement (multi-serveur ready)
+- **Coordination** : Clé de save distribuée par le coordinateur
+- **Autonomie** : Chaque module implémente son propre `serialize()` / `deserialize()`
+- **Chunks** : Seulement les chunks modifiés (metachunks 512x512)
+- **Objectif** : Système fonctionnel et suffisant pour tests et développement
+
+### Architecture de Fichiers
+
+```
+saves/
+└── abc123_1728226320/          # Clé de save : [id]_[timestamp]
+    ├── save_metadata.json       # Métadonnées globales de la save
+    ├── server_1/                # Un dossier par serveur (future-proof)
+    │   ├── tank.json
+    │   └── combat.json
+    ├── server_2/
+    │   ├── economy.json
+    │   └── factory.json
+    └── metachunks/
+        ├── 0_0.json             # Metachunk coords (x, y) en 512x512
+        ├── 0_1.json
+        └── ...
+```
+
+**Note** : En configuration single-process V1, un seul dossier serveur existe (ex: `server_1/`), mais la structure supporte déjà le multi-serveur.
+
+### Format save_metadata.json
+
+Fichier global décrivant la sauvegarde complète :
+
+```json
+{
+  "save_key": "abc123_1728226320",
+  "timestamp": "2025-10-06T14:32:00Z",
+  "game_version": "0.1.0-alpha",
+  "modules": {
+    "tank": {
+      "version": "0.1.15.3847",
+      "load_status": "ok"
+    },
+    "economy": {
+      "version": "0.2.8.1203",
+      "load_status": "ok"
+    },
+    "factory": {
+      "version": "0.1.20.4512",
+      "load_status": "load_pending"
+    },
+    "transport": {
+      "version": "0.1.5.982",
+      "load_status": "ok"
+    }
+  },
+  "metachunks_count": 42,
+  "world_seed": 1847293847
+}
+```
+
+**Champs** :
+- `save_key` : Identifiant unique de la save (format : `[id]_[timestamp_unix]`)
+- `timestamp` : Date/heure de sauvegarde (ISO 8601)
+- `game_version` : Version du jeu ayant créé la save
+- `modules` : État de chaque module sauvé
+  - `version` : Version du module (voir `module-versioning.md`)
+  - `load_status` : `"ok"`, `"load_pending"`, `"failed"`
+- `metachunks_count` : Nombre de metachunks sauvés
+- `world_seed` : Seed de génération procédurale
+
+### Format Fichiers Modules
+
+Chaque module implémente `IModuleSave` et définit son propre format JSON.
+
+#### Exemple : tank.json
+
+```json
+{
+  "module_name": "tank",
+  "module_version": "0.1.15.3847",
+  "save_timestamp": "2025-10-06T14:32:00Z",
+  "data": {
+    "tanks": [
+      {
+        "id": "tank_001",
+        "chassis_type": "m1_abrams",
+        "position": {"x": 1250.5, "y": 3480.2},
+        "rotation": 45.0,
+        "components": [
+          {
+            "type": "turret_120mm",
+            "grid_pos": [2, 3],
+            "health": 100,
+            "ammo_loaded": "apfsds"
+          },
+          {
+            "type": "engine_turbine",
+            "grid_pos": [1, 1],
+            "health": 85,
+            "fuel": 0.75
+          }
+        ],
+        "inventory": {
+          "120mm_apfsds": 32,
+          "120mm_heat": 18
+        },
+        "crew_status": "operational"
+      }
+    ]
+  }
+}
+```
+
+#### Exemple : economy.json
+
+```json
+{
+  "module_name": "economy",
+  "module_version": "0.2.8.1203",
+  "save_timestamp": "2025-10-06T14:32:00Z",
+  "data": {
+    "market_prices": {
+      "iron_ore": 2.5,
+      "copper_ore": 3.2,
+      "steel_plate": 8.0
+    },
+    "player_balance": 125000,
+    "pending_transactions": [
+      {
+        "id": "tx_4829",
+        "type": "buy",
+        "resource": "steel_plate",
+        "quantity": 1000,
+        "price_per_unit": 8.0,
+        "timestamp": "2025-10-06T14:30:15Z"
+      }
+    ]
+  }
+}
+```
+
+**Convention** : Chaque fichier module contient :
+- `module_name` : Nom du module (vérification cohérence)
+- `module_version` : Version du module ayant créé la save
+- `save_timestamp` : Timestamp de sauvegarde
+- `data` : Objet contenant toutes les données spécifiques au module
+
+### Format Metachunks (512x512)
+
+Pour réduire le nombre de fichiers, les chunks 64x64 sont regroupés en **metachunks 512x512** (8x8 chunks par metachunk = 64 chunks).
+
+#### Structure Metachunk
+
+```json
+{
+  "metachunk_coords": {"x": 0, "y": 0},
+  "metachunk_size": 512,
+  "chunk_size": 64,
+  "chunks": {
+    "0_0": {
+      "terrain": {
+        "land_ids_base64": "AQIDBAUGBwg...",
+        "roof_ids_base64": "CQAKAA..."
+      },
+      "buildings": [
+        {
+          "id": "building_factory_001",
+          "type": "assembler_mk1",
+          "position": {"x": 10, "y": 15},
+          "recipe": "ammunition_7.62mm",
+          "progress": 0.45,
+          "inventory": {
+            "iron_plate": 50,
+            "copper_wire": 30
+          }
+        }
+      ],
+      "resources": [
+        {
+          "type": "iron_ore",
+          "patch_id": "iron_patch_042",
+          "positions": [[5,5], [5,6], [6,5], [6,6]],
+          "amounts": [1000, 950, 980, 1020]
+        }
+      ]
+    },
+    "0_1": {
+      "terrain": { "land_ids_base64": "..." },
+      "buildings": [],
+      "resources": []
+    }
+  }
+}
+```
+
+**Optimisations** :
+- **Base64 compression** : Données terrain denses compressées
+- **Sparse storage** : Chunks vides omis du metachunk
+- **Dirty tracking** : Seulement metachunks avec chunks modifiés sont sauvés
+
+#### Calcul Coords Metachunk
+
+```cpp
+// Chunk 64x64 coords → Metachunk 512x512 coords
+MetachunkCoords getMetachunkCoords(int chunkX, int chunkY) {
+    return {
+        chunkX / 8,  // 512 / 64 = 8 chunks par metachunk
+        chunkY / 8
+    };
+}
+
+// Coords locales dans le metachunk
+ChunkLocalCoords getLocalCoords(int chunkX, int chunkY) {
+    return {
+        chunkX % 8,
+        chunkY % 8
+    };
+}
+```
+
+### Interface IModuleSave
+
+Chaque module implémente cette interface pour gérer sa persistence :
+
+```cpp
+class IModuleSave {
+public:
+    virtual ~IModuleSave() = default;
+
+    // Sérialise l'état complet du module en JSON
+    virtual nlohmann::json serialize() = 0;
+
+    // Restaure l'état du module depuis JSON
+    // Retourne true si succès, false si erreur (→ load_pending)
+    virtual bool deserialize(const nlohmann::json& data) = 0;
+
+    // Version du module (auto-générée, voir module-versioning.md)
+    virtual std::string getVersion() const = 0;
+};
+```
+
+#### Exemple Implémentation
+
+```cpp
+class TankModule : public IModule, public IModuleSave {
+private:
+    std::vector<Tank> tanks;
+
+public:
+    nlohmann::json serialize() override {
+        json data;
+        data["module_name"] = "tank";
+        data["module_version"] = getVersion();
+        data["save_timestamp"] = getCurrentTimestamp();
+
+        json tanksArray = json::array();
+        for (const auto& tank : tanks) {
+            tanksArray.push_back(tank.toJson());
+        }
+        data["data"]["tanks"] = tanksArray;
+
+        return data;
+    }
+
+    bool deserialize(const json& data) override {
+        try {
+            // Validation version
+            if (data["module_name"] != "tank") {
+                LOG_ERROR("Invalid module name in save file");
+                return false;
+            }
+
+            // Charge les tanks
+            tanks.clear();
+            for (const auto& tankJson : data["data"]["tanks"]) {
+                tanks.push_back(Tank::fromJson(tankJson));
+            }
+
+            return true;
+        }
+        catch (const std::exception& e) {
+            LOG_ERROR("Deserialization failed: {}", e.what());
+            return false;
+        }
+    }
+
+    std::string getVersion() const override {
+        return MODULE_VERSION;  // Défini par CMake
+    }
+};
+```
+
+### Workflow de Sauvegarde
+
+#### Déclenchement
+
+**En single-process** :
+```cpp
+saveSystem->saveGame("abc123");
+```
+
+**En multi-serveur** :
+Le coordinateur broadcast une clé de save :
+```cpp
+// Coordinateur
+coordinator->broadcastSaveCommand("abc123_1728226320");
+
+// Chaque serveur reçoit et exécute
+void Server::onSaveCommand(const std::string& saveKey) {
+    saveSystem->saveGame(saveKey);
+}
+```
+
+#### Processus de Sauvegarde
+
+```cpp
+void SaveSystem::saveGame(const std::string& saveKey) {
+    auto startTime = std::chrono::steady_clock::now();
+
+    // 1. Créer structure de dossiers
+    std::string savePath = "saves/" + saveKey + "/";
+    fs::create_directories(savePath + "server_1/");
+    fs::create_directories(savePath + "metachunks/");
+
+    // 2. Sauvegarder chaque module
+    json metadata;
+    metadata["save_key"] = saveKey;
+    metadata["timestamp"] = getCurrentTimestamp();
+    metadata["game_version"] = GAME_VERSION;
+
+    for (auto& module : moduleSystem->getAllModules()) {
+        std::string moduleName = module->getName();
+
+        try {
+            // Sérialiser module
+            json moduleData = module->serialize();
+
+            // Écrire fichier
+            std::string modulePath = savePath + "server_1/" +
+                                     moduleName + ".json";
+            writeJsonFile(modulePath, moduleData);
+
+            // Mettre à jour metadata
+            metadata["modules"][moduleName] = {
+                {"version", module->getVersion()},
+                {"load_status", "ok"}
+            };
+
+            LOG_INFO("Module {} saved successfully", moduleName);
+        }
+        catch (const std::exception& e) {
+            LOG_ERROR("Failed to save module {}: {}", moduleName, e.what());
+            metadata["modules"][moduleName] = {
+                {"version", module->getVersion()},
+                {"load_status", "failed"}
+            };
+        }
+    }
+
+    // 3. Sauvegarder metachunks modifiés
+    int metachunkCount = 0;
+    for (auto& [coords, metachunk] : dirtyMetachunks) {
+        json metachunkData = metachunk->serialize();
+        std::string filename = std::to_string(coords.x) + "_" +
+                               std::to_string(coords.y) + ".json";
+        writeJsonFile(savePath + "metachunks/" + filename, metachunkData);
+        metachunkCount++;
+    }
+    metadata["metachunks_count"] = metachunkCount;
+
+    // 4. Écrire metadata
+    writeJsonFile(savePath + "save_metadata.json", metadata);
+
+    auto duration = std::chrono::duration_cast<std::chrono::milliseconds>(
+        std::chrono::steady_clock::now() - startTime
+    );
+
+    LOG_INFO("Save completed in {}ms: {} modules, {} metachunks",
+             duration.count(), metadata["modules"].size(), metachunkCount);
+}
+```
+
+### Workflow de Chargement
+
+```cpp
+void SaveSystem::loadGame(const std::string& saveKey) {
+    std::string savePath = "saves/" + saveKey + "/";
+
+    // 1. Charger metadata
+    json metadata = readJsonFile(savePath + "save_metadata.json");
+
+    // Validation game version (warning seulement en V1)
+    if (metadata["game_version"] != GAME_VERSION) {
+        LOG_WARN("Save created with different game version: {} vs {}",
+                 metadata["game_version"], GAME_VERSION);
+    }
+
+    // 2. Charger world data (seed, params)
+    worldGenerator->setSeed(metadata["world_seed"]);
+
+    // 3. Charger chaque module
+    for (auto& module : moduleSystem->getAllModules()) {
+        std::string moduleName = module->getName();
+        std::string modulePath = savePath + "server_1/" +
+                                 moduleName + ".json";
+
+        if (!fs::exists(modulePath)) {
+            LOG_WARN("No save file for module {}, using defaults", moduleName);
+            continue;
+        }
+
+        try {
+            json moduleData = readJsonFile(modulePath);
+
+            // Vérification version module
+            std::string savedVersion = moduleData["module_version"];
+            std::string currentVersion = module->getVersion();
+
+            if (savedVersion != currentVersion) {
+                LOG_WARN("Module {} version mismatch: save={}, current={}",
+                         moduleName, savedVersion, currentVersion);
+            }
+
+            // Désérialiser
+            bool success = module->deserialize(moduleData);
+
+            if (!success) {
+                LOG_ERROR("Module {} deserialization failed, marked as load_pending",
+                          moduleName);
+                metadata["modules"][moduleName]["load_status"] = "load_pending";
+            }
+            else {
+                LOG_INFO("Module {} loaded successfully", moduleName);
+            }
+        }
+        catch (const std::exception& e) {
+            LOG_ERROR("Failed to load module {}: {}", moduleName, e.what());
+            metadata["modules"][moduleName]["load_status"] = "load_pending";
+        }
+    }
+
+    // 4. Metachunks chargés à la demande (streaming)
+    // Voir Chunk Streaming ci-dessous
+
+    LOG_INFO("Save loaded: {}", saveKey);
+}
+```
+
+### Chunk Streaming
+
+Les metachunks ne sont **pas tous chargés au démarrage** pour économiser la mémoire. Système de chargement à la demande :
+
+```cpp
+Chunk* ChunkManager::getChunk(int x, int y) {
+    ChunkCoords coords{x, y};
+
+    // 1. Vérifier si déjà en RAM
+    if (loadedChunks.contains(coords)) {
+        return loadedChunks[coords];
+    }
+
+    // 2. Calculer metachunk parent
+    MetachunkCoords metaCoords = getMetachunkCoords(x, y);
+    ChunkLocalCoords localCoords = getLocalCoords(x, y);
+
+    // 3. Charger metachunk si nécessaire
+    if (!loadedMetachunks.contains(metaCoords)) {
+        loadMetachunk(metaCoords);
+    }
+
+    // 4. Extraire chunk du metachunk
+    Metachunk* metachunk = loadedMetachunks[metaCoords];
+    Chunk* chunk = metachunk->getChunk(localCoords);
+
+    if (chunk) {
+        loadedChunks[coords] = chunk;
+        return chunk;
+    }
+
+    // 5. Si chunk n'existe pas dans save → génération procédurale
+    return generateNewChunk(coords);
+}
+
+void ChunkManager::loadMetachunk(MetachunkCoords coords) {
+    std::string path = "saves/" + currentSave + "/metachunks/" +
+                       std::to_string(coords.x) + "_" +
+                       std::to_string(coords.y) + ".json";
+
+    if (!fs::exists(path)) {
+        // Metachunk pas encore exploré/modifié
+        loadedMetachunks[coords] = new Metachunk(coords);
+        return;
+    }
+
+    // Charger et désérialiser metachunk
+    json metachunkData = readJsonFile(path);
+    Metachunk* metachunk = new Metachunk(coords);
+    metachunk->deserialize(metachunkData);
+
+    loadedMetachunks[coords] = metachunk;
+    LOG_DEBUG("Metachunk loaded: ({}, {})", coords.x, coords.y);
+}
+```
+
+### Gestion des Erreurs : load_pending
+
+Lorsqu'un module échoue à charger (JSON corrompu, incompatibilité version, etc.), il est marqué `load_pending` dans le metadata.
+
+#### Workflow de Récupération
+
+```cpp
+// Au chargement, si erreur détectée
+if (!module->deserialize(moduleData)) {
+    metadata["modules"][moduleName]["load_status"] = "load_pending";
+
+    // Sauvegarder metadata mis à jour
+    writeJsonFile(savePath + "save_metadata.json", metadata);
+
+    // Continuer le chargement des autres modules
+}
+```
+
+#### Interface Utilisateur
+
+```cpp
+void UI::displayLoadPendingModules() {
+    for (const auto& [moduleName, info] : metadata["modules"].items()) {
+        if (info["load_status"] == "load_pending") {
+            std::cout << "[WARNING] Module '" << moduleName
+                      << "' failed to load. Check logs and fix JSON file.\n";
+            std::cout << "  File: saves/" << saveKey << "/server_1/"
+                      << moduleName << ".json\n";
+            std::cout << "  Version: " << info["version"] << "\n\n";
+        }
+    }
+}
+```
+
+#### Retry Manuel
+
+Après avoir corrigé le fichier JSON manuellement :
+
+```cpp
+void SaveSystem::retryLoadModule(const std::string& moduleName) {
+    auto module = moduleSystem->getModule(moduleName);
+    std::string modulePath = savePath + "server_1/" + moduleName + ".json";
+
+    try {
+        json moduleData = readJsonFile(modulePath);
+        bool success = module->deserialize(moduleData);
+
+        if (success) {
+            metadata["modules"][moduleName]["load_status"] = "ok";
+            writeJsonFile(savePath + "save_metadata.json", metadata);
+            LOG_INFO("Module {} successfully reloaded", moduleName);
+        }
+    }
+    catch (const std::exception& e) {
+        LOG_ERROR("Retry failed for module {}: {}", moduleName, e.what());
+    }
+}
+```
+
+### Dirty Tracking
+
+Seuls les chunks/metachunks **modifiés** sont sauvegardés pour optimiser la taille des saves.
+
+```cpp
+class ChunkManager {
+private:
+    std::unordered_set<MetachunkCoords> dirtyMetachunks;
+
+public:
+    void markChunkDirty(int chunkX, int chunkY) {
+        MetachunkCoords metaCoords = getMetachunkCoords(chunkX, chunkY);
+        dirtyMetachunks.insert(metaCoords);
+    }
+
+    void onBuildingPlaced(int x, int y) {
+        int chunkX = x / 64;
+        int chunkY = y / 64;
+        markChunkDirty(chunkX, chunkY);
+    }
+
+    void onResourceMined(int x, int y) {
+        int chunkX = x / 64;
+        int chunkY = y / 64;
+        markChunkDirty(chunkX, chunkY);
+    }
+};
+```
+
+### Performance Targets V1
+
+- **Autosave** : < 100ms pause perceptible (background thread recommandé)
+- **Save manuelle** : < 500ms acceptable (avec feedback UI)
+- **Load game** : < 3 secondes pour metadata + modules
+- **Chunk streaming** : < 16ms par metachunk (1 frame @60fps)
+- **Taille save** : ~10-50MB pour partie moyenne (dépend exploration)
+
+### Limitations V1
+
+Ces limitations seront résolues dans les versions futures :
+
+1. **Pas de migration format** : Si le format JSON d'un module change, incompatibilité
+2. **JSON verbeux** : Fichiers volumineux comparé à format binaire (acceptable pour debug)
+3. **Pas de compression** : Taille disque non optimale
+4. **Pas de checksums** : Corruption de données détectée tard (au parsing JSON)
+5. **Concurrence limitée** : Save/load synchrones (pas de multi-threading)
+
+## Évolution Future
+
+### Version 2 : Compression et Migration
+
+- **Compression LZ4/Zstd** : Réduction 60-80% taille fichiers
+- **Format binaire optionnel** : MessagePack ou Protobuf pour données volumineuses
+- **Migration automatique** : Système de conversion entre versions de format
+- **Checksums** : Validation intégrité (CRC32, SHA256)
+- **Async I/O** : Save/load en background threads
+
+### Version 3 : Incremental Saves
+
+- **Delta encoding** : Sauvegardes différentielles (snapshot + journal de changements)
+- **Rollback temporel** : Restaurer état à timestamp spécifique
+- **Compression inter-saves** : Déduplication entre sauvegardes
+- **Hot-save** : Sauvegarde pendant le jeu sans pause
+
+### Version 4 : Cloud et Multiplayer
+
+- **Synchronisation cloud** : Steam Cloud, Google Drive, etc.
+- **Save distribué** : Réplication multi-serveur automatique
+- **Conflict resolution** : Merge intelligent pour multiplayer
+- **Versioning git-like** : Branches, merge, rollback
+
+## Références Croisées
+
+- `module-versioning.md` : Système de versioning automatique des modules
+- `architecture-modulaire.md` : Interface IModule, contraintes autonomie
+- `systemes-techniques.md` : Architecture chunks multi-échelle
+- `map-system.md` : Génération procédurale, resource patches
+- `metriques-joueur.md` : Métriques à sauvegarder (3.1GB analytics)
+
+## Exemples Pratiques
+
+### Créer une Nouvelle Save
+
+```cpp
+// Single-process
+saveSystem->saveGame("my_first_base");
+
+// Multi-serveur
+coordinator->broadcastSaveCommand("my_first_base_1728226320");
+```
+
+### Charger une Save Existante
+
+```cpp
+saveSystem->loadGame("my_first_base_1728226320");
+```
+
+### Éditer une Save Manuellement
+
+```bash
+# Ouvrir fichier module
+nano saves/abc123_1728226320/server_1/economy.json
+
+# Modifier prix du marché
+# "iron_ore": 2.5 → "iron_ore": 5.0
+
+# Recharger le module spécifique
+saveSystem->retryLoadModule("economy");
+```
+
+### Lister les Saves Disponibles
+
+```cpp
+std::vector<SaveInfo> SaveSystem::listSaves() {
+    std::vector<SaveInfo> saves;
+
+    for (const auto& entry : fs::directory_iterator("saves/")) {
+        if (!entry.is_directory()) continue;
+
+        std::string metadataPath = entry.path().string() + "/save_metadata.json";
+        if (!fs::exists(metadataPath)) continue;
+
+        json metadata = readJsonFile(metadataPath);
+        saves.push_back({
+            .saveKey = metadata["save_key"],
+            .timestamp = metadata["timestamp"],
+            .gameVersion = metadata["game_version"],
+            .moduleCount = metadata["modules"].size(),
+            .metachunkCount = metadata["metachunks_count"]
+        });
+    }
+
+    // Trier par timestamp décroissant (plus récent en premier)
+    std::sort(saves.begin(), saves.end(), [](const auto& a, const auto& b) {
+        return a.timestamp > b.timestamp;
+    });
+
+    return saves;
+}
+```