diff --git a/monitoring/loki/loki-config.yml b/monitoring/loki/loki-config.yml
index efea0ea8..100cb93a 100644
--- a/monitoring/loki/loki-config.yml
+++ b/monitoring/loki/loki-config.yml
@@ -1,3 +1,15 @@
+# Loki reads this file once, at startup. It has no reload endpoint and no
+# SIGHUP reload; only a separate -runtime-config.file reloads live, and this
+# stack passes -config.file only. It is also a single-file bind mount, so a git
+# pull replaces it by rename and the running container keeps reading the old
+# inode: a plain `docker compose up -d` changes nothing here. What applies an
+# edit is the DEP-6 hash label, `homelab.config-sha` on the loki service in
+# monitoring/compose.yaml, which deploy.yml sets to a sha256 of this file so a
+# content change recreates the container. It matters most for the retention
+# settings below: a retention_period edit that silently never loaded either
+# deletes logs you believed you were keeping or fills the disk, and both look
+# exactly like a healthy system until the damage is done.
+
 auth_enabled: false
 
 server:
diff --git a/monitoring/tautulli-exporter/main.py b/monitoring/tautulli-exporter/main.py
index fabe4e75..20c24c57 100644
--- a/monitoring/tautulli-exporter/main.py
+++ b/monitoring/tautulli-exporter/main.py
@@ -14,6 +14,16 @@
 #   5. Component transcode counts use Tautulli get_activity's stream_*_decision
 #      fields (upstream looked for nonexistent transcode_*_decision fields).
 # Re-sync required if the image pin in monitoring/compose.yaml changes.
+#
+# Python reads this file once, when the process starts, and it is a single-file
+# bind mount, so a git pull replaces it by rename and the running container
+# keeps the old inode: a plain `docker compose up -d` applies nothing. What
+# applies an edit is the DEP-6 hash label, homelab.config-sha on the
+# tautulli-exporter service in monitoring/compose.yaml, which deploy.yml sets to
+# a sha256 of this file so a content change recreates the container. Editing
+# this file without a deploy leaves the old code serving the old numbers, and
+# since two of the patches above are the exporter's own scrape-health metrics,
+# nothing reports a problem while it does.
 import os
 import sys
 import json