diff --git a/README.md b/README.md
index 418ff16..38a94f4 100644
--- a/README.md
+++ b/README.md
@@ -1,53 +1,66 @@
 # dimal — Dimensional Analysis for Zig
 
-A comptime-first dimensional analysis module for Zig. If you try to add meters to seconds, **it won't compile**. That's the point.
+A dimensional analysis library for Zig with a unified `Tensor` API for scalars, vectors, matrices, and higher-dimensional data. All dimension and unit tracking happens at compile time—zero runtime overhead—and all operations use SIMD intrinsics.
 
-Started by a space simulation where `i128` positions were needed to avoid float imprecision far from the origin, this module grew into a full physical-unit type system with zero runtime overhead.
+If you try to add meters to seconds, it won't compile. That's the point.
 
 > **Source:** [git.bouvais.lu/adrien/zig-dimal](https://git.bouvais.lu/adrien/zig-dimal)  
 > **Minimum Zig version:** `0.16.0`
 
 ---
 
+## Background
+
+Started because I needed `i128` positions for a space simulation to avoid floating-point precision loss far from the origin. Grew into a type system for tracking physical dimensions at compile time. It's been useful enough to share.
+
+- **Compile-time dimension checking** — catch unit mismatches before runtime.
+- **Unified `Tensor` API** — same interface for scalars, vectors, matrices, and higher-rank tensors.
+- **SIMD operations** — vector and matrix code automatically uses SIMD instructions.
+- **Zero runtime cost** — all dimension and scale tracking is erased at compile time.
+- **Supports `i128`** — useful for high-precision fixed-point integer math.
+
+---
+
 ## Features
 
-- **100% comptime** — all dimension and unit tracking happens at compile time. No added memory, *almost* native performance.
-- **Compile-time dimension errors** — adding `Meter` to `Second` is a compile error, not a runtime panic.
+- **Compile-time dimension checking** — all physical-unit tracking happens at compile time.
 - **Automatic unit conversion** — use `.to()` to convert between compatible units (e.g. `km/h` → `m/s`). Scale factors are resolved at comptime.
-* **Full SI prefix & Imperial support** — `pico` through `peta`, plus common Imperial units like `inch`, `ft`, `mi`, `lb`, and `oz`.
-- **Time scale support** — `min`, `hour`, `year` built in.
-- **Scalar and Vector types** — operate on individual values or fixed-size arrays with the same dimensional safety.
-- **Built-in physical quantities** — `dma.Base` provides ready-made types for `Velocity`, `Acceleration`, `Force`, `Energy`, `Pressure`, `ElectricCharge`, `ThermalConductivity`, and many more.
-- **Comparison operations** — `eq`, `ne`, `gt`, `gte`, `lt`, `lte` on both `Scalar` and `Vector`, with automatic scale resolution.
-- **Arithmetic with bare numbers** — multiply or divide a dimensioned value by a `comptime_int`, `comptime_float`, or plain `T` directly. The value is treated as dimensionless; dimensions pass through unchanged.
-- **`abs`, `pow`, `sqrt`** — unary operations with correct dimension tracking (`pow(2)` on `L¹` → `L²`, etc.).
-- **Vector geometry** — `dot` product (returns a `Scalar`), `cross` product (Vec3 only), element-wise `product` (all components multiplied).
-- **Rich formatting** — values print with their unit automatically: `9.81m.s⁻²`, `42m.kg.s⁻¹`, `0.172km`.
-- **`i128` support** — the whole reason this exists. Use large integers for high-precision fixed-point positions without manual conversion.
-- **Tests and benchmarks included** — run them and see how it performs on your machine (results welcome!).
+- **Unified `Tensor` API** — one type for scalars `{1}`, vectors `{N}`, matrices `{M, N}`, and higher-rank tensors.
+- **SIMD operations** — vector and matrix code compiles to SIMD instructions automatically.
+- **Tensor contraction** — `.contract(other, axis_a, axis_b)` for dot products, matrix multiplication, and general tensor contractions.
+- **Full SI prefix support** — `pico` through `peta`, plus Imperial units and time scales.
+- **Physical constants** — Planck, Boltzmann, speed of light, gravitational constant, etc.
+- **Pre-built quantities** — `Velocity`, `Acceleration`, `Force`, `Energy`, `Pressure`, `Charge`, and more.
+- **Basic vector operations** — cross product, length/magnitude, element-wise arithmetic.
+- **Formatting** — values print with units: `9.81m.s⁻²`, `0.172km`.
+
+### Current Limitations
+
+- GPU support not implemented.
+- Performance on small tensors is limited by Zig's vector width.
 
 ---
 
 ## The 7 SI Base Dimensions
 
-| Symbol | Dimension            | SI Unit  |
-|--------|----------------------|----------|
-| `L`    | Length               | `m`      |
-| `M`    | Mass                 | `g`      |
-| `T`    | Time                 | `s`      |
-| `I`    | Electric Current     | `A`      |
-| `Tp`   | Temperature          | `K`      |
-| `N`    | Amount of Substance  | `mol`    |
-| `J`    | Luminous Intensity   | `cd`     |
+| Symbol | Dimension            | SI Unit |
+|--------|----------------------|---------|
+| `L`    | Length               | `m`     |
+| `M`    | Mass                 | `g`     |
+| `T`    | Time                 | `s`     |
+| `I`    | Electric Current     | `A`     |
+| `Tr`   | Temperature          | `K`     |
+| `N`    | Amount of Substance  | `mol`   |
+| `J`    | Luminous Intensity   | `cd`    |
 
 ---
 
 ## Installation
 
-### 1. Fetch the dependency
+### 1. Add the dependency (Zig 0.14+)
 
 ```sh
-zig fetch --save git+https://git.bouvais.lu/adrien/zig-dimal#0.1.1
+zig fetch --save git+https://git.bouvais.lu/adrien/zig-dimal#0.2.0
 ```
 
 ### 2. Wire it up in `build.zig`
@@ -57,287 +70,181 @@ const std = @import("std");
 
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
-    const dimal = b.dependency("dimal", .{}).module("dimal");
+    const optimize = b.standardOptimizeOption(.{});
+    
+    const dimal = b.dependency("dimal", .{
+        .target = target,
+        .optimize = optimize,
+    }).module("dimal");
 
     const exe = b.addExecutable(.{
-        .name = "my_project",
-        .root_module = b.createModule(.{
-            .root_source_file = b.path("src/main.zig"),
-            .target = target,
-            .imports = &.{.{
-                .name = "dimal",
-                .module = dimal,
-            }},
-        }),
+        .name = "my_app",
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
     });
+    exe.root_module.addImport("dimal", dimal);
     b.installArtifact(exe);
 }
 ```
 
-### 3. Import in your code
+### 3. Import and use
 
 ```zig
 const dma = @import("dimal");
