Reorganize source tree: kernel/, v3/, v4/ split and board infrastructure

Source tree reorganization: - Move StarForth v3 engine to v3/ (src/, include/, Makefile) - Move kernel to kernel/ (src/, include/, linker/, Makefile) - Create v4/ skeleton for F18-ISA golden model (DECOMPOSITION.md, JUSTIFICATION.md) - Move FABRIC-0..4.md to docs/fabric/ - Move ONTOLOGY.md and ROADMAP.md to docs/ Board infrastructure: - Add boards/ser5/, boards/raspi/, boards/milkv/, boards/zynq7020/ - Each board has board.mk (ISA, CPU flags, boot recipe) and README.md - Root Makefile becomes thin dispatcher: boot_image, all, clean, docs take TARGET - make boot_image TARGET=SER5|RASPI|MILKV builds one GPT/MBR image per board - ZYNQ7020 target exists but stops with clear error (ARMv7 port not built yet) - scripts/mkdiskimage.sh builds disk images for all boards Docs pipeline: - docs/book/ with LaTeX master (main.tex) and Makefile - pandoc converts Markdown to LaTeX at build time - Two Lua filters: table-widths.lua (wide tables wrap), code-breaks.lua (inline code breaks) - make docs builds single PDF (754 pages, 0 missing characters) - make docs TARGET=<board> adds board appendix - build/docs/<book|board>/meta.tex stamps git commit into PDF Bug fixes: - 42 include paths that only worked by accident now use correct relative paths - clang-18 hardcode replaced with configurable CC variable (fixed aarch64 build) - Pi 5: kernel_2712.img linked at 0x80000, .bss zeroed, memory reserved - Doxyfile, .clang-tidy, README.md, Kconfig paths updated Verified: - Hosted v3 build passes 1012 tests, 0 failures - SER5 image boots in QEMU (OVMF), POST passes, K exact (65536 = Q48_ONE) - Milk-V image boots in QEMU (OpenSBI + U-Boot + bootefi), POST passes - make clean TARGET=<board> removes only that board and its ISA objects - make all builds all boards, hosted v3, and docs in one run Co-authored-by: Junie <junie@jetbrains.com>
2026-10-01 15:40:09 -04:00
parent 3c709c115b
commit a8b70e88d3
630 changed files with 2646 additions and 2036 deletions
@@ -14,7 +14,7 @@ Checks: >

 WarningsAsErrors: [ ]

-HeaderFilterRegex: '^src/.*|^include/.*'
+HeaderFilterRegex: '^v3/(src|include)/.*|^kernel/(src|include)/.*'

 AnalyzeTemporaryDtors: false
 FormatStyle: none
@@ -6,8 +6,8 @@
 # clang-tidy will ALWAYS false-positive them. Always.
 # ---------------------------------------------------------

