docs: server comments say what the code does, not how it came to be (#6277)

Comment blocks in cmd/minstrel and 30 smaller internal packages, rewritten
to rule 32's standard with each citation read in context: task, milestone
and rule ids go, and so do the stories they were attached to ("used to",
"Before #N", measurements from one install, quotes, pointers to Fabled
Librarian's records and to docs/superpowers files that are not in the
repo). Where a story wrapped a real constraint, the constraint stays as a
present-tense fact.

Comments that had gone stale are corrected:
- taste.Config: the tuned values are overlaid by internal/recsettings;
  it is no longer "a later follow-up".
- StorageConfig: the data dir holds art, caches and the stream secret,
  not only playlist covers.
- the Subsonic album list and getUser comments describe what they do
  today rather than a milestone that would change it.

Checked: the non-comment token stream of every changed file matches
HEAD, and gofmt -l is empty.

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

internal/coverart/artist_enricher.go

@@ -141,11 +141,11 @@ func (e *Enricher) recordArtistArt(ctx context.Context, artistID pgtype.UUID, th
 //
 // Emits a single Info log line at end-of-batch with a category
 // breakdown (succeeded / settled-none / no-MBID / left-NULL /
-// errored). The JSON tally written to scan_runs keeps the existing
-// processed/succeeded/failed shape for backwards compat with the
-// admin overview UI; the log line is the operator's diagnostic.
-// limit: 0 = stage disabled; >0 = bounded; <0 = unbounded (#388 —
-// no global cap; remote providers self-throttle per provider).
+// errored). The JSON tally written to scan_runs keeps the
+// processed/succeeded/failed shape the admin overview reads; the log line
+// is the diagnostic.
+// limit: 0 = stage disabled; >0 = bounded; <0 = unbounded (remote
+// providers pace themselves).
 func (e *Enricher) EnrichArtistBatch(ctx context.Context, limit int, dataDir string,
 	progressCb func(processed, succeeded, failed int)) (processed, succeeded, failed int, err error) {
 	if limit == 0 {

internal/coverart/enricher.go

@@ -210,13 +210,12 @@ func (e *Enricher) recordAlbumCover(ctx context.Context, albumID pgtype.UUID, pa
 //
 // Emits a single Info log line at end-of-batch with a category
 // breakdown (succeeded / settled-none / left-NULL / errored). The
-// JSON tally written to scan_runs keeps the existing
-// processed/succeeded/failed shape for backwards compat with the
-// admin overview UI; the log line is the operator's diagnostic.
+// JSON tally written to scan_runs keeps the processed/succeeded/failed
+// shape the admin overview reads; the log line is the diagnostic.
 // limit semantics: 0 = stage disabled (skip); >0 = bounded batch;
-// <0 = unbounded — walk every album needing art. The global cap was
-// removed (#388); external providers self-throttle via their
-// per-provider httpClient MinInterval, local sources run at disk speed.
+// <0 = unbounded — walk every album needing art. External providers pace
+// themselves via their httpClient MinInterval; local sources run at disk
+// speed.
 func (e *Enricher) EnrichBatch(ctx context.Context, limit int,
 	progressCb func(processed, succeeded, failed int)) (processed, succeeded, failed int, err error) {
 	if limit == 0 {
@@ -302,7 +301,7 @@ func (e *Enricher) logBatchSummary(stage string, eligible, processed, succeeded,
 // admin bulk-retry endpoint. Clears 'none' to NULL first so
 // EnrichAlbum picks them up.
 // limit: 0 = no-op; >0 = bounded; <0 = unbounded (retry every
-// missing/none album). Admin bulk-retry passes <0 post-#388.
+// missing/none album). Admin bulk-retry passes <0.
 func (e *Enricher) EnrichRetryMissing(ctx context.Context, limit int) (int, error) {
 	if limit == 0 {
 		return 0, nil
@@ -346,9 +345,8 @@ func (e *Enricher) RetryAlbum(ctx context.Context, albumID pgtype.UUID) error {
 		}
 		return fmt.Errorf("get album: %w", err)
 	}
-	// Delete the file only if we previously wrote it (mbcaa or
-	// theaudiodb). Operator sidecars stay; embedded extracts (future)
-	// live in a managed cache with its own lifecycle.
+	// Delete the file only if we wrote it (mbcaa or theaudiodb). Sidecar
+	// images placed beside the music stay.
 	if row.CoverArtSource != nil &&
 		(*row.CoverArtSource == "mbcaa" || *row.CoverArtSource == "theaudiodb") &&
 		row.CoverArtPath != nil && *row.CoverArtPath != "" {

internal/coverart/provider.go

@@ -16,8 +16,7 @@ import (
 type Provider interface {
 	// ID is a stable lowercase token persisted in DB columns
 	// (cover_art_source / artist_art_source) and the
-	// cover_art_provider_settings.provider_id key, plus referenced
-	// in the operator-facing UI.
+	// cover_art_provider_settings.provider_id key, and shown in the admin UI.
 	ID() string
 
 	// DisplayName is the human-readable label shown in the admin
@@ -36,7 +35,7 @@ type Provider interface {
 	// with this provider on. Both v1 providers return true.
 	DefaultEnabled() bool
 
-	// Configure receives the operator's settings (api_key, enabled
+	// Configure receives the admin's settings (api_key, enabled
 	// flag) and applies them. Called at boot during reconciliation
 	// and on every admin PATCH. Implementations must be idempotent
 	// and goroutine-safe (the enricher may be reading concurrently).
@@ -84,7 +83,7 @@ type AlbumCoverProvider interface {
 
 // ReleaseGroupCoverProvider is an opt-in capability for sources that can
 // answer by MusicBrainz release group, which is how the release catalogue
-// names an album before any edition of it is held (M502 #5519).
+// names an album before any edition of it is held.
 type ReleaseGroupCoverProvider interface {
 	AlbumCoverProvider
 	FetchReleaseGroupCover(ctx context.Context, groupMBID string) ([]byte, error)

internal/coverart/provider_mbcaa.go

@@ -11,7 +11,7 @@ import (
 	"time"
 )
 
-// FetcherConfig assembles the operator-tunable knobs for the MBCAA
+// FetcherConfig assembles the tunable knobs for the MBCAA
 // HTTP client. Kept exported because main.go's boot wiring constructs
 // one to pass into NewMBCAAProviderFromConfig.
 type FetcherConfig struct {
@@ -97,7 +97,7 @@ func (p *mbcaaProvider) FetchAlbumCover(ctx context.Context, ref AlbumRef) ([]by
 
 // FetchReleaseGroupCover retrieves the 500px front cover the Cover Art
 // Archive chose for a release group: what a search result or a wanted album
-// shows before any edition of it is held (M502 #5519).
+// shows before any edition of it is held.
 func (p *mbcaaProvider) FetchReleaseGroupCover(ctx context.Context, groupMBID string) ([]byte, error) {
 	return p.fetchFront(ctx, "release-group", groupMBID)
 }

internal/coverart/settings.go

@@ -270,10 +270,9 @@ func enabledSetSignature(enabledIDs map[string]bool) string {
 // unchanged, returns (currentVersion, false, nil) without touching the DB.
 //
 // Used at boot to ensure rows previously settled to 'none' get re-tried
-// once after a provider chain change (e.g. operator updates the binary
-// and a new provider is registered, or one is removed). The version
-// bump triggers eligibility for 'none' rows on the next enrichment pass
-// without requiring a manual operator action.
+// once after a provider chain change (an update registers a new provider,
+// or removes one). The version bump makes 'none' rows eligible on the next
+// enrichment pass with no manual step.
 func (s *SettingsService) BumpVersionIfProvidersChanged(ctx context.Context) (version int32, bumped bool, err error) {
 	hash := registeredProvidersHash()
 	q := dbq.New(s.pool)
@@ -313,7 +312,7 @@ func registeredProvidersHash() string {
 
 // BumpVersion unconditionally increments cover_art_sources_meta.current_version
 // and returns the new value. Used by the manual "Re-search missing art"
-// admin endpoint when the operator wants every 'none' row re-attempted
+// admin endpoint, to re-attempt every 'none' row
 // on the next enrichment pass.
 //
 // Distinct from BumpVersionIfProvidersChanged: that method is the boot-