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

@@ -18,7 +18,7 @@ import (
 
 // duplicateMemberView is one copy in a proposed duplicate group. LikeCount and
 // PlayCount span every user: the report is admin-only, and what a copy carries
-// is the fact the operator weighs when choosing which to keep.
+// is the fact an admin weighs when choosing which to keep.
 type duplicateMemberView struct {
 	TrackID     string `json:"track_id"`
 	Title       string `json:"title"`
@@ -36,13 +36,13 @@ type duplicateMemberView struct {
 	DiscNumber  *int32 `json:"disc_number"`
 	TrackNumber *int32 `json:"track_number"`
 	// StreamURL lets the review play each copy, to hear whether they are the
-	// same song (#6168).
+	// same song.
 	StreamURL string `json:"stream_url"`
 }
 
 // duplicateGroupView is one proposal. SurvivorTrackID and SurvivorReason are
 // the copy the report proposes keeping and the rule that chose it
-// (library.ProposeSurvivor) — a default the merge (#3911) lets the operator
+// (library.ProposeSurvivor) — a default the merge lets an admin
 // override.
 type duplicateGroupView struct {
 	ID                string   `json:"id"`
@@ -52,7 +52,7 @@ type duplicateGroupView struct {
 	SurvivorTrackID   string   `json:"survivor_track_id"`
 	SurvivorReason    string   `json:"survivor_reason"`
 	// Class is the resolver's verdict (library.DuplicateClass), null until its
-	// first pass; ResolveNote is why it left the group for the operator.
+	// first pass; ResolveNote is why it left the group for an admin.
 	Class       *string               `json:"class"`
 	ResolveNote *string               `json:"resolve_note"`
 	Members     []duplicateMemberView `json:"members"`
@@ -78,8 +78,8 @@ type duplicateViewCounts struct {
 	Resolved     int64 `json:"resolved"`
 }
 
-// Report views (M498). cross_release groups are the same song on different
-// releases, kept on purpose; everything else pending needs the operator.
+// Report views. cross_release groups are the same song on different
+// releases, kept on purpose; everything else pending needs an admin.
 const (
 	duplicateViewReview       = "review"
 	duplicateViewCrossRelease = "cross_release"
@@ -97,12 +97,13 @@ type adminDuplicatesResponse struct {
 	Groups       []duplicateGroupView    `json:"groups"`
 }
 
-// handleListDuplicates implements GET /api/admin/library/duplicates (#3912).
-// ?view=review (the default) or cross_release picks the tab (M498).
+// handleListDuplicates implements GET /api/admin/library/duplicates.
+// ?view=review (the default) or cross_release picks the tab.
 //
 // Read-only. The sweep's state and the fingerprint backfill's progress travel
 // with the groups because an empty report means three different things — still
-// fingerprinting, never swept, or swept and clean — and the page has to say which.
+// fingerprinting, never swept, or swept and clean — and the page has to say
+// which.
 func (h *handlers) handleListDuplicates(w http.ResponseWriter, r *http.Request) {
 	limit, offset, err := parsePaging(r.URL.Query())
 	if err != nil {
@@ -203,7 +204,7 @@ type resolvedActivityResponse struct {
 }
 
 // handleListResolvedDuplicates implements GET
-// /api/admin/library/duplicates/resolved (M498): what the resolver did by
+// /api/admin/library/duplicates/resolved: what the resolver did by
 // itself, newest first, read from the audit log so it outlives the groups.
 func (h *handlers) handleListResolvedDuplicates(w http.ResponseWriter, r *http.Request) {
 	limit, offset, err := parsePaging(r.URL.Query())
@@ -332,7 +333,7 @@ func (h *handlers) handleRunDuplicateSweep(w http.ResponseWriter, _ *http.Reques
 // handleDismissDuplicateGroup implements POST
 // /api/admin/library/duplicates/{id}/dismiss: "these are not duplicates". The
 // sweep keeps the dismissal and will not propose that set of tracks again. On a
-// cross-release group it also undoes the song link (M498 #5438): the copies
+// cross-release group it also undoes the song link: the copies
 // stop sharing likes from here on. 404 duplicate_group_not_pending when the
 // group was already resolved or is gone.
 func (h *handlers) handleDismissDuplicateGroup(w http.ResponseWriter, r *http.Request) {
@@ -380,7 +381,7 @@ type mergeDuplicateRequest struct {
 }
 
 // mergeDuplicateResponse reports what the merge removed. RemovedPaths are files
-// deleted from disk; the operator reads them to know exactly what went.
+// deleted from disk; an admin reads them to know exactly what went.
 type mergeDuplicateResponse struct {
 	SurvivorTrackID string   `json:"survivor_track_id"`
 	RemovedPaths    []string `json:"removed_paths"`
@@ -389,9 +390,10 @@ type mergeDuplicateResponse struct {
 // mergeRequestBodyLimit bounds the request body. It holds one id.
 const mergeRequestBodyLimit = 1 << 16
 
-// handleMergeDuplicateGroup implements POST /api/admin/library/duplicates/{id}/merge
-// (#3911): keep one copy, move the others' likes, plays and playlist entries onto
-// it, and delete the others' files and rows.
+// handleMergeDuplicateGroup implements POST
+// /api/admin/library/duplicates/{id}/merge: keep one copy, move the others'
+// likes, plays and playlist entries onto it, and delete the others' files and
+// rows.
 //
 // Errors:
 //   - 409 library_not_writable / 500 file_delete_failed when a file could not be
@@ -450,7 +452,7 @@ func (h *handlers) handleMergeDuplicateGroup(w http.ResponseWriter, r *http.Requ
 	writeJSON(w, http.StatusOK, resp)
 }
 
-// refetchDuplicateRequest is the operator's answer for one recording filling
+// refetchDuplicateRequest is an admin's answer for one recording filling
 // several of an album's slots. keep_track_id is the copy whose title the
 // recording is; empty means they cannot say, and every copy goes.
 type refetchDuplicateRequest struct {
@@ -466,9 +468,9 @@ type refetchDuplicateResponse struct {
 }
 
 // handleRefetchDuplicateGroup implements POST
-// /api/admin/library/duplicates/{id}/refetch (#6184): settle a group of one
-// recording in several slots of an album the way the resolver would, with the
-// operator's answer. The copies in slots that are not the recording's are
+// /api/admin/library/duplicates/{id}/refetch: settle a group of one
+// recording in several slots of an album the way the resolver would, with an
+// admin's answer. The copies in slots that are not the recording's are
 // removed and marked missing, the release they came from is set aside, and the
 // album is wanted again. Merge is the wrong action there: it keeps one title
 // whether or not it is the audio's, and fetches nothing.