-src/platform/**
-src/platform/*
+v3/src/platform/**
+v3/src/platform/*

 # ---------------------------------------------------------
 # Skip test infrastructure
@@ -15,8 +15,8 @@ src/platform/*
 # and stress edge conditions clang-tidy will never grok.
 # ---------------------------------------------------------

-src/test_runner/**
-src/test_runner/*
+v3/src/test_runner/**
+v3/src/test_runner/*

 # ---------------------------------------------------------
 # Skip word definitions generated or "mechanically patterned"
@@ -24,30 +24,30 @@ src/test_runner/*
 # clang-tidy gives ZERO useful feedback on them.
 # ---------------------------------------------------------

-src/word_source/string_words.c
-src/word_source/block_words.c
-src/word_source/arithmetic_words.c
-src/word_source/mixed_arithmetic_words.c
-src/word_source/return_stack_words.c
-src/word_source/defining_words.c
-src/word_source/stack_words.c
-src/word_source/logical_words.c
-src/word_source/memory_words.c
-src/word_source/io_words.c
-src/word_source/dictionary_words.c
-src/word_source/dictionary_manipulation_words.c
-src/word_source/vocabulary_words.c
-src/word_source/system_words.c
-src/word_source/starforth_words.c
-src/word_source/editor_words.c
-src/word_source/format_words.c
+v3/src/word_source/string_words.c
+v3/src/word_source/block_words.c
+v3/src/word_source/arithmetic_words.c
+v3/src/word_source/mixed_arithmetic_words.c
+v3/src/word_source/return_stack_words.c
+v3/src/word_source/defining_words.c
+v3/src/word_source/stack_words.c
+v3/src/word_source/logical_words.c
+v3/src/word_source/memory_words.c
+v3/src/word_source/io_words.c
+v3/src/word_source/dictionary_words.c
+v3/src/word_source/dictionary_manipulation_words.c
+v3/src/word_source/vocabulary_words.c
+v3/src/word_source/system_words.c
+v3/src/word_source/starforth_words.c
+v3/src/word_source/editor_words.c
+v3/src/word_source/format_words.c

 # ---------------------------------------------------------
 # Skip headers belonging to the word system
 # Same reason: no signal, infinite false positives.
 # ---------------------------------------------------------

-src/word_source/include/*
+v3/src/word_source/include/*

 # ---------------------------------------------------------
 # Skip anything that implements performance knobs,
@@ -55,15 +55,15 @@ src/word_source/include/*
 # These are meant to be weird, and tidy can't reason about them.
 # ---------------------------------------------------------

-src/stack_management.c
-src/profiler.c
-src/vm_debug.c
-src/physics_runtime.c
+v3/src/stack_management.c
+v3/src/profiler.c
+v3/src/vm_debug.c
+v3/src/physics_runtime.c

 # ---------------------------------------------------------
 # Skip integration + stress torture-tests.
 # These *intentionally* do UB-like bullshit.
 # ---------------------------------------------------------

-src/test_runner/modules/*stress*
-src/test_runner/modules/*integration*
+v3/src/test_runner/modules/*stress*
+v3/src/test_runner/modules/*integration*
@@ -224,43 +224,43 @@ changes with any new C word registration).

 ```bash
 # Build kernel for a given architecture (amd64 default)
-make -f Makefile.starkernel ARCH=amd64
-make -f Makefile.starkernel ARCH=aarch64
-make -f Makefile.starkernel ARCH=riscv64
+make -f kernel/Makefile ARCH=amd64
+make -f kernel/Makefile ARCH=aarch64
+make -f kernel/Makefile ARCH=riscv64

 # Run in QEMU with OVMF
-make -f Makefile.starkernel qemu
-make -f Makefile.starkernel ARCH=aarch64 qemu
-make -f Makefile.starkernel ARCH=riscv64 qemu
+make -f kernel/Makefile qemu
+make -f kernel/Makefile ARCH=aarch64 qemu
+make -f kernel/Makefile ARCH=riscv64 qemu

 # Clean
-make -f Makefile.starkernel clean
+make -f kernel/Makefile clean
 ```

 Output: `build/<arch>/kernel/starkernel_loader.efi` + `build/<arch>/kernel/starkernel_kernel.elf`.

 Two independently tracked version strings flow into the generated `include/version.h`:
-`VERSION` (`Makefile.starkernel` — the embedded StarForth engine version, currently `3.1.0`;
+`VERSION` (`kernel/Makefile` — the embedded StarForth engine version, currently `3.1.0`;
 note this does **not** auto-sync with the standalone StarForth repo's own version) and
-`LITHOS_VERSION` (`Makefile.starkernel` — the kernel version, currently **`2.0.0`**;
+`LITHOS_VERSION` (`kernel/Makefile` — the kernel version, currently **`2.0.0`**;
 corrected 2026-09-19 — this file said `2.0.1`, but `FABRIC-3.md` §I.2 rolled it back to
 `2.0.0` on 2026-09-04 because `2.0.1` names the SER5 hardware-track line and claims hardware
 progress not yet verified. The versioning policy is **semantic, not sequential** — see the
-roadmap table in `Makefile.starkernel` before choosing any version).
+roadmap table in `kernel/Makefile` before choosing any version).

 ### Build configuration (Kconfig — real, wired, not vestigial)

 Every kernel-only knob (`STARFORTH_ENABLE_VM`, `PARITY_MODE`, the shared physics/heartbeat
 family, etc.) is an optional Kconfig symbol defined across `Kconfig`, `Kconfig.arch`,
 `Kconfig.heartbeat`, `Kconfig.kernel`, `Kconfig.physics`, `Kconfig.variant` (~40 symbols
-total). `Makefile.starkernel` pulls its defaults from this system via a `kconfig_bool(...)`
+total). `kernel/Makefile` pulls its defaults from this system via a `kconfig_bool(...)`
 mechanism — e.g. `STARFORTH_ENABLE_VM` defaults to **1** (confirmed at
-`Makefile.starkernel:61`), meaning a plain `make -f Makefile.starkernel` already builds with
+`kernel/Makefile:61`), meaning a plain `make -f kernel/Makefile` already builds with
 VM + capsule-birth + ACL active. A bare invocation uses the defaults it always has:

 ```bash
-make -f Makefile.starkernel ARCH=amd64 menuconfig
-make -f Makefile.starkernel ARCH=amd64 kernel_amd64_defconfig
+make -f kernel/Makefile ARCH=amd64 menuconfig
+make -f kernel/Makefile ARCH=amd64 kernel_amd64_defconfig
 ```

 ### Hosted VM (vendored, for local sanity only)
@@ -277,7 +277,7 @@ StarForth repo) were removed 2026-08-15 — they referenced
 in the actual generated `include/version.h` (which only has `STARFORTH_VERSION`,
 `STARFORTH_ARCH`, `STARFORTH_TARGET`, `STARFORTH_TIMESTAMP`, `STARFORTH_VERSION_FULL`,
 `LITHOS_VERSION`, `LITHOS_VERSION_STR`), so they could never have worked. Bump versions by hand-editing the `VERSION`/
-`LITHOS_VERSION` variables in `Makefile.starkernel` instead. Report the broken targets if
+`LITHOS_VERSION` variables in `kernel/Makefile` instead. Report the broken targets if
 asked, don't silently fix them.

 ### Important: Linker Configuration
@@ -298,9 +298,9 @@ The vendored hosted `make` build (above) is NEVER used to validate kernel change

 ```bash
 # Run in this exact order for every kernel change:
-make -f Makefile.starkernel ARCH=amd64   clean qemu
-make -f Makefile.starkernel ARCH=aarch64 clean qemu
-make -f Makefile.starkernel ARCH=riscv64 clean qemu
+make -f kernel/Makefile ARCH=amd64   clean qemu
+make -f kernel/Makefile ARCH=aarch64 clean qemu
+make -f kernel/Makefile ARCH=riscv64 clean qemu
 ```

 **QEMU rule — non-negotiable:** Only ONE QEMU instance may run at a time, always in the
@@ -475,7 +475,7 @@ listed in `proof/ROOT` (corrected 2026-09-19; this file said 23, and `proof/COVE
 said 52 all along). **Read `proof/COVERAGE.md` first**: its stated goal is not a green build but
 "identify precisely what cannot be proven and why — the boundary between 'formally verified'
 and 'not, for this specific reason'." Run `isabelle build -D proof/`
-directly; neither `Makefile` nor `Makefile.starkernel` in this repo defines an
+directly; neither `Makefile` nor `kernel/Makefile` in this repo defines an
 `isabelle-build`/`isabelle-check` target (unlike the standalone StarForth repo, which has a
 broken one — this repo simply doesn't have the target at all, so there's nothing to
 mistakenly invoke).
@@ -495,7 +495,7 @@ status for kernel work.

 - **Strict ANSI C99** — No GNU extensions, no C++ features
 - **Zero warnings target, with four explicit exceptions — corrected 2026-08-18, previous
-  claim was wrong.** Build with `-Wall -Wextra -Werror`, but `Makefile.starkernel` carries
+  claim was wrong.** Build with `-Wall -Wextra -Werror`, but `kernel/Makefile` carries
  `-Wno-error=unused-parameter -Wno-error=shift-negative-value -Wno-error=sign-compare
  -Wno-error=missing-field-initializers` — those four classes are enabled (still visible as
  warnings) but deliberately downgraded from fatal, everything else is. The previous version
@@ -933,10 +933,12 @@ WARN_LOGFILE           = docs/api/doxygen_warnings.log
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.

-INPUT                  = include \
-                         src \
-                         src/word_source \
-                         src/test_runner \
+INPUT                  = v3/include \
+                         v3/src \
+                         v3/src/word_source \
+                         v3/src/test_runner \
+                         kernel/include \
+                         kernel/src \
                         README.md

 # This tag can be used to specify the character encoding of the source files
@@ -2366,9 +2368,10 @@ SEARCH_INCLUDES        = YES
 # RECURSIVE has no effect here.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.

-INCLUDE_PATH           = include \
-                         src/word_source/include \
-                         src/test_runner/include
+INCLUDE_PATH           = v3/include \
+                         kernel/include \
+                         v3/src/word_source/include \
+                         v3/src/test_runner/include

 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the
@@ -5,7 +5,7 @@ choice
 	default ARCH_AMD64
 	help
 	  Selects the value passed as ARCH= to whichever Makefile
-	  (Makefile or Makefile.starkernel) is driven from this config.
+	  (Makefile or kernel/Makefile) is driven from this config.
 	  Both Makefiles already accept "amd64"/"aarch64"/"riscv64" as
 	  canonical spellings (each has its own alias-normalizing logic
 	  for other spellings like x86_64/arm64/riscv), so this choice
@@ -17,7 +17,7 @@ config HEARTBEAT_THREAD_ENABLED
 	  builds without needing a special case. This is UI/model
 	  correctness (menuconfig can't offer a choice LithosAnanke has no
 	  way to honor -- there are no pthreads in a freestanding kernel),
-	  not the sole enforcement mechanism: Makefile.starkernel additionally
+	  not the sole enforcement mechanism: kernel/Makefile additionally
 	  keeps its own unconditional `VM_FEATURE_OVERRIDES +=
 	  -DHEARTBEAT_THREAD_ENABLED=0` post-override exactly as it was
 	  before this migration. Deliberately redundant with the `depends
@@ -11,7 +11,7 @@ config STARFORTH_ENABLE_VM
 	  kernel that only reaches the M0-M6 hardware milestones (console,
 	  PMM, VMM, interrupts, timers, kmalloc) with no FORTH interpreter,
 	  no capsules, no "ok" REPL. Gates a large source-file selection
-	  block in Makefile.starkernel, not just a handful of -D flags.
+	  block in kernel/Makefile, not just a handful of -D flags.

 config PARITY_MODE
 	bool "Deterministic parity harness mode (PARITY_MODE)"
@@ -48,19 +48,39 @@ POST at boot: **parity hash verified across amd64/aarch64/riscv64 · Mama capsul
 ## Quick Start

 ```bash
+# One boot image per physical target (output: build/boards/<board>/)
+make boot_image TARGET=SER5       # Beelink SER5   -- GPT/ESP, BOOTX64.EFI
+make boot_image TARGET=RASPI      # Raspberry Pi 5 -- FAT, config.txt + kernel_2712.img + DTB
+make boot_image TARGET=MILKV      # Milk-V Mars    -- GPT/ESP, BOOTRISCV64.EFI (U-Boot bootefi)
+make boot_image TARGET=ZYNQ7020   # Zynq-7020      -- ARMv7 port in progress
+make boards                       # list boards
+
+# The same TARGET drives all, docs and clean (make help)
+make                              # every board with a kernel port + hosted v3 + the book
+make TARGET=RASPI                 # one board's image + build/docs/LithosAnanke-raspi.pdf
+make docs                         # build/docs/LithosAnanke.pdf (LaTeX master: docs/book/main.tex)
+make clean TARGET=RASPI           # that board's outputs and build/aarch64/kernel
+make clean                        # all of build/ except build/cache/
+
 # Build kernel (requires cross-compilation toolchain, or native gcc)
-make -f Makefile.starkernel ARCH=amd64
+make -f kernel/Makefile ARCH=amd64

 # Run in QEMU with OVMF
-make -f Makefile.starkernel qemu
+make -f kernel/Makefile qemu

 # Other architectures
-make -f Makefile.starkernel ARCH=aarch64 qemu
-make -f Makefile.starkernel ARCH=riscv64 qemu
+make -f kernel/Makefile ARCH=aarch64 qemu
+make -f kernel/Makefile ARCH=riscv64 qemu
 ```

 Artifacts: `build/amd64/kernel/starkernel_loader.efi` · `build/amd64/kernel/starkernel_kernel.elf`

+Tree: `kernel/` (LithosAnanke: `Makefile`, `src/`, `include/starkernel/`, `linker/`),
+`v3/` (StarForth v3 engine and hosted build: `Makefile`, `src/`, `include/`),
+`v4/` (StarForth v4, see `docs/v4.0.0/`), `boards/<board>/` (`board.mk` + boot files).
+Every makefile runs from the repo root; the root `Makefile` forwards any other goal to
+`v3/Makefile` (hosted build).
+
 For the hosted VM by itself (Linux, no cross-compiler needed, no bare-metal tooling): see
 the separate **StarForth** repository — LithosAnanke used to be a branch inside that repo,
 now it's its own project with its own `master`.
@@ -69,12 +89,12 @@ now it's its own project with its own `master`.

 Every kernel-only knob (`STARFORTH_ENABLE_VM`, `PARITY_MODE`, the shared
 physics/heartbeat family, etc.) is an optional Kconfig symbol — a plain
-`make -f Makefile.starkernel` uses the same defaults it always has unless
+`make -f kernel/Makefile` uses the same defaults it always has unless
 you opt in:

 ```bash
-make -f Makefile.starkernel ARCH=amd64 menuconfig
-make -f Makefile.starkernel ARCH=amd64 kernel_amd64_defconfig
+make -f kernel/Makefile ARCH=amd64 menuconfig
+make -f kernel/Makefile ARCH=amd64 kernel_amd64_defconfig
 ```

 ---
@@ -0,0 +1,29 @@
+# boards/
+
+One directory per physical target. `make boot_image TARGET=<NAME>` (repo root) maps the
+name to a directory here, reads its `board.mk`, and builds the single file that goes on
+that board's boot medium into `build/boards/<board>/`.
+
+| TARGET | Directory | ISA | Boot path | Image |
+|---|---|---|---|---|
+| `SER5` | `ser5/` | amd64 | UEFI firmware, removable-media path | GPT + FAT32 ESP: `EFI/BOOT/BOOTX64.EFI` |
+| `RASPI` | `raspi/` | aarch64 | Pi 5 EEPROM firmware, native | MBR + FAT32: `config.txt`, `kernel_2712.img`, `bcm2712-rpi-5-b.dtb` |
+| `MILKV` | `milkv/` | riscv64 | SPI-flash U-Boot + OpenSBI, `bootefi` | GPT + FAT32 ESP: `EFI/BOOT/BOOTRISCV64.EFI` |
+| `ZYNQ7020` | `zynq7020/` | armv7 | BootROM, `BOOT.BIN`, U-Boot | not yet: needs `kernel/src/arch/armv7` |
+
+`board.mk` sets:
+
+- `BOARD_DESC`: one-line description (`make boards`)
+- `BOARD_ARCH`: kernel ISA (`kernel/src/arch/<arch>`)
+- `BOARD_BOOT`: image recipe in `kernel/Makefile` (`uefi-esp`, `rpi-native`, ...)
+- `BOARD_IMAGE`: output file name
+
+Disk images are assembled by `scripts/mkdiskimage.sh`, which needs no root access and no loop
+devices. `KERNEL_ARGS="..."` is written as `starforth.cfg` (UEFI boards) or `cmdline.txt`
+(Pi 5, where the firmware copies it into `/chosen/bootargs`). `BOOT_IMAGE_SIZE_MIB` sets the
+image size; the default is 128.
+
+Hardware status: none of these images has been booted on real silicon from this build. The
+SER5 image has been booted in QEMU (q35 + OVMF, from its own disk) through POST. The Pi 5
+native path (`raspi/README.md`) and the JH7110 peripherals have still only been checked by
+compiling.
@@ -0,0 +1,30 @@
+# Milk-V Mars boot media
+
+`make boot_image TARGET=MILKV` builds `build/boards/milkv/lithos-milkv.img`: a GPT disk with one
+FAT32 EFI System Partition. Write it to an SD card with `dd`. The partition holds:
+
+- `EFI/BOOT/BOOTRISCV64.EFI`: the riscv64 monolithic loader, the same one QEMU boots.
+- `startup.nsh`: for a UEFI shell, if one is used.
+- `starforth.cfg`: only present when `KERNEL_ARGS="..."` is given.
+
+The board's own SPI-flash U-Boot, with OpenSBI underneath, finds the loader through its standard
+`bootefi` scan of the removable-media path. U-Boot passes its devicetree to the loader through the
+EFI configuration table.
+
+Status: booted in QEMU through the same chain the board uses: OpenSBI, then U-Boot
+`qemu-riscv64_smode`, then `bootefi` from this image's ESP, then the loader and the kernel. POST
+passed, Stadium conservation was exact (resident 43691 + reservoir 21845 = 65536 = `Q48_ONE`), and
+Hestia and Artemis came up. Not yet booted on the Mars itself. The JH7110 peripherals
+(framebuffer, RNG) have only been checked by compiling.
+
+To repeat the QEMU boot (`qemu-system-riscv64` is in Ubuntu 26.04's `qemu-system-riscv` package;
+OpenSBI and U-Boot come from `opensbi` and `u-boot-qemu`). Use a copy, because the kernel writes
+to its disk:
+
+```
+cp build/boards/milkv/lithos-milkv.img /tmp/mv.img
+qemu-system-riscv64 -machine virt -cpu rv64 -m 2048 -nographic \
+    -bios /usr/lib/riscv64-linux-gnu/opensbi/generic/fw_dynamic.bin \
+    -kernel /usr/lib/u-boot/qemu-riscv64_smode/u-boot.bin \
+    -drive if=none,format=raw,file=/tmp/mv.img,id=d0 -device virtio-blk-device,drive=d0
+```
@@ -0,0 +1,11 @@
+# boards/milkv/board.mk -- Milk-V Mars (StarFive JH7110, SiFive U74, RV64GC).
+#
+# The board's own SPI-flash U-Boot (OpenSBI underneath) runs the EFI
+# application through its standard distro/bootefi scan: the SD card is a GPT
+# disk with one FAT32 EFI System Partition holding EFI/BOOT/BOOTRISCV64.EFI,
+# the same riscv64 monolithic loader QEMU boots. U-Boot passes its own
+# devicetree through the EFI configuration table.
+BOARD_DESC  := Milk-V Mars (StarFive JH7110, RV64GC, U-Boot bootefi)
+BOARD_ARCH  := riscv64
+BOARD_BOOT  := uefi-esp
+BOARD_IMAGE := lithos-milkv.img
@@ -0,0 +1,20 @@
+# Raspberry Pi 5 native boot media
+
+`make boot_image TARGET=RASPI` builds `build/boards/raspi/lithos-raspi.img`: an MBR disk
+with one FAT32 (LBA) partition. Write it to an SD card with `dd`. The partition holds:
+
+- `config.txt`: checked in here (FABRIC-3.md §IV.3 item 6). It pins `kernel_address=0x80000`
+  because Pi 5 firmware loads `kernel_2712.img` at 0x200000 by default.
+- `kernel_2712.img`: the aarch64 kernel objects relinked at 0x80000 by
+  `kernel/linker/starkernel-native-rpi5.ld`, entered at `rpi5_native_start`
+  (`kernel/src/arch/aarch64/native_rpi5_entry.S`, which zeroes `.bss` first), and flattened
+  with `objcopy -O binary`.
+- `bcm2712-rpi-5-b.dtb`: the Raspberry Pi firmware's own stock DTB. It is not built by this
+  project; it is fetched once from the firmware release pinned in `board.mk`
+  (`RPI_FIRMWARE_TAG`) into `build/cache/`. To use a local copy, pass `RPI5_DTB=/path/to/dtb`.
+- `cmdline.txt`: only present when `KERNEL_ARGS="..."` is given. The firmware copies it into
+  `/chosen/bootargs`, which `rpi5_native_boot()` parses.
+
+Not yet verified on hardware. The native path still assumes everything `kernel_main()`
+needs after a UEFI handoff. The firmware enters at EL2 with the MMU off, which is not what
+UEFI hands over, and that difference has not been exercised.
@@ -0,0 +1,18 @@
+# boards/raspi/board.mk -- Raspberry Pi 5 (BCM2712, Cortex-A76, aarch64).
+#
+# Native firmware boot, no UEFI (FABRIC-3.md §IV): the Pi 5 bootloader
+# lives in EEPROM and reads config.txt, kernel_2712.img and the board DTB
+# from the first FAT partition of the SD card. kernel_2712.img is the
+# aarch64 kernel relinked at 0x80000 (kernel/linker/starkernel-native-rpi5.ld)
+# and flattened to a raw binary.
+#
+# The DTB is the Raspberry Pi firmware's own stock file, not built here. It
+# is fetched once from the pinned firmware release below into build/cache/
+# unless RPI5_DTB points at a local copy.
+BOARD_DESC  := Raspberry Pi 5 (BCM2712, Cortex-A76, native firmware boot)
+BOARD_ARCH  := aarch64
+BOARD_BOOT  := rpi-native
+BOARD_IMAGE := lithos-raspi.img
+RPI_FIRMWARE_TAG ?= 1.20260915
+RPI5_DTB_URL     ?= https://raw.githubusercontent.com/raspberrypi/firmware/$(RPI_FIRMWARE_TAG)/boot/bcm2712-rpi-5-b.dtb
+RPI5_DTB         ?= build/cache/raspi-$(RPI_FIRMWARE_TAG)/bcm2712-rpi-5-b.dtb
@@ -12,6 +12,13 @@
 # firmware picks up.
 kernel=kernel_2712.img

+# Pin the load address to the one the image is linked at
+# (kernel/linker/starkernel-native-rpi5.ld). Pi 5 firmware's own default
+# for kernel_2712.img is 0x200000, not the classic 0x80000 -- leaving it
+# implicit would load a 0x80000-linked flat image 1.5 MiB away from where
+# every absolute address in it points.
+kernel_address=0x80000
+
 # Disable the firmware's Linux-compatible-image sanity check. Without
 # this, official docs describe it as checking for "a compatible Device
 # Tree file before attempting to boot" and warn that "older non-compatible
@@ -0,0 +1,14 @@
+# Beelink SER5 boot media
+
+`make boot_image TARGET=SER5` builds `build/boards/ser5/lithos-ser5.img`: a GPT disk with one
+FAT32 EFI System Partition. Write it to a USB stick with `dd`. The partition holds:
+
+- `EFI/BOOT/BOOTX64.EFI`: the amd64 monolithic loader, with the whole kernel embedded. Firmware
+  finds it through the UEFI removable-media path, so no boot entry has to be created.
+- `startup.nsh`: runs the loader if the firmware drops into the UEFI shell.
+- `starforth.cfg`: only present when `KERNEL_ARGS="..."` is given.
+
+Nothing in the image is SER5-specific. It follows the generic UEFI/ACPI path in FABRIC-3.md §III.
+
+Status: booted in QEMU (q35 + OVMF, from this image as its own disk) through POST, with Stadium
+conservation exact (sum 65536 = `Q48_ONE`). Not yet booted on the SER5 itself.
@@ -0,0 +1,10 @@
+# boards/ser5/board.mk -- Beelink SER5 (AMD Ryzen, x86-64, UEFI/ACPI).
+#
+# Generic standards-compliant UEFI path (FABRIC-3.md §III): nothing in the
+# image is SER5-specific. The monolithic loader embeds the whole kernel, so
+# the image is a GPT disk with one FAT32 EFI System Partition holding
+# EFI/BOOT/BOOTX64.EFI. Write it to a USB stick with dd.
+BOARD_DESC  := Beelink SER5 (AMD Ryzen, x86-64, UEFI)
+BOARD_ARCH  := amd64
+BOARD_BOOT  := uefi-esp
+BOARD_IMAGE := lithos-ser5.img
@@ -0,0 +1,17 @@
+# Xilinx Zynq-7020 boot media
+
+The Zynq-7020's processing system is a dual Cortex-A9: ARMv7-A, 32-bit. It is the host for the
+StarForth v4 mesh (`docs/v4.0.0/JUSTIFICATION.md` §5, §8).
+
+Boot chain: BootROM, then `BOOT.BIN` (U-Boot SPL with the board's `ps7_init` DDR and clock setup),
+then U-Boot, then LithosAnanke. Everything is read from the SD card's FAT partition.
+
+Status: no image yet. `make boot_image TARGET=ZYNQ7020` stops with an error, because there is no
+ARMv7 kernel port (`kernel/src/arch/armv7`: entry code, MMU, GIC, private timer). A trial
+compile for Cortex-A9 built 147 of the 151 kernel and engine sources. The four that failed use
+`__int128` or have no ARMv7 branch: `kernel/src/crypto/fe25519.c`,
+`kernel/src/crypto/scalar25519.c`, `kernel/src/hal/hal.c` and
+`v3/src/word_source/mixed_arithmetic_words.c`.
+
+`BOOT.BIN` depends on the exact board (Zybo Z7-20, PYNQ-Z2, Arty Z7-20, ZedBoard, ...), because
+`ps7_init` holds that board's DDR timing. The board has not been chosen yet.
@@ -0,0 +1,11 @@
+# boards/zynq7020/board.mk -- Xilinx Zynq-7020 (dual Cortex-A9, ARMv7-A, 32-bit).
+#
+# Boot chain: BootROM -> BOOT.BIN (U-Boot SPL with the board's ps7_init DDR/
+# clock setup) -> U-Boot -> LithosAnanke, all from the SD card's FAT
+# partition. Needs the ARMv7 kernel port (kernel/src/arch/armv7), which is
+# in progress: until it exists, boot_image stops with an explicit error
+# rather than producing an image that cannot run.
+BOARD_DESC  := Xilinx Zynq-7020 (Cortex-A9, ARMv7-A, BOOT.BIN) -- ARMv7 port in progress
+BOARD_ARCH  := armv7
+BOARD_BOOT  := zynq-bootbin
+BOARD_IMAGE := lithos-zynq7020.img
@@ -1,12 +0,0 @@
-# Raspberry Pi 5 native boot media
-
-What goes on the SD card for the native (non-UEFI) boot path (FABRIC-3.md §IV):
-
- `config.txt` — checked in here, done (§IV.3 item 6).
- `bcm2712-rpi-5-b.dtb` — Raspberry Pi firmware's own stock DTB; not built by this
-  project, copied from the firmware release the card is otherwise built from.
- `kernel_2712.img` — **does not exist yet.** `config.txt` names it, but no build target
-  in `Makefile.starkernel` currently emits a raw image by this name at load address
-  0x80000 — item 1 (entry stub) explicitly scoped a separate-image build target as future
-  work, not part of that item. Building this file is the remaining prerequisite before
-  item 7 (assembling the card) is possible.
@@ -1,5 +1,5 @@
 # Capsule Block Manifest — Auto-generated
-<!-- Generated by mkcapsule --manifest  2026-09-22T22:29:26Z -->
+<!-- Generated by mkcapsule --manifest  2026-10-01T19:21:21Z -->
 <!-- DO NOT EDIT — re-run mkcapsule --manifest to refresh.  -->
 <!-- Hand-written justifications and immutability notes live  -->
 <!-- in MANIFEST.md alongside this auto-generated index.      -->
@@ -8,42 +8,44 @@

 | Capsule | Blocks claimed | xxHash64 | Signed |
 |---------|----------------|----------|--------|
-| `ACL.4th` | 4000, 4001, 4002, 4003, 4004, 4005, 4006, 4007, 4008, 4015 | `0xf8890c05c0d8f921` | yes |
-| `acl-std79.4th` | 4023, 4024, 4025, 4026, 4027, 4028, 4029, 4030, 4031, 4032, 4033, 4034, 4035, 4036, 4037, 4038, 4039, 4040, 4041, 4042, 4043, 4044, 4045, 4046, 4047, 4048 | `0x773bf9209df191d1` | yes |
-| `artemis:init.4th` | 4110, 4111, 4112, 4113, 4122, 4123, 4124, 4125, 4126, 4127, 4128, 4129, 4130, 4131, 4132, 4133, 4134, 4135, 4136, 4137, 4138, 4139, 4140, 4141, 4160, 4161, 4162, 4163, 4164, 4165, 4166, 4167, 4168, 4169, 4170, 4171, 4172, 4173, 4174, 4177, 4178, 4179, 4180, 4181, 4182, 4851, 4852, 4853, 4854, 4856, 4857, 4858, 4860 | `0xe6fba9ae56e1c916` | yes |
-| `block-acl.4th` | 4019, 4020 | `0xf6cc2a59e3a6734e` | yes |
-| `doe-campaign.4th` | 4060, 4061, 4062, 4063, 4064, 4065 | `0x26fb485e5c9dc6ff` | yes |
-| `doe.4th` | 2100, 2101, 2102, 2103, 2104, 2105, 2106, 2107 | `0xf154616d248e861f` | yes |
-| `fabric.4th` | 4900, 4901, 4902, 4903, 4904, 4905, 4906, 4907, 4908, 4909, 4910, 4911, 4912, 4913, 4914, 4915, 4916, 4917, 4918, 4919, 4920, 4921, 4922, 4923, 4924, 5000, 5001, 5002 | `0x9d9489cbeca4099b` | yes |
-| `font.4th` | 4925, 4926, 4927, 4928, 4929, 4930, 4931, 4932, 4933, 4934, 4935, 4936, 4937, 4938, 4939, 4940, 4941, 4942, 4943, 4944, 4945, 4946, 4947, 4948, 4949, 4950, 4951, 4952, 4953, 4954, 4955, 4956, 4957, 4958, 4959, 4960, 4961, 4962, 4963, 4964, 4965, 4966, 4967, 4968, 4969, 4970, 4971, 4972, 4973, 4974, 4975, 4976, 4977, 4978, 4979, 4980, 4981, 4982, 4983, 4984, 4985 | `0x3f305911500c78f6` | yes |
-| `hestia:init.4th` | 4986, 4987, 4988 | `0x64e111990fbc45ff` | yes |
-| `init-l8-diverse.4th` | 4820, 4821, 4822 | `0xaa293201a6c91838` | yes |
-| `init-l8-omni.4th` | 2064, 2065, 2066, 2067, 2068, 2069, 2070, 2071, 2072, 2073, 2074, 2075, 2076, 2077, 2078, 2079 | `0x5979e314d6452045` | yes |
-| `init-l8-stable.4th` | 4806 | `0xdc3830f189063a9a` | yes |
-| `init-l8-temporal.4th` | 4830, 4831 | `0x51abd4c138246651` | yes |
-| `init-l8-transition.4th` | 4840, 4841, 4842 | `0xbcc1a81976f0a4c9` | yes |
-| `init-l8-volatile.4th` | 4810, 4811, 4812, 4813 | `0x98caabbbd92abac4` | yes |
-| `init.4th` | 2049, 2050, 2057 | `0xea038ba684c53443` | yes |
-| `lib.4th` | 4050 | `0x4b216635c359ef73` | yes |
-| `multiuser-doe.4th` | 5044, 5045, 5046, 5047, 5048, 5049, 5050, 5051, 5052, 5053, 5054, 5055 | `0x22140588ee7c39e6` | yes |
-| `sdk.4th` | 5109, 5110, 5111, 5112, 5113, 5114, 5115 | `0x008fdbbb62c94a3a` | yes |
-| `turtle.4th` | 5100, 5101, 5102, 5103, 5104, 5105, 5106, 5107, 5108 | `0x4d470418ca543365` | yes |
-| `user-font-demo.4th` | 4200, 4201, 4202 | `0xce1fd7d1b581a56d` | yes |
-| `workload-0.4th` | 2200, 2201 | `0x93f86f60aeba8feb` | yes |
-| `workload-1-lite.4th` | 5058, 5059 | `0x44a7a7e3176dcc8d` | yes |
-| `workload-1.4th` | 4406, 4415, 4425, 4435 | `0x63e251adb0a03613` | yes |
-| `workload-2.4th` | 4506, 4515, 4525, 4535, 4545 | `0xf113b3d0bcccae47` | yes |
-| `workload-3.4th` | 4606, 4615, 4625, 4635, 4645, 4655, 4665 | `0x62b7a71576ad1041` | yes |
-| `workload-4.4th` | 2130, 2131, 2132 | `0x099619264e650b1c` | yes |
-| `workload-5-lite.4th` | 5056, 5057 | `0xea0303f38824f254` | yes |
-| `workload-5.4th` | *(none — raw code capsule)* | `0x526964c7c9506a11` | yes |
-| `workload-6.4th` | 2080, 2081, 2082, 2083, 2084, 2085, 2086, 2087, 2088, 2089, 2090, 2091, 2092, 2093, 2094, 2095 | `0x06fc0ce1e369ef5a` | yes |
-| `workload-7.4th` | 2150 | `0x02862291387eb7ac` | yes |
-| `workload-8.4th` | 2160 | `0x56b7f2f0efa000df` | yes |
-| `workload-9.4th` | 4706, 4715, 4725, 4735, 4745 | `0x3f2bec73142aa424` | yes |
-| `workload-calib1.4th` | 5043 | `0x3b9f2d17b554fabc` | yes |
-| `zuse-eligibility.4th` | 4021, 4022 | `0x7b28f4776a32e0b7` | yes |
-| `zuse.4th` | 4016, 4017, 4018 | `0x490ded9be257a90b` | yes |
+| `ACL.4th` | 4000, 4001, 4002, 4003, 4004, 4005, 4006, 4007, 4008, 4015 | `0xf8890c05c0d8f921` | n/a |
+| `acl-std79.4th` | 4023, 4024, 4025, 4026, 4027, 4028, 4029, 4030, 4031, 4032, 4033, 4034, 4035, 4036, 4037, 4038, 4039, 4040, 4041, 4042, 4043, 4044, 4045, 4046, 4047, 4048 | `0x773bf9209df191d1` | n/a |
+| `artemis:init.4th` | 4110, 4111, 4112, 4113, 4122, 4123, 4124, 4125, 4126, 4127, 4128, 4129, 4130, 4131, 4132, 4133, 4134, 4135, 4136, 4137, 4138, 4139, 4140, 4141, 4160, 4161, 4162, 4163, 4164, 4165, 4166, 4167, 4168, 4169, 4170, 4171, 4172, 4173, 4174, 4177, 4178, 4179, 4180, 4181, 4182, 4851, 4852, 4853, 4854, 4856, 4857, 4858, 4860 | `0xe6fba9ae56e1c916` | n/a |
+| `block-acl.4th` | 4019, 4020 | `0xf6cc2a59e3a6734e` | n/a |
+| `doe-campaign.4th` | 4060, 4061, 4062, 4063, 4064, 4065 | `0x26fb485e5c9dc6ff` | n/a |
+| `doe.4th` | 2100, 2101, 2102, 2103, 2104, 2105, 2106, 2107 | `0xf154616d248e861f` | n/a |
+| `fabric.4th` | 4900, 4901, 4902, 4903, 4904, 4905, 4906, 4907, 4908, 4909, 4910, 4911, 4912, 4913, 4914, 4915, 4916, 4917, 4918, 4919, 4920, 4921, 4922, 4923, 4924, 5000, 5001, 5002 | `0x9d9489cbeca4099b` | n/a |
+| `font.4th` | 4925, 4926, 4927, 4928, 4929, 4930, 4931, 4932, 4933, 4934, 4935, 4936, 4937, 4938, 4939, 4940, 4941, 4942, 4943, 4944, 4945, 4946, 4947, 4948, 4949, 4950, 4951, 4952, 4953, 4954, 4955, 4956, 4957, 4958, 4959, 4960, 4961, 4962, 4963, 4964, 4965, 4966, 4967, 4968, 4969, 4970, 4971, 4972, 4973, 4974, 4975, 4976, 4977, 4978, 4979, 4980, 4981, 4982, 4983, 4984, 4985 | `0x3f305911500c78f6` | n/a |
+| `hestia:init.4th` | 4986, 4987, 4988 | `0x64e111990fbc45ff` | n/a |
+| `init-l8-diverse.4th` | 4820, 4821, 4822 | `0xaa293201a6c91838` | n/a |
+| `init-l8-omni.4th` | 2064, 2065, 2066, 2067, 2068, 2069, 2070, 2071, 2072, 2073, 2074, 2075, 2076, 2077, 2078, 2079 | `0x5979e314d6452045` | n/a |
+| `init-l8-stable.4th` | 4806 | `0xdc3830f189063a9a` | n/a |
+| `init-l8-temporal.4th` | 4830, 4831 | `0x51abd4c138246651` | n/a |
+| `init-l8-transition.4th` | 4840, 4841, 4842 | `0xbcc1a81976f0a4c9` | n/a |
+| `init-l8-volatile.4th` | 4810, 4811, 4812, 4813 | `0x98caabbbd92abac4` | n/a |
+| `init.4th` | 2049, 2050, 2057 | `0xea038ba684c53443` | n/a |
+| `lib.4th` | 4050 | `0x4b216635c359ef73` | n/a |
+| `multiuser-doe.4th` | 5044, 5045, 5046, 5047, 5048, 5049, 5050, 5051, 5052, 5053, 5054, 5055 | `0x22140588ee7c39e6` | n/a |
+| `sdk.4th` | 5109, 5110, 5111, 5112, 5113, 5114, 5115 | `0x008fdbbb62c94a3a` | n/a |
+| `turtle.4th` | 5100, 5101, 5102, 5103, 5104, 5105, 5106, 5107, 5108 | `0x4d470418ca543365` | n/a |
+| `user-font-demo.4th` | 4200, 4201, 4202 | `0xce1fd7d1b581a56d` | n/a |
+| `workload-0.4th` | 2200, 2201 | `0x93f86f60aeba8feb` | n/a |
+| `workload-1-lite.4th` | 5058, 5059 | `0x44a7a7e3176dcc8d` | n/a |
+| `workload-1.4th` | 4406, 4415, 4425, 4435 | `0x63e251adb0a03613` | n/a |
+| `workload-2.4th` | 4506, 4515, 4525, 4535, 4545 | `0xf113b3d0bcccae47` | n/a |
+| `workload-3.4th` | 4606, 4615, 4625, 4635, 4645, 4655, 4665 | `0x62b7a71576ad1041` | n/a |
+| `workload-4.4th` | 2130, 2131, 2132 | `0x099619264e650b1c` | n/a |
+| `workload-5-lite.4th` | 5056, 5057 | `0xea0303f38824f254` | n/a |
+| `workload-5.4th` | *(none — raw code capsule)* | `0x526964c7c9506a11` | n/a |
+| `workload-6.4th` | 2080, 2081, 2082, 2083, 2084, 2085, 2086, 2087, 2088, 2089, 2090, 2091, 2092, 2093, 2094, 2095 | `0x06fc0ce1e369ef5a` | n/a |
+| `workload-7.4th` | 2150 | `0x02862291387eb7ac` | n/a |
+| `workload-8.4th` | 2160 | `0x56b7f2f0efa000df` | n/a |
+| `workload-9.4th` | 4706, 4715, 4725, 4735, 4745 | `0x3f2bec73142aa424` | n/a |
+| `workload-calib1.4th` | 5043 | `0x3b9f2d17b554fabc` | n/a |
+| `zuse-eligibility.4th` | 4021, 4022 | `0x7b28f4776a32e0b7` | n/a |
+| `zuse.4th` | 4016, 4017, 4018 | `0xa14d5a7a88791cf6` | n/a |
+
+*Signed column is `n/a`: this manifest run had no `--sign-key`. Re-run with `--sign-key <path>` to check signing status (does not modify or require rebuilding capsule_generated.c).*

 ## Block Map (sorted by LBN)

@@ -109,9 +111,9 @@
 | 4007 | `ACL.4th` | `0xf8890c05c0d8f921` | ok |
 | 4008 | `ACL.4th` | `0xf8890c05c0d8f921` | ok |
 | 4015 | `ACL.4th` | `0xf8890c05c0d8f921` | ok |
-| 4016 | `zuse.4th` | `0x490ded9be257a90b` | ok |
-| 4017 | `zuse.4th` | `0x490ded9be257a90b` | ok |
-| 4018 | `zuse.4th` | `0x490ded9be257a90b` | ok |
+| 4016 | `zuse.4th` | `0xa14d5a7a88791cf6` | ok |
+| 4017 | `zuse.4th` | `0xa14d5a7a88791cf6` | ok |
+| 4018 | `zuse.4th` | `0xa14d5a7a88791cf6` | ok |
 | 4019 | `block-acl.4th` | `0xf6cc2a59e3a6734e` | ok |
 | 4020 | `block-acl.4th` | `0xf6cc2a59e3a6734e` | ok |
 | 4021 | `zuse-eligibility.4th` | `0x7b28f4776a32e0b7` | ok |
@@ -1,7 +1,7 @@
 # configs/

 Example Kconfig `defconfig` files — starting points for `make -f
-Makefile.starkernel ARCH=<arch> defconfig` (kernel) or the equivalent
+kernel/Makefile ARCH=<arch> defconfig` (kernel) or the equivalent
 hosted target, matching the current committed default build behavior for
 each profile. Loaded via `tools/kconfig/conf`.

@@ -0,0 +1,112 @@
+# docs/book/Makefile -- the single LithosAnanke book, built from LaTeX.
+#
+# Run from the repo root (the root Makefile does this):
+#   make docs                   -> build/docs/LithosAnanke.pdf
+#   make docs TARGET=<board>    -> build/docs/LithosAnanke-<board>.pdf
+#                                  (same book + that board's appendix)
+#
+# docs/book/main.tex is the master. Markdown sources are converted by pandoc
+# into LaTeX fragments under build/docs/gen/ and \input from main.tex; the
+# Markdown stays the source of truth until a chapter is rewritten in LaTeX.
+# Figures and tables that present data read the CSV directly at LaTeX time
+# (pgfplots / pgfplotstable) and cite it with \datasource{path}; see
+# docs/book/README.md.
+
+BOOK_DIR := docs/book
+OUT      := build/docs
+GEN      := $(OUT)/gen
+
+BOARD      ?=
+BOARD_NAME ?=
+VARIANT    := $(if $(BOARD),$(BOARD),book)
+VAR_DIR    := $(OUT)/$(VARIANT)
+PDF        := $(OUT)/LithosAnanke$(if $(BOARD),-$(BOARD)).pdf
+
+PANDOC  ?= pandoc
+LATEXMK ?= latexmk
+PANDOC_FILTERS := $(BOOK_DIR)/pandoc/table-widths.lua $(BOOK_DIR)/pandoc/code-breaks.lua
+PANDOC_FLAGS := -f gfm -t latex --top-level-division=chapter --wrap=preserve \
+    $(foreach f,$(PANDOC_FILTERS),--lua-filter=$(f))
+
+# fragment name : Markdown source. The order of \input lines is main.tex's.
+CHAPTERS := \
+    ontology:docs/ONTOLOGY.md \
+    roadmap:docs/ROADMAP.md \
+    boards:boards/README.md \
+    justification:docs/v4.0.0/JUSTIFICATION.md \
+    decomposition:docs/v4.0.0/DECOMPOSITION.md \
+    fabric-0:docs/fabric/FABRIC-0.md \
+    fabric-1:docs/fabric/FABRIC-1.md \
+    fabric-2:docs/fabric/FABRIC-2.md \
+    fabric-3:docs/fabric/FABRIC-3.md \
+    fabric-3-5:docs/fabric/FABRIC-3.5.md \
+    fabric-3-6:docs/fabric/FABRIC-3.6.md \
+    fabric-3-7:docs/fabric/FABRIC-3.7.md \
+    fabric-4:docs/fabric/FABRIC-4.md
+
+ifneq ($(BOARD),)
+ifeq ($(wildcard boards/$(BOARD)/README.md),)
+    $(error boards/$(BOARD)/README.md is missing: it is the board's appendix)
+endif
+CHAPTERS += board-$(BOARD):boards/$(BOARD)/README.md
+endif
+
+chapter_name = $(word 1,$(subst :, ,$(1)))
+chapter_src  = $(word 2,$(subst :, ,$(1)))
+FRAGMENTS := $(foreach c,$(CHAPTERS),$(GEN)/$(call chapter_name,$(c)).tex)
+
+.PHONY: all tools FORCE
+all: $(PDF)
+
+tools:
+	@missing=""; \
+	for t in $(PANDOC) $(LATEXMK) xelatex; do command -v $$t >/dev/null 2>&1 || missing="$$missing $$t"; done; \
+	if [ -n "$$missing" ]; then \
+	    echo "Error: make docs needs:$$missing"; \
+	    echo "  sudo apt-get install -y pandoc latexmk texlive-xetex texlive-latex-extra texlive-pictures texlive-fonts-recommended fonts-dejavu fonts-dejavu-extra"; \
+	    echo "  (or a user-local TinyTeX + pandoc in ~/.local; see docs/book/README.md)"; \
+	    exit 1; \
+	fi
+
+# --id-prefix keeps heading labels unique across documents that reuse
+# section names ("Summary", "Open questions", ...).
+define chapter_rule
+$(GEN)/$(call chapter_name,$(1)).tex: $(call chapter_src,$(1)) $(PANDOC_FILTERS) | tools
+	@mkdir -p $(GEN)
+	@echo "  PANDOC  $$< -> $$@"
+	@$(PANDOC) $(PANDOC_FLAGS) --id-prefix=$(call chapter_name,$(1))- $$< -o $$@
+endef
+$(foreach c,$(CHAPTERS),$(eval $(call chapter_rule,$(c))))
+
+# Pandoc's syntax-highlighting macros, taken from the installed pandoc so the
+# fragments and their macros always come from the same version.
+$(GEN)/pandoc-highlighting.tex: $(BOOK_DIR)/pandoc/highlighting.latex | tools
+	@mkdir -p $(GEN)
+	@printf '```c\nx\n```\n' | $(PANDOC) -f gfm -t latex -s --template=$< -o $@
+
+# Per-build facts the book prints: the commit every \datasource refers to,
+# and which board appendix (if any) is included.
+$(VAR_DIR)/meta.tex: FORCE
+	@mkdir -p $(VAR_DIR)
+	@{ \
+	    c=$$(git rev-parse --short=12 HEAD 2>/dev/null || echo unknown); \
+	    git diff --quiet HEAD -- 2>/dev/null || c="$$c (+ uncommitted changes)"; \
+	    printf '\\newcommand{\\bookcommit}{%s}\n' "$$c"; \
+	    printf '\\newcommand{\\bookdate}{%s}\n' "$$(date -u +%Y-%m-%d)"; \
+	    printf '\\def\\bookboard{%s}\n' "$(BOARD_NAME)"; \
+	    $(if $(BOARD),printf '\\newcommand{\\bookboardappendix}{board-%s}\n' "$(BOARD)";) \
+	} > $@.tmp
+	@cmp -s $@.tmp $@ && rm -f $@.tmp || mv $@.tmp $@
+
+FORCE:
+
+TEXINPUTS_BOOK := $(abspath $(VAR_DIR)):$(abspath $(GEN)):$(abspath $(BOOK_DIR)):
+
+$(PDF): $(BOOK_DIR)/main.tex $(FRAGMENTS) $(GEN)/pandoc-highlighting.tex $(VAR_DIR)/meta.tex | tools
+	@echo "  LATEXMK $(BOOK_DIR)/main.tex -> $@"
+	@TEXINPUTS=$(TEXINPUTS_BOOK) $(LATEXMK) -xelatex -interaction=nonstopmode -halt-on-error \
+	    -file-line-error -outdir=$(VAR_DIR) $(BOOK_DIR)/main.tex > $(VAR_DIR)/latexmk.log 2>&1 || { \
+	    grep -A4 -E '^(.*:[0-9]+:|!)' $(VAR_DIR)/main.log | head -40; \
+	    echo "Error: LaTeX failed; full log: $(VAR_DIR)/main.log"; exit 1; }
+	@cp $(VAR_DIR)/main.pdf $@
+	@echo "  PDF     $@"
@@ -0,0 +1,66 @@
+# docs/book/
+
+`make docs` builds one PDF, `build/docs/LithosAnanke.pdf`, from `main.tex` with xelatex.
+`make docs TARGET=<board>` builds `build/docs/LithosAnanke-<board>.pdf`: the same book with
+`boards/<board>/README.md` added as an appendix.
+
+Tools: `sudo apt-get install -y pandoc latexmk texlive-xetex texlive-latex-extra texlive-pictures texlive-fonts-recommended fonts-dejavu fonts-dejavu-extra`
+
+Without root, a user-local TeX Live works too (this is how the book was first built):
+TinyTeX (`curl -sL https://yihui.org/tinytex/install-bin-unix.sh | sh`) plus
+`tlmgr install latexmk xetex fontspec pgf pgfplots booktabs multirow fancyvrb fvextra lineno upquote ulem enumitem newunicodechar bookmark hyperref geometry xcolor graphics tools etoolbox fancyhdr truncate amsfonts`,
+and the pandoc release tarball unpacked into `~/.local`.
+
+The installed DejaVu decides italics: `fonts-dejavu-core` alone has no serif italic, so
+`main.tex` falls back to a slanted upright face; `fonts-dejavu-extra` gives real italics.
+
+## How it fits together
+
+- `main.tex` is the master file. It sets the parts and the chapter order.
+- Chapters that are still Markdown are listed in `Makefile` (`CHAPTERS`, as `name:source.md`).
+  At build time pandoc converts each one into `build/docs/gen/<name>.tex`, and `main.tex`
+  includes it with `\input{<name>}`. The Markdown stays the source until the chapter is
+  rewritten in LaTeX. At that point the `.tex` moves into this directory and the `CHAPTERS`
+  entry is removed.
+- `pandoc/highlighting.latex` extracts the code-highlighting macros from the installed pandoc,
+  so the macros and the fragments always come from the same pandoc version.
+- Two Lua filters run on every chapter. `pandoc/table-widths.lua` gives wide tables
+  proportional wrapping columns, because pandoc's gfm reader leaves column widths unset.
+  `pandoc/code-breaks.lua` lets long inline identifiers and paths break after `_ / . - :`.
+  Code blocks wrap through fvextra (`breaklines`).
+- `build/docs/<book|board>/meta.tex` is written on every build. It records the commit (and
+  whether there were uncommitted changes), the date, and the board.
+
+## Rule for data
+
+Any figure or table that shows measured numbers is generated from the CSV when the book is
+built. Numbers are never typed in by hand:
+
+```latex
+\begin{tikzpicture}
+  \begin{axis}[xlabel=run, ylabel=K]
+    \addplot table[col sep=comma, x=run, y=K]{experiments/<campaign>/results.csv};
+  \end{axis}
+\end{tikzpicture}
+\datasource{experiments/<campaign>/results.csv}
+```
+
+Use `\pgfplotstabletypeset[col sep=comma]{...}` for tables. `\datasource` prints the CSV path
+and the commit, so a reader can find the exact file the figure was drawn from. CSV paths are
+repo-relative, because xelatex runs from the repo root.
+
+## Older pipelines to fold in or retire
+
+These still exist and still have their own targets. Each one needs a decision during the
+curation pass: move it into this book, or retire it.
+
+| Source | Current target | Produces |
+|---|---|---|
+| `docs/formal/vol1-vm-physics`, `vol2-kernel`, `vol3-research` | `make -C docs/formal vols` | three volume PDFs |
+| `docs/formal/dev-guide`, `user-guide`, `cookbook` | `make -C docs/formal books` | three practitioner PDFs |
+| `docs/formal/experiments`, `proofs`, `ssrn`, `patent` | `make -C docs/formal standalone` | four standalone PDFs |
+| Doxygen (`Doxyfile`) | `make -C docs/formal doxygen` | API reference PDF |
+| `scripts/generate-doxygen-appendix.sh` | `make -f v3/Makefile api-docs` | AsciiDoc API appendix |
+| `docs/src/internal/formal/*.thy` | `make -f v3/Makefile docs-isabelle` | Isabelle report |
+| `scripts/asciidoc-to-latex.sh` | `make -f v3/Makefile docs-latex` | `docs/latex/` |
+| `docs/SSRN_companion/Math_Companion_SSRN.tex` | `make -f v3/Makefile math-companion` | SSRN math companion |
@@ -0,0 +1,161 @@
+% docs/book/main.tex -- master file of the single LithosAnanke book.
+%
+% Built by `make docs [TARGET=<board>]` (docs/book/Makefile) with xelatex.
+% Fragments named below (ontology, fabric-0, ...) are generated by pandoc
+% from the Markdown listed in docs/book/Makefile's CHAPTERS into
+% build/docs/gen/; meta.tex is generated per build. Neither is committed.
+\documentclass[11pt,openany]{book}
+
+\usepackage{amsmath,amssymb}
+\usepackage{fontspec}
+% fonts-dejavu-core has no serif/sans italics (fonts-dejavu-extra does); when a
+% shape is missing, slant the upright one rather than silently drop emphasis.
+\setmainfont{DejaVu Serif}[AutoFakeSlant=0.2]
+\setsansfont{DejaVu Sans}[AutoFakeSlant=0.2]
+\setmonofont{DejaVu Sans Mono}[Scale=0.85]
+\newfontfamily\symbolfont{DejaVu Sans}
+
+\usepackage[letterpaper,margin=1in]{geometry}
+\usepackage{xcolor}
+\usepackage{graphicx}
+\usepackage{longtable,booktabs,array,calc,multirow}
+\usepackage{fancyvrb}
+\usepackage[normalem]{ulem}
+\usepackage{enumitem}
+\usepackage{newunicodechar}
+\usepackage{pgfplots}
+\usepackage{pgfplotstable}
+\pgfplotsset{compat=1.18}
+\usepackage[hidelinks]{hyperref}
+\usepackage{bookmark}
+
+% --- what pandoc's LaTeX fragments expect (normally from its own template)
+\providecommand{\tightlist}{\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+\providecommand{\pandocbounded}[1]{#1}
+\providecommand{\st}[1]{\sout{#1}}
+\newcounter{none} % pandoc: {\def\LTcaptype{none} ...} marks unnumbered tables
+\usepackage{etoolbox}
+\makeatletter
+\def\fnum@table{\tablename~\thetable}
+\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{}
+\makeatother
+\usepackage{fvextra}
+\input{pandoc-highlighting}
+% Code and diagrams are wider than the page in places: wrap, never overflow.
+\RecustomVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\},breaklines,breakanywhere,fontsize=\small}
+\RecustomVerbatimEnvironment{verbatim}{Verbatim}{breaklines,breakanywhere,fontsize=\small}
+\setlistdepth{9}
+\renewlist{itemize}{itemize}{9}
+\setlist[itemize]{label=\textbullet}
+\renewlist{enumerate}{enumerate}{9}
+\setlist[enumerate]{label=\arabic*.}
+% Running heads: chapter on the left page, section on the right, both cut to
+% the page width (several design-record titles are a full sentence long).
+\usepackage{fancyhdr}
+\usepackage[fit]{truncate}
+\pagestyle{fancy}
+\fancyhf{}
+\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
+\renewcommand{\sectionmark}[1]{\markright{#1}}
+\fancyhead[LE]{\small\truncate{\dimexpr\headwidth-3em}{\leftmark}}
+\fancyhead[RO]{\small\truncate{\dimexpr\headwidth-3em}{\rightmark}}
+\fancyhead[RE,LO]{\small\thepage}
+\renewcommand{\headrulewidth}{0.4pt}
+\setlength{\headheight}{14pt}
+\fancypagestyle{plain}{\fancyhf{}\fancyfoot[C]{\small\thepage}\renewcommand{\headrulewidth}{0pt}}
+\setlength{\emergencystretch}{3em}
+\setlength{\parindent}{0pt}
+\setlength{\parskip}{0.5em}
+
+% --- glyphs DejaVu Serif lacks: the status marks used across the docs
+\newunicodechar{✅}{{\symbolfont ✔}}
+\newunicodechar{✓}{{\symbolfont ✓}}
+\newunicodechar{❌}{{\symbolfont ✘}}
+\newunicodechar{✗}{{\symbolfont ✗}}
+\newunicodechar{⬜}{{\symbolfont ☐}}
+\newunicodechar{⭐}{{\symbolfont ★}}
+\newunicodechar{🔶}{{\symbolfont ◆}}
+\newunicodechar{⚠}{{\symbolfont ⚠}}
+\newunicodechar{📋}{}
+\newunicodechar{🐛}{[bug]}
+\newunicodechar{🎯}{[goal]}
+\newunicodechar{🟡}{{\symbolfont ●}}
+\newunicodechar{📍}{{\symbolfont ▸}}
+\newunicodechar{🔓}{[unlocked]}
+\newunicodechar{❓}{?}
+\newunicodechar{⟺}{\ensuremath{\Longleftrightarrow}}
+\newunicodechar{⋯}{\ensuremath{\cdots}}
+\newunicodechar{^^^^fe0f}{}
+
+% --- the documents number their own sections (§III.1, D-3, ...)
+\setcounter{secnumdepth}{0}
+\setcounter{tocdepth}{1}
+
+\input{meta}
+
+% \datasource{path/to/data.csv}: cite the data behind a figure or table.
+% Every figure or table of measured numbers reads its CSV at build time
+% (\addplot table / \pgfplotstabletypeset) and is followed by this line, so
+% the reader can find the exact file at the exact commit.
+\newcommand{\datasource}[1]{%
+  \par{\small Data: \texttt{\detokenize{#1}} at commit \texttt{\bookcommit}.}\par}
+
+\title{LithosAnanke and StarForth}
+\author{}
+\date{Built \bookdate{} from commit \texttt{\bookcommit}%
+  \ifx\bookboard\empty\else\\Board appendix: \bookboard\fi}
+
+\begin{document}
+\frontmatter
+\maketitle
+\tableofcontents
+
+\chapter{About this book}
+This book is generated from the repository by \texttt{make docs}. Each
+chapter below is still maintained as the Markdown file named in the table and
+converted at build time; a chapter moves into LaTeX source when it is
+rewritten. Part~III is the design record: those documents are archival and
+are reproduced as written, including their struck-through corrections.
+
+\begin{longtable}{@{}ll@{}}
+\toprule
+Chapter & Source \\
+\midrule
+\endhead
+Ontology & \texttt{docs/ONTOLOGY.md} \\
+Roadmap & \texttt{docs/ROADMAP.md} \\
+Boot targets & \texttt{boards/README.md} \\
+v4 justification & \texttt{docs/v4.0.0/JUSTIFICATION.md} \\
+v4 decomposition & \texttt{docs/v4.0.0/DECOMPOSITION.md} \\
+FABRIC-0 \dots{} FABRIC-4 & \texttt{docs/fabric/FABRIC-*.md} \\
+Board appendix (\texttt{TARGET=}) & \texttt{boards/<board>/README.md} \\
+\bottomrule
+\end{longtable}
+
+\mainmatter
+
+\part{The system}
+\input{ontology}
+\input{roadmap}
+\input{boards}
+
+\part{StarForth v4}
+\input{justification}
+\input{decomposition}
+
+\part{Design record (FABRIC series)}
+\input{fabric-0}
+\input{fabric-1}
+\input{fabric-2}
+\input{fabric-3}
+\input{fabric-3-5}
+\input{fabric-3-6}
+\input{fabric-3-7}
+\input{fabric-4}
+
+\ifdefined\bookboardappendix
+\appendix
+\input{\bookboardappendix}
+\fi
+
+\end{document}
@@ -0,0 +1,29 @@
+-- docs/book/pandoc/code-breaks.lua
+--
+-- Inline code in the design record is full of long identifiers and paths
+-- (g_wirebind_attached_username, kernel/src/arch/riscv64/...), which LaTeX
+-- cannot break, so they run into the margin. Emit inline code as \texttt
+-- ourselves, escaped the same way pandoc does, with a break opportunity
+-- after each separator character.
+
+local BREAK_AFTER = { ["_"] = true, ["/"] = true, ["."] = true, ["-"] = true,
+                      [":"] = true, [","] = true, ["("] = true, ["="] = true }
+
+local ESCAPE = {
+  ["\\"] = "\\textbackslash{}", ["{"] = "\\{", ["}"] = "\\}",
+  ["$"] = "\\$", ["&"] = "\\&", ["#"] = "\\#", ["%"] = "\\%", ["_"] = "\\_",
+  ["^"] = "\\textasciicircum{}", ["~"] = "\\textasciitilde{}",
+  ["'"] = "\\textquotesingle{}", ["`"] = "\\textasciigrave{}",
+  [" "] = "\\ ",
+}
+
+function Code(el)
+  if not FORMAT:match("latex") then return nil end
+  local out = {}
+  for _, cp in utf8.codes(el.text) do
+    local ch = utf8.char(cp)
+    out[#out + 1] = ESCAPE[ch] or ch
+    if BREAK_AFTER[ch] then out[#out + 1] = "\\allowbreak{}" end
+  end
+  return pandoc.RawInline("latex", "\\texttt{" .. table.concat(out) .. "}")
+end
@@ -0,0 +1,3 @@
+$if(highlighting-macros)$
+$highlighting-macros$
+$endif$
@@ -0,0 +1,55 @@
+-- docs/book/pandoc/table-widths.lua
+--
+-- pandoc's gfm reader leaves every column width unset, so the LaTeX writer
+-- emits `l` columns and a table with long cells runs off the page. For any
+-- table wider than WIDE characters, give each column a width proportional
+-- to its longest cell (clamped to [MIN_COL, MAX_COL] characters); the
+-- writer then emits wrapping p{} columns that together fill \linewidth.
+
+local WIDE    = 72
+local MIN_COL = 6
+local MAX_COL = 60
+
+local stringify = pandoc.utils.stringify
+
+local function measure(rows, widths)
+  for _, row in ipairs(rows) do
+    local col = 1
+    for _, cell in ipairs(row.cells) do
+      local span = cell.col_span or 1
+      local len = utf8.len(stringify(cell.contents)) or #stringify(cell.contents)
+      local per = len / span
+      for c = col, col + span - 1 do
+        if per > (widths[c] or 0) then widths[c] = per end
+      end
+      col = col + span
+    end
+  end
+end
+
+function Table(tbl)
+  local n = #tbl.colspecs
+  local widths = {}
+  for i = 1, n do widths[i] = 0 end
+
+  measure(tbl.head.rows, widths)
+  for _, body in ipairs(tbl.bodies) do
+    measure(body.head, widths)
+    measure(body.body, widths)
+  end
+  measure(tbl.foot.rows, widths)
+
+  local total = 0
+  for i = 1, n do total = total + widths[i] end
+  if total <= WIDE then return nil end
+
+  local sum = 0
+  for i = 1, n do
+    widths[i] = math.max(MIN_COL, math.min(MAX_COL, widths[i]))
+    sum = sum + widths[i]
+  end
+  for i = 1, n do
+    tbl.colspecs[i] = { tbl.colspecs[i][1], widths[i] / sum }
+  end
+  return tbl
+end
@@ -1,13 +1,13 @@
 # ==============================================================================
-# Makefile.starkernel — StarKernel UEFI Build System
+# kernel/Makefile — StarKernel UEFI Build System
 # Multi-architecture: amd64 (x86_64), aarch64 (ARM64), riscv64 (RISC-V 64)
 #
 # Quick start:
-#   make -f Makefile.starkernel                        — build for host arch
-#   make -f Makefile.starkernel ARCH=amd64 qemu        — build + boot (x86_64)
-#   make -f Makefile.starkernel ARCH=aarch64 qemu      — build + boot (aarch64)
-#   make -f Makefile.starkernel ARCH=riscv64 qemu      — build + boot (riscv64)
-#   make -f Makefile.starkernel help                   — show all targets
+#   make -f kernel/Makefile                        — build for host arch
+#   make -f kernel/Makefile ARCH=amd64 qemu        — build + boot (x86_64)
+#   make -f kernel/Makefile ARCH=aarch64 qemu      — build + boot (aarch64)
+#   make -f kernel/Makefile ARCH=riscv64 qemu      — build + boot (riscv64)
+#   make -f kernel/Makefile help                   — show all targets
 # ==============================================================================

 # ==============================================================================
@@ -64,7 +64,7 @@ $(eval $(call kconfig_bool,STARFORTH_ENABLE_VM,1))
 MONOLITHIC ?= 1

 # Parallel build — use all available cores when not cleaning
-# (adding -j when 'clean' is also a goal causes a race on include/version.h)
+# (adding -j when 'clean' is also a goal causes a race on v3/include/version.h)
 NPROC := $(shell nproc 2>/dev/null || echo 4)
 ifeq ($(filter clean,$(MAKECMDGOALS)),)
 MAKEFLAGS += -j$(NPROC)
@@ -106,9 +106,9 @@ KERNEL_OBJ_DIR     := $(OBJ_DIR)/kernel
 LOADER_EFI         := $(BUILD_DIR)/starkernel_loader.efi
 KERNEL_ELF         := $(BUILD_DIR)/starkernel_kernel.elf

-KERNEL_SRC         := src/starkernel
-KERNEL_INC         := include/starkernel
-STARFORTH_CONFIG_HEADER := include/starforth_config.h
+KERNEL_SRC         := kernel/src
+KERNEL_INC         := kernel/include/starkernel
+STARFORTH_CONFIG_HEADER := v3/include/starforth_config.h

 QEMU_LOG_DIR       := logs
 QEMU_ISO           := $(BUILD_DIR)/starkernel.iso
@@ -129,17 +129,17 @@ ARTDISK            ?= disk/artemis.img
 # headroom above the current 9-device identity roster (Zuse + 8 minted identities)
 # rather than matching it exactly, per Bob's standing ruling against hardcoding a bound
 # to today's scale (FABRIC-3.md §VII.4). Override if a future test needs more, e.g.
-# `make -f Makefile.starkernel qemu XHCI_PORTS=32`.
+# `make -f kernel/Makefile qemu XHCI_PORTS=32`.
 XHCI_PORTS         ?= 16
 # ZUSEDISK -- Zuse's own minted USB thumbdrive, attached by default so a
 # plain `make qemu` lands already authenticated into the Zuse identity
 # (Captain Bob, 2026-08-28). Attached at QEMU launch time via -drive/
 # -device on the qemu-xhci controller each arch's qemu target already
-# creates; xhci_bringup()'s initial port scan (src/starkernel/usb/xhci.c)
+# creates; xhci_bringup()'s initial port scan (kernel/src/usb/xhci.c)
 # is what makes an already-connected-at-launch device visible at all --
 # xhci_poll_events() alone is purely hotplug-event-driven and would never
 # see a device present before controller reset. Override to "" (empty) to
-# boot without Zuse attached, e.g. `make -f Makefile.starkernel qemu ZUSEDISK=`.
+# boot without Zuse attached, e.g. `make -f kernel/Makefile qemu ZUSEDISK=`.
 ZUSEDISK           ?= disk/thumbdrives/zuse-thumb-ident.img
 # Precomputed (not inlined as $(if ...,...)) because the drive/device specs
 # below are comma-heavy and GNU make's $(if) function splits its own
@@ -153,10 +153,10 @@ else
 ZUSEDISK_QEMU_ARGS :=
 endif
 MKCAPSULE_SRC       = tools/mkcapsule.c tools/pkcs8_ed25519.c \
-                      src/starkernel/crypto/ed25519.c \
-                      src/starkernel/crypto/fe25519.c \
-                      src/starkernel/crypto/scalar25519.c \
-                      src/starkernel/crypto/sha512.c
+                      kernel/src/crypto/ed25519.c \
+                      kernel/src/crypto/fe25519.c \
+                      kernel/src/crypto/scalar25519.c \
+                      kernel/src/crypto/sha512.c
 MKCAPSULE_BIN       = $(BUILD_DIR)/tools/mkcapsule
 # Milestone 6 (Phase 8): the snakeoil intermediate's private key, generated
 # offline outside this repo entirely (see FABRIC-2.md's Phase 8 §Milestone 6
@@ -169,6 +169,28 @@ CAPSULE_GENERATED   = $(BUILD_DIR)/capsule_generated.c
 CAPSULE_GENERATED_OBJ  = $(BUILD_DIR)/capsule_generated.o
 CAPSULE_GENERATED_KOBJ = $(KERNEL_OBJ_DIR)/capsule_generated.o

+# ==============================================================================
+# BOARD (boot_image)
+# ==============================================================================
+# BOARD names a directory under boards/ (ser5, raspi, milkv, ...). Its
+# board.mk sets BOARD_ARCH, BOARD_BOOT (how the firmware finds us) and
+# BOARD_IMAGE (the single file written to the boot medium). The root
+# Makefile's `make boot_image TARGET=<NAME>` maps NAME to BOARD and passes
+# ARCH=$(BOARD_ARCH); the kernel objects themselves are the ordinary
+# build/$(ARCH)/kernel ones, shared with `make qemu`.
+BOARD ?=
+ifneq ($(strip $(BOARD)),)
+ifeq ($(wildcard boards/$(BOARD)/board.mk),)
+    $(error Unknown BOARD='$(BOARD)': no boards/$(BOARD)/board.mk)
+endif
+include boards/$(BOARD)/board.mk
+ifneq ($(BOARD_ARCH),$(ARCH))
+    $(error BOARD=$(BOARD) is ARCH=$(BOARD_ARCH), but ARCH=$(ARCH) was requested)
+endif
+BOARD_OUT := build/boards/$(BOARD)
+endif
+BOOT_IMAGE_SIZE_MIB ?= 128
+
 # ==============================================================================
 # TOOLCHAIN
 # ==============================================================================
@@ -195,8 +217,8 @@ ifeq ($(ARCH),amd64)
    # correctly. These flags come after COMMON_CFLAGS on the command line so
    # they win for amd64 only; riscv64/aarch64 keep -fPIC.
    ARCH_CFLAGS          := -m64 -march=x86-64 -mno-red-zone -DARCH_AMD64 -fno-pic -fno-pie
-    LOADER_LINKER_SCRIPT := linker/starkernel-loader-amd64.ld
-    KERNEL_LINKER_SCRIPT := linker/starkernel-kernel-amd64.ld
+    LOADER_LINKER_SCRIPT := kernel/linker/starkernel-loader-amd64.ld
+    KERNEL_LINKER_SCRIPT := kernel/linker/starkernel-kernel-amd64.ld

 else ifeq ($(ARCH),aarch64)
    ifneq ($(shell which aarch64-linux-gnu-gcc 2>/dev/null),)
@@ -211,14 +233,16 @@ else ifeq ($(ARCH),aarch64)
        $(error No ARM64 toolchain found. Install aarch64-linux-gnu-gcc or aarch64-none-elf-gcc)
    endif
    # aarch64 loader uses clang + lld-link (COFF target — GCC cannot produce aarch64 PE)
-    LOADER_CC            := clang-18
-    # Debian/Ubuntu package only installs the versioned lld-link-18 on PATH by
-    # default (unversioned lld-link lives under /usr/lib/llvm-18/bin, which
+    # Any clang with the aarch64 COFF backend works; the version is not
+    # pinned (Ubuntu 26.04 ships clang-21, older hosts clang-18).
+    LOADER_CC            := $(shell which clang 2>/dev/null || ls /usr/bin/clang-[0-9]* 2>/dev/null | sort -V | tail -1 || echo clang)
+    # Debian/Ubuntu package only installs the versioned lld-link-NN on PATH by
+    # default (unversioned lld-link lives under /usr/lib/llvm-NN/bin, which
    # isn't on PATH unless explicitly prepended) — detect whichever resolves.
-    LOADER_LD            := $(shell which lld-link 2>/dev/null || which lld-link-18 2>/dev/null || echo lld-link)
+    LOADER_LD            := $(shell which lld-link 2>/dev/null || ls /usr/bin/lld-link-[0-9]* /usr/lib/llvm-*/bin/lld-link 2>/dev/null | sort -V | tail -1 || echo lld-link)
    ARCH_CFLAGS          := -march=armv8-a -mcpu=cortex-a72 -DARCH_AARCH64 -mno-outline-atomics
