docs: improve README clarity

[rlippmann]

Summary

Improve README clarity, navigation, and package-facing documentation across the example integrations repo.

This PR keeps the examples behaviorally unchanged while making the docs easier to use from GitHub, PyPI, and npm package pages.

Why

The README set had accumulated stale links, duplicate navigation, internal terminology, and architecture-first wording. This made the examples harder to scan and increased drift risk around shared provider/runtime documentation.

The cleanup makes the docs more behavior-first: readers should be able to see what changes at runtime, where authoritative state is enforced, and which example to open next.

Example metadata

• Enforcement point: multiple / repository documentation
• Domain: repository maintenance
• Technology/runtime: Python, TypeScript, package READMEs, example READMEs
• Example type: repository maintenance
• Does this use directive drafter? should normally be no: no
• Does this derive state from model output? must be no for primary examples: no

Checklist

• Repository scaffolding / governance change
• One primary enforcement point
• Explicit authoritative state
• No model-derived state mutation
• Adversarial stub or equivalent test
• Observable runtime behavior change
• Domain vocabulary is natural
• Framework is secondary to the enforcement point
• Docs updated
• Tests/smoke checks added where practical

Notes

Docs-only cleanup.

Notable changes:

• fixed stale and machine-local README links
• clarified package README introductions for PyPI/npm readers
• removed duplicate navigation and empty/dangling sections
• consolidated the shared provider/model environment contract in PROVIDER_CONTRACT.md
• removed cross-language navigation from language-specific docs
• removed internal Tier 1 / Tier 2 / Tier 3 terminology from user-facing docs
• made example introductions more behavior-first
• documented the cross-language navigation policy in AGENTS.md

Markdownlint was run on changed Markdown files during the cleanup commits.