docs: add examples, guides, and expanded keywords for AI discoverability

Author: TheCryptoDonkey

README.md

@@ -209,6 +209,21 @@ class MyEngine implements RoutingEngine {
 }
 ```
 
+## Examples
+
+Runnable examples in [`examples/`](./examples/):
+
+- **[basic-usage.ts](./examples/basic-usage.ts)** — find a fair meeting point for three people
+- **[comparing-fairness-strategies.ts](./examples/comparing-fairness-strategies.ts)** — see how min_max, min_total, and min_variance rank differently
+- **[custom-engine.ts](./examples/custom-engine.ts)** — implement the RoutingEngine interface with a mock engine
+
+Run any example with `npx tsx examples/<name>.ts`.
+
+## Guides
+
+- **[Choosing a Fairness Strategy](./docs/choosing-a-fairness-strategy.md)** — when to use min_max vs min_total vs min_variance
+- **[Self-Hosting a Routing Engine](./docs/self-hosting-a-routing-engine.md)** — run Valhalla, OSRM, or GraphHopper locally with Docker
+
 ## Companion Library
 
 **geohash-kit** — spatial primitives (pointInPolygon, GeoJSON types, distance utilities) used internally by rendezvous-kit.

docs/choosing-a-fairness-strategy.md

@@ -0,0 +1,67 @@
+# Choosing a Fairness Strategy
+
+rendezvous-kit scores candidate venues using a **fairness strategy** — a function that reduces each participant's travel time into a single score. Lower scores are better.
+
+## The Three Strategies
+
+### `min_max` — Nobody travels excessively (default)
+
+Optimises for the **worst-case** travel time. The score is the longest individual journey.
+
+**Best for:** Social meetups, events where one person travelling much further than everyone else feels unfair.
+
+```
+Alice: 30 min, Bob: 45 min, Carol: 20 min → score = 45
+```
+
+### `min_total` — Minimise group effort
+
+Optimises for the **sum** of all travel times. The score is the total minutes spent travelling across the whole group.
+
+**Best for:** Logistics, delivery hubs, or scenarios where total cost (fuel, time, emissions) matters more than individual fairness.
+
+```
+Alice: 30 min, Bob: 45 min, Carol: 20 min → score = 95
+```
+
+### `min_variance` — Everyone travels roughly equally
+
+Optimises for **equalising** travel times. The score is the standard deviation of individual journey times.
+
+**Best for:** Repeated meetings (e.g. weekly team syncs) where perceived fairness over time matters. Everyone should feel they are making a similar effort.
+
+```
+Alice: 30 min, Bob: 45 min, Carol: 20 min → score = 10.3
+Alice: 35 min, Bob: 32 min, Carol: 33 min → score = 1.2 ← preferred
+```
+
+## When They Disagree
+
+The three strategies often pick different top venues. Consider a scenario with two candidate cafés:
+
+| Café | Alice | Bob | Carol | min_max | min_total | min_variance |
+|------|-------|-----|-------|---------|-----------|--------------|
+| The Fox | 25 min | 50 min | 25 min | 50 | 100 | 11.8 |
+| The Bear | 35 min | 35 min | 35 min | 35 | 105 | 0.0 |
+
+- **min_max** picks The Bear (worst case is 35 vs 50)
+- **min_total** picks The Fox (total is 100 vs 105)
+- **min_variance** picks The Bear (perfectly equal)
+
+There is no universally "correct" strategy — choose based on what matters to your users.
+
+## Usage
+
+```typescript
+const suggestions = await findRendezvous(engine, {
+  participants: [alice, bob, carol],
+  mode: 'drive',
+  maxTimeMinutes: 60,
+  venueTypes: ['cafe'],
+  fairness: 'min_variance',  // or 'min_max' (default), 'min_total'
+})
+```
+
+## Comparing Strategies
+
+See [`examples/comparing-fairness-strategies.ts`](../examples/comparing-fairness-strategies.ts) for a runnable script that shows how the three strategies rank the same venues differently.

docs/self-hosting-a-routing-engine.md

@@ -0,0 +1,121 @@
+# Self-Hosting a Routing Engine
+
+rendezvous-kit is engine-agnostic — it works with any routing service that can compute isochrones and route matrices. This guide covers self-hosting options so you can run the full pipeline without third-party API keys or rate limits.
+
+## Quick Comparison
+
+| Engine | Isochrone | Route Matrix | Docker image | Typical RAM | Setup effort |
+|--------|:---------:|:------------:|--------------|-------------|--------------|
+| Valhalla | Yes | Yes | `ghcr.io/gis-ops/docker-valhalla` | 2–8 GB | Medium |
+| OSRM | No | Yes | `osrm/osrm-backend` | 1–4 GB | Low |
+| GraphHopper | Yes | Yes | `graphhopper/graphhopper` | 2–6 GB | Low |
+
+**Recommendation:** Valhalla is the best all-round choice — it supports isochrones, route matrices, and turn-by-turn routing. OSRM is lighter but cannot compute isochrones, so you would need to supply your own intersection polygon or pair it with another engine.
+
+## Valhalla (Recommended)
+
+The easiest way to run Valhalla is with the [GIS-OPS Docker image](https://github.com/gis-ops/docker-valhalla):
+
+```bash
+docker run -d --name valhalla \
+  -p 8002:8002 \
+  -e tile_urls=https://download.geofabrik.de/europe/great-britain-latest.osm.pbf \
+  -v valhalla_data:/custom_files \
+  ghcr.io/gis-ops/docker-valhalla/valhalla:latest
+```
+
+The first run downloads and builds routing tiles — this can take 10–60 minutes depending on the region size. Subsequent starts are fast.
+
+**Use in rendezvous-kit:**
+
+```typescript
+import { ValhallaEngine } from 'rendezvous-kit/engines/valhalla'
+
+const engine = new ValhallaEngine({ baseUrl: 'http://localhost:8002' })
+```
+
+### Choosing a Region
+
+Download `.osm.pbf` extracts from [Geofabrik](https://download.geofabrik.de/). Smaller regions use less RAM and build faster:
+
+- `great-britain-latest.osm.pbf` — ~1.2 GB, builds in ~15 min, ~4 GB RAM
+- `europe-latest.osm.pbf` — ~28 GB, builds in hours, ~16 GB RAM
+- Country-level extracts are a good compromise
+
+### Multiple Regions
+
+To cover multiple non-contiguous regions, download separate extracts and merge them with [Osmium](https://osmcode.org/osmium-tool/):
+
+```bash
+osmium merge england.osm.pbf scotland.osm.pbf wales.osm.pbf -o gb.osm.pbf
+```
+
+## OSRM
+
+OSRM is fast and lightweight but only supports route matrices — no isochrones.
+
+```bash
+# Download and prepare data
+wget https://download.geofabrik.de/europe/great-britain-latest.osm.pbf
+docker run -t -v $(pwd):/data osrm/osrm-backend osrm-extract -p /opt/car.lua /data/great-britain-latest.osm.pbf
+docker run -t -v $(pwd):/data osrm/osrm-backend osrm-partition /data/great-britain-latest.osrm
+docker run -t -v $(pwd):/data osrm/osrm-backend osrm-customize /data/great-britain-latest.osrm
+
+# Run the server
+docker run -d --name osrm \
+  -p 5000:5000 \
+  -v $(pwd):/data \
+  osrm/osrm-backend osrm-routed --algorithm mld /data/great-britain-latest.osrm
+```
+
+**Use in rendezvous-kit:**
+
+```typescript
+import { OsrmEngine } from 'rendezvous-kit/engines/osrm'
+
+const engine = new OsrmEngine({ baseUrl: 'http://localhost:5000' })
+// Note: OSRM cannot compute isochrones — findRendezvous will throw.
+// Use OSRM for computeRouteMatrix only.
+```
+
+## GraphHopper
+
+GraphHopper supports isochrones and route matrices. The open-source version is free to self-host.
+
+```bash
+docker run -d --name graphhopper \
+  -p 8989:8989 \
+  -e JAVA_OPTS="-Xmx4g" \
+  -v graphhopper_data:/data \
+  graphhopper/graphhopper:latest \
+  --url https://download.geofabrik.de/europe/great-britain-latest.osm.pbf \
+  --host 0.0.0.0
+```
+
+**Use in rendezvous-kit:**
+
+```typescript
+import { GraphHopperEngine } from 'rendezvous-kit/engines/graphhopper'
+
+const engine = new GraphHopperEngine({ baseUrl: 'http://localhost:8989' })
+```
+
+## Cloud-Hosted Alternatives
+
+If you prefer not to self-host:
+
+- **OpenRouteService** — free API key from [openrouteservice.org](https://openrouteservice.org/dev/), rate-limited (40 requests/min on free tier)
+- **Trotters Routing** — `https://routing.trotters.cc`, L402-gated (pay-per-request with Lightning)
+
+```typescript
+import { OpenRouteServiceEngine } from 'rendezvous-kit/engines/openrouteservice'
+
+const engine = new OpenRouteServiceEngine({ apiKey: 'your-api-key' })
+```
+
+## Tips
+
+- **Start with a small region** while developing — city or country level. You can always upgrade later.
+- **Pin the PBF date** in production so tile rebuilds are reproducible.
+- **Monitor memory** — routing engines are memory-hungry. Valhalla with GB data uses ~4 GB RAM.
+- **Health checks** — all engines respond to `GET /` or similar. Add a health check to your Docker Compose or Kubernetes config.

