Add detailed godoc documentation to CLIEntry function

Expand the documentation comment for CLIEntry to provide more context
about what the function does, including its use of the fx dependency
injection framework, signal handling, and blocking behavior.

internal/server/handlers.go

@@ -21,18 +21,19 @@ import (
 )
 
 const (
-	// statsContextTimeout is the timeout for stats API operations
+	// statsContextTimeout is the timeout for stats API operations.
 	statsContextTimeout = 4 * time.Second
 )
 
-// handleRoot returns a handler that redirects to /status
+// handleRoot returns a handler that redirects to /status.
 func (s *Server) handleRoot() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		http.Redirect(w, r, "/status", http.StatusSeeOther)
 	}
 }
 
-// writeJSONError writes a standardized JSON error response
+// writeJSONError writes a standardized JSON error response with the given
+// status code and error message.
 func writeJSONError(w http.ResponseWriter, statusCode int, message string) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(statusCode)
@@ -45,7 +46,8 @@ func writeJSONError(w http.ResponseWriter, statusCode int, message string) {
 	})
 }
 
-// writeJSONSuccess writes a standardized JSON success response
+// writeJSONSuccess writes a standardized JSON success response containing
+// the provided data wrapped in a status envelope.
 func writeJSONSuccess(w http.ResponseWriter, data interface{}) error {
 	w.Header().Set("Content-Type", "application/json")
 

internal/server/middleware.go

@@ -44,7 +44,12 @@ func (rw *responseWriter) Header() http.Header {
 	return rw.ResponseWriter.Header()
 }
 
-// JSONResponseMiddleware wraps all JSON responses with metadata
+// JSONResponseMiddleware is an HTTP middleware that wraps all JSON responses
+// with a @meta field containing execution metadata. The metadata includes the
+// time zone (always UTC), API version, and request execution time in milliseconds.
+//
+// Endpoints "/" and "/status" are excluded from this processing and passed through
+// unchanged. Non-JSON responses and empty responses are also passed through unchanged.
 func JSONResponseMiddleware(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		// Skip non-JSON endpoints
@@ -155,7 +160,13 @@ func (tw *timeoutWriter) markWritten() {
 	tw.written = true
 }
 
-// TimeoutMiddleware creates a timeout middleware that returns JSON errors
+// TimeoutMiddleware creates an HTTP middleware that enforces a request timeout.
+// If the handler does not complete within the specified duration, the middleware
+// returns a JSON error response with HTTP status 408 (Request Timeout).
+//
+// The timeout parameter specifies the maximum duration allowed for request processing.
+// The returned middleware handles panics from the wrapped handler by re-panicking
+// after cleanup, and prevents concurrent writes to the response after timeout occurs.
 func TimeoutMiddleware(timeout time.Duration) func(http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -218,7 +229,15 @@ func TimeoutMiddleware(timeout time.Duration) func(http.Handler) http.Handler {
 	}
 }
 
-// JSONValidationMiddleware ensures all JSON API responses are valid JSON
+// JSONValidationMiddleware is an HTTP middleware that validates JSON API responses.
+// It ensures that responses with Content-Type "application/json" contain valid JSON.
+//
+// If a response is not valid JSON or is empty when JSON is expected, the middleware
+// returns a properly formatted JSON error response. For timeout errors (status 408),
+// the error message will be "Request timeout". For other errors, it returns
+// "Internal server error" with status 500 if the original status was 200.
+//
+// Non-JSON responses are passed through unchanged.
 func JSONValidationMiddleware(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		// Create a custom response writer to capture the response