docs: telemetry statement and Kubernetes telemetry provider guide

src/components/Footer.astro

@@ -19,6 +19,7 @@ const groups = [
     links: [
       { label: "Documentation", href: withBase("/docs/") },
       { label: "Changelog", href: withBase("/docs/changelog/") },
+      { label: "Telemetry", href: withBase("/telemetry/") },
       { label: "GitHub", href: GITHUB_URL },
     ],
   },

src/content/docs/air-gapped-installation.mdx

@@ -329,6 +329,19 @@ helm upgrade gameplane oci://registry.internal.corp/gameplane/charts-gameplane \
 
 Confirm the operator and API pods roll with the new image digest, and re-run GameServer tests above.
 
+### Disable usage telemetry
+
+New installs send anonymous usage reports to the project's provider at `telemetry.gameplane.net` unless told otherwise. An air-gapped cluster cannot reach it, and the reporter would retry for nothing. Turn telemetry off at install time so the API never attempts the connection, whatever an admin later toggles:
+
+```yaml
+# values-offline.yaml
+api:
+  telemetry:
+    enabled: false
+```
+
+With `api.telemetry.enabled=false` no first-login notice is shown and Admin Settings > Telemetry shows both switches as unavailable. To keep usage figures inside the cluster instead, leave telemetry enabled and set `api.telemetry.receiver.enabled=true` (the bundled receiver, mirrored as `telemetry-receiver` in the image list above), or point `api.telemetry.endpoint` at an internal receiver. See [Platform settings, telemetry, and build info](../platform-settings-telemetry/) and the [data-handling statement](https://gameplane.net/telemetry/).
+
 ### Test with egress fully blocked
 
 If possible, disconnect the cluster from the public internet (or block all egress via NetworkPolicy) and repeat the above tests to confirm every artifact is truly local. A 404 or timeout on any pull request confirms you missed an image.
@@ -339,5 +352,6 @@ If possible, disconnect the cluster from the public internet (or block all egres
     "01  Mirror chart + images + modules + signatures + SBOMs by digest",
     "02  Render offline; reject public hosts and mutable tags",
     "03  Test install, server, backup, upgrade, rollback with egress blocked",
+    "04  Set api.telemetry.enabled=false (or an internal endpoint) so no report leaves the cluster",
   ]}
 />

src/content/docs/helm-values-reference.mdx

@@ -128,7 +128,8 @@ Configure logging, metrics, and alerting sinks.
 | `api.audit.syslogBridge.enabled` | boolean | `false` | Deploy the bundled RFC 5424 syslog bridge (audit-syslog-bridge image). When enabled and `webhook.url` is unset, the API auto-wires to it. |
 | `api.audit.syslogBridge.syslog.addr` | string | *(empty — required if enabled)* | Syslog collector address in `host:port` format, e.g., `syslog.example:514`. |
 | `api.audit.syslogBridge.syslog.network` | enum | `tcp` | Syslog transport: `tcp` (recommended for reliability) or `udp` (no delivery confirmation). |
-| `api.telemetry.endpoint` | string | *(empty)* | External telemetry receiver URL, e.g., `https://telemetry.example.com/ingest`. Disables the bundled receiver auto-wiring. |
+| `api.telemetry.enabled` | boolean | `true` | Hard on/off for usage telemetry. `false` means the API never sends telemetry, whatever the admin switches say, and no first-login notice is shown. Use it for air-gapped and privacy-sensitive clusters. |
+| `api.telemetry.endpoint` | string | *(empty)* | Where reports go. Empty means the project's default provider, `https://telemetry.gameplane.net/ingest`. Set a URL such as `https://telemetry.example.com/ingest` to send reports to your own receiver instead; it replaces the default and disables the bundled receiver auto-wiring. |
 | `serviceMonitors.enabled` | boolean | `false` | Create Prometheus Operator ServiceMonitor resources for scraping Gameplane metrics. Requires Prometheus Operator to be installed in your cluster. |
 
 ## Storage and modules
@@ -179,7 +180,16 @@ Configure optional integrations.
 | Key | Type | Default | Description |
 |---|---|---|---|
 | `mcpServer.enabled` | boolean | `false` | Deploy a read-only Model Context Protocol (MCP) server for AI assistant integrations. It reads 7 Gameplane CRDs (not `Cluster`, nor `NetworkCapture`, the ninth CRD added in v0.3.0), plus Pods, Events and pod logs. Read-only, stdio JSON-RPC only (no network port). See `mcp-server/README.md`. |
