Add developer API, Prometheus metrics, and community links

docs/prometheus.md

@@ -0,0 +1,77 @@
+# Prometheus and Grafana
+
+Open MineGeo's **Moderation** page while signed in as an **Admin**, then find
+**Prometheus & Grafana**. Regular Moderators cannot view or change this setup.
+No new Vercel environment variables or Supabase keys are needed.
+
+## Connect Prometheus
+
+1. Click **Generate metrics token**. Copy the generated configuration immediately.
+   Only a token hash is stored; the raw token cannot be recovered after leaving
+   the page or hiding it.
+2. Paste the configuration into your Prometheus server's `prometheus.yml`.
+   If that file already has `scrape_configs:`, add only the `- job_name: minegeo`
+   entry under that existing section. Do not create two `scrape_configs` keys.
+3. Validate the configuration with `promtool check config prometheus.yml`, then
+   reload or restart your Prometheus service using its normal deployment process.
+4. In Prometheus, open **Status → Targets** and check that `minegeo` is **UP**.
+   A successful scrape also appears in MineGeo's **Last successful scrape** field;
+   use **Refresh status** to update it.
+
+Prometheus must be able to reach MineGeo's public HTTPS address. The endpoint is
+`https://minegeo.vercel.app/api/metrics`, protected by an Authorization bearer
+header. Browser login cookies, plugin credentials, and URL query tokens do not
+grant access. The generated job scrapes once a minute with a 20-second timeout
+and does not forward credentials through redirects. Keep the configuration
+private; do not paste it into public Git repositories or forum posts.
+
+**Rotate metrics token** revokes the previous token immediately. Copy the new
+configuration and update Prometheus afterward. **Disable metrics access** revokes
+the current token. Deleting the issuing Admin account or removing its Admin role
+also invalidates that token. Issuing another token requires a current Admin.
+
+## Import the Grafana dashboard
+
+1. In MineGeo, click **Download Grafana dashboard**.
+2. In Grafana, add a **Prometheus** data source pointing to your Prometheus server
+   (for example, its internal service address). Grafana queries Prometheus;
+   it does not use the MineGeo metrics URL as its data source.
+3. Open **Dashboards → New → Import**, upload the downloaded JSON, and choose the
+   Prometheus data source when prompted.
+4. Select the MineGeo instance. Allow one or two scrapes for the first values.
+
+The dashboard has 15 panels covering scrape health, registered accounts, maps,
+panoramas, solo games, multiplayer rooms, uploads, bug reports, content reports,
+Discord delivery, exporter read time, and snapshot age. It requires only the
+built-in Prometheus source and Grafana stat/time-series panels.
+
+History begins when your Prometheus instance starts scraping; existing retained
+records appear in the first snapshot. Prometheus retention controls how long
+history remains. Set up Prometheus/Grafana on your own server or supported hosted
+monitoring service; Vercel runs the exporter, not the monitoring servers.
+
+## Meaning and privacy of metrics
+
+- All `minegeo_*` values are **gauges**, not monotonic counters. Deleted records,
+  including closed bug reports removed after three days, can lower counts.
+  Do not use `rate()` or `increase()` on these retained inventory gauges.
+- Games/rooms created in the last 24 hours are rolling-window gauges.
+- Solo games are complete once `current_round = 5`. Incomplete includes abandoned
+  games. Room lifecycle states describe stored rooms, not currently online users.
+- Aggregates are collected in one database transaction and cached there for
+  30 seconds to share work across Vercel instances. Failed scrapes return 503,
+  never a fabricated all-zero dataset. Prometheus's `up` series records failures.
+- Names, IDs, emails, messages, screenshots, credentials, and map content are
+  excluded. Metric labels use fixed state/difficulty values only.
+- Page views, IP addresses, browser sessions, Vercel CPU/memory, and request latency
+  are not collected by this integration. Vercel Web Analytics remains separate.
+
+For another installation, apply
+`supabase/migrations/20261012085217_prometheus_metrics.sql` before deployment.
+The new table has RLS and service-role-only permissions; the three RPC functions
+use `security invoker` and explicitly revoke public/anonymous/authenticated access.
+Verify SQL authorization locally with `node scripts/test-prometheus-sql.mjs` using
+the same optional PGlite runtime as the existing SQL verification scripts.
+
+References: [Prometheus scrape configuration](https://prometheus.io/docs/prometheus/latest/configuration/configuration/),
+[Grafana dashboard imports](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/import-dashboards/).