Support early build cache hints

README.md

@@ -15,6 +15,32 @@ also disables the default shell-oriented `amazon-init` service and enables a
 small generic service that treats EC2 user-data as `/etc/nixos/flake.nix`, then
 runs `nixos-rebuild switch --flake /etc/nixos`.
 
+## First-Boot Build Cache Hints
+
+The first user-data switch is built by the AMI's existing Nix configuration,
+before the target NixOS system has activated its own `nix.settings`. A caller
+flake can optionally expose `quixosEarlyBuildNixConfig` to make that first
+build use known binary caches without baking any project-specific cache into
+the AMI:
+
+```nix
+{
+  quixosEarlyBuildNixConfig = {
+    hosts = {
+      "2600:..." = [ "nix-cache.internal.example.org" ];
+    };
+    substituters = [ "http://nix-cache.internal.example.org/cache" ];
+    trustedPublicKeys = [ "nix-cache.internal.example.org-1:..." ];
+  };
+}
+```
+
+The AMI runner evaluates this output after writing `/etc/nixos/flake.nix`,
+appends the host hints to `/etc/hosts`, and passes the substituters and trusted
+public keys through `NIX_CONFIG` only for the first `nixos-rebuild switch`.
+The target NixOS configuration should still declare the same cache in
+`nix.settings` for all later rebuilds.
+
 ## Publish
 
 The normal flow builds on a temporary EC2 instance, so your local machine does