diff --git a/docs/reference/run-directory.mdx b/docs/reference/run-directory.mdx
index c7755d1ee..dc4828f8c 100644
--- a/docs/reference/run-directory.mdx
+++ b/docs/reference/run-directory.mdx
@@ -3,6 +3,10 @@ title: "Run Directory"
 description: "Structure of Fabro's per-run directory"
 ---
 
+<Warning>
+  The run directory structure and file formats described here are internal implementation details and subject to change without notice. Do not build tooling that relies on them.
+</Warning>
+
 Each `fabro run` invocation creates a timestamped directory under `~/.fabro/runs/`:
 
 ```