docs: speed up publishing with a Fern example cache

[dev-seth-vapi]

Description

Fern spent about 24 minutes preparing validation and another 25 minutes rebuilding API examples on the previous production publish. Cache the exact property and request/response examples so content-only changes reuse this work.

• Keep API parsing, schema and page validation, examples, SDK snippets, and the playground enabled.
• Restrict changes to this docs repository. No monorepo or API schema changes.
• Pin the official Fern 5.112.0 bundle and verify its checksum before wrapping two example-generation functions. Unexpected bundles fail before publishing.
• Invalidate for API sources, resolved specs, parser settings, reference directories, and tooling changes. Preserve value types, diagnostics, and independent returned objects. Corrupt cache entries regenerate normally.
• Save fresh CI cache snapshots so publication can extend the cache created earlier in a build. Preview failures now fail CI instead of being swallowed.

Testing Steps

• Eight tests cover exact values, stable typed keys, mutation isolation, invalidation, diagnostics, exceptions, corrupted entries, and generated-file exclusions.
• Full local check: validation setup fell from 697 seconds to 6.9 seconds (101x), with 2,266 hits and zero misses. The full cached check took about 15 seconds.
• Cold and cached checks produce identical warning text: zero errors and 11 warnings.
• Two full-site preview publishes completed in approximately 47 and 49 seconds, each with 4,532 cache hits and zero misses. No snippet-disabling or validation-skipping flags were used.
• Browser verification: GPT-Live navigation and waitlist, API reference, request examples, and interactive API Explorer with authentication and body fields. No API requests were submitted.
• A missing documentation page still fails validation with the cache present. Temporary test changes were restored.
• Final CI passes. A fresh GitHub Actions rerun restored the cache and published the full preview in 75 seconds, with 4,532 hits and zero misses. The complete job took 1 minute 39 seconds, compared with 26 minutes 19 seconds for the cold run.

Full-site preview

The 101x figure applies to validation setup on the same machine, not end-to-end publication. The 47–49 second timings are local full-site publishes. The first build after API or Fern changes still generates examples normally, then populates the cache.

The existing TypeScript snippet warning about the unknown @vapi/server-sdk package also appears in the baseline production log. This change neither introduces nor suppresses it.

[lightsage-app]

Lightsage docs evals

Result: passed
Staging docs: https://vapi-preview-01a0a8c3-3364-77d5-b2fd-3fcb1cc71310.docs.buildwithfern.com
Commit: f918bd9

Average score: 100/100
Passed: 3/3

Eval ID	Status	Score	Model	Tools	Docs 404
08e24c18-82a0-45de-abdc-d237bd12bc0f	Pass	100	claude-code/global.anthropic.claude...	11	0
08e24c18-82a0-45de-abdc-d237bd12bc0f	Pass	100	codex/gpt-5.4	28	0
08e24c18-82a0-45de-abdc-d237bd12bc0f	Pass	100	cursor/auto	14	0

[github-actions]

🌿 Preview your docs: https://vapi-preview-01a0a7fe-ee63-71cb-a62f-120fc5039814.docs.buildwithfern.com

[github-actions]

🌿 Preview your docs: https://vapi-preview-01a0a804-efdd-719c-8e00-02402593cf21.docs.buildwithfern.com

[github-actions]

🌿 Preview your docs: https://vapi-preview-01a0a8c3-3364-77d5-b2fd-3fcb1cc71310.docs.buildwithfern.com