Add demo safety net: pinned deployment + cached API fixtures

Problem

Live demos break due to failures in any layer: frontend code regressions, API server outages, policyengine-us/uk model updates, or us/uk-data recalibrations. We need a fully isolated demo environment that decouples from all upstream changes.

Solution

Two layers of protection:

1. Pinned Vercel deployment (demo.policyengine.org) — freezes the frontend code at a known-good commit
2. Demo mode (?demo=true) — serves pre-captured API responses from static JSON files, bypassing the live API entirely

When demo mode is active, no network calls are made to api.policyengine.org. The app runs entirely on frozen fixtures, so changes to the API, policyengine-us/uk, or us/uk-data have zero impact.

Isolation coverage

Failure	Protected by
Frontend bug merged to main	Pinned Vercel deployment
API server down or erroring	Fixtures bypass API entirely
API response format change	Fixtures bypass API entirely
policyengine-us/uk model update	Fixtures are frozen snapshots
policyengine-us/uk-data recalibration	Fixtures are frozen snapshots
Embedded sites (slides, tracker)	Not covered — avoid in demo or pin separately

Implementation plan

1. DNS + Vercel setup

• Add CNAME: demo.policyengine.org → cname.vercel-dns.com
• Add demo.policyengine.org as a domain in Vercel project settings
• Assign it to a specific deployment (not auto-tracking production)

2. File structure

app/
├── public/
│   └── demo-fixtures/
│       ├── manifest.json              # Capture metadata (timestamp, model versions)
│       ├── us/
│       │   ├── metadata.json
│       │   ├── household--{id}.json
│       │   ├── household--{id}--policy--{id}.json
│       │   ├── policy--{id}.json
│       │   └── economy--{id}--over--{id}.json
│       └── uk/
│           └── ...
└── src/
    └── api/
        ├── demoFetch.ts               # Fetch wrapper (~30 lines)
        └── fixtureMap.ts              # Explicit URL → fixture path map
scripts/
    └── capture-demo-fixtures.ts       # Automated fixture capture

3. demoFetch.ts wrapper

• Checks for ?demo=true query param
• In demo mode: looks up fixture from explicit fixtureMap.ts mapping, returns static JSON
• No fixture found: falls back to live API with console warning
• Outside demo mode: passes through to native fetch with zero overhead

4. Wire into existing API modules

Replace fetch() with demoFetch() in ~9 files under app/src/api/:

• household.ts, policy.ts, metadata.ts, simulation.ts, report.ts
• householdCalculation.ts, societyWideCalculation.ts, householdVariation.ts, reportCalculations.ts

5. Capture script

scripts/capture-demo-fixtures.ts — replays the demo flow against the live API and saves responses + a manifest.json with capture timestamp and model versions.

6. Demo workflow

Before a demo:

1. Run capture script to refresh fixtures
2. Commit + push, wait for Vercel deploy
3. Test with ?demo=true
4. Pin deployment: vercel alias <deployment-url> demo.policyengine.org

During a demo:

• Start with production if confident
• Switch to demo.policyengine.org?demo=true if anything breaks

Estimated effort

~4 hours total implementation

Future enhancements (only if needed)

• CI freshness check — weekly workflow that re-captures and opens a PR if responses changed
• Multiple demo scenarios — ?demo=scenario-a for different audiences
• Embedded site pinning for slides/tracker

Start by reading the existing API modules under app/src/api/ and the proposed entry points app/src/api/demoFetch.ts and fixtureMap.ts. Run scripts/capture-demo-fixtures.ts to understand fixture generation, then verify ?demo=true uses the captured files across the listed API modules without live API calls and that the pinned demo deployment is reachable at demo.policyengine.org.