fix: address coderabbitai review feedback on PR #127

- Add UTC indicator to env list timestamp output
- Add missing godoc comments to credentials, health, db, and metrics packages

https://claude.ai/code/session_01KiE3FJpfF6XE2y3Tyth2r3

Author: claude

packages/engine/internal/api/health/health.go

@@ -17,6 +17,8 @@ type LivenessChecker interface {
 	Name() string
 }
 
+// HealthzHandler returns an HTTP handler that always responds 200 OK, used as
+// a liveness probe.
 func HealthzHandler() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
@@ -25,6 +27,9 @@ func HealthzHandler() http.HandlerFunc {
 	}
 }
 
+// ReadyzHandler returns an HTTP handler used as a readiness probe. It pings
+// the database and checks each LivenessChecker; it responds 503 if any check
+// fails.
 func ReadyzHandler(database *sql.DB, checkers ...LivenessChecker) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")

packages/engine/internal/cli/credentials.go

@@ -15,6 +15,7 @@ const (
 	CredTypeOIDC   = "oidc"
 )
 
+// Credentials holds the authentication material persisted to disk.
 type Credentials struct {
 	Type         string    `json:"type"`
 	APIKey       string    `json:"api_key,omitempty"`
@@ -23,11 +24,15 @@ type Credentials struct {
 	ExpiresAt    time.Time `json:"expires_at,omitempty"`
 }
 
+// DefaultCredentialsPath returns ~/.mantle/credentials, the default location
+// where authentication material is stored.
 func DefaultCredentialsPath() string {
 	home, _ := os.UserHomeDir()
 	return filepath.Join(home, ".mantle", "credentials")
 }
 
+// SaveCredentials marshals cred to JSON and writes it to path with
+// 0600 permissions, creating parent directories as needed.
 func SaveCredentials(path string, cred *Credentials) error {
 	if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {
 		return fmt.Errorf("creating credentials directory: %w", err)
@@ -42,6 +47,7 @@ func SaveCredentials(path string, cred *Credentials) error {
 	return nil
 }
 
+// LoadCredentials reads and parses the JSON credentials file at path.
 func LoadCredentials(path string) (*Credentials, error) {
 	data, err := os.ReadFile(path)
 	if err != nil {
@@ -54,6 +60,8 @@ func LoadCredentials(path string) (*Credentials, error) {
 	return &cred, nil
 }
 
+// DeleteCredentials removes the credentials file at path. It is not an error
+// if the file does not exist.
 func DeleteCredentials(path string) error {
 	if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
 		return fmt.Errorf("removing credentials: %w", err)

packages/engine/internal/cli/env.go

@@ -96,7 +96,7 @@ func newEnvListCommand() *cobra.Command {
 			w := tabwriter.NewWriter(cmd.OutOrStdout(), 0, 0, 2, ' ', 0)
 			fmt.Fprintln(w, "NAME\tCREATED")
 			for _, e := range envs {
-				fmt.Fprintf(w, "%s\t%s\n", e.Name, e.CreatedAt.Format("2006-01-02 15:04:05"))
+				fmt.Fprintf(w, "%s\t%s\n", e.Name, e.CreatedAt.UTC().Format("2006-01-02 15:04:05 UTC"))
 			}
 			return w.Flush()
 		},

packages/engine/internal/db/db.go

@@ -43,10 +43,13 @@ func Open(cfg config.DatabaseConfig) (*sql.DB, error) {
 	return database, nil
 }
 
+// WithContext stores database in ctx so it can be retrieved by FromContext.
 func WithContext(ctx context.Context, database *sql.DB) context.Context {
 	return context.WithValue(ctx, contextKey{}, database)
 }
 
+// FromContext retrieves the *sql.DB previously stored by WithContext. It
+// returns nil if no database is present in ctx.
 func FromContext(ctx context.Context) *sql.DB {
 	database, _ := ctx.Value(contextKey{}).(*sql.DB)
 	return database

packages/engine/internal/metrics/metrics.go

@@ -131,10 +131,17 @@ var (
 // Queue helper functions.
 
 func SetQueueDepth(n int)                { QueueDepth.Set(float64(n)) }
+// RecordClaimDuration records the duration of a queue claim attempt.
 func RecordClaimDuration(d time.Duration) { ClaimDurationSeconds.Observe(d.Seconds()) }
-func RecordLeaseRenewal()                { LeaseRenewalsTotal.Inc() }
-func RecordLeaseExpiration()             { LeaseExpirationsTotal.Inc() }
-func RecordReaperReclaimed(n int)        { ReaperReclaimedTotal.Add(float64(n)) }
+
+// RecordLeaseRenewal increments the lease renewal counter.
+func RecordLeaseRenewal() { LeaseRenewalsTotal.Inc() }
+
+// RecordLeaseExpiration increments the lease expiration counter.
+func RecordLeaseExpiration() { LeaseExpirationsTotal.Inc() }
+
+// RecordReaperReclaimed increments the reaper reclaimed counter by n.
+func RecordReaperReclaimed(n int) { ReaperReclaimedTotal.Add(float64(n)) }
 
 // Email trigger metrics.
 var (
@@ -202,9 +209,16 @@ var (
 func RecordToolCall(step, tool, status string) {
 	ToolCallsTotal.WithLabelValues(step, tool, status).Inc()
 }
+// RecordToolRound increments the tool-round counter for the given step.
 func RecordToolRound(step string) { ToolRoundsTotal.WithLabelValues(step).Inc() }
+
+// RecordToolRoundDuration records the duration of a tool-use round for the given step.
 func RecordToolRoundDuration(step string, d time.Duration) {
 	ToolRoundDurationSeconds.WithLabelValues(step).Observe(d.Seconds())
 }
-func RecordLLMCacheHit()          { LLMCacheHitsTotal.Inc() }
+
+// RecordLLMCacheHit increments the LLM cache hit counter.
+func RecordLLMCacheHit() { LLMCacheHitsTotal.Inc() }
+
+// SetParallelStepsInFlight sets the gauge tracking concurrent step executions.
 func SetParallelStepsInFlight(n int) { ParallelStepsInFlight.Set(float64(n)) }