Add package-level doc comments for go doc and gopls

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

middleware/doc.go

@@ -0,0 +1,28 @@
+// Package middleware provides client-side HTTP middleware for use with
+// httpx.Client or any http.RoundTripper-based transport chain.
+//
+// Each middleware is a function of type func(http.RoundTripper) http.RoundTripper.
+// Compose them with Chain:
+//
+//	chain := middleware.Chain(
+//	    middleware.Logging(logger),
+//	    middleware.Recovery(),
+//	    middleware.UserAgent("my-service/1.0"),
+//	)
+//	transport := chain(http.DefaultTransport)
+//
+// # Available middleware
+//
+//   - Logging — structured request/response logging via slog
+//   - Recovery — panic recovery, converts panics to errors
+//   - DefaultHeaders — adds default headers to outgoing requests
+//   - UserAgent — sets User-Agent header
+//   - BearerAuth — dynamic Bearer token authentication
+//   - BasicAuth — HTTP Basic authentication
+//   - RequestID — propagates request ID from context to X-Request-Id header
+//
+// # RoundTripperFunc
+//
+// RoundTripperFunc adapts plain functions to http.RoundTripper, similar to
+// http.HandlerFunc. Useful for testing and inline middleware.
+package middleware