Create an indexed examples gallery with per-example learning goals

[dgenio]

Summary

Turn the nine CI-tested example scripts into a discoverable gallery: an
examples/README.md index table (what each demonstrates, concepts covered,
expected output, suggested order) plus a top-level README pointer — making the
existing investment visible to evaluators.

Why this matters

The repo already has what most projects lack — nine runnable, CI-verified examples
covering the full surface (basic CLI, billing, HTTP driver, tutorial, quickstart,
contextweaver/ChainWeaver flows, repository safety check, evaluation artifacts) —
but they are an unindexed directory listing. Evaluators decide in minutes; an
index that says "you want X? run this file" converts existing assets into adoption
without writing new code. It also gives the sample-app (#136) and notebook (#137)
issues a place to slot into when they land.

Current evidence

• examples/ contains 9 scripts + policies/default.toml; all 9 run in make example (Makefile lines 18–27) — verified, CI-tested assets.
• No examples/README.md; the top-level README does not enumerate the examples or their purposes.
• Docs reference individual examples ad hoc (docs/integrations/*.md) but nothing indexes them.

External context

Examples-gallery indexes with difficulty/coverage tables are a documented onboarding
pattern across developer tools.

Proposed implementation

1. Write examples/README.md: table (file, demonstrates, key concepts, run
   command, ~runtime), a suggested learning path (quickstart → tutorial → drivers →
   policies → integrations), and prerequisites per example (extras needed).
2. Add a one-line docstring header to any example lacking a clear statement of
   purpose (verify each against its actual behavior).
3. Link from the top-level README ("Learn by example") and from docs/tutorial.md.
4. Keep the table honest with a tiny test asserting every examples/*.py appears
   in the index (drift guard).

AI-agent execution notes

• Inspect first: every file in examples/, Makefile example target, README structure.
• Run each example locally to write accurate "demonstrates/output" lines — no guessing.
• Edge cases: examples requiring extras (document which); future examples (the drift test catches omissions).
• Do not modify example logic in this issue.

Acceptance criteria

• examples/README.md indexes all current examples with accurate descriptions and prerequisites.
• A drift test fails when a new example is added without indexing.
• Top-level README links the gallery.

Test plan

The drift test; make example unchanged; manual accuracy review. Run make ci.

Documentation plan

The deliverable is documentation; CHANGELOG Added (docs).

Migration and compatibility notes

Not expected to require migration.

Risks and tradeoffs

Negligible; small ongoing duty to keep descriptions accurate (drift test covers
existence, review covers accuracy).

Suggested labels

adoption, documentation, good-first-ai-issue