Turn examples and documentation snippets into executable smoke tests

[parthdongre]

Summary

Make the most important README/docs examples executable in CI so user-facing examples cannot silently drift away from the real API.

Why

FrameVitals exposes many workflows—analysis, drift, contracts, gates, snapshots, source inspection, CLI, and optional backends. Keeping examples runnable is one of the cheapest ways to protect the user experience as APIs evolve.

Scope

• Select a small canonical set of examples from README/docs.
• Convert them into executable scripts or doctest-style snippets.
• Use deterministic small fixtures so CI stays fast.
• Cover at least one optional-source path when dependencies are installed.
• Keep example outputs concise and stable.

Acceptance criteria

• Core quick-start examples run in CI.
• At least one drift workflow and one contract/gate workflow are executed.
• Example failures clearly identify the broken user-facing workflow.
• Optional-dependency examples are isolated from the minimum core environment.
• Documentation explains how contributors can run the example smoke suite locally.

Priority: P2 — documentation / contributor-friendly
Suggested labels: documentation, testing, good-first-issue