docs: api comments say what the endpoints do, not how they came to be (#6277)

Rewrites the internal/api comment blocks to rule 32: task, milestone and
rule ids gone, the stories behind them restated as the constraint they
left, stale references corrected (the stream secret is wired from config,
the timezone handler already refreshes the scheduler, the Android app is
the native client, the design docs cited are not in the repo). Also
rewraps comment lines over 80 columns left by the earlier batches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/api/radio.go

@@ -82,16 +82,14 @@ func (h *handlers) handleRadio(w http.ResponseWriter, r *http.Request) {
 	}
 
 	currentVec := loadCurrentSessionVector(r, q, user.ID, h.logger)
-	// Condition on the current device (#1551): the latest play's device is a
+	// Condition on the current device: the latest play's device is a
 	// cheap, request-free proxy for what the user is on right now.
 	currentVec.DeviceClass = latestDeviceClass(r.Context(), q, user.ID, h.logger)
 
 	exclude := parseExcludeParam(r.URL.Query().Get("exclude"))
-	// Size the pool to the library (#3880). A fixed ~170 candidates samples a
-	// shrinking fraction of a growing collection, which is what made the
-	// recommendations feel less relevant as the library grew. Degrades to the
-	// base limits if the count is unavailable — never fails the request over a
-	// sizing hint.
+	// Size the pool to the library: a fixed ~170 candidates samples a shrinking
+	// fraction of a growing collection. Degrades to the base limits if the
+	// count is unavailable — never fails the request over a sizing hint.
 	librarySize := h.librarySize.Get(r.Context(), func(ctx context.Context) (int64, error) {
 		return recommendation.CountLibraryTracks(ctx, q)
 	})
@@ -101,7 +99,7 @@ func (h *handlers) handleRadio(w http.ResponseWriter, r *http.Request) {
 	candidates, err := recommendation.LoadCandidatesFromSimilarity(
 		r.Context(), q, user.ID, seedID,
 		h.recCfg.RecentlyPlayedHours, currentVec, exclude, limits,
-		// A fresh seed per request (#3889): radio is a new session each time
+		// A fresh seed per request: radio is a new session each time
 		// and SHOULD draw differently. The system mixes are the surfaces that
 		// promise repeatability; this is not one of them.
 		strconv.FormatInt(time.Now().UnixNano(), 36),
@@ -119,11 +117,11 @@ func (h *handlers) handleRadio(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	// Scoring weights come from the DB-backed tuning lab (#1250) —
+	// Scoring weights come from the DB-backed tuning —
 	// read per request so an admin change takes effect live.
 	weights := h.recSettings.Weights(recsettings.ScopeRadio)
-	// Diversity caps (#3882). Radio had none while every sibling surface did,
-	// which is how a whole session could come back from one artist. Scaled to
+	// Diversity caps, so a whole session cannot come back from one artist.
+	// Scaled to
 	// the requested length so a 20-track radio and a 200-track one are capped
 	// alike; Shuffle relaxes them rather than returning a short radio.
 	//
@@ -177,7 +175,7 @@ func loadCurrentSessionVector(r *http.Request, q *dbq.Queries, userID pgtype.UUI
 }
 
 // latestDeviceClass returns the device_class of the user's most recent play as
-// the "current device" for context conditioning (#1551), or "" when unknown
+// the "current device" for context conditioning, or "" when unknown
 // (no plays yet, or the latest play predates device capture). Best-effort: a
 // lookup failure yields a device-agnostic ("") affinity cell.
 func latestDeviceClass(ctx context.Context, q *dbq.Queries, userID pgtype.UUID, logger *slog.Logger) string {