# ISO Build Rules

## Verify package names before use

ISO builds take 30–60 minutes. A wrong package name wastes an entire build cycle.

**Rule: before adding any Debian package name to the ISO config, verify it exists and check its file list.**

Use one of:
- `https://packages.debian.org/bookworm/<package-name>` — existence + description
- `https://packages.debian.org/bookworm/amd64/<package-name>/filelist` — exact files installed
- `apt-cache show <package>` inside a Debian bookworm container

This applies to:
- `iso/builder/config/package-lists/*.list.chroot`
- Any package referenced in bootloader configs, hooks, or overlay scripts

## Bootloader sync rule

The ISO has two independent bootloader configs that must be kept in sync manually:

| File | Used by |
|------|---------|
| `config/bootloaders/grub-efi/grub.cfg` | UEFI (all modern servers) |
| `config/bootloaders/isolinux/live.cfg.in` | CSM / legacy BIOS (syslinux) |

live-build does NOT derive one from the other. Any new boot entry, kernel parameter
change, or new mode added to one file must be manually mirrored in the other.

**Canonical entry list** (both files must have all of these):

| Label | Key params |
|-------|-----------|
| normal (default) | `nomodeset bee.nvidia.mode=normal` + full param set |
| load to RAM | `toram nomodeset bee.nvidia.mode=normal` + full param set |
| GSP=off | `nomodeset bee.nvidia.mode=gsp-off` + full param set |
| KMS | no `nomodeset`, `bee.nvidia.mode=normal` + full param set |
| KMS + GSP=off | no `nomodeset`, `bee.nvidia.mode=gsp-off` + full param set |
| fail-safe | `nomodeset bee.nvidia.mode=gsp-off noapic noapm nodma nomce nolapic nosmp` |

**Full standard param set** (append after `@APPEND_LIVE@` / `nomodeset` flags):
```
net.ifnames=0 biosdevname=0 mitigations=off transparent_hugepage=always
numa_balancing=disable pcie_aspm=off intel_idle.max_cstate=1 processor.max_cstate=1
nowatchdog nosoftlockup
```
(fail-safe is the exception — it deliberately uses minimal params.)

**Historical note:** `grub-pc/` was mistakenly used instead of `grub-efi/` until v8.25.
live-build reads `config/bootloaders/grub-efi/` for UEFI because the build is
configured with `--bootloaders "grub-efi,syslinux"`. Directory `grub-pc` is ignored.

## Memtest rule

Do not assume live-build's built-in memtest integration is sufficient for `bee`.
We already tried that path and regressed again on 2026-04-01: `lb binary_memtest`
ran, but the final ISO still lacked memtest binaries and menu entries.

For this project, memtest is accepted only when the produced ISO actually
contains all of the following:

- `boot/memtest86+x64.bin`
- `boot/memtest86+x64.efi`
- a memtest entry in `boot/grub/grub.cfg`
- a memtest entry in `isolinux/live.cfg`

Rules:

- Keep explicit post-build memtest validation in `build.sh`.
- Treat ISO reader success as a separate prerequisite from memtest content.
  If the reader cannot list or extract from the ISO, that is a validator
  failure, not proof that memtest is missing.
- If built-in integration does not produce the artifacts above, use a
  deterministic project-owned copy/extract step instead of hoping live-build
  will "start working".
- Do not switch back to built-in-only memtest without fresh build evidence from
  a real ISO.
- If you reference memtest files manually, verify the exact package file list
  first for the target Debian release.

Known bad loops for this repository:

- Do not retry built-in-only memtest without new evidence. We already proved
  that `lb binary_memtest` can run while the final ISO still has no memtest.
- Do not assume fixing memtest file names is enough. Correct names did not fix
  the final artifact path.
- Do not assume `chroot/boot/` contains memtest payloads at the time hooks run.
- Do not assume source `grub.cfg` / `live.cfg.in` are the final writers of ISO
  bootloader configs.
- Do not assume the current `config/hooks/normal/9100-memtest.hook.binary`
  timing is late enough to patch final `binary/boot/grub/grub.cfg` or
  `binary/isolinux/live.cfg`; logs from 2026-04-01 showed those files were not
  present yet when the hook executed.
- Do not treat a validator warning as ground truth until you have confirmed the
  ISO reader actually succeeded. On 2026-04-01 we misdiagnosed another memtest
  regression because the final ISO was correct but the validator produced a
  false negative.
