From a2fbd4e4625f1629e245c7023e063afd0f6d2c4e Mon Sep 17 00:00:00 2001
From: DevomB <Devom.hb@yahoo.com>
Date: Fri, 2 Oct 2026 02:21:17 -0700
Subject: [PATCH 1/3] Cut the build system's comments to one line

The stamp machinery in common.sh, the stages, every recipe, the service
scripts and s6 run files, the guest checks, the config lists and the
patch-set READMEs lose their stacked comments, history and rhetoric. Each
recipe drops its two-line "a stage 04 recipe, sourced by..." header.
Wrong comments are corrected: bc's shim name, shadow's man pages, the
boot-success re-arm file, testctl's key list, and the glibc README's claim
that the whole patch directory is fingerprinted.

Comments only. bash's declare -f output of every changed script is
unchanged and no heredoc body moves, so no recipe or stage function
re-fingerprints. Files hashed whole still move their step: the service
scripts, run files and sysctl file the late services step, the guest
checks the tests step, the allowlists stage 06's rootfs step, and the
kernel checker's accepted list its check step alone.
---
 build/config/artifact-accepted.txt            |  7 +-
 build/config/capability-allowlist.txt         |  4 +-
 build/config/hardening-exceptions.txt         |  8 +-
 build/config/hardening.env                    | 11 +--
 build/config/kernel/checker-accepted.txt      | 13 +--
 build/config/licence-exceptions.txt           |  4 +-
 build/config/setuid-allowlist.txt             |  9 +-
 .../config/sysctl.d/99-kryptik-hardening.conf | 11 +--
 build/guest-tests/icmp-echo.py                |  6 +-
 build/lib/common.sh                           | 92 +++++--------------
 build/lib/kconfig-check.sh                    | 12 +--
 build/patches/dwl-0.8/README.md               | 26 +++---
 build/patches/gawk-5.3.0/README.md            |  8 +-
 build/patches/glibc-2.40/README.md            | 20 ++--
 build/patches/iputils-20250605/README.md      |  6 +-
 build/patches/readline-8.3/README.md          |  4 +-
 build/patches/shadow-4.16.0/README.md         | 10 +-
 build/patches/tar-1.35/README.md              |  2 +-
 build/patches/zlib-1.3.1/README.md            |  2 +-
 build/recipes/bc.sh                           |  4 +-
 build/recipes/binutils.sh                     | 10 +-
 build/recipes/bzip2.sh                        |  6 +-
 build/recipes/ca-bundle.sh                    |  6 +-
 build/recipes/cmake.sh                        |  2 -
 build/recipes/compiler-check.sh               |  6 +-
 build/recipes/console.sh                      |  7 +-
 build/recipes/coreutils.sh                    |  2 -
 build/recipes/cryptsetup.sh                   |  5 +-
 build/recipes/desktop.sh                      |  9 +-
 build/recipes/dhcpcd.sh                       |  2 -
 build/recipes/dnsmasq.sh                      |  8 +-
 build/recipes/dwl.sh                          | 14 +--
 build/recipes/e2fsprogs.sh                    |  2 -
 build/recipes/efiboot.sh                      |  7 +-
 build/recipes/elfutils.sh                     |  2 -
 build/recipes/eudev.sh                        |  2 -
 build/recipes/firmware.sh                     | 13 +--
 build/recipes/fonts.sh                        |  6 +-
 build/recipes/gawk.sh                         |  7 +-
 build/recipes/gcc.sh                          | 26 ++----
 build/recipes/gdbm.sh                         |  2 -
 build/recipes/glibc.sh                        | 28 ++----
 build/recipes/groff.sh                        |  7 +-
 build/recipes/hardened-malloc.sh              |  8 +-
 build/recipes/havoc.sh                        |  2 -
 build/recipes/hwdata.sh                       |  2 -
 build/recipes/iana-etc.sh                     |  2 -
 build/recipes/inetutils.sh                    |  7 +-
 build/recipes/installer.sh                    |  5 +-
 build/recipes/iproute2.sh                     |  2 -
 build/recipes/iputils.sh                      | 10 +-
 build/recipes/iw.sh                           |  5 +-
 build/recipes/json-c.sh                       | 12 +--
 build/recipes/kbd.sh                          |  5 +-
 build/recipes/kryptikd.sh                     | 21 +----
 build/recipes/libaio.sh                       |  2 -
 build/recipes/libcap.sh                       |  2 -
 build/recipes/libdrm.sh                       |  2 -
 build/recipes/libinput.sh                     |  2 -
 build/recipes/libxkbcommon.sh                 |  2 -
 build/recipes/licences.sh                     | 24 ++---
 build/recipes/locales.sh                      |  6 +-
 build/recipes/lvm2.sh                         | 11 +--
 build/recipes/lynx.sh                         |  2 -
 build/recipes/man-db.sh                       |  3 -
 build/recipes/meson.sh                        |  5 +-
 build/recipes/netzone.sh                      |  5 +-
 build/recipes/ninja.sh                        |  2 -
 build/recipes/openssh.sh                      |  7 +-
 build/recipes/openssl.sh                      |  5 +-
 build/recipes/perl.sh                         | 13 +--
 build/recipes/pkgconf.sh                      |  5 +-
 build/recipes/python.sh                       |  9 +-
 build/recipes/readline.sh                     |  7 +-
 build/recipes/s6.sh                           |  8 +-
 build/recipes/seatd.sh                        |  2 -
 build/recipes/shadow.sh                       |  8 +-
 build/recipes/tar.sh                          |  5 +-
 build/recipes/tests.sh                        |  9 +-
 build/recipes/updater.sh                      |  2 -
 build/recipes/wayland.sh                      |  2 -
 build/recipes/wlroots.sh                      |  5 +-
 build/recipes/wpa-supplicant.sh               |  9 +-
 build/recipes/xz.sh                           |  2 -
 build/recipes/zlib.sh                         |  2 -
 build/recipes/zstd.sh                         |  2 -
 build/service-scripts/ask.sh                  | 17 ++--
 build/service-scripts/boot-smoke.sh           | 24 ++---
 build/service-scripts/devices.sh              | 11 +--
 build/service-scripts/eudev-trigger.sh        |  3 +-
 build/service-scripts/kryptikd-check.sh       |  3 +-
 build/service-scripts/watchdog.sh             |  6 +-
 build/services/getty-tty1/run                 |  5 +-
 build/services/getty-tty2/run                 |  4 +-
 build/services/kryptikd-serve/run             |  3 +-
 build/services/net-zone/run                   |  6 +-
 build/services/watchdog/run                   |  4 +-
 build/stages/00-host-check.sh                 |  6 +-
 build/stages/01-toolchain.sh                  | 45 +++------
 build/stages/02-temp-tools.sh                 |  8 +-
 build/stages/05-kernel.sh                     | 69 ++++----------
 101 files changed, 245 insertions(+), 658 deletions(-)

diff --git a/build/config/artifact-accepted.txt b/build/config/artifact-accepted.txt
index 581b6fea..60a14f35 100644
--- a/build/config/artifact-accepted.txt
+++ b/build/config/artifact-accepted.txt
@@ -1,8 +1,5 @@
-# Findings of tools/check-artifact-hardening.sh that the image keeps, each with
-# its reason: `FINDING PATH # why`, or `RPATH PATH RPATH # why`, since an RPATH
-# entry accepts one rpath. PATH and RPATH are globs on the object's path in the
-# image and on its rpath. A finding not listed here fails --strict, and so does
-# an entry that no longer matches anything.
+# Findings of tools/check-artifact-hardening.sh the image keeps, as globs: `FINDING PATH # why`
+# or `RPATH PATH RPATH # why`. --strict fails on an unlisted finding and on a stale entry.
 
 NO-CET  usr/bin/kryptikd                        # stable rustc marks nothing for CET, nor does the std it links
 NO-CET  usr/bin/kryptik-wlproxy                 # the same
diff --git a/build/config/capability-allowlist.txt b/build/config/capability-allowlist.txt
index f7c716c2..11db5e18 100644
--- a/build/config/capability-allowlist.txt
+++ b/build/config/capability-allowlist.txt
@@ -1,4 +1,2 @@
-# Files allowed to carry file capabilities (security.capability) in a Kryptik
-# image; stage 06 removes them from every other file in its root
-# (tools/audit-setuid.sh --strip). Nothing in the image needs one yet.
+# Files allowed file capabilities; stage 06 strips the rest (tools/audit-setuid.sh --strip).
 #   /absolute/path   # justification
diff --git a/build/config/hardening-exceptions.txt b/build/config/hardening-exceptions.txt
index 2b383062..ab4c0327 100644
--- a/build/config/hardening-exceptions.txt
+++ b/build/config/hardening-exceptions.txt
@@ -1,6 +1,4 @@
-# Packages exempted from part of the hardening flag set:
-#   <package>  <flag-to-drop>  # justification
-# An entry without a justification fails the build. Say what breaks and what
-# you tried; exceptions are meant to be removed, not accumulated.
+# Packages exempted from a hardening flag; an entry without a justification fails the build.
+#   <package>  <flag-to-drop>  # what breaks, and what was tried
 
-glibc  -D_FORTIFY_SOURCE=3  # glibc DEFINES the fortify machinery; fortifying it against itself fails to build
+glibc  -D_FORTIFY_SOURCE=3  # glibc provides the fortify machinery; fortifying it against itself fails to build
diff --git a/build/config/hardening.env b/build/config/hardening.env
index 239ab445..4f30bb3a 100644
--- a/build/config/hardening.env
+++ b/build/config/hardening.env
@@ -1,10 +1,6 @@
-# Hardening flags for the target packages; docs/hardening.md has the reasons.
-# Loaded by stage 04 only: stages 01 and 02 build the compiler that implements
-# these flags, and set no flags at all.
+# Hardening flags for the target packages, loaded by stage 04; docs/hardening.md has the reasons.
 
-# No -fPIE or -pie: GCC is built with --enable-default-pie, so executables are
-# PIE anyway, and -pie links Scrt1.o into shared libraries, which then fail on
-# an undefined main.
+# No -fPIE or -pie: GCC defaults to PIE, and -pie breaks shared libraries (Scrt1.o, undefined main).
 
 # _FORTIFY_SOURCE needs -O1 or more; -O2 is the tested level.
 KRYPTIK_OPT="-O2"
@@ -29,6 +25,5 @@ export CFLAGS="${KRYPTIK_OPT} ${KRYPTIK_CFLAGS_HARDENING}"
 export CXXFLAGS="${KRYPTIK_OPT} ${KRYPTIK_CFLAGS_HARDENING}"
 export LDFLAGS="${KRYPTIK_LDFLAGS_HARDENING}"
 
-# Packages exempted from some flags. Each needs a justification, which
-# validate_hardening_exceptions in build/lib/common.sh enforces.
+# Per-package flag exemptions, each with the justification validate_hardening_exceptions enforces.
 KRYPTIK_HARDENING_EXCEPTIONS="build/config/hardening-exceptions.txt"
diff --git a/build/config/kernel/checker-accepted.txt b/build/config/kernel/checker-accepted.txt
index adac4c2e..f9995dfe 100644
--- a/build/config/kernel/checker-accepted.txt
+++ b/build/config/kernel/checker-accepted.txt
@@ -1,13 +1,8 @@
-# kernel-hardening-checker failures on the resolved config and the shipped
-# command line that Kryptik accepts, each with its reason:
+# kernel-hardening-checker failures Kryptik accepts, read by tools/check-kernel-hardening.sh:
 #   <kconfig|cmdline|sysctl>  <option>   # <why it stays>
-# tools/check-kernel-hardening.sh fails on an unlisted failure or an entry
-# without a reason, and reports an entry that now passes so it can go.
-# The checker's decision column names who recommends a setting: kspp (Kernel
-# Self-Protection Project), clipos, grsec, maintainer, a13xp0p0v (its author).
 
 # --- the toolchain is GCC (ADR-001) --------------------------------------------
-kconfig  CONFIG_CFI_CLANG         # kernel control-flow integrity needs Clang; hardening.fragment records why that split is not adopted yet
+kconfig  CONFIG_CFI_CLANG         # kernel control-flow integrity needs Clang; hardening.fragment says why the kernel is built with GCC
 kconfig  CONFIG_CFI_PERMISSIVE    # follows CFI_CLANG
 kconfig  CONFIG_CFI_AUTO_DEFAULT  # follows CFI_CLANG
 cmdline  cfi                      # cfi=kcfi selects the Clang CFI mode; no kernel CFI is built
@@ -18,7 +13,7 @@ kconfig  CONFIG_MODULES           # drivers that need firmware load after the ve
 
 # --- the desktop and the console need them ------------------------------------------
 kconfig  CONFIG_VT                # the framebuffer console and the tty1 login (boot.fragment)
-kconfig  CONFIG_KCMP              # DRM selects it (drivers/gpu/drm/Kconfig) and the compositor needs DRM; the "is not set" line for it was ignored, so it is a decision here rather than a dead line there
+kconfig  CONFIG_KCMP              # DRM selects it (drivers/gpu/drm/Kconfig), and the compositor needs DRM
 
 # --- ADR-007: Landlock and seccomp, no SELinux ------------------------------------
 kconfig  CONFIG_SECURITY_SELINUX  # the checker's author prefers SELinux; Kryptik compiles no MAC framework it loads no policy into (ADR-007)
@@ -29,4 +24,4 @@ kconfig  CONFIG_LSM_MMAP_MIN_ADDR # exists only with SELinux; CONFIG_DEFAULT_MMA
 kconfig  CONFIG_KALLSYMS          # a stack trace without symbols cannot be acted on; kernel.kptr_restrict=2 and kernel.dmesg_restrict=1 (build/config/sysctl.d) keep them from users, and KALLSYMS_ALL is off
 
 # --- the IOMMU is already on and strict by default -------------------------------
-cmdline  iommu                    # iommu=force is clipos's belt over the same braces: INTEL_IOMMU_DEFAULT_ON, AMD_IOMMU and IOMMU_DEFAULT_DMA_STRICT turn it on, strict, wherever there is one
+cmdline  iommu                    # INTEL_IOMMU_DEFAULT_ON, AMD_IOMMU and IOMMU_DEFAULT_DMA_STRICT already turn it on, strict, wherever there is one
diff --git a/build/config/licence-exceptions.txt b/build/config/licence-exceptions.txt
index f9f7d4dc..fbc5ba30 100644
--- a/build/config/licence-exceptions.txt
+++ b/build/config/licence-exceptions.txt
@@ -1,7 +1,5 @@
-# Sources the image carries no licence file for, each with its reason:
+# Sources the image carries no licence file for; tools/check-image-licences.sh fails on any other.
 #   name   # why
-# Stage 04 installs every other source's (s_licences), and acceptance fails
-# on a source without them (tools/check-image-licences.sh).
 glibc-fhs-patch   # a patch to glibc, whose licence files cover it
 linux-hardened    # a patch to linux, whose COPYING and LICENSES/ cover it
 cmake-bin         # the build's own cmake, which stage 06 leaves out of the root
diff --git a/build/config/setuid-allowlist.txt b/build/config/setuid-allowlist.txt
index 8a60d070..46545ada 100644
--- a/build/config/setuid-allowlist.txt
+++ b/build/config/setuid-allowlist.txt
@@ -1,8 +1,5 @@
-# Binaries allowed to be setuid or setgid in a Kryptik image; stage 06 takes
-# the bit off every other file in its root (tools/audit-setuid.sh --strip).
+# Binaries allowed setuid or setgid; stage 06 strips the rest (tools/audit-setuid.sh --strip).
 #   /absolute/path   # why it stays, and what would remove it
-# Privilege transitions go through kryptikd, where they are auditable. A file
-# capability is no way round this list: it needs an entry in
-# capability-allowlist.txt, and nothing has one.
+# A file capability is no way round this list: it needs an entry in capability-allowlist.txt.
 /usr/bin/su       # the one way from a login to root, for an administrator and for the test drivers (vm-drive.py su:); goes when kryptikd brokers a root session
-/usr/bin/passwd   # a user changes their own password; goes when a kryptikd verb does that, which weighs a new root-side parser of /etc/shadow against this one binary
+/usr/bin/passwd   # a user changes their own password; goes when a kryptikd verb does that, at the cost of a root-side /etc/shadow parser
diff --git a/build/config/sysctl.d/99-kryptik-hardening.conf b/build/config/sysctl.d/99-kryptik-hardening.conf
index 7ea8a926..c65cd5f5 100644
--- a/build/config/sysctl.d/99-kryptik-hardening.conf
+++ b/build/config/sysctl.d/99-kryptik-hardening.conf
@@ -5,19 +5,17 @@ kernel.kptr_restrict = 2
 kernel.dmesg_restrict = 1
 kernel.printk = 3 3 3 3
 kernel.perf_event_paranoid = 3
-# (No kernel.kexec_load_disabled: CONFIG_KEXEC is off, so the key does not exist.)
+# No kernel.kexec_load_disabled: CONFIG_KEXEC is off, so the key does not exist.
 
 # --- ptrace: disabled entirely after boot ---
 kernel.yama.ptrace_scope = 3
 
-# --- eBPF ---
-# Nothing: CONFIG_BPF_SYSCALL is off (kernel/hardening.fragment), so
-# kernel.unprivileged_bpf_disabled and net.core.bpf_jit_harden do not exist.
+# --- eBPF: not built (CONFIG_BPF_SYSCALL is off), so its sysctls do not exist ---
 
 # --- ASLR: maximum entropy on x86-64 ---
 kernel.randomize_va_space = 2
 vm.mmap_rnd_bits = 32
-# (No vm.mmap_rnd_compat_bits: no 32-bit programs, CONFIG_IA32_EMULATION is off.)
+# No vm.mmap_rnd_compat_bits: no 32-bit programs, CONFIG_IA32_EMULATION is off.
 
 # --- userfaultfd, a heap-grooming primitive, is not built; its sysctl does not exist ---
 
@@ -42,5 +40,4 @@ net.ipv4.icmp_echo_ignore_broadcasts = 1
 net.ipv6.conf.all.accept_redirects = 0
 net.ipv6.conf.all.accept_source_route = 0
 
