Add package-level doc comments for go doc and gopls

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

balancer/doc.go

@@ -0,0 +1,34 @@
+// Package balancer provides client-side load balancing as HTTP middleware.
+//
+// It distributes requests across multiple backend endpoints using pluggable
+// strategies (round-robin, weighted, failover) with optional health checking.
+//
+// # Usage
+//
+//	mw, closer := balancer.Transport(
+//	    []balancer.Endpoint{
+//	        {URL: "http://backend1:8080"},
+//	        {URL: "http://backend2:8080"},
+//	    },
+//	    balancer.WithStrategy(balancer.RoundRobin()),
+//	    balancer.WithHealthCheck(5 * time.Second),
+//	)
+//	defer closer.Close()
+//	transport := mw(http.DefaultTransport)
+//
+// # Strategies
+//
+//   - RoundRobin — cycles through healthy endpoints
+//   - Weighted — distributes based on endpoint Weight field
+//   - Failover — prefers primary, falls back to secondaries
+//
+// # Health checking
+//
+// When enabled, a background goroutine periodically probes each endpoint.
+// The returned Closer must be closed to stop the health checker goroutine.
+// In httpx.Client, this is handled by Client.Close().
+//
+// # Sentinel errors
+//
+// ErrNoHealthy is returned when no healthy endpoints are available.
+package balancer