Add experimental metrics insights, comparisons, and scope filters

docs/metrics.md

@@ -14,6 +14,14 @@ Background refresh keeps the last successful report visible on failure and offer
 Retry. Returning to a visible tab refreshes immediately. The selected range is
 stored in the URL, and refreshes preserve table controls and chart selection.
 
+Game and map filters apply to the whole report, including its comparisons,
+recommendations, and heatmap. Map choices preserve the exact recorded game/map
+pair. Range and scope are shareable through the URL. Table searches remain local.
+
+The timeline defaults to **Share of captured time**: each stack includes occupied,
+idle, and unknown server time, normalized to 100%. This denominator differs from the
+headline utilization percentage, which excludes unknown time. Switch to **Hours**
+to compare absolute server time. Periods without captured time remain gaps.
 The timeline has labelled axes and marks partial edge periods. Select a period,
 use Previous/Next, or select a bar to inspect its exact interval and values. The
 time table supplies the same figures for comparison and assistive technology.
@@ -23,7 +31,46 @@ seconds or minutes so a real observation is not rounded to zero.
 Map and server tables support numeric sorting and local search. Their searches
 apply only to the named table. Known-capacity duration stays next to all-full time.
 Server identities retain the technical name; rows describe history grouped by
-name, which may include different instances if a name was reused.
+name, which may include different instances if a name was reused. **Open current
+server** appears only when that name is currently registered; its destination
+represents the current registration rather than every instance in the history.
+
+**Explore this period** adds experimental decision aids below the main timeline:
+
+- **Map capacity pressure** pools all-full map-hours divided by known-capacity
+  map-hours across the selected map groups. Overlapping map intervals are counted
+  separately. The score is not elapsed fleet time or a fleet health score; its
+  denominator and contributing map count remain visible.
+- **Previous-period comparisons** use the preceding equally long window with
+  identical filters. Utilization changes are percentage points; player-hours
+  changes are relative percentages. A previous observed zero can show **New**.
+  Missing evidence remains unavailable. Partial retained history is labelled;
+  a 30-day comparison usually has little previous history because retention is
+  only 31 days. Both periods' known time is shown. Bounds cannot establish that
+  collection was uninterrupted, and changes are not adjusted for fleet size.
+- **Activity heatmap** groups captured time by weekday and hour in its displayed
+  timezone. Color represents occupied / known server time. Exact cell values
+  include unknown time and contributing dates. No-data cells differ from observed
+  zero utilization; repeated DST hours contribute their actual elapsed time.
+- **Hosting experiments** are generated automatically from the selected map
+  observations. They are advisory and never create, restart, or destroy a server.
+
+Hosting Rules v1 deliberately offer experiments even with small samples:
+
+| Recorded condition | Suggested experiment |
+| --- | --- |
+| At least 20% of known capacity time had every lobby full | Trial one additional lobby during busy hours. |
+| Capacity unavailable and players present for at least 80% of known server time | Tentatively trial an extra lobby using occupancy as a proxy. |
+| Players present for at most 10% of known time, with under 1% measured pressure or unavailable capacity | Review one idle lobby or a shorter hosting window while preserving access to the map. |
+| Occupancy unavailable | Check telemetry/RCON reporting and watch for known player counts. |
+| Other observations | Check missing capacity or keep the lineup and watch peaks. |
+
+Each suggestion includes evidence and an outcome to watch. Unknown capacity,
+less than one hour of relevant known evidence, or substantial unknown captured
+status makes the suggestion tentative. These thresholds are product hypotheses;
+occupancy does not establish failed joins or a need for additional capacity.
+Suggestions use historical observations. Check the current lineup before trying
+a change; a retained map may no longer have a hosted lobby.
 
 - Utilized means a successful status response reported at least one player.
 - Idle means a successful response reported zero players.
@@ -36,3 +83,10 @@ Observations are recorded by the existing status worker. Each remains valid unti
 Capacity comes from `sv_maxclients` / `sv_maxClients` in the status response. When unavailable, the UI displays unknown rather than assuming a four-player limit. Capacity coverage is the map time for which every tracked lobby reported both occupancy and capacity.
 
 Collection begins after this feature is installed; previous occupancy cannot be reconstructed. Samples are retained for 31 days and pruned during collection. They survive removal of a server and contain no player identities. The additive database table is created automatically on startup.
+
+`GET /api/metrics` supplies the same report as the page and disables response
+caching. Query parameters are `days` (1, 7, or 30), `game`, `map` (requires game),
+and `timeZone` (an IANA zone). Invalid ranges and zones fall back to the defaults;
+invalid scope syntax is normalized. Fleet collection timestamps remain separate
+from selected-scope evidence timestamps. Collection boundaries are determined
+before scope filtering, so samples from other groups still end a batch interval.