diff --git a/modules/clan/prometheus/README.md b/modules/clan/prometheus/README.md
index e69de29b..d4f57b27 100644
--- a/modules/clan/prometheus/README.md
+++ b/modules/clan/prometheus/README.md
@@ -0,0 +1,8 @@
+# Prometheus
+
+Monitoring over the Yggdrasil network. Requires the `yggdrasil` clan service on every machine in the instance.
+
+Roles:
+
+- `server`: runs Prometheus and Alertmanager, scraping every `nodes` machine by its Yggdrasil address. Optional `matrix-alertmanager` forwards alerts to Matrix rooms; the bot token and webhook secret are generated as clan vars.
+- `nodes`: enables the `services.prometheus.exporters` listed in `exporters` (with `openFirewall`) so the server can harvest them.