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/suggestions.go

@@ -23,13 +23,13 @@ type suggestionView struct {
 	Score       float64                `json:"score"`
 	Attribution []seedContributionView `json:"attribution"`
 	// MatchedTags are the candidate's tags that overlap the user's taste
-	// profile, strongest first (#2377) — the "matches: shoegaze, melancholic"
+	// profile, strongest first — the "matches: shoegaze, melancholic"
 	// line. Omitted when empty, which is common: tag coverage for
-	// out-of-library artists is permanently partial (#2376), and the card
-	// falls back to the seed attribution it has always shown.
+	// out-of-library artists is permanently partial, and the card falls back
+	// to the seed attribution.
 	MatchedTags []string `json:"matched_tags,omitempty"`
 	// ImageURL is Minstrel's catalogue art endpoint for the candidate
-	// (out-of-library artists have no local art row, M502 #5519). It
+	// (out-of-library artists have no local art row). It
 	// answers 404 when no enabled source has an image, and the client
 	// falls back to a placeholder.
 	ImageURL string `json:"image_url,omitempty"`
@@ -75,7 +75,7 @@ func (h *handlers) handleListSuggestions(w http.ResponseWriter, r *http.Request)
 	}
 
 	// Read the tuned weight per request so an admin change takes effect on the
-	// next refresh, no restart (rule #25).
+	// next refresh, no restart.
 	tagWeight := h.recSettings.Discover().TagOverlapWeight
 	suggestions, err := recommendation.SuggestArtists(
 		r.Context(), h.pool, user.ID, halfLife, limit, tagWeight)
@@ -107,8 +107,8 @@ func (h *handlers) handleListSuggestions(w http.ResponseWriter, r *http.Request)
 }
 
 // maxSnoozeDays caps a client-supplied duration. The DEFAULT is not here: it's
-// a DB-backed knob on the admin tuning card (rule #25), read per request via
-// recSettings.Discover().SnoozeDays. See #2377.
+// a DB-backed knob on the admin tuning card, read per request via
+// recSettings.Discover().SnoozeDays.
 const maxSnoozeDays = 365.0
 
 // snoozeRequest is the POST body. Both fields are optional in the JSON sense
@@ -136,8 +136,8 @@ type snoozeView struct {
 // snoozing an already-snoozed candidate extends it rather than conflicting.
 //
 // This is NOT negative feedback. It records no verdict on the artist and is
-// never read by internal/taste — see 0049_suggestion_snoozes.up.sql for the
-// rule #101 reasoning. Returns 204.
+// never read by internal/taste — see 0049_suggestion_snoozes.up.sql for why.
+// Returns 204.
 func (h *handlers) handleSnoozeSuggestion(w http.ResponseWriter, r *http.Request) {
 	user, ok := requireUser(w, r)
 	if !ok {
@@ -222,7 +222,7 @@ func (h *handlers) handleUnsnoozeSuggestion(w http.ResponseWriter, r *http.Reque
 //
 // The un-snooze surface needs this: a parked candidate is by definition
 // absent from the suggestion deck, so without a list there is no way to
-// reach the DELETE above. Scoped to the caller (rule #47). Expired rows are
+// reach the DELETE above. Scoped to the caller. Expired rows are
 // already filtered by the query — the hourly gc sweep only reclaims space.
 func (h *handlers) handleListSuggestionSnoozes(w http.ResponseWriter, r *http.Request) {
 	user, ok := requireUser(w, r)
@@ -248,7 +248,7 @@ func (h *handlers) handleListSuggestionSnoozes(w http.ResponseWriter, r *http.Re
 }
 
 // resolveSuggestionArt points each suggestion's ImageURL at Minstrel's
-// catalogue art endpoint (M502 #5519). Nothing is fetched here: the image is
+// catalogue art endpoint. Nothing is fetched here: the image is
 // looked up from the enabled cover-art sources when the browser asks for it,
 // and kept, so listing suggestions makes no outbound call. A candidate with
 // no MBID keeps an empty ImageURL and the client renders its placeholder.