Phase 2: Expand docs/handler-authoring.md with salesagent-migration lessons (PR-T)

[bokelley]

Summary

docs/handler-authoring.md covers the first 80% of the authoring journey. Once salesagent completes their MCP migration using the SDK's new hooks, a bunch of concrete patterns surface that this guide should document for the next adopter.

Intended additions

Post-migration feedback should drive the specifics, but a rough list:

• ResolvedIdentity pattern, end-to-end. The guide mentions it; expand into a real example showing the _impl layer taking a typed identity, the ADCPHandler delegating, and the context_factory populating from token → DB lookup.
• Tenant routing from token. Nginx-only subdomain → tenant + bearer-token → principal, both resolved inside BearerAuthMiddleware. salesagent's actual prod pattern. Include the Postgres lookup sketch.
• Discovery-skill exemption in practice. DISCOVERY_TOOLS | {"list_public_formats", ...} + validate_discovery_set() + the composed method in DISCOVERY_METHODS or (method == "tools/call" and name in DISCOVERY_TOOLS) gate from Document and lock the tools/list pre-auth posture; consider DISCOVERY_METHODS for JSON-RPC method gating #222.
• Keeping SalesAgentHandler(ADCPHandler) class thin. Every method is a one-line delegation to _impl.*; the class exists to translate between SDK ToolContext and internal ResolvedIdentity. Structural test that enforces this (a grep-based check that handler methods don't do business logic).
• Idempotency wiring. @store.wrap on create/update methods; ToolContext.caller_identity + tenant_id populated by the factory; the warning on missing-principal calls.
• Error classification in practice. When to raise adcp_error("BUDGET_TOO_LOW") vs a plain ADCPTaskError; the AdCP error-code taxonomy.
• Troubleshooting section. "My handler runs but idempotency dedup isn't firing" → check caller_identity. "My context_factory returned a dict and now the handler explodes" → the isinstance guard error message.

Acceptance

• Appended to docs/handler-authoring.md (or split into docs/handler-authoring-advanced.md if it gets big).
• Cross-links from examples/mcp_with_auth_middleware.py and MIGRATION_v3_to_v4.md.
• Skim-pass from salesagent (or another adopter) confirming the recipes reflect actual production setups, not just theory.

Context

Roadmap item PR-T (Phase 2). Explicitly scheduled for after at least one downstream has completed MCP adoption — don't guess at the lessons; ship what the migration actually surfaced.