docs(server): brighter webhook wiring guidance + hello_seller_with_webhooks example

[bokelley]

Closes #546

Summary

The auto_emit_completion_webhooks silent-no-op scenario (no sender wired, no error until a buyer actually sends a request with push_notification_config.url) was already caught at boot by validate_webhook_sender_for_platform(). This PR makes the path from error to fix obvious, and gives adopters a runnable reference before they need to read the error at all.

Five changes, all non-breaking:

1. Error message improvement (src/adcp/decisioning/webhook_emit.py): The existing AdcpError raised at boot now includes copy-paste import + constructor snippets for all three primary WebhookSender factory methods plus InMemoryWebhookDeliverySupervisor wiring. Previous message named the classes but not the import paths — copy-pasting it produced NameError. Also fixed a missing key_id= in the from_standard_webhooks_secret snippet (that kwarg has no default; the omission would have raised TypeError on copy-paste).

2. hello_seller.py comment expansion: Four-line comment expanded to list the three sender constructors with one-line use-case summaries and a link to the new docs section.

3. docs/handler-authoring.md — new ## Completion webhooks section: Covers the exact boot-time check conditions (only fires when advertised tools overlap SPEC_WEBHOOK_TASK_TYPES), all three primary constructors with code snippets, InMemoryWebhookDeliverySupervisor wiring, and the explicit opt-out pattern. Decision tree and "Where to look next" updated.

4. New examples/hello_seller_with_webhooks.py: Self-contained ~65 LOC — inlines a minimal _WebhookSeller (5 hard-required methods), wires WebhookSender.from_bearer_token + InMemoryWebhookDeliverySupervisor with a fixture token configurable via WEBHOOK_BEARER_TOKEN env var. Runnable from repo root with uv run python examples/hello_seller_with_webhooks.py.

5. hello_seller_creative.py comment: Updated to match the new three-constructor framing.

What was tested

• pytest tests/ -k "webhook" — 309 passed, 27 skipped (3 pre-existing collection errors unrelated to this change)
• ruff check — clean
• mypy src/adcp/decisioning/webhook_emit.py — clean
• python -m py_compile on all changed files — clean
• Pre-existing failures on test_oauth_passthrough.py, test_proposal_manager.py, test_upstream_helpers.py confirmed present on main before this branch

Pre-PR review:

• code-reviewer: approved — fixed from_standard_webhooks_secret missing key_id blocker; fixed cwd-fragile cross-example import blocker by inlining minimal seller
• dx-expert: approved — error message is textbook DX; decision tree + section + "Where to look next" all link correctly; self-contained example resolves first-run failure risk

Nits noted (not fixed, not regressions):

• auto_emit_completion_webhooks=True removed from the serve() call in the example (it's the default; stating it added noise)
• docs section header spacing confirmed correct in on-disk file

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

• Push fixup commits directly: gh pr checkout <num> →
  fix → push.
• Or re-trigger: comment /triage execute on the source
  issue.

See adcp#3121
for context.

Session: https://claude.ai/code/session_01VaoqDC8iDD2tfzRFExrkK3

---

Generated by Claude Code

[bokelley]

Superseded by #551 (already merged). #551 covers the same docs/handler-authoring section, expanded hello_seller, and the with_webhooks example for issue #546. Closing in favor of the merged work; if the additional changes here (hello_seller_creative.py touch-up, webhook_emit.py error message tweak) are still wanted, they can land in a separate focused PR.

[bokelley]

Acknowledged — #551 covers the core scope. If the hello_seller_creative.py comment touch-up and webhook_emit.py error message tweak are still wanted, a focused follow-up PR makes sense when convenient.

---

Generated by Claude Code