Add a recorded demo, and the script that produces it

scripts/demo.sh is a real walkthrough: it starts the gateway, routes model:auto,
resolves four aliases to four different models, shows a cache hit costing zero
quota, recalls a name across a server-side session, 404s an unknown model with
suggestions, and prints where the tokens went. Nothing is staged — every line is
output the gateway actually produced against a live provider.

scripts/record-demo.html turns a captured transcript into video frames. ffmpeg
on macOS ships without freetype, so it can encode frames but cannot draw text;
the browser can do both, so frames are rasterised on a canvas and posted to a
local server for ffmpeg to assemble.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

README.md

@@ -8,6 +8,11 @@ Your apps point at `http://localhost:8787/v1` and never see a provider key. When
 one free tier runs out, the next one takes over — mid-conversation, even if it
 has a sixteenth of the context window.
 
+![Freeway demo](demo/freeway-demo.gif)
+
+*Every frame above is a real request against a live provider — recorded by
+`./scripts/demo.sh`, which you can run yourself.*
+
 ```
 your app ──▶ Freeway ──┬──▶ Mistral        1B tokens/month
                        ├──▶ Cloudflare     10k neurons/day
@@ -399,6 +404,7 @@ gateway flatly refuses to bind one with no keys at all.
 ## Development
 
 ```bash
+./scripts/demo.sh       # scripted walkthrough against your real providers
 npm run build           # tsc --build, must be clean
 npm test                # node:test across all workspaces
 npm run smoke           # every route against mock upstreams — run this after adding a provider