-    LOADER_LINKER_SCRIPT := linker/starkernel-loader-aarch64.ld
-    KERNEL_LINKER_SCRIPT := linker/starkernel-kernel-aarch64.ld
+    LOADER_LINKER_SCRIPT := kernel/linker/starkernel-loader-aarch64.ld
+    KERNEL_LINKER_SCRIPT := kernel/linker/starkernel-kernel-aarch64.ld

 else ifeq ($(ARCH),riscv64)
    ifneq ($(shell which riscv64-unknown-elf-gcc 2>/dev/null),)
@@ -233,8 +257,8 @@ else ifeq ($(ARCH),riscv64)
        $(error No RISC-V toolchain found. Install riscv64-unknown-elf-gcc or riscv64-linux-gnu-gcc)
    endif
    ARCH_CFLAGS          := -march=rv64gc -mabi=lp64d -DARCH_RISCV64
-    LOADER_LINKER_SCRIPT := linker/starkernel-loader-riscv64.ld
-    KERNEL_LINKER_SCRIPT := linker/starkernel-kernel-riscv64.ld
+    LOADER_LINKER_SCRIPT := kernel/linker/starkernel-loader-riscv64.ld
+    KERNEL_LINKER_SCRIPT := kernel/linker/starkernel-kernel-riscv64.ld
 endif

 # Default loader toolchain = kernel toolchain (overridden for aarch64 above)