examples/basic-usage.ts

@@ -0,0 +1,38 @@
+/**
+ * Basic usage — find a fair meeting point for three people.
+ *
+ * Prerequisites:
+ *   npm install rendezvous-kit
+ *   A running Valhalla instance (or swap for OpenRouteServiceEngine with an API key)
+ *
+ * Run:
+ *   npx tsx examples/basic-usage.ts
+ */
+import { findRendezvous } from 'rendezvous-kit'
+import { ValhallaEngine } from 'rendezvous-kit/engines/valhalla'
+
+const engine = new ValhallaEngine({ baseUrl: 'http://localhost:8002' })
+
+const suggestions = await findRendezvous(engine, {
+  participants: [
+    { lat: 51.5074, lon: -0.1278, label: 'Alice' },   // London
+    { lat: 51.4545, lon: -2.5879, label: 'Bob' },      // Bristol
+    { lat: 52.4862, lon: -1.8904, label: 'Carol' },    // Birmingham
+  ],
+  mode: 'drive',
+  maxTimeMinutes: 90,
+  venueTypes: ['cafe', 'restaurant'],
+  fairness: 'min_max',   // minimise the worst-case travel time
+  limit: 5,
+})
+
+if (suggestions.length === 0) {
+  console.log('No overlap — participants are too far apart for the given time budget.')
+} else {
+  for (const s of suggestions) {
+    console.log(`${s.venue.name} (${s.venue.venueType})`)
+    console.log(`  Fairness score: ${s.fairnessScore.toFixed(1)} min`)
+    console.log('  Travel times:', s.travelTimes)
+    console.log()
+  }
+}