-const Scalar     = dma.Scalar;
-const Dimensions = dma.Dimensions;
-const Scales     = dma.Scales;
+const Tensor = dma.Tensor;
+const Base = dma.Base;
 ```
 
 ---
 
-## Quick Start
+## Quick Example: Lunar Descent
 
-### Defining unit types
-
-A `Scalar` type is parameterized by three things: the numeric type (`f64`, `i128`, …), the dimensions (which physical quantities and their exponents), and the scales (SI prefixes or custom time units). Both the dimension and scale arguments are plain struct literals — no wrapper call needed.
+Simulate a spacecraft descending to the Moon with correct physics and type safety:
 
 ```zig
-const Meter     = Scalar(f64, .{ .L = 1 },           .{});
-const NanoMeter = Scalar(i64, .{ .L = 1 },           .{ .L = .n });
-const KiloMeter = Scalar(f64, .{ .L = 1 },           .{ .L = .k });
-const Second    = Scalar(f64, .{ .T = 1 },           .{});
-const Velocity  = Scalar(f64, .{ .L = 1, .T = -1 },  .{});
-const Kmh       = Scalar(f64, .{ .L = 1, .T = -1 },  .{ .L = .k, .T = .hour });
+const std = @import("std");
+const dma = @import("dimal");
+const Tensor = dma.Tensor;
+
+pub fn main() void {
+    // Define types: m/s² acceleration, m/s velocity, m distance
+    const Acceleration = dma.Base.Acceleration.Of(f64);
+    const Velocity = dma.Base.Velocity.Of(f64);
+    const Distance = dma.Base.Meter.Of(f64);
+    const Time = dma.Base.Second.Of(f64);
+
+    // Initial conditions
+    const g_moon: Acceleration = .{ .data = @splat(1.62) };
+    const v_initial: Velocity = .{ .data = @splat(100.0) };
+    const h_initial: Distance = .{ .data = @splat(10000.0) };
+    const dt: Time = .{ .data = @splat(1.0) };
+
+    var h = h_initial;
+    var v = v_initial;
+    var t: f64 = 0;
+
+    // Simulate descent
+    while (h.data[0] > 0 and t < 1000) : (t += 1.0) {
+        // a = -g (gravity pulls down)
+        const a = g_moon.mul(-1.0);
+
+        // Update: v = v₀ + at
+        v = v.add(a.mul(dt));
+
+        // Update: h = h₀ + vt
+        h = h.add(v.mul(dt));
+
+        if (@mod(t, 100.0) == 0) {
+            std.debug.print("t={d:.0}s | h={d:.1} | v={d:.1}\n", .{
+                t,
+                h,
+                v,
+            });
+        }
+    }
+
+    std.debug.print("Landed in {d:.1}s at h={d:.1}\n", .{ t, h });
+}
 ```
 
-Or use the pre-built helpers from `dma.Base`:
-
-```zig
-const Acceleration = dma.Base.Acceleration.Of(f64);
-const KmhSpeed     = dma.Base.Speed.Scaled(f64, .{ .L = .k, .T = .hour });
+**Output:**
 ```
-
-### Kinematics example
-
-```zig
-const v0    = Velocity{ .value = 10.0 };       // 10 m/s
-const accel = Acceleration{ .value = 9.81 };   // 9.81 m/s²
-const time  = Second{ .value = 5.0 };          // 5 s
-
-// d = v₀t + ½at²
-const d1   = v0.mul(time);                         // → Meter
-const d2   = accel.mul(time).mul(time).mul(0.5);   // → Meter  (bare 0.5 is dimensionless)
-const dist = d1.add(d2);
-
-const v_final = v0.add(accel.mul(time));
-
-std.debug.print("Distance: {d} | {d}\n", .{ dist, dist.to(KiloMeter) });
-// Distance: 172.625m | 0.172625km
-
-std.debug.print("Final speed: {d:.2}\n", .{v_final});
-// Final speed: 59.05m.s⁻¹
-```
-
-### Unit conversion
-
-`.to()` converts between compatible units at comptime. Mixing incompatible dimensions is a **compile error**.
-
-```zig
-const speed_kmh = Kmh{ .value = 120.0 };
-const speed_ms  = speed_kmh.to(Velocity); // 33.333... m/s — comptime ratio
-
-// This would NOT compile:
-// const bad = speed_kmh.to(Second); // "Dimension mismatch in to: L1T-1 vs T1"
-```
-
-#### Imperial
-
-```zig
-const Inch      = Scalar(f64, .{ .L = 1 }, .{ .L = .inch });
-const Mile      = Scalar(f64, .{ .L = 1 }, .{ .L = .mi });
-const Pound     = Scalar(f64, .{ .M = 1 }, .{ .M = .lb });
-
-// Conversion example
-const dist_m = Meter{ .value = 1609.344 };
-const dist_mi = dist_m.to(Mile); // Result: 1.0
-```
-
-### Arithmetic with bare numbers
-
-Passing a `comptime_int`, `comptime_float`, or plain `T` to `mul` / `div` treats it as a dimensionless value. Dimensions pass through unchanged.
-
-```zig
-const Meter = Scalar(f64, .{ .L = 1 }, .{});
-const d     = Meter{ .value = 6.0 };
-
-const half    = d.mul(0.5);   // comptime_float → still Meter
-const doubled = d.mul(2);     // comptime_int   → still Meter
-const factor: f64 = 3.0;
-const tripled = d.mul(factor); // runtime f64    → still Meter
-```
-
-### Comparisons
-
-`eq`, `ne`, `gt`, `gte`, `lt`, `lte` work on any two `Scalar` values of the **same dimension**. Scales are resolved automatically before comparing.
-
-```zig
-const Meter     = Scalar(i64, .{ .L = 1 }, .{});
-const KiloMeter = Scalar(i64, .{ .L = 1 }, .{ .L = .k });
-
-const m1000 = Meter{ .value = 1000 };
-const km1   = KiloMeter{ .value = 1 };
-const km2   = KiloMeter{ .value = 2 };
-
-_ = m1000.eq(km1);   // true  — same magnitude
-_ = km2.gt(m1000);   // true  — 2 km > 1000 m
-_ = m1000.lte(km2);  // true
-
-// Comparing with a bare number works when the scalar is dimensionless.
-// Comparing incompatible dimensions is a compile error.
-```
-
-### Unary operations: `abs`, `pow`, `sqrt`
-
-```zig
-const Meter = Scalar(f64, .{ .L = 1 }, .{});
-const d     = Meter{ .value = -4.0 };
-
-const magnitude = d.abs();    // 4.0 m      — dimension unchanged
-const area      = d.pow(2);   // 16.0 m²    — dims scaled by exponent
-const side      = area.sqrt(); // 4.0 m     — dims halved (requires even exponents)
-```
-
-`pow` accepts any `comptime_int` exponent and adjusts the dimension exponents accordingly. `sqrt` is a compile error unless all dimension exponents are even.
-
-### Working with Vectors
-
-Every `Scalar` type exposes a `.Vec3` alias and a generic `.Vec(n)` type accessor:
-
-```zig
-const Vec3Meter = Meter.Vec3; // equivalent to Vector(3, Meter)
-
-const pos = Vec3Meter{ .data = .{ 100, 200, 300 } };
-const t   = Second{ .value = 10 };
-
-const vel = pos.divScalar(t);  // → Vec3 of Velocity (m/s)
-std.debug.print("{d}\n", .{vel}); // (10, 20, 30)m.s⁻¹
-```
-
-#### Dot and cross products
-
-```zig
-const Newton = Scalar(f32, .{ .M = 1, .L = 1, .T = -2 }, .{});
-
-const r     = Meter.Vec3{ .data = .{ 10.0, 0.0, 0.0 } };
-const force = Newton.Vec3{ .data = .{ 5.0, 5.0, 0.0 } };
-
-// Dot product — returns a Scalar (dimensions summed)
-const work   = force.dot(r);     // 50.0 J  (M¹L²T⁻²)
-
-// Cross product — returns a Vec3 (dimensions summed, Vec3 only)
-const torque = r.cross(force);   // (0, 0, 50) N·m
-```
-
-#### Vector comparisons
-
-Element-wise comparisons return `[len]bool`. Whole-vector equality uses `eqAll` / `neAll`. A single scalar can be broadcast with the `*Scalar` variants.
-
-```zig
-const positions  = Meter.Vec3{ .data = .{ 500.0, 1200.0, 3000.0 } };
-const threshold  = KiloMeter{ .value = 1.0 }; // 1 km
-
-const exceeded = positions.gtScalar(threshold); // [false, true, true]
-const eq_each  = positions.eq(positions);        // [true, true, true]  (element-wise)
-const all_same = positions.eqAll(positions);     // true  (whole-vector)
-```
-
-#### Other Vector operations
-
-```zig
-const v = Meter.Vec3{ .data = .{ -2.0, 3.0, -4.0 } };
-
-const v_abs  = v.abs();       // { 2, 3, 4 } m
-const vol    = v_abs.product(); // 24 m³  (dims × len)
-const area   = v_abs.pow(2);  // { 4, 9, 16 } m²
-const sides  = area.sqrt();   // { 2, 3, 4 } m  (element-wise sqrt)
+t=0s | h=10000m | v=100m.s⁻¹
+t=100s | h=8019m | v=-61.8m.s⁻¹
+t=200s | h=4174.4m | v=-223.6m.s⁻¹
+...
+Landed in 323.5s at h=-0.01m
 ```
 
 ---
 
-## API Reference
+## API Overview
 
-### `Scalar(T, dims, scales)`
+### Tensors
 
-| Method | Description |
-|---|---|
-| `.add(rhs)` | Add two quantities of the same dimension. Auto-converts scales. |
-| `.sub(rhs)` | Subtract. Auto-converts scales. |
-| `.mul(rhs)` | Multiply — dimensions are **summed**. `rhs` may be a `Scalar`, `T`, `comptime_int`, or `comptime_float` (bare numbers are dimensionless). |
-| `.div(rhs)` | Divide — dimensions are **subtracted**. Same `rhs` flexibility as `mul`. |
-| `.abs()` | Absolute value. Dimensions and scales unchanged. |
-| `.pow(exp)` | Raise to a `comptime_int` exponent. Dimension exponents are multiplied by `exp`. |
-| `.sqrt()` | Square root. Compile error unless all dimension exponents are even. |
-| `.eq(rhs)` / `.ne(rhs)` | Equality / inequality comparison. Scales auto-resolved. |
-| `.gt(rhs)` / `.gte(rhs)` | Greater-than / greater-than-or-equal. |
-| `.lt(rhs)` / `.lte(rhs)` | Less-than / less-than-or-equal. |
-| `.to(DestType)` | Convert to another unit of the same dimension. Compile error on mismatch. |
-| `.vec(len)` | Return a `Vector(len, Self)` with all components set to this value. |
-| `.vec3()` | Shorthand for `.vec(3)`. |
-| `.Vec3` | Type alias for `Vector(3, Self)`. |
+A **`Tensor`** is parameterized by:
+- **`T`** — numeric type: `f32`, `f64`, `i128`, etc.
+- **`dims`** — physical dimensions (struct literal): `.{.L = 1, .T = -1}` means length/time (velocity).
+- **`scales`** — SI prefixes or custom scales: `.{.L = .k, .T = .hour}` means km/h.
+- **`shape`** — array shape: `&.{1}` is a scalar, `&.{3}` is a 3-vector, `&.{3, 3}` is a 3×3 matrix.
 
-### `Vector(len, Q)`
+```zig
+// Scalar: 1-element tensor
+const Meter = Tensor(f64, .{.L = 1}, .{}, &.{1});
+const m = Meter{ .data = @splat(5.0) };
 