@@ -260,13 +284,13 @@ COMMON_CFLAGS := \
    -ffreestanding -nostdlib -fno-builtin \
    -fPIC -fvisibility=hidden -fno-stack-protector -fshort-wchar \
    $(ARCH_CFLAGS) \
-    -I$(KERNEL_INC) -Iinclude -Isrc \
+    -I$(KERNEL_INC) -Iv3/include -Ikernel/include -Iv3/src \
    -include $(STARFORTH_CONFIG_HEADER) \
    -DPARITY_MODE=$(PARITY_MODE)

 VMCORE_CFLAGS_COMMON := \
    $(filter-out -I$(KERNEL_INC),$(COMMON_CFLAGS)) \
-    -Iinclude -I. -Isrc/word_source -Isrc/test_runner/include \
+    -Iv3/include -Ikernel/include -I. -Iv3/src/word_source -Iv3/src/test_runner/include \
    -Wno-error=unused-parameter -Wno-error=shift-negative-value \
    -Wno-error=sign-compare -Wno-error=missing-field-initializers

@@ -281,8 +305,8 @@ LOADER_BASE_CFLAGS := \
    -mno-stack-arg-probe \
    -march=armv8-a \
    -DARCH_AARCH64 \
-    -I$(KERNEL_INC) -Iinclude -Isrc \
-    -Iinclude/starkernel/freestanding \
+    -I$(KERNEL_INC) -Iv3/include -Ikernel/include -Iv3/src \
+    -Ikernel/include/starkernel/freestanding \
    -include $(STARFORTH_CONFIG_HEADER) \
    -DPARITY_MODE=$(PARITY_MODE) \
    -DPLATFORM_TIME_NO_INLINE
