docs: create comprehensive documentation and deep-dive examples

- Created DOCUMENTATION.md covering core philosophy, modules, and platform specifics.
- Created EXAMPLES_FULL.md with complex multi-platform usage scenarios.
- Updated README.md and docs/index.md to centralize documentation links.

DOCUMENTATION.md

@@ -0,0 +1,97 @@
+# Entropyk: The Definitive Guide
+
+Entropyk is a high-performance thermodynamic simulation framework designed for precision modeling of HVAC/R systems. It combines deep physical principles with modern software engineering patterns to provide a robust, scalable, and cross-platform simulation engine.
+
+## 1. Core Philosophy
+
+### Physics First (Type-Safe Units)
+Entropyk eliminates unit errors at the compiler level. Instead of using `f64` for all physical values, we use strong types:
+- `Pressure` (Pascals, bar, psi)
+- `Temperature` (Kelvin, Celsius, Fahrenheit)
+- `Enthalpy` (J/kg, kJ/kg)
+- `MassFlow` (kg/s, g/s)
+
+These types prevent accidents like adding Celsius to Kelvin or confusing bar with Pascals.
+
+### Topology Safety (Type-State Connections)
+Using Rust's type system, ports transition from `Disconnected` to `Connected`. A `Connected` port is guaranteed to have the same fluid, pressure, and enthalpy as its peer. The solver only accepts systems with fully connected and validated topologies.
+
+---
+
+## 2. Core Modules
+
+### 💧 Fluids (`entropyk-fluids`)
+The thermodynamic property backbone.
+- **CoolProp Backend**: Full Equation of State (EOS) for hundreds of fluids and mixtures.
+- **Tabular Backend**: High-performance bicubic interpolation for real-time applications (HIL).
+- **Caching Layer**: Intelligent LRU caching and SIMD-optimized lookups.
+
+### 🧱 Components (`entropyk-components`)
+Highly modular building blocks.
+- **Compressor**: AHRI 540 10-coefficient and SST/SDT polynomial models.
+- **Heat Exchangers**: ε-NTU and LMTD models with support for phase changes.
+- **Advanced Topology**: `FlowSplitter`, `FlowMerger`, `FlowSource`, and `FlowSink`.
+- **Customizable**: Implement the `Component` trait to add your own physics.
+
+### 🔄 Solver (`entropyk-solver`)
+The convergence engine.
+- **Newton-Raphson**: Fast, quadratic convergence with line search and step clipping.
+- **Picard (Sequential Substitution)**: Robust fallback for systems with high non-linearity.
+- **Jacobian Freezing**: Performance optimization that skips expensive derivative calculations when appropriate.
+
+---
+
+## 3. Advanced Modeling
+
+### Multi-Circuit Brilliance
+Entropyk naturally supports systems with multiple independent circuits (e.g., a Chiller with a refrigerant loop and a water loop) through thermal coupling via Heat Exchangers.
+
+### Inverse Control & Parameter Estimation
+Go beyond "What happens if...?" to "What must I do to...?"
+- **Bounded Control**: Set limits on control variables (e.g., valve opening 0.0-1.0).
+- **Constraint Solver**: Target specific outputs (e.g., "Set speed to achieve 7°C water exit").
+- **Inverse Calibration**: Estimate physical parameters (like UA or efficiency) from experimental data using the one-shot solver.
+
+### Physical Validation
+Every solution is automatically validated for:
+- **Mass Balance**: Σ ṁ_in = Σ ṁ_out within 1e-9 kg/s.
+- **Energy Balance**: (Planned) Conservation of enthalpy across joints.
+
+---
+
+## 4. Multi-Platform Ecosystem
+
+### 🐍 Python
+Mirroring the Rust API, our Python bindings offer the same speed and safety with the flexibility of data science tools (NumPy, Pandas, Jupyter).
+
+### 🛠️ C / FFI
+Integrate Entropyk into PLC controllers, HIL systems (dSPACE, Speedgoat), or legacy C++ codebases with our zero-allocation C header.
+
+### 🌐 WebAssembly
+The same Rust physics engine running in your browser for interactive design tools and client-side simulations.
+
+---
+
+## 5. Developer Ecosystem & Platform Specifics
+
+### 🐍 Python: Integration & Data Science
+- **Performance**: Rust-native speed with zero-copy data passing for large state vectors.
+- **Exception Hierarchy**: Specific catchable exceptions like `SolverError`, `FluidError`, and `ValidationError`.
+- **Interchange**: System states can be exported to NumPy arrays for analysis.
+
+### 🛠️ C / FFI: HIL & Real-Time
+- **Ownership**: Explicit `create`/`free` patterns. Adding a component to a `System` transfers ownership to Rust.
+- **Real-Time Ready**: No dynamic allocations in the `solve` hot path when using the C FFI.
+- **Header**: Single `entropyk.h` required for integration.
+
+### 🌐 WebAssembly: Client-Side Physics
+- **Initialization**: Must call `await init()` before use.
+- **Fluid Tables**: Uses `TabularBackend`. Custom fluids loaded via `load_fluid_table(json_string)`.
+- **JSON First**: Optimized for passing system definitions and results as JSON objects.
+
+---
+
+## 7. Getting Started
+- **Basic Example**: See [EXAMPLES_FULL.md](./EXAMPLES_FULL.md) for a "Simple Cycle" walkthrough.
+- **Performance Tuning**: Use `JacobianBuilder` for custom components to maximize sparse matrix efficiency.
+- **API Reference**: `cargo doc --open` for the full technical API.

EXAMPLES_FULL.md

