docs: add FAQ from resolved GitHub issues

[fredbi]

Summary

• Add docs/FAQ.md with answers extracted from 13 open issues tagged question
• Covers client usage (TLS config, custom MIME types, error body access), middleware (auth principal access, context propagation, request validation), and Swagger UI configuration
• Link FAQ from README.md

Issues closed

Closes #31, #44, #82, #89, #121, #196, #201, #203, #252, #253, #316, #329, #375

Issues not closed (no maintainer resolution):

• Extract middleware with UI to separate repository #257 — feature request to extract UI middleware (no response)
• [issue] it's better determine client is nil or not before assign it #125 — client overwrite bug (acknowledged but unresolved)

Test plan

• Verify FAQ renders correctly on GitHub
• Verify issue cross-references link properly
• Verify README link to FAQ works

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.68%. Comparing base (3b063c0) to head (b5b87f1).
⚠️ Report is 2 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #403   +/-   ##
=======================================
  Coverage   81.68%   81.68%           
=======================================
  Files          50       50           
  Lines        3379     3379           
=======================================
  Hits         2760     2760           
  Misses        507      507           
  Partials      112      112           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.