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

@@ -2,27 +2,19 @@ package api
 
 import "math"
 
-// Uncertainty on the deltas the recommendation-metrics card shows (#2495).
+// Uncertainty on the deltas the recommendation-metrics card shows.
 //
-// Why this exists: the card had exactly one volume threshold,
-// recMetricsLowVolume = 20, and it was doing two jobs. Twenty plays is enough to
-// be worth DISPLAYING — below that a skip rate is anecdote — but it is nowhere
-// near enough to ACT on. Detecting the ~13pp differences that actually matter
-// needs roughly 133 plays per arm for 80% power at α=0.05.
+// recMetricsLowVolume = 20 answers "is this worth DISPLAYING" — below that a
+// skip rate is anecdote — but twenty plays is nowhere near enough to ACT on.
+// Detecting the ~13pp differences that actually matter needs roughly 133
+// plays per arm for 80% power at α=0.05, and two arms of 60-70 plays each
+// can look like a bold difference while sitting at p ≈ 0.06.
 //
-// So Discover's taste-matched (59 plays) and random-unheard (70) both rendered as
-// full-confidence rows with a bold delta beside them, and that comparison sits at
-// p ≈ 0.06. The card said "signal"; the arithmetic said "maybe". It led directly
-// to a recommendation the data didn't support, and any reader with the same
-// numbers would have made the same call.
-//
-// The fix is to publish the margin of error next to the delta and flag when the
-// delta is smaller than it — i.e. not distinguishable from zero. Computed here,
-// server-side, so both clients agree rather than each re-deriving it.
-//
-// recMetricsLowVolume stays exactly as it was. This is a second, independent
-// signal, not a replacement: "too thin to show" and "too thin to act on" are
-// different questions and deserve different answers.
+// So each delta carries its margin of error, and a flag when the delta is
+// smaller than it — not distinguishable from zero. Computed here,
+// server-side, so both clients agree rather than each re-deriving it. "Too
+// thin to show" and "too thin to act on" are different questions and get
+// different answers.
 
 // deltaZ is the two-sided 95% normal critical value. Normal rather than
 // Student's t: at the sample sizes where a delta is worth acting on (n in the
@@ -50,7 +42,8 @@ type metricDelta struct {
 // proportionDelta compares two rates (skips/plays) as a two-proportion
 // difference. Returns nil when either sample is empty, or when either rate is
 // degenerate (0 or 1) — a rate with no observed variation has an SE of 0 on its
-// side, which would report a spuriously narrow margin rather than an honest one.
+// side, which would report a spuriously narrow margin rather than an honest
+// one.
 func proportionDelta(rate1 float64, n1 int64, rate2 float64, n2 int64) *metricDelta {
 	if n1 <= 0 || n2 <= 0 {
 		return nil
@@ -98,8 +91,8 @@ func newDelta(deltaPP, marginPP float64) *metricDelta {
 }
 
 // sampleVariance recovers the sample variance from the aggregates the SQL
-// returns. sum is mean×n rather than a selected column, which keeps the query to
-// one extra expression.
+// returns. sum is mean×n rather than a selected column, which keeps the query
+// to one extra expression.
 //
 // The subtraction can go very slightly negative through floating-point
 // cancellation when every observation is identical, so the result is clamped —