Document Flex/FydeOS taking over UEFI BootOrder on updates

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

CHROMEOS-FLEX.md

@@ -127,8 +127,9 @@ mmcblk0      29.1G
 ```
 
 The ESP is copied from the image, so its FAT UUID (`CBE4-703E`) survived
-the reinstall unchanged. The UEFI boot entries and `BootOrder` were
+the reinstall unchanged. The install itself left the UEFI boot entries
-untouched.
+and `BootOrder` untouched, but Flex's first auto-update changed them.
+See "Flex takes over the UEFI boot order on updates" below.
 
 ## Booting Flex
 
@@ -154,6 +155,57 @@ Two ways:
    With the USB card unplugged, the firmware falls through to `Internal
    eMMC` and boots Flex with no menu.
 
+## Flex takes over the UEFI boot order on updates
+
+Seen 2026-09-27: after the install, Flex booted fine, found an update,
+installed it, and rebooted. The next boot went straight to Flex, and
+getting back to neon took the firmware setup. `efibootmgr` afterwards:
+
+```
+BootOrder: 0004,0005,0001,0000,0003,0002      (was 0005,0001,0000,0003,0002)
+Boot0004* ChromeOS Flex  HD(12,GPT,2877e60b-...)/File(\efi\boot\bootx64.efi)   <- new
+Boot0005* neon           HD(1,GPT,34facff5-...)/File(\EFI\neon\shimx64.efi)
+```
+
+**What does it:** `cros_installer`'s post-install
+(`platform2/installer/efi_boot_management.cc`, strings "Adding EFI Boot
+entry." / "Creating new BootOrder."). It makes sure a "ChromeOS Flex"
+entry for the eMMC's ESP exists and puts it first in `BootOrder`. Nothing
+else in the rootfs writes `BootOrder` (only `cros_installer`,
+`efibootmgr` and fwupd's EFI binary mention it), and no boot-time
+upstart job runs `cros_installer`. It runs:
+- at **install** time, but not under `install-flex-emmc.sh`: the chroot
+  binds `/sys` non-recursively, so `efivarfs` isn't visible and it logs
+  `EFI runtime services not [available]` and skips EFI management.
+  That's why the entry list printed straight after the install was
+  unchanged.
+- **after every auto-update**, when `update_engine` runs post-install
+  on the running Flex system with real EFI access. That's what happened
+  here: the eMMC afterwards had ROOT-A `16640.57.0` (the install) and
+  ROOT-B `16640.61.0` (the update), with KERN-B the higher priority.
+
+So resetting the order once won't last: expect it again after each
+Flex update. No flag to turn it off was found. The binary does have an
+"EFI is buggy continue without EFI management" fallback, but nothing
+user-settable was found that triggers it.
+
+**FydeOS has the same code**: its `cros_installer` includes the same
+`efi_boot_management.cc` and `libefivar`, so FydeOS updates will very
+likely do the same. The FydeOS `fydeos_dualboot` flag is *not* a fix:
+it's for FydeOS's dual-boot mode, where it runs from an image file on
+another OS's partition, and only gates its `update_initrd.sh`.
+
+Ways to live with it (none implemented yet):
+- Fix it by hand when it happens: pick neon from the firmware boot
+  picker (`Esc` at POST), then
+  `sudo efibootmgr -o 0005,0001,0000,0003,0002` (adjust to taste).
+- A small neon systemd oneshot at boot that puts `neon` back first
+  whenever a ChromeOS entry is ahead of it. It still needs one manual
+  `Esc` boot into neon after each ChromeOS update, but then it's fixed
+  for good until the next update.
+- Deleting `Boot0004` doesn't help: the next update recreates it.
+  Neon's GRUB entry chainloads the ESP directly and doesn't need it.
+
 ## Other ChromiumOS-based images: FydeOS
 
 Checked 2026-09-27, by reading the image only (not installed):