diff --git a/docs/gotchas.md b/docs/gotchas.md
index 9c781519..ab9e6e66 100644
--- a/docs/gotchas.md
+++ b/docs/gotchas.md
@@ -170,6 +170,29 @@ firefox / safari are consistent). Asset fetches (`image/*`,
 fall through to the trailing `=404`. No extension list to maintain;
 no named-location indirection needed.
 
+## `nix build flake#name` does not walk into `nixosConfigurations`
+
+`nix build` resolves the fragment (`#name`) against the flake's
+**top-level output attrs** — not against `nixosConfigurations`
+specifically. `nixos-container` and `nixos-rebuild` use their own
+internal convention that routes an agent name to
+`nixosConfigurations.<name>.config.system.build.toplevel`, but
+`nix build` has no such convention.
+
+```
+# ❌ silently builds the wrong thing (or errors if attr doesn't exist)
+nix build /var/lib/hyperhive/meta#argus.config.system.build.toplevel
+
+# ✅ explicit path nix build actually resolves
+nix build /var/lib/hyperhive/meta#nixosConfigurations.argus.config.system.build.toplevel
+```
+
+`lifecycle::prebuild_toplevel` hit this in #721 (fixed in #738) by
+constructing the attr path as `{flake_ref}.config…` — which produced
+`meta#argus.config…` instead of `meta#nixosConfigurations.argus.config…`.
+The fix: `split_once('#')` to separate flake path from name, then
+template `{path}#nixosConfigurations.{name}.config.system.build.toplevel`.
+
 ## `hive-forge`: prefer over raw curl pipelines
 
 Every agent container has `hive-forge` in PATH (installed via