API caching

The toolkit caches aggressively. Here's what's cached, for how long, and why.

Why cache

The Bethesda Creations API is undocumented and rate-limited. Round-trip times vary from fast to abysmal. The toolkit caches locally so that:

• Tab switches are instant — no re-fetching on every view.
• A cold start is pleasant — what you saw last session is still there.
• The API doesn't get hammered for data that doesn't change.

Immutable vs volatile fields

The toolkit splits every creation's metadata into two buckets:

Immutable fields, once cached, are never refetched unless you hit Clear Cache. Volatile fields are considered fresh for 30 minutes per process lifetime — the second time you open the same creation in a session, it's read straight from disk.

Explicit refreshes

The Check for Updates and Check Achievements buttons bypass the staleness window and always hit the API. This is how you guarantee a fresh read when you want one.

Disk layout

Cached files live under a per-user data directory:

• creations/<id>.json — one file per creation, merging immutable + volatile fields.
• thumbnails/<id>.jpg — downloaded creation thumbnail.
• loot/ — fetched LOOT masterlist with a timestamp.
• catalogue/ — the offline text catalogue (see below).

Exact paths in File locations.

The offline text catalogue

A separate scraper (Feature 005) maintains a catalogue of all ~5K Starfield creations — not just the ones you have installed. It stores description and release-notes text plus metadata and SHA-256 content hashes. This catalogue feeds the Description parser and the Fast Lane baseline.

Rate limiting

The API client uses exponential backoff with jitter on 429/503 responses and a single-flight guard so two tabs can't redundantly request the same creation at the same time. The status bar shows when a rate-limit wait is in progress.