From d4d9f8ae929aa2a08a4c132ba319d7aaf6cfb67b Mon Sep 17 00:00:00 2001
From: John Dyreby <john@isentropic.dev>
Date: Thu, 12 Feb 2026 14:41:09 -0600
Subject: [PATCH] Add type annotation and compound unit docs to dim-si README

Document how to annotate function parameters and return types using
Quantity<D> wrapper with dimension types.

Show pattern for creating compound units like km/h by combining scale
factors from existing units.

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

diff --git a/packages/dim-si/README.md b/packages/dim-si/README.md
index 5910871..23d659c 100644
--- a/packages/dim-si/README.md
+++ b/packages/dim-si/README.md
@@ -109,6 +109,38 @@ const picogram = gram.scaled(PICO);
 
 See [prefixes.ts](./src/prefixes.ts) for all available SI prefixes.
 
+## Type Annotations
+
+Each unit module exports a dimension type (e.g., `Length`, `Velocity`). Wrap
+these with `Quantity` to annotate function parameters and return types:
+
+```typescript
+import type { Quantity } from "@isentropic/dim-quantity";
+import type { Length } from "@isentropic/dim-si/length";
+import type { Time } from "@isentropic/dim-si/time";
+import type { Velocity } from "@isentropic/dim-si/velocity";
+import { divide } from "@isentropic/dim-si/ops";
+
+function speed(
+  distance: Quantity<Length>,
+  duration: Quantity<Time>,
+): Quantity<Velocity> {
+  return divide(distance, duration);
+}
+```
+
+## Compound Units
+
+Create units like `km/h` by combining scale factors from existing units:
+
+```typescript
+import { kilometer } from "@isentropic/dim-si/length";
+import { hour } from "@isentropic/dim-si/time";
+import { meterPerSecond } from "@isentropic/dim-si/velocity";
+
+const kilometerPerHour = meterPerSecond.scaled(kilometer.scale / hour.scale);
+```
+
 ## Adding a New Unit
 
 Units are organized one file per dimension. To add a new unit to an existing