diff --git a/deploy/nixos/hardware/raspberry-pi-4.nix b/deploy/nixos/hardware/raspberry-pi-4.nix
index 8fc469b..f32bf69 100644
--- a/deploy/nixos/hardware/raspberry-pi-4.nix
+++ b/deploy/nixos/hardware/raspberry-pi-4.nix
@@ -57,7 +57,46 @@
   # highest priority survive. nixpkgs sets loglevel/lsm at normal priority, so
   # a mkDefault list here is dropped entirely — and with no console= at all
   # the kernel falls back to the device tree's stdout-path, i.e. this UART.
-  boot.kernelParams = [ "console=tty0" ];
+  # cma=256M: the vc4 display pipeline allocates its framebuffer from the
+  # contiguous memory area, and the default reservation on this board is 32MiB
+  # with about 11MiB free. A 3840x1080 framebuffer is ~16.6MB before double
+  # buffering, so X got as far as picking the mode and then died:
+  #
+  #   Output HDMI-1 using initial mode 3840x1080 +0+0
+  #   (EE) AddScreen/ScreenInit failed for driver 0
+  #
+  # nixos-hardware's fkms-3d injected a CMA overlay alongside the display one;
+  # this replaces that half of it. 256M is generous for any panel an ATM will
+  # carry and trivial against 4-8GB of RAM.
+  boot.kernelParams = [ "console=tty0" "cma=256M" ];
+
+  # ── REQUIRES A MANUAL STEP ON THE FIRMWARE PARTITION ────────────────
+  # This board boots the FIRMWARE's vendor DTB, not the DTBs NixOS builds.
+  # Confirmed on the CM4: the live device tree carries __symbols__ and the
+  # mainline DTBs in dtbs-filtered do not, and U-Boot found no FDTDIR match for
+  # compatible "raspberrypi,4-compute-module" so it passed the firmware's DTB
+  # through. That means hardware.deviceTree.overlays cannot reach the running
+  # device tree, and the display has to be enabled by the firmware instead.
+  #
+  # In the vendor DTB every display node (hvs, gpu, all pixelvalves, both hdmi)
+  # ships `disabled`. So /boot/firmware/config.txt needs:
+  #
+  #     dtoverlay=vc4-kms-v3d,noaudio
+  #
+  # and /boot/firmware/overlays/ needs to be populated from raspberrypifw --
+  # the NixOS sd-image writes the DTBs there but NOT the overlays, so the
+  # directory ships empty and the dtoverlay line fails silently. Copy the whole
+  # directory (2MB, 356 files); copying only vc4-kms-v3d.dtbo is not enough
+  # because the firmware remaps that to vc4-kms-v3d-pi4.dtbo on this board.
+  #
+  # `noaudio` is required, not cosmetic. With HDMI audio enabled vc4_hdmi cannot
+  # register its PCM component, returns -517 (EPROBE_DEFER) forever, and the DRM
+  # device never registers -- so X finds no card at all. We removed the audio
+  # stack anyway, so there is nothing to lose.
+  #
+  # This is a reflash-losing manual step and it should be folded into the image
+  # builder. Tracked as a follow-up; noted here so the next person does not
+  # rediscover it from a blank screen.
 
   # Kiosk display: mainline full KMS, NOT nixos-hardware's fkms-3d.
   #