diff --git a/README.md b/README.md
index e5d4db3..f28b641 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,12 @@ repackaging a prebuilt archive.
 
 ## Install
 
+> **Note:** this repository must stay **public**. Flatpak fetches the OSTree
+> repo from the raw `pages` branch without any credentials — with the repo set
+> to private, `flatpak remote-add` / `flatpak install` fail with a 404.
+> (The agent's source lives in the private HeiniRemote repo; only the built
+> binary is published here.)
+
 From the Flatpak remote (gets updates via `flatpak update`):
 
 ```sh