diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
new file mode 100644
index 00000000..3b4a6ca5
--- /dev/null
+++ b/docs/CHANGELOG.md
@@ -0,0 +1,10 @@
+# Changelog
+
+## 2026-07-20
+
+- Added `overlays/paho-mqtt.nix` to disable paho-mqtt's flaky, socket-based
+  test suite. Its `checkPhase` hangs in the Nix sandbox and times out with a
+  `KeyboardInterrupt` after ~150s, which was breaking the `flame` rebuild
+  (paho-mqtt is pulled in transitively, e.g. via mealie). The override is
+  applied through `pythonPackagesExtensions` so it covers every Python
+  package set.
diff --git a/overlays/paho-mqtt.nix b/overlays/paho-mqtt.nix
new file mode 100644
index 00000000..4b70b6eb
--- /dev/null
+++ b/overlays/paho-mqtt.nix
@@ -0,0 +1,20 @@
+# Disable paho-mqtt's flaky test suite.
+#
+# paho-mqtt's checkPhase runs socket-based integration tests that hang in
+# the Nix sandbox (they eventually time out with a KeyboardInterrupt after
+# ~150s, reporting errors and failing the build). This breaks the flame
+# rebuild, where paho-mqtt is pulled in transitively (e.g. via mealie).
+#
+# Applied through pythonPackagesExtensions so it covers every Python
+# package set (python3Packages, python314Packages, ...).
+
+_inputs: _final: prev: {
+  pythonPackagesExtensions = prev.pythonPackagesExtensions ++ [
+    (_pyfinal: pyprev: {
+      paho-mqtt = pyprev.paho-mqtt.overridePythonAttrs (_old: {
+        doCheck = false;
+        doInstallCheck = false;
+      });
+    })
+  ];
+}