diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md
index e8875c1..595b367 100644
--- a/DOCUMENTATION.md
+++ b/DOCUMENTATION.md
@@ -1,138 +1,355 @@
-# Entropyk: Technical Manual & Reference Guide
+# Entropyk — Manuel technique
 
-Entropyk is a high-performance thermodynamic simulation framework designed for precision modeling of HVAC/R systems. This manual provides exhaustive documentation of the physical models, solver mechanics, and multi-platform APIs.
+Entropyk est un cadre de simulation thermodynamique en régime permanent pour systèmes HVAC/R (chillers, pompes à chaleur, cycles frigorifiques). Ce manuel détaille les fondations physiques, les modèles de composants, le solveur, les DoF, et les API multi-plateformes.
+
+Pour un tour d’horizon orienté utilisateur : [`README.md`](./README.md).  
+Pour le CLI JSON : [`crates/cli/README.md`](./crates/cli/README.md).  
+Pour Fixed/Free Modelica : [`docs/modelica-boundary-proof.md`](./docs/modelica-boundary-proof.md).
 
 ---
 
-## 1. Physical Foundations
+## Table des matières
 
-### 1.1 Dimensional Analysis & Type Safety
-Entropyk utilizes a "Type-Safe Dimension" pattern to eliminate unit errors. Every physical quantity is wrapped in a NewType that enforces SI base units internally.
-
-| Quantity | Internal Unit (SI) | Documentation Symbol |
-| :--- | :--- | :--- |
-| Pressure | Pascal ($Pa$) | $P$ |
-| Temperature | Kelvin ($K$) | $T$ |
-| Enthalpy | Joule per kilogram ($J/kg$) | $h$ |
-| Mass Flow | Kilogram per second ($kg/s$) | $\dot{m}$ |
-| Density | Kilogram per cubic meter ($kg/m^3$) | $\rho$ |
-
-### 1.2 Conservation Laws
-The solver operates on the principle of local conservation at every node $i$:
-- **Mass Conservation**: $\sum \dot{m}_{in} - \sum \dot{m}_{out} = 0$
-- **Energy Conservation**: $\sum (\dot{m} \cdot h)_{in} - \sum (\dot{m} \cdot h)_{out} + \dot{Q} - \dot{W} = 0$
+1. [Fondations physiques](#1-fondations-physiques)
+2. [Fluides (`entropyk-fluids`)](#2-fluides-entropyk-fluids)
+3. [Composants (`entropyk-components`)](#3-composants-entropyk-components)
+4. [Solveur (`entropyk-solver`)](#4-solveur-entropyk-solver)
+5. [Degrés de liberté (DoF)](#5-degrés-de-liberté-dof)
+6. [Frontières Fixed / Free](#6-frontières-fixed--free)
+7. [Fonctionnalités avancées](#7-fonctionnalités-avancées)
+8. [API multi-plateformes](#8-api-multi-plateformes)
+9. [Démarrage et références](#9-démarrage-et-références)
 
 ---
 
-## 2. Fluid Physics (`entropyk-fluids`)
+## 1. Fondations physiques
 
-The `FluidBackend` trait provides thermodynamic properties $(T, \rho, c_p, s)$ as functions of state variables $(P, h)$.
+### 1.1 Typage dimensionnel
 
-### 2.1 Backend Implementations
+Chaque grandeur est un *newtype* SI — pas de `f64` nu aux frontières publiques.
 
-#### A. CoolProp Backend
-Utilizes full Helmholtz energy equations of state (EOS). 
-- **Domain**: Precise research and steady-state validation.
-- **Complexity**: $O(N)$ high overhead due to iterative property calls.
+| Grandeur | Unité interne SI | Symbole |
+|----------|------------------|---------|
+| Pression | Pascal (Pa) | \(P\) |
+| Température | Kelvin (K) | \(T\) |
+| Enthalpie massique | J/kg | \(h\) |
+| Débit massique | kg/s | \(\dot{m}\) |
+| Densité | kg/m³ | \(\rho\) |
+| Puissance | W | \(\dot{Q}\), \(\dot{W}\) |
 
-#### B. Tabular Backend (Bicubic)
-Uses high-fidelity lookup tables with bicubic Hermite spline interpolation.
-- **Equation**: $Z(P, h) = \sum_{i=0}^3 \sum_{j=0}^3 a_{ij} \cdot P^i \cdot h^j$
-- **Performance**: $O(1)$ constant time with SIMD acceleration. Recommended for HIL.
+Les configs JSON acceptent souvent °C / bar pour l’ergonomie ; la conversion vers SI se fait à la construction des composants.
 
-#### C. Incompressible Backend (Linearized)
-For water, glycols, and brines where $\rho$ is nearly constant.
-- **Density**: $\rho(T) = \rho_0 \cdot [1 - \beta(T - T_0)]$
-- **Enthalpy**: $h = c_p \cdot (T - T_0)$
+### 1.2 Lois de conservation
 
-### 2.2 Phase Change Logic
-Fluid backends automatically identify the fluid phase:
-1. **Subcooled**: $h < h_{sat,l}(P)$
-2. **Two-Phase**: $h_{sat,l}(P) \le h \le h_{sat,v}(P)$
-3. **Superheated**: $h > h_{sat,v}(P)$
+Sur chaque nœud / branche, le solveur impose localement :
 
-For two-phase flow, quality $x$ is defined as:
-$$x = \frac{h - h_{sat,l}}{h_{sat,v} - h_{sat,l}}$$
+- **Masse** : \(\sum \dot{m}_{\mathrm{in}} - \sum \dot{m}_{\mathrm{out}} = 0\) (souvent trivialisée sur branche série via ṁ partagé)
+- **Énergie** : \(\sum (\dot{m}\,h)_{\mathrm{in}} - \sum (\dot{m}\,h)_{\mathrm{out}} + \dot{Q} - \dot{W} = 0\)
 
+### 1.3 Vecteur d’état
+
+Chaque **arête** du graphe porte **trois** inconnues :
+
+\[
+\mathbf{x}_{\mathrm{edge}} = [\dot{m},\; P,\; h]
+\]
+
+*(Ancienne doc obsolète : \([P,h]\) seul — post-CM1.x le débit est une inconnue d’arête / de branche.)*
+
+Sur une chaîne série 1-entrée / 1-sortie, les arêtes partagent souvent le même index ṁ (topologie CM1.4).
 
 ---
 
-## 3. Component Technical Reference (`entropyk-components`)
+## 2. Fluides (`entropyk-fluids`)
 
-### 3.1 Compressor (`Compressor`)
+Trait unifié `FluidBackend` : propriétés \((T,\rho,c_p,s,\ldots)\) en fonction de l’état \((P,h)\) (ou autres paires selon l’appel).
 
-#### A. AHRI 540 (10-Coefficient)
-Standard model for positive displacement compressors. Mass flow $\dot{m}$ and power $W$ are calculated using the 3rd-order polynomial:
-$$X = C_1 + C_2 T_s + C_3 T_d + C_4 T_s^2 + C_5 T_s T_d + C_6 T_d^2 + C_7 T_s^3 + C_8 T_d T_s^2 + C_9 T_s T_d^2 + C_{10} T_d^3$$
-*Note: $T_s$ is suction temperature and $T_d$ is discharge temperature in Fahrenheit or Celsius depending on coefficients.*
+### 2.1 Implémentations
 
-#### B. SST/SDT Polynomials
-Used for variable speed compressors where coefficients are adjusted for RPM:
-$$\dot{m} = \sum_{i=0}^3 \sum_{j=0}^3 A_{ij} \cdot SST^i \cdot SDT^j$$
+| Backend | Rôle |
+|---------|------|
+| **CoolProp** | Équations d’état Helmholtz — précision recherche / validation |
+| **Tabular** | Tables + splines bicubiques Hermite — \(O(1)\), adapté HIL / WASM |
+| **Incompressible** | Eau, glycols, saumures — \(\rho(T)\), \(h \approx c_p\,\Delta T\) |
+| **Cached / Damped** | Wrappers perf / stabilité numérique |
+| **TestBackend** | Mocks pour tests sans CoolProp |
 
-### 3.2 Pipe (`Pipe`)
-- **Pressure Drop**: $\Delta P = f \cdot \frac{L}{D} \cdot \frac{\rho v^2}{2}$
-- **Haaland Approximation** (Friction Factor $f$):
-$$\frac{1}{\sqrt{f}} \approx -1.8 \log_{10} \left[ \left(\frac{\epsilon/D}{3.7}\right)^{1.11} + \frac{6.9}{Re} \right]$$
-*Where $Re = \frac{\rho v D}{\mu}$ is the Reynolds number.*
+Feature Cargo typique : `coolprop` via `coolprop-sys` (bibliothèque précompilée sous `vendor/coolprop`).
 
-### 3.3 Heat Exchanger (`HeatExchanger`)
-Single-phase and phase-change modeling via the $\varepsilon$-NTU method.
+### 2.2 Phases
 
-- **Heat Transfer**: $\dot{Q} = \varepsilon \cdot C_{min} \cdot (T_{h,in} - T_{c,in})$
-- **Effectiveness ($\varepsilon$)**:
-    - **Counter-Flow**: $\varepsilon = \frac{1 - \exp(-NTU(1 - C^*))}{1 - C^* \exp(-NTU(1 - C^*))}$
-    - **Evaporator/Condenser**: $\varepsilon = 1 - \exp(-NTU)$ (since $C^* \to 0$ during phase change)
+1. **Sous-refroidi** : \(h < h_{\mathrm{sat},l}(P)\)
+2. **Diphasique** : \(h_{\mathrm{sat},l}(P) \le h \le h_{\mathrm{sat},v}(P)\)
+3. **Surchauffé** : \(h > h_{\mathrm{sat},v}(P)\)
+4. **Supercritique** : au-delà du point critique (selon backend)
+
+Titre vapeur en diphasique :
+
+\[
+x = \frac{h - h_{\mathrm{sat},l}}{h_{\mathrm{sat},v} - h_{\mathrm{sat},l}}
+\]
 
 ---
 
-## 4. Solver Engine (`entropyk-solver`)
+## 3. Composants (`entropyk-components`)
 
-The engine solves $\mathbf{F}(\mathbf{x}) = \mathbf{0}$ where $\mathbf{x}$ is the state vector $[P, h]$ for all edges.
+Tous implémentent le trait `Component` :
 
-### 4.1 Newton-Raphson Solver
-Primary strategy for fast, quadratic convergence.
-$$\mathbf{J}(\mathbf{x}_k) \Delta \mathbf{x} = -\mathbf{F}(\mathbf{x}_k)$$
-$$\mathbf{x}_{k+1} = \mathbf{x}_k + \alpha \Delta \mathbf{x}$$
+- `n_equations()` — nombre de résidus
+- `compute_residuals(state, r)` — \(\mathbf{F}(\mathbf{x})\)
+- `jacobian_entries(state, J)` — \(\partial\mathbf{F}/\partial\mathbf{x}\) (**analytique** de préférence)
+- ports / `set_system_context` / `set_port_context` — indices d’arêtes live
 
-- **Armijo Line Search**: Dynamically adjusts $\alpha$ to ensure steady residual reduction.
-- **Step Clipping**: Hard bounds on $\Delta P$ and $\Delta h$ to maintain physical sanity (e.g., $P > 0$).
-- **Jacobian Freezing**: Reuses $\mathbf{J}$ for $N$ steps if convergence is stable, improving speed by ~40%.
+### 3.1 Compresseurs
 
-### 4.2 Sequential Substitution (Picard)
-Fixed-point iteration for robust initialization:
-$$\mathbf{x}_{k+1} = \mathbf{x}_k - \omega \cdot \mathbf{F}(\mathbf{x}_k)$$
-*Where $\omega \in (0, 1]$ is the relaxation factor (default 0.5).*
+#### `IsentropicCompressor` (cycles émergents courants)
+
+- Loi de débit (si non métré) : \(\dot{m} \approx \rho_{\mathrm{suc}}\,V\,N\,\eta_{\mathrm{vol}}\)
+- Énergie de refoulement via \(\eta_{\mathrm{is}}\)
+- `emergent_pressure` : ne pince pas les pressions de design
+- Mode **ṁ externe** : quand un EXV orifice Fixed métre le débit (CLI)
+
+#### `Compressor` — AHRI 540 (10 coefficients)
+
+\[\begin{aligned}
+X &= C_1 + C_2 T_s + C_3 T_d + C_4 T_s^2 + C_5 T_s T_d + C_6 T_d^2 \\
+&\quad + C_7 T_s^3 + C_8 T_d T_s^2 + C_9 T_s T_d^2 + C_{10} T_d^3
+\end{aligned}\]
+
+où \(X\) est \(\dot{m}\) ou \(\dot{W}\) selon le jeu de coeffs. Unités \(T_s,T_d\) selon la convention du jeu (souvent °F pour AHRI).
+
+#### Cartes SST/SDT
+
+\[\dot{m} = \sum_{i,j} A_{ij}\,\mathrm{SST}^i\,\mathrm{SDT}^j\]
+
+Utilisé aussi pour `ScrewEconomizerCompressor` (vis + port écono, VFD, slide valve).
+
+#### `CentrifugalCompressor`
+
+Carte polytropique (facteur de débit, nombre de Mach périphérique).
+
+### 3.2 Détente
+
+#### `IsenthalpicExpansionValve` / EXV
+
+Trois modes :
+
+| Mode | Équations | Effet de `opening` |
+|------|-----------|--------------------|
+| Isenthalpique seul (`emergent_pressure`, **sans** `orifice_kv`) | \(h_{\mathrm{out}}-h_{\mathrm{in}}=0\) | **Aucun** — ṁ = compresseur |
+| Orifice Fixed (`orifice_kv` + `fix_opening: true`) | + \(\dot{m}=K_v\cdot o\cdot\sqrt{2\rho\Delta P}\) | Paramètre physique |
+| Orifice Free (`fix_opening: false`) | idem, \(o\) inconnu | Régulation / contrôleur |
+
+#### `ExpansionValve`, `CapillaryTube`, `ReversingValve`, `BypassValve`
+
+Voir fiches sous [`docs/components/`](./docs/components/) et meta UI `apps/web/src/lib/componentMeta.ts`.
+
+### 3.3 Conduits (`Pipe`)
+
+Chute de pression Darcy–Weisbach :
+
+\[
+\Delta P = f\,\frac{L}{D}\,\frac{\rho v^2}{2},\quad
+\frac{1}{\sqrt{f}} \approx -1{,}8\log_{10}\!\left[\left(\frac{\varepsilon/D}{3{,}7}\right)^{1{,}11}+\frac{6{,}9}{Re}\right]
+\]
+
+(Haaland). Mode edge-coupled CLI :
+
+- `pressure_drop_pa > 0` → ΔP **imposé** constant
+- `pressure_drop_pa = 0` → ΔP **Darcy** depuis géométrie + ṁ live
+
+### 3.4 Échangeurs
+
+#### `HeatExchanger` générique (ε-NTU / LMTD)
+
+\[
+\dot{Q} = \varepsilon\, C_{\min}\,(T_{h,\mathrm{in}}-T_{c,\mathrm{in}})
+\]
+
+- Contre-courant : \(\varepsilon = \dfrac{1-e^{-NTU(1-C^*)}}{1-C^* e^{-NTU(1-C^*)}}\)
+- Évap / cond (changement de phase, \(C^*\to 0\)) : \(\varepsilon = 1-e^{-NTU}\)
+
+En mode 4 ports live : + fermetures isobares \(P_{\mathrm{out}}-P_{\mathrm{in}}=0\) par flux (pattern Modelica Free-P).
+
+#### `Condenser` / `Evaporator` / `FloodedEvaporator`
+
+- Côté frigorigène : bilans + fermetures SC / SH / vapeur saturée / qualité
+- `emergent_pressure` : P flotte, fermée par l’énergie + closures
+- Secondaire 4 ports : énergie + momentum (isobare ou ΔP quadratique de rating)
+
+ΔP secondaire type rating :
+
+\[
+\Delta P_{\mathrm{sec}} = \Delta P_{\mathrm{rated}}\left(\frac{\dot{m}}{\dot{m}_{\mathrm{rated}}}\right)^2
+\]
+
+via `secondary_rated_pressure_drop_pa` + `secondary_rated_m_flow_kg_s`.
+
+#### Autres HX
+
+`Bphx*`, `AirCooledCondenser`, `FinCoilCondenser`, `MchxCondenserCoil`, `Economizer`, `GasCooler`, `ShellAndTubeHx`, `FanCoilUnit`, `FreeCoolingExchanger` — corrélations / géométries dédiées (voir modules `heat_exchanger/`).
+
+### 3.5 Frontières
+
+| Famille | Rôle |
+|---------|------|
+| `RefrigerantSource` / `Sink` | BC frigorigène (P, qualité / h, ṁ) |
+| `BrineSource` / `Sink` | Eau / glycol (P, T, ṁ, concentration) |
+| `AirSource` / `Sink` | Air humide (psychrométrie) |
+
+### 3.6 Hydraulique / air / jonctions
+
+`Pump`, `Fan` (courbes + affinity laws), `FlowSplitter` / `FlowMerger`, `Drum` (séparateur L/V flooded), `ThermalLoad`, `HeatSource`, `Anchor`, `Node`.
 
 ---
 
-## 5. Advanced Features
+## 4. Solveur (`entropyk-solver`)
 
-### 5.1 Inverse Control
-Swaps independent variables for targets.
-- **Constraints**: Force specific outputs (e.g., Exit Superheat $= 5K$).
-- **Bounded Variables**: Physical limits on inputs (e.g., Valve Opening $0 \le x \le 1$).
+On résout \(\mathbf{F}(\mathbf{x})=\mathbf{0}\) sur le vecteur d’état global (arêtes + actionneurs + couplages).
 
-### 5.2 Multi-Circuit Coupling
-Modeled via bridge components (typically `HeatExchanger`). The solver constructs a unified Jacobian for both circuits to handle thermal feedback loops in a single pass.
+### 4.1 Newton–Raphson (défaut CLI)
+
+\[
+\mathbf{J}(\mathbf{x}_k)\,\Delta\mathbf{x} = -\mathbf{F}(\mathbf{x}_k),\quad
+\mathbf{x}_{k+1} = \mathrm{clamp}\bigl(\mathbf{x}_k + \alpha\,\Delta\mathbf{x}\bigr)
+\]
+
+- **Jacobien** : assemblé depuis les `jacobian_entries` des composants (analytique)
+- **Armijo** : réduit \(\alpha\) si le résidu ne diminue pas (activé CLI si contrôles / orifice / Free-P eau)
+- **Gel de Jacobien** : réutilisation de \(\mathbf{J}\) pendant \(N\) itérations stables
+- **Bornes** : ex. \(P \ge 10\,\mathrm{kPa}\) (`MIN_SOLVER_PRESSURE_PA`) sur les slots pression
+
+### 4.2 Picard (substitution successive)
+
+\[
+\mathbf{x}_{k+1} = (1-\omega)\,\mathbf{x}_k + \omega\,G(\mathbf{x}_k)
+\]
+
+avec \(\omega \approx 0{,}5\). Plus robuste, convergence linéaire. Anderson optionnel.
+
+### 4.3 Fallback
+
+1. Newton d’abord  
+2. Si divergence → Picard  
+3. Si résidu redescend sous un seuil → retour Newton  
+Nombre max de bascules limité (anti-oscillation).
+
+### 4.4 Homotopy
+
+Continuation \(\lambda\) pour chemins difficiles (API solver avancée).
+
+### 4.5 Seed
+
+- Frontières : `seed_from_boundary_conditions`
+- Cycles émergents : staging HP/BP distinct (`build_staged_emergent_seed`)
+- Actionneurs libres : valeurs initiales nominales
 
 ---
 
-## 6. Multi-Platform API Reference
+## 5. Degrés de liberté (DoF)
 
-Entropyk provides high-fidelity bindings with near-perfect parity.
+Un système est **carré** ssi :
 
-| Feature | Rust (`-core`) | Python (`entropyk`) | C / FFI | WASM |
-| :--- | :--- | :--- | :--- | :--- |
-| **Component Creation** | `Compressor::new()` | `ek.Compressor()` | `ek_compressor_create()` | `new Compressor()` |
-| **System Finalization** | `system.finalize()` | `system.finalize()` | `ek_system_finalize()` | `system.finalize()` |
-| **Solving** | `config.solve(&sys)` | `config.solve(sys)` | `ek_solve(sys, cfg)` | `await config.solve(sys)` |
-| **Inverse Control** | `sys.add_constraint()` | `sys.add_constraint()` | `ek_sys_add_constraint()` | `sys.addConstraint()` |
-| **Memory Management** | RAII (Automatic) | Ref-Counted (PyO3) | Manual Free (`_free`) | JS Garbage Collected |
+\[
+n_{\mathrm{équations}} = n_{\mathrm{inconnues}}
+\]
+
+- Sur-contraint → `TopologyError::DofImbalance` à `finalize()` (porte DoF, défaut ON)
+- Sous-contraint → refusé en production CLI (`validate_system_dof`)
+
+Chaque résidu porte un `EquationRole` (Dirichlet, bilan énergie, fermeture outlet SH/SC, actionneur…).
+
+**Règle d’or** : ne jamais fixer **à la fois** \(\dot{m}\) et \(P\) sur le même flux sans libérer un autre DoF.
+
+Ledger UI (aide design, non bit-exact) : `apps/web/src/lib/dofLedger.ts`.
 
 ---
 
-## 7. Getting Started
-- **Step-by-Step Instructions**: Refer to [EXAMPLES_FULL.md](./EXAMPLES_FULL.md).
-- **Performance**: Use `TabularBackend` for real-time HIL applications.
-- **Custom Physics**: Implement the `Component` trait in Rust for specialized modeling.
+## 6. Frontières Fixed / Free
+
+Alignement Modelica `MassFlowSource_T` / `Boundary_pT` — détails et sources : [`docs/modelica-boundary-proof.md`](./docs/modelica-boundary-proof.md).
+
+| Pattern | Source | Sink | Remarque |
+|---------|--------|------|----------|
+| MassFlowSource_T (**défaut** si ṁ imposé) | Fixed T, Fixed ṁ, **Free P** | Fixed P, Free T_out | HX propage P (isobare / ΔP) |
+| Boundary_pT + friction | Fixed P, Fixed T, Free ṁ | Fixed P | Pipe / ΔP HX obligatoire |
+| Rating T_out | Free ṁ | Fixed P + Fixed T_out | ṁ devient inconnu |
+
+Flags JSON : `fix_pressure`, `fix_temperature`, `fix_mass_flow`.
+
+Double Fixed-P aux deux extrémités **uniquement** s’il existe une résistance hydraulique entre elles.
+
+---
+
+## 7. Fonctionnalités avancées
+
+### 7.1 Contrôle inverse / calibration
+
+- **Contraintes** : imposer une sortie (SH = 5 K, capacité = …)
+- **Variables bornées** : actionneurs (`opening`, `z_ua`, `f_m`…) avec min/max
+- CLI : bloc `controls` (`SaturatedController`, etc.)
+
+### 7.2 Multi-circuits et couplages thermiques
+
+Plusieurs circuits dans `circuits[]` ; `thermal_couplings` pour un pont thermique (UA, efficacité) entre circuits. Jacobien unifié.
+
+### 7.3 Ratings saisonniers / part-load
+
+| Métrique | CLI | Norme |
+|----------|-----|-------|
+| IPLV / NPLV / ESEER | `rate` | AHRI 550/590, Eurovent |
+| SCOP | `scop` | EN 14825 |
+| SEER | `seer` | EN 14825 |
+
+Chaque point de charge est une **vraie** re-simulation du cycle, pas une interpolation de points imposés.  
+Référence : [`docs/rating-and-seasonal-metrics.md`](./docs/rating-and-seasonal-metrics.md).
+
+### 7.4 Qualification HX
+
+Sous-commande `qualify` : régime frigorigène fixé, balayage des conditions secondaires.
+
+---
+
+## 8. API multi-plateformes
+
+| Capacité | Rust | Python | C / FFI | WASM |
+|----------|------|--------|---------|------|
+| Création composants | `IsentropicCompressor::new()`… | wrappers PyO3 | `ek_*_create` | `wasm_bindgen` |
+| Finalisation | `system.finalize()` | idem | `ek_system_finalize` | idem |
+| Solve | `NewtonConfig::solve` | idem | `ek_solve` | async JS |
+| Mémoire | RAII | PyO3 refcount | `*_free` manuel | GC JS |
+
+Chemins réels des bindings : `bindings/python`, `bindings/c`, `bindings/wasm` (pas sous `crates/`).
+
+> Audit 2026-07 : certaines classes Python/C historiques restent des stubs — vérifier les warnings ; préférer CLI / Rust pour la physique complète.
+
+---
+
+## 9. Démarrage et références
+
+```bash
+# Build & test
+cargo build
+cargo test
+
+# CLI
+cargo run -p entropyk-cli -- run -c crates/cli/examples/chiller_aircooled_r134a.json
+
+# UI API
+cargo run -q -p entropyk-demo --bin ui-server   # :3030
+```
+
+| Document | Contenu |
+|----------|---------|
+| [`README.md`](./README.md) | Vue d’ensemble FR, catalogue composants, CLI, UI |
+| [`crates/cli/README.md`](./crates/cli/README.md) | Référence CLI JSON |
+| [`EXAMPLES_FULL.md`](./EXAMPLES_FULL.md) | Scénarios avancés |
+| [`docs/CLI_TUTORIAL.md`](./docs/CLI_TUTORIAL.md) | Tutoriel pas à pas |
+| [`docs/components/`](./docs/components/) | Fiches composants |
+| [`AGENTS.md`](./AGENTS.md) | Conventions agents / structure dépôt |
+
+### Politique d’implémentation
+
+- Zero-panic en production (`Result` partout)
+- Jacobiens exacts (FD seulement si chemin documenté / temporaire)
+- Nouveau composant : Rust + CLI + (Python/WASM) + meta UI — voir checklist dans le README racine
diff --git a/README.md b/README.md
index 54b1da8..8dac8f9 100644
--- a/README.md
+++ b/README.md
@@ -1,37 +1,612 @@
 # Entropyk
 
-High-performance thermodynamic simulation engine for HVAC/R and industrial systems.
+Moteur de simulation thermodynamique pour cycles frigorifiques, pompes à chaleur et systèmes CVC (HVAC/R).
 
-## 📚 Documentation & Theory
+Entropyk assemble une **machine** (compresseur, échangeurs, détendeur, boucles secondaires…) sous forme de graphe de composants, résout le système d’équations non linéaires, et expose le même modèle via **Rust**, **CLI JSON**, **Python**, **C** et **WebAssembly**.
 
-Entropyk is built on rigorous physical principles.
-- **[Technical Manual](./DOCUMENTATION.md)**: Exhaustive documentation of physical models (AHRI 540, ε-NTU), solver algorithms (Newton-Raphson, Picard), and multi-platform API parity.
-- **[Comprehensive Examples](./EXAMPLES_FULL.md)**: Advanced scenarios including multi-circuit chillers, inverse control optimization, and HIL integration guide.
+> Documentation approfondie : [`DOCUMENTATION.md`](./DOCUMENTATION.md) · Exemples avancés : [`EXAMPLES_FULL.md`](./EXAMPLES_FULL.md) · Frontières Modelica : [`docs/modelica-boundary-proof.md`](./docs/modelica-boundary-proof.md)
 
-## Quick Start (Rust)
+---
 
-```toml
-[dependencies]
-entropyk = "0.1"
+## Table des matières
+
+1. [Ce que fait Entropyk](#1-ce-que-fait-entropyk)
+2. [Architecture du dépôt](#2-architecture-du-dépôt)
+3. [Principes physiques et DoF](#3-principes-physiques-et-dof)
+4. [Le solveur](#4-le-solveur)
+5. [Catalogue des composants](#5-catalogue-des-composants)
+6. [Mode CLI](#6-mode-cli)
+7. [API Rust (SystemBuilder)](#7-api-rust-systembuilder)
+8. [Frontières Fixed / Free (style Modelica)](#8-frontières-fixed--free-style-modelica)
+9. [EXV, orifice et débit](#9-exv-orifice-et-débit)
+10. [Fluides et backends](#10-fluides-et-backends)
+11. [Interface web](#11-interface-web)
+12. [Bindings Python / C / WASM](#12-bindings-python--c--wasm)
+13. [Installation et commandes](#13-installation-et-commandes)
+14. [Exemples fournis](#14-exemples-fournis)
+15. [Conventions de développement](#15-conventions-de-développement)
+
+---
+
+## 1. Ce que fait Entropyk
+
+Entropyk simule un **cycle frigorifique / PAC / chiller** en régime permanent :
+
+1. Vous déclarez des **composants** (compresseur, condenseur, EXV, évaporateur, sources d’air/eau…).
+2. Vous les **câblez** par des arêtes (`comp:outlet → cond:inlet`).
+3. Le moteur construit un vecteur d’état, assemble résidus + Jacobien, et **Newton** (ou Picard / fallback) converge.
+4. Vous obtenez pressions, enthalpies, débits, puissances, COP, et diagnostics DoF.
+
+Cas d’usage typiques :
+
+| Cas | Comment |
+|-----|---------|
+| Point de design d’un chiller | Config JSON + `entropyk-cli run` |
+| Pressions émergentes (SST/SDT libres) | `emergent_pressure: true` sur HX + EXV |
+| Calibration inverse (cible SH / capacité) | Contrôles `SaturatedController` / facteurs `z_ua` |
+| Rating IPLV / SCOP / SEER | Sous-commandes `rate`, `scop`, `seer` |
+| Qualif. échangeur isolé | `qualify` |
+| Schéma interactif | UI `apps/web` → API `ui-server` |
+
+---
+
+## 2. Architecture du dépôt
+
+```
+Entropyk/
+├── crates/
+│   ├── core/           # Newtypes physiques : Pressure, Temperature, Enthalpy, MassFlow…
+│   ├── fluids/         # FluidBackend + CoolProp / Tabular / Incompressible
+│   ├── components/     # Tous les composants (trait Component)
+│   ├── solver/         # Graphe, DoF, Newton / Picard / Fallback / Homotopy
+│   ├── entropyk/       # Façade : SystemBuilder, SimulationResult, rating
+│   ├── cli/            # Binaire entropyk-cli + exemples JSON
+│   └── vendors/        # Parsers données constructeurs (Copeland, Danfoss, SWEP, Bitzer)
+├── bindings/
+│   ├── python/         # PyO3 (chemin réel — pas crates/bindings/)
+│   ├── c/              # FFI C + cbindgen
+│   └── wasm/           # WebAssembly
+├── apps/web/           # Workbench diagramme (Next.js)
+├── demo/               # ui-server Axum (:3030)
+├── docs/               # Manuels, Modelica, tutoriels
+└── plans/              # Plans d’audit / remediation
 ```
 
-```rust
-use entropyk_solver::{System, FallbackConfig};
+Flux de données :
 
-fn main() {
-    let mut system = System::new();
-    // ... define components and edges ...
-    system.finalize().unwrap();
-    
-    let result = FallbackConfig::default().solve(&system).unwrap();
-    println!("System Converged!");
+```text
+JSON config / SystemBuilder / UI
+        │
+        ▼
+  create_component  →  System (graphe)
+        │
+        ▼
+   finalize() + DoF gate  →  vecteur d’état [ṁ, P, h]…
+        │
+        ▼
+   Newton / Picard / Fallback
+        │
+        ▼
+   SimulationResult (états, énergies, COP, diagnostics)
+```
+
+---
+
+## 3. Principes physiques et DoF
+
+### Vecteur d’état
+
+Chaque **arête** du graphe porte trois inconnues :
+
+| Slot | Symbole | Unité SI |
+|------|---------|----------|
+| 0 | ṁ | kg/s |
+| 1 | P | Pa |
+| 2 | h | J/kg |
+
+Sur une branche série (1 entrée / 1 sortie), les arêtes partagent souvent le **même ṁ** (topologie CM1.4) : le solveur réduit alors le nombre d’inconnues de débit.
+
+### Degrés de liberté (DoF)
+
+Un système est **carré** si :
+
+```text
+n_équations  =  n_inconnues
+```
+
+- Trop d’équations → **sur-contraint** → `finalize()` refuse (DoF gate).
+- Pas assez → **sous-contraint** → refuse aussi en production (CLI).
+
+Chaque composant déclare un nombre d’équations et des **rôles** (`EquationRole`) : bilan d’énergie, chute de pression, Dirichlet de frontière, fermeture de sortie (SH/SC/qualité), actionneur…
+
+Règle d’or (alignée Modelica) : **aucun composant ne doit fixer à la fois ṁ et P** sur le même flux.
+
+---
+
+## 4. Le solveur
+
+Implémentation : `crates/solver`.
+
+### Stratégies disponibles
+
+| Stratégie JSON | Comportement |
+|----------------|--------------|
+| `"newton"` (**défaut**) | Newton–Raphson : `x ← x − α J⁻¹ r`. Jacobien analytique des composants. Recherche linéaire Armijo optionnelle (activée si contrôles / orifice / Free-P eau). |
+| `"picard"` | Substitution successive amortie : `x ← (1−ω)x + ω G(x)`, ω ≈ 0,5. Plus robuste, plus lente. |
+| `"fallback"` | Newton d’abord ; en cas de divergence → Picard ; retour à Newton si le résidu redescend sous un seuil. |
+
+Tolérance typique : `1e-6`. Nombre d’itérations CLI : souvent `300` (augmenter pour des Jacobiens partiellement numériques, ex. certains HX).
+
+### Boucle Newton (schéma)
+
+```text
+1. Seed initial (frontières + staging HP/BP si emergent_pressure)
+2. Calculer r(x)  = résidus de tous les composants
+3. Assembler J(x) = ∂r/∂x
+4. Résoudre J·Δx = −r
+5. Appliquer x ← clamp(x + α·Δx)  (bornes P ≥ 10 kPa, actionneurs…)
+6. Répéter jusqu’à ‖r‖ < tolérance
+```
+
+### Ce qui n’est **pas** le solveur
+
+- Pas de dynamique temporelle (régime permanent).
+- Pas de CFD : les HX sont des modèles 0D/1D (LMTD, ε-NTU, corrélations).
+- Les propriétés fluides viennent du **backend** (CoolProp…), pas d’hypothèses hardcodées (politique « zero fallback » côté composants sérieux).
+
+---
+
+## 5. Catalogue des composants
+
+Tous implémentent le trait `Component` (`n_equations`, `compute_residuals`, `jacobian_entries`, ports…).  
+Types CLI = chaînes `"type"` dans le JSON (voir `crates/cli/src/run.rs`).
+
+### 5.1 Compresseurs
+
+| Type CLI | Rôle | Paramètres clés |
+|----------|------|-----------------|
+| `IsentropicCompressor` | Compresseur η_is + déplacement volumétrique ; mode **emergent** courant | `displacement_m3`, `speed_hz`, `volumetric_efficiency`, `isentropic_efficiency`, `emergent_pressure` |
+| `Compressor` | Cartographie AHRI 540 / SST–SDT (ṁ, puissance) | coeffs `m1`…`m10` ou carte polynomiale |
+| `ScrewEconomizerCompressor` / `ScrewCompressor` | Vis + port écono, VFD, slide valve optionnel | courbes SST/SDT, `speed_hz` |
+| `CentrifugalCompressor` | Carte polytropique (facteur de débit, Mach) | `diameter_m`, `speed_rpm`, γ, R |
+
+En mode **emergent**, le compresseur impose typiquement la **loi de ṁ** (déplacement × ρ × η_vol) et l’énergie de refoulement ; les pressions HP/BP émergent des HX.
+
+Si un EXV à **orifice Fixed** métre le débit, le CLI bascule le compresseur en **ṁ externe** (énergie seule) pour rester carré.
+
+### 5.2 Détente / vannes
+
+| Type CLI | Rôle | Notes critiques |
+|----------|------|-----------------|
+| `IsenthalpicExpansionValve` / `EXV` | Laminants isenthalpiques (`h_out = h_in`) | **Sans `orifice_kv`**, `opening` n’a **aucun effet** — voir [§9](#9-exv-orifice-et-débit) |
+| `ExpansionValve` | Modèles débit orifice / Cd·A / TXV Eames | `flow_model`, `opening`, `beta_m2`… |
+| `CapillaryTube` | Capillaire adiabatique segmenté | `diameter_m`, `length_m`, `n_segments` |
+| `ReversingValve` / `FourWayValve` | 4 voies PAC (froid/chaud) | `mode`, `pressure_drop_pa` |
+| `BypassValve` | Bypass hydronique proportionnel | `opening`, `cv` |
+
+### 5.3 Échangeurs frigorifiques
+
+| Type CLI | Rôle | Notes |
+|----------|------|-------|
+| `Condenser` | Condensation + côté secondaire (eau/air) | `ua`, `emergent_pressure`, `subcooling_k`, `secondary_fluid`, ΔP secondaire optionnelle |
+| `Evaporator` | Évaporation DX + secondaire | `ua`, `superheat_k` / emergent, `secondary_fluid` |
+| `FloodedEvaporator` | Flooded / recirculation | fermeture vapeur saturée ou `quality_control` |
+| `FloodedCondenser` | Condenseur flooded | sortie sous-refroidie |
+| `HeatExchanger` | HX générique 4 ports (LMTD / ε-NTU) | `hot_fluid_id`, `cold_fluid_id`, `ua` |
+| `BphxEvaporator` / `BphxCondenser` | Plaques brasées + corrélations HTC | géométrie plaques, corrélations Longo/Shah… |
+| `AirCooledCondenser` | T_cond ≈ OAT + approach | `oat_k`, `approach_k` |
+| `FinCoilCondenser` | Bobine ailettée air | géométrie tubes/ailettes |
+| `MchxCondenserCoil` | Microcanaux | géométrie MCHX |
+| `CondenserCoil` / `EvaporatorCoil` | Bobines dédiées | variantes rating |
+| `Economizer` | IHX ON/OFF/BYPASS | machine à états |
+| `GasCooler` | Refroidisseur de gaz CO₂ | HTC Pettersen |
+| `ShellAndTubeHx` | Rating Bell-Delaware | |
+| `FanCoilUnit` | FCU eau–air | ε-NTU + BPF |
+| `FreeCoolingExchanger` | Free-cooling côté eau | |
+
+**Pressions émergentes** (`emergent_pressure: true`) : le HX ne pince plus P_sat sur une T de design ; la pression flotte et est fermée par SC/SH/qualité + bilans d’énergie.
+
+**Secondaire 4 ports** : brancher `BrineSource`/`AirSource` → `secondary_inlet` → `secondary_outlet` → `BrineSink`/`AirSink`. Le HX propage la pression (fermeture isobare ou ΔP quadratique de rating).
+
+### 5.4 Tuyauterie, pompes, air
+
+| Type CLI | Rôle | Notes |
+|----------|------|-------|
+| `Pipe` / `RefrigerantPipe` / `WaterPipe` / `AirDuct` | Conduits Darcy–Weisbach | `length_m`, `diameter_m` ; `pressure_drop_pa = 0` → **ΔP Darcy** depuis L/D + ṁ ; `> 0` → ΔP imposé |
+| `Pump` | Courbes H/η + affinity laws | |
+| `Fan` | Courbes pression/η + affinity | souvent sur boucle air |
+| `FlowSplitter` / `FlowMerger` | Jonctions | |
+| `Drum` | Séparateur L/V (flooded) | |
+
+### 5.5 Frontières (sources / sinks)
+
+| Type CLI | Fluide | Impose typiquement |
+|----------|--------|--------------------|
+| `RefrigerantSource` / `RefrigerantSink` | Frigorigène | P (+ qualité ou h), ṁ optionnel |
+| `BrineSource` / `BrineSink` | Eau / glycol | T, ṁ, P (Fixed/Free) |
+| `AirSource` / `AirSink` | Air humide | T_dry, RH, ṁ, P |
+
+Voir [§8](#8-frontières-fixed--free-style-modelica).
+
+### 5.6 Divers
+
+| Type CLI | Rôle |
+|----------|------|
+| `ThermalLoad` | Charge thermique Q (couplage) |
+| `HeatSource` | Injection Q inline |
+| `Anchor` / `RefrigerantNode` | Nœud / ancre SH optionnelle |
+| `Placeholder` | Composant stub (tests / topology) |
+
+### 5.7 Intégration obligatoire d’un nouveau composant
+
+Lorsqu’on ajoute un composant, il doit être câblé **partout** :
+
+1. Trait `Component` + Jacobien exact dans `crates/components`
+2. Export façade `crates/entropyk`
+3. Bras `create_component` dans `crates/cli/src/run.rs`
+4. Wrapper Python (PyO3) et WASM si exposé
+5. Meta UI (`apps/web/src/lib/componentMeta.ts`) si visible dans le workbench
+
+---
+
+## 6. Mode CLI
+
+Binaire : `entropyk-cli` (`crates/cli`).
+
+### Sous-commandes
+
+| Commande | Rôle |
+|----------|------|
+| `run` | Une simulation depuis un JSON |
+| `batch` | Dossier de configs, parallèle |
+| `validate` | Vérifie le JSON / topologie sans résoudre (ou validation légère) |
+| `qualify` | Qualification HX (régime frigorigène fixe, balayage secondaire) |
+| `rate` | IPLV (AHRI 550/590) / ESEER |
+| `scop` | SCOP EN 14825 (bins chauffage) |
+| `seer` | SEER EN 14825 (bins froid) |
+| `schema` | Émet le JSON Schema du Model IR |
+
+Flags globaux : `-v` / `--verbose`, `-q` / `--quiet`.
+
+### Exemples d’invocation
+
+```bash
+# Build
+cargo build --release -p entropyk-cli
+
+# Chiller air R134a
+cargo run -p entropyk-cli -- run \
+  --config crates/cli/examples/chiller_aircooled_r134a.json \
+  --output result.json
+
+# Validation
+cargo run -p entropyk-cli -- validate --config mon_cycle.json
+
+# Batch
+cargo run -p entropyk-cli -- batch -d ./scenarios/ -p 4 -O results.json
+
+# Rating IPLV
+cargo run -p entropyk-cli -- rate -c crates/cli/examples/rate_chiller_iplv_ahri.json
+
+# Schema
+cargo run -p entropyk-cli -- schema -o model-ir.schema.json
+```
+
+### Schéma JSON minimal
+
+```json
+{
+  "name": "Mon chiller",
+  "fluid": "R134a",
+  "fluid_backend": "CoolProp",
+  "circuits": [
+    {
+      "id": 0,
+      "name": "Circuit principal",
+      "components": [
+        { "type": "IsentropicCompressor", "name": "comp", "...": "..." },
+        { "type": "Condenser", "name": "cond", "...": "..." },
+        { "type": "IsenthalpicExpansionValve", "name": "exv", "...": "..." },
+        { "type": "Evaporator", "name": "evap", "...": "..." }
+      ],
+      "edges": [
+        { "from": "comp:outlet", "to": "cond:inlet" },
+        { "from": "cond:outlet", "to": "exv:inlet" },
+        { "from": "exv:outlet", "to": "evap:inlet" },
+        { "from": "evap:outlet", "to": "comp:inlet" }
+      ]
+    }
+  ],
+  "controls": [],
+  "solver": {
+    "strategy": "newton",
+    "max_iterations": 300,
+    "tolerance": 1e-6
+  }
 }
 ```
 
-## Features
+### Pipeline interne de `run`
 
-- **Physics-First**: Strong typing for Pressure, Temperature, and Enthalpy.
-- **Fluid Backends**: CoolProp (RefProp compatible) and high-speed Tabular interpolators.
-- **Advanced Solvers**: Newton-Raphson with Armijo line search and Picard robust fallback.
-- **Inverse Control**: Built-in support for parameter estimation and design-to-target.
-- **Multi-Platform**: First-class support for Python, C/FFI, and WebAssembly.
+1. Parse `ScenarioConfig`
+2. Pour chaque composant : `create_component(...)` (CoolProp, params, modes orifice / emergent…)
+3. Ajout des arêtes nommées `nom:port`
+4. `finalize()` + contrôle DoF
+5. Seed (frontières + staging HP/BP)
+6. Solve selon `solver.strategy`
+7. Sérialisation JSON : états d’arêtes, performances, `dof`, `failure_diagnostics` si échec
+
+### Contrôles (régulation / calibration)
+
+Bloc optionnel `controls` : boucles type `SaturatedController` qui lient une **mesure** (capacité, SH…) à un **actionneur** (`opening`, `z_ua`, `f_m`…).  
+Le solveur augmente alors le vecteur d’état d’inconnues d’actionneurs + résidus de tracking.
+
+---
+
+## 7. API Rust (SystemBuilder)
+
+Façade : crate `entropyk`.
+
+```rust
+use entropyk::SystemBuilder;
+// + types composants depuis entropyk / entropyk_components
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let system = SystemBuilder::new()
+        .with_fluid("R134a")?
+        // .component("comp", Box::new(...))?
+        // .edge_with_ports("comp", "outlet", "cond", "inlet")?
+        .build()?;
+
+    // Ou bas niveau :
+    // let mut newton = entropyk_solver::NewtonConfig::default();
+    // let result = newton.solve(&mut system)?;
+    Ok(())
+}
+```
+
+Points d’entrée utiles :
+
+- `SystemBuilder` — construction ergonomique + JSON round-trip (`to_config_json` / `from_config_json`)
+- `System` — graphe, `finalize`, `dof_report`, `validate_system_dof`
+- `NewtonConfig` / `PicardConfig` / `FallbackConfig` — stratégies
+- `SimulationResult` — sortie structurée
+
+---
+
+## 8. Frontières Fixed / Free (style Modelica)
+
+Alignement documenté dans [`docs/modelica-boundary-proof.md`](./docs/modelica-boundary-proof.md).
+
+| Pattern Modelica | Source | Sink | Conséquence |
+|------------------|--------|------|-------------|
+| **MassFlowSource_T** (défaut Entropyk si ṁ imposé) | Fixed T, Fixed ṁ, **Free P** | Fixed P, Free T_out | Le HX/propager ΔP ferme le DoF pression |
+| **Boundary_pT** | Fixed P, Fixed T, Free ṁ | Fixed P | Il faut une résistance hydraulique (pipe / ΔP HX) entre les deux P |
+| Rating T_out | Free ṁ | Fixed P + Fixed T_out | ṁ devient inconnu (calibration) |
+
+Flags JSON : `fix_pressure`, `fix_temperature`, `fix_mass_flow` (booléens).
+
+**Interdit** : Fixed ṁ **et** Fixed P sur la même source sans degré de liberté ailleurs.
+
+ΔP secondaire de rating (eau/air) :
+
+```json
+"secondary_rated_pressure_drop_pa": 40000,
+"secondary_rated_m_flow_kg_s": 0.5
+```
+
+---
+
+## 9. EXV, orifice et débit
+
+Trois modes pour `IsenthalpicExpansionValve` :
+
+### Mode A — Isenthalpique seul (exemples chillers classiques)
+
+```json
+{ "type": "IsenthalpicExpansionValve", "name": "exv", "emergent_pressure": true }
+```
+
+- Équation : `h_out − h_in = 0`
+- **ṁ imposé par le compresseur** (déplacement)
+- `opening` **ignoré** (même s’il apparaît dans l’UI avec une valeur par défaut)
+
+### Mode B — Orifice Fixed (opening = paramètre)
+
+```json
+{
+  "type": "IsenthalpicExpansionValve",
+  "name": "exv",
+  "emergent_pressure": true,
+  "orifice_kv": 2.0e-6,
+  "opening": 0.6,
+  "fix_opening": true
+}
+```
+
+Loi :
+
+```text
+ṁ = Kv · opening · √(2 · ρ_in · max(ΔP, 0))
+```
+
+Le CLI met le compresseur en **ṁ métré** (lâche la loi de déplacement) pour rester carré.
+
+### Mode C — Orifice Free (opening = inconnue)
+
+```json
+"orifice_kv": 2.0e-6,
+"fix_opening": false
+```
+
+`opening` est une inconnue ; il faut une boucle de régulation (ex. SH → SaturatedController).
+
+> **Piège UI** : le catalogue montre « Opening » même sans Kv. Sans `orifice_kv` explicite, changer l’ouverture ne change **rien**.
+
+Exemple dédié : `crates/cli/examples/chiller_r134a_exv_orifice.json`.
+
+---
+
+## 10. Fluides et backends
+
+| Backend | Usage |
+|---------|--------|
+| **CoolProp** (`fluid_backend: "CoolProp"`) | Frigorigènes (R134a, R410A…), eau — défaut sérieux |
+| **Tabular** | Tables interpolées (WASM / hors CoolProp) |
+| **Incompressible** | Glycols / liquides (ρ, μ de design) |
+| **Cached / Damped** | Wrappers perf / stabilité |
+
+Types physiques dans `entropyk-core` : toujours SI (Pa, K, J/kg, kg/s). Les JSON d’entrée acceptent souvent °C / bar pour l’ergonomie ; la conversion est faite à la construction.
+
+---
+
+## 11. Interface web
+
+| Élément | Chemin |
+|---------|--------|
+| Front Next.js | `apps/web` |
+| API Axum | `cargo run -p entropyk-demo --bin ui-server` → `http://localhost:3030` |
+
+Fonctionnalités :
+
+- Palette de composants + glyph ISO
+- Câblage React Flow
+- Ledger DoF temps réel (`dofLedger.ts`)
+- Coach Fixed/Free Modelica (`boundaryFix.ts`, `dofCoach.ts`)
+- Solve via `POST /api/simulate`
+
+```bash
+# Terminal 1
+cargo run -q -p entropyk-demo --bin ui-server
+
+# Terminal 2
+cd apps/web && npm run dev
+```
+
+---
+
+## 12. Bindings Python / C / WASM
+
+Chemins réels : `bindings/python`, `bindings/c`, `bindings/wasm` (pas sous `crates/`).
+
+### Python (`uv` obligatoire)
+
+```bash
+uv pip install -e ./bindings/python
+uv pip install maturin
+cd bindings/python && uv run maturin develop --release
+uv run pytest tests/
+```
+
+### C
+
+```bash
+cargo build --release -p entropyk-c
+# header généré sous target/ (voir bindings/c/README.md)
+```
+
+### WASM
+
+Voir `bindings/wasm/README.md` — adapté aux backends tabulaires côté client.
+
+> Certaines classes Python historiques sont encore des **stubs / mocks** (audit 2026-07) : vérifier les warnings à la construction et préférer le chemin CLI / Rust pour la physique complète.
+
+---
+
+## 13. Installation et commandes
+
+### Prérequis
+
+- Rust (édition workspace 2021+)
+- CoolProp précompilé sous `vendor/coolprop` (lien via `coolprop-sys`)
+- Pour l’UI : Node.js + npm
+- Pour Python : [`uv`](https://github.com/astral-sh/uv)
+
+### Commandes courantes
+
+```bash
+# Build / tests
+cargo build
+cargo test
+cargo test -p entropyk-components
+cargo test -p entropyk-cli --test hx_standalone
+
+# CLI
+cargo run -p entropyk-cli -- run -c crates/cli/examples/chiller_aircooled_r134a.json
+
+# Clippy / format
+cargo fmt
+cargo clippy
+
+# UI API (port 3030)
+cargo run -q -p entropyk-demo --bin ui-server
+```
+
+Sous Windows, si `ui-server.exe` est verrouillé pendant `cargo test --workspace`, exclure le package démo :
+
+```bash
+cargo test --workspace --exclude entropyk-demo --no-fail-fast
+```
+
+---
+
+## 14. Exemples fournis
+
+Répertoire : `crates/cli/examples/`.
+
+| Fichier | Intérêt |
+|---------|---------|
+| `chiller_aircooled_r134a.json` | Chiller air 4 ports, emergent, air + eau glacée |
+| `chiller_watercooled_r410a.json` | Chiller eau R410A |
+| `chiller_flooded_4port_watercooled.json` | FloodedEvaporator + DoF carré |
+| `chiller_r134a_emergent_pressure.json` | Pressions émergentes |
+| `chiller_r134a_exv_orifice.json` | EXV avec orifice (opening physique) |
+| `chiller_r134a_superheat_control.json` | Boucle SH |
+| `chiller_r134a_slide_valve.json` | Slide valve vis |
+| `chiller_r134a_dual_circuit_staging.json` | Dual circuit |
+| `heatpump_airsource_r410a.json` | PAC air |
+| `heatpump_r410a_reversing_valve.json` | Vanne 4 voies |
+| `hx_air_water_4port.json` | HX isolé air–eau |
+| `bphx_evaporator_condenser.json` | Plaques brasées |
+| `capillary_tube_r134a.json` | Capillaire |
+| `rate_chiller_iplv_ahri.json` | Rating IPLV |
+| `scop_heatpump_r134a.json` | SCOP |
+
+---
+
+## 15. Conventions de développement
+
+- **Langage code** : Rust, `Result` partout (politique zero-panic en production).
+- **Jacobiens** : analytiques exacts ; pas de différences finies sauf chemin explicitement documenté / temporaire.
+- **Types** : newtypes SI (`Pressure`, `Enthalpy`…) — pas de `f64` nus aux frontières publiques.
+- **Docs techniques / commits** : anglais ; communication projet possible en français.
+- **Git** : branche `main`, messages impératifs anglais.
+- **BMAD** : workflows sous `_bmad/` — suivre les fichiers YAML/XML à la lettre si activés.
+
+### Ajouter un composant (checklist)
+
+1. Struct + `Component` dans `crates/components`
+2. Tests unitaires (résidus, Jacobien FD-check)
+3. Export `lib.rs` + façade `entropyk`
+4. Bras CLI `create_component`
+5. Exemple JSON sous `crates/cli/examples/`
+6. Meta UI + bindings si besoin
+
+---
+
+## Liens utiles
+
+| Document | Contenu |
+|----------|---------|
+| [`DOCUMENTATION.md`](./DOCUMENTATION.md) | Modèles physiques, solveur, API |
+| [`EXAMPLES_FULL.md`](./EXAMPLES_FULL.md) | Scénarios avancés |
+| [`docs/CLI_TUTORIAL.md`](./docs/CLI_TUTORIAL.md) | Tutoriel CLI |
+| [`docs/modelica-boundary-proof.md`](./docs/modelica-boundary-proof.md) | Preuve Fixed/Free |
+| [`docs/components/`](./docs/components/) | Fiches composants |
+| [`AGENTS.md`](./AGENTS.md) | Instructions agents / structure |
+| [`crates/cli/README.md`](./crates/cli/README.md) | Détails CLI |
+| [`apps/web/README.md`](./apps/web/README.md) | UI |
+
+---
+
+**Projet** : Entropyk · **Langage** : Rust · **Licence / version** : voir `Cargo.toml` (v0.1.x)
diff --git a/crates/cli/README.md b/crates/cli/README.md
index 58a4f68..6e12c1d 100644
--- a/crates/cli/README.md
+++ b/crates/cli/README.md
@@ -1,169 +1,317 @@
 # Entropyk CLI
 
-Command-line interface for batch thermodynamic simulations.
+Interface en ligne de commande pour lancer, valider et noter des simulations thermodynamiques à partir de fichiers JSON.
+
+Binaire : `entropyk-cli` · Crate : `crates/cli` · Exemples : `crates/cli/examples/`
+
+Le README racine ([`../../README.md`](../../README.md)) décrit l’architecture globale, les composants et le solveur. Ce document se concentre sur **l’usage CLI**.
+
+---
 
 ## Installation
 
 ```bash
 cargo build --release -p entropyk-cli
+
+# Binaire
+./target/release/entropyk-cli --help          # Linux / macOS
+.\target\release\entropyk-cli.exe --help      # Windows
 ```
 
-## Usage
+Ou sans installer :
 
 ```bash
-# Single simulation
-./target/release/entropyk-cli run config.json -o result.json
-
-# Batch processing
-./target/release/entropyk-cli batch ./scenarios/ --parallel 4
-
-# Validate configuration
-./target/release/entropyk-cli validate config.json
-
-# Help
-./target/release/entropyk-cli --help
+cargo run -p entropyk-cli -- <sous-commande> ...
 ```
 
-## Configuration Format
+Flags globaux : `-v` / `--verbose`, `-q` / `--quiet`.
 
-### Complete Chiller Example (R410A + Water)
+---
+
+## Sous-commandes
+
+| Commande | Rôle |
+|----------|------|
+| `run` | Une simulation depuis un JSON |
+| `batch` | Un dossier de configs, en parallèle |
+| `validate` | Vérifie la config (parse / topologie) |
+| `qualify` | Qualification HX (régime frigorigène fixe) |
+| `rate` | IPLV (AHRI 550/590) / ESEER |
+| `scop` | SCOP EN 14825 (bins chauffage) |
+| `seer` | SEER EN 14825 (bins froid) |
+| `schema` | Émet le JSON Schema du Model IR |
+
+### Exemples
+
+```bash
+# Simulation unique
+cargo run -p entropyk-cli -- run \
+  --config crates/cli/examples/chiller_aircooled_r134a.json \
+  --output result.json
+
+# Validation
+cargo run -p entropyk-cli -- validate --config mon_cycle.json
+
+# Batch (4 workers)
+cargo run -p entropyk-cli -- batch -d ./scenarios/ -p 4 -O results.json
+
+# Rating IPLV
+cargo run -p entropyk-cli -- rate -c crates/cli/examples/rate_chiller_iplv_ahri.json
+
+# SCOP
+cargo run -p entropyk-cli -- scop -c crates/cli/examples/scop_heatpump_r134a.json
+
+# Schema
+cargo run -p entropyk-cli -- schema -o model-ir.schema.json
+```
+
+---
+
+## Pipeline de `run`
+
+1. Parse `ScenarioConfig` (fluide, circuits, edges, controls, solver)
+2. Pour chaque composant : `create_component` (`crates/cli/src/run.rs`)
+3. Câblage des arêtes `nom:port` → `nom:port`
+4. `finalize()` + **porte DoF** (système carré obligatoire)
+5. Seed initial (frontières + staging HP/BP si `emergent_pressure`)
+6. Solve : `newton` | `picard` | `fallback`
+7. Sortie JSON : états, performances, `dof`, erreurs / `failure_diagnostics`
+
+---
+
+## Format de configuration
+
+### Structure racine
 
 ```json
 {
-  "name": "Chiller eau glacée R410A",
-  "fluid": "R410A",
-  
-  "circuits": [
-    {
-      "id": 0,
-      "components": [
-        {
-          "type": "Compressor",
-          "name": "comp",
-          "fluid": "R410A",
-          "speed_rpm": 2900,
-          "displacement_m3": 0.000030,
-          "efficiency": 0.85,
-          "m1": 0.85, "m2": 2.5,
-          "m3": 500, "m4": 1500, "m5": -2.5, "m6": 1.8
-        },
-        {
-          "type": "HeatExchanger",
-          "name": "condenser",
-          "ua": 5000,
-          "hot_fluid": "R410A",
-          "hot_t_inlet_c": 45,
-          "hot_pressure_bar": 24,
-          "hot_mass_flow_kg_s": 0.05,
-          "cold_fluid": "Water",
-          "cold_t_inlet_c": 30,
-          "cold_pressure_bar": 1,
-          "cold_mass_flow_kg_s": 0.4
-        },
-        {
-          "type": "ExpansionValve",
-          "name": "exv",
-          "fluid": "R410A",
-          "opening": 1.0
-        },
-        {
-          "type": "Evaporator",
-          "name": "evaporator",
-          "ua": 6000,
-          "t_sat_k": 275.15,
-          "superheat_k": 5
-        }
-      ],
-      "edges": [
-        { "from": "comp:outlet", "to": "condenser:inlet" },
-        { "from": "condenser:outlet", "to": "exv:inlet" },
-        { "from": "exv:outlet", "to": "evaporator:inlet" },
-        { "from": "evaporator:outlet", "to": "comp:inlet" }
-      ]
-    },
-    {
-      "id": 1,
-      "components": [
-        { "type": "Pump", "name": "pump" },
-        { "type": "Placeholder", "name": "load", "n_equations": 0 }
-      ],
-      "edges": [
-        { "from": "pump:outlet", "to": "load:inlet" },
-        { "from": "load:outlet", "to": "pump:inlet" }
-      ]
-    }
-  ],
-  
-  "thermal_couplings": [
-    {
-      "hot_circuit": 0,
-      "cold_circuit": 1,
-      "ua": 6000,
-      "efficiency": 0.95
-    }
-  ],
-  
+  "name": "Mon chiller",
+  "description": "optionnel",
+  "fluid": "R134a",
+  "fluid_backend": "CoolProp",
+  "circuits": [ { "id": 0, "components": [], "edges": [] } ],
+  "controls": [],
+  "thermal_couplings": [],
   "solver": {
-    "strategy": "fallback",
-    "max_iterations": 100,
+    "strategy": "newton",
+    "max_iterations": 300,
     "tolerance": 1e-6
   }
 }
 ```
 
-## Component Types
+| Champ | Description |
+|-------|-------------|
+| `fluid` | Frigorigène principal du circuit (ex. `R134a`, `R410A`) |
+| `fluid_backend` | `CoolProp` (défaut sérieux), Tabular, etc. |
+| `circuits[]` | Un ou plusieurs circuits (id 0…n) |
+| `components[]` | Objets avec `type`, `name`, + paramètres |
+| `edges[]` | `{ "from": "comp:outlet", "to": "cond:inlet" }` |
+| `controls[]` | Boucles inverse / SaturatedController (optionnel) |
+| `solver.strategy` | `newton` (**défaut**), `picard`, `fallback` |
 
-| Type | Required Parameters | Optional Parameters |
-|------|---------------------|---------------------|
-| `Compressor` | `fluid`, `speed_rpm`, `displacement_m3` | `efficiency`, `m1-m10` (AHRI 540) |
-| `HeatExchanger` | `ua`, `hot_fluid`, `cold_fluid`, `hot_t_inlet_c`, `cold_t_inlet_c` | `hot_pressure_bar`, `cold_pressure_bar`, `hot_mass_flow_kg_s`, `cold_mass_flow_kg_s` |
-| `Condenser` | `ua` | `t_sat_k` |
-| `CondenserCoil` | `ua` | `t_sat_k` |
-| `Evaporator` | `ua` | `t_sat_k`, `superheat_k` |
-| `EvaporatorCoil` | `ua` | `t_sat_k`, `superheat_k` |
-| `ExpansionValve` | `fluid` | `opening` |
-| `Pump` | - | `name` |
-| `Placeholder` | `name` | `n_equations` |
+### Exemple moderne (chiller air, 4 ports)
 
-## Thermal Couplings
+Voir `examples/chiller_aircooled_r134a.json` — pattern recommandé :
 
-Thermal couplings define heat transfer between circuits:
+- `IsentropicCompressor` + `emergent_pressure`
+- `Condenser` / `Evaporator` avec secondaires `AirSource`/`BrineSource` → HX → sinks
+- `IsenthalpicExpansionValve` isenthalpique (sans orifice sauf besoin)
+- Sources : Fixed T + Fixed ṁ + **Free P** ; sinks : Fixed P
+
+```bash
+cargo run -p entropyk-cli -- run \
+  -c crates/cli/examples/chiller_aircooled_r134a.json
+```
+
+---
+
+## Types de composants CLI
+
+Chaînes `type` reconnues par `create_component` (liste non exhaustive — voir le match dans `src/run.rs`).
+
+### Compresseurs
+
+| Type | Paramètres utiles |
+|------|-------------------|
+| `IsentropicCompressor` | `displacement_m3`, `speed_hz`, `volumetric_efficiency`, `isentropic_efficiency`, `emergent_pressure` |
+| `Compressor` | Cartes AHRI 540 (`m1`…`m10`) ou SST/SDT |
+| `ScrewEconomizerCompressor` / `ScrewCompressor` | Courbes SST/SDT, VFD, slide valve |
+| `CentrifugalCompressor` | `diameter_m`, `speed_rpm`, γ, R |
+
+### Détente
+
+| Type | Paramètres utiles | Attention |
+|------|-------------------|-----------|
+| `IsenthalpicExpansionValve` / `EXV` | `emergent_pressure`, `t_evap_k` | Sans `orifice_kv`, **`opening` est ignoré** |
+| `ExpansionValve` | `opening`, `flow_model`, `beta_m2`… | |
+| `CapillaryTube` | `diameter_m`, `length_m`, `n_segments` | |
+| `ReversingValve` / `FourWayValve` | `mode`, `pressure_drop_pa` | |
+| `BypassValve` | `opening`, `cv` | |
+
+**EXV orifice** (débit physique) :
 
 ```json
 {
-  "hot_circuit": 0,
-  "cold_circuit": 1,
-  "ua": 5000,
-  "efficiency": 0.95
+  "type": "IsenthalpicExpansionValve",
+  "name": "exv",
+  "emergent_pressure": true,
+  "orifice_kv": 2.0e-6,
+  "opening": 0.6,
+  "fix_opening": true
 }
 ```
 
-- `hot_circuit`: Circuit ID providing heat
-- `cold_circuit`: Circuit ID receiving heat
-- `ua`: Thermal conductance (W/K)
-- `efficiency`: Heat exchanger efficiency (0.0-1.0)
+Loi : `ṁ = Kv · opening · √(2 · ρ · max(ΔP, 0))`.  
+Avec orifice Fixed, le CLI met le compresseur en ṁ métré. Voir `examples/chiller_r134a_exv_orifice.json`.
 
-## Solver Strategies
+### Échangeurs
 
-| Strategy | Description |
-|----------|-------------|
-| `newton` | Newton-Raphson solver |
-| `picard` | Sequential substitution (Picard iteration) |
-| `fallback` | Picard → Newton fallback (recommended) |
+| Type | Paramètres utiles |
+|------|-------------------|
+| `Condenser` / `Evaporator` | `ua`, `emergent_pressure`, `subcooling_k` / SH, `secondary_fluid`, ΔP secondaire |
+| `FloodedEvaporator` | `ua`, `quality_control` |
+| `HeatExchanger` | `ua`, `hot_fluid_id`, `cold_fluid_id` (4 ports) |
+| `BphxEvaporator` / `BphxCondenser` | Géométrie plaques + corrélations |
+| `AirCooledCondenser`, `FinCoilCondenser`, `MchxCondenserCoil` | Bobines air / MCHX |
+| `FreeCoolingExchanger` | Free-cooling eau |
 
-## Exit Codes
+Secondaire 4 ports :
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | Simulation error |
-| 2 | Configuration error |
-| 3 | I/O error |
+```text
+BrineSource/AirSource → HX:secondary_inlet → HX:secondary_outlet → BrineSink/AirSink
+```
 
-## Examples
+ΔP secondaire de rating (optionnel) :
 
-See `crates/cli/examples/` for complete configuration examples:
+```json
+"secondary_rated_pressure_drop_pa": 40000,
+"secondary_rated_m_flow_kg_s": 0.5
+```
 
-- `chiller_r410a_full.json` - Water chiller with R410A
-- `heat_pump_r410a.json` - Air-to-water heat pump
-- `simple_cycle.json` - Simple heat exchanger cycle
+### Tuyauterie / machines tournantes
+
+| Type | Notes |
+|------|-------|
+| `Pipe` / `RefrigerantPipe` / `WaterPipe` / `AirDuct` | `length_m`, `diameter_m` ; `pressure_drop_pa = 0` → **Darcy** L/D ; `> 0` → ΔP imposé |
+| `Pump`, `Fan` | Courbes + affinity laws |
+| `FlowSplitter`, `FlowMerger`, `Drum` | Jonctions / séparateur |
+
+### Frontières
+
+| Type | Flags Fixed/Free |
+|------|------------------|
+| `BrineSource` / `BrineSink` | `fix_pressure`, `fix_temperature`, `fix_mass_flow` |
+| `AirSource` / `AirSink` | idem (+ psychrométrie `t_dry_c`, `rh`) |
+| `RefrigerantSource` / `RefrigerantSink` | P, qualité / h, ṁ |
+
+**Défaut recommandé (Modelica MassFlowSource_T)** : source Fixed T + Fixed ṁ + Free P ; sink Fixed P.
+
+Voir [`docs/modelica-boundary-proof.md`](../../docs/modelica-boundary-proof.md).
+
+### Divers
+
+`ThermalLoad`, `HeatSource`, `Anchor` / `RefrigerantNode`, `Placeholder`.
+
+---
+
+## Contrôles (régulation / calibration)
+
+```json
+"controls": [
+  {
+    "type": "SaturatedController",
+    "id": "sh_loop",
+    "measure": { "component": "evap", "output": "superheat" },
+    "actuator": {
+      "component": "exv",
+      "factor": "opening",
+      "initial": 0.5,
+      "min": 0.1,
+      "max": 1.0
+    },
+    "target": 5.0
+  }
+]
+```
+
+Chaque boucle ajoute des inconnues d’actionneur + résidus de tracking. Le système doit rester DoF-carré (mesure FIX ↔ actionneur FREE).
+
+---
+
+## Stratégies solveur
+
+| Valeur | Comportement |
+|--------|--------------|
+| `newton` | Newton–Raphson (défaut). Armijo activé si contrôles, orifice EXV, ou Free-P sur `BrineSource`. |
+| `picard` | Substitution successive amortie (ω ≈ 0,5) |
+| `fallback` | Newton → Picard si divergence → retour Newton si résidu bas |
+
+```json
+"solver": {
+  "strategy": "newton",
+  "max_iterations": 300,
+  "tolerance": 1e-6
+}
+```
+
+Si le résidu décroît lentement (Jacobien partiellement numérique sur certains HX), augmenter `max_iterations` (ex. 1000).
+
+---
+
+## Sortie et codes de sortie
+
+Sortie typique JSON (`--output`) :
+
+- `status` : `converged` / `Error` / …
+- `iterations`, `state` (arêtes : ṁ, P, h…)
+- `performance` (puissances, COP…)
+- `dof` (équations vs inconnues)
+- `error`, `failure_diagnostics` si échec après itérations
+
+| Code | Signification |
+|------|----------------|
+| 0 | Succès |
+| 1 | Erreur de simulation / non-convergence |
+| 2 | Erreur de configuration |
+| 3 | Erreur I/O |
+
+---
+
+## Exemples fournis (`examples/`)
+
+| Fichier | Intérêt |
+|---------|---------|
+| `chiller_aircooled_r134a.json` | Chiller air 4 ports, emergent |
+| `chiller_watercooled_r410a.json` | Chiller eau R410A |
+| `chiller_flooded_4port_watercooled.json` | FloodedEvaporator |
+| `chiller_r134a_emergent_pressure.json` | Pressions émergentes |
+| `chiller_r134a_exv_orifice.json` | EXV orifice (opening physique) |
+| `chiller_r134a_superheat_control.json` | Boucle SH |
+| `heatpump_airsource_r410a.json` | PAC air |
+| `heatpump_r410a_reversing_valve.json` | Vanne 4 voies |
+| `hx_air_water_4port.json` | HX isolé |
+| `bphx_evaporator_condenser.json` | Plaques brasées |
+| `capillary_tube_r134a.json` | Capillaire |
+| `rate_chiller_iplv_ahri.json` | Rating IPLV |
+| `scop_heatpump_r134a.json` | SCOP |
+
+---
+
+## Pièges fréquents
+
+1. **EXV `opening` sans effet** → il manque `orifice_kv` (sinon isenthalpique seul ; ṁ = compresseur).
+2. **DoF under-constrained** → source Free P sans fermeture P sur le HX/pipe ; ou oubli de brancher le secondaire 4 ports.
+3. **DoF over-constrained** → Fixed ṁ **et** Fixed P sur la même frontière ; ou double Fixed-P sans ΔP.
+4. **Pipe isobare** → avec l’ancien défaut mental « ΔP=0 = rien » : aujourd’hui `pressure_drop_pa = 0` déclenche **Darcy** depuis L/D.
+5. **Exemples obsolètes** cités dans d’anciennes docs (`chiller_r410a_full.json`, etc.) → utiliser la table ci-dessus.
+
+---
+
+## Voir aussi
+
+- [README racine](../../README.md) — architecture, composants, solveur
+- [DOCUMENTATION.md](../../DOCUMENTATION.md) — manuel technique
+- [docs/CLI_TUTORIAL.md](../../docs/CLI_TUTORIAL.md) — tutoriel pas à pas
+- [docs/modelica-boundary-proof.md](../../docs/modelica-boundary-proof.md) — Fixed/Free
+- [docs/rating-and-seasonal-metrics.md](../../docs/rating-and-seasonal-metrics.md) — IPLV / SCOP / SEER