docs(decoders): add a "write your own ResponseDecoder" guide

[lesnik512]

What

Adds docs/decoders.md, the Seam B extension-point guide — the decoder counterpart to docs/middleware.md. Closes deferred item G6 (custom-ResponseDecoder guide).

Contents

The page mirrors the structure of the middleware guide:

• The protocol — can_decode / decode, the can_decode no-raise obligation (it runs outside the DecodeError wrap), and auto-DecodeError wrapping of decode failures.
• How the client resolves a model — decoders=[...] order as preference, the pydantic-first None default, and the MissingDecoderError pre-flight vs DecodeError distinction.
• Decoders are sync — for both clients — one protocol shared by Client and AsyncClient, unlike middleware's two flavors.
• Worked example: a CSV decoder — text/csv → list[<dataclass>], stdlib-only and single-pass, chosen because both built-ins are JSON so it best teaches that the seam is raw-bytes-in / typed-object-out.
• Claiming the right models — the discrimination obligation, a cattrs/attrs adapter sketch, and that the single-pass rule is a built-in perf choice, not a hard obligation.
• When NOT to write a decoder.

Also

• mkdocs.yml — Decoders nav entry after Middleware.
• planning/deferred.md — G6 removed (closed).
• Planning bundle 2026-06-15.01-custom-decoder-guide.

No source or public-API change.

Verification

• CSV example exercised against the real ResponseDecoder protocol — can_decode accepts list[Sale] and rejects list / list[int] / Sale / dict; decode round-trips a CSV body.
• mkdocs build --strict — clean (links resolve, nav builds).
• just lint — clean.

🤖 Generated with Claude Code