@@ -0,0 +1,106 @@
+# Entropyk: Comprehensive Examples
+
+This document provides deep-dive examples for various Entropyk features across different platforms.
+
+## 1. Simple Refrigeration Cycle (Rust)
+The "Hello World" of thermodynamics.
+
+```rust
+use entropyk_components::compressor::{Compressor, Ahri540Coefficients};
+use entropyk_components::heat_exchanger::{Condenser, Evaporator};
+use entropyk_components::expansion_valve::ExpansionValve;
+use entropyk_solver::{System, FallbackConfig};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut system = System::new();
+
+    // 1. Create Components
+    let comp = Compressor::new(Ahri540Coefficients::typical(), ...)?;
+    let cond = Condenser::new(5000.0);
+    let valve = ExpansionValve::new(...)?;
+    let evap = Evaporator::new(3000.0);
+
+    // 2. Add to System & Connect
+    let n1 = system.add_component(Box::new(comp));
+    let n2 = system.add_component(Box::new(cond));
+    let n3 = system.add_component(Box::new(valve));
+    let n4 = system.add_component(Box::new(evap));
+
+    system.add_edge(n1, n2)?; // Comp -> Cond
+    system.add_edge(n2, n3)?; // Cond -> Valve
+    system.add_edge(n3, n4)?; // Valve -> Evap
+    system.add_edge(n4, n1)?; // Evap -> Comp
+
+    // 3. Finalize & Solve
+    system.finalize()?;
+    let config = FallbackConfig::default();
+    let result = config.solve(&system)?;
+
+    println!("Cycle COP: {}", result.cop());
+    Ok(())
+}
+```
+
+## 2. Parameter Estimation in Python
+Estimating fouling (UA reduction) from sensor data.
+
+```python
+import entropyk as ek
+
+# Setup system with experimental targets
+system = ek.System()
+comp = system.add_component(ek.Compressor(...))
+cond = system.add_component(ek.Condenser(ua=5000.0)) # Initial guess
+
+# Add Inverse Control target: Discharge temperature must match sensor
+system.add_constraint(target_node=cond, target_value=325.15, ... )
+
+# Solve for the UA that makes the physics match the sensor
+solver = ek.NewtonConfig(inverse_mode=True)
+result = solver.solve(system)
+
+print(f"Calculated UA: {result.component_params[cond].ua} W/K")
+```
+
+## 3. Custom Component Implementation
+How to add a new physical model.
+
+```rust
+use entropyk_components::{Component, SystemState, ResidualVector, JacobianBuilder, ConnectedPort};
+
+struct BypassValve {
+    opening: f64,
+}
+
+impl Component for BypassValve {
+    fn compute_residuals(&self, state: &SystemState, residuals: &mut ResidualVector) -> Result<(), ComponentError> {
+        // P_out = P_in - (k * opening^2 * flow^2)
+        residuals[0] = state[1] - (state[0] - self.calc_dp(state));
+        Ok(())
+    }
+
+    fn jacobian_entries(&self, state: &SystemState, jacobian: &mut JacobianBuilder) -> Result<(), ComponentError> {
+        // Provide partial derivatives for fast convergence
+        jacobian.add_entry(0, 0, self.dp_dm(state));
+        jacobian.add_entry(0, 1, 1.0);
+        Ok(())
+    }
+
+    fn n_equations(&self) -> usize { 1 }
+    fn get_ports(&self) -> &[ConnectedPort] { &self.ports }
+}
+```
+
+## 4. Multi-Circuit Coupling
+Bridging a Chiller to a Water loop.
+
+```rust
+// Evaporator acts as a bridge
+let evaporator = HeatExchanger::new_bridge(ua);
+
+system.add_edge(refrigerant_valve, evaporator.side_a_in)?;
+system.add_edge(evaporator.side_a_out, refrigerant_comp)?;
+
+system.add_edge(water_pump, evaporator.side_b_in)?;
+system.add_edge(evaporator.side_b_out, water_building)?;
+```

README.md

@@ -37,10 +37,9 @@ Then visit [http://localhost:3030](http://localhost:3030) in your browser.
 - `ui/`: Web-based interface for visual modeling.
 - `docs/`: Technical documentation and tutorials.
 
-## Documentation
+- **[Comprehensive Documentation](./DOCUMENTATION.md)**: The definitive guide to Entropyk features and architecture.
-
+- **[Exhaustive Examples](./EXAMPLES_FULL.md)**: Deep-dive code samples for all platforms (Rust, Python, C).
 - **[Tutorial](./docs/TUTORIAL.md)**: Step-by-step guide to using the library and UI.
-- **[Examples](./EXAMPLES.md)**: Detailed code snippets for each component.
 - **[Full Index](./docs/index.md)**: Directory of all project documentation.
 
 ## License

docs/index.md

@@ -2,9 +2,11 @@
 
 ## General Documentation
 
+- **[DOCUMENTATION.md](../DOCUMENTATION.md)** - The definitive guide to Entropyk.
+- **[EXAMPLES_FULL.md](../EXAMPLES_FULL.md)** - Deep-dive usage examples for all platforms.
 - **[README.md](../README.md)** - Main project overview and getting started guide.
 - **[TUTORIAL.md](./TUTORIAL.md)** - Step-by-step guide to using Entropyk (CLI & UI).
-- **[EXAMPLES.md](../EXAMPLES.md)** - Comprehensive usage examples for all library components.
+- **[EXAMPLES.md](../EXAMPLES.md)** - Component-level usage snippets (Legacy).
 - **[README_STORY_1_3.md](../README_STORY_1_3.md)** - Technical details of Port and Connection system implementation.
 
 ## Project Subdirectories