diff --git a/pkgs/by-name/bootpart-uefi-x86_64/package.nix b/pkgs/by-name/bootpart-uefi-x86_64/package.nix
index 3942e6f61..6dc191182 100644
--- a/pkgs/by-name/bootpart-uefi-x86_64/package.nix
+++ b/pkgs/by-name/bootpart-uefi-x86_64/package.nix
@@ -1,3 +1,5 @@
+# DEBUGGING
+# - if it fails to load menu.c32, or anything, just type 'nixos-default', to boot the default entry.
 {
   runCommandLocal,
   syslinux,
@@ -37,21 +39,17 @@ runCommandLocal "bootpart-uefi-x86_64" {
   };
 } ''
   # populate the EFI directory with syslinux, and configure it to read the extlinux.conf file managed by nixos.
-  mkdir -p $out/EFI/syslinux
-  cp -R ${syslinux'}/share/syslinux/efi64/* $out/EFI/syslinux/
-  install -Dm644 ${./EFI/syslinux/syslinux.cfg} $out/EFI/syslinux/syslinux.cfg
-
-  # create the EFI/BOOT/BOOTX64.EFI default entry.
-  # except for systems with multiple bootloaders, this is the entry the BIOS will actually boot,
-  # and nothing in /EFI/syslinux is actually read during any part of boot.
-  # but keep /EFI/syslinux around, so that one can copy the .c32 modules out of it
-  # (and into /syslinux/) to configure runtime features like menuing.
-  install -Dm644 $out/EFI/syslinux/syslinux.efi $out/EFI/BOOT/BOOTX64.EFI
-  # install the ldlinux runtime dependency, else it hangs at a black screen
-  install -Dm644 $out/EFI/syslinux/ldlinux.e64 $out/EFI/BOOT/ldlinux.e64
+  # i populate two entries: /EFI/syslinux, for EFI-program-aware bootloaders (which may host multiple EFI programs),
+  # and /EFI/BOOT/BOOTX64.EFI, for older bootloaders that hardcode the EFI program to load.
+  for entry in BOOT syslinux; do
+    mkdir -p $out/EFI/$entry
+    cp -R ${syslinux'}/share/syslinux/efi64/* $out/EFI/$entry
+    install -Dm644 ${./EFI/syslinux/syslinux.cfg} $out/EFI/$entry/syslinux.cfg
+    if [ "$entry" = "BOOT" ]; then
+      mv $out/EFI/$entry/syslinux.efi $out/EFI/$entry/BOOTX64.EFI
+    fi
+  done
 
   # we create this "trampoline" layer so that we can setup the UI directive
-  # and enable a menu before loading the real, nixos-managed extlinux.conf.
-  install -Dm644 ${syslinux'}/share/syslinux/efi64/menu.c32 $out/syslinux/menu.c32
   install -Dm644 ${./syslinux/syslinux.cfg} $out/syslinux/syslinux.cfg
 ''
diff --git a/pkgs/by-name/bootpart-uefi-x86_64/syslinux/syslinux.cfg b/pkgs/by-name/bootpart-uefi-x86_64/syslinux/syslinux.cfg
index b2564f47c..ad0841b98 100644
--- a/pkgs/by-name/bootpart-uefi-x86_64/syslinux/syslinux.cfg
+++ b/pkgs/by-name/bootpart-uefi-x86_64/syslinux/syslinux.cfg
@@ -1,2 +1,23 @@
+# ABOUT THE /boot LAYOUT:
+# /EFI/syslinux/syslinux.efi: EFI entrypoint which modern bootloaders should hand off to.
+# /EFI/BOOT/BOOTX64.EFI:      fallback EFI entrypoint for older firmware which doesn't know
+#                                  how to locate EFI programs, and hardcodes entries instead.
+#
+# for either .efi, the entrypoint first loads from its same directory:
+# - ldlinux.e64
+# - syslinux.cfg
+# in both cases, the syslinux.cfg loaded "trampolines" here, to /syslinux/syslinux.cfg.
+#
+# within this file, we can configure the UI mode (e.g. barebones prompt, curses-like 'menu.c32'),
+# add boot entries (e.g. a memtest entry), and so on.
+
+# N.B.: .c32 files mentioned here are loaded on-demand, from either the current directory *or*
+# the .efi's original directory in /EFI/...
+#
+# known menus:
+# - UI cmenu.c32: fails to load: `Undef symbol FAIL: memset`
+# - UI vesamenu.c32: fails to load: `Undef symbol FAIL: memset`
+# - UI menu.c32: works, basic fixed-size curses-like menu
+#
 UI menu.c32
 INCLUDE ../extlinux/extlinux.conf