I was about to take a pass at #1205 and checked this PR first. This looks like it covers the missing client-side half of sampling clearly: it answers that the SDK does not call a provider directly, shows where sampling_callback plugs in, and explains that model_preferences / include_context are advisory inputs for the client rather than automatic behavior.

Local validation on current PR head:

uv run --frozen mkdocs build --strict

Result: docs build completed successfully. Only output was the existing MkDocs/Material compatibility warning, not specific to this change.

One small thing I specifically checked: adding sampling.md to mkdocs.yml makes the new page reachable from the docs nav, so this should directly address the discoverability gap from #1205.

Thanks for the PR. This has since landed via #2978. Closing as part of a general backlog cleanup following the v2 release. If this is still relevant against v2, feel free to reopen.

_{AI Disclaimer}