From 1c55637171c102e79da27c1f92fb3358459725d1 Mon Sep 17 00:00:00 2001
From: John Dyreby <john@isentropic.dev>
Date: Thu, 12 Feb 2026 14:42:06 -0600
Subject: [PATCH 1/2] Add worked example to dim-si README

Show a complete kinetic energy calculation with typed functions,
demonstrating dimensional analysis catching errors in context.

Addresses #4
---
 packages/dim-si/README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/packages/dim-si/README.md b/packages/dim-si/README.md
index 23d659c..2510df6 100644
--- a/packages/dim-si/README.md
+++ b/packages/dim-si/README.md
@@ -51,6 +51,36 @@ const total = add(kilometer(5), meter(500));
 const speed = divide(kilometer(100), hour(2));
 ```
 
+## Worked Example
+
+Computing kinetic energy: KE = ½mv²
+
+```typescript
+import type { Quantity } from "@isentropic/dim-quantity";
+import type { Energy, Mass, Velocity } from "@isentropic/dim-isq";
+import { kilogram } from "@isentropic/dim-si/mass";
+import { meterPerSecond } from "@isentropic/dim-si/velocity";
+import { joule, kilojoule } from "@isentropic/dim-si/energy";
+import { multiply, scale, valueIn } from "@isentropic/dim-si/ops";
+
+function kineticEnergy(
+  mass: Quantity<Mass>,
+  velocity: Quantity<Velocity>,
+): Quantity<Energy> {
+  return scale(multiply(mass, multiply(velocity, velocity)), 0.5);
+}
+
+const car = kilogram(1200);
+const highway = meterPerSecond(30);
+
+const ke = kineticEnergy(car, highway);
+valueIn(ke, joule); // 540000
+valueIn(ke, kilojoule); // 540
+
+// Dimension mismatches caught at compile time:
+// kineticEnergy(car, kilogram(10));  // Error: expected Velocity, got Mass
+```
+
 ## Units
 
 ### Base

From 36a2f67c8949b2faf1921fca25333e42ac4533ff Mon Sep 17 00:00:00 2001
From: Greg Troszak <greg@isentropic.dev>
Date: Thu, 12 Feb 2026 16:09:10 -0500
Subject: [PATCH 2/2] docs(dim-si): expand Quick Start with more fluent API
 examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the worked example section with a richer Quick Start that
demonstrates division, multiplication, scaling, and addition — all
using the fluent q() API. Free functions get a one-line mention.
---
 packages/dim-si/README.md | 61 +++++++++++----------------------------
 1 file changed, 17 insertions(+), 44 deletions(-)

diff --git a/packages/dim-si/README.md b/packages/dim-si/README.md
index 2510df6..b50047f 100644
--- a/packages/dim-si/README.md
+++ b/packages/dim-si/README.md
@@ -22,15 +22,25 @@ bunx jsr add @isentropic/dim-si
 
 ```typescript
 import { kilometer, meter } from "@isentropic/dim-si/length";
+import { kilogram } from "@isentropic/dim-si/mass";
 import { hour } from "@isentropic/dim-si/time";
+import { meterPerSecond } from "@isentropic/dim-si/velocity";
+import { meterPerSecondSquared } from "@isentropic/dim-si/acceleration";
+import { newton } from "@isentropic/dim-si/force";
 import { celsius, kelvin } from "@isentropic/dim-si/temperature";
-import { q, valueIn } from "@isentropic/dim-si/ops";
+import { q } from "@isentropic/dim-si/ops";
+
+// Division produces velocity
+q(kilometer(100)).div(hour(2)).in(meterPerSecond); // ~13.89
 
-const speed = q(kilometer(100)).div(hour(2));
-const total = q(kilometer(5)).plus(meter(500));
+// Multiplication produces force (F = ma)
+q(kilogram(80)).times(meterPerSecondSquared(9.81)).in(newton); // 784.8
 
-valueIn(total, meter); // 5500
-valueIn(total, kilometer); // 5.5
+// Addition with unit conversion
+q(kilometer(5)).plus(meter(500)).in(kilometer); // 5.5
+
+// Scaling
+q(meter(3)).scale(2).in(meter); // 6
 
 // Dimension mismatches are compile errors
 q(kilometer(5)).plus(hour(1)); // Error: can't add length and time
@@ -41,45 +51,8 @@ q(celsius(100)).minus(celsius(0)).in(kelvin); // 100 (linear delta)
 q(celsius(20)).plus(celsius.delta(5)).in(celsius); // 25
 ```
 
-Free functions (`add`, `subtract`, `multiply`, `divide`, `scale`) are also
-available:
-
-```typescript
-import { add, divide } from "@isentropic/dim-si/ops";
-
-const total = add(kilometer(5), meter(500));
-const speed = divide(kilometer(100), hour(2));
-```
-
-## Worked Example
-
-Computing kinetic energy: KE = ½mv²
-
-```typescript
-import type { Quantity } from "@isentropic/dim-quantity";
-import type { Energy, Mass, Velocity } from "@isentropic/dim-isq";
-import { kilogram } from "@isentropic/dim-si/mass";
-import { meterPerSecond } from "@isentropic/dim-si/velocity";
-import { joule, kilojoule } from "@isentropic/dim-si/energy";
-import { multiply, scale, valueIn } from "@isentropic/dim-si/ops";
-
-function kineticEnergy(
-  mass: Quantity<Mass>,
-  velocity: Quantity<Velocity>,
-): Quantity<Energy> {
-  return scale(multiply(mass, multiply(velocity, velocity)), 0.5);
-}
-
-const car = kilogram(1200);
-const highway = meterPerSecond(30);
-
-const ke = kineticEnergy(car, highway);
-valueIn(ke, joule); // 540000
-valueIn(ke, kilojoule); // 540
-
-// Dimension mismatches caught at compile time:
-// kineticEnergy(car, kilogram(10));  // Error: expected Velocity, got Mass
-```
+Free functions (`add`, `subtract`, `multiply`, `divide`, `scale`, `valueIn`) are
+also available for a non-chaining style.
 
 ## Units