Rewrite French project docs for architecture, solver, and CLI.

Bring the root README, technical manual, and CLI guide in sync with post-CM1.x state (m,P,h), Modelica Fixed/Free, and current component catalog. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-18 00:06:39 +02:00
parent 3358b74342
commit a4f0e26263
3 changed files with 1187 additions and 247 deletions
--- 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