From f9a492f7a9a945fb3d1b8c51112d2ca1696fe11c Mon Sep 17 00:00:00 2001
From: lexis <lexis@hyperhive>
Date: Sun, 31 May 2026 12:45:49 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20nix=20build=20attr=20path=20gotcha=20?=
 =?UTF-8?q?=E2=80=94=20nixosConfigurations=20not=20implicit=20(follow-up?=
 =?UTF-8?q?=20to=20#738)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/gotchas.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

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