The curated catalog stays the source of truth for model identity (ids,
aliases, match patterns, deprecations, escalation targets), but its
volatile facts went stale between releases. A cached snapshot of
https://models.dev/api.json now overlays context window, max output
tokens, and base per-million pricing onto known entries at registry
construction. The overlay never adds models, never touches curated
tiered pricing (models.dev has no tier data), and never does network on
the registry hot path: fetching happens only in an explicit background
refresh (exec/TUI startup), TTL 24h, atomic write, validated before it
can clobber a good cache, capped at 32MiB.
Opt-in by design: only the CLI entrypoint enables the overlay
(EnableModelsDevOverlay), so library consumers and hermetic tests are
never perturbed by a cache file on the machine. ZERO_MODELS_URL
overrides the source, ZERO_DISABLE_MODELS_FETCH disables fetch+overlay,
ZERO_MODELS_CACHE_PATH relocates the cache. Snapshots older than 7 days
are ignored (the shipped catalog is likely fresher). Parser validated
against the live api.json shape (150 providers).
Co-Authored-By: Claude Fable 5 <[email protected]>