-# --- core dumps, which could hold zone secrets, are not built (CONFIG_COREDUMP is off):
-# no kernel.core_pattern exists; fs.suid_dumpable above is the belt to that brace ---
+# --- core dumps could hold zone secrets: CONFIG_COREDUMP is off; suid_dumpable is a backstop ---
diff --git a/build/guest-tests/icmp-echo.py b/build/guest-tests/icmp-echo.py
index 55742d35..100d2b88 100644
--- a/build/guest-tests/icmp-echo.py
+++ b/build/guest-tests/icmp-echo.py
@@ -3,9 +3,7 @@
 
     icmp-echo.py HOST [TIMEOUT]
 """
-# The ICMP datagram socket needs no privilege (net.ipv4.ping_group_range, set
-# by kryptikd in the zone). ping uses it too; the reachability checks use this
-# instead, so a broken ping fails only the ping checks.
+# Not ping itself, so a broken ping fails only the ping checks.
 import socket
 import struct
 import sys
@@ -31,7 +29,7 @@
         s.recvfrom(1500)
         print("PONG", host)
         sys.exit(0)
-    except Exception as e:  # noqa: BLE001 - the reason is the point
+    except Exception as e:  # noqa: BLE001 - its text is the reason printed
         last = str(e)
     finally:
         try:
diff --git a/build/lib/common.sh b/build/lib/common.sh
index 083afbbf..17a9a93d 100644
--- a/build/lib/common.sh
+++ b/build/lib/common.sh
@@ -24,7 +24,7 @@ err()   { printf '%s fail%s %s\n' "$C_RED" "$C_RST" "$*" >&2; }
 die()   { err "$*"; exit 1; }
 dim()   { printf '%s%s%s\n' "$C_DIM" "$*" "$C_RST"; }
 
-# Report the failing line rather than a bare non-zero exit.
+# Report the failing line, not a bare non-zero exit.
 _kryptik_trap() {
     local ec=$? line=${BASH_LINENO[0]} src=${BASH_SOURCE[1]:-?}
     err "aborted at ${src}:${line} (exit ${ec})"
@@ -32,8 +32,7 @@ _kryptik_trap() {
 }
 trap _kryptik_trap ERR
 
-# nproc, capped at one job per 1.5 GB of RAM, or GCC and glibc builds meet the
-# OOM killer ("internal compiler error: Killed"). KRYPTIK_JOBS overrides it.
+# nproc, capped at one job per 1.5 GB of RAM, or GCC and glibc builds meet the OOM killer.
 kryptik_default_jobs() {
     local cpus mem_kb mem_gb by_mem
     cpus="$(nproc 2>/dev/null || echo 1)"
@@ -61,26 +60,20 @@ sha256_of_stdin() {
     fi
 }
 
-# licence_members TARBALL [ERE]: a source tarball's licence files, at its top
-# or in its doc/ (attr and acl keep them there), which tools/scan-licenses.sh
-# reads and stage 04 installs, and the members matching ERE too, from one
-# listing. The pattern is local, so it is part of the fingerprint of any step
-# that calls this.
+# licence_members TARBALL [ERE]: the licence files at a tarball's top or in doc/, and ERE matches.
 licence_members() {
+    # Local, so the pattern is in the fingerprint of every step that calls this.
     local re='^[^/]+/(doc/)?(COPYING[^/]*|Copying|COPYRIGHT[^/]*|LICEN[CS]E[^/]*|License|Artistic|NOTICE)$'
     [[ -z "${2:-}" ]] || re="${re}|${2}"
     tar -tf "$1" 2>/dev/null | grep -E "$re" || true
 }
 
-# header_notices TARBALL MEMBER...: the notice at the head of each member, for
-# a source that ships no licence file. A notice runs from the first Copyright
-# line to the line ending in "SOFTWARE.", where the MIT text ends, and loses
-# its comment marks. awk reads to the end, since stopping early would kill
-# tar with SIGPIPE, and prints nothing for a notice that never ends.
+# header_notices TARBALL MEMBER...: each member's MIT notice, for sources with no licence file.
 header_notices() {
     local tarball="$1" m text
     shift
     for m in "$@"; do
+        # From Copyright to "SOFTWARE.", comment marks stripped; awk reads on, or tar would SIGPIPE.
         text="$(tar -xOf "$tarball" "$m" | awk '
             done { next }
             /Copyright/ { on = 1 }
@@ -92,8 +85,7 @@ header_notices() {
     done
 }
 
-# unpack TARBALL TOPDIR [NAME]: extract a source into the stage's BUILDDIR, as
-# NAME if given, replacing any earlier copy; print its path.
+# unpack TARBALL TOPDIR [NAME]: extract afresh into BUILDDIR, as NAME if given; print the path.
 unpack() {
     local tarball="$1" srcdir="$2" destname="${3:-}"
     local dir="${BUILDDIR}/${destname:-$srcdir}"
@@ -106,10 +98,7 @@ unpack() {
     printf '%s' "$dir"
 }
 
-# Stages 01-03 run on the host and install into ${KRYPTIK_WORK}/sysroot; stages
-# 04 and 05 run inside the chroot, where the sysroot is /. A KRYPTIK_WORK path
-# may not exist in there, and installing to it would build a nested tree.
-# KRYPTIK_DESTDIR is the DESTDIR= value: empty inside the chroot.
+# Stages 01-03 install into ${KRYPTIK_WORK}/sysroot; in the chroot (04, 05) the sysroot is /.
 KRYPTIK_CHROOT_MARKER="/etc/kryptik/inside-chroot"
 
 kryptik_in_chroot() { [[ -f "$KRYPTIK_CHROOT_MARKER" ]]; }
@@ -185,10 +174,7 @@ validate_hardening_exceptions() {
     [[ "$n" -eq 0 ]] || die "${n} undocumented hardening exception(s). See docs/hardening.md."
 }
 
-# Build stamps carry a fingerprint of the step's inputs. A mismatch stops the
-# build (KRYPTIK_STALE=refuse, the default), since one rebuilt step leaves a
-# sysroot built from two configurations; KRYPTIK_STALE=rebuild rebuilds the
-# affected steps. Stamps without a fingerprint are moved to .stamps/legacy/.
+# Stamps fingerprint each step's inputs; a change stops the build unless KRYPTIK_STALE=rebuild.
 
 # Bump when the set of fingerprint inputs changes.
 KRYPTIK_STAMP_FORMAT=4
@@ -197,23 +183,17 @@ STAMP_PREFIX=""
 STAGE_FILE=""
 STAMP_CC=""
 
-#   stage_contract <this-file> <stamp-prefix> <compiler>
-# Called before a stage's first step(). <compiler> is the one the stage drives:
-# the host gcc for stage 01, whose cross gcc exists only halfway through.
+# stage_contract FILE PREFIX CC: call before the first step(); CC is the compiler the stage drives.
 stage_contract() {
     STAGE_FILE="${1:?stage_contract needs the stage file}"
     STAMP_PREFIX="${2-}"
     STAMP_CC="${3:?stage_contract needs the compiler this stage drives}"
 }
 
-# "name=fingerprint;" for every step so far, seeded by stage_depends_on(). Each
-# stamp hashes it, so a changed step invalidates every later step and every
-# stage built on it, while an unchanged prefix still resumes.
+# "name=fingerprint;" per step so far; each stamp hashes it, so a change invalidates later ones.
 STAMP_DEPS=""
 
-#   stage_depends_on <stamp-prefix> <step-name>
-# Seed the chain from an earlier stage's step, so stamps also record the
-# toolchain a stage was built with. That stamp must exist.
+# stage_depends_on PREFIX STEP: chain onto an earlier stage's stamp, so its toolchain counts too.
 stage_depends_on() {
     local prefix="$1" name="$2"
     local stamp="${STAMPS}/${prefix}${name}" fp
@@ -230,8 +210,7 @@ _hash_file() {
     if [[ -n "$f" && -f "$f" ]]; then sha256_of "$f"; else printf 'absent'; fi
 }
 
-# One digest over what apply_repo_patches reads of a patch set: its patches
-# and their SHA256SUMS. Not a README, which a documentation edit changes.
+# One digest over a patch set's patches and SHA256SUMS: what apply_repo_patches reads, no README.
 _hash_patchset() {
     local d="${1:-}"
     if [[ -n "$d" && -d "$d" ]]; then
@@ -256,8 +235,7 @@ _expand_v() {
 # In-repository patch sets; only the harness test overrides the location.
 KRYPTIK_PATCHES="${KRYPTIK_PATCHES:-${KRYPTIK_ROOT}/build/patches}"
 
-# Apply build/patches/<set>/*.patch here in name order (-p1, no fuzz). Every
-# patch must be listed in the set's SHA256SUMS and match it.
+# Apply build/patches/<set>/*.patch in name order (-p1, no fuzz); each must match SHA256SUMS.
 apply_repo_patches() {
     local set="${1:?apply_repo_patches needs a patch-set name}"
     local pdir="${KRYPTIK_PATCHES}/${set}"
@@ -279,9 +257,7 @@ apply_repo_patches() {
     echo "applied ${n} patch(es) from ${set}"
 }
 
-# GCC's math libraries, unpacked into its tree under the names it builds them
-# from. One command per line: after `tar ... && mv ...`, a failed tar let
-# configure find the host's copies.
+# GCC's math libraries in its tree, one command per line: set -e misses a failed tar in tar && mv.
 gcc_prereqs() {
     local t
     for t in "mpfr-${V_MPFR}.tar.xz" "gmp-${V_GMP}.tar.xz" "mpc-${V_MPC}.tar.gz"; do
@@ -305,10 +281,7 @@ stamp_compiler_id() {
     fi
 }
 
-# The functions FN names, the ones those name, and so on, as text in name
-# order. declare -f leaves comments out, so only code counts. The step runner
-# and its parts run around a recipe, never inside one: "step" in a recipe's
-# message is not a call, and an edit to the runner is a stamp format change.
+# The code of every function FN reaches, in name order; never the runner, which wraps recipes.
 _helpers_of() {
     local -A seen=(["$1"]=1)
     local -a todo=("$1")
@@ -326,11 +299,7 @@ _helpers_of() {
     done
 }
 
-# What one step was built from: the text of the recipe and of every helper it
-# reaches, its arguments, the sources and patch sets they name or that text
-# reads and applies, and every V_* it reads. Not the whole stage file, so a
-# fix to one recipe does not invalidate every stamp; not all of common.sh, so
-# a comment changes none.
+# A step's inputs: its recipe's and helpers' code, arguments, named sources and patch sets, V_*.
 recipe_fingerprint() {
     local fn="${1:-}"; shift || true
     local body
@@ -366,9 +335,7 @@ recipe_fingerprint() {
                  | sed -n 's/.*apply_repo_patches[[:space:]]\{1,\}"\{0,1\}\([^" ;)]*\).*/\1/p' \
                  | sort -u || true)
 
-        # A source the recipe's text names: a tarball, wherever it is named, or
-        # any file read from the sources directory. A name still holding a
-        # variable is a helper's argument, hashed with the step's arguments.
+        # Tarballs and source files the text names; one still holding a variable is an argument.
         local sf
         while IFS= read -r sf; do
             sf="$(_expand_v "$sf")"
@@ -383,8 +350,7 @@ recipe_fingerprint() {
         while IFS= read -r v; do
             [[ -z "$v" ]] && continue
             printf 'ver:%s=%s\n' "$v" "${!v-unset}"
-        # `|| true`: grep exits 1 for a recipe with no V_*, which would fire
-        # the ERR trap inside the process substitution.
+        # || true: grep exits 1 for a recipe with no V_*, which would fire the ERR trap.
         done < <(printf '%s
 %s
 ' "$body" "$*" \
@@ -392,9 +358,7 @@ recipe_fingerprint() {
     } | sha256_of_stdin
 }
 
-# The step's inputs plus what affects every step. versions.env and
-# hardening.env are not hashed whole: they reach a step through tarball names,
-# V_* values and the flags below, so an unrelated edit invalidates nothing.
+# Inputs, compiler, flags, chain; versions.env and hardening.env count only where a step reads them.
 stamp_fingerprint() {
     local name="$1"; shift
     {
@@ -476,12 +440,8 @@ Stamp: ${stamp}"
     esac
 }
 
-#   step <name> [--check] <recipe> [args...]
-# Stages provide STAMPS, LOGS, STAMP_PREFIX and STAGE_FILE, and optionally
-# REDO, set_flags_for() (per-package hardening) and step_failure_hint().
-# A check writes nothing a later step reads. It is stamped like any step and
-# runs again when anything before it changes, but it is no link in the chain:
-# editing one reruns it alone.
+# step NAME [--check] RECIPE [ARGS...]; a check is no link in the chain: an edit reruns it alone.
+# Stages set STAMPS, LOGS, STAMP_PREFIX and STAGE_FILE [REDO, set_flags_for, step_failure_hint].
 step() {
     local name="$1"; shift
     local link=1
@@ -505,7 +465,7 @@ step() {
             [[ "$link" -eq 0 ]] || STAMP_DEPS="${STAMP_DEPS}${name}=${want};"
             return 0
         fi
-        # Dies unless KRYPTIK_STALE=rebuild, or the stamp was fingerprint-less.
+        # Dies unless KRYPTIK_STALE=rebuild, or the stamp has no fingerprint.
         _stamp_stale "$name" "$stamp" "$got"
     fi
 
@@ -514,11 +474,7 @@ step() {
     local logfile="${LOGS}/${STAMP_PREFIX}${name}.log"
     local start=$SECONDS
 
-    # A bare subshell, never a condition: `( ... ) || rc=$?` or `if ! ( ... )`
-    # turns errexit off inside the recipe too. The ERR trap fires even without
-    # errexit and would exit this shell, so it is lifted here and re-armed in
-    # the subshell, where the recipe's abort line lands in its log.
-    # Tested by tools/tests/step-errexit.sh.
+    # A bare subshell, since a condition drops errexit in the recipe; the ERR trap moves inside it.
     local rc=0
     set +e
     trap - ERR
diff --git a/build/lib/kconfig-check.sh b/build/lib/kconfig-check.sh
index 6fb41877..62604d14 100644
--- a/build/lib/kconfig-check.sh
+++ b/build/lib/kconfig-check.sh
@@ -1,8 +1,5 @@
 # shellcheck shell=bash
-# Does a resolved .config honour every line of the kernel config fragments?
-# Used by stage 05 and tools/resolve-kernel-config.sh. merge_config.sh and
-# olddefconfig drop a line silently on an unmet dependency, on a `select` that
-# overrides "is not set", or when its prompt is hidden (e.g. behind EXPERT).
+# Does a resolved .config honour every fragment line? Kconfig drops unmet ones silently.
 
 # The .config as KCONFIG_HAVE[option]=value, read once for both checks.
 declare -gA KCONFIG_HAVE=()
@@ -15,8 +12,7 @@ _kconfig_load() {   # <.config>
     done < "$1"
 }
 
-# Options Kryptik's guarantees rest on. They must be present at all, so that
-# deleting one from a fragment is noticed; =y or =m is the fragment's choice.
+# Options Kryptik's guarantees rest on, so deleting one from a fragment is noticed; =y or =m pass.
 KCONFIG_CRITICAL="CONFIG_SECURITY_LANDLOCK CONFIG_SECCOMP_FILTER CONFIG_USER_NS
 CONFIG_NET_NS CONFIG_EFI_STUB CONFIG_CMDLINE_BOOL CONFIG_CMDLINE_OVERRIDE
 CONFIG_DM_INIT CONFIG_EFIVAR_FS CONFIG_OVERLAY_FS CONFIG_DRM_VIRTIO_GPU
@@ -39,9 +35,7 @@ kconfig_critical_check() {
     [[ "$missing" -eq 0 ]]
 }
 
-# kconfig_fragment_check <.config> <fragment>...
-# Each =value line must come out with that value and each "is not set" line
-# unset or absent. Prints the lines that did not; 0 when there are none.
+# kconfig_fragment_check <.config> <fragment>...: print the lines not honoured; 0 when none.
 kconfig_fragment_check() {
     local config="$1"; shift
     local frag line opt want got total=0 bad=0
diff --git a/build/patches/dwl-0.8/README.md b/build/patches/dwl-0.8/README.md
index ae03316b..42448384 100644
--- a/build/patches/dwl-0.8/README.md
+++ b/build/patches/dwl-0.8/README.md
@@ -1,4 +1,4 @@
-# dwl 0.8: a window closed with its decoration still alive no longer crashes dwl
+# dwl 0.8: a window closing with its decoration alive does not crash dwl
 
 Applied by `s_dwl` in stage 04 through `apply_repo_patches`, before
 `tools/desktop/dwl-zone-borders.py`; `SHA256SUMS` is verified before anything
@@ -8,10 +8,10 @@ dwl 0.8 frees a client in `destroynotify` without removing the two listeners
 it put on the client's xdg-decoration, and `destroydecoration` leaves
 `c->decoration` set. When a client disconnects, wlroots destroys its toplevel
 first: `destroynotify` frees the client, then the decoration is destroyed and
-its destroy signal walks into the freed listeners. Under glibc the freed
-memory still held the old links, so nothing showed. The image preloads
-hardened_malloc, which does not keep them: dwl died the first time a zone's
-havoc window closed, and every later window, in any zone, found no display.
+its destroy signal walks into the freed listeners. glibc leaves the old links
+in freed memory, so nothing shows. hardened_malloc, which the image preloads,
+does not: dwl dies the first time a zone's window closes, and every later
+window, in any zone, finds no display.
 
 Both patches are upstream's, generated with `git format-patch` and unchanged;
 they apply to the 0.8 tarball with a one-line offset:
@@ -24,14 +24,14 @@ they apply to the 0.8 tarball with a one-line offset:
 
 Checked on headless dwl 0.8 with wlroots 0.19.3 and hardened_malloc 14
 preloaded: without the patches dwl dies of SIGSEGV when a havoc window's
-client disconnects, with them it carries on. The desktop suite's
+client disconnects; with them it carries on. The desktop suite's
 `compositor-survives-close` checks the same on the image. Delete this
 directory when the dwl pin moves to a release that contains both commits.
 
-Reviewed and not carried: upstream 4847f97 ("Clear surface->data on unmap
-to fix idle-inhibitor use-after-free"). No zone can create an idle inhibitor,
-since the proxy does not offer the protocol, and under hardened_malloc the
-freed scene tree `checkidleinhibitor` reads is zeroed, so its parent is NULL
-and the read is harmless; a zone-0 client that inhibits, drops its toplevel
-and keeps the surface does not crash dwl with or without it. Take it with the
-next dwl release rather than as a patch.
+Not carried: upstream 4847f97 ("Clear surface->data on unmap to fix
+idle-inhibitor use-after-free"). No zone can create an idle inhibitor, since
+the proxy does not offer the protocol, and under hardened_malloc the freed
+scene tree `checkidleinhibitor` reads is zeroed, so its parent is NULL and the
+read is harmless; a zone 0 client that inhibits, drops its toplevel and keeps
+the surface does not crash dwl with or without it. It comes with the next dwl
+release.
diff --git a/build/patches/gawk-5.3.0/README.md b/build/patches/gawk-5.3.0/README.md
index e7117fc4..a4a6bb6a 100644
--- a/build/patches/gawk-5.3.0/README.md
+++ b/build/patches/gawk-5.3.0/README.md
@@ -7,13 +7,13 @@ gawk 5.4.1 fixes four advisories (CERT Polska, July 2026). Three reach
 Kryptik's x86-64 build and are carried, each as upstream wrote it, with its
 ChangeLog hunk dropped:
 
-- `0001`, CVE-2026-40467: `do_getline_redir()` in io.c released the
-  redirection's name and then read it on the path for a closed two-way pipe.
+- `0001`, CVE-2026-40467: `do_getline_redir()` in io.c frees the
+  redirection's name and then reads it on the path for a closed two-way pipe.
   Upstream a2d18c74109e41bec29a23098eba2e00057286d8, "Small memory
   management fix in io.c.", made against 5.3.0's text, which differs in the
   lines around it.
-- `0002`, CVE-2026-40468: `do_sub()` kept its output offset in an `int`, and
-  `parse_escape()` gathered a `\u` escape's eight hex digits in an `int`.
+- `0002`, CVE-2026-40468: `do_sub()` keeps its output offset in an `int`, and
+  `parse_escape()` gathers a `\u` escape's eight hex digits in an `int`.
   Both are widened as in upstream 062f2f2581b991362c046f7f2e238ffa34e6f8c7,
   "Minor integer overflow fixes."; 5.3.0 declares the escape's value `int`
   where upstream had `long`.
diff --git a/build/patches/glibc-2.40/README.md b/build/patches/glibc-2.40/README.md
index a642dd7d..034732c5 100644
--- a/build/patches/glibc-2.40/README.md
+++ b/build/patches/glibc-2.40/README.md
@@ -2,8 +2,8 @@
 
 Applied by `s_glibc` in stages 01 and 04 through `apply_repo_patches
 "glibc-${V_GLIBC}"` (build/lib/common.sh), after the LFS FHS patch. The
-whole directory is an input to those steps' fingerprints; `SHA256SUMS` is
-verified before anything is applied.
+patches and `SHA256SUMS` are inputs to those steps' fingerprints, and
+`SHA256SUMS` is verified before anything is applied.
 
 ## What is here
 
@@ -16,7 +16,7 @@ The signed tarball stays the base. `glibc-2.40.tar.xz` is verified against
 the GNU keyring like every other GNU source, and its contents are
 byte-identical to the tree of the `glibc-2.40` tag (`git archive glibc-2.40`
 against the unpacked tarball: no differing entry), so a diff between two
-commit ids is exactly a diff against the tarball.
+commit ids is a diff against the tarball.
 
 ## Why the whole branch
 
@@ -51,7 +51,7 @@ with no message: `_dl_find_object` attributes every object loaded after
 startup to `ld-linux-x86-64.so.2` itself, so libgcc's unwinder reads ld.so's
 `.eh_frame`, finds no FDE and calls `abort()`. Bug 31943 (an ld.so mapped
 with gaps between its LOAD segments) gives the same symptom; its fix is on
-the branch, in 0001, but it was not the cause here.
+the branch, in 0001, and does not cure this one.
 
 **Bug 33088**: the loader stores its own map bounds -
 `l_map_start = &__ehdr_start`, `l_map_end = _end` - in `_dl_start`, before
@@ -63,11 +63,11 @@ the load of it to the top of `_dl_start`, above `ELF_DYNAMIC_RELOCATE`.
 The word holds the link-time value, 0, at that moment, so ld.so records
 itself as `[0, _end)`. `_dl_find_object` then answers "ld.so" for every
 address below libc that belongs to nothing it knows - which is where every
-later `dlopen` is mapped. On Kryptik, `ldd` printed
+later `dlopen` is mapped. Unpatched, `ldd` prints
 `/lib64/ld-linux-x86-64.so.2 (0x0000000000000000)` and
-`_dl_find_object((void *) 0x1000)` returned ld.so. Recompiling `rtld.c`
-with `-fno-tree-slp-vectorize` or `-O1` removed the relocated constant;
-none of the hardening flags mattered. Upstream fixed it in 2.42 with two
+`_dl_find_object((void *) 0x1000)` returns ld.so. Compiling `rtld.c` with
+`-fno-tree-slp-vectorize` or `-O1` removes the relocated constant; the
+hardening flags play no part. Upstream fixed it in 2.42 with two
 `asm` barriers (GCC bug 120653 records the compiler side). It was never
 backported to `release/2.40/master`, and is not on it at `cdaa5d6d`.
 
@@ -112,8 +112,8 @@ from having to understand git's rename headers, so anyone with a clone gets
 these bytes. The range contains no binary change and no mode-only change
 (`git diff --numstat` and `--summary` over the same range), which patch(1)
 could not have carried. `UPSTREAM-SHA256SUMS` records the sha256 of that
-command's output; it equals the file's entry in `SHA256SUMS`, because nothing
-was edited afterwards.
+command's output; it equals the file's entry in `SHA256SUMS`, as the file is
+unedited.
 
 The check that the patch is the branch and nothing else: unpack the tarball,
 apply the LFS FHS patch, 0001 and 0004, and `diff -r` the result against
diff --git a/build/patches/iputils-20250605/README.md b/build/patches/iputils-20250605/README.md
index d50eba10..4a098c17 100644
--- a/build/patches/iputils-20250605/README.md
+++ b/build/patches/iputils-20250605/README.md
@@ -9,9 +9,9 @@ socket that `net.ipv4.ping_group_range` opens to the zone's group
 (`docs/design/net-zone.md`). Built without libcap, ping still calls
 `seteuid()` and `setuid()` to give up privilege it does not have, and exits
 when one fails. A zone's seccomp filter answers every id call with EPERM, so
-ping ended before its first packet.
+ping exits before its first packet.
 
 The patch skips the three calls when ping starts with equal effective and
 real uids, which is when there is nothing to drop. A setuid-root ping
-behaves as upstream's. Not upstream when this was written. Delete this
-directory when an iputils release carries an equivalent.
+behaves as upstream's. The patch is Kryptik's own; delete this directory
+when an iputils release carries an equivalent.
diff --git a/build/patches/readline-8.3/README.md b/build/patches/readline-8.3/README.md
index da6a683e..6bac56a0 100644
--- a/build/patches/readline-8.3/README.md
+++ b/build/patches/readline-8.3/README.md
@@ -25,8 +25,8 @@ against its `.sig` and the GNU keyring. All six are signed by
 
 GNU writes them for `patch -p0`, and `apply_repo_patches` applies `-p1` with
 no fuzz, so their file-header lines are rewritten: `*** ../readline-8.3/FILE`
-became `*** a/FILE` (some name `../readline-8.3-patched/`, and 002 names
-`../readline-8.2/patchlevel`), and `--- FILE` became `--- b/FILE`. Hunk lines
+to `*** a/FILE` (some name `../readline-8.3-patched/`, and 002 names
+`../readline-8.2/patchlevel`), and `--- FILE` to `--- b/FILE`. Hunk lines
 and bodies are GNU's. Two copies of the tarball, one patched with the six
 originals at `-p0` and one with these at `-Np1 -F0`, are the same tree
 (`diff -r`), and `patchlevel` reads 6 in both.
diff --git a/build/patches/shadow-4.16.0/README.md b/build/patches/shadow-4.16.0/README.md
index 9a269a6f..f75a91bf 100644
--- a/build/patches/shadow-4.16.0/README.md
+++ b/build/patches/shadow-4.16.0/README.md
@@ -4,14 +4,14 @@ Applied by `s_shadow` in stage 04 through `apply_repo_patches`;
 `SHA256SUMS` is verified before anything is applied.
 
 `sgetgrent()` parses one line of /etc/group for the group database code
-every shadow tool goes through (`lib/groupio.c`). 4.16.0 accepted a line
-with three fields instead of four, and then took the member list from a
+every shadow tool goes through (`lib/groupio.c`). 4.16.0 accepts a line
+with three fields instead of four, and then takes the member list from a
 pointer left over from the previous line, which can point into a buffer it
 has since freed. The patch is upstream's fix, unchanged:
 8424d7c49462a6587c773f9b08c1867d7750f5ec, "lib/sgetgrent.c: sgetgrent():
 Fix use-after-free bug" (https://github.com/shadow-maint/shadow/issues/1144),
-first released in 4.17.0. A line missing a field is now refused like any
-other malformed line. /etc/group is root's file, so this is hardening, not a
-boundary.
+first released in 4.17.0. With it, a line missing a field is refused like
+any other malformed line. /etc/group is root's file, so this is hardening,
+not a boundary.
 
 Delete this directory when the shadow pin moves to 4.17.0 or later.
diff --git a/build/patches/tar-1.35/README.md b/build/patches/tar-1.35/README.md
index f378bc09..150026cf 100644
--- a/build/patches/tar-1.35/README.md
+++ b/build/patches/tar-1.35/README.md
@@ -6,7 +6,7 @@ Applied by `s_tar` in stage 04 through `apply_repo_patches`;
 tar 1.35 defines three private helpers, `acl_get_file_at()`,
 `acl_set_file_at()` and `acl_delete_def_file_at()`, in `src/xattrs.c`.
 acl 2.4.0 declares public functions of those names with other signatures in
-`<sys/acl.h>`, so tar no longer compiles against it ("conflicting types
+`<sys/acl.h>`, so tar does not compile against it ("conflicting types
 for 'acl_get_file_at'"). The patch is upstream's rename to `tar_acl_*`,
 08c3fc2e9337094aff01a511170fd35fdb8f1ee3, "Avoid acl_ prefix for functions",
 made against 1.35's text: the same three names renamed at the same
diff --git a/build/patches/zlib-1.3.1/README.md b/build/patches/zlib-1.3.1/README.md
index 13004686..e911e32e 100644
--- a/build/patches/zlib-1.3.1/README.md
+++ b/build/patches/zlib-1.3.1/README.md
@@ -6,7 +6,7 @@ verified before anything is applied.
 `crc32_combine()`, `crc32_combine_gen()` and their 64-bit forms never return
 when the length they are given is negative. They walk the length's bits by
 shifting it right until it is zero, and a negative length shifted right never
-is. zlib.h already said the length must not be negative. This is
+is. zlib.h says the length must not be negative. This is
 CVE-2026-27171; the fix has them return 0 instead.
 
 zlib 1.3.2 is the release that fixes it, and it is not taken because it adds
diff --git a/build/recipes/bc.sh b/build/recipes/bc.sh
index 7b6bf2ac..ec1339fa 100644
--- a/build/recipes/bc.sh
+++ b/build/recipes/bc.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# bc: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_bc() {
     local src; src="$(unpack "bc-${V_BC}.tar.gz" "bc-${V_BC}")"
@@ -21,7 +19,7 @@ s_bc() {
     echo "  1000000000/250 = ${got}"
     [[ "$got" == "4000000" ]] || { echo "FAIL: bc computed ${got}, expected 4000000"; return 1; }
 
-    # libmath is what fix-libmath_h exists for; -l loads it.
+    # -l loads libmath, which the build generates with fix-libmath.sed.
     got="$(echo 's(0)' | bc -q -l)"
     echo "  s(0) = ${got}"
     [[ "$got" == "0" || "$got" == ".00000000000000000000" ]] \
diff --git a/build/recipes/binutils.sh b/build/recipes/binutils.sh
index 07357da7..78bc9dac 100644
--- a/build/recipes/binutils.sh
+++ b/build/recipes/binutils.sh
@@ -1,15 +1,10 @@
 #!/usr/bin/env bash
-# binutils: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_binutils_native() {
     local src; src="$(unpack "binutils-${V_BINUTILS}.tar.xz" "binutils-${V_BINUTILS}")"
     cd "$src"
     mkdir -p build && cd build
-    # --with-stage1-ldflags= : the shared top-level configure would link the
-    # programs with -static-libgcc -static-libstdc++, whose objects (stage
-    # 02's) carry no CET note, and ld would drop it from ld, as and the rest.
-    # No gprofng, a profiler nothing here uses.
+    # --with-stage1-ldflags=: the default static libgcc and libstdc++ (stage 02's) lack CET notes.
     ../configure --prefix=/usr --sysconfdir=/etc --enable-gold \
         --enable-ld=default --enable-plugins --enable-shared --disable-werror \
         --enable-64-bit-bfd --enable-new-dtags --with-system-zlib \
@@ -17,8 +12,7 @@ s_binutils_native() {
     make tooldir=/usr
     make tooldir=/usr install
     rm -fv /usr/lib/lib{bfd,ctf,ctf-nobfd,opcodes,sframe}.a
-    # Stage 02's binutils went into the target's tool directory, which gcc
-    # searches before PATH; tooldir=/usr put these in /usr/bin instead.
+    # gcc searches stage 02's /usr/<triple> tools before PATH; tooldir=/usr put these in /usr/bin.
     local t; t="$(gcc -dumpmachine)"
     rm -rf "/usr/${t:?}"
     local p
diff --git a/build/recipes/bzip2.sh b/build/recipes/bzip2.sh
index 3840500c..f2960462 100644
--- a/build/recipes/bzip2.sh
+++ b/build/recipes/bzip2.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# bzip2: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_bzip2() {
     local src; src="$(unpack "bzip2-${V_BZIP2}.tar.gz" "bzip2-${V_BZIP2}")"
@@ -8,9 +6,7 @@ s_bzip2() {
     # bzip2 has no configure; its docs path and shared-lib build need patching.
     sed -i 's@\(ln -s -f \)$(PREFIX)/bin/@\1@' Makefile
     sed -i "s@(PREFIX)/man@(PREFIX)/share/man@g" Makefile
-    # Both Makefiles assign CFLAGS, which beats the environment, and link the
-    # library with neither CFLAGS nor LDFLAGS: the flags go on the command
-    # line, with the -fPIC and large-file define theirs carried.
+    # Both Makefiles set CFLAGS over the environment and link without LDFLAGS: pass both here.
     sed -i -e 's/-shared -Wl,-soname/-shared $(LDFLAGS) -Wl,-soname/' \
         -e 's/$(CFLAGS) -o bzip2-shared/$(CFLAGS) $(LDFLAGS) -o bzip2-shared/' Makefile-libbz2_so
     [[ "$(grep -c 'LDFLAGS' Makefile-libbz2_so)" -eq 2 ]] || { echo "FAIL: Makefile-libbz2_so did not take LDFLAGS"; return 1; }
diff --git a/build/recipes/ca-bundle.sh b/build/recipes/ca-bundle.sh
index 73c719d7..a1c14c5a 100644
--- a/build/recipes/ca-bundle.sh
+++ b/build/recipes/ca-bundle.sh
@@ -1,10 +1,6 @@
 #!/usr/bin/env bash
-# ca-bundle: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# Mozilla's CA bundle, where OpenSSL 3 and python's ssl look by default, on the
-# verified root (zones see /etc/ssl/certs read-only). A release's authenticity
-# rests on its signature, not TLS, but the downloader still verifies servers.
+# Mozilla's CA bundle where OpenSSL and python look: releases are signed, but servers are verified.
 s_ca_bundle() {
     local pem="${KRYPTIK_SOURCES}/cacert-${V_CA_BUNDLE}.pem"
     [[ -f "$pem" ]] || { echo "FAIL: ${pem} was not fetched"; return 1; }
diff --git a/build/recipes/cmake.sh b/build/recipes/cmake.sh
index 2aa366f1..d997b1ec 100644
--- a/build/recipes/cmake.sh
+++ b/build/recipes/cmake.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# cmake: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_cmake() {
     local bin
diff --git a/build/recipes/compiler-check.sh b/build/recipes/compiler-check.sh
index 8ffec9f5..ca267266 100644
--- a/build/recipes/compiler-check.sh
+++ b/build/recipes/compiler-check.sh
@@ -1,10 +1,6 @@
 #!/usr/bin/env bash
-# compiler-check: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# With -fcf-protection=full a function must start with endbr64; gcc 14.2.0 put
-# a loop's .p2align first (GCC PR target/116174, fixed in 14.3). This runs the
-# bug's own test case with the image's flags; "plain" is the control.
+# GCC PR target/116174's case, plus a plain control: each must start with endbr64 under the flags.
 s_compiler_check() {
     local d; d="$(mktemp -d)"
     printf '%s\n' 'char *f(char *d, const char *s) { while ((*d++ = *s++)) ; return --d; }' \
diff --git a/build/recipes/console.sh b/build/recipes/console.sh
index 8c9c659d..332d073b 100644
--- a/build/recipes/console.sh
+++ b/build/recipes/console.sh
@@ -1,11 +1,6 @@
 #!/usr/bin/env bash
-# console: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# The console: a root shell on install media (agetty -n -l skips login), a
-# login prompt otherwise. The device is the kernel's active console, not a
-# guess: a serial port when there is one; a virtual terminal is left to
-# getty-tty1.
+# A root shell on install media, a login prompt otherwise, on the kernel's active console.
 s_console() {
     mkdir -p /usr/libexec
     cat > /usr/libexec/kryptik-console <<'EOF'
diff --git a/build/recipes/coreutils.sh b/build/recipes/coreutils.sh
index a88c71f2..ba1aebe9 100644
--- a/build/recipes/coreutils.sh
+++ b/build/recipes/coreutils.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# coreutils: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 # chroot goes to /usr/sbin, over the unhardened copy stage 02 put there.
 s_coreutils() {
diff --git a/build/recipes/cryptsetup.sh b/build/recipes/cryptsetup.sh
index 24ab04e1..34333814 100644
--- a/build/recipes/cryptsetup.sh
+++ b/build/recipes/cryptsetup.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# cryptsetup: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_cryptsetup() {
     local src; src="$(unpack "cryptsetup-${V_CRYPTSETUP}.tar.xz" "cryptsetup-${V_CRYPTSETUP}")"
@@ -12,8 +10,7 @@ s_cryptsetup() {
     echo "--- what shipped ---"
     cryptsetup --version
     veritysetup --version
-    # LUKS2 is the contract (docs/design/encrypted-volumes.md). The help text is
-    # captured, not piped into grep -q, which can SIGPIPE cryptsetup.
+    # LUKS2 is the contract (docs/design/encrypted-volumes.md); captured, as grep -q can SIGPIPE it.
     cryptsetup benchmark --help >/dev/null 2>&1 || true
     local help; help="$(cryptsetup --help 2>&1 || true)"
     case "$help" in
diff --git a/build/recipes/desktop.sh b/build/recipes/desktop.sh
index 8a11b802..90db40bb 100644
--- a/build/recipes/desktop.sh
+++ b/build/recipes/desktop.sh
@@ -1,10 +1,6 @@
 #!/usr/bin/env bash
-# desktop: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# kryptik-launch (the session's client of the launch daemon), the session and
-# chrome scripts, and the per-zone Wayland proxy, built outside like kryptikd
-# (KRYPTIK_WLPROXY_BIN). Every input is a digest argument of the step.
+# The launch client, session and chrome scripts, and the Wayland proxy built outside (as kryptikd).
 s_desktop() {
     local wl="$1" wl_sha="${2:-absent}" launch_sha="${3:-none}" session_sha="${4:-none}" chrome_sha="${5:-none}" probe_sha="${6:-none}"
     [[ "$wl" == "none" ]] && wl=""
@@ -28,8 +24,7 @@ s_desktop() {
     [[ "$out" == *usage:* ]] || { echo "FAIL: kryptik-launch does not run here: ${out}"; return 1; }
     echo "kryptik-launch: built and runs"
 
-    # The Wayland probe the boundary tests run in zones and in zone 0: which
-    # globals a client is offered, and what binding a hidden one gets.
+    # The boundary tests' probe: the globals a client is offered and what binding a hidden one gets.
     # shellcheck disable=SC2086
     gcc ${CFLAGS} ${LDFLAGS} -o /usr/libexec/kryptik/wlprobe "$d/wlprobe.c"
     chmod 0755 /usr/libexec/kryptik/wlprobe
diff --git a/build/recipes/dhcpcd.sh b/build/recipes/dhcpcd.sh
index a8dd2322..5a0ea3ea 100644
--- a/build/recipes/dhcpcd.sh
+++ b/build/recipes/dhcpcd.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# dhcpcd: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_dhcpcd() {
     local src; src="$(unpack "dhcpcd-${V_DHCPCD}.tar.xz" "dhcpcd-${V_DHCPCD}")"
diff --git a/build/recipes/dnsmasq.sh b/build/recipes/dnsmasq.sh
index af635e5a..1fb8c557 100644
--- a/build/recipes/dnsmasq.sh
+++ b/build/recipes/dnsmasq.sh
@@ -1,14 +1,10 @@
 #!/usr/bin/env bash
-# dnsmasq: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_dnsmasq() {
     local src; src="$(unpack "dnsmasq-${V_DNSMASQ}.tar.xz" "dnsmasq-${V_DNSMASQ}")"
     cd "$src"
-    # Its Makefile assigns CFLAGS and LDFLAGS, which beat the environment, so
-    # the hardening goes on the command line. No inotify: a zone gets ENOSYS
-    # for it (REFUSED_SOFTLY in seccomp.rs), dnsmasq exits when it cannot have
-    # it, and the net zone runs it with --no-poll, which never watches anyway.
+    # The Makefile sets CFLAGS and LDFLAGS over the environment, so they go on the command line.
+    # NO_INOTIFY: a zone gets ENOSYS for inotify (seccomp.rs), and dnsmasq exits without it.
     local mk=(PREFIX=/usr COPTS="-DNO_DBUS -DNO_ID -DNO_INOTIFY" CFLAGS="$CFLAGS" LDFLAGS="$LDFLAGS")
     make "${mk[@]}"
     # `install`, not `install-common`, which installs nothing with PREFIX set.
diff --git a/build/recipes/dwl.sh b/build/recipes/dwl.sh
index 24996581..7ef44b83 100644
--- a/build/recipes/dwl.sh
+++ b/build/recipes/dwl.sh
@@ -1,15 +1,6 @@
 #!/usr/bin/env bash
-# dwl: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# dwl with Kryptik's config.h: the keybindings are the trusted launcher, and
-# border colours are the compositor-controlled zone identity. Its three inputs
-# are digests in this step's arguments:
-#   build/desktop/dwl-config.h        the configuration; includes the next
-#   build/desktop/zone-colours.h      the zone -> border colour table
-#   tools/desktop/dwl-zone-borders.py the change to dwl.c that draws them
-# config.h uses `ZoneColor`, which only the patch adds: the three go together.
-# Upstream fixes come first, from build/patches/dwl-0.8 (see its README).
+# dwl with Kryptik's keybindings (the trusted launcher) and zone border colours (zone identity).
 s_dwl() {
     local cfg_sha="${1:-none}" colours_sha="${2:-none}" patch_sha="${3:-none}"
     local desk="${KRYPTIK_ROOT}/build/desktop"
@@ -42,8 +33,7 @@ s_dwl() {
     cp "$cfg" config.h
     make PREFIX=/usr XWAYLAND= XLIBS=
     make PREFIX=/usr install
-    # The installed binary must carry the change: the chooser's app_id prefix
-    # is a literal in it.
+    # The installed binary must carry the change; the chooser's app_id prefix is a literal in it.
     grep -aq 'kryptik\.' /usr/bin/dwl || { echo "FAIL: /usr/bin/dwl does not contain the zone chooser"; return 1; }
     echo "installed dwl with per-zone borders"
     dwl -v 2>&1 | head -1 || true
diff --git a/build/recipes/e2fsprogs.sh b/build/recipes/e2fsprogs.sh
index 23f15894..587e4589 100644
--- a/build/recipes/e2fsprogs.sh
+++ b/build/recipes/e2fsprogs.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# e2fsprogs: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_e2fsprogs() {
     local src; src="$(unpack "e2fsprogs-${V_E2FSPROGS}.tar.gz" "e2fsprogs-${V_E2FSPROGS}")"
diff --git a/build/recipes/efiboot.sh b/build/recipes/efiboot.sh
index acbbee04..ff39519f 100644
--- a/build/recipes/efiboot.sh
+++ b/build/recipes/efiboot.sh
@@ -1,14 +1,11 @@
 #!/usr/bin/env bash
-# efiboot: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# The firmware side of the A/B trial: writes Boot#### and BootNext through
-# efivarfs. Its source hash is an argument, so a source change rebuilds it.
+# The firmware side of the A/B trial: Boot#### and BootNext through efivarfs.
 s_efiboot() {
     local src="${KRYPTIK_ROOT}/tools/efi/kryptik-efiboot.c"
     [[ -f "$src" ]] || { echo "no source at ${src}"; return 1; }
     echo "source sha256: ${1:-unknown}"
-    # shellcheck disable=SC2086  # CFLAGS/LDFLAGS are deliberately word-split
+    # shellcheck disable=SC2086  # CFLAGS/LDFLAGS are word-split
     gcc $CFLAGS $LDFLAGS -std=gnu11 -Wall -Wextra -o /usr/sbin/kryptik-efiboot "$src"
     local out
     out="$(/usr/sbin/kryptik-efiboot 2>&1 || true)"
diff --git a/build/recipes/elfutils.sh b/build/recipes/elfutils.sh
index 9e61947f..af39d79e 100644
--- a/build/recipes/elfutils.sh
+++ b/build/recipes/elfutils.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# elfutils: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_elfutils() {
     local src; src="$(unpack "elfutils-${V_ELFUTILS}.tar.bz2" "elfutils-${V_ELFUTILS}")"
diff --git a/build/recipes/eudev.sh b/build/recipes/eudev.sh
index fc43f3d9..3cc2e8b1 100644
--- a/build/recipes/eudev.sh
+++ b/build/recipes/eudev.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# eudev: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_eudev() {
     local src; src="$(unpack "eudev-${V_EUDEV}.tar.gz" "eudev-${V_EUDEV}")"
diff --git a/build/recipes/firmware.sh b/build/recipes/firmware.sh
index c95237b2..d9c0a071 100644
--- a/build/recipes/firmware.sh
+++ b/build/recipes/firmware.sh
@@ -1,11 +1,6 @@
 #!/usr/bin/env bash
-# firmware: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# copy-firmware.sh lays the pinned linux-firmware release out as the kernel
-# names the files; build/config/firmware.list (format in its header) picks what
-# ships, beside wireless-regdb. Files are zstd-compressed, as the kernel looks
-# for name.zst (CONFIG_FW_LOADER_COMPRESS_ZSTD), and links are repointed.
+# The linux-firmware files build/config/firmware.list picks, and wireless-regdb, zstd-compressed.
 s_firmware() {
     echo "list digest: ${1:-none}"
     local list="${KRYPTIK_ROOT}/build/config/firmware.list"
@@ -32,8 +27,7 @@ s_firmware() {
         fi
         matches="$(find "$tree" -path "${tree}/${pattern}" \( -type f -o -type l \) -print | sort)"
         if [[ "$keep" -gt 0 && -n "$matches" ]]; then
-            # Group by the name with its trailing -NUMBER removed, keep the
-            # highest NUMBERs of each group; a name without one is kept as is.
+            # Keep the newest $keep of each name by trailing -NUMBER; a name without one is kept.
             matches="$(printf '%s\n' "$matches" | while IFS= read -r f; do
                 b="${f##*/}"; stem="${b%.*}"; ext="${b##*.}"; ver="${stem##*-}"
                 if [[ "$ver" =~ ^[0-9]+$ ]]; then
@@ -74,8 +68,7 @@ s_firmware() {
     local regdb; regdb="$(unpack "wireless-regdb-${V_WIRELESS_REGDB}.tar.xz" "wireless-regdb-${V_WIRELESS_REGDB}")"
     install -m 0644 "${regdb}/regulatory.db" "${regdb}/regulatory.db.p7s" "$dest/"
 
-    # Compress the regular files, then repoint every symlink at the .zst. zstd
-    # takes its files one at a time, so several run at once.
+    # The kernel looks for name.zst (FW_LOADER_COMPRESS_ZSTD): compress, then repoint the links.
     find "$dest" -type f ! -name '*.zst' -print0 \
         | xargs -0 -r -P"${KRYPTIK_JOBS:-$(nproc)}" -n 32 zstd -19 -q --rm
     while IFS= read -r -d '' f; do
diff --git a/build/recipes/fonts.sh b/build/recipes/fonts.sh
index c0dcd4c1..3b7a0a40 100644
--- a/build/recipes/fonts.sh
+++ b/build/recipes/fonts.sh
@@ -1,10 +1,6 @@
 #!/usr/bin/env bash
-# fonts: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# havoc renders from the one TrueType file its config names
-# (/usr/share/fonts/TTF/DejaVuSansMono.ttf); Sans and the bold faces come along.
-# Licence: Bitstream Vera terms plus public-domain changes (LICENSE, installed).
+# DejaVu: havoc renders from the one file its config names; Sans and the bold faces come along.
 s_fonts() {
     local src; src="$(unpack "dejavu-fonts-ttf-${V_DEJAVU_FONTS}.tar.bz2" "dejavu-fonts-ttf-${V_DEJAVU_FONTS}")"
     install -d -m 0755 /usr/share/fonts/TTF
diff --git a/build/recipes/gawk.sh b/build/recipes/gawk.sh
index abd212bf..98473e48 100644
--- a/build/recipes/gawk.sh
+++ b/build/recipes/gawk.sh
@@ -1,14 +1,11 @@
 #!/usr/bin/env bash
-# gawk: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# gawk's install links gawk-<version> only when the name is free, so stage
-# 02's copy would stay under it. build/patches/gawk-5.3.0 (see its README)
-# carries upstream's memory-safety fixes from 5.4.1.
 s_gawk() {
+    # Install links gawk-<version> only when the name is free, so stage 02's would stay.
     rm -f "/usr/bin/gawk-${V_GAWK}"
     local src; src="$(unpack "gawk-${V_GAWK}.tar.xz" "gawk-${V_GAWK}")"
     cd "$src"
+    # Upstream's memory-safety fixes from 5.4.1 (see the patch set's README).
     apply_repo_patches "gawk-${V_GAWK}"
     ./configure --prefix=/usr --disable-pma
     make
diff --git a/build/recipes/gcc.sh b/build/recipes/gcc.sh
index 024ea4c1..ed86d41f 100644
--- a/build/recipes/gcc.sh
+++ b/build/recipes/gcc.sh
@@ -1,12 +1,6 @@
 #!/usr/bin/env bash
-# gcc: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# GCC again, in place of stage 02's temporary compiler, which set no flags:
-# the same triplet and defaults, so stage 05 and the stamps see the same
-# compiler, but now built with the hardening flags. Its binaries become PIE
-# with BIND_NOW, and libgcc_s and libstdc++, which glibc's unwinder and every
-# C++ program load, carry IBT and SHSTK.
+# GCC with the hardening, same triplet and defaults as stage 02's so stage 05 and the stamps agree.
 s_gcc_native() {
     local src; src="$(unpack "gcc-${V_GCC}.tar.xz" "gcc-${V_GCC}")"
     cd "$src"
@@ -14,11 +8,8 @@ s_gcc_native() {
         x86_64) sed -e '/m64=/s/lib64/lib/' -i.orig gcc/config/i386/t-linux64 ;;
     esac
     mkdir -p build && cd build
-    # The target libraries take CFLAGS by themselves in a native build, but
-    # not LDFLAGS: named, so libgcc_s and libstdc++ are linked with them too.
-    # Without a bootstrap, cc1 and the drivers would link stage 02's static
-    # libstdc++ and libgcc, which carry no CET note, and lose theirs; the
-    # empty stage1 flags link the shared ones instead.
+    # LDFLAGS_FOR_TARGET: a native build passes CFLAGS to the target libraries, not LDFLAGS.
+    # --with-stage1-ldflags=: else cc1 links stage 02's static libstdc++, which has no CET note.
     local want; want="$(uname -m)-kryptik-linux-gnu"
     ../configure --build="$want" --prefix=/usr LD=ld LDFLAGS_FOR_TARGET="$LDFLAGS" \
         --with-stage1-ldflags= \
@@ -29,12 +20,9 @@ s_gcc_native() {
         --disable-libsanitizer --disable-libssp --disable-libvtv \
         --with-system-zlib
     make
-    # Stage 02's compiler ran fixincludes and this one does not, so its fixed
-    # headers (searched before /usr/include) and its fixincl would stay.
+    # No fixincludes here, so stage 02's fixed headers (searched first) would stay.
     rm -rf "/usr/lib/gcc/${want}/${V_GCC}/include-fixed" "/usr/libexec/gcc/${want}/${V_GCC}/install-tools"
-    # -j1: the install replaces /usr/include/c++'s headers one by one, and a
-    # parallel job rebuilding libcc1 against them, which they now postdate,
-    # can find one gone.
+    # -j1: install replaces the C++ headers one by one, and a parallel libcc1 rebuild can miss one.
     make -j1 install
 
     local triple t lib
@@ -48,9 +36,7 @@ s_gcc_native() {
     { gcc $CFLAGS $LDFLAGS -o "$t/c" "$t/c.c" && "$t/c" \
         && g++ $CXXFLAGS $LDFLAGS -o "$t/p" "$t/p.cc" && "$t/p"; } \
         || { rm -rf "$t"; echo "FAIL: the new compiler cannot build and run a C and a C++ program that throws"; return 1; }
-    # Whole outputs, not pipes into grep -q, which can end readelf with SIGPIPE.
-    # A program keeps the CET note only if every object it links has it: the
-    # crt files, libc_nonshared and libgcc.a included.
+    # Captured, as grep -q can SIGPIPE readelf; CET survives only if every linked object has it.
     local out; out="$(readelf -h -n "$t/c")"; rm -rf "$t"
     [[ "$out" == *"Type:"*"DYN"* ]] || { echo "FAIL: its programs are not PIE"; return 1; }
     [[ "$out" == *"x86 feature: IBT, SHSTK"* ]] || { echo "FAIL: its programs carry no IBT and SHSTK: an object they link lacks the note"; return 1; }
diff --git a/build/recipes/gdbm.sh b/build/recipes/gdbm.sh
index ab49e4a3..d52edb0d 100644
--- a/build/recipes/gdbm.sh
+++ b/build/recipes/gdbm.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# gdbm: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_gdbm() {
     # No --enable-libgdbm-compat: man-db uses gdbm's native interface, not ndbm.
diff --git a/build/recipes/glibc.sh b/build/recipes/glibc.sh
index ab4fdf25..6ae9e83b 100644
--- a/build/recipes/glibc.sh
+++ b/build/recipes/glibc.sh
@@ -1,9 +1,6 @@
 #!/usr/bin/env bash
-# glibc: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# glibc, rebuilt natively with the hardening flags (stage 01's was built
-# without). After python, which glibc's configure requires.
+# glibc rebuilt with the hardening flags; after python, which its configure requires.
 s_glibc() {
     local src; src="$(unpack "glibc-${V_GLIBC}.tar.xz" "glibc-${V_GLIBC}")"
     cd "$src"
@@ -11,9 +8,7 @@ s_glibc() {
     local fhs="${KRYPTIK_SOURCES}/glibc-${V_GLIBC}-fhs-1.patch"
     [[ -f "$fhs" ]] && patch -Np1 -i "$fhs"
 
-    # build/patches/glibc-2.40 (see its README): upstream's release/2.40/master
-    # branch plus the bug 33088 fix, without which ld.so records its own map at
-    # address 0 and unwinding aborts. The two checks below catch its return.
+    # release/2.40 plus the bug 33088 fix (see the README), without which unwinding aborts.
     apply_repo_patches "glibc-${V_GLIBC}"
 
     mkdir -p build
@@ -21,11 +16,7 @@ s_glibc() {
     echo "rootsbindir=/usr/sbin" > configparms
 
     # --enable-stack-protector=strong: glibc builds its own stack protection.
-    # --enable-cet: glibc compiles its CET support only when GCC defines __CET__
-    # by default (Kryptik's does not), yet -fcf-protection=full in CFLAGS makes
-    # rtld call it, so the link fails on _dl_cet_*. Dropping the flag instead
-    # would leave the loader, which arms IBT and shadow stacks for everything,
-    # without CET. Activation still depends on the CPU and kernel.
+    # --enable-cet: CFLAGS' -fcf-protection makes rtld call _dl_cet_*, built only with this flag.
     ../configure \
         --prefix=/usr \
         --disable-werror \
@@ -36,8 +27,7 @@ s_glibc() {
         libc_cv_slibdir=/usr/lib
     make
 
-    # Upstream's check for bug 33088 (the test suite is not run): rtld must not
-    # reach __ehdr_start or _end through a run-time relocation.
+    # Upstream's bug 33088 check, since the test suite is not run.
     echo "--- run-time relocations against __ehdr_start or _end in rtld.os ---"
     local rtld_relocs
     rtld_relocs="$(readelf -rW elf/rtld.os | grep -E 'R_X86_64_64.*(__ehdr_start|_end)' || true)"
@@ -50,8 +40,7 @@ s_glibc() {
     fi
     echo "  ok: none"
 
-    # Skip glibc's test-installation script, as LFS does: it fails in a partly
-    # built system.
+    # Skip the test-installation script, as LFS does: it fails in a partly built system.
     sed '/test-installation/s@$(PERL)@true@' -i ../Makefile
     touch /etc/ld.so.conf
     make install
@@ -65,8 +54,7 @@ s_glibc() {
     grep -a -m1 -o "GNU C Library.*" /usr/lib/libc.so.6 || \
         echo "(no GNU C Library banner found - check the install)"
 
-    # Without the CET property note the loader arms IBT and shadow stacks for
-    # nothing.
+    # Without the CET property note the loader arms IBT and shadow stacks for nothing.
     echo "--- CET in the dynamic loader ---"
     local ldso=/usr/lib/ld-linux-x86-64.so.2
     if [[ -e "$ldso" ]]; then
@@ -86,9 +74,7 @@ s_glibc() {
         return 1
     fi
 
-    # The runtime form of that check: LD_TRACE_LOADED_OBJECTS (what ldd runs)
-    # prints each map start, and with bug 33088 the loader's is 0.
-    # tools/tests/libc-unwind.sh tests the consequence on the whole system.
+    # The runtime check: LD_TRACE_LOADED_OBJECTS prints map starts, and with bug 33088 ld.so's is 0.
     echo "--- the loader's own map start ---"
     local trace ldso_start
     trace="$(LD_TRACE_LOADED_OBJECTS=1 /usr/bin/bash 2>&1 || true)"
diff --git a/build/recipes/groff.sh b/build/recipes/groff.sh
index 0627b768..28029a59 100644
--- a/build/recipes/groff.sh
+++ b/build/recipes/groff.sh
@@ -1,11 +1,6 @@
 #!/usr/bin/env bash
-# groff: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# groff renders man pages for a terminal. Its HTML output and the mm and pdf
-# wrappers are not installed: pre-grohtml, mmroff and pdfmom ran commands
-# embedded in their input (fixed in groff 1.24.2), and nothing here renders
-# HTML. A sysroot from an earlier build still holds them, so they are removed.
+# Man pages for a terminal; no HTML output, mmroff or pdfmom, which run commands from their input.
 s_groff() {
     native_build "groff-${V_GROFF}.tar.gz" "groff-${V_GROFF}"
     rm -f /usr/bin/pre-grohtml /usr/bin/post-grohtml /usr/bin/mmroff /usr/bin/pdfmom
diff --git a/build/recipes/hardened-malloc.sh b/build/recipes/hardened-malloc.sh
index 91ba7ac3..30890396 100644
--- a/build/recipes/hardened-malloc.sh
+++ b/build/recipes/hardened-malloc.sh
@@ -1,14 +1,11 @@
 #!/usr/bin/env bash
-# hardened-malloc: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_hardened_malloc() {
     # ADR-005. Built here so it exists before anything links against it.
     local src; src="$(unpack "${V_HARDENED_MALLOC}.tar.gz" "hardened_malloc-${V_HARDENED_MALLOC}")"
     cd "$src"
 
-    # CONFIG_NATIVE=false overrides upstream's -march=native: in the system
-    # allocator, an instruction an older CPU lacks kills every process.
+    # Not upstream's -march=native: an instruction an older CPU lacks would kill every process.
     make VARIANT=default CONFIG_NATIVE=false
 
     # Check the command line beat config/default.mk.
@@ -25,7 +22,6 @@ s_hardened_malloc() {
 
     install -Dm755 out/libhardened_malloc.so /usr/lib/libhardened_malloc.so
 
-    # Not preloaded here, or every later package would build on it: stage 06
-    # writes /etc/ld.so.preload into the image's root only.
+    # Not preloaded here, or every later package would build on it; stage 06 preloads it.
     echo "installed to /usr/lib/libhardened_malloc.so (not yet preloaded)"
 }
diff --git a/build/recipes/havoc.sh b/build/recipes/havoc.sh
index 4d45e25d..92eeda7b 100644
--- a/build/recipes/havoc.sh
+++ b/build/recipes/havoc.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# havoc: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_havoc() {
     local src; src="$(unpack "havoc-${V_HAVOC}.tar.gz" "havoc-${V_HAVOC}")"
diff --git a/build/recipes/hwdata.sh b/build/recipes/hwdata.sh
index d871bc7f..23642102 100644
--- a/build/recipes/hwdata.sh
+++ b/build/recipes/hwdata.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# hwdata: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_hwdata() {
     local src; src="$(unpack "hwdata-${V_HWDATA}.tar.gz" "hwdata-${V_HWDATA}")"
diff --git a/build/recipes/iana-etc.sh b/build/recipes/iana-etc.sh
index 5ff1762f..ef25a8be 100644
--- a/build/recipes/iana-etc.sh
+++ b/build/recipes/iana-etc.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# iana-etc: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_iana_etc() {
     # Not a build: /etc/protocols and /etc/services are data files.
diff --git a/build/recipes/inetutils.sh b/build/recipes/inetutils.sh
index b6c700b7..a9a97573 100644
--- a/build/recipes/inetutils.sh
+++ b/build/recipes/inetutils.sh
@@ -1,13 +1,10 @@
 #!/usr/bin/env bash
-# inetutils: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# inetutils' clients: hostname and ifconfig. --disable-servers: no telnetd,
-# ftpd, rlogind and the rest, which nothing starts; ping is iputils'. traceroute
-# is not built, and a sysroot from an earlier build still holds its setuid copy.
+# hostname and ifconfig; no servers, which nothing starts, and ping comes from iputils.
 s_inetutils() {
     native_build "inetutils-${V_INETUTILS}.tar.gz" "inetutils-${V_INETUTILS}" --bindir=/usr/bin --localstatedir=/var \
         --disable-servers --disable-logger --disable-whois --disable-rlogin --disable-rsh --disable-rcp --disable-rexec \
         --disable-ping --disable-ping6 --disable-traceroute
+    # A cached sysroot may still hold an old setuid traceroute.
     rm -f /usr/bin/traceroute
 }
diff --git a/build/recipes/installer.sh b/build/recipes/installer.sh
index 48313e83..e925557a 100644
--- a/build/recipes/installer.sh
+++ b/build/recipes/installer.sh
@@ -1,9 +1,6 @@
 #!/usr/bin/env bash
-# installer: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# The installer runs inside a booted Kryptik system, onto a second disk; it is
-# never run on the build host.
+# The installer runs in a booted Kryptik system, onto a second disk, never on the build host.
 s_installer() {
     local src="${KRYPTIK_ROOT}/tools/install/kryptik-install.sh"
     [[ -f "$src" ]] || { echo "no installer at ${src}"; return 1; }
diff --git a/build/recipes/iproute2.sh b/build/recipes/iproute2.sh
index f5f6689d..08c6136b 100644
--- a/build/recipes/iproute2.sh
+++ b/build/recipes/iproute2.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# iproute2: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_iproute2() {
     local src; src="$(unpack "iproute2-${V_IPROUTE2}.tar.xz" "iproute2-${V_IPROUTE2}")"
diff --git a/build/recipes/iputils.sh b/build/recipes/iputils.sh
index 0947c8fd..171f21fe 100644
--- a/build/recipes/iputils.sh
+++ b/build/recipes/iputils.sh
@@ -1,13 +1,10 @@
 #!/usr/bin/env bash
-# iputils: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# iputils' ping alone, without libcap, with no setuid bit or file capability:
-# in a routed zone it sends over the ICMP datagram socket ping_group_range opens
-# (netzone.rs), and the patch stops it making the id calls a zone refuses.
+# ping alone, with no setuid bit or capability: zones ping over ICMP datagram sockets.
 s_iputils() {
     local src; src="$(unpack "iputils-${V_IPUTILS}.tar.xz" "iputils-${V_IPUTILS}")"
     cd "$src"
+    # Stops the id calls a zone refuses.
     apply_repo_patches "iputils-${V_IPUTILS}"
     meson setup build --prefix=/usr --buildtype=plain --wrap-mode=nodownload \
         -DBUILD_PING=true -DBUILD_ARPING=false -DBUILD_CLOCKDIFF=false -DBUILD_TRACEPATH=false \
@@ -15,8 +12,7 @@ s_iputils() {
         -DBUILD_MANS=true -DBUILD_HTML_MANS=false -DSKIP_TESTS=true
     ninja -C build
     ninja -C build install
-    # The tarball's prebuilt ping.8, installed without xsltproc, comes with an
-    # HTML copy that nothing reads.
+    # The prebuilt ping.8 comes with an HTML copy that nothing reads.
     rm -rf /usr/share/iputils
     [[ -f /usr/share/man/man8/ping.8 ]] || { echo "FAIL: ping.8 was not installed"; return 1; }
     local out; out="$(/usr/bin/ping -V)"
diff --git a/build/recipes/iw.sh b/build/recipes/iw.sh
index 13429696..7eaaf694 100644
--- a/build/recipes/iw.sh
+++ b/build/recipes/iw.sh
@@ -1,9 +1,6 @@
 #!/usr/bin/env bash
-# iw: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# iw: the operator's view of a radio (scan, link, reg), and the reference for
-# what kryptikd does with nl80211 itself.
+# The operator's view of a radio (scan, link, reg), and a reference for kryptikd's nl80211 use.
 s_iw() {
     local src; src="$(unpack "iw-${V_IW}.tar.xz" "iw-${V_IW}")"
     cd "$src"
diff --git a/build/recipes/json-c.sh b/build/recipes/json-c.sh
index fb0e3c46..036feb4b 100644
--- a/build/recipes/json-c.sh
+++ b/build/recipes/json-c.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# json-c: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_json_c() {
     local cmake
@@ -11,19 +9,15 @@ s_json_c() {
     echo "cmake: ${cmake}"
     local src; src="$(unpack "json-c-${V_JSON_C}.tar.gz" "json-c-json-c-${V_JSON_C}")"
     cd "$src"
-    # CMAKE_POLICY_VERSION_MINIMUM: cmake 4 refuses projects whose minimum is
-    # below 3.5, and json-c's test/app subdirectories still say 2.8/3.9.
-    #
-    # CMAKE_INSTALL_LIBDIR=lib: Kitware's binary, unlike the patched source
-    # build, picks lib64 here, where nothing in this sysroot looks.
+    # CMAKE_POLICY_VERSION_MINIMUM: cmake 4 refuses the old minimums json-c's subdirectories set.
+    # CMAKE_INSTALL_LIBDIR=lib: Kitware's binary would pick lib64, where nothing looks.
     "$cmake" -S . -B build -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release \
         -DCMAKE_INSTALL_LIBDIR=lib \
         -DBUILD_STATIC_LIBS=OFF -DBUILD_TESTING=OFF -DBUILD_APPS=OFF \
         -DCMAKE_POLICY_VERSION_MINIMUM=3.5
     "$cmake" --build build
     "$cmake" --install build
-    # cryptsetup's own check, made here where a failure names json-c (as s_lvm2
-    # does for devmapper.pc).
+    # cryptsetup's own check, made here where a failure names json-c.
     [[ -f /usr/lib/pkgconfig/json-c.pc ]] || { echo "no /usr/lib/pkgconfig/json-c.pc (installed under lib64?)"; return 1; }
     [[ -e /usr/lib64/libjson-c.so ]] && { echo "json-c installed into /usr/lib64, which this sysroot does not use"; return 1; }
     pkg-config --exists --print-errors json-c || return 1
diff --git a/build/recipes/kbd.sh b/build/recipes/kbd.sh
index 1f673312..cdff4450 100644
--- a/build/recipes/kbd.sh
+++ b/build/recipes/kbd.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# kbd: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_kbd() {
     local src; src="$(unpack "kbd-${V_KBD}.tar.xz" "kbd-${V_KBD}")"
@@ -8,8 +6,7 @@ s_kbd() {
     sed -i '/RESIZECONS_PROGS=/s/yes/no/' configure
     sed -i 's/resizecons.8 //' docs/man/man8/Makefile.in
 
-    # --disable-tests: generating the test suite needs autom4te, and there is no
-    # autoconf here.
+    # --disable-tests: generating the test suite needs autom4te, and there is no autoconf.
     ./configure --prefix=/usr --disable-vlock --disable-tests
     make
     make install
diff --git a/build/recipes/kryptikd.sh b/build/recipes/kryptikd.sh
index 1c8136d1..003f0be8 100644
--- a/build/recipes/kryptikd.sh
+++ b/build/recipes/kryptikd.sh
@@ -1,21 +1,13 @@
 #!/usr/bin/env bash
-# kryptikd: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# kryptikd, the zone supervisor: Rust, built outside as the sysroot has no Rust
-# toolchain, and its absence is reported, not passed over. The path and the
-# binary's hash are arguments, so the stamp covers them; an environment
-# variable would not be.
+# kryptikd, built outside (no Rust here); its path and hash are arguments, so the stamp covers them.
 s_kryptikd() {
     local src="$1" want_sha="${2:-absent}" zones_sha="${3:-nozones}"
     [[ "$src" == "none" ]] && src=""
     echo "requested: ${src:-<none>} (sha256 ${want_sha})"
     echo "zone definitions: ${zones_sha}"
 
-    # Zone files and their policies live on the verified root, where every
-    # privileged reader looks. /etc/kryptik/zones only links there for the
-    # kryptik command: the /etc overlay could replace that link, and only that
-    # unprivileged wrapper follows it.
+    # Privileged readers use the verified root; the replaceable /etc link serves only `kryptik`.
     install -d -m 0755 /etc/kryptik /usr/lib/kryptik
     install -d -m 0755 /usr/lib/kryptik/zones /usr/lib/kryptik/zones/policy
     if [[ -d "${KRYPTIK_ROOT}/compartments/zones" ]]; then
@@ -59,8 +51,7 @@ s_kryptikd() {
 
     [[ -f "$src" ]] || { echo "KRYPTIK_KRYPTIKD_BIN=${src} does not exist"; return 1; }
 
-    # The hash was taken outside the chroot; a mismatch means the file changed
-    # under the build.
+    # The hash was taken outside the chroot; a mismatch means the file changed under the build.
     local got_sha; got_sha="$(sha256_of "$src")"
     if [[ "$want_sha" != "absent" && "$got_sha" != "$want_sha" ]]; then
         echo "kryptikd binary changed during the build:"
@@ -73,14 +64,12 @@ s_kryptikd() {
     install -Dm755 "$src" /usr/bin/kryptikd
     rm -f /etc/kryptik/kryptikd-absent
 
-    # It must run here: one linked against the host's libc installs fine and
-    # fails at boot.
+    # It must run here: one linked against the host's libc installs fine and fails at boot.
     echo "--- installed kryptikd ---"
     ls -la /usr/bin/kryptikd
     readelf -l /usr/bin/kryptikd 2>/dev/null | grep 'Requesting program interpreter' \
         || echo "  (static binary, no interpreter - good)"
-    # --help is the one subcommand that exits 0 and touches nothing (--version
-    # is not a subcommand); `check` would probe the build host's kernel.
+    # --help exits 0 and touches nothing; `check` would probe the build host's kernel.
     /usr/bin/kryptikd --help > /dev/null || {
         echo "FAIL: the installed kryptikd does not run inside the target."
         echo "A binary built against the host's libc installs fine and fails here."
diff --git a/build/recipes/libaio.sh b/build/recipes/libaio.sh
index c85263c4..15a8b84b 100644
--- a/build/recipes/libaio.sh
+++ b/build/recipes/libaio.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# libaio: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_libaio() {
     local src; src="$(unpack "libaio-${V_LIBAIO}.tar.gz" "libaio-${V_LIBAIO}")"
diff --git a/build/recipes/libcap.sh b/build/recipes/libcap.sh
index 44a8f523..73b1c018 100644
--- a/build/recipes/libcap.sh
+++ b/build/recipes/libcap.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# libcap: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_libcap() {
     local src; src="$(unpack "libcap-${V_LIBCAP}.tar.xz" "libcap-${V_LIBCAP}")"
diff --git a/build/recipes/libdrm.sh b/build/recipes/libdrm.sh
index 48da90b4..292f6928 100644
--- a/build/recipes/libdrm.sh
+++ b/build/recipes/libdrm.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# libdrm: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_libdrm() {
     meson_build "libdrm-${V_LIBDRM}.tar.xz" "libdrm-${V_LIBDRM}" \
diff --git a/build/recipes/libinput.sh b/build/recipes/libinput.sh
index c624e1e0..7afc879d 100644
--- a/build/recipes/libinput.sh
+++ b/build/recipes/libinput.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# libinput: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_libinput() {
     meson_build "libinput-${V_LIBINPUT}.tar.gz" "libinput-${V_LIBINPUT}" \
diff --git a/build/recipes/libxkbcommon.sh b/build/recipes/libxkbcommon.sh
index 1e547f07..8f9e65ae 100644
--- a/build/recipes/libxkbcommon.sh
+++ b/build/recipes/libxkbcommon.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# libxkbcommon: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_libxkbcommon() {
     meson_build "libxkbcommon-${V_LIBXKBCOMMON}.tar.gz" "libxkbcommon-xkbcommon-${V_LIBXKBCOMMON}" \
diff --git a/build/recipes/licences.sh b/build/recipes/licences.sh
index 1284c207..1400e30c 100644
--- a/build/recipes/licences.sh
+++ b/build/recipes/licences.sh
@@ -1,14 +1,8 @@
 #!/usr/bin/env bash
-# licences: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# Every source's licence files, from its own tarball, under
-# /usr/share/licenses/<source>/, and Kryptik's own under kryptik/. Beside the
-# top-level files: the kernel's LICENSES/preferred and exceptions, which its
-# COPYING points to, firmware's WHENCE, which says which licence covers which
-# file, and a lowercase licence file (the microcode's). Acceptance checks that
-# no shipped source is left without one (tools/check-image-licences.sh).
+# Every source's licence files, from its own tarball, under /usr/share/licenses/<source>/.
 s_licences() {
+    # Also the microcode's lowercase license, firmware's WHENCE and the kernel's LICENSES/.
     local more_re='^[^/]+/(license|WHENCE|LICENSES/(preferred|exceptions)/[^/]+)$'
     local name url f m dir tmp n=0 members
     while read -r name _ url _; do
@@ -17,16 +11,13 @@ s_licences() {
         [[ -f "$f" ]] || continue
         mapfile -t members < <(licence_members "$f" "$more_re")
         [[ "${#members[@]}" -gt 0 ]] || continue
-        # One extraction for all of them: every tar run reads the whole
-        # compressed stream, and linux-firmware has over a hundred.
+        # One extraction: every tar run reads the whole stream, and firmware has over a hundred.
         tmp="$(mktemp -d)"
         tar -xf "$f" -C "$tmp" -- "${members[@]}"
         dir="/usr/share/licenses/${name}"
         install -d -m 0755 "$dir"
         for m in "${members[@]}"; do
-            # A link to a file not extracted would dangle: there is nothing to copy.
-            # By its path below the top directory, so doc/COPYING and COPYING
-            # cannot overwrite each other.
+            # Skip a dangling link; keep the path so doc/COPYING and COPYING do not collide.
             if [[ -f "${tmp}/${m}" ]]; then
                 install -D -m 0644 "${tmp}/${m}" "${dir}/${m#*/}"
                 n=$((n + 1))
@@ -35,15 +26,12 @@ s_licences() {
         rm -rf "$tmp"
     done < <("${KRYPTIK_ROOT}/tools/fetch-sources.sh" --list)
 
-    # Licence texts that no source tarball here carries, kept in
-    # build/licences/: the MPL 2.0 of Mozilla's CA bundle, and what kryptikd
-    # and kryptik-wlproxy link statically, which is Rust's standard library,
-    # the libc crate and musl. libdrm ships no licence file either; its MIT
-    # notice heads each file of its core library, the only part built.
+    # Texts no tarball carries: the CA bundle's MPL, and Rust std, libc and musl in static binaries.
     for f in "${KRYPTIK_ROOT}"/build/licences/*/*; do
         install -D -m 0644 "$f" "/usr/share/licenses/$(basename "$(dirname "$f")")/$(basename "$f")"
         n=$((n + 1))
     done
+    # libdrm ships no licence file; its MIT notice heads each file of the core library.
     f="${KRYPTIK_SOURCES}/libdrm-${V_LIBDRM}.tar.xz"
     mapfile -t members < <(tar -tf "$f" | grep -E '^[^/]+/[^/]+\.c$' || true)
     [[ "${#members[@]}" -gt 0 ]] || { echo "FAIL: no C files at the top of ${f##*/}"; return 1; }
diff --git a/build/recipes/locales.sh b/build/recipes/locales.sh
index 292de087..731429f7 100644
--- a/build/recipes/locales.sh
+++ b/build/recipes/locales.sh
@@ -1,10 +1,6 @@
 #!/usr/bin/env bash
-# locales: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# Locales, with stage 01's localedef, first and apart from the glibc rebuild:
-# perl needs them (Configure probes LC_ALL), and glibc's rebuild waits for
-# python, which comes after perl.
+# Early, with stage 01's localedef: perl's Configure probes LC_ALL, and glibc waits for python.
 s_locales() {
     mkdir -p /usr/lib/locale
     localedef -i C -f UTF-8 C.UTF-8
diff --git a/build/recipes/lvm2.sh b/build/recipes/lvm2.sh
index 7b5015df..52055c62 100644
--- a/build/recipes/lvm2.sh
+++ b/build/recipes/lvm2.sh
@@ -1,9 +1,6 @@
 #!/usr/bin/env bash
-# lvm2: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# Only device-mapper from LVM2: libdevmapper for cryptsetup, dmsetup for an
-# operator. No lvm binary, daemons or volume udev rules.
+# Only device-mapper: libdevmapper for cryptsetup and dmsetup for an operator; no lvm or daemons.
 s_lvm2() {
     local src; src="$(unpack "LVM2.${V_LVM2}.tgz" "LVM2.${V_LVM2}")"
     cd "$src"
@@ -11,11 +8,9 @@ s_lvm2() {
         --disable-readline --disable-selinux --with-default-dm-run-dir=/run \
         --enable-udev_sync --disable-silent-rules
     make device-mapper
-    # -j1: the install target's two sub-makes both rebuild dmsetup, and in
-    # parallel one links while the other rewrites dmsetup.o.
+    # -j1: both sub-makes of the install rebuild dmsetup and race on dmsetup.o.
     make -j1 install_device-mapper
-    # The library line shows the binary runs. The driver line after it needs
-    # the build machine's device-mapper, and dmsetup fails without it.
+    # The library line proves it runs; the driver line needs the host's device-mapper.
     local out; out="$(dmsetup --version 2>&1 || true)"
     grep -m1 '^Library version:' <<<"$out" || { echo "dmsetup does not run: ${out}"; return 1; }
     [[ -f /usr/lib/pkgconfig/devmapper.pc ]] || { echo "no devmapper.pc"; return 1; }
diff --git a/build/recipes/lynx.sh b/build/recipes/lynx.sh
index 1654cffe..d2983944 100644
--- a/build/recipes/lynx.sh
+++ b/build/recipes/lynx.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# lynx: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_lynx() {
     local src; src="$(unpack "lynx${V_LYNX}.tar.bz2" "lynx${V_LYNX}")"
diff --git a/build/recipes/man-db.sh b/build/recipes/man-db.sh
index ac6502bb..e75b5ebb 100644
--- a/build/recipes/man-db.sh
+++ b/build/recipes/man-db.sh
@@ -1,13 +1,10 @@
 #!/usr/bin/env bash
-# man-db: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_man_db() {
     local src; src="$(unpack "man-db-${V_MANDB}.tar.xz" "man-db-${V_MANDB}")"
     cd "$src"
 
     # --disable-setuid: no setuid man parsing untrusted files for a page cache.
-    # No browser/vgrind/grap paths: those programs are not on the system.
     ./configure --prefix=/usr \
         --docdir="/usr/share/doc/man-db-${V_MANDB}" \
         --sysconfdir=/etc \
diff --git a/build/recipes/meson.sh b/build/recipes/meson.sh
index 67076775..2c64c552 100644
--- a/build/recipes/meson.sh
+++ b/build/recipes/meson.sh
@@ -1,9 +1,6 @@
 #!/usr/bin/env bash
-# meson: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# meson runs uninstalled from its own tree, avoiding the unpinned pip, wheel
-# and setuptools.
+# meson runs from its own tree, so no unpinned pip, wheel or setuptools.
 s_meson() {
     local src; src="$(unpack "meson-${V_MESON}.tar.gz" "meson-${V_MESON}")"
     rm -rf /usr/lib/meson
diff --git a/build/recipes/netzone.sh b/build/recipes/netzone.sh
index 3ff780d6..e3232d7a 100644
--- a/build/recipes/netzone.sh
+++ b/build/recipes/netzone.sh
@@ -1,9 +1,6 @@
 #!/usr/bin/env bash
-# netzone: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# The net zone's startup program (docs/design/net-zone.md): dhcpcd, nftables
-# NAT and dnsmasq in the zone that holds the NIC, run by the net-zone service.
+# The net zone's startup program (docs/design/net-zone.md): DHCP, NAT and DNS beside the NIC.
 s_netzone() {
     local src="${KRYPTIK_ROOT}/tools/net/netzone-init.sh"
     [[ -f "$src" ]] || { echo "no netzone-init at ${src}"; return 1; }
diff --git a/build/recipes/ninja.sh b/build/recipes/ninja.sh
index 0bd723ee..ade6a66a 100644
--- a/build/recipes/ninja.sh
+++ b/build/recipes/ninja.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# ninja: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_ninja() {
     local src; src="$(unpack "ninja-${V_NINJA}.tar.gz" "ninja-${V_NINJA}")"
diff --git a/build/recipes/openssh.sh b/build/recipes/openssh.sh
index 9ff52268..49c6e711 100644
--- a/build/recipes/openssh.sh
+++ b/build/recipes/openssh.sh
@@ -1,8 +1,6 @@
 #!/usr/bin/env bash
-# openssh: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# Only ssh-keygen, whose -Y verifies them; no sshd, ssh or host keys.
+# Only ssh-keygen, whose -Y verifies update manifests; no sshd, ssh or host keys.
 s_openssh() {
     local src; src="$(unpack "openssh-${V_OPENSSH}.tar.gz" "openssh-${V_OPENSSH}")"
     cd "$src"
@@ -11,8 +9,7 @@ s_openssh() {
         --with-pid-dir=/run --without-pam
     make ssh-keygen
     install -m 0755 ssh-keygen /usr/bin/ssh-keygen
-    # Captured, not piped: the usage exits non-zero. Without -Y ssh-keygen says
-    # "unknown option -- Y"; with it, it complains of missing arguments.
+    # Captured, as the usage exits non-zero; with no -Y support it says "unknown option -- Y".
     local out
     out="$(ssh-keygen -Y verify 2>&1 || true)"
     case "$out" in
diff --git a/build/recipes/openssl.sh b/build/recipes/openssl.sh
index bd95d8cd..a0f438c4 100644
--- a/build/recipes/openssl.sh
+++ b/build/recipes/openssl.sh
@@ -1,12 +1,9 @@
 #!/usr/bin/env bash
-# openssl: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_openssl() {
     local src; src="$(unpack "openssl-${V_OPENSSL}.tar.gz" "openssl-${V_OPENSSL}")"
     cd "$src"
-    # No enable-ktls: crypto in the kernel widens the surface a kernel bug
-    # exposes to every zone at once (ADR-002).
+    # No enable-ktls: kernel crypto widens what a kernel bug exposes to every zone (ADR-002).
     ./config --prefix=/usr --openssldir=/etc/ssl --libdir=lib \
         shared zlib-dynamic
     make
diff --git a/build/recipes/perl.sh b/build/recipes/perl.sh
index 33ef7ada..312ed8d6 100644
--- a/build/recipes/perl.sh
+++ b/build/recipes/perl.sh
@@ -1,15 +1,11 @@
 #!/usr/bin/env bash
-# perl: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_perl() {
     local src; src="$(unpack "perl-${V_PERL}.tar.xz" "perl-${V_PERL}")"
     cd "$src"
-    # Configure reads neither CFLAGS nor LDFLAGS, so the hardening goes in as
-    # its own settings. lddlflags names -shared because a value given for it
-    # replaces Configure's default instead of adding to it. No GDBM_File: perl
-    # is built before gdbm, and nothing needs the binding, so the build must
-    # not depend on whether an older sysroot has gdbm already.
+    # Configure ignores CFLAGS and LDFLAGS, so the hardening goes in as its own settings.
+    # -shared: a given lddlflags replaces Configure's default instead of adding to it.
+    # No GDBM_File: nothing needs it, and the build must not depend on a cached gdbm.
     sh Configure -des \
         -Dprefix=/usr \
         -Dvendorprefix=/usr \
@@ -22,7 +18,6 @@ s_perl() {
         -Dnoextensions=GDBM_File
     make
     make install
-    # A sysroot from an earlier build may hold the module a rebuild after gdbm
-    # once made; nothing else removes what a step no longer installs.
+    # A cached sysroot may hold the module from a build that saw gdbm; nothing else removes it.
     rm -rf /usr/lib/perl5/*/*/auto/GDBM_File /usr/lib/perl5/*/*/GDBM_File.pm
 }
diff --git a/build/recipes/pkgconf.sh b/build/recipes/pkgconf.sh
index ac815031..29e1d774 100644
--- a/build/recipes/pkgconf.sh
+++ b/build/recipes/pkgconf.sh
@@ -1,9 +1,6 @@
 #!/usr/bin/env bash
-# pkgconf: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# pkgconf installs as pkgconf and everything asks for pkg-config, with no
-# configure option for the name: link it by hand, as LFS does.
+# pkgconf has no option to install as pkg-config, which everything asks for: link it, as LFS does.
 s_pkgconf() {
     native_build "pkgconf-${V_PKGCONF}.tar.xz" "pkgconf-${V_PKGCONF}" \
         --disable-static --docdir="/usr/share/doc/pkgconf-${V_PKGCONF}"
diff --git a/build/recipes/python.sh b/build/recipes/python.sh
index f6e3a472..9d8e7756 100644
--- a/build/recipes/python.sh
+++ b/build/recipes/python.sh
@@ -1,20 +1,15 @@
 #!/usr/bin/env bash
-# python: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_python() {
     local src; src="$(unpack "Python-${V_PYTHON}.tar.xz" "Python-${V_PYTHON}")"
     cd "$src"
-    # This python only serves glibc's configure. No --enable-optimizations: its
-    # PGO pass fails to link (libgcov) and triples the build time. No
-    # --with-system-expat: expat is not built yet.
+    # Only for glibc's configure; no PGO, which fails to link (libgcov), and no system expat yet.
     ./configure --prefix=/usr --enable-shared
     make
     make install
 }
 
-# The full python, rebuilt over the early one after libffi, openssl, expat and
-# readline. The step fails unless ctypes, ssl, pyexpat and readline import.
+# The full python, once libffi, openssl, expat and readline exist; their modules must import.
 s_python_final() {
     local src; src="$(unpack "Python-${V_PYTHON}.tar.xz" "Python-${V_PYTHON}")"
     cd "$src"
diff --git a/build/recipes/readline.sh b/build/recipes/readline.sh
index ea698d30..5b847c59 100644
--- a/build/recipes/readline.sh
+++ b/build/recipes/readline.sh
@@ -1,17 +1,14 @@
 #!/usr/bin/env bash
-# readline: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# shobj-conf links the libraries with an rpath to /usr/lib, where the loader
-# looks anyway. Without --with-shared-termcap-library, libreadline does not
-# name the curses library it calls, and bc and python then build without it.
 s_readline() {
     local src; src="$(unpack "readline-${V_READLINE}.tar.gz" "readline-${V_READLINE}")"
     cd "$src"
     # GNU's official patches, which the tarball does not carry (see the README).
     apply_repo_patches "readline-${V_READLINE}"
     [[ "$(tail -1 patchlevel)" == 6 ]] || { echo "FAIL: readline is not at patch level 6"; return 1; }
+    # shobj-conf's rpath to /usr/lib is redundant: the loader looks there anyway.
     sed -i 's/-Wl,-rpath,[^ ]*//' support/shobj-conf
+    # --with-shared-termcap-library, or libreadline names no curses and bc and python skip readline.
     ./configure --prefix=/usr --disable-static --with-curses \
         --with-shared-termcap-library
     make
diff --git a/build/recipes/s6.sh b/build/recipes/s6.sh
index 5633e035..99ef4d45 100644
--- a/build/recipes/s6.sh
+++ b/build/recipes/s6.sh
@@ -1,10 +1,7 @@
 #!/usr/bin/env bash
-# s6: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_s6_stack() {
-    # ADR-006. skarnet packages use their own configure conventions. Whole
-    # tarball names, so the step's stamp hashes each one.
+    # ADR-006. Whole tarball names, so the step's stamp hashes each one.
     local tb p
     for tb in "skalibs-${V_SKALIBS}.tar.gz" "execline-${V_EXECLINE}.tar.gz" \
               "s6-${V_S6}.tar.gz" "s6-rc-${V_S6_RC}.tar.gz" \
@@ -14,8 +11,7 @@ s_s6_stack() {
         local src; src="$(unpack "$tb" "$p")"
         cd "$src"
 
-        # --skeldir: with --prefix=/usr the skeleton would land in /usr/etc,
-        # where s6-linux-init-maker does not look, leaving no stage 2 scripts.
+        # --skeldir: under --prefix=/usr it is /usr/etc, where s6-linux-init-maker never looks.
         local extra=()
         case "$p" in
             s6-linux-init-*) extra=(--skeldir=/etc/s6-linux-init/skel) ;;
diff --git a/build/recipes/seatd.sh b/build/recipes/seatd.sh
index 72ebb1ec..0fa658a8 100644
--- a/build/recipes/seatd.sh
+++ b/build/recipes/seatd.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# seatd: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_seatd() {
     meson_build "${V_SEATD}.tar.gz" "seatd-${V_SEATD}" \
diff --git a/build/recipes/shadow.sh b/build/recipes/shadow.sh
index 6cf7f0f7..3d10c2cb 100644
--- a/build/recipes/shadow.sh
+++ b/build/recipes/shadow.sh
@@ -1,14 +1,11 @@
 #!/usr/bin/env bash
-# shadow: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_shadow() {
     local src; src="$(unpack "shadow-${V_SHADOW}.tar.xz" "shadow-${V_SHADOW}")"
     cd "$src"
     # build/patches/shadow-4.16.0 (see its README): upstream's sgetgrent fix from 4.17.0.
     apply_repo_patches "shadow-${V_SHADOW}"
-    # Kryptik does not ship groups(1) or the *chage man pages that conflict
-    # with coreutils/man-pages.
+    # No groups(1) or its man page: coreutils provides groups.
     sed -i 's/groups$(EXEEXT) //' src/Makefile.in
     find man -name Makefile.in -exec sed -i 's/groups\.1 / /' {} \;
 
@@ -22,7 +19,6 @@ s_shadow() {
         --without-libbsd --with-group-name-max-length=32
     make
     make exec_prefix=/usr install
-    # Privilege from a bit is su's and passwd's alone
-    # (build/config/setuid-allowlist.txt); the rest run unprivileged or not at all.
+    # Only su and passwd keep a setuid bit (build/config/setuid-allowlist.txt).
     chmod ug-s /usr/bin/{chage,chfn,chsh,expiry,gpasswd,newgidmap,newgrp,newuidmap}
 }
diff --git a/build/recipes/tar.sh b/build/recipes/tar.sh
index b7cafc16..d30fb786 100644
--- a/build/recipes/tar.sh
+++ b/build/recipes/tar.sh
@@ -1,9 +1,6 @@
 #!/usr/bin/env bash
-# tar: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# tar 1.35 defines private acl_*_at functions that libacl 2.4.0 now declares;
-# build/patches/tar-1.35 (see its README) carries upstream's rename.
+# tar 1.35's private acl_*_at functions clash with libacl 2.4.0's; the patch set renames them.
 s_tar() {
     local src; src="$(unpack "tar-${V_TAR}.tar.xz" "tar-${V_TAR}")"
     cd "$src"
diff --git a/build/recipes/tests.sh b/build/recipes/tests.sh
index 22da4a21..3c9d84a0 100644
--- a/build/recipes/tests.sh
+++ b/build/recipes/tests.sh
@@ -1,10 +1,6 @@
 #!/usr/bin/env bash
-# tests: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# The suites and guest checks, in the image, so the VM drivers run them as root
-# on the installed kernel. They find their tree as $HERE/../.., hence
-# /usr/lib/kryptik/compartments/tests beside a kryptikd link at their default.
+# The suites in the image, laid out as in the repository: they find their tree as $HERE/../..
 s_tests() {
     echo "inputs digest: ${1:-none}"
     local base=/usr/lib/kryptik
@@ -17,8 +13,7 @@ s_tests() {
     for t in "${KRYPTIK_ROOT}"/compartments/kryptikd/probes/*.sh; do
         install -m 0755 "$t" "$base/compartments/kryptikd/probes/$(basename "$t")"
     done
-    # adversarial.sh checks its namespace set against isolate.rs and its proc
-    # and sysfs mounts against rootfs.rs.
+    # adversarial.sh checks its namespaces against isolate.rs and its mounts against rootfs.rs.
     for src in isolate.rs rootfs.rs; do
         install -m 0644 "${KRYPTIK_ROOT}/compartments/kryptikd/src/${src}" "$base/compartments/kryptikd/src/${src}"
     done
diff --git a/build/recipes/updater.sh b/build/recipes/updater.sh
index 95b909ba..4bf3f92e 100644
--- a/build/recipes/updater.sh
+++ b/build/recipes/updater.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# updater: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_updater() {
     local src="${KRYPTIK_ROOT}/tools/update/kryptik-update"
diff --git a/build/recipes/wayland.sh b/build/recipes/wayland.sh
index 07645226..c1da4328 100644
--- a/build/recipes/wayland.sh
+++ b/build/recipes/wayland.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# wayland: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_wayland() {
     meson_build "wayland-${V_WAYLAND}.tar.xz" "wayland-${V_WAYLAND}" \
diff --git a/build/recipes/wlroots.sh b/build/recipes/wlroots.sh
index 3b602e31..269fa5d0 100644
--- a/build/recipes/wlroots.sh
+++ b/build/recipes/wlroots.sh
@@ -1,9 +1,6 @@
 #!/usr/bin/env bash
-# wlroots: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# wlroots with the pixman renderer only: GLES2, Vulkan and GBM need Mesa and
-# LLVM. The DRM backend uses dumb buffers, which virtio-gpu and simpledrm have.
+# The pixman renderer only, as the others need Mesa; virtio-gpu and simpledrm take dumb buffers.
 s_wlroots() {
     meson_build "wlroots-${V_WLROOTS}.tar.gz" "wlroots-${V_WLROOTS}" \
         -Dxwayland=disabled -Dexamples=false -Drenderers=[] -Dallocators=[] \
diff --git a/build/recipes/wpa-supplicant.sh b/build/recipes/wpa-supplicant.sh
index f45edd15..37a6f30a 100644
--- a/build/recipes/wpa-supplicant.sh
+++ b/build/recipes/wpa-supplicant.sh
@@ -1,13 +1,6 @@
 #!/usr/bin/env bash
-# wpa-supplicant: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
-# wpa_supplicant from its own .config: nl80211 through libnl, the unix control
-# interface for wpa_cli (no D-Bus or readline), OpenSSL for WPA3-SAE, OWE, DPP
-# and enterprise EAP, 802.11r and protected management frames, and AP mode,
-# which only the zones suite uses: its access point on mac80211_hwsim is this
-# binary in a namespace of its own. Its Makefile takes CFLAGS from the
-# environment, so the hardening flags apply.
+# CONFIG_AP is for the zones suite, whose hwsim access point is this binary in its own namespace.
 s_wpa_supplicant() {
     local src; src="$(unpack "wpa_supplicant-${V_WPA_SUPPLICANT}.tar.gz" "wpa_supplicant-${V_WPA_SUPPLICANT}")"
     cd "$src/wpa_supplicant"
diff --git a/build/recipes/xz.sh b/build/recipes/xz.sh
index 2e36dbf5..0dc20f6d 100644
--- a/build/recipes/xz.sh
+++ b/build/recipes/xz.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# xz: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_xz_native() {
     native_build "xz-${V_XZ}.tar.xz" "xz-${V_XZ}" \
diff --git a/build/recipes/zlib.sh b/build/recipes/zlib.sh
index acec3729..bb2d4945 100644
--- a/build/recipes/zlib.sh
+++ b/build/recipes/zlib.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# zlib: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_zlib() {
     local src; src="$(unpack "zlib-${V_ZLIB}.tar.gz" "zlib-${V_ZLIB}")"
diff --git a/build/recipes/zstd.sh b/build/recipes/zstd.sh
index 4001ec4f..9664889d 100644
--- a/build/recipes/zstd.sh
+++ b/build/recipes/zstd.sh
@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# zstd: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
-# which runs it in the order its list gives.
 
 s_zstd() {
     local src; src="$(unpack "zstd-${V_ZSTD}.tar.gz" "zstd-${V_ZSTD}")"
diff --git a/build/service-scripts/ask.sh b/build/service-scripts/ask.sh
index 922f20b7..fb2eae23 100755
--- a/build/service-scripts/ask.sh
+++ b/build/service-scripts/ask.sh
@@ -1,13 +1,10 @@
 #!/bin/sh
-# What a boot service asks a person, asked on every console the kernel writes
-# to: a machine with a serial port prefers it for /dev/console, but its user
-# may be at the screen, and a VM's may be on the serial port alone. POSIX sh,
-# sourced by sysinit and firstboot.
+# Boot-time questions on every console: /dev/console may be a serial port the person is not at.
+# POSIX sh, sourced by sysinit and firstboot.
 #   consoles           the console devices, one per line
 #   tell LINE...       each LINE on every console
-#   ask [-s] SECS Q    Q on every console; the first line typed on any of them
-#                      goes to stdout. -s keeps echo off, SECS 0 waits for
-#                      ever, and it fails when nothing is typed in time.
+#   ask [-s] SECS Q    Q on every console; the first line typed on any goes to stdout.
+#                      -s keeps echo off; SECS 0 waits forever; fails if nothing comes in time.
 
 ask_dir=/run/kryptik
 
@@ -25,10 +22,7 @@ tell() {
     done
 }
 
-# One reader per console; the first to finish a line wins and the rest are
-# stopped. Echo goes off before the question and stty never discards input,
-# so an early answer is not lost. printf is a builtin: the answer is never an
-# argument.
+# One reader per console, first line wins; stty never discards input, so an early answer is kept.
 ask() {
     _a_quiet=''
     [ "$1" = -s ] && { _a_quiet=1; shift; }
@@ -77,5 +71,6 @@ ask() {
         { echo > "$_a_dev"; } 2>/dev/null || true
     done
     [ -n "$_a_from" ] || return 1
+    # printf is a builtin, so the answer never appears as an argument.
     printf '%s' "$_a_ans"
 }
diff --git a/build/service-scripts/boot-smoke.sh b/build/service-scripts/boot-smoke.sh
index 893c4393..38796ad3 100755
--- a/build/service-scripts/boot-smoke.sh
+++ b/build/service-scripts/boot-smoke.sh
@@ -1,6 +1,5 @@
 #!/bin/sh
-# Report what this machine is, on the console, every boot. The poweroff at the
-# end runs only when a test control disk asks (testctl.sh, install media only).
+# Report the machine on the console every boot; power off only when a test control disk asks.
 . /usr/libexec/kryptik/testctl.sh
 
 say() { echo "KRYPTIK_SMOKE: $*"; }
@@ -29,10 +28,9 @@ fi
 say "efi=$([ -d /sys/firmware/efi ] && echo yes || echo no)"
 say "secureboot=$({ od -An -tu1 -j4 -N1 /sys/firmware/efi/efivars/SecureBoot-8be4df61-93ca-11d2-aa0d-00e098032b8c 2>/dev/null || echo unreadable; } | tr -d ' ')"
 
-# --- the filesystem we booted from ----------------------------------------
-# A root the kernel mounted shows as /dev/root; name the real device from
-# mountinfo's major:minor.
+# --- the filesystem we booted from ------------------------------------------
 root_line="$(awk '$2=="/"{print $1, $3, $4; exit}' /proc/mounts)"
+# A root the kernel mounted shows as /dev/root: name its device from mountinfo's major:minor.
 case "$root_line" in
     /dev/root*)
         mm="$(awk '$5=="/"{print $3; exit}' /proc/self/mountinfo 2>/dev/null)"
@@ -87,10 +85,10 @@ for k in kernel.kptr_restrict kernel.dmesg_restrict kernel.yama.ptrace_scope \
     v=$(sysctl -n "$k" 2>/dev/null || echo "unreadable")
     say "sysctl $k=$v"
 done
-# The allocator this very process runs on, read from its own mappings.
+# The allocator, read from grep's own mappings.
 say "allocator=$(grep -q /usr/lib/libhardened_malloc.so /proc/self/maps && echo hardened_malloc || echo libc)"
 
-# --- the zone model, on this kernel ---------------------------------------
+# --- the zone model, on this kernel -----------------------------------------
 say "kryptikd_check_begin"
 /usr/bin/kryptikd check --zones /usr/lib/kryptik/zones 2>&1 | sed 's/^/KRYPTIK_SMOKE: kd: /'
 say "kryptikd_check_rc=$?"
@@ -100,13 +98,12 @@ say "lsm=$(cat /sys/kernel/security/lsm 2>/dev/null || echo unreadable)"
 say "microcode=$(awk -F': ' '/^microcode/ {print $2; exit}' /proc/cpuinfo 2>/dev/null) loader=$(dmesg 2>/dev/null | grep -m1 -o 'microcode: .*' || echo none)"
 say "cgroup2=$(awk '$3=="cgroup2"{print $2; exit}' /proc/mounts 2>/dev/null || echo none)"
 
-# --- users and the login path -------------------------------------------
+# --- users and the login path -----------------------------------------------
 say "users=$(awk -F: '$3>=1000 && $3<65534 {printf "%s ", $1}' /etc/passwd 2>/dev/null)"
 say "root_password=$(awk -F: '$1=="root"{print ($2 ~ /^[!*]/ || $2=="") ? "none" : "set"}' /etc/shadow 2>/dev/null)"
 say "securetty=$([ -e /etc/securetty ] && echo "present ($(wc -l < /etc/securetty) lines)" || echo absent)"
 say "login_binary=$([ -x /usr/bin/login ] && echo present || echo MISSING)"
-# The serial getty a test driver logs in at. From the host a stuck one looks
-# like a healthy boot, so record its state here.
+# A stuck serial getty looks like a healthy boot from the host, so record its state.
 for svc in /run/service/*early-getty*; do
     [ -d "$svc" ] || continue
     say "early_getty=$(s6-svstat "$svc" 2>&1 | head -c 160)"
@@ -129,15 +126,14 @@ fi
 say "END"
 echo
 
-# --- power off only when a test asked, and only on install media -----------
+# --- power off only when a test asked, and only on install media ------------
 if testctl_load && [ "$(testctl_get smoke_poweroff)" = "1" ]; then
-    # An install requested too runs from its own service: give it install_wait.
+    # An install asked for as well runs in its own service; install_wait gives it time.
     wait_s="$(testctl_get install_wait)"
     [ -n "$wait_s" ] && sleep "$wait_s"
     say "POWEROFF"
     say "shutdownd_fifo=$( [ -p /run/service/s6-linux-init-shutdownd/fifo ] && echo present || echo absent )"
-    # If the clean poweroff does not take effect, say so (the host checks for
-    # that line) and force it.
+    # If the clean poweroff does not take effect, say so (the host checks) and force it.
     setsid sh -c 'sleep 90
         echo "KRYPTIK_SMOKE: POWEROFF_DID_NOT_TAKE_EFFECT after 90s" > /dev/console 2>/dev/null
         sync
diff --git a/build/service-scripts/devices.sh b/build/service-scripts/devices.sh
index 9afc607a..0ae84c1d 100755
--- a/build/service-scripts/devices.sh
+++ b/build/service-scripts/devices.sh
@@ -1,10 +1,8 @@
 #!/bin/sh
-# Which partitions belong to this installation: those with the right GPT label
-# on the disk the running root came from, since another disk (a clone, an old
-# install) can carry the same labels. POSIX sh, sourced by services and tools.
+# Partitions by GPT label on the root's own disk only: another disk may carry the same labels.
+# POSIX sh, sourced by services and tools.
 #   kryptik_root_disk         the disk under the root, via dm and loop devices
-#   kryptik_part LABEL        the one partition with LABEL there; fails on none
-#                             or several, never picks one
+#   kryptik_part LABEL        the one partition with LABEL there; fails on none or several
 #   kryptik_part_count LABEL  how many carry LABEL there
 #   kryptik_others LABEL      partitions with LABEL on other disks
 
@@ -72,8 +70,7 @@ kryptik_others() {   # LABEL -> partitions with LABEL that are NOT on the root d
     done
 }
 
-# Run as a command (by kryptik-efiboot):
-#   devices.sh disk | part LABEL | count LABEL | others LABEL
+# As a command, for kryptik-efiboot.
 case "${0##*/}" in
     devices.sh)
         case "${1:-}" in
diff --git a/build/service-scripts/eudev-trigger.sh b/build/service-scripts/eudev-trigger.sh
index ab55eb54..64e4f457 100755
--- a/build/service-scripts/eudev-trigger.sh
+++ b/build/service-scripts/eudev-trigger.sh
@@ -1,6 +1,5 @@
 #!/bin/sh -e
-# Replay devices that existed before udevd started, then settle, so a later
-# service does not race a node that is about to appear.
+# Replay the devices udevd missed and settle, so no later service races a node about to appear.
 /usr/sbin/udevadm trigger --action=add --type=subsystems
 /usr/sbin/udevadm trigger --action=add --type=devices
 /usr/sbin/udevadm settle --timeout=30 || echo "eudev-trigger: settle timed out" >&2
diff --git a/build/service-scripts/kryptikd-check.sh b/build/service-scripts/kryptikd-check.sh
index a1584b4f..0db49dae 100755
--- a/build/service-scripts/kryptikd-check.sh
+++ b/build/service-scripts/kryptikd-check.sh
@@ -1,6 +1,5 @@
 #!/bin/sh
-# Log whether kryptikd can read the zones and the kernel supports them. Not -e:
-# a machine that cannot start zones must still boot far enough to debug.
+# Log kryptikd's zone and kernel checks; no -e, so a machine without zones still boots to debug.
 log=/var/log/kryptik/kryptikd-check.log
 mkdir -p /var/log/kryptik
 {
diff --git a/build/service-scripts/watchdog.sh b/build/service-scripts/watchdog.sh
index f2ec6220..faba74dc 100755
--- a/build/service-scripts/watchdog.sh
+++ b/build/service-scripts/watchdog.sh
@@ -1,8 +1,6 @@
 #!/bin/bash
-# Feed every registered watchdog while this process gets scheduled, and check
-# nothing else: rebooting over a crashed service is worse than a hang.
-# WATCHDOG_NOWAYOUT: closing a device does not stop it, so the supervisor must
-# restart this within the timeout, and a shutdown that hangs gets reset.
+# Only feed the watchdogs: rebooting over a crashed service is worse than a hang.
+# With NOWAYOUT a closed device keeps counting, so a hung shutdown resets the machine.
 set -u
 fds=()
 for dev in /dev/watchdog[0-9]*; do
diff --git a/build/services/getty-tty1/run b/build/services/getty-tty1/run
index b80c4068..3668f3e8 100755
--- a/build/services/getty-tty1/run
+++ b/build/services/getty-tty1/run
@@ -1,8 +1,7 @@
 #!/bin/sh
-# Authenticated login on tty1; the desktop session starts from the user's
-# profile. An install medium's passwordless root shell is here as well as on a
-# serial console (kryptik-console), since whoever installs may be at either.
+# Install media get a root shell here as on serial: whoever installs may be at either.
 if grep -qw 'kryptik\.media=[a-z]' /proc/cmdline 2>/dev/null; then
     exec /usr/sbin/agetty -n -l /usr/bin/bash --noclear tty1 linux
 fi
+# A login; the user's profile starts the desktop session.
 exec /usr/sbin/agetty --noclear tty1 linux
diff --git a/build/services/getty-tty2/run b/build/services/getty-tty2/run
index 01c6da73..7a78c55b 100755
--- a/build/services/getty-tty2/run
+++ b/build/services/getty-tty2/run
@@ -1,5 +1,3 @@
 #!/bin/sh
-# A text login on tty2 (Ctrl+Alt+F2) for administration: the profile starts
-# the desktop on tty1 only, so a login here is a shell, and root is su from
-# wheel.
+# Admin login on tty2 (Ctrl+Alt+F2): the profile starts the desktop on tty1 only.
 exec /usr/sbin/agetty --noclear tty2 linux
diff --git a/build/services/kryptikd-serve/run b/build/services/kryptikd-serve/run
index a519f36c..f5af64e7 100755
--- a/build/services/kryptikd-serve/run
+++ b/build/services/kryptikd-serve/run
@@ -1,4 +1,3 @@
 #!/bin/sh
-# The launch daemon: the only path from the desktop session (group kryptik) to
-# zone creation, which needs root. Supervised, so a crash restarts it.
+# The launch daemon: the session's only way to zone creation, which needs root.
 exec /usr/bin/kryptikd serve --zones /usr/lib/kryptik/zones --rootfs /var/lib/kryptik/zones
diff --git a/build/services/net-zone/run b/build/services/net-zone/run
index 1363a848..4bc6a0ca 100755
--- a/build/services/net-zone/run
+++ b/build/services/net-zone/run
@@ -1,8 +1,5 @@
 #!/bin/sh
-# The net zone, sole holder of the physical NICs: every interface on a bus
-# device (`nic = "*"`, kryptikd's netzone::physical_interfaces). Ephemeral, so
-# no --passphrase-file. Waits for such an interface rather than failing in a
-# restart loop: drivers are modules, and a radio or a dock can appear later.
+# The net zone takes every NIC on a bus device (`nic = "*"`, netzone::physical_interfaces).
 have_nic() {
     for d in /sys/class/net/*; do
         case "${d##*/}" in lo) continue ;; esac
@@ -10,6 +7,7 @@ have_nic() {
     done
     return 1
 }
+# Wait for one, not a restart loop: drivers are modules, and a radio or a dock can come later.
 if ! have_nic; then
     echo "net-zone: no physical network interface yet; waiting for one"
     while ! have_nic; do sleep 5; done
diff --git a/build/services/watchdog/run b/build/services/watchdog/run
index d8eecd3f..21cb0aa0 100755
--- a/build/services/watchdog/run
+++ b/build/services/watchdog/run
@@ -1,5 +1,3 @@
 #!/bin/sh
-# Watchdog feeder, restarted well inside the timeout if it dies. If it stops
-# being scheduled the machine reboots; in an A/B trial BootNext is spent by
-# then, so the reboot lands on the committed slot.
+# A starved feeder reboots the machine, which in an A/B trial lands on the committed slot.
 exec /usr/libexec/kryptik/watchdog.sh
diff --git a/build/stages/00-host-check.sh b/build/stages/00-host-check.sh
index 2b1dd243..929c0f0c 100755
--- a/build/stages/00-host-check.sh
+++ b/build/stages/00-host-check.sh
@@ -24,8 +24,7 @@ check_version() {
     fi
 }
 
-# First dotted version number in a command's output. No pipeline: under
-# pipefail, a reader that exits early (head -1, grep -q) fails the writer.
+# First dotted version in a command's output; no pipe, as an early-exiting reader fails the writer.
 ver_of() {
     local out
     out="$("$@" 2>&1 || true)"
@@ -96,8 +95,7 @@ else
     warn "yacc is not bison — some packages will fail to build"; WARN=$((WARN + 1))
 fi
 
-# Measure where the build writes: CI keeps KRYPTIK_WORK on a large second
-# disk, apart from the checkout's small root disk.
+# Measure where the build writes: CI keeps KRYPTIK_WORK on a large second disk.
 space_dir="${KRYPTIK_WORK:-$KRYPTIK_ROOT/build/work}"
 mkdir -p "$space_dir" 2>/dev/null || space_dir="$KRYPTIK_ROOT"
 avail_gb=$(df -BG --output=avail "$space_dir" 2>/dev/null | tail -1 | tr -dc '0-9' || echo 0)
diff --git a/build/stages/01-toolchain.sh b/build/stages/01-toolchain.sh
index 82fe0602..e5e29bb9 100755
--- a/build/stages/01-toolchain.sh
+++ b/build/stages/01-toolchain.sh
@@ -5,9 +5,7 @@
 source "$(dirname "${BASH_SOURCE[0]}")/../lib/common.sh"
 load_config
 
-# No hardening flags: pass-1 GCC implements -fstack-protector and cannot be
-# built with it, and host CFLAGS leak into a cross build. Hardening starts at
-# stage 04 (docs/hardening.md).
+# No flags before stage 04: pass-1 GCC cannot build with the SSP it provides, and host flags leak in.
 unset CFLAGS CXXFLAGS LDFLAGS CPPFLAGS LD_LIBRARY_PATH
 
 require_outside_chroot "stage 01"
@@ -21,7 +19,7 @@ KRYPTIK_JOBS="${KRYPTIK_JOBS:-$(kryptik_default_jobs)}"
 export MAKEFLAGS="-j${KRYPTIK_JOBS}"
 umask 022
 
-# The host gcc builds this stage.
+# The host gcc: the cross one exists only halfway through this stage.
 stage_contract "${BASH_SOURCE[0]}" "" gcc
 
 STAMPS="${KRYPTIK_WORK}/.stamps"
@@ -80,8 +78,7 @@ s_gcc_pass1() {
 
     mkdir -p build
     cd build
-    # Default PIE and SSP are built into the compiler, so a package that
-    # forgets the flags still gets them (docs/hardening.md).
+    # Default PIE and SSP in the compiler, so a package that drops the flags still gets them.
     ../configure \
         --target="$LFS_TGT" \
         --prefix="${LFS}/tools" \
@@ -120,8 +117,7 @@ s_linux_headers() {
     make headers
     find usr/include -type f ! -name "*.h" -delete
 
-    # Clear old headers first, or a V_LINUX bump leaves behind files the new
-    # kernel dropped and glibc builds against a mix of two versions.
+    # Cleared first, or a V_LINUX bump leaves headers the new kernel dropped for glibc to mix in.
     rm -rf "${LFS}/usr/include"
     cp -rv usr/include "${LFS}/usr"
 
@@ -155,9 +151,7 @@ s_glibc() {
         echo "note: FHS patch absent, continuing without it"
     fi
 
-    # Upstream's release/2.40/master branch plus the bug 33088 fix, without
-    # which GCC 14 makes ld.so record its own map at address 0 (see the patch
-    # set's README). Stage 04 applies the same set to the final glibc.
+    # release/2.40 plus the bug 33088 fix (see the README); stage 04 applies the same set.
     apply_repo_patches "glibc-${V_GLIBC}"
 
     mkdir -p build
@@ -173,8 +167,7 @@ s_glibc() {
         libc_cv_slibdir=/usr/lib
     make
 
-    # Upstream's check for bug 33088: rtld must not reach __ehdr_start or _end
-    # through a run-time relocation, as it stores them before relocating itself.
+    # Upstream's bug 33088 check: rtld stores __ehdr_start and _end before relocating itself.
     echo "--- run-time relocations against __ehdr_start or _end in rtld.os ---"
     local rtld_relocs
     rtld_relocs="$(readelf -rW elf/rtld.os | grep -E 'R_X86_64_64.*(__ehdr_start|_end)' || true)"
@@ -192,8 +185,7 @@ s_glibc() {
     sed "/RTLDLIST=/s@/usr@@g" -i "${LFS}/usr/bin/ldd"
 }
 
-# Cross-compiled binaries must request the target's loader, not the host's;
-# otherwise everything downstream is silently host-contaminated.
+# Cross-compiled binaries must request the target's loader, or the host leaks into everything.
 s_sanity_check() {
     cd "$BUILDDIR"
     echo "int main(void){return 0;}" > sanity.c
@@ -212,8 +204,7 @@ s_sanity_check() {
     fi
     echo "PASS: binaries link against the target loader."
 
-    # --enable-default-pie took effect. No `readelf | grep -q`: under
-    # pipefail, grep exiting on a match can fail the pipeline with SIGPIPE.
+    # Default PIE took effect; no readelf | grep -q, which can SIGPIPE under pipefail.
     local hdr
     hdr="$(readelf -h sanity 2>/dev/null || true)"
     if [[ "$hdr" == *"DYN (Position-Independent"* ]]; then
@@ -258,11 +249,7 @@ STEPS=(
     "libstdcxx s_libstdcxx"
 )
 
-# The toolchain's identity: its build steps' fingerprints, chained as step()
-# chains them, so it changes exactly when one of them would rebuild: a recipe
-# or a helper it calls, a version or patch set it names, the flags, or the host
-# compiler. The walk comes before any step runs, so no step's arguments may
-# read what an earlier one writes (tools/tests/toolchain-identity.sh).
+# The toolchain's identity, walked before any step runs: no step argument may read build output.
 toolchain_id="$(for row in "${STEPS[@]}"; do
                     read -ra s <<< "$row"
                     [[ "${s[1]}" != --check ]] || continue
@@ -311,25 +298,21 @@ Run 'make check' for the full host requirement list."
 preflight
 
 # --- a cross toolchain is never rebuilt over another one's sysroot -------------
-# Pass 1 expects a sysroot with no headers; over an older tree, fixincludes
-# keeps copies of the old glibc headers, which no stamp hashes. So a tree built
-# by another toolchain, or by a stage 01 step since changed, is cleared, stamps
-# included. The record of which one built it stays out of the sysroot, which
-# becomes the root image.
+
+# Kept out of the sysroot, which becomes the root image.
 toolchain_marker="${STAMPS}/toolchain-id"
 
-# Anything mounted under DIR? Stage 03 binds this repository into the sysroot,
-# and rm --one-file-system does not stop at a bind mount of the same filesystem.
-# /proc/mounts has resolved paths with a space as \040 (ENVIRON, since awk -v
-# would unescape it). Unreadable means yes.
+# Mounted under DIR (unreadable means yes)? rm --one-file-system crosses stage 03's binds.
 mounted_under() {
     local real esc
     real="$(realpath -m -- "$1")" || return 0
     [[ -r /proc/mounts ]] || return 0
+    # /proc/mounts writes a space as \040; ENVIRON, since awk -v would unescape it.
     esc="$(printf '%s' "$real" | sed -e 's/\\/\\134/g' -e 's/ /\\040/g' -e 's/\t/\\011/g')"
     P="${esc}/" awk 'index($2, ENVIRON["P"]) == 1 { found = 1 } END { exit !found }' /proc/mounts
 }
 
+# Over another toolchain's tree, fixincludes would keep old glibc headers that no stamp hashes.
 if [[ -d "${LFS}/usr/include" && "$(cat "$toolchain_marker" 2>/dev/null)" != "$toolchain_id" ]]; then
     warn "the sysroot was built by a different toolchain (or by none this script recorded)."
     if mounted_under "$LFS"; then
diff --git a/build/stages/02-temp-tools.sh b/build/stages/02-temp-tools.sh
index 59930e82..1d75ab09 100755
--- a/build/stages/02-temp-tools.sh
+++ b/build/stages/02-temp-tools.sh
@@ -138,9 +138,7 @@ s_binutils_pass2() {
     local src; src="$(unpack "binutils-${V_BINUTILS}.tar.xz" "binutils-${V_BINUTILS}")"
     cd "$src"
 
-    # libtool adds an install-prefix -L path when relinking, which poisons a
-    # cross build. LFS removes it by line number; find the line by content
-    # instead. It occurs twice and LFS patches the second, so require two.
+    # libtool's relink -L to the install prefix poisons a cross build; LFS edits the second of two.
     local -a lines
     mapfile -t lines < <(grep -n -F 'add_dir="$add_dir -L$inst_prefix_dir$libdir"' ltmain.sh | cut -d: -f1)
 
@@ -156,7 +154,6 @@ s_binutils_pass2() {
     echo "patching ltmain.sh line ${target} (second of ${#lines[@]} occurrences)"
     sed -i "${target}s/\$add_dir//" ltmain.sh
 
-    # Prove it took.
     if sed -n "${target}p" ltmain.sh | grep -qF 'add_dir="$add_dir'; then
         echo "ltmain.sh patch did not apply"
         return 1
@@ -183,8 +180,7 @@ s_gcc_pass2() {
         x86_64) sed -e "/m64=/s/lib64/lib/" -i.orig gcc/config/i386/t-linux64 ;;
     esac
 
-    # libgcc and libstdc++ can now be built with threads, but the generated
-    # gthr header still points at the pass-1 placeholder.
+    # Pass 2 builds with threads, but the generated gthr header names the pass-1 placeholder.
     sed '/thread_header =/s/@.*@/gthr-posix.h/' \
         -i libgcc/Makefile.in libstdc++-v3/include/Makefile.in
 
diff --git a/build/stages/05-kernel.sh b/build/stages/05-kernel.sh
index 3b981a4e..cba1375d 100755
--- a/build/stages/05-kernel.sh
+++ b/build/stages/05-kernel.sh
@@ -1,11 +1,6 @@
 #!/usr/bin/env bash
-# Stage 05: the linux-hardened kernel (ADR-009), built in the chroot by the
-# native target compiler from the fragments in build/config/kernel:
-#   hardening.fragment   KSPP options in vanilla Linux
-#   hardened.fragment    options that exist only with linux-hardened
-#   boot.fragment        firmware boot, the verified root, the desktop, drivers
-# It installs into the chroot's own /boot and /lib/modules. An install under
-# ${KRYPTIK_WORK}/sysroot would be a nested, half-populated target tree.
+# Stage 05: the linux-hardened kernel (ADR-009), built in the chroot from build/config/kernel.
+# It installs into the chroot's own /boot and /lib/modules, never a nested ${KRYPTIK_WORK}/sysroot.
 # usage: make kernel   (or, inside the chroot, 05-kernel.sh [--redo <step>])
 
 source "$(dirname "${BASH_SOURCE[0]}")/../lib/common.sh"
@@ -36,7 +31,6 @@ MODDIR="${KRYPTIK_DESTDIR}/lib/modules"
 CONFIG_DIR="${KRYPTIK_ROOT}/build/config/kernel"
 FRAG_BASE="${CONFIG_DIR}/hardening.fragment"
 FRAG_HARDENED="${CONFIG_DIR}/hardened.fragment"
-# See docs/design/boot-and-updates.md.
 FRAG_BOOT="${CONFIG_DIR}/boot.fragment"
 
 REDO=""
@@ -47,8 +41,7 @@ mkdir -p "$STAMPS" "$LOGS" "$BUILDDIR"
 
 # --- steps -----------------------------------------------------------------
 
-# Before unpacking the source: gcc must be native (not the /tools cross
-# compiler), target Kryptik, and be the one stage 04 built userspace with.
+# Before unpacking: gcc must be the native Kryptik compiler stage 04 built userspace with.
 s_compiler_check() {
     local cc; cc="$(command -v gcc || true)"
     [[ -n "$cc" ]] || { echo "no gcc on PATH (${PATH})"; return 1; }
@@ -76,8 +69,7 @@ s_compiler_check() {
     fi
     echo "PASS: native target compiler"
 
-    # KSTACK_ERASE, RANDSTRUCT_FULL and LATENT_ENTROPY are GCC plugins; without
-    # the plugin headers kconfig drops them and s_config refuses the config.
+    # KSTACK_ERASE, RANDSTRUCT_FULL and LATENT_ENTROPY need the plugin headers, or s_config fails.
     local plugin_dir; plugin_dir="$(gcc -print-file-name=plugin)"
     if [[ -e "${plugin_dir}/include/plugin-version.h" ]]; then
         echo "PASS: gcc plugin headers at ${plugin_dir}/include"
@@ -86,7 +78,6 @@ s_compiler_check() {
         echo "         CONFIG_GCC_PLUGINS resolves to n and the fragment check in s_config will fail."
     fi
 
-    # And it must link binaries that run.
     local t; t="$(mktemp -d)"
     # shellcheck disable=SC2064  # $t is wanted at trap-definition time
     trap "rm -rf '$t'" RETURN
@@ -141,23 +132,20 @@ s_patch() {
     echo "--- applying ---"
     patch -Np1 -i "$patch"
 
-    # A hardened-only symbol must now exist.
+    # After patching, a hardened-only symbol must exist.
     if ! grep -rq "config SLAB_CANARY" security/ mm/ 2>/dev/null \
     && ! grep -rq "SLAB_CANARY" security/Kconfig.hardening 2>/dev/null; then
         echo "WARNING: SLAB_CANARY not found after patching - verify the patch"
     fi
 }
 
-# CPU microcode, built into the signed kernel (CONFIG_EXTRA_FIRMWARE): with no
-# initramfs, the early loader can find it nowhere else. All of Intel's files
-# (it picks by family-model-stepping) and AMD's containers, about 18 MB. Intel's
-# "with caveats" updates stay out; they need a BIOS that expects them.
+# CPU microcode, built into the kernel: with no initramfs the early loader finds it nowhere else.
 s_microcode() {
     echo "inputs: intel ${1:-none}, amd from linux-firmware ${2:-none}"
-    # Inside the kernel tree: stage 06 relinks from a cached or artifact copy
-    # of the tree, which carries nothing beside it.
+    # In the kernel tree, since stage 06 relinks from a copy of the tree alone.
     local dir="${KSRC}/kryptik-microcode"
     rm -rf "$dir"; mkdir -p "$dir"
+    # Not Intel's "with caveats" set, which needs a BIOS that expects it.
     tar -xf "${KRYPTIK_SOURCES}/microcode-${V_INTEL_MICROCODE}.tar.gz" -C "$dir" \
         --strip-components=1 --wildcards '*/intel-ucode/*' '*/license'
     tar -xf "${KRYPTIK_SOURCES}/linux-firmware-${V_LINUX_FIRMWARE}.tar.xz" -C "$dir" \
@@ -176,9 +164,7 @@ s_microcode() {
 }
 
 s_config() {
-    # $1 fragment digest, $2 $3 microcode releases, $4 the critical option
-    # list's digest: arguments only so the stamp covers inputs read by path or
-    # held in a variable, which a function's text does not show.
+    # Arguments only for the stamp: fragment digest, microcode releases, critical list digest.
     echo "fragment digest: ${1:-none}; microcode: ${2:-none} ${3:-none}; critical options: ${4:-none}"
     cd "$KSRC"
 
@@ -285,8 +271,7 @@ s_install() {
     cp -v System.map "${BOOTDIR}/System.map-${V_LINUX}"
     cp -v .config "${BOOTDIR}/config-${V_LINUX}"
 
-    # The integrity suite loads the signed mac80211_hwsim and must see this
-    # unsigned copy refused. modules_install signs; the build tree's .ko is not.
+    # An unsigned copy the integrity suite must see refused; only modules_install signs.
     local hwsim="drivers/net/wireless/virtual/mac80211_hwsim.ko"
     [[ -f "$hwsim" ]] || { echo "FAIL: ${hwsim} was not built (CONFIG_MAC80211_HWSIM=m, boot.fragment)"; return 1; }
     if grep -q '~Module signature appended~' "$hwsim"; then
@@ -307,8 +292,7 @@ s_verify_install() {
 
     [[ -s "$img" ]] || { echo "FAIL: ${img} missing or empty"; n=$((n + 1)); }
 
-    # Modules live under the kernel release (include/config/kernel.release),
-    # which LOCALVERSION makes differ from V_LINUX.
+    # Modules live under the kernel release, which LOCALVERSION makes differ from V_LINUX.
     local krel
     krel="$(cat "${KSRC}/include/config/kernel.release" 2>/dev/null || true)"
     [[ -n "$krel" ]] || krel="${V_LINUX}"
@@ -332,8 +316,7 @@ s_verify_install() {
     fi
 
     echo "--- compiler recorded in the image ---"
-    # grep reads vmlinux itself: `strings | grep -m1` can fail on SIGPIPE.
-    # [ -~] stops at the NUL ending the banner, which names the compiler.
+    # grep reads vmlinux itself, as strings | grep -m1 can SIGPIPE; [ -~] stops at the banner's NUL.
     local banner
     banner="$(grep -a -m1 -o 'Linux version [ -~]*' "$KSRC/vmlinux" 2>/dev/null || true)"
     if [[ -z "$banner" ]]; then
@@ -368,24 +351,18 @@ echo
 [[ -f "$FRAG_BASE" ]]     || die "missing ${FRAG_BASE}"
 [[ -f "$FRAG_HARDENED" ]] || die "missing ${FRAG_HARDENED}"
 
-# An EOL kernel is refused (ADR-009) on the host, by `make kernel` before it
-# enters the chroot: in here there is no network to ask kernel.org.
+# `make kernel` refuses an EOL kernel (ADR-009) on the host: in here there is no network.
 
-# No -lgcc_s workaround for sorttable's pthread_exit(): the patched glibc
-# loader copes with it (build/patches/glibc-2.40/README.md), and this link
-# tests that.
+# No -lgcc_s for sorttable's pthread_exit(): the patched glibc copes, and this link tests it.
 
-# Files read by path and variables from the environment are invisible to
-# `declare -f`, so their digests are passed as step arguments.
+# Files read by path are invisible to declare -f, so their digests go in as step arguments.
 FRAG_DIGEST="$(cat "$FRAG_BASE" "$FRAG_HARDENED" "$FRAG_BOOT" | sha256_of_stdin)"
 
-# elfutils is the last of the kernel's build dependencies in stage 04's order,
-# so this covers them without tying the kernel to later packages.
+# The kernel's last build dependency in stage 04, so later packages do not rebuild the kernel.
 stage_depends_on "bs-" elfutils
 
 step compiler-check  --check s_compiler_check
-# The build tree may be deleted to reclaim space; then every step that reads
-# it must run again, so their stamps are archived.
+# A build tree deleted to reclaim space: archive the stamps of every step that reads it.
 if [[ ! -d "$KSRC" && -f "${STAMPS}/${STAMP_PREFIX}unpack" ]]; then
     gone="${STAMPS}/legacy/kernel-tree-gone-$(date +%Y%m%dT%H%M%S)"
     mkdir -p "$gone"
@@ -395,10 +372,7 @@ if [[ ! -d "$KSRC" && -f "${STAMPS}/${STAMP_PREFIX}unpack" ]]; then
     warn "the kernel tree ${KSRC} is gone but its steps were stamped as built;"
     warn "those stamps are archived under ${gone}/ and the tree is unpacked, patched, configured and built again."
 fi
-# The module signing key never goes into the cache, which a pull request's run
-# can restore. A tree without it builds again from `build`: kbuild makes a new
-# key, and the kernel and its modules are signed as one pair. Every restore
-# comes here, so the stamps are dropped, not archived.
+# The signing key is never cached (a pull request's run can restore caches): rebuild and re-sign.
 if [[ -d "$KSRC" && ! -f "$KSRC/certs/signing_key.pem" && -f "${STAMPS}/${STAMP_PREFIX}build" ]]; then
     for s in build size modules install verify-install; do
         rm -f "${STAMPS}/${STAMP_PREFIX}${s}"
@@ -412,9 +386,7 @@ step microcode       s_microcode "$V_INTEL_MICROCODE" "$V_LINUX_FIRMWARE"
 step config          s_config "$FRAG_DIGEST" "$V_INTEL_MICROCODE" "$V_LINUX_FIRMWARE" \
     "$(printf '%s' "$KCONFIG_CRITICAL" | sha256_of_stdin)"
 
-# kernel-hardening-checker (KSPP) on this .config and on stage 06's COMMON_ARGS
-# command line. Each finding must be fixed in a fragment or listed, with its
-# reason, in build/config/kernel/checker-accepted.txt.
+# kernel-hardening-checker on .config and stage 06's COMMON_ARGS; fix a finding or accept it.
 s_hardening_check() {
     echo "config digest: ${1:-none}; accepted list digest: ${2:-none}; command line digest: ${3:-none}"
     echo "checker: ${5:-none}, the script that runs it: ${4:-none}"
@@ -427,8 +399,7 @@ step hardening-check --check s_hardening_check \
     "$(sha256_of "$ACCEPTED_LIST")" "$COMMON_ARGS_DIGEST" \
     "$(sha256_of "${KRYPTIK_ROOT}/tools/check-kernel-hardening.sh")" "$V_KERNEL_HARDENING_CHECKER"
 
-# .config is an input of every later step, but a fingerprint covers only a
-# step's recipe and arguments; hence this digest, taken after s_config wrote it.
+# .config feeds every later step, but no fingerprint sees it; hence this digest, after s_config.
 CFG_DIGEST="$(sha256_of "${KSRC}/.config" 2>/dev/null || echo noconfig)"
 
 step build           s_build "${HOSTLDFLAGS:-}" "$CFG_DIGEST"

From 6d713cb376d3b848f5f893d9ec5f60c911f7a8c2 Mon Sep 17 00:00:00 2001
From: DevomB <Devom.hb@yahoo.com>
Date: Fri, 2 Oct 2026 02:26:14 -0700
Subject: [PATCH 2/3] Shorten the build's runner messages and the console
 wrapper's comments

The stamp runner's refusals lose their history ("predates this harness")
and their essay, keeping every phrase step-errexit.sh matches; the
unchrooted escape hatch and stage 05's nested-tree check say what they
mean in a line. The console wrapper the console recipe writes gets one-
line comments, and firmware.list's header a tight format table. Stage
01's collapsed grep continuation is split again.

Fingerprints: the runner functions are excluded from every recipe's, and
stage 01's change leaves declare -f identical. The console recipe's
heredoc and firmware.list are step inputs, so the console step, the
linux-firmware step and every stage 04 step after them rebuild, with
stage 06; stage 05 builds on elfutils, earlier, so the kernel does not.
---
 build/config/firmware.list   | 20 ++++++--------------
 build/lib/common.sh          | 28 ++++++++--------------------
 build/recipes/console.sh     | 27 ++++++---------------------
 build/stages/01-toolchain.sh |  3 ++-
 build/stages/05-kernel.sh    |  3 +--
 5 files changed, 23 insertions(+), 58 deletions(-)

diff --git a/build/config/firmware.list b/build/config/firmware.list
index 4db6e0e1..9d718aad 100644
--- a/build/config/firmware.list
+++ b/build/config/firmware.list
@@ -1,17 +1,10 @@
 # The only firmware shipped under /lib/firmware on the verified root (ADR-012).
-# One `find -path` pattern per line, matched in the tree linux-firmware's
-# copy-firmware.sh lays out; a selected link brings its target.
-# `newest N PATTERN` keeps the N highest trailing -NUMBERs per device, since a
-# driver falls back only a few firmware API versions. A pattern that matches
-# nothing fails the build.
+#   PATTERN            a `find -path` pattern in copy-firmware.sh's layout; a link brings its target
+#   newest N PATTERN   only the N highest trailing -NUMBERs (API versions) per device
+# A pattern that matches nothing fails the build.
 
-# Intel Wi-Fi: the newest three API versions per device, and every PNVM.
-# Not the version MODULE_FIRMWARE names, on purpose: the driver loads the
-# highest one inside its MAC's range intersected with its RF's (iwl-drv.c), so
-# AX210 with a gf radio declares -100 and loads -89, and the newest parts try
-# cNN names, which newest-N keeps whole, before NN ones. Picking exactly takes
-# that logic and a real card to test on. The glob also keeps the DVM parts'
-# firmware, about 2 MB this kernel cannot load, rather than a way to exclude it.
+# Intel Wi-Fi: three API versions per device, as which one loads depends on MAC and RF (iwl-drv.c).
+# The glob also keeps about 2 MB of DVM firmware this kernel cannot load.
 newest 3 iwlwifi-*.ucode
 iwlwifi-*.pnvm
 
@@ -42,8 +35,7 @@ rtlwifi/rtl8188eufw.bin
 # Broadcom over PCIe (Dell and Apple machines); the SDIO parts are not.
 brcm/brcmfmac*-pcie*
 
-# Graphics: all of Intel's and AMD's. Not NVIDIA: nouveau's GSP firmware is tens
-# of MB per generation, and the firmware framebuffer still gives a display.
+# Graphics: Intel and AMD, not NVIDIA (GSP firmware is tens of MB; the framebuffer still works).
 i915/*
 xe/*
 amdgpu/*
diff --git a/build/lib/common.sh b/build/lib/common.sh
index 17a9a93d..5bdb144c 100644
--- a/build/lib/common.sh
+++ b/build/lib/common.sh
@@ -132,8 +132,8 @@ require_inside_chroot() {
   make ${2:-system}
 
 mounts the chroot, runs this stage in it and unmounts again, escalating only
-for the mount and the chroot call themselves. Set KRYPTIK_ALLOW_UNCHROOTED=1
-only if you know exactly why."
+for the mount and the chroot call themselves. KRYPTIK_ALLOW_UNCHROOTED=1
+skips this check."
 }
 
 require_linux() {
@@ -200,8 +200,7 @@ stage_depends_on() {
     [[ -f "$stamp" ]] || die "${name}: the stage this one builds on has not completed.
 No stamp at ${stamp}. Finish that stage first."
     fp="$(_stamp_read "$stamp")"
-    [[ -n "$fp" ]] || die "${stamp} carries no fingerprint. Rebuild that stage under the
-current harness before building on it."
+    [[ -n "$fp" ]] || die "${stamp} carries no fingerprint; rebuild that stage before building on it."
     STAMP_DEPS="${STAMP_DEPS}stage:${prefix}${name}=${fp};"
 }
 
@@ -403,18 +402,12 @@ _stamp_stale() {
         local archive="${STAMPS}/legacy"
         mkdir -p "$archive"
         mv -f "$stamp" "${archive}/$(basename "$stamp")"
-        warn "${name}: stamp carries no fingerprint - it predates this harness,"
-        warn "${name}: which means it was written by the step() that recorded"
-        warn "${name}: FAILED builds as successful. It proves nothing."
-        warn "${name}: archived to ${archive}/ and rebuilding."
+        warn "${name}: stamp carries no fingerprint, so it proves nothing; archived to ${archive}/, rebuilding"
         return 0
     fi
 
-    local reason="records a different fingerprint than the current inputs.
-One of: the recipe or a helper it calls, an in-repository patch set it applies,
-versions.env, the hardening flags, sources.lock, the compiler in use, an
-earlier step in this stage, or a stage this one builds on has changed since
-${name} was built."
+    local reason="records a different fingerprint than the current inputs: its recipe or a helper,
+a patch set, versions.env, the flags, sources.lock, the compiler or an earlier step or stage changed."
 
     case "${KRYPTIK_STALE:-refuse}" in
         rebuild)
@@ -425,15 +418,10 @@ ${name} was built."
             ;;
         *)
             err "${name}: stamp ${reason}"
-            die "Refusing to resume onto changed inputs.
-
-A stamped step whose inputs moved leaves a sysroot built from two different
-configurations, and nothing downstream can tell. Choose deliberately:
+            die "Refusing to resume onto changed inputs: the sysroot would mix two configurations.
 
   KRYPTIK_STALE=rebuild <command>   rebuild only the affected steps
-  make reset-stamps                 archive every stamp and start clean
-                                    (archives under .stamps/legacy, never
-                                     deletes)
+  make reset-stamps                 archive every stamp under .stamps/legacy and start clean
 
 Stamp: ${stamp}"
             ;;
diff --git a/build/recipes/console.sh b/build/recipes/console.sh
index 332d073b..773106b2 100644
--- a/build/recipes/console.sh
+++ b/build/recipes/console.sh
@@ -5,17 +5,11 @@ s_console() {
     mkdir -p /usr/libexec
     cat > /usr/libexec/kryptik-console <<'EOF'
 #!/bin/sh
-# Start an interactive shell on the active kernel console.
-#
-# Called by the s6-linux-init early getty service. Takes an optional device
-# name; otherwise asks the kernel which console it is using.
+# A shell on the active kernel console for the early getty service; takes an optional device name.
 
 dev="$1"
 
-# sysinit and then firstboot may be asking on this console (ask.sh: the state
-# passphrase, the first account). Each gets 30 s to start (a broken service
-# database must still end in a console); once one has, the console is its own
-# until it ends.
+# Wait out sysinit and firstboot asking here (ask.sh); 30 s each to start, so a console always comes.
 for held in sysinit firstboot; do
     n=0
     until [ -e "/run/kryptik-$held" ] || [ "$n" -ge 150 ]; do sleep 0.2; n=$((n + 1)); done
@@ -23,9 +17,7 @@ for held in sysinit firstboot; do
 done
 
 if [ -z "$dev" ]; then
-    # /sys/class/tty/console/active lists the kernel-preferred console last.
-    # With both video and serial consoles that is "tty0 ttyS0", so taking the
-    # first field races rc.init's /sys mount and strands a headless login on tty0.
+    # The preferred console comes last ("tty0 ttyS0"); taking the first strands a headless login.
     if [ -r /sys/class/tty/console/active ]; then
         dev=$(awk '{print $NF}' < /sys/class/tty/console/active)
     fi
@@ -34,18 +26,13 @@ fi
 
 [ -e "/dev/$dev" ] || dev=console
 
-# A virtual terminal is getty-tty1's. With no serial port the kernel's console
-# is tty0, the terminal tty1 is shown on, and a second getty there would split
-# its keystrokes.
+# A virtual terminal is getty-tty1's: a second getty on tty0, where tty1 shows, would split its keys.
 case "$dev" in
     tty[0-9]*) exec s6-pause ;;
 esac
 
 if [ -x /usr/sbin/agetty ]; then
-    # On an install medium (kryptik.media= is on the signed command line) the
-    # serial console is the installer's root shell: -n -l skips login(1).
-    # On an installed system it is an ordinary login prompt; root is locked,
-    # so it admits the first-boot user, not root.
+    # Install media (kryptik.media= on the signed command line) get a root shell, others a login.
     if grep -qw 'kryptik\.media=[a-z]' /proc/cmdline 2>/dev/null; then
         exec /usr/sbin/agetty -n -l /usr/bin/bash --keep-baud \
              115200,57600,38400,9600 "$dev" vt220
@@ -53,9 +40,7 @@ if [ -x /usr/sbin/agetty ]; then
     exec /usr/sbin/agetty --keep-baud 115200,57600,38400,9600 "$dev" vt220
 fi
 
-# No agetty: put a shell directly on the device. Less capable - no baud
-# handling, no controlling-terminal setup beyond setsid - but a system whose
-# console is unreachable cannot be debugged at all.
+# No agetty: a bare shell on the device, as an unreachable console cannot be debugged at all.
 exec setsid -c /usr/bin/bash -l < "/dev/$dev" > "/dev/$dev" 2>&1
 EOF
     chmod 0755 /usr/libexec/kryptik-console
diff --git a/build/stages/01-toolchain.sh b/build/stages/01-toolchain.sh
index e5e29bb9..bd1fdc45 100755
--- a/build/stages/01-toolchain.sh
+++ b/build/stages/01-toolchain.sh
@@ -123,7 +123,8 @@ s_linux_headers() {
 
     if [[ -f "${LFS}/usr/include/linux/version.h" ]]; then
         echo "installed kernel headers:"
-        grep -E "LINUX_VERSION_(MAJOR|PATCHLEVEL|SUBLEVEL)"             "${LFS}/usr/include/linux/version.h" || true
+        grep -E "LINUX_VERSION_(MAJOR|PATCHLEVEL|SUBLEVEL)" \
+             "${LFS}/usr/include/linux/version.h" || true
     fi
 }
 
diff --git a/build/stages/05-kernel.sh b/build/stages/05-kernel.sh
index cba1375d..3c5b7ce9 100755
--- a/build/stages/05-kernel.sh
+++ b/build/stages/05-kernel.sh
@@ -308,8 +308,7 @@ s_verify_install() {
     # A ${KRYPTIK_WORK}/sysroot here means a nested install.
     if [[ -e "${KRYPTIK_WORK}/sysroot" ]]; then
         echo "FAIL: ${KRYPTIK_WORK}/sysroot exists inside the chroot."
-        echo "Something installed into a nested target tree. See the header of"
-        echo "this file."
+        echo "Something installed into a nested target tree (see the header of build/stages/05-kernel.sh)."
         n=$((n + 1))
     else
         echo "ok: no nested target tree under ${KRYPTIK_WORK}"

From 42f4ad45110e7c00620a8e670873832fa8f1d90e Mon Sep 17 00:00:00 2001
From: DevomB <Devom.hb@yahoo.com>
Date: Fri, 2 Oct 2026 03:08:50 -0700
Subject: [PATCH 3/3] The firmware step reports every pattern that matches
 nothing

grep -c exits 1 when it counts nothing, and under the step's pipefail that aborted the recipe at the first such pattern, before its MISSING line and the summary that names them all.
---
 build/recipes/firmware.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/build/recipes/firmware.sh b/build/recipes/firmware.sh
index d9c0a071..0b4fc547 100644
--- a/build/recipes/firmware.sh
+++ b/build/recipes/firmware.sh
@@ -37,7 +37,7 @@ s_firmware() {
                 fi
             done | sort -t "$(printf '\t')" -k1,1 -k2,2nr | awk -F '\t' -v k="$keep" '{ if (++c[$1] <= k) print $3 }')"
         fi
-        n="$(printf '%s\n' "$matches" | grep -c .)"
+        n="$(printf '%s\n' "$matches" | grep -c . || true)"
         if [[ "$n" -eq 0 ]]; then
             echo "  MISSING  ${pattern}: matches nothing in linux-firmware-${V_LINUX_FIRMWARE}"
             missing=$((missing + 1))