-| `api.telemetry.receiver.enabled` | boolean | `false` | Deploy the bundled telemetry receiver (telemetry-receiver image) for opt-in anonymous usage stats. When enabled and `endpoint` is unset, the API auto-wires to it. Admin toggle in dashboard controls whether anything is sent. |
+| `api.telemetry.receiver.enabled` | boolean | `false` | Deploy the bundled telemetry receiver (telemetry-receiver image). When enabled and `endpoint` is unset, the API auto-wires to it, so reports stay in your cluster. Admin switches in the dashboard control whether anything is sent. |
+| `api.telemetry.receiver.persistence.enabled` | boolean | `true` | Keep the receiver's aggregates in a PVC at `/data` (`persistence.size`, default `1Gi`). With `false` an emptyDir is used and everything is lost on restart. While on, `receiver.replicas` must stay `1`. |
+| `api.telemetry.receiver.dashboard.tokenSecretRef.name` | string | *(empty)* | Secret holding the receiver's dashboard token (key `token`, at least 32 characters). Setting it starts the private dashboard listener on port 8081; reach it with `kubectl port-forward`. |
+| `api.telemetry.receiver.pepperSecretRef.name` | string | *(empty)* | Optional Secret (key `pepper`) with the HMAC pepper for install IDs. Empty means the receiver generates and stores one. |
+| `api.telemetry.receiver.publicSummary.enabled` | boolean | `false` | Serve five public aggregate counters on `GET /v1/summary`. |
+| `api.telemetry.receiver.retentionDays` | integer | `730` | Daily aggregate retention (minimum `365`). |
+| `api.telemetry.receiver.activityExpiryDays` | integer | `90` | Per-install activity record expiry (minimum `31`). |
+| `api.telemetry.receiver.ingestPow.enabled` | boolean | `false` | Require proof-of-work on report ingestion (tuned by `targetPerMinute` `60`, `minBits` `0`, `maxBits` `22`; `maxBits` at most `26`). Meant for a public provider. |
+
+To run a receiver for other installs, see [Run a telemetry provider on Kubernetes](../telemetry-provider-kubernetes/).
 
 ## Example: minimal production install
 

src/content/docs/platform-settings-telemetry.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Platform settings, telemetry, and build info"
-description: "Maintain instance identity and defaults, make an explicit telemetry choice, and capture exact build data for support."
+description: "Maintain instance identity and defaults, review the telemetry tiers and opt-out, and capture exact build data for support."
 section: "platform"
 group: "audit-observability"
 order: 7
@@ -44,26 +44,33 @@ Keep instance name, canonical external URL, and default namespace stable and env
 
 ## Telemetry and privacy
 
-Usage telemetry is an explicit choice and is not a substitute for operational metrics and logs.
+Usage telemetry is on by default for new installs and is not a substitute for operational metrics and logs. Reports go to the project's provider at `telemetry.gameplane.net` unless the operator chose another destination or disabled telemetry. The project's [data-handling statement](../../telemetry/) lists exactly what is collected and how long it is kept.
 
-When enabled, the API sends a daily anonymous report containing only the cluster version, count of active GameServers, and count of GameTemplates. The current implementation excludes server names, player counts, and identifying data.
+On a new install the first admin to sign in sees a notice naming the destination and both tiers; nothing is sent until an admin has seen it. Admin Settings > Telemetry then shows the destination, a preview of the next report, the last attempt, separate switches for the basic and extended tiers, and an install-ID reset. Turning basic off turns extended off with it.
+
+**Basic** sends only the Gameplane version, the GameServer count and the GameTemplate count. **Extended** adds a random install ID, the Kubernetes minor version, a distribution category, CPU architectures and a node-count band, server counts per official module (custom modules are one combined count), feature adoption flags and bands, the database kind, the UI language, a public signing key and the send time. Every value comes from a fixed set or is a number; names, namespaces, hostnames, addresses and player data are never sent.
 
 <DocsSectionList
   items={[
     {
       icon: "check",
-      label: "The current promise excludes server names, players, and identifying data",
-      text: "Only version, server count, and template count are transmitted. No names, IDs, or private configuration is collected.",
+      label: "Choose the tiers deliberately",
+      text: "Basic and extended have separate switches. Turn extended off to keep only the version and the two counts, or turn both off to send nothing. Resetting the install ID gives the install a new, unlinkable ID and signing key.",
     },
     {
       icon: "check",
-      label: "Document any required organizational privacy review",
-      text: "If your organization requires a Data Processing Agreement or privacy assessment, collect the details from the telemetry-receiver configuration and CHANGELOG before enabling.",
+      label: "Operators can disable or redirect telemetry at install time",
+      text: "Set `api.telemetry.enabled=false` for a hard off that no admin switch can override (the switches are shown as unavailable and no notice appears). Set `api.telemetry.endpoint` to send reports to your own receiver instead of the project's. See the Helm values reference and the air-gapped guide.",
     },
     {
       icon: "check",
       label: "Recheck the saved choice after upgrades",
-      text: "Telemetry state persists across upgrades. After updating Gameplane, verify that your chosen setting (enabled or disabled) matches your policy.",
+      text: "Installs that never saved a choice stay off after an upgrade; installs that had basic on keep basic and get extended only when an admin turns it on. After updating, confirm the setting matches your policy.",
+    },
+    {
+      icon: "check",
+      label: "Document any required organizational privacy review",
+      text: "If your organization requires a privacy review, use the data-handling statement and the field list above; the provider keeps daily aggregates for 24 months and per-install activity records for 90 days.",
     },
   ]}
 />
@@ -88,7 +95,7 @@ Before opening a support ticket or upgrading:
   label="PLATFORM RECORD"
   items={[
     "Stable instance name + canonical URL + intentional namespace",
-    "Explicit telemetry choice; operational monitoring remains separate",
+    "Telemetry tiers chosen on purpose (or disabled at install); operational monitoring remains separate",
     "Record chart/image-tag/Kubernetes/values before support or upgrade",
   ]}
 />