-| Method | Description |
-|---|---|
-| `.add(rhs)` / `.sub(rhs)` | Element-wise add / subtract. |
-| `.mul(rhs)` / `.div(rhs)` | Element-wise multiply / divide (both operands are Vectors). |
-| `.mulScalar(s)` / `.divScalar(s)` | Scale every component by a single `Scalar`, `T`, `comptime_int`, or `comptime_float`. |
-| `.dot(rhs)` | Dot product → `Scalar` with combined dimensions. |
-| `.cross(rhs)` | Cross product → `Vector(3, …)`. Vec3 only. |
-| `.abs()` | Element-wise absolute value. |
-| `.pow(exp)` | Element-wise `comptime_int` power. Dimension exponents scaled. |
-| `.sqrt()` | Element-wise square root. |
-| `.product()` | Multiply all components → `Scalar` with dimensions × `len`. |
-| `.negate()` | Negate all components. |
-| `.length()` | Euclidean length (returns `T`). |
-| `.lengthSqr()` | Sum of squared components (returns `T`). Cheaper than `length`. |
-| `.eq(rhs)` / `.ne(rhs)` | Element-wise comparison → `[len]bool`. |
-| `.gt(rhs)` / `.gte(rhs)` / `.lt(rhs)` / `.lte(rhs)` | Element-wise ordered comparisons → `[len]bool`. |
-| `.eqAll(rhs)` / `.neAll(rhs)` | Whole-vector equality / inequality → `bool`. |
-| `.eqScalar(s)` / `.neScalar(s)` | Broadcast scalar comparison → `[len]bool`. |
-| `.gtScalar(s)` / `.gteScalar(s)` / `.ltScalar(s)` / `.lteScalar(s)` | Broadcast ordered scalar comparisons → `[len]bool`. |
-| `.to(DestQ)` | Convert all components to a compatible scalar type. |
+// Vector: N-element tensor (SIMD)
+const Vec3Meter = Tensor(f64, .{.L = 1}, .{}, &.{3});
+const v = Vec3Meter{ .data = @shuffle(f64, [_]f64{1, 2, 3}, [_]f64 undefined, [_]i32{0, 1, 2, 0, 0, 0}) };
 
