Add unique and new player metrics (Refs #142)

docs/guides/metrics.md

@@ -83,6 +83,40 @@ statistics do not establish lobby-hours, availability, or an autoscaling shortag
 Match statistics cover the selected period only and have no previous-period
 comparison.
 
+## Players over time
+
+The player chart uses the lobby chart's periods: hourly for 24 hours, and UTC-aligned
+24-hour periods for 7 or 30 days. Labels use the report timezone. **Unique players**
+counts distinct player GUIDs in every period overlapped by their recorded match
+participation, from first to last sighting. Multiple matches in one period count
+once, and the same GUID across Black Ops I and II is one player. Matches that began
+before the range still contribute participation inside it. These are recorded
+participants, not concurrent player counts or the lobby chart's player-hours.
+
+**New players** counts a GUID at its earliest recorded sighting across both games.
+Game and Map filters limit unique players to matching retained matches; new players
+count only when their original sighting was in a matching match. A regular's first
+visit to another map or game does not make them new again. Period boundaries belong
+to the following period; a sighting exactly at the range's end counts in the final
+period. Range totals count distinct GUIDs across the entire window independently:
+daily unique counts cannot be added to get the range total.
+
+Periods before the earliest retained match are gaps, not zero players. This history
+boundary is fleet-wide, so filtering to a quiet map does not hide recorded zeroes.
+The chart notes limited history and marks periods clipped by the selected range or
+the retained-history boundary with hollow points. Totals cover available history
+only. Select a point, use Left/Right or Home/End, or open **Inspect a period** for
+the exact interval and counts. **View exact time data** provides the same values
+in a keyboard-accessible table, with missing history shown as a dash.
+
+History begins when leaderboard recording started; earlier play cannot be recovered.
+Players already playing then count as new when first recorded. Participation spans
+do not prove continuous presence between reports, and unrecorded matches are absent.
+Match retention removes participation, which can shorten or leave holes in this
+history. The durable first-seen player identities survive retention, so removing an
+old match cannot make a returning player new again. The original map cannot be
+recovered from an expired match. The chart remains available without occupancy samples.
+
 ## Timeline and tables
 
 The timeline defaults to **Average lobbies running**, split into **With players**,
@@ -217,6 +251,14 @@ retains the recorded number of starts. Match scope uses the exact saved `game` a
 labels, and its time window uses the saved `started_at` timestamp. Occupancy
 collection and evidence timestamps remain independent of match history.
 
+`players` contains the separately deduplicated range totals `uniquePlayers` and
+`newPlayers`, plus `historyStartAt` (the earliest retained match, in epoch
+milliseconds). Every `points` entry also has `uniquePlayers`, `newPlayers`, and
+`playerHistoryPartial`. Counts before retained history are `null`; known periods
+with no scoped participation are zero. Player charts treat either `partial` or
+`playerHistoryPartial` as partial. Participation timestamp changes and durable
+first-seen identity changes invalidate the report cache.
+
 Map rows expose `noEmpty`, `availabilityObserved`, and
 `availabilityUnknown` durations, plus current `policy` context and
 `noEmptyAtMaximum` / `noEmptyBelowMaximum` durations. `pooledAvailability` combines