examples/comparing-fairness-strategies.ts

@@ -0,0 +1,49 @@
+/**
+ * Compare fairness strategies — see how min_max, min_total, and min_variance
+ * produce different rankings for the same participants and venues.
+ *
+ * Prerequisites:
+ *   npm install rendezvous-kit
+ *   A running Valhalla instance (or swap engine)
+ *
+ * Run:
+ *   npx tsx examples/comparing-fairness-strategies.ts
+ */
+import { findRendezvous } from 'rendezvous-kit'
+import { ValhallaEngine } from 'rendezvous-kit/engines/valhalla'
+import type { FairnessStrategy } from 'rendezvous-kit'
+
+const engine = new ValhallaEngine({ baseUrl: 'http://localhost:8002' })
+
+const participants = [
+  { lat: 51.5074, lon: -0.1278, label: 'Alice' },   // London
+  { lat: 51.4545, lon: -2.5879, label: 'Bob' },      // Bristol
+  { lat: 52.4862, lon: -1.8904, label: 'Carol' },    // Birmingham
+]
+
+const strategies: FairnessStrategy[] = ['min_max', 'min_total', 'min_variance']
+
+for (const fairness of strategies) {
+  console.log(`\n=== Strategy: ${fairness} ===\n`)
+
+  const suggestions = await findRendezvous(engine, {
+    participants,
+    mode: 'drive',
+    maxTimeMinutes: 90,
+    venueTypes: ['cafe', 'pub'],
+    fairness,
+    limit: 3,
+  })
+
+  if (suggestions.length === 0) {
+    console.log('No results — try increasing maxTimeMinutes.')
+    continue
+  }
+
+  for (const s of suggestions) {
+    const times = Object.entries(s.travelTimes)
+      .map(([who, mins]) => `${who}: ${mins} min`)
+      .join(', ')
+    console.log(`  ${s.venue.name} — score: ${s.fairnessScore.toFixed(1)}, ${times}`)
+  }
+}