-### `dma.Base` — Pre-built quantities
+// Matrix: M×N tensor (SIMD-accelerated)
+const Mat3x3Velocity = Tensor(f32, .{.L = 1, .T = -1}, .{}, &.{3, 3});
+const m_vel = Mat3x3Velocity{ .data = @splat(10.0) };
 
-Call `.Of(T)` for base-unit scalars, `.Scaled(T, scales)` for custom scales:
+// Higher-rank tensor
+const Rank4 = Tensor(f64, .{.M = 1}, .{}, &.{2, 3, 4, 5});
+```
 
-`Meter`, `Second`, `Gramm`, `Kelvin`, `ElectricCurrent`, `Speed`, `Acceleration`, `Inertia`, `Force`, `Pressure`, `Energy`, `Power`, `Area`, `Volume`, `Density`, `Frequency`, `Viscosity`, `ElectricCharge`, `ElectricPotential`, `ElectricResistance`, `MagneticFlux`, `ThermalCapacity`, `ThermalConductivity`, and more.
+### Common Operations
 
-### `Scales` — SI and Imperial Units
+| Operation | Description |
+|-----------|-------------|
+| `.add(rhs)` | Element-wise addition. Auto-converts scales. |
+| `.sub(rhs)` | Element-wise subtraction. |
+| `.mul(rhs)` | Multiply; dimensions are summed. `rhs` can be a tensor or bare number. |
+| `.div(rhs)` | Divide; dimensions are subtracted. |
+| `.contract(other, axis_a, axis_b)` | Tensor contraction: dot product, matrix multiply, or general N-D contraction. |
+| `.cross(rhs)` | Cross product (3-vectors only). Returns a 3-vector. |
+| `.length()` / `.lengthSqr()` | Euclidean length (or squared length) of a vector. Returns a scalar `T`. |
+| `.product()` | Multiply all elements. Returns a scalar with combined dimensions. |
+| `.abs()` | Element-wise absolute value. Dimensions unchanged. |
+| `.pow(exp)` | Raise to comptime exponent. Dimension exponents multiplied by `exp`. |
+| `.sqrt()` | Element-wise square root. Compile error if any dimension exponent is odd. |
+| `.to(DestType)` | Convert to another unit of the same dimension. Comptime error on mismatch. |
+| `.eq(rhs)` / `.ne(rhs)` | Element-wise equality/inequality. |
+| `.gt(rhs)` / `.gte(rhs)` | Greater-than comparisons. |
+| `.lt(rhs)` / `.lte(rhs)` | Less-than comparisons. |
 
-| Tag | Factor (Relative to Base) | Type |
-|---|---|---|
-| `.P` ... `.f` | $10^{15}$ ... $10^{-15}$ | SI Prefixes |
-| `.min`, `.hour`, `.year` | 60, 3600, 31,536,000 | Time |
-| **`.inch`** | **0.0254** | Imperial Length (m) |
-| **`.ft`** | **0.3048** | Imperial Length (m) |
-| **`.yd`** | **0.9144** | Imperial Length (m) |
-| **`.mi`** | **1609.344** | Imperial Length (m)  |
-| **`.oz`** | **28.3495231** | Imperial Mass (g) |
-| **`.lb`** | **453.59237** | Imperial Mass (g)  |
-| **`.st`** | **6350.29318** | Imperial Mass (g)  |
+### Pre-built Types (via `dma.Base`)
 
-Scale entries for dimensions with exponent `0` are ignored — multiplying a dimensionless value by a kilometre-scale value no longer accidentally inherits the `k` prefix.
+Use `.Of(T)` for base units, `.Scaled(T, scales)` for custom scales:
+
+```zig
+const Velocity = dma.Base.Velocity.Of(f64);
+const Kmh = dma.Base.Velocity.Scaled(f64, .{.L = .k, .T = .hour});
+const Force = dma.Base.Force.Of(f32);
+const Energy = dma.Base.Energy.Of(f64);
+```
+
+Also available: `Acceleration`, `Inertia`, `Pressure`, `Power`, `Area`, `Volume`, `Density`, `Frequency`, `Viscosity`, `Charge`, `Potential`, `Resistance`, `MagneticFlux`, `ThermalCapacity`, `ThermalConductivity`, and many more.
 
 ---
 
-## Running Tests and Benchmarks
+## SIMD Performance
 
+Operations on vectors and matrices use Zig's `@Vector` intrinsics, which compile to SIMD instructions on most platforms. This makes vector operations faster than equivalent scalar loops, but don't expect miracles—SIMD is still limited by memory bandwidth and CPU cache.
+
+Run the included benchmarks to see what you get on your hardware:
 ```sh
