diff --git a/docs/atomic-upgrades.md b/docs/atomic-upgrades.md
index 27e02a7e..75d925e4 100644
--- a/docs/atomic-upgrades.md
+++ b/docs/atomic-upgrades.md
@@ -142,3 +142,19 @@ so just like `/boot`, it has a version of `0` or `1` appended.
 Each bootloader entry has a special `ostree=` argument which refers to
 one of these symbolic links.  This is parsed at runtime in the
 initramfs.
+
+## The /boot/ostree directory
+
+There is also a `/boot/ostree` directory which is where ostree will
+install kernel data (including the initramfs).  In order to
+deduplicate across deployments, the kernel state is hashed (again
+with sha256), resulting in a directory like `/boot/ostree/<stateroot>-<checksum>`;
+this is what the bootloader entries will use.
+
+However, this is an implementation detail and may change in the
+future.  As a tool which wants to find kernel for a given root, instead look
+in `/usr/lib/modules/$kver`; this is how OSTree itself finds
+the kernel to "deploy" by copying it into `/boot`.
+
+Note that if `/boot` is on the same partition as `/`, then OSTree
+will just hardlink instead of copying.