@@ -308,7 +332,7 @@ ifeq ($(ARCH),aarch64)
 else ifeq ($(ARCH),riscv64)
    LOADER_LDFLAGS_PE :=   # ELF→objcopy pipeline in link rule
 else
-    LOADER_LINKER_SCRIPT_PE := linker/starkernel-loader-amd64-pe.ld
+    LOADER_LINKER_SCRIPT_PE := kernel/linker/starkernel-loader-amd64-pe.ld
    LOADER_LDFLAGS_PE := \
        -T $(LOADER_LINKER_SCRIPT_PE) -m i386pep -nostdlib \
        --enable-reloc-section --image-base 0 --subsystem 10 -e efi_main
@@ -429,7 +453,7 @@ LOADER_CFLAGS += $(VM_FEATURE_OVERRIDES)
 endif

 # SK_CMD — optional startup FORTH script injected before the interactive REPL.
-# Usage: make -f Makefile.starkernel qemu SK_CMD="TIME-TICKS . BYE"
+# Usage: make -f kernel/Makefile qemu SK_CMD="TIME-TICKS . BYE"
 ifdef SK_CMD
 KERNEL_CFLAGS += -DSK_STARTUP_FORTH='"$(SK_CMD)"'
 LOADER_CFLAGS += -DSK_STARTUP_FORTH='"$(SK_CMD)"'
