doc: add ISO boot documentation, module ref, BusyBox ref, and boot-process section

New files
- doc/index.md: documentation index with one-line summary per doc file
- doc/iso_boot.md: ISO boot parameter reference — details every kernel
  parameter injected (iso-scan/findiso/img_dev/img_loop/iso/live-media),
  which initramfs framework uses it, and parameter value rules
- doc/busybox_perks.md: BusyBox v1.36.1 vs GNU command differences for
  every tool used in initrd scripts (xxd padding, cpio exit code, stat, etc.)
- doc/modules.md: module list from Makefile:718-746 showing which tools
  are BusyBox applets vs standalone binaries

Updated files
- doc/architecture.md: add modules.md cross-reference in module list section
- doc/boot-process.md: add Stage 2b (USB ISO Boot) section covering
  kexec-iso-init.sh flow (Layer 1 initrd compat, Layer 2 loopback.cfg,
  Layer 3 kexec-select-boot), compat markers legend, and parameter injection

Signed-off-by: Thierry Laurion <insurgo@riseup.net>

Author: tlaurion

doc/architecture.md

@@ -87,7 +87,7 @@ Changes to user configuration are persisted by reflashing the ROM (CBFS operatio
 The top-level `Makefile` orchestrates:
 
 - Cross-compiler (`musl-cross-make`, target: `x86_64-linux-musl` or `powerpc64le-linux-musl`)
-- Modules (coreboot, Linux, busybox, GPG, cryptsetup, kexec, LVM2, …)
+- Modules (coreboot, Linux, busybox, GPG, cryptsetup, kexec, LVM2, zstd, … — see [modules.md](modules.md) for the full list)
 - Six CPIO archives assembled into the initrd:
   1. `dev.cpio` — device nodes
   2. `modules.cpio` — kernel modules

doc/boot-process.md

@@ -122,6 +122,97 @@ menu, system info, power off.
 
 ---
 
+## Stage 2b: USB ISO Boot (`kexec-iso-init.sh`)
+
+When booting from an ISO file on USB media, `kexec-iso-init.sh` handles the ISO
+boot flow. It is invoked from the "USB ISO Boot" option in the main menu.
+
+### Flow
+
+1. **Signature verification**: Check for `.sig` or `.asc` detached signature
+2. **Mount ISO**: Mount the ISO file as loopback device at `/boot`
+3. **Layer 1 — initramfs fs compatibility check** (`check_initrd_fs_compat`):
+   Before presenting boot options, verify the ISO's initramfs contains kernel
+   modules for the USB partition's filesystem (ext4/vfat/exfat).  If the initrd
+   can't read the USB filesystem, the kernel won't find the ISO after kexec.
+   - Parsing boot configs for initrd paths (instead of searching the whole ISO)
+   - Unpacking each initrd and checking for required `.ko` files and
+     `modules.builtin`
+   - Each initrd gets its own independent `[OK]` / `[!]` / (blank) marker in
+     `/tmp/kexec_initrd_compat.txt` (the per-initrd flag `initrd_supports_fs` is tracked
+     separately from the global `any_supported` flag, so no initrd is silently
+     skipped)
+   - `[OK]` = initrd has the needed module as `.ko`, has it in
+     `modules.builtin`, or has no `.ko` files at all (minimal initrd with
+     everything built into the kernel — nothing to check against).
+   - `[!]`  = initrd has loadable kernel modules but none for the USB
+     filesystem type.  No built-in assumption — we report what we find.
+   - Read-only filesystems (iso9660/squashfs/udf) and unmapped fstypes skip
+   - All initrds are checked (no early break) so the compat file is complete.
+4. **Layer 2 — loopback.cfg fast path**: If the ISO has a `loopback.cfg`, parse
+   it and resolve GRUB variables (`${iso_path}`, `${isofile}`) to extract the
+   ISO kernel params from loopback entries.
+5. **Boot param injection**: When Layer 2 resolves nothing (no GRUB vars found
+   in loopback.cfg), all common ISO boot methods are injected unconditionally
+   as kernel ADD params so the ISO initrd can pick whichever it supports:
+   - `iso-scan/filename=/$ISO_PATH` — Ubuntu casper, Fedora dracut
+   - `findiso=/$ISO_PATH` — Debian live-boot, NixOS stage-1
+   - `img_dev=/dev/disk/by-uuid/$DEV_UUID` — block device containing the ISO
+   - `img_loop=$ISO_PATH` — loopback file path (relative)
+   - `iso=$DEV_UUID/$ISO_PATH` — UUID/path alternative
+   - `live-media=/dev/disk/by-uuid/$DEV_UUID` — device filter (casper, live-boot)
+   The kernel ignores parameters it doesn't understand.
+   `fromiso=` is intentionally not injected because it conflicts with `findiso=`
+   in Debian live-boot's `check_dev()` — `fromiso` mounts the ISO, then `findiso`
+   looks for the ISO file inside the mounted ISO (not found), unmounts it,
+   leaving orphaned loop devices that get re-scanned → infinite loop.
+   `findiso=` alone covers Debian and NixOS.
+   `live-media-path=` is intentionally not injected because the default differs
+   per distro (`/live` for Debian, `/casper` for Ubuntu/PureOS, `/LiveOS` for
+   Fedora); leaving it unset lets each distro use its own default.
+6. **Layer 3 — kexec-select-boot**: Launch the standard boot menu with `-u`
+   (unique entries, dedup sorted by name).
+
+### Initrd compatibility markers in the boot menu
+
+During Layer 1, `check_initrd_fs_compat` writes per-initrd results to
+`/tmp/kexec_initrd_compat.txt`.  `kexec-select-boot` reads this file and shows
+`[OK]` or `[!]` at the start of each menu line (before the entry name):
+
+| Marker | Meaning | Behavior |
+|--------|---------|----------|
+| `[OK]` | Initrd has the USB fs module (as .ko or modules.builtin) | Boot should work |
+| `[!]`  | Initrd has loadable modules but none for the USB fs type | May fail after kexec |
+| (blank) | Initrd has zero .ko files — can't verify either way | Assume OK (minimal initrd) |
+| (none) | Entry has no initrd (memtest, etc.) | No filesystem dependency |
+
+A `NOTE` (3-second sleep, cannot scroll past) is displayed before the menu
+explaining the legend.  Markers follow `doc/logging.md` accessibility rules:
+text-based, serial-safe, not color-dependent.
+
+### Compatibility note for ext4 and vfat
+
+Initrds with no `.ko` files at all get no marker at all (blank) — we can't
+verify either way, so nothing is displayed.
+
+### Boot param injection
+
+When Layer 2 (loopback.cfg) resolves no GRUB variables, the following
+parameters are injected unconditionally so the ISO initrd can find the USB
+partition and the ISO file after kexec, regardless of which distribution's
+init system it uses:
+
+| Parameter | Example | Used by |
+|-----------|---------|---------|
+| `iso-scan/filename=` | `/ISOs/foo.iso` | Ubuntu casper, Fedora dracut |
+| `findiso=` | `/ISOs/foo.iso` | Debian live-boot, NixOS stage-1 |
+| `img_dev=` | `/dev/disk/by-uuid/UUID` | Block device hint |
+| `img_loop=` | `ISOs/foo.iso` | Loopback path |
+| `iso=` | `UUID/ISOs/foo.iso` | Alternative path |
+| `live-media=` | `/dev/disk/by-uuid/UUID` | Device filter (casper, live-boot) |
+
+---
+
 ## Stage 3: kexec-select-boot
 
 Called from the boot menu. Responsible for final verification and OS handoff.

doc/busybox_perks.md

@@ -0,0 +1,135 @@
+# BusyBox vs GNU: Heads usage reference
+
+Heads initrd scripts run under BusyBox v1.36.1, not GNU coreutils.
+This documents every command usage across Heads scripts and the BusyBox
+adaptations required.
+
+## dd
+
+BusyBox `dd` supports `status=`, `iflag=`, `oflag=` the same as GNU.
+
+**Usage in Heads**:
+```bash
+dd if="$file" bs=6 count=1 status=none   # kexec-iso-init.sh:
+dd bs=1 count=1 status=none              # unpack_initramfs.sh:38
+dd bs="$segment_end" count=1 status=none # unpack_initramfs.sh:101
+```
+
+## xxd
+
+**BusyBox quirk**: `xxd -p` pads the last line to 60 columns with spaces.
+GNU xxd does not pad.
+
+**Usage in Heads**:
+```bash
+# Good — strips padding:
+next_byte="$(dd bs=1 count=1 status=none | xxd -p | tr -d '\n ')"  # unpack_initramfs.sh:38
+magic="$(dd if="$f" bs=6 count=1 status=none | xxd -p | tr -d '\n ')" # unpack_initramfs.sh:68
+
+# Reverse — needs fold workaround (from etc/functions.sh:2701):
+fold -w 60 | xxd -p -r
+```
+
+## cpio
+
+**BusyBox quirk**: Stops at first TRAILER. GNU reads past it and exits 2.
+
+**Heads pattern**: `cpio -i -d "${CPIO_ARGS[@]}" 2>/dev/null || true`
+The `|| true` handles GNU's exit 2 on multi-segment archives.
+
+For multi-segment extraction (`unpack_initramfs.sh:94-106`), the TRAILER offset
+is pre-computed and dd limits cpio's input to exactly one segment, so both
+BusyBox and GNU behave identically.
+
+## grep
+
+**BusyBox**: no `-a` flag, but treats binary as text by default.
+
+**Heads usage**: `grep -F -a -b -o "TRAILER!!!"` at `unpack_initramfs.sh:78`.
+The `-a` can be omitted on BusyBox; harmless on GNU (no-op).
+
+**Heads pattern**: `grep -F -b -o "TRAILER!!!" "$file" 2>/dev/null | head -1 | cut -d: -f1 || true`
+
+## stat
+
+Identical for `stat -c %s FILE`.
+
+**Usage in Heads**:
+```bash
+orig_size="$(stat -c %s "$unpack_archive")"        # unpack_initramfs.sh:127
+rest_size="$(stat -c %s "$rest_archive")"            # unpack_initramfs.sh:128
+rest_size="$(stat -c %s "$next_archive" 2>/dev/null || echo 0)" # unpack_initramfs.sh:147
+```
+
+## find
+
+**Usage in Heads** (all supported by BusyBox):
+```bash
+find "$dir" -name "*.ko*" -type f 2>/dev/null | head -1  # kexec-iso-init.sh
+find "$dir" -name '*.cfg' -type f 2>/dev/null            # kexec-iso-init.sh
+find "$dir" -name "*.ko*" 2>/dev/null | grep -q "ext4"    # kexec-iso-init.sh
+```
+
+## gunzip / gzip / zcat
+
+Identical. Used via pipe in segment decompression:
+```bash
+gunzip | unpack_cpio   # unpack_initramfs.sh:111
+```
+
+## unxz / xzcat
+
+Identical:
+```bash
+unxz | unpack_cpio    # unpack_initramfs.sh:115
+```
+
+## zstd / zstd-decompress
+
+**Standalone binary** compiled at `build/x86/zstd-1.5.5/programs/zstd-decompress`
+and included in the initrd via `Makefile:745` (`CONFIG_ZSTD`). Not a BusyBox
+applet, but available in all boards with `CONFIG_ZSTD=y`.
+
+Usage via pipe (`unpack_initramfs.sh:119`):
+```bash
+zstd-decompress -d < input.zst   # reads stdin, writes stdout
+```
+
+**Current code**: `(zstd-decompress -d 2>/dev/null || zstd -d 2>/dev/null || true) | unpack_cpio`
+— should work if `CONFIG_ZSTD=y` in the board config.
+
+## sed
+
+Identical for all patterns used in Heads:
+```bash
+sed 's|^/dev/||'          # kexec-iso-init.sh (path stripping)
+sed 's/^append //'         # kexec-iso-init.sh (param extraction)
+sed 's/^initrd //'         # kexec-iso-init.sh (field extraction)
+sed "s|\${$var}|$val|g"    # kexec-iso-init.sh (GRUB var resolution)
+```
+
+## awk
+
+BusyBox awk is minimal but sufficient for Heads usage:
+```bash
+awk -v dev="$dev" 'index($1, dev) == 1 { print $3; exit }' /proc/mounts
+awk '{print $2}' /proc/mounts
+```
+
+## cut / head / tr / sort / uniq / fold / basename / dirname / readlink
+
+All identical for Heads usage. No special BusyBox workarounds needed.
+
+## cat / mv / rm / mkdir / mktemp / printf / wc / xargs / echo
+
+All identical. No BusyBox workarounds needed.
+
+## Summary of required BusyBox workarounds
+
+| Command | Workaround | Where |
+|---------|------------|-------|
+| `xxd -p` | `tr -d '\n '` strips 60-col padding | `unpack_initramfs.sh:38,68` |
+| `xxd -p -r` | `fold -w 60 \| xxd -p -r` | `etc/functions.sh:2701` |
+| `cpio` trailing data exit | `|| true` swallows GNU exit 2 | `unpack_initramfs.sh:52,101` |
+| `grep -a` | Omit or keep (no-op on both) | `unpack_initramfs.sh:78` |
+| `zstd` not available | `(zstd-decompress -d \|\| zstd -d \|\| true)` fails silently | `unpack_initramfs.sh:119` |

doc/index.md

@@ -0,0 +1,16 @@
+# Heads documentation index
+
+Quick reference — read the relevant doc when working on a topic.
+
+| File | What it covers |
+|------|----------------|
+| `architecture.md` | System architecture: coreboot → kernel → initrd, build system, config hierarchy |
+| `boot-process.md` | Boot flow stages, ISO boot layers (Layer 1/2/3), [OK]/[!] marker legend |
+| `busybox_perks.md` | GNU vs BusyBox command differences for all tools used in initrd scripts |
+| `docker.md` | Docker-based build environment |
+| `logging.md` | Log levels (STATUS, WARN, NOTE, INFO, DEBUG, TRACE) usage conventions |
+| `modules.md` | Available tools: which are BusyBox applets vs standalone binaries |
+| `security-model.md` | TPM, measured boot, trust chain |
+| `tpm.md` | TPM 1.2 and 2.0 operations |
+| `ux-patterns.md` | User interaction patterns (whiptail, CLI menu, confirm dialogs) |
+| `iso_boot.md` | ISO boot parameter reference — what each kernel param does and which framework uses it |

doc/iso_boot.md

@@ -0,0 +1,95 @@
+# ISO Boot Parameter Reference
+
+## Design
+
+Heads kexec-boots ISO files from USB by injecting kernel command-line
+parameters that tell the target initramfs where to find the ISO on the
+USB drive.  The parameters are designed to be universal — every common
+Linux distribution's initramfs framework finds the ISO via at least one
+of the injected parameters.
+
+## Universal parameter set
+
+The following parameters are injected unconditionally.  Each specifies
+the ISO location in a format that a different initramfs framework
+understands.  Unrecognised parameters are harmless — the kernel passes
+them to userspace and each initramfs ignores what it doesn't understand.
+
+```
+iso-scan/filename=/$ISO_PATH
+findiso=/$ISO_PATH
+img_dev=/dev/disk/by-uuid/$DEV_UUID
+img_loop=$ISO_PATH
+iso=$DEV_UUID/$ISO_PATH
+live-media=/dev/disk/by-uuid/$DEV_UUID
+```
+
+Where:
+- `ISO_PATH` — path to the ISO file relative to the USB device root
+  (e.g. `ISOs/debian-live-13.2.0-amd64-xfce.iso`)
+- `DEV_UUID` — UUID of the USB block device
+- `$ISO_PATH` resolves to the relative path (e.g. `ISOs/file.iso`)
+- `/$ISO_PATH` resolves to the absolute path within a mounted device
+  (e.g. `/ISOs/file.iso`)
+- `$DEV_UUID` resolves to the UUID string
+- `/dev/disk/by-uuid/$DEV_UUID` resolves to a stable block device path
+
+## Framework coverage
+
+| Param | live-boot (Debian) | casper (Ubuntu) | dracut (Fedora) | NixOS stage-1 |
+|-------|--------------------|-----------------|----------------|---------------|
+| `iso-scan/filename=` | — | ✓ scans devices | ✓ scans devices | — |
+| `findiso=` | ✓ scans devices | — | — | ✓ scans devices |
+| `img_dev=` + `img_loop=` | — | — | — | — |
+| `live-media=` | ✓ device filter | ✓ device filter | — | — |
+
+### live-boot (Debian, Tails, Devuan)
+
+`findiso=` scans all block devices, mounts each, and checks for
+`${mountpoint}/$FINDISO` — so the value must be a relative path from
+the device root.
+
+`live-media=` narrows the device scan to a specific device.
+
+Squashfs lives in `/live/` on the ISO.
+
+### casper (Ubuntu, PureOS)
+
+`iso-scan/filename=` scans all block devices and looks for the ISO at
+the given relative path.  `live-media=` specifies the block device.
+`live-media-path` defaults to `casper` and does not need to be
+specified.
+
+Squashfs lives in `/casper/` on the ISO.
+
+### dracut/dmsquash-live (Fedora, RHEL, Kicksecure)
+
+`iso-scan/filename=` is supported identically to casper — it scans
+block devices and loop-mounts the ISO.  `root=live:*` is the primary
+specification (LABEL, UUID, CDLABEL, or `/path/file.iso`).
+
+Squashfs lives in `/LiveOS/` by default, but Kicksecure overrides to
+`rd.live.dir=live`.
+
+### NixOS stage-1
+
+`findiso=` scans block devices identically to Debian live-boot —
+mounts each device and checks for `${mountpoint}$isoPath`.
+
+## Parameter value rules
+
+1. **`iso-scan/filename=/$ISO_PATH`** — relative path prefixed with `/`
+   (absolute within the mounted filesystem).  The initramfs mounts each
+   block device and checks for the file at that path.
+
+2. **`findiso=/$ISO_PATH`** — same format as `iso-scan/filename=`.
+   The initramfs scans block devices for the file.
+
+3. **`img_dev=/dev/disk/by-uuid/$DEV_UUID`** — block device path only
+   (no file path appended).
+
+4. **`img_loop=$ISO_PATH`** — relative path without `/` prefix.
+
+5. **`live-media=/dev/disk/by-uuid/$DEV_UUID`** — block device path
+   only (no file path appended).  This is NOT a file path — the
+   initramfs uses it to identify which device to scan.