examples/custom-engine.ts

@@ -0,0 +1,87 @@
+/**
+ * Implement a custom routing engine.
+ *
+ * This example shows how to implement the RoutingEngine interface with a mock
+ * engine, which is useful for testing or when wrapping a proprietary API.
+ *
+ * Run:
+ *   npx tsx examples/custom-engine.ts
+ */
+import { findRendezvous } from 'rendezvous-kit'
+import type { RoutingEngine, LatLon, TransportMode, Isochrone, RouteMatrix, RouteGeometry, MatrixEntry } from 'rendezvous-kit'
+import { circleToPolygon } from 'rendezvous-kit/geo'
+
+/**
+ * A mock engine that generates circular isochrones and straight-line travel times.
+ * Replace the method bodies with calls to your actual routing API.
+ */
+class MockEngine implements RoutingEngine {
+  readonly name = 'MockEngine'
+
+  async computeIsochrone(origin: LatLon, mode: TransportMode, timeMinutes: number): Promise<Isochrone> {
+    // Approximate reachable area as a circle. Real engines return road-network-shaped polygons.
+    const speedKmh = mode === 'drive' ? 80 : mode === 'cycle' ? 20 : 5
+    const radiusMetres = (speedKmh * timeMinutes / 60) * 1000
+
+    return {
+      origin,
+      mode,
+      timeMinutes,
+      polygon: circleToPolygon([origin.lon, origin.lat], radiusMetres),
+    }
+  }
+
+  async computeRouteMatrix(origins: LatLon[], destinations: LatLon[], mode: TransportMode): Promise<RouteMatrix> {
+    const speedKmh = mode === 'drive' ? 80 : mode === 'cycle' ? 20 : 5
+    const entries: MatrixEntry[] = []
+
+    for (let oi = 0; oi < origins.length; oi++) {
+      for (let di = 0; di < destinations.length; di++) {
+        const distKm = haversineKm(origins[oi], destinations[di])
+        entries.push({
+          originIndex: oi,
+          destinationIndex: di,
+          durationMinutes: (distKm / speedKmh) * 60,
+          distanceKm: distKm,
+        })
+      }
+    }
+
+    return { origins, destinations, entries }
+  }
+
+  async computeRoute(_origin: LatLon, _destination: LatLon, _mode: TransportMode): Promise<RouteGeometry> {
+    throw new Error('computeRoute not implemented in MockEngine')
+  }
+}
+
+function haversineKm(a: LatLon, b: LatLon): number {
+  const R = 6371
+  const dLat = (b.lat - a.lat) * Math.PI / 180
+  const dLon = (b.lon - a.lon) * Math.PI / 180
+  const sinLat = Math.sin(dLat / 2)
+  const sinLon = Math.sin(dLon / 2)
+  const h = sinLat * sinLat + Math.cos(a.lat * Math.PI / 180) * Math.cos(b.lat * Math.PI / 180) * sinLon * sinLon
+  return R * 2 * Math.atan2(Math.sqrt(h), Math.sqrt(1 - h))
+}
+
+// --- Run it ---
+
+const engine = new MockEngine()
+
+const suggestions = await findRendezvous(engine, {
+  participants: [
+    { lat: 51.5074, lon: -0.1278, label: 'Alice' },
+    { lat: 51.4545, lon: -2.5879, label: 'Bob' },
+  ],
+  mode: 'drive',
+  maxTimeMinutes: 60,
+  venueTypes: ['cafe'],
+  limit: 3,
+})
+
+console.log(`Found ${suggestions.length} suggestion(s) using ${engine.name}:`)
+for (const s of suggestions) {
+  console.log(`  ${s.venue.name} — score: ${s.fairnessScore.toFixed(1)} min`)
+  console.log('    Travel times:', s.travelTimes)
+}