diff --git a/infra/ansible/vault.yml.example b/infra/ansible/vault.yml.example
index 1ee84e0..81ca1dc 100644
--- a/infra/ansible/vault.yml.example
+++ b/infra/ansible/vault.yml.example
@@ -4,6 +4,13 @@
 # Edit later with:
 #   ansible-vault edit vault.yml
 
+# DO NOT put a literal "$" in any value here. Docker compose interpolates the
+# top-level .env, and depending on version it also interpolates env_file, so a
+# password like "aB$fPx" is read as the variable $fPx and silently replaced
+# with an empty string — on one side of the connection but not the other.
+# That produced "MQTT connect refused: Not authorized" with no obvious cause.
+# Generate with: openssl rand -hex 32  (hex output has no shell metacharacters)
+
 # ── MQTT ─────────────────────────────────────────────────────────────────────
 vault_mqtt_c2_user: drb-c2-core
 vault_mqtt_c2_pass: "CHANGE_ME"