@@ -439,7 +463,7 @@ endif
 # The loader reads this file from the EFI partition and parses it at boot.
 # Supported flags: --doe  --log-level=<debug|info|warn|error>
 #                  --stack=<N>[MG]  --heap=<N>[MG]
-# Usage: make -f Makefile.starkernel qemu KERNEL_ARGS="--doe --log-level=info"
+# Usage: make -f kernel/Makefile qemu KERNEL_ARGS="--doe --log-level=info"
 KERNEL_ARGS ?=

 # ==============================================================================
@@ -534,19 +558,19 @@ KERNEL_ASM := $(wildcard $(KERNEL_SRC)/arch/$(ARCH)/*.S)

 ifeq ($(STARFORTH_ENABLE_VM),1)
 VM_ALL_SRCS := \
-    $(wildcard src/*.c) \
-    $(wildcard src/word_source/*.c) \
-    $(wildcard src/test_runner/*.c) \
-    $(wildcard src/test_runner/modules/*.c)
+    $(wildcard v3/src/*.c) \
+    $(wildcard v3/src/word_source/*.c) \
+    $(wildcard v3/src/test_runner/*.c) \
+    $(wildcard v3/src/test_runner/modules/*.c)

 VM_EXCLUDE := \
-    src/main.c src/cli.c src/repl.c \
-    src/platform/% \
-    src/blkio_factory.c src/blkio_file.c \
-    src/log.c src/doe_metrics.c \
-    src/vm.c src/vm_core.c src/vm_bootstrap.c src/vm_runtime.c src/vm_time.c \
-    src/word_source/q48_16_words.c \
-    src/test_runner/modules/break_me_tests.c
+    v3/src/main.c v3/src/cli.c v3/src/repl.c \
+    v3/src/platform/% \
+    v3/src/blkio_factory.c v3/src/blkio_file.c \
+    v3/src/log.c v3/src/doe_metrics.c \
+    v3/src/vm.c v3/src/vm_core.c v3/src/vm_bootstrap.c v3/src/vm_runtime.c v3/src/vm_time.c \
+    v3/src/word_source/q48_16_words.c \
+    v3/src/test_runner/modules/break_me_tests.c

 VM_CORE_SRCS := $(filter-out $(VM_EXCLUDE),$(VM_ALL_SRCS))

@@ -569,8 +593,8 @@ LOADER_EXTRA_SRCS := \

 KERNEL_EXTRA_SRCS := $(LOADER_EXTRA_SRCS)

-LOADER_VM_OBJS := $(patsubst src/%.c,$(LOADER_OBJ_DIR)/vmcore/%.o,$(VM_CORE_SRCS))
-KERNEL_VM_OBJS := $(patsubst src/%.c,$(KERNEL_OBJ_DIR)/vmcore/%.o,$(VM_CORE_SRCS))
+LOADER_VM_OBJS := $(patsubst v3/src/%.c,$(LOADER_OBJ_DIR)/vmcore/%.o,$(VM_CORE_SRCS))
+KERNEL_VM_OBJS := $(patsubst v3/src/%.c,$(KERNEL_OBJ_DIR)/vmcore/%.o,$(VM_CORE_SRCS))
 endif

 LOADER_SRCS := $(LOADER_SRCS_BASE) $(LOADER_EXTRA_SRCS)
@@ -603,7 +627,7 @@ KERNEL_OBJS := \
 # MAIN TARGETS
 # ==============================================================================

-all: include/version.h $(CAPSULE_GENERATED_OBJ) $(CAPSULE_GENERATED_KOBJ) $(LOADER_EFI) $(KERNEL_ELF)
+all: v3/include/version.h $(CAPSULE_GENERATED_OBJ) $(CAPSULE_GENERATED_KOBJ) $(LOADER_EFI) $(KERNEL_ELF)
 	@echo "StarKernel built successfully for $(ARCH)"
 	@echo "  Loader: $(LOADER_EFI)"
 	@echo "  Kernel: $(KERNEL_ELF)"
@@ -611,13 +635,13 @@ all: include/version.h $(CAPSULE_GENERATED_OBJ) $(CAPSULE_GENERATED_KOBJ) $(LOAD
 kernel: all

 kernel-all:
-	@$(MAKE) -f Makefile.starkernel ARCH=amd64   TARGET=$(TARGET)
-	@$(MAKE) -f Makefile.starkernel ARCH=aarch64 TARGET=$(TARGET)
-	@$(MAKE) -f Makefile.starkernel ARCH=riscv64 TARGET=$(TARGET)
+	@$(MAKE) -f kernel/Makefile ARCH=amd64   TARGET=$(TARGET)
+	@$(MAKE) -f kernel/Makefile ARCH=aarch64 TARGET=$(TARGET)
+	@$(MAKE) -f kernel/Makefile ARCH=riscv64 TARGET=$(TARGET)

 clean:
 	rm -rf build/$(ARCH)/$(TARGET)
-	rm -f include/version.h
+	rm -f v3/include/version.h

 clean-kernel:
 	@echo "Cleaning all StarKernel build artifacts..."
@@ -636,8 +660,8 @@ FORCE:
 # here after a hosted `make` run silently reuses that stale/wrong-flavored file
 # and fails with "LITHOS_VERSION_STR undeclared" deep in kernel_main.c, instead
 # of regenerating its own correct version.
-include/version.h: FORCE
-	@mkdir -p include
+v3/include/version.h: FORCE
+	@mkdir -p v3/include
 	@BUILD_TS=$$(date -Iseconds 2>/dev/null || echo "unknown"); \
 	printf '#ifndef STARFORTH_VERSION_H\n#define STARFORTH_VERSION_H\n\n' > $@; \
 	printf '#define STARFORTH_VERSION "%s"\n' "$(VERSION)" >> $@; \
@@ -653,7 +677,7 @@ include/version.h: FORCE
 $(MKCAPSULE_BIN): $(MKCAPSULE_SRC)
 	@mkdir -p $(dir $@)
 	@echo "HOSTCC  $(MKCAPSULE_SRC)"
-	@cc -std=c99 -Wall -Wextra -O2 -Iinclude -Itools -o $@ $(MKCAPSULE_SRC)
+	@cc -std=c99 -Wall -Wextra -O2 -Iv3/include -Ikernel/include -Itools -o $@ $(MKCAPSULE_SRC)

 # Generate capsule_generated.c from capsules/
 CAPSULE_SRCS := $(shell find $(CAPSULES_DIR) -type f ! -name '.*' 2>/dev/null)
@@ -695,12 +719,12 @@ $(LOADER_OBJ_DIR)/%.o: $(KERNEL_SRC)/%.c | $(LOADER_OBJ_DIR)
 	@$(LOADER_CC) $(LOADER_CFLAGS) -c $< -o $@

 # Compile loader VM core sources
-$(LOADER_OBJ_DIR)/vmcore/%.o: src/%.c include/version.h | $(LOADER_OBJ_DIR)
+$(LOADER_OBJ_DIR)/vmcore/%.o: v3/src/%.c v3/include/version.h | $(LOADER_OBJ_DIR)
 	@mkdir -p $(dir $@)
 	@echo "CC (loader) $<"
 ifeq ($(ARCH),aarch64)
 	@$(LOADER_CC) $(LOADER_CFLAGS) \
-	    -Iinclude -I. -Isrc/test_runner/include \
+	    -Iv3/include -Ikernel/include -I. -Iv3/src/test_runner/include \
 	    -Wno-error=unused-parameter -Wno-error=shift-negative-value \
 	    -Wno-error=sign-compare -Wno-error=missing-field-initializers \
 	    -Wno-unused-function \
@@ -722,10 +746,10 @@ $(KERNEL_OBJ_DIR)/%.o: $(KERNEL_SRC)/%.c | $(KERNEL_OBJ_DIR)
 	@$(CC) $(KERNEL_CFLAGS) -c $< -o $@

 # Compile kernel VM core sources
-$(KERNEL_OBJ_DIR)/vmcore/%.o: src/%.c include/version.h | $(KERNEL_OBJ_DIR)
+$(KERNEL_OBJ_DIR)/vmcore/%.o: v3/src/%.c v3/include/version.h | $(KERNEL_OBJ_DIR)
 	@mkdir -p $(dir $@)
 	@echo "CC (kernel) $<"
-	@$(CC) $(VMCORE_CFLAGS_COMMON) $(filter-out -I$(KERNEL_INC),$(KERNEL_CFLAGS)) -Isrc/starkernel/vm -c $< -o $@
+	@$(CC) $(VMCORE_CFLAGS_COMMON) $(filter-out -I$(KERNEL_INC),$(KERNEL_CFLAGS)) -Ikernel/src/vm -c $< -o $@

 # Compile kernel assembly sources
 $(KERNEL_OBJ_DIR)/%.o: $(KERNEL_SRC)/%.S | $(KERNEL_OBJ_DIR)
@@ -802,7 +826,7 @@ OVMF_CODE    := /usr/share/OVMF/OVMF_CODE_4M.fd
 OVMF_VARS_RO := /usr/share/OVMF/OVMF_VARS_4M.fd

 # QEMU_DISPLAY — window backend for the framebuffer console (gtk/sdl/none/...).
-# Usage: make -f Makefile.starkernel qemu QEMU_DISPLAY=none   # headless/CI
+# Usage: make -f kernel/Makefile qemu QEMU_DISPLAY=none   # headless/CI
 QEMU_DISPLAY ?= gtk

 # QEMU_EXTRA — extra raw qemu-system-* args appended verbatim to every arch's
@@ -1072,38 +1096,98 @@ else ifeq ($(ARCH),riscv64)
 # fallback boot path EFI/BOOT/BOOT<ARCH>.EFI. Storage on real hardware is the
 # USB BOT/xHCI path (already live), not virtio.
 thumbdrive: all
-	@mkdir -p $(BUILD_DIR)
-	@if ! which sgdisk >/dev/null 2>&1; then echo "Error: sgdisk not found. Install gdisk (apt-get install gdisk)."; exit 1; fi
-	@if ! which mkfs.fat >/dev/null 2>&1; then echo "Error: mkfs.fat not found. Install dosfstools (apt-get install dosfstools)."; exit 1; fi
-	@case "$(ARCH)" in \
-		amd64)  BOOTNAME="BOOTX64.EFI"    ;; \
-		aarch64) BOOTNAME="BOOTAA64.EFI"  ;; \
-		riscv64) BOOTNAME="BOOTRISCV64.EFI" ;; \
-		*) echo "Error: no thumbdrive EFI boot name for ARCH=$(ARCH)"; exit 1 ;; \
-	esac; \
-	# Geometry: 128 MiB disk (262144 sectors), GPT partition 1 spans sectors \
-	# 2048..262110 (the GPT last-usable sector for this disk size), i.e.   \
-	# 260063 sectors. The FAT32 ESP image MUST match the partition size    \
-	# exactly; a larger ESP overruns the disk (GPT grows corrupt) or       \
-	# spills past the partition end, both of which made earlier builds     \
-	# unbootable on hardware.                                              \
-	DISK=$(BUILD_DIR)/starkernel-thumbdrive.img; \
-	ESP_SECTORS=260063; \
-	rm -f $$DISK $(BUILD_DIR)/thumbdrive-esp.img; \
-	dd if=/dev/zero of=$(BUILD_DIR)/thumbdrive-esp.img bs=512 count=$$ESP_SECTORS 2>/dev/null; \
-	mkfs.fat -F 32 -n "STARKERNEL" $(BUILD_DIR)/thumbdrive-esp.img >/dev/null 2>&1; \
-	mmd    -i $(BUILD_DIR)/thumbdrive-esp.img ::/EFI; \
-	mmd    -i $(BUILD_DIR)/thumbdrive-esp.img ::/EFI/BOOT; \
-	mcopy  -i $(BUILD_DIR)/thumbdrive-esp.img $(LOADER_EFI) ::/EFI/BOOT/$$BOOTNAME; \
-	printf 'FS0:\\EFI\\BOOT\\%s\r\n' "$$BOOTNAME" > $(BUILD_DIR)/thumbdrive-startup.nsh; \
-	mcopy -i $(BUILD_DIR)/thumbdrive-esp.img $(BUILD_DIR)/thumbdrive-startup.nsh ::/startup.nsh; \
-	dd if=/dev/zero of=$$DISK bs=1M count=128 2>/dev/null; \
-	sgdisk -n 1:2048:0 -t 1:ef00 -c 1:"EFI System" $$DISK >/dev/null 2>&1; \
-	dd if=$(BUILD_DIR)/thumbdrive-esp.img of=$$DISK bs=512 seek=2048 conv=notrunc 2>/dev/null; \
-	rm -f $(BUILD_DIR)/thumbdrive-esp.img $(BUILD_DIR)/thumbdrive-startup.nsh; \
-	echo "Thumbdrive image: $$DISK"; \
-	echo "Write to a USB stick with: dd if=$$DISK of=/dev/sdX bs=4M status=progress"
+	@printf 'FS0:\\EFI\\BOOT\\%s\r\n' "$(EFI_BOOTNAME)" > $(BUILD_DIR)/thumbdrive-startup.nsh
+	@bash scripts/mkdiskimage.sh --out $(BUILD_DIR)/starkernel-thumbdrive.img --table gpt \
+	    --size-mib 128 --label STARKERNEL \
+	    $(LOADER_EFI):/EFI/BOOT/$(EFI_BOOTNAME) \
+	    $(BUILD_DIR)/thumbdrive-startup.nsh:/startup.nsh
+	@rm -f $(BUILD_DIR)/thumbdrive-startup.nsh
+	@echo "Write to a USB stick with: dd if=$(BUILD_DIR)/starkernel-thumbdrive.img of=/dev/sdX bs=4M status=progress"

+# ==============================================================================
+# BOOT IMAGES (one per board)
+# ==============================================================================
+# boot_image -- the single file written to a board's boot medium. Driven by
+# BOARD (boards/<board>/board.mk); normally invoked from the repo root as
+#   make boot_image TARGET=SER5|RASPI|MILKV|ZYNQ7020
+# Output: build/boards/<board>/$(BOARD_IMAGE).
+#
+# BOARD_BOOT selects the recipe:
+#   uefi-esp   -- GPT disk, one FAT32 EFI System Partition holding the
+#                 monolithic loader as EFI/BOOT/BOOT<ARCH>.EFI (+ startup.nsh
+#                 for the UEFI shell, + starforth.cfg when KERNEL_ARGS is set).
+#                 Real UEFI firmware (SER5) and U-Boot's bootefi (Milk-V) both
+#                 boot it through the removable-media fallback path.
+#   rpi-native -- MBR disk, one FAT32 (LBA) partition holding config.txt,
+#                 kernel_2712.img (kernel relinked at 0x80000 and flattened)
+#                 and the stock BCM2712 DTB (+ cmdline.txt, which firmware
+#                 copies into /chosen/bootargs, when KERNEL_ARGS is set).
+ifeq ($(ARCH),amd64)
+EFI_BOOTNAME := BOOTX64.EFI
+else ifeq ($(ARCH),aarch64)
+EFI_BOOTNAME := BOOTAA64.EFI
+else ifeq ($(ARCH),riscv64)
+EFI_BOOTNAME := BOOTRISCV64.EFI
+endif
+
+RPI5_NATIVE_LINKER_SCRIPT := kernel/linker/starkernel-native-rpi5.ld
+RPI5_NATIVE_ELF           := $(BUILD_DIR)/starkernel_rpi5.elf
+RPI5_NATIVE_IMG           := $(BUILD_DIR)/kernel_2712.img
+
+$(RPI5_NATIVE_ELF): $(KERNEL_OBJS) $(RPI5_NATIVE_LINKER_SCRIPT) | $(BUILD_DIR)
+	@echo "LD (rpi5 native) $@"
+	@$(LD) -T $(RPI5_NATIVE_LINKER_SCRIPT) -nostdlib --build-id=none \
+	    -e rpi5_native_start $(KERNEL_OBJS) -o $@
+
+$(RPI5_NATIVE_IMG): $(RPI5_NATIVE_ELF)
+	@echo "OBJCOPY (raw) $@"
+	@$(OBJCOPY) -O binary $< $@
+
+.PHONY: boot_image
+ifeq ($(strip $(BOARD)),)
+boot_image:
+	@echo "boot_image needs a board. From the repo root:"
+	@echo "  make boot_image TARGET=SER5|RASPI|MILKV|ZYNQ7020"
+	@exit 1
+else ifeq ($(BOARD_BOOT),uefi-esp)
+boot_image: all
+	@mkdir -p $(BOARD_OUT)
+	@printf 'FS0:\\EFI\\BOOT\\%s\r\n' "$(EFI_BOOTNAME)" > $(BOARD_OUT)/startup.nsh
+	@rm -f $(BOARD_OUT)/starforth.cfg
+	$(if $(KERNEL_ARGS),@printf '%s\n' '$(KERNEL_ARGS)' > $(BOARD_OUT)/starforth.cfg)
+	@bash scripts/mkdiskimage.sh --out $(BOARD_OUT)/$(BOARD_IMAGE) --table gpt \
+	    --size-mib $(BOOT_IMAGE_SIZE_MIB) --label LITHOS \
+	    $(LOADER_EFI):/EFI/BOOT/$(EFI_BOOTNAME) \
+	    $(BOARD_OUT)/startup.nsh:/startup.nsh \
+	    $(if $(KERNEL_ARGS),$(BOARD_OUT)/starforth.cfg:/starforth.cfg)
+	@echo "$(BOARD_DESC)"
+	@echo "Write with: dd if=$(BOARD_OUT)/$(BOARD_IMAGE) of=/dev/sdX bs=4M conv=fsync status=progress"
+else ifeq ($(BOARD_BOOT),rpi-native)
+$(RPI5_DTB):
+	@mkdir -p $(dir $@)
+	@echo "  FETCH   $(RPI5_DTB_URL)"
+	@curl -fsSL -o $@.tmp $(RPI5_DTB_URL) || { rm -f $@.tmp; \
+	    echo "Error: could not fetch the Pi 5 DTB. Copy bcm2712-rpi-5-b.dtb from a Raspberry Pi"; \
+	    echo "firmware release and pass RPI5_DTB=/path/to/bcm2712-rpi-5-b.dtb"; exit 1; }
+	@mv $@.tmp $@
+
+boot_image: v3/include/version.h $(RPI5_NATIVE_IMG) $(RPI5_DTB)
+	@mkdir -p $(BOARD_OUT)
+	@rm -f $(BOARD_OUT)/cmdline.txt
+	$(if $(KERNEL_ARGS),@printf '%s\n' '$(KERNEL_ARGS)' > $(BOARD_OUT)/cmdline.txt)
+	@bash scripts/mkdiskimage.sh --out $(BOARD_OUT)/$(BOARD_IMAGE) --table mbr \
+	    --size-mib $(BOOT_IMAGE_SIZE_MIB) --label LITHOS \
+	    boards/$(BOARD)/config.txt:/config.txt \
+	    $(RPI5_NATIVE_IMG):/kernel_2712.img \
+	    $(RPI5_DTB):/bcm2712-rpi-5-b.dtb \
+	    $(if $(KERNEL_ARGS),$(BOARD_OUT)/cmdline.txt:/cmdline.txt)
+	@echo "$(BOARD_DESC)"
+	@echo "Write with: dd if=$(BOARD_OUT)/$(BOARD_IMAGE) of=/dev/mmcblkX bs=4M conv=fsync status=progress"
+else
+boot_image:
+	@echo "Error: BOARD=$(BOARD) has BOARD_BOOT='$(BOARD_BOOT)', which has no boot_image recipe"
+	@exit 1
+endif

 # iso-usb — build a PURE UEFI isohybrid ISO for the Iso Image Writer workflow
 # (GNOME Disks "Restore Disk Image...", or dd). Writes a single .iso to a USB
@@ -1150,7 +1234,7 @@ iso-usb: all
 # yourself with Ctrl-A X or by closing the window).
 # amd64/aarch64: serial → stdio (bidirectional, you can type into the REPL);
 # riscv64: uses proper GPT (esp dir not supported)
-qemu-esp: include/version.h $(LOADER_EFI) $(KERNEL_ELF)
+qemu-esp: v3/include/version.h $(LOADER_EFI) $(KERNEL_ELF)
 ifeq ($(ARCH),amd64)
 	@rm -rf $(BUILD_DIR)/esp
 	@mkdir -p $(BUILD_DIR)/esp/EFI/BOOT
@@ -1206,7 +1290,7 @@ else ifeq ($(ARCH),riscv64)
 endif

 # qemu-gdb — launch QEMU with GDB stub on port 1234
-qemu-gdb: include/version.h $(LOADER_EFI) $(KERNEL_ELF)
+qemu-gdb: v3/include/version.h $(LOADER_EFI) $(KERNEL_ELF)
 ifeq ($(ARCH),amd64)
 	@mkdir -p $(BUILD_DIR)/esp/EFI/BOOT
 	@cp $(LOADER_EFI) $(BUILD_DIR)/esp/EFI/BOOT/BOOTX64.EFI
@@ -1259,7 +1343,7 @@ help:
 	@echo "StarKernel Build System"
 	@echo "======================="
 	@echo ""
-	@echo "Usage: make -f Makefile.starkernel [ARCH=<arch>] [TARGET=<target>] <goal>"
+	@echo "Usage: make -f kernel/Makefile [ARCH=<arch>] [TARGET=<target>] <goal>"
 	@echo ""
 	@echo "Architectures (aliases accepted):"
 	@echo "  ARCH=amd64    / x86_64   — x86-64 (default on x86 host)"
@@ -1289,8 +1373,8 @@ help:
 	@echo "  help          — show this message"
 	@echo ""
 	@echo "Examples:"
-	@echo "  make -f Makefile.starkernel ARCH=amd64 qemu"
-	@echo "  make -f Makefile.starkernel ARCH=aarch64 clean qemu"
-	@echo "  make -f Makefile.starkernel ARCH=riscv64 clean qemu"
-	@echo "  make -f Makefile.starkernel ARCH=x86_64 qemu   # alias works"
-	@echo "  make -f Makefile.starkernel kernel-all"
+	@echo "  make -f kernel/Makefile ARCH=amd64 qemu"
+	@echo "  make -f kernel/Makefile ARCH=aarch64 clean qemu"
+	@echo "  make -f kernel/Makefile ARCH=riscv64 clean qemu"
+	@echo "  make -f kernel/Makefile ARCH=x86_64 qemu   # alias works"
+	@echo "  make -f kernel/Makefile kernel-all"
--- a/Show More
+++ b/Show More