refactor(intrinsics): remove deprecation shims; rewrite intrinsics_and_adapters.md; write 3 tutorials (Epic #929 Phase 4)

[planetf1]

Parent epic: #929
Design proposal: PR #1080 §16 Phase 4, Part I §5 Q4
Phase: 4 (file now as tracking issue; deferred until after 1.A ships in a minor release)
Depends on: 1.A (shims introduced) + Phase 2 complete + at least 1 minor release elapsed

⏳ DEFERRED — do not start until at least one minor release has elapsed after 1.A ships. The deprecation window is a minimum of one minor release (≈ 4–6 weeks), extendable if user impact warrants. Per PR #1080 Part I §5 Q4 (Resolved by Paul/Jake).

---

Problem

After Phase 1 ships, the old IntrinsicAdapter, EmbeddedIntrinsicAdapter, and CustomIntrinsicAdapter classes exist as deprecation shims with one minor release of warnings. The structural refactor is not complete until these are removed.

Additionally, docs/dev/intrinsics_and_adapters.md describes the old four-class hierarchy — it will be actively misleading once the shims are gone.

Agreed design

Delete the three shim classes. Rewrite (not edit) the dev doc. Write three tutorials.

If the IBM "Intrinsic" → post-"Intrinsic" rename has been confirmed by the time this lands, fold it in here. Otherwise keep separate.

Docs rewrite

docs/dev/intrinsics_and_adapters.md — rewrite (not edit) to document the final Adapter + WeightsBinding + IOContract model. The design proposal §15 explicitly says rewrite.

Three tutorials (§15)

1. "Adding a custom intrinsic in 20 lines" — replaces the CustomIntrinsicAdapter monkey-patch story
2. "Handling a breaking schema change without breaking users" — requirement-check v1→v2 worked example; HF revision pinning and AdapterSchemaMismatchError
3. "Reading intrinsic telemetry" — short dashboard-building guide referencing parse_failures, phase_duration_ms, and the span tree

Scope

• Delete IntrinsicAdapter, EmbeddedIntrinsicAdapter, CustomIntrinsicAdapter from mellea/backends/adapters/__init__.py and definitions
• Update changelog with removal + migration note
• Rewrite docs/dev/intrinsics_and_adapters.md
• Write at least two of the three tutorials; link from docs/docs/advanced/intrinsics.md

Out of scope

Any new functionality. IBM rename (separate issue if not yet confirmed).

Acceptance criteria

• Shim classes removed
• No internal references to old class names remain (grep gate)
• Changelog entry with migration note (import path change)
• docs/dev/intrinsics_and_adapters.md rewritten; describes Adapter + WeightsBinding + IOContract; no references to deleted class names
• At least two of three tutorials written and linked from docs/docs/advanced/intrinsics.md
• All tutorial code examples validated against current source
• markdownlint clean on all touched docs
• Existing tests pass (callers already on new types)

Test plan

• grep for old class names in mellea/ — no hits (gate this in CI)
• grep for old class names in docs/ — no hits in rewritten docs
• Existing test suite passes
• npx markdownlint-cli2 "docs/dev/intrinsics_and_adapters.md"
• Tutorial examples: uv run pytest (mark with # pytest: e2e, hf or appropriate markers)

Breaking changes

• Removal of IntrinsicAdapter, EmbeddedIntrinsicAdapter, CustomIntrinsicAdapter — by design, after the deprecation window. Anyone still importing these breaks. Document in changelog with migration path.

References

• PR docs: design proposal for adapter lifecycle (#929) — review channel, do not merge #1080 §16 Phase 4, §15 (tutorial list), Part I §5 Q4
• All Phase 1 issues — must be merged for callers to be off the old classes
• All Phase 2 issues — must be merged for backend surface on new types