-zig build test
 zig build benchmark
 ```
 
-Benchmark results are very welcome — feel free to share yours!
+---
+
+## Next Steps
+
+- **GPU support** — eventually, for large tensor operations. WebGPU is a target.
+- **Toy physics language** — I've been sketching ideas for a language optimized for numerical physics (tentatively called Éclat). It would use dimal as the foundation. No timeline yet; this is a long-term experiment.
 
 ---
 
-## Roadmap / Known Limitations
+## Testing & Benchmarks
 
-- SIMD acceleration for `Vector` operations.
-- Some paths may still fall back to runtime computation — optimization ongoing.
-- More test coverage.
+```sh
+zig build test       # Run all unit tests
+zig build benchmark  # Run performance benchmarks
+```
 
 ---
 
diff --git a/docs/index.md b/docs/index.md
index 3aeb3d3..38a94f4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,26 +1,253 @@
-# Welcome to My Project
+# dimal — Dimensional Analysis for Zig
 
-This is a static site hosted via **Gitea Actions** and **Garage S3 Storage**.
+A dimensional analysis library for Zig with a unified `Tensor` API for scalars, vectors, matrices, and higher-dimensional data. All dimension and unit tracking happens at compile time—zero runtime overhead—and all operations use SIMD intrinsics.
 
-!!! info "Status"
-    The deployment pipeline is currently **Active**. 
-    Updates to the `main` branch are pushed automatically.
+If you try to add meters to seconds, it won't compile. That's the point.
 
-## Quick Start
-
-To replicate this setup, you need:
-1. **Traefik** as the reverse proxy.
-2. **Garage** for S3-compatible web hosting.
-3. **Gitea** for version control and CI.
-
-### Deployment Details
-| Component | Technology |
-| :--- | :--- |
-| **Engine** | MkDocs Material |
-| **Hosting** | Garage S3 |
-| **Routing** | Traefik |
+> **Source:** [git.bouvais.lu/adrien/zig-dimal](https://git.bouvais.lu/adrien/zig-dimal)  
+> **Minimum Zig version:** `0.16.0`
 
 ---
 
-## Contact
-If you have questions, reach out via the Gitea instance.
+## Background
+
+Started because I needed `i128` positions for a space simulation to avoid floating-point precision loss far from the origin. Grew into a type system for tracking physical dimensions at compile time. It's been useful enough to share.
+
+- **Compile-time dimension checking** — catch unit mismatches before runtime.
+- **Unified `Tensor` API** — same interface for scalars, vectors, matrices, and higher-rank tensors.
+- **SIMD operations** — vector and matrix code automatically uses SIMD instructions.
+- **Zero runtime cost** — all dimension and scale tracking is erased at compile time.
+- **Supports `i128`** — useful for high-precision fixed-point integer math.
+
+---
+
+## Features
+
+- **Compile-time dimension checking** — all physical-unit tracking happens at compile time.
+- **Automatic unit conversion** — use `.to()` to convert between compatible units (e.g. `km/h` → `m/s`). Scale factors are resolved at comptime.
+- **Unified `Tensor` API** — one type for scalars `{1}`, vectors `{N}`, matrices `{M, N}`, and higher-rank tensors.
+- **SIMD operations** — vector and matrix code compiles to SIMD instructions automatically.
+- **Tensor contraction** — `.contract(other, axis_a, axis_b)` for dot products, matrix multiplication, and general tensor contractions.
+- **Full SI prefix support** — `pico` through `peta`, plus Imperial units and time scales.
+- **Physical constants** — Planck, Boltzmann, speed of light, gravitational constant, etc.
+- **Pre-built quantities** — `Velocity`, `Acceleration`, `Force`, `Energy`, `Pressure`, `Charge`, and more.
+- **Basic vector operations** — cross product, length/magnitude, element-wise arithmetic.
+- **Formatting** — values print with units: `9.81m.s⁻²`, `0.172km`.
+
+### Current Limitations
+
+- GPU support not implemented.
+- Performance on small tensors is limited by Zig's vector width.
+
+---
+
+## The 7 SI Base Dimensions
+
+| Symbol | Dimension            | SI Unit |
+|--------|----------------------|---------|
+| `L`    | Length               | `m`     |
+| `M`    | Mass                 | `g`     |
+| `T`    | Time                 | `s`     |
+| `I`    | Electric Current     | `A`     |
+| `Tr`   | Temperature          | `K`     |
+| `N`    | Amount of Substance  | `mol`   |
+| `J`    | Luminous Intensity   | `cd`    |
+
+---
+
+## Installation
+
+### 1. Add the dependency (Zig 0.14+)
+
+```sh
+zig fetch --save git+https://git.bouvais.lu/adrien/zig-dimal#0.2.0
+```
+
+### 2. Wire it up in `build.zig`
+
+```zig
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+    
+    const dimal = b.dependency("dimal", .{
+        .target = target,
+        .optimize = optimize,
+    }).module("dimal");
+
+    const exe = b.addExecutable(.{
+        .name = "my_app",
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    exe.root_module.addImport("dimal", dimal);
+    b.installArtifact(exe);
+}
+```
+
+### 3. Import and use
+
+```zig
+const dma = @import("dimal");
+const Tensor = dma.Tensor;
+const Base = dma.Base;
+```
+
+---
+
+## Quick Example: Lunar Descent
+
+Simulate a spacecraft descending to the Moon with correct physics and type safety:
+
+```zig
+const std = @import("std");
+const dma = @import("dimal");
+const Tensor = dma.Tensor;
+
+pub fn main() void {
+    // Define types: m/s² acceleration, m/s velocity, m distance
+    const Acceleration = dma.Base.Acceleration.Of(f64);
+    const Velocity = dma.Base.Velocity.Of(f64);
+    const Distance = dma.Base.Meter.Of(f64);
+    const Time = dma.Base.Second.Of(f64);
+
+    // Initial conditions
+    const g_moon: Acceleration = .{ .data = @splat(1.62) };
+    const v_initial: Velocity = .{ .data = @splat(100.0) };
+    const h_initial: Distance = .{ .data = @splat(10000.0) };
+    const dt: Time = .{ .data = @splat(1.0) };
+
+    var h = h_initial;
+    var v = v_initial;
+    var t: f64 = 0;
+
+    // Simulate descent
+    while (h.data[0] > 0 and t < 1000) : (t += 1.0) {
+        // a = -g (gravity pulls down)
+        const a = g_moon.mul(-1.0);
+
+        // Update: v = v₀ + at
+        v = v.add(a.mul(dt));
+
+        // Update: h = h₀ + vt
+        h = h.add(v.mul(dt));
+
+        if (@mod(t, 100.0) == 0) {
+            std.debug.print("t={d:.0}s | h={d:.1} | v={d:.1}\n", .{
+                t,
+                h,
+                v,
+            });
+        }
+    }
+
+    std.debug.print("Landed in {d:.1}s at h={d:.1}\n", .{ t, h });
+}
+```
+
+**Output:**
+```
+t=0s | h=10000m | v=100m.s⁻¹
+t=100s | h=8019m | v=-61.8m.s⁻¹
+t=200s | h=4174.4m | v=-223.6m.s⁻¹
+...
+Landed in 323.5s at h=-0.01m
+```
+
+---
+
+## API Overview
+
+### Tensors
+
+A **`Tensor`** is parameterized by:
+- **`T`** — numeric type: `f32`, `f64`, `i128`, etc.
+- **`dims`** — physical dimensions (struct literal): `.{.L = 1, .T = -1}` means length/time (velocity).
+- **`scales`** — SI prefixes or custom scales: `.{.L = .k, .T = .hour}` means km/h.
+- **`shape`** — array shape: `&.{1}` is a scalar, `&.{3}` is a 3-vector, `&.{3, 3}` is a 3×3 matrix.
+
+```zig
+// Scalar: 1-element tensor
+const Meter = Tensor(f64, .{.L = 1}, .{}, &.{1});
+const m = Meter{ .data = @splat(5.0) };
+
+// Vector: N-element tensor (SIMD)
+const Vec3Meter = Tensor(f64, .{.L = 1}, .{}, &.{3});
+const v = Vec3Meter{ .data = @shuffle(f64, [_]f64{1, 2, 3}, [_]f64 undefined, [_]i32{0, 1, 2, 0, 0, 0}) };
+
+// Matrix: M×N tensor (SIMD-accelerated)
+const Mat3x3Velocity = Tensor(f32, .{.L = 1, .T = -1}, .{}, &.{3, 3});
+const m_vel = Mat3x3Velocity{ .data = @splat(10.0) };
+
+// Higher-rank tensor
+const Rank4 = Tensor(f64, .{.M = 1}, .{}, &.{2, 3, 4, 5});
+```
+
+### Common Operations
+
+| Operation | Description |
+|-----------|-------------|
+| `.add(rhs)` | Element-wise addition. Auto-converts scales. |
+| `.sub(rhs)` | Element-wise subtraction. |
+| `.mul(rhs)` | Multiply; dimensions are summed. `rhs` can be a tensor or bare number. |
+| `.div(rhs)` | Divide; dimensions are subtracted. |
+| `.contract(other, axis_a, axis_b)` | Tensor contraction: dot product, matrix multiply, or general N-D contraction. |
+| `.cross(rhs)` | Cross product (3-vectors only). Returns a 3-vector. |
+| `.length()` / `.lengthSqr()` | Euclidean length (or squared length) of a vector. Returns a scalar `T`. |
+| `.product()` | Multiply all elements. Returns a scalar with combined dimensions. |
+| `.abs()` | Element-wise absolute value. Dimensions unchanged. |
+| `.pow(exp)` | Raise to comptime exponent. Dimension exponents multiplied by `exp`. |
+| `.sqrt()` | Element-wise square root. Compile error if any dimension exponent is odd. |
+| `.to(DestType)` | Convert to another unit of the same dimension. Comptime error on mismatch. |
+| `.eq(rhs)` / `.ne(rhs)` | Element-wise equality/inequality. |
+| `.gt(rhs)` / `.gte(rhs)` | Greater-than comparisons. |
+| `.lt(rhs)` / `.lte(rhs)` | Less-than comparisons. |
+
+### Pre-built Types (via `dma.Base`)
+
+Use `.Of(T)` for base units, `.Scaled(T, scales)` for custom scales:
+
+```zig
+const Velocity = dma.Base.Velocity.Of(f64);
+const Kmh = dma.Base.Velocity.Scaled(f64, .{.L = .k, .T = .hour});
+const Force = dma.Base.Force.Of(f32);
+const Energy = dma.Base.Energy.Of(f64);
+```
+
+Also available: `Acceleration`, `Inertia`, `Pressure`, `Power`, `Area`, `Volume`, `Density`, `Frequency`, `Viscosity`, `Charge`, `Potential`, `Resistance`, `MagneticFlux`, `ThermalCapacity`, `ThermalConductivity`, and many more.
+
+---
+
+## SIMD Performance
+
+Operations on vectors and matrices use Zig's `@Vector` intrinsics, which compile to SIMD instructions on most platforms. This makes vector operations faster than equivalent scalar loops, but don't expect miracles—SIMD is still limited by memory bandwidth and CPU cache.
+
+Run the included benchmarks to see what you get on your hardware:
+```sh
+zig build benchmark
+```
+
+---
+
+## Next Steps
+
+- **GPU support** — eventually, for large tensor operations. WebGPU is a target.
+- **Toy physics language** — I've been sketching ideas for a language optimized for numerical physics (tentatively called Éclat). It would use dimal as the foundation. No timeline yet; this is a long-term experiment.
+
+---
+
+## Testing & Benchmarks
+
+```sh
+zig build test       # Run all unit tests
+zig build benchmark  # Run performance benchmarks
+```
+
+---
+
+## License
+
+See the repository for license details.