Change the greeter tagline to "Beautiful, Fun & Opinionated"

The same frame opens omarchy's first boot from its own copy of the string, so both repositories change together or an install and the deferred first boot after it bookend the setup with different words. Nothing generates one copy from the other: the vendoring between the repositories covers the setup form, not the greeter.

The line is centred from its own length, so the three characters it loses move it one column and nothing else.

.github/workflows/nightly-build.yml

@@ -2,40 +2,34 @@ name: Nightly ISO Build
 
 on:
   schedule:
-    - cron: '1 0 * * *'  # Daily at 00:01 UTC
-  workflow_dispatch:  # Allow manual triggering
+    - cron: "1 0 * * *" # Daily at 00:01 UTC
+  workflow_dispatch: # Allow manual triggering
 
 jobs:
   build-iso:
     runs-on: ubuntu-latest
-
-    container:
-      image: archlinux/archlinux:latest
-      options: --privileged
-    
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-      
-    - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v3
-      
-    - name: Build ISO in Arch Linux container
-      run: |
-        docker run --rm \
-          --privileged \
-          -v "${{ github.workspace }}:/workspace" \
-          -w /workspace \
-          archlinux:latest \
-          bash -c "
-            pacman -Syu --noconfirm && \
-            chmod +x build_iso.sh && \
-            ./build_iso.sh
-          "
-    
-    - name: Upload ISO artifact
-      uses: actions/upload-artifact@v4
-      with:
-        name: omarchy-iso-${{ github.run_number }}
-        path: out/*.iso
-        retention-days: 30
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Free Disk Space
+        uses: jlumbroso/free-disk-space@v1.3.1
+
+      - name: Build ISO
+        run: NO_BOOT_OFFER=1 ./bin/omarchy-iso-make
+
+      - name: Delete previously uploaded ISO artifact
+        uses: philips-labs/action-delete-artifacts@v1.0.0
+        with:
+          workflow: nightly-build.yml
+        continue-on-error: true
+
+      - name: Upload newly built ISO artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: omarchy-iso-${{ github.run_number }}
+          path: ./release/*.iso
+          retention-days: 1

.gitignore

@@ -1,2 +1,9 @@
 release/**
 vm-saves/**
+
+# Python bytecode (orchestrator)
+__pycache__/
+*.pyc
+
+# Acceptance test harness artifacts
+test-runs/**

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Anton Hvornum
+Copyright (c) 2026 Anton Hvornum
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,39 +1,145 @@
 # Omarchy ISO
 
-The Omarchy ISO streamlines [the installation of Omarchy](https://learn.omacom.io/2/the-omarchy-manual/50/getting-started). It includes the Omarchy Configurator as a front-end to archinstall and automatically launches the [Omarchy Installer](https://github.com/basecamp/omarchy) after base arch has been setup.
+The Omarchy ISO is the only supported way to install Omarchy. It ships the Omarchy Configurator, installs Arch Linux, installs the Omarchy packages from the bundled mirror, runs target system setup in the chroot, creates the user, and runs `omarchy-setup-user` for that user.
 
 ## Downloading the latest ISO
 
 See the ISO link on [omarchy.org](https://omarchy.org).
 
+Every published ISO has a `.sha256` beside it at the same URL. Download both into the same directory and check the ISO before writing it to a USB stick:
+
+```bash
+sha256sum -c omarchy-3.0.iso.sha256
+```
+
+Corruption anywhere in the ISO is worth catching before the write, and corruption in the bundled package mirror is worth catching most: the mirror lives inside the ISO and the installer reads it straight off the medium, so those bytes surface minutes into the install as a pacman "invalid or corrupted package" error rather than as anything that names the download. Corruption elsewhere is louder and earlier — it stops the medium booting or mounting. There is a `.sig` beside the ISO too for anyone who wants to verify it against the Omarchy signing key.
+
 ## Creating the ISO
 
-Run `./bin/omarchy-iso-make` and the output goes into `./release`.
+Run `./bin/omarchy-iso-make`; output goes into `./release`. By default the ISO uses the Omarchy packages and tracks the `quattro` branch, from the stable mirror. Pass `--edge` to use `omarchy-dev` and `omarchy-settings-dev` from the edge mirror.
 
-### Environment Variables
+For local development, build the ISO from sibling checkouts:
 
-You can customize the repositories used during the build process by passing in variables:
-
-- `OMARCHY_INSTALLER_REPO` - GitHub repository for the installer (default: `basecamp/omarchy`)
-- `OMARCHY_INSTALLER_REF` - Git ref (branch/tag) for the installer (default: `master`)
-
-Example usage:
 ```bash
-OMARCHY_INSTALLER_REPO="myuser/omarchy-fork" OMARCHY_INSTALLER_REF="some-feature" ./bin/omarchy-iso-make
+./bin/omarchy-iso-make --local-source ../omarchy-installer ../omarchy-pkgs
 ```
 
+Despite the local folder name, the first argument is the Omarchy source checkout (runtime commands, configs, setup scripts, themes, shell, migrations). The installer itself lives in this ISO repo.
+
+Use `--dev` or `--rc` to build against those package channels. Both `--dev` and `--edge` select the dev packages from the edge mirror.
+
+## Autoinstall
+
+The shipped ISO installs itself with no keyboard when it finds its configuration on a second drive. Attach a drive labeled `cidata` alongside the ISO and the installer copies the config off it and skips the configurator; with no such drive, nothing changes and the wizard runs as usual. No rebuild, no extra boot entry.
+
+`cidata` is the cloud-init `NoCloud` label, so Proxmox, libvirt, and Packer already know how to attach one.
+
+### Configuration files
+
+These are the configurator's own output files, so the way to get a starting set is to run one interactive install and copy what it wrote into `/root`.
+
+| File | Required | Purpose |
+|------|----------|---------|
+| `user_configuration.json` | Yes | archinstall config: disk, hostname, timezone, keyboard |
+| `user_credentials.json` | Yes | Username and password hash |
+| `user_full_name.txt` | No | Git full name |
+| `user_email_address.txt` | No | Git email |
+| `user_encrypt_installation.txt` | No | `true` when `user_configuration.json` carries a `disk_encryption` block; defaults to false |
+| `authorized_keys` | No | SSH public keys in sshd's own format, one per line |
+| `tailscale_authkey` | No | Tailscale auth key; the machine joins your tailnet on first boot |
+
+Both required files must be present or the installer falls back to the configurator. Generate the password hash for `user_credentials.json` with `openssl passwd -6 "yourpassword"`.
+
+Encryption itself is configured by the `disk_encryption` block inside `user_configuration.json` — which carries the passphrase in plaintext, so treat a drive built from an encrypted install accordingly. The flag file must match it: it drives the encrypted install's SDDM autologin and the final boot validation, not the encryption.
+
+`authorized_keys` is the same file sshd reads — copy your own or write one key per line:
+
+```
+ssh-ed25519 AAAA... you@host
+```
+
+When `authorized_keys` is present, autoinstall installs it as the user's `~/.ssh/authorized_keys`, enables `sshd`, and adds a `ufw allow ssh` rule — a stock Omarchy install ships openssh with the service disabled and its firewall opens neither port 22 nor anything else beyond LocalSend. Networking needs nothing extra; NetworkManager is already enabled with DHCP. Password SSH authentication is left at the distro default. An `authorized_keys` with no usable keys fails the install rather than producing a machine nobody can reach.
+
+When `tailscale_authkey` is present (one key, blank lines and `#` comments ignored), the install adds the `tailscale` package from the ISO's bundled mirror — nothing is fetched from the network at install or boot — and stages the join for first boot: the key lands at `/etc/tailscale/authkey` (root-only), `tailscaled` is enabled, ufw allows traffic in on `tailscale0`, and a background unit runs `tailscale up` once the network is actually up, retrying until it succeeds without holding up the boot. After a successful join the key is deleted and the unit disables itself; until then both survive reboots, so a machine installed offline joins whenever it first gets connectivity. The node appears on the tailnet under the configured hostname. Use a reusable, pre-authorized (tagged) key so one drive image serves many machines — or an ephemeral key for disposable VMs.
+
+### Building the drive
+
+```bash
+mkdir cidata
+cp user_configuration.json user_credentials.json authorized_keys cidata/
+genisoimage -output cidata.iso -volid cidata -joliet -rock cidata/
+```
+
+### Proxmox example
+
+```bash
+qm create 101 --name my-omarchy \
+  --bios ovmf --machine q35 --cpu host --cores 4 --memory 8192 \
+  --ostype l26 --scsihw virtio-scsi-single \
+  --efidisk0 local-lvm:0,efitype=4m,pre-enrolled-keys=0 \
+  --scsi0 local-lvm:40,discard=on,iothread=1 \
+  --net0 virtio,bridge=vmbr0 --vga virtio --serial0 socket \
+  --ide2 local:iso/omarchy.iso,media=cdrom \
+  --ide3 local:iso/cidata.iso,media=cdrom \
+  --boot order='scsi0;ide2'
+
+qm start 101
+```
+
+Boot order is disk first: the empty disk falls through to the ISO on the first boot, and the installed system boots from disk afterwards. The machine reboots into Omarchy on its own when the install finishes.
+
+Encrypted autoinstalls are not fully unattended — the LUKS passphrase prompt still needs someone at the first boot.
+
 ## Testing the ISO
 
 Run `./bin/omarchy-iso-boot [release/omarchy.iso]`.
 
+Run `./test/all` for the fast, VM-free tests under `test/unit/`, which cover cidata autoinstall loading and the orchestrator's phases without needing a built ISO.
+
+To exercise installation alongside existing Windows-style partitions, run
+`./bin/omarchy-iso-test-windows-disk [release/omarchy.iso]`. It creates a
+synthetic disk in `/tmp` with an existing ESP and data partition plus ample
+unallocated space, then offers to start an interactive installation on it. The
+fixture exercises Windows partition preservation but does not contain Windows.
+
+## Acceptance testing the ISO
+
+Run `./bin/omarchy-iso-test [release/omarchy.iso]` to install the ISO into a headless VM by driving the real interactive install flow — the harness reads each screen via QMP screendumps + OCR and answers with virtual keystrokes, so the configurator wizard, install dashboard, reboot prompt, and SDDM login are all exercised exactly as a user would. It then boots the installed system, sends real VM keyboard shortcuts for the primary shell and window-management actions, and runs the in-guest acceptance suite (`test/acceptance` in the omarchy repo). The suite checks session and service health, the complete core-package manifest, user defaults, representative applications, menus, panels, live weather, launchers, visual selectors, notifications, clipboard, and other interactive shell behavior.
+
+Visual checkpoints are saved as `success-<step>.png` or `failure-<step>.png` alongside the serial and install logs in `test-runs/<iso>/runs/<timestamp>/`. Independent test files and applications continue after a failure so one broken surface does not hide the rest of the report. The harness then stops the VM and opens the ordered screenshots in `imv` for quick visual review.
+
+The harness syncs the acceptance suite from `$OMARCHY_PATH` when it is available. The install phase produces a reusable base image, so iterating against another checkout is fast:
+
+```bash
+./bin/omarchy-iso-test release/omarchy.iso --install-only        # once per ISO
+./bin/omarchy-iso-test release/omarchy.iso --reuse-base \
+  --sync-omarchy ../omarchy                                      # fast loop against local tests
+```
+
+Pass `--encrypt` to drive the encrypted install flow (including typing the LUKS passphrase at boot) instead of the unencrypted one. Pass `--no-preview` to collect the same visual artifacts without opening them in `imv` when the run finishes.
+
+## Integration testing the ISO
+
+Scenarios under `test/integration.d/` boot a real ISO install in QEMU and assert on what the running system actually does. The runner installs the ISO once — unattended, from a generated cidata drive — and saves the result as a reusable base image; every scenario then boots a throwaway overlay of that base with its own copy of the firmware vars, so neither disk nor NVRAM state leaks between runs. Shared machinery (VM lifecycle, QMP screendump + OCR console driving, virtual keystrokes, guest SSH, the cidata build) lives in `test/integration.d/base-test.sh`, so a new scenario is one file.
+
+```bash
+./test/integration release/omarchy.iso                   # install once, run all scenarios
+./test/integration release/omarchy.iso --reuse-base      # fast loop against the saved base
+./test/integration release/omarchy.iso factory-reset     # a single named scenario
+```
+
+The first scenario is `factory-reset`: it proves `omarchy-system-factory-reset` hands a machine on without destroying a shared ESP. The installed ESP gets a Windows entry with payload plus a second Linux cloned under a foreign machine-id with its own boot directory and UKIs; a real factory reset is then driven through a guest pty, and the harness asserts the foreign entries survive both the staged reset and first-boot provisioning, that the old Omarchy identity is fully retired, and that the machine reaches first-boot setup unattended.
+
+Artifacts — screenshots, the fixtured/staged/final `limine.conf`, the reset typescript, and the factory-reset log — land under `test-runs/<iso>-integration/runs/<timestamp>-<scenario>/`, and `--no-preview` skips the `imv` review just like the acceptance harness.
+
 ## Signing the ISO
 
-Run `./bin/omarchy-iso-sign [gpg-user] [release/omarchy.iso]`.
+Run `./bin/omarchy-iso-sign [release/omarchy.iso]`. The signing key is retrieved from the shared Omarchy vault with the 1Password CLI.
 
 ## Uploading the ISO
 
-Run `./bin/omarchy-iso-upload [release/omarchy.iso]`. This requires you've configured rclone (use `rclone config`).
+Run `./bin/omarchy-iso-upload [release/omarchy.iso]`. This requires rclone configuration (`rclone config`). The `.sig` and `.sha256` sidecars go up with the ISO when they exist beside it.
 
 ## Full release of the ISO
 
-Run `./bin/omarchy-iso-release` to create, test, sign, and upload the ISO in one flow.
+Run `./bin/omarchy-iso-release VERSION` to create, test, sign, and upload the ISO in one flow. Add `--rc` to release an RC build instead.

bin/omarchy-iso-boot

@@ -2,36 +2,168 @@
 
 set -e
 
-if [ $# -eq 0 ]; then
-  echo "Usage: omarchy-iso-boot [release/omarchy.iso] [reuse]"
-  echo "  SSH available at: ssh -p 2222 root@localhost (after installing openssh)"
+ISO=""
+REUSE=""
+SSH_HOST="${OMARCHY_VM_SSH_HOST:-127.0.0.1}"
+SSH_PORT="${OMARCHY_VM_SSH_PORT:-2222}"
+NETWORK="${OMARCHY_VM_NETWORK:-1}"
+DISK="${OMARCHY_VM_DISK:-/tmp/omarchy-iso-boot.qcow2}"
+OVMF_VARS="${OMARCHY_VM_OVMF_VARS:-/tmp/OVMF_VARS.4m.fd}"
+EXTRA_QEMU_ARGS=()
+
+usage() {
+  cat <<USAGE
+Usage: omarchy-iso-boot [options] [release/omarchy.iso] [reuse]
+
+Options:
+  --reuse              Reuse the existing VM disk
+  --ssh-port PORT      Forward host PORT to guest port 22 (default: $SSH_PORT)
+  --ssh-host HOST      Host address for SSH forwarding (default: $SSH_HOST)
+  --no-network         Boot without a virtual NIC
+  --disk PATH          VM disk path (default: $DISK)
+  --ovmf-vars PATH     OVMF vars path (default: $OVMF_VARS)
+  -h, --help           Show this help
+  --                   Pass the remaining arguments directly to QEMU
+
+SSH access after starting sshd in the guest:
+  ssh -p $SSH_PORT root@localhost
+  scp -P $SSH_PORT /path/to/system-manifest root@localhost:/tmp/
+USAGE
+}
+
+while (( $# > 0 )); do
+  case "$1" in
+    --reuse|reuse)
+      REUSE="reuse"
+      shift
+      ;;
+    --ssh-port)
+      SSH_PORT="${2:-}"
+      shift 2
+      ;;
+    --ssh-port=*)
+      SSH_PORT="${1#*=}"
+      shift
+      ;;
+    --ssh-host)
+      SSH_HOST="${2:-}"
+      shift 2
+      ;;
+    --ssh-host=*)
+      SSH_HOST="${1#*=}"
+      shift
+      ;;
+    --no-network|--no-net)
+      NETWORK=0
+      shift
+      ;;
+    --disk)
+      DISK="${2:-}"
+      shift 2
+      ;;
+    --disk=*)
+      DISK="${1#*=}"
+      shift
+      ;;
+    --ovmf-vars)
+      OVMF_VARS="${2:-}"
+      shift 2
+      ;;
+    --ovmf-vars=*)
+      OVMF_VARS="${1#*=}"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --)
+      shift
+      EXTRA_QEMU_ARGS+=("$@")
+      break
+      ;;
+    *)
+      if [[ -z $ISO ]]; then
+        ISO="$1"
+      else
+        echo "Unexpected argument: $1" >&2
+        usage >&2
+        exit 1
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [[ -z $ISO && -t 0 ]]; then
+  ISO=$(ls -t release/*.iso 2>/dev/null | gum choose --header "Select ISO to boot")
+  if gum confirm --default=false "Reuse existing disk?"; then
+    REUSE="reuse"
+  fi
+fi
+
+if [[ -z $ISO ]]; then
+  usage
   exit 1
 fi
 
-if ! pacman -Q qemu-full >/dev/null || ! pacman -Q edk2-ovmf >/dev/null; then
-  sudo pacman -S --noconfirm --needed --quiet qemu-full edk2-ovmf
+if [[ -z $DISK || -z $OVMF_VARS ]]; then
+  echo "Disk and OVMF vars paths must not be empty" >&2
+  exit 1
 fi
 
-DISK="/tmp/omarchy-iso-boot.qcow2"
-if [[ ! -f $DISK || $2 != "reuse" ]]; then
-  qemu-img create -f qcow2 "$DISK" 20G
-  cp /usr/share/edk2/x64/OVMF_VARS.4m.fd /tmp/OVMF_VARS.4m.fd
+omarchy-pkg-add qemu-full edk2-ovmf
+
+if [[ -z ${WAYLAND_DISPLAY:-} && -z ${DISPLAY:-} ]]; then
+  while IFS='=' read -r name value; do
+    case "$name" in
+      WAYLAND_DISPLAY|DISPLAY|XAUTHORITY|XDG_SESSION_TYPE)
+        export "$name=$value"
+        ;;
+    esac
+  done < <(systemctl --user show-environment 2>/dev/null || true)
+fi
+
+if [[ -z ${WAYLAND_DISPLAY:-} && -z ${DISPLAY:-} ]]; then
+  echo "Unable to find a graphical session for QEMU." >&2
+  echo "Run omarchy-iso-boot from the Omarchy desktop session." >&2
+  exit 1
+fi
+
+if [[ ! -f $DISK || $REUSE != "reuse" ]]; then
+  qemu-img create -f qcow2 "$DISK" 40G
+  cp /usr/share/edk2/x64/OVMF_VARS.4m.fd "$OVMF_VARS"
+fi
+
+NET_ARGS=()
+if [[ $NETWORK != "0" && $NETWORK != "false" && $NETWORK != "no" ]]; then
+  if [[ -n $SSH_PORT && $SSH_PORT != "0" ]]; then
+    NET_ARGS=(-netdev "user,id=net0,hostfwd=tcp:${SSH_HOST}:${SSH_PORT}-:22" -device virtio-net-pci,netdev=net0)
+    echo "SSH forwarding enabled: ssh -p $SSH_PORT root@localhost"
+    echo "SCP example: scp -P $SSH_PORT /path/to/system-manifest root@localhost:/tmp/"
+  else
+    NET_ARGS=(-netdev user,id=net0 -device virtio-net-pci,netdev=net0)
+    echo "Networking enabled without SSH port forwarding."
+  fi
+else
+  echo "Networking disabled."
 fi
 
 # Boot from ISO before we've installed, then boot from drive after
 qemu-system-x86_64 \
   -cpu host -enable-kvm -machine q35,accel=kvm \
-  -smp "$(nproc)" \
+  -smp "$(($(nproc) < 8 ? $(nproc) : 8))" \
   -m 8192 \
   -drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2/x64/OVMF_CODE.4m.fd \
-  -drive if=pflash,format=raw,file=/tmp/OVMF_VARS.4m.fd \
+  -drive if=pflash,format=raw,file="$OVMF_VARS" \
   -drive file="$DISK",format=qcow2,if=none,id=drive0 \
   -device virtio-blk-pci,drive=drive0,bootindex=1 \
-  -drive file="$1",media=cdrom,if=none,format=raw,id=cdrom0 \
+  -drive file="$ISO",media=cdrom,if=none,format=raw,id=cdrom0 \
   -device ide-cd,drive=cdrom0,bootindex=2 \
   -device virtio-vga-gl \
-  -display gtk,gl=on \
+  -display sdl,gl=on \
   -usb -device usb-tablet \
-  -netdev user,id=net0,hostfwd=tcp::2222-:22 \
-  -device virtio-net-pci,netdev=net0 \
-  -boot menu=on
+  -serial none \
+  "${NET_ARGS[@]}" \
+  -boot menu=on \
+  "${EXTRA_QEMU_ARGS[@]}"

bin/omarchy-iso-configurator

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+if [[ -z "${OMARCHY_PATH:-}" ]]; then
+  for candidate in "$repo_root/../omarchy-installer" "$repo_root/../omarchy" /usr/share/omarchy; do
+    if [[ -f "$candidate/logo.txt" ]]; then
+      export OMARCHY_PATH="$candidate"
+      break
+    fi
+  done
+fi
+
+# Do a dry-run of the configurator to show the flow without having to do a real installation
+exec bash "$repo_root/configs/airootfs/root/configurator" dry "$@"

bin/omarchy-iso-installer

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# Preview the shipped Omarchy installer dashboard without building an ISO.
+set -euo pipefail
+
+# The dashboard drives the package phase from the target's pacman database, so
+# fake one here; without it the preview falls back to its time curve and the bar
+# barely moves, which reads as a bug.
+PREVIEW_PACKAGES="${PREVIEW_PACKAGES:-925}"
+
+write_simulation_state() {
+  local state_file="$1" started_at="$2" phase_started_at="$3" current_phase="$4"
+  local target="$5" index="$6" total="$7"
+  local finished_at="${8:-null}" temporary="${state_file}.tmp"
+
+  jq -n \
+    --argjson started_at "$started_at" \
+    --argjson phase_started_at "$phase_started_at" \
+    --arg current_phase "$current_phase" \
+    --arg target "$target" \
+    --argjson current_index "$index" \
+    --argjson total_phases "$total" \
+    --argjson finished_at "$finished_at" \
+    '{
+      started_at: $started_at,
+      phase_started_at: $phase_started_at,
+      current_phase: $current_phase,
+      target: $target,
+      current_index: $current_index,
+      total_phases: $total_phases
+    } + if $finished_at == null then {} else {finished_at: $finished_at} end' \
+    >"$temporary"
+  mv -f -- "$temporary" "$state_file"
+}
+
+# Fill the fake database over the phase's duration, so the bar is driven by the
+# same count it uses on a real install.
+simulate_packages() {
+  local db="$1" duration="$2" total="$3" steps=25 i n
+  for ((i = 1; i <= steps; i++)); do
+    n=$(( total * i / steps ))
+    while (( $(ls -1 "$db" 2>/dev/null | wc -l) < n )); do
+      mkdir -p "$db/preview-$(( $(ls -1 "$db" 2>/dev/null | wc -l) ))-1.0-1"
+    done
+    sleep "$(awk -v d="$duration" -v s="$steps" 'BEGIN { printf "%.3f", d / s }')"
+  done
+}
+
+simulate_install() {
+  local state_file="$1"
+  local started_at="$EPOCHREALTIME"
+  local phase phase_started_at finished_at duration i index total
+  local target db
+  target="$(dirname -- "$state_file")/target"
+  db="$target/var/lib/pacman/local"
+  mkdir -p "$db"
+  local -a phases=(
+    "Starting installation" 0.5
+    "Preparing live environment" 0.8
+    "Preparing install target" 0.3
+    "Installing Arch + Omarchy" 5.0
+    "Configuring hibernation" 0.4
+    "Configuring system" 1.2
+    "Finalizing Limine boot" 1.0
+    "Finalizing user" 1.0
+    "Configuring login" 0.6
+    "Configuring DNS resolver" 0.3
+    "Validating boot setup" 0.8
+  )
+  total=$(( ${#phases[@]} / 2 ))
+
+  for ((i = 0; i < ${#phases[@]}; i += 2)); do
+    phase="${phases[i]}"
+    duration="${phases[i + 1]}"
+    index=$(( i / 2 ))
+    phase_started_at="$EPOCHREALTIME"
+    write_simulation_state "$state_file" "$started_at" "$phase_started_at" \
+      "$phase" "$target" "$index" "$total"
+    if [[ $phase == "Installing Arch + Omarchy" ]]; then
+      simulate_packages "$db" "$duration" "$PREVIEW_PACKAGES"
+    else
+      sleep "$duration"
+    fi
+  done
+
+  finished_at="$EPOCHREALTIME"
+  write_simulation_state "$state_file" "$started_at" "$finished_at" \
+    "Installation complete" "$target" "$(( total - 1 ))" "$total" "$finished_at"
+  sleep 0.3
+}
+
+if [[ ${1:-} == "--simulate-install" ]]; then
+  (( $# == 2 )) || exit 2
+  simulate_install "$2"
+  exit 0
+fi
+
+if (( $# > 0 )); then
+  echo "Usage: $0" >&2
+  exit 2
+fi
+
+repo_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+dashboard="$repo_root/configs/airootfs/usr/local/bin/omarchy-install-dashboard"
+
+if [[ ! -x $dashboard ]]; then
+  echo "Installer dashboard is not executable: $dashboard" >&2
+  exit 1
+fi
+
+if [[ -z ${OMARCHY_PATH:-} ]]; then
+  for candidate in "$repo_root/../omarchy" /usr/share/omarchy; do
+    if [[ -f $candidate/logo.txt ]]; then
+      export OMARCHY_PATH="$candidate"
+      break
+    fi
+  done
+fi
+
+if [[ -z ${OMARCHY_PATH:-} || ! -f $OMARCHY_PATH/logo.txt ]]; then
+  echo "Unable to find Omarchy logo.txt; set OMARCHY_PATH to an Omarchy checkout." >&2
+  exit 1
+fi
+
+preview_dir="$(mktemp -d)"
+cleanup() {
+  rm -rf "$preview_dir"
+}
+trap cleanup EXIT
+
+log_file="$preview_dir/install.log"
+state_file="$preview_dir/state.json"
+touch "$log_file"
+
+# Match what the simulated database will reach, so the preview shows the
+# package-driven bar rather than the missing-signal fallback.
+printf '%s\n' "$PREVIEW_PACKAGES" >"$preview_dir/expected-packages"
+
+OMARCHY_UI_AUTO_REBOOT=no \
+  OMARCHY_EXPECTED_PACKAGES_FILE="$preview_dir/expected-packages" \
+  PREVIEW_PACKAGES="$PREVIEW_PACKAGES" \
+  "$dashboard" "$log_file" "$state_file" -- \
+  "$0" --simulate-install "$state_file"

bin/omarchy-iso-make

@@ -1,45 +1,131 @@
 #!/bin/bash
 
-# Abort if anything fails
 set -e
 
-# Parse command line arguments
 NO_CACHE=""
+KEEP_PKG_CACHE=""
+LOCAL_OMARCHY_PATH=""
+LOCAL_PKGS_PATH=""
 while [[ $# -gt 0 ]]; do
   case $1 in
   --no-cache)
     NO_CACHE=1
     shift
     ;;
+  --keep-pkg-cache)
+    KEEP_PKG_CACHE=1
+    shift
+    ;;
   --no-boot-offer)
     NO_BOOT_OFFER=1
     shift
     ;;
+  --debug)
+    OMARCHY_INSTALL_DEBUG=1
+    shift
+    ;;
+  --edge)
+    OMARCHY_ISO_REF=edge
+    OMARCHY_MIRROR=edge
+    shift
+    ;;
+  --local-source)
+    LOCAL_OMARCHY_PATH="${2:-}"
+    LOCAL_PKGS_PATH="${3:-}"
+    if [[ -z $LOCAL_OMARCHY_PATH || -z $LOCAL_PKGS_PATH ]]; then
+      echo "Error: --local-source requires two args: <omarchy-checkout> <pkgs-checkout>" >&2
+      exit 1
+    fi
+    OMARCHY_MIRROR=edge
+    OMARCHY_ISO_REF=local
+    shift 3
+    ;;
+  --dev)
+    OMARCHY_ISO_REF=dev
+    OMARCHY_MIRROR=edge
+    shift
+    ;;
+  --quattro)
+    OMARCHY_INSTALLER_REF=quattro
+    OMARCHY_MIRROR=edge
+    shift
+    ;;
+  --rc)
+    OMARCHY_ISO_REF=rc
+    OMARCHY_MIRROR=rc
+    shift
+    ;;
   *)
     echo "Unknown option: $1"
-    echo "Usage: $0 [--no-cache] [--no-boot-offer]"
+    echo "Usage: $0 [--no-cache] [--keep-pkg-cache] [--no-boot-offer] [--debug] [--edge] [--dev|--rc] [--local-source <omarchy-checkout> <pkgs-checkout>]"
     exit 1
     ;;
   esac
 done
 
-# Ensure we have the submodule checked out
+if [[ -n $LOCAL_OMARCHY_PATH ]]; then
+  [[ -d $LOCAL_OMARCHY_PATH ]] || { echo "Error: Omarchy checkout not found at $LOCAL_OMARCHY_PATH" >&2; exit 1; }
+  [[ -d $LOCAL_PKGS_PATH ]]    || { echo "Error: pkgs checkout not found at $LOCAL_PKGS_PATH" >&2; exit 1; }
+  LOCAL_OMARCHY_PATH=$(realpath "$LOCAL_OMARCHY_PATH")
+  LOCAL_PKGS_PATH=$(realpath "$LOCAL_PKGS_PATH")
+fi
+
+lint_file_permissions() {
+  local profiledef="configs/profiledef.sh"
+  local -A declared=()
+  local missing=()
+
+  while IFS= read -r path; do
+    [[ -n $path ]] && declared["$path"]=1
+  done < <(grep -oP '^\s*\["\K[^"]+(?="\])' "$profiledef" || true)
+
+  while IFS= read -r f; do
+    [[ -f $f ]] || continue
+
+    local rel="${f#configs/airootfs}"
+    local mode
+    mode=$(git ls-files --stage -- "$f" | awk '{print $1}')
+
+    if [[ $mode != 100755 && $(head -c 2 "$f") != "#!" ]]; then
+      continue
+    fi
+
+    if [[ -z ${declared[$rel]+x} ]]; then
+      missing+=("$rel")
+    fi
+  done < <(find configs/airootfs/usr/local/bin configs/airootfs/root -type f 2>/dev/null)
+
+  if (( ${#missing[@]} > 0 )); then
+    echo "ERROR: the following executable files are missing from $profiledef file_permissions:" >&2
+    printf '  %s\n' "${missing[@]}" >&2
+    echo "Add entries like [\"<path>\"]=\"0:0:755\" to profiledef.sh and retry." >&2
+    exit 1
+  fi
+}
+
+lint_file_permissions
+
+# Purging the host package cache needs interactive sudo; --keep-pkg-cache
+# skips it so unattended builds (test rigs, agents) can run without a prompt.
+if [[ -z $KEEP_PKG_CACHE ]]; then
+  sudo rm -rf /var/cache/pacman/pkg/*
+fi
 git submodule update --init --recursive --jobs=8
 
-# Prepare build repo
 BUILD_SCRIPT="builder/build-iso.sh"
 BUILD_ROOT=$(realpath "${BASH_SOURCE[0]%/*}/..")
 BUILD_RELEASE_PATH="$BUILD_ROOT/release"
 mkdir -p "$BUILD_RELEASE_PATH"
 
-OMARCHY_INSTALLER_REPO="${OMARCHY_INSTALLER_REPO:-basecamp/omarchy}"
-OMARCHY_INSTALLER_REF="${OMARCHY_INSTALLER_REF:-master}"
+OMARCHY_ISO_REF="${OMARCHY_ISO_REF:-quattro}"
+OMARCHY_MIRROR="${OMARCHY_MIRROR:-stable}"
 
 DOCKER_ARGS=(
   --rm
   --privileged
-  -e "OMARCHY_INSTALLER_REPO=$OMARCHY_INSTALLER_REPO"
-  -e "OMARCHY_INSTALLER_REF=$OMARCHY_INSTALLER_REF"
+  -e "OMARCHY_ISO_REF=$OMARCHY_ISO_REF"
+  -e "OMARCHY_MIRROR=$OMARCHY_MIRROR"
+  -e "OMARCHY_INSTALL_DEBUG=${OMARCHY_INSTALL_DEBUG:-}"
   -e "HOST_UID=$(id -u)"
   -e "HOST_GID=$(id -g)"
   -v "$BUILD_RELEASE_PATH/:/out/"
@@ -49,31 +135,36 @@ DOCKER_ARGS=(
   -v "$BUILD_ROOT/configs:/configs:ro"
 )
 
-# Use local pacman cache if you already have one on host to speed up repeat runs
-if [ -d "/var/cache/pacman/pkg" ]; then
+if [[ -n $LOCAL_OMARCHY_PATH ]]; then
+  DOCKER_ARGS+=(
+    -v "$LOCAL_OMARCHY_PATH:/omarchy-source:ro"
+    -v "$LOCAL_PKGS_PATH:/omarchy-pkgs:ro"
+  )
+fi
+
+if [[ -d /var/cache/pacman/pkg ]]; then
   DOCKER_ARGS+=(-v "/var/cache/pacman/pkg:/var/cache/pacman/pkg")
 fi
 
-# Mount the build cache directory where packages are downloaded
+# Mount the build cache directory where packages are downloaded. Channels use
+# different package snapshots and must never share an offline mirror cache.
 if [[ -z "$NO_CACHE" ]]; then
-  # using a dated dir on the host to refresh daily if building multiple times
-  BUILD_DATE=$(date +%Y-%m-%d)
-  OFFLINE_REPO_BUILD_CACHE_DIR="$HOME/.cache/omarchy/iso_${BUILD_DATE}/airootfs/var/cache/omarchy"
+  OFFLINE_REPO_BUILD_CACHE_DIR="$HOME/.cache/omarchy/iso_${OMARCHY_MIRROR}/airootfs/var/cache/omarchy"
   mkdir -p "$OFFLINE_REPO_BUILD_CACHE_DIR"
-  # Mount to /var/cache/airootfs/var/cache/omarchy since that's where repo packages go in the ISO
   DOCKER_ARGS+=(-v "$OFFLINE_REPO_BUILD_CACHE_DIR:/var/cache/airootfs/var/cache/omarchy")
+else
+  # The locally cached :latest image is a cache too — docker run never
+  # re-checks the registry for it, so refresh it when building cold.
+  DOCKER_ARGS+=(--pull=always)
 fi
 
-# Run the builder with assembled args
 docker run "${DOCKER_ARGS[@]}" archlinux/archlinux:latest /$BUILD_SCRIPT
 
-# Move as install ref
 latest_iso=$(\ls -t "$BUILD_RELEASE_PATH"/*.iso | head -n1)
-iso_ref="${latest_iso%.*}-$OMARCHY_INSTALLER_REF.iso"
+iso_ref="${latest_iso%.*}-$OMARCHY_ISO_REF.iso"
 mv -f "$latest_iso" "$iso_ref"
 
-# Offer to boot the new build
-if [[ -z "$NO_BOOT_OFFER" ]]; then
+if [[ -z "${NO_BOOT_OFFER:-}" ]]; then
   echo
-  gum confirm "Boot $iso_ref?" && omarchy-iso-boot "$iso_ref"
+  gum confirm "Boot $iso_ref?" && "$BUILD_ROOT/bin/omarchy-iso-boot" "$iso_ref"
 fi

bin/omarchy-iso-make-dev

@@ -1,3 +0,0 @@
-#!/bin/bash
-
-OMARCHY_INSTALLER_REF=dev omarchy-iso-make

bin/omarchy-iso-rclone-config

@@ -0,0 +1,16 @@
+#!/bin/bash
+omarchy-pkg-add rclone
+mkdir -p ~/.config/rclone
+
+access_key=$(op read "op://Shared/Cloudflare Buckets/iso.omarchy.org/access_key_id" --account Omarchy)
+secret_access_key=$(op read "op://Shared/Cloudflare Buckets/iso.omarchy.org/secret_access_key" --account Omarchy)
+endpoint=$(op read "op://Shared/Cloudflare Buckets/iso.omarchy.org/endpoint" --account Omarchy)
+
+cat > ~/.config/rclone/rclone.conf << EOF
+[Omarchy]
+type = s3
+provider = Cloudflare
+access_key_id = $access_key
+secret_access_key = $secret_access_key
+endpoint = $endpoint
+EOF

bin/omarchy-iso-release

@@ -1,38 +1,72 @@
 #!/bin/bash
 
-if [ $# -eq 0 ]; then
-  echo "Usage: omarchy-iso-release [version]"
+MAKE_ARGS=()
+ISO_REF=quattro
+RELEASE_SUFFIX=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+  --no-make)
+    MAKE_ARGS+=("$1")
+    shift
+    ;;
+  --rc)
+    MAKE_ARGS+=("$1")
+    ISO_REF=rc
+    RELEASE_SUFFIX="-rc"
+    shift
+    ;;
+  -*)
+    echo "Unknown option: $1"
+    echo "Usage: omarchy-iso-release [--no-make] [--rc] [version]"
+    exit 1
+    ;;
+  *)
+    if [[ -n "${BUILD_VERSION-}" ]]; then
+      echo "Usage: omarchy-iso-release [--no-make] [--rc] [version]"
+      exit 1
+    fi
+    BUILD_VERSION="$1"
+    shift
+    ;;
+  esac
+done
+
+if [[ -z "${BUILD_VERSION-}" ]]; then
+  echo "Usage: omarchy-iso-release [--no-make] [--rc] [version]"
   exit 1
 fi
 
 BUILD_ROOT=$(realpath "${BASH_SOURCE[0]%/*}/..")
 BUILD_RELEASE_PATH="$BUILD_ROOT/release"
-BULD_VERSION="$1"
 
 # Make ISOs
-if [[ $1 != "--no-make" ]]; then
-  echo -e "\e[32mMaking master ISO\e[0m"
-  OMARCHY_INSTALLER_REF=master omarchy-iso-make --no-cache --no-boot-offer
-
-  echo -e "\e[32m\nMaking dev ISO\e[0m"
-
-  OMARCHY_INSTALLER_REF=dev omarchy-iso-make --no-cache --no-boot-offer
+if [[ ! " ${MAKE_ARGS[*]} " =~ " --no-make " ]]; then
+  echo -e "\e[32mMaking $ISO_REF ISO\e[0m"
+  omarchy-iso-make --no-cache --no-boot-offer "${MAKE_ARGS[@]}"
 else
   echo -e "\e[31mSkipping remaking ISOs\e[0m"
 fi
 
-# Sign and upload master ISO
-latest_master_iso=$(\ls -t "$BUILD_RELEASE_PATH"/*x86_64-master.iso | head -n1)
-release_master_iso="$BUILD_RELEASE_PATH/omarchy-$BULD_VERSION.iso"
-cp "$latest_master_iso" "$release_master_iso"
-echo -e "\e[32mSigning master ISO\e[0m"
-omarchy-iso-sign "$release_master_iso"
-omarchy-iso-upload "$release_master_iso"
+# Sign and upload ISO
+latest_iso=$(\ls -t "$BUILD_RELEASE_PATH"/*x86_64-"$ISO_REF".iso | head -n1)
+release_iso="$BUILD_RELEASE_PATH/omarchy-$BUILD_VERSION$RELEASE_SUFFIX.iso"
+cp "$latest_iso" "$release_iso"
 
-# Sign and upload dev ISO
-latest_dev_iso=$(\ls -t "$BUILD_RELEASE_PATH"/*x86_64-dev.iso | head -n1)
-release_dev_iso="$BUILD_RELEASE_PATH/omarchy-$BULD_VERSION-dev.iso"
-cp "$latest_dev_iso" "$release_dev_iso"
-echo -e "\e[32mSigning dev ISO\e[0m"
-omarchy-iso-sign "$release_dev_iso"
-omarchy-iso-upload "$release_dev_iso"
+echo -e "\e[32mSigning $ISO_REF ISO\e[0m"
+omarchy-iso-sign "$release_iso"
+
+# The checksum sidecar names the ISO alone, never the build path: it is
+# downloaded next to the ISO and has to verify with `sha256sum -c` from
+# whatever directory the person who downloaded it happens to be in. A release
+# that cannot write it stops here, because the sidecar left over from the last
+# release reads as a checksum for this one.
+iso_sha=$(sha256sum "$release_iso")
+iso_sha=${iso_sha%% *}
+if [[ -z $iso_sha ]] || ! printf '%s  %s\n' "$iso_sha" "${release_iso##*/}" >"$release_iso.sha256"; then
+  echo -e "\e[31mCould not write the checksum for $release_iso\e[0m" >&2
+  exit 1
+fi
+echo -e "\e[32mSHA256 for $ISO_REF ISO: $iso_sha\e[0m"
+
+omarchy-iso-upload "$release_iso"

bin/omarchy-iso-sign

@@ -1,14 +1,48 @@
 #!/bin/bash
 
-if [ $# -eq 0 ]; then
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
   echo "usage: omarchy-iso-sign [release/omarchy.iso]"
   exit 1
 fi
 
-if ! pacman -Q gnupg >/dev/null; then
-  sudo pacman -S --noconfirm --needed --quiet gnupg
-  echo "you'll need to generate a new key with: gpg --full-generate-key"
+iso="$1"
+key_ref="op://Shared/Omarchy GPG Private Key/omarchy-private.asc"
+
+if [[ ! -f $iso ]]; then
+  echo "ISO not found: $iso" >&2
+  exit 1
 fi
 
-gnupg_user_key=$(gpg --list-secret-keys --keyid-format=long | awk '/^[[:space:]]/{print $1; exit}')
-gpg --local-user "$gnupg_user_key" --output $1.sig --detach-sig $1
+if ! command -v op >/dev/null; then
+  echo "1Password CLI is required to retrieve the signing key." >&2
+  exit 1
+fi
+
+if ! pacman -Q gnupg >/dev/null 2>&1; then
+  sudo pacman -S --noconfirm --needed --quiet gnupg
+fi
+
+gnupg_home="$(mktemp -d)"
+chmod 700 "$gnupg_home"
+trap 'rm -rf "$gnupg_home"' EXIT
+
+op read "$key_ref" --account Omarchy |
+  gpg --batch --homedir "$gnupg_home" --import >/dev/null
+
+signing_key="$(
+  gpg --batch --homedir "$gnupg_home" --with-colons --list-secret-keys |
+    awk -F: '$1 == "fpr" { print $10; exit }'
+)"
+
+if [[ -z $signing_key ]]; then
+  echo "No private signing key found in $key_ref" >&2
+  exit 1
+fi
+
+gpg --batch --yes \
+  --homedir "$gnupg_home" \
+  --local-user "$signing_key" \
+  --output "$iso.sig" \
+  --detach-sig "$iso"

bin/omarchy-iso-test-windows-disk

@@ -0,0 +1,338 @@
+#!/bin/bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+
+DISK_SIZE_GIB=96
+MIN_FREE_GIB=64
+RECREATE=0
+GAP=0
+ISO=""
+
+ACTIVE_NBD=""
+MOUNT_DIR=""
+MOUNTED=0
+TEMPORARY_DISK=""
+
+usage() {
+  cat <<USAGE
+Usage: omarchy-iso-test-windows-disk [--recreate] [--gap] [release/omarchy.iso]
+
+Creates or validates a synthetic Windows-style test disk with:
+  - a 512MiB EFI partition containing EFI/Microsoft
+  - an existing ext4 data partition with a preservation marker
+  - more than 64GiB of contiguous unallocated space for Omarchy
+
+This exercises Windows partition detection and preservation; it is not a
+bootable Windows installation.
+
+--gap builds the same fixture with a hole in the partition numbering: a third
+partition is created and then deleted, leaving slot 3 free while slot 4 stays
+in use. parted fills the lowest free slot, so the installer must create its
+partitions as 3 and 5 and read those numbers back. The contiguous fixture
+cannot catch that class of bug, because there "lowest free" and "highest + 1"
+are the same number.
+
+Options:
+  --recreate  Replace the existing test fixture
+  --gap       Build the numbering-hole variant (separate disk image)
+  -h, --help  Show this help
+
+Paths can be overridden with:
+  OMARCHY_ISO_TEST_WINDOWS_DISK
+  OMARCHY_ISO_TEST_WINDOWS_OVMF_VARS
+USAGE
+}
+
+while (( $# > 0 )); do
+  case "$1" in
+    --recreate)
+      RECREATE=1
+      shift
+      ;;
+    --gap)
+      GAP=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    -*)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+    *)
+      if [[ -n $ISO ]]; then
+        echo "Only one ISO may be specified." >&2
+        usage >&2
+        exit 2
+      fi
+      ISO="$1"
+      shift
+      ;;
+  esac
+done
+
+# Separate images per layout so the two fixtures can coexist and neither has
+# to be rebuilt to run the other.
+if (( GAP )); then
+  TEST_DISK="${OMARCHY_ISO_TEST_WINDOWS_DISK:-/tmp/omarchy-iso-test-windows-gap.qcow2}"
+  TEST_OVMF_VARS="${OMARCHY_ISO_TEST_WINDOWS_OVMF_VARS:-/tmp/OVMF_VARS.omarchy-iso-test-windows-gap.fd}"
+  LAYOUT_LABEL="512MiB Windows ESP + data + deleted slot 3 + data + 64GiB+ free"
+else
+  TEST_DISK="${OMARCHY_ISO_TEST_WINDOWS_DISK:-/tmp/omarchy-iso-test-windows.qcow2}"
+  TEST_OVMF_VARS="${OMARCHY_ISO_TEST_WINDOWS_OVMF_VARS:-/tmp/OVMF_VARS.omarchy-iso-test-windows.fd}"
+  LAYOUT_LABEL="512MiB Windows ESP + existing data + 64GiB+ free"
+fi
+
+cleanup_mount() {
+  if (( MOUNTED )); then
+    sudo umount "$MOUNT_DIR" >/dev/null 2>&1 || true
+    MOUNTED=0
+  fi
+  if [[ -n $MOUNT_DIR ]]; then
+    rmdir "$MOUNT_DIR" >/dev/null 2>&1 || true
+    MOUNT_DIR=""
+  fi
+}
+
+disconnect_disk() {
+  cleanup_mount
+  if [[ -n $ACTIVE_NBD ]]; then
+    sudo qemu-nbd --disconnect "$ACTIVE_NBD" >/dev/null 2>&1 || true
+    ACTIVE_NBD=""
+  fi
+}
+
+cleanup() {
+  disconnect_disk
+  [[ -z $TEMPORARY_DISK ]] || rm -f "$TEMPORARY_DISK"
+}
+
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+find_free_nbd() {
+  local device
+  for device in /sys/class/block/nbd*; do
+    [[ -e $device ]] || continue
+    [[ ! -e $device/pid ]] || continue
+    printf '/dev/%s\n' "${device##*/}"
+    return 0
+  done
+  return 1
+}
+
+connect_disk() {
+  local disk="$1" mode="${2:-read-write}"
+  local -a options=(--format=qcow2)
+
+  ACTIVE_NBD="$(find_free_nbd)" || {
+    echo "No unused NBD device is available." >&2
+    return 1
+  }
+  [[ $mode == read-only ]] && options+=(--read-only)
+
+  if ! sudo qemu-nbd "${options[@]}" --connect="$ACTIVE_NBD" "$disk"; then
+    ACTIVE_NBD=""
+    return 1
+  fi
+  if ! sudo udevadm settle; then
+    disconnect_disk
+    return 1
+  fi
+}
+
+mount_partition() {
+  local partition="$1"
+  MOUNT_DIR="$(mktemp -d)" || return 1
+  if ! sudo mount -o "${2:-defaults}" "$partition" "$MOUNT_DIR"; then
+    rmdir "$MOUNT_DIR" >/dev/null 2>&1 || true
+    MOUNT_DIR=""
+    return 1
+  fi
+  MOUNTED=1
+}
+
+largest_free_region() {
+  sudo parted -ms "$1" unit B print free </dev/null 2>/dev/null |
+    awk -F: '
+      $NF ~ /free/ {
+        size=$4
+        gsub(/B/, "", size)
+        if (size+0 > max+0) max=size
+      }
+      END { print max+0 }
+    '
+}
+
+validate_test_disk() {
+  local part_count pttype free_space_b min_free_b want_parts numbers
+  local esp data valid=1
+
+  [[ -f $TEST_DISK ]] || return 1
+  qemu-img check -q "$TEST_DISK" >/dev/null 2>&1 || return 1
+  connect_disk "$TEST_DISK" read-only || return 1
+
+  esp="${ACTIVE_NBD}p1"
+  data="${ACTIVE_NBD}p2"
+  part_count=$(lsblk -nro TYPE "$ACTIVE_NBD" | awk '$1 == "part" { count++ } END { print count+0 }')
+  pttype=$(lsblk -dnro PTTYPE "$ACTIVE_NBD" 2>/dev/null || true)
+  free_space_b=$(largest_free_region "$ACTIVE_NBD")
+  min_free_b=$((MIN_FREE_GIB * 1024 * 1024 * 1024))
+  want_parts=2
+  (( GAP )) && want_parts=3
+
+  [[ $pttype == gpt ]] || valid=0
+  (( part_count == want_parts )) || valid=0
+
+  # The whole point of the gap fixture: slot 3 free, slot 4 in use.
+  if (( GAP )); then
+    numbers=$(sudo parted -ms "$ACTIVE_NBD" unit B print 2>/dev/null | tail -n +3 | cut -d: -f1 | sort | tr '\n' ' ')
+    [[ $numbers == "1 2 4 " ]] || valid=0
+  fi
+  (( free_space_b >= min_free_b )) || valid=0
+  [[ $(sudo blkid -s TYPE -o value "$esp" 2>/dev/null || true) == vfat ]] || valid=0
+  [[ $(sudo blkid -s LABEL -o value "$esp" 2>/dev/null || true) == WINDOWS_ESP ]] || valid=0
+  [[ $(sudo blkid -s TYPE -o value "$data" 2>/dev/null || true) == ext4 ]] || valid=0
+  [[ $(sudo blkid -s LABEL -o value "$data" 2>/dev/null || true) == WINDOWS_DATA ]] || valid=0
+
+  if (( valid )); then
+    mount_partition "$esp" ro || valid=0
+    if (( valid )); then
+      sudo test -d "$MOUNT_DIR/EFI/Microsoft" || valid=0
+    fi
+    cleanup_mount
+  fi
+
+  if (( valid )); then
+    mount_partition "$data" ro || valid=0
+    if (( valid )); then
+      sudo test -f "$MOUNT_DIR/OMARCHY-MUST-NOT-TOUCH.txt" || valid=0
+    fi
+    cleanup_mount
+  fi
+
+  disconnect_disk
+  (( valid ))
+}
+
+create_test_disk() {
+  local esp data
+
+  mkdir -p "$(dirname "$TEST_DISK")"
+  TEMPORARY_DISK="${TEST_DISK}.creating.$$"
+  rm -f "$TEMPORARY_DISK"
+
+  gum style --foreground 6 "Creating synthetic Windows test disk at $TEST_DISK"
+  qemu-img create -f qcow2 "$TEMPORARY_DISK" "${DISK_SIZE_GIB}G"
+  connect_disk "$TEMPORARY_DISK"
+
+  sudo parted --script "$ACTIVE_NBD" mklabel gpt
+  sudo parted --script "$ACTIVE_NBD" mkpart WINDOWS_ESP fat32 1MiB 513MiB
+  sudo parted --script "$ACTIVE_NBD" set 1 esp on
+  sudo parted --script "$ACTIVE_NBD" mkpart WINDOWS_DATA ext4 513MiB 20GiB
+
+  if (( GAP )); then
+    # Slot 3 is created and deleted, slot 4 stays. parted then fills 3 before
+    # 5, so an installer that assumes "highest + 1" (which would be 5 and 6)
+    # writes to device nodes that do not exist. The deleted region is
+    # deliberately smaller than the trailing free space so the installer still
+    # picks the tail as its largest free region.
+    sudo parted --script "$ACTIVE_NBD" mkpart SCRATCH ext4 20GiB 28GiB
+    sudo parted --script "$ACTIVE_NBD" mkpart WINDOWS_MORE ext4 28GiB 30GiB
+    sudo parted --script "$ACTIVE_NBD" rm 3
+  fi
+
+  sudo partprobe "$ACTIVE_NBD"
+  sudo udevadm settle
+
+  esp="${ACTIVE_NBD}p1"
+  data="${ACTIVE_NBD}p2"
+  sudo mkfs.fat -F32 -n WINDOWS_ESP "$esp" >/dev/null
+  sudo mkfs.ext4 -F -L WINDOWS_DATA "$data" >/dev/null 2>&1
+
+  mount_partition "$esp"
+  sudo mkdir -p "$MOUNT_DIR/EFI/Microsoft/Boot"
+  printf '%s\n' 'Synthetic Windows ESP for Omarchy ISO testing.' |
+    sudo tee "$MOUNT_DIR/EFI/Microsoft/README.txt" >/dev/null
+  cleanup_mount
+
+  mount_partition "$data"
+  printf '%s\n' 'This existing partition must survive the Omarchy installation.' |
+    sudo tee "$MOUNT_DIR/OMARCHY-MUST-NOT-TOUCH.txt" >/dev/null
+  cleanup_mount
+
+  sync
+  disconnect_disk
+  mv -f "$TEMPORARY_DISK" "$TEST_DISK"
+  TEMPORARY_DISK=""
+}
+
+select_iso() {
+  local -a isos=()
+
+  if [[ -n $ISO ]]; then
+    [[ -f $ISO ]] || {
+      echo "ISO not found: $ISO" >&2
+      return 1
+    }
+    realpath "$ISO"
+    return 0
+  fi
+
+  mapfile -t isos < <(
+    find "$REPO_ROOT/release" -maxdepth 1 -type f -name '*.iso' -printf '%T@ %p\n' 2>/dev/null |
+      sort -nr |
+      cut -d' ' -f2-
+  )
+  (( ${#isos[@]} > 0 )) || {
+    echo "No ISO found under $REPO_ROOT/release." >&2
+    return 1
+  }
+
+  printf '%s\n' "${isos[@]}" | gum choose --header "Select ISO to install"
+}
+
+omarchy-pkg-add qemu-full edk2-ovmf parted dosfstools e2fsprogs
+sudo modprobe nbd max_part=16
+
+if [[ -f $TEST_DISK ]] && (( ! RECREATE )); then
+  gum style --foreground 6 "Verifying existing test disk at $TEST_DISK"
+  if validate_test_disk; then
+    gum style --foreground 2 "✓ Synthetic Windows test disk is ready"
+  elif gum confirm --default=false "The existing test disk is not a pristine fixture. Recreate it?"; then
+    create_test_disk
+  else
+    gum style "Left the existing disk untouched."
+    exit 0
+  fi
+else
+  create_test_disk
+fi
+
+# The synthetic fixture has no real Windows bootloader, so reset OVMF state for
+# every run. The ISO still sees EFI/Microsoft and must leave that ESP untouched.
+mkdir -p "$(dirname "$TEST_OVMF_VARS")"
+cp /usr/share/edk2/x64/OVMF_VARS.4m.fd "$TEST_OVMF_VARS"
+
+gum style --border rounded --padding "0 1" --border-foreground 6 \
+  "Synthetic Windows disk ready" \
+  "Disk: $TEST_DISK" \
+  "Layout: $LAYOUT_LABEL"
+
+if gum confirm "Start installation on this disk?"; then
+  ISO="$(select_iso)"
+  trap - EXIT INT TERM
+  exec "$SCRIPT_DIR/omarchy-iso-boot" \
+    --reuse \
+    --disk "$TEST_DISK" \
+    --ovmf-vars "$TEST_OVMF_VARS" \
+    "$ISO" \
+    -- -boot once=d,menu=on
+fi

bin/omarchy-iso-upload

@@ -6,12 +6,28 @@ if [ $# -eq 0 ]; then
 fi
 
 if [[ ! -f ~/.config/rclone/rclone.conf ]]; then
-  echo "You must first configure rclone with the R2 credentials: rclone config"
+  echo "You must first configure rclone with the R2 credentials: omarchy-iso-rclone-config"
   exit 1
 fi
 
-rclone copy $1 Omarchy:omarchy/ -P
+# Every copy reports, and one failure fails the upload. Without the tally the
+# last copy decides the exit status, so a signature that never made it is
+# hidden by a checksum that did.
+status=0
 
-if [[ -f $1.sig ]]; then
-  rclone copy $1.sig Omarchy:omarchy/ -P
+rclone copy "$1" Omarchy:omarchy/ -P || status=1
+
+# The signature and the checksum are only worth anything to someone who can
+# reach them beside the ISO, so they go up in the same run rather than a step
+# a release can finish without.
+for sidecar in "$1.sig" "$1.sha256"; do
+  if [[ -f $sidecar ]]; then
+    rclone copy "$sidecar" Omarchy:omarchy/ -P || status=1
+  fi
+done
+
+if [[ ! -f $1.sha256 ]]; then
+  echo "Warning: no $1.sha256 to publish, so nobody can verify this download" >&2
 fi
+
+exit $status

bin/omarchy-vm

@@ -4,8 +4,8 @@ set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 VM_DIR="$(dirname "$SCRIPT_DIR")/vm-saves"
-TMP_DISK="/tmp/omarchy-iso-boot.qcow2"
-TMP_OVMF="/tmp/OVMF_VARS.4m.fd"
+TMP_DISK="${OMARCHY_VM_DISK:-/tmp/omarchy-iso-boot.qcow2}"
+TMP_OVMF="${OMARCHY_VM_OVMF_VARS:-/tmp/OVMF_VARS.4m.fd}"
 
 mkdir -p "$VM_DIR"
 
@@ -18,7 +18,7 @@ save_vm() {
   fi
 
   if [[ ! -f "$TMP_DISK" || ! -f "$TMP_OVMF" ]]; then
-    echo "Error: No active VM found in /tmp"
+    echo "Error: No active VM found at $TMP_DISK / $TMP_OVMF"
     echo "Boot a VM first with: omarchy-iso-boot [iso]"
     exit 1
   fi
@@ -53,7 +53,44 @@ list_vms() {
 }
 
 boot_vm() {
-  local name="$1"
+  local name=""
+  local boot_args=()
+  local active_disk="$TMP_DISK"
+  local active_ovmf="$TMP_OVMF"
+
+  if [[ $# -gt 0 && ${1:-} != --* ]]; then
+    name="$1"
+    shift
+  fi
+
+  while (( $# > 0 )); do
+    case "$1" in
+      --disk)
+        active_disk="${2:-}"
+        boot_args+=("$1" "${2:-}")
+        shift 2
+        ;;
+      --disk=*)
+        active_disk="${1#*=}"
+        boot_args+=("$1")
+        shift
+        ;;
+      --ovmf-vars)
+        active_ovmf="${2:-}"
+        boot_args+=("$1" "${2:-}")
+        shift 2
+        ;;
+      --ovmf-vars=*)
+        active_ovmf="${1#*=}"
+        boot_args+=("$1")
+        shift
+        ;;
+      *)
+        boot_args+=("$1")
+        shift
+        ;;
+    esac
+  done
 
   if [[ -z "$(ls -A "$VM_DIR" 2>/dev/null)" ]]; then
     echo "No VM snapshots available"
@@ -73,25 +110,34 @@ boot_vm() {
     exit 1
   fi
 
-  if [[ -f "$TMP_DISK" ]] && ! gum confirm "Override existing /tmp VM?"; then
+  if [[ -z $active_disk || -z $active_ovmf ]]; then
+    echo "Error: active disk and OVMF vars paths must not be empty"
+    exit 1
+  fi
+
+  if [[ -f $active_disk ]] && ! gum confirm "Override existing active VM disk at $active_disk?"; then
     exit 0
   fi
 
-  echo "Copying VM '$name' to /tmp..."
-  cp "$vm_path/omarchy-iso-boot.qcow2" "$TMP_DISK"
-  cp "$vm_path/OVMF_VARS.4m.fd" "$TMP_OVMF"
+  echo "Copying VM '$name' to $active_disk..."
+  mkdir -p "$(dirname "$active_disk")" "$(dirname "$active_ovmf")"
+  cp "$vm_path/omarchy-iso-boot.qcow2" "$active_disk"
+  cp "$vm_path/OVMF_VARS.4m.fd" "$active_ovmf"
 
   gum style --foreground 212 "✓ VM ready. Booting..."
 
-  exec omarchy-iso-boot /dev/null reuse
+  exec omarchy-iso-boot "${boot_args[@]}" /dev/null reuse
 }
 
-case "${1:-}" in
+command="${1:-}"
+[[ $# -gt 0 ]] && shift
+
+case "$command" in
   save)
-    save_vm "$2"
+    save_vm "${1:-}"
     ;;
   boot)
-    boot_vm "$2"
+    boot_vm "$@"
     ;;
   list)
     list_vms
@@ -101,9 +147,16 @@ case "${1:-}" in
       "$(gum style --bold 'omarchy-vm') - VM snapshot manager" \
       "" \
       "$(gum style --foreground 245 'Commands:')" \
-      "  save [name]  Save current VM from /tmp" \
-      "  boot [name]  Boot saved VM (interactive if no name)" \
-      "  list         List available VMs" \
+      "  save [name]                 Save current active VM" \
+      "  boot [name] [boot-options]  Boot saved VM (interactive if no name)" \
+      "  list                        List available VMs" \
+      "" \
+      "$(gum style --foreground 245 'Boot options:')" \
+      "  --ssh-port PORT   Forward host PORT to guest SSH (default: 2222)" \
+      "  --ssh-host HOST   Host address for SSH forwarding (default: 127.0.0.1)" \
+      "  --disk PATH       Active disk path, useful for parallel VMs" \
+      "  --ovmf-vars PATH  Active OVMF vars path, useful for parallel VMs" \
+      "  --no-network      Boot without a virtual NIC" \
       "" \
       "$(gum style --foreground 245 'Current VMs:')"
     list_vms 2>/dev/null || echo "  None"

builder/archinstall.packages

@@ -7,7 +7,9 @@ intel-ucode
 linux-firmware
 linux
 limine
+omarchy-keyring
 openssh
 pipewire
 snapper
 sof-firmware
+tailscale

builder/build-iso.sh

@@ -2,90 +2,354 @@
 
 set -e
 
-# Note that these are packages installed to the Arch container used to build the ISO.
+OMARCHY_ISO_REF="${OMARCHY_ISO_REF:-quattro}"
+OMARCHY_MIRROR="${OMARCHY_MIRROR:-stable}"
+
+# Edge, dev, and local-source ISOs install the dev packages explicitly. Those
+# package recipes track the quattro branch. This avoids relying on pacman's
+# provides=omarchy resolution and shows the real package names being tested in
+# the offline mirror and target install. Every other ref, the default quattro
+# build included, installs the published omarchy packages.
+case "$OMARCHY_ISO_REF" in
+  edge|dev|local)
+    : "${OMARCHY_RUNTIME_PACKAGE:=omarchy-dev}"
+    : "${OMARCHY_SETTINGS_PACKAGE:=omarchy-settings-dev}"
+    ;;
+  *)
+    : "${OMARCHY_RUNTIME_PACKAGE:=omarchy}"
+    : "${OMARCHY_SETTINGS_PACKAGE:=omarchy-settings}"
+    ;;
+esac
+: "${OMARCHY_NVIM_PACKAGE:=omarchy-nvim}"
+export OMARCHY_RUNTIME_PACKAGE OMARCHY_SETTINGS_PACKAGE OMARCHY_NVIM_PACKAGE
+
+# Packages installed into the Arch container used to build the ISO.
 pacman-key --init
 pacman --noconfirm -Sy archlinux-keyring
-pacman --noconfirm -Sy archiso git sudo base-devel jq grub
+# Full upgrade, not just -Sy: docker never re-pulls :latest once it's cached,
+# so this container can be months behind the mirror it installs from. A plain
+# -Sy install is then a partial upgrade — new packages linked against a glibc
+# the container doesn't have yet.
+pacman --noconfirm -Syu archiso git sudo base-devel jq grub imagemagick neovim nodejs npm tree-sitter-cli
 
-# Setup build locations
-build_cache_dir="/var/cache"
+# Pre-import the omarchy signing key (so pacman trusts our [omarchy] repo
+# during the build without keyserver lookups).
+pacman-key --add /builder/omarchy.gpg
+pacman-key --lsign-key 40DFB630FF42BCFFB047046CF0134EE680CAC571
+
+# omarchy-keyring is needed inside the offline mirror too.
+pacman --config /configs/pacman-online-${OMARCHY_MIRROR}.conf --noconfirm -Sy omarchy-keyring
+pacman-key --populate omarchy
+
+# Append the [omarchy] repo to the container's /etc/pacman.conf so subsequent
+# tools (notably makepkg in build-omarchy-packages.sh) can resolve omarchy-
+# only build deps like limine-snapper-sync and limine-mkinitcpio-hook.
+if ! grep -q '^\[omarchy\]' /etc/pacman.conf; then
+  awk '/^\[omarchy\]/,/^$/' /configs/pacman-online-${OMARCHY_MIRROR}.conf >> /etc/pacman.conf
+fi
+
+# Build locations
+build_cache_dir=/var/cache
 offline_mirror_dir="$build_cache_dir/airootfs/var/cache/omarchy/mirror/offline"
-mkdir -p $build_cache_dir/
-mkdir -p $offline_mirror_dir/
+mkdir -p "$build_cache_dir" "$offline_mirror_dir"
 
-# We base our ISO on the official arch ISO (releng) config
-cp -r /archiso/configs/releng/* $build_cache_dir/
+# Seed from the official Arch releng profile.
+cp -r /archiso/configs/releng/* "$build_cache_dir/"
 rm "$build_cache_dir/airootfs/etc/motd"
 
-# Avoid using reflector for mirror identification as we are relying on the global CDN
-rm "$build_cache_dir/airootfs/etc/systemd/system/multi-user.target.wants/reflector.service"
+# We rely on the global CDN; drop reflector.
+rm -rf "$build_cache_dir/airootfs/etc/systemd/system/multi-user.target.wants/reflector.service"
 rm -rf "$build_cache_dir/airootfs/etc/systemd/system/reflector.service.d"
 rm -rf "$build_cache_dir/airootfs/etc/xdg/reflector"
 
-# Bring in our configs
-cp -r /configs/* $build_cache_dir/
+# Bring in our archiso profile additions.
+cp -r /configs/* "$build_cache_dir/"
+mkdir -p "$build_cache_dir/airootfs/usr/share/omarchy-iso"
+echo "$OMARCHY_MIRROR" > "$build_cache_dir/airootfs/root/omarchy_mirror"
+echo "$OMARCHY_ISO_REF" > "$build_cache_dir/airootfs/root/omarchy_iso_ref"
+cat > "$build_cache_dir/airootfs/usr/share/omarchy-iso/package-targets" <<EOF
+OMARCHY_RUNTIME_PACKAGE=$OMARCHY_RUNTIME_PACKAGE
+OMARCHY_SETTINGS_PACKAGE=$OMARCHY_SETTINGS_PACKAGE
+OMARCHY_NVIM_PACKAGE=$OMARCHY_NVIM_PACKAGE
+EOF
 
-# Clone Omarchy itself
-git clone -b $OMARCHY_INSTALLER_REF https://github.com/$OMARCHY_INSTALLER_REPO.git "$build_cache_dir/airootfs/root/omarchy"
+if [[ ${OMARCHY_INSTALL_DEBUG:-} == "1" ]]; then
+  touch "$build_cache_dir/airootfs/usr/share/omarchy-iso/install-debug"
+  {
+    echo "debug=1"
+    echo "built_at=$(date -Is)"
+    echo "ref=$OMARCHY_ISO_REF"
+    echo "mirror=$OMARCHY_MIRROR"
+    echo "runtime_package=$OMARCHY_RUNTIME_PACKAGE"
+    echo "settings_package=$OMARCHY_SETTINGS_PACKAGE"
+    echo "nvim_package=$OMARCHY_NVIM_PACKAGE"
+    if [[ -d /omarchy-source ]]; then
+      echo "omarchy_source=/omarchy-source"
+      git -c safe.directory=/omarchy-source -C /omarchy-source rev-parse HEAD 2>/dev/null | sed 's/^/omarchy_commit=/' || true
+      git -c safe.directory=/omarchy-source -C /omarchy-source status --short 2>/dev/null | sed 's/^/omarchy_status=/' || true
+    fi
+    if [[ -d /omarchy-pkgs ]]; then
+      echo "omarchy_pkgs_source=/omarchy-pkgs"
+      git -c safe.directory=/omarchy-pkgs -C /omarchy-pkgs rev-parse HEAD 2>/dev/null | sed 's/^/omarchy_pkgs_commit=/' || true
+      git -c safe.directory=/omarchy-pkgs -C /omarchy-pkgs status --short 2>/dev/null | sed 's/^/omarchy_pkgs_status=/' || true
+    fi
+  } > "$build_cache_dir/airootfs/usr/share/omarchy-iso/build-info"
+fi
 
-# Make log uploader available in the ISO too
-mkdir -p "$build_cache_dir/airootfs/usr/local/bin/"
-cp "$build_cache_dir/airootfs/root/omarchy/bin/omarchy-upload-log" "$build_cache_dir/airootfs/usr/local/bin/omarchy-upload-log"
+# When --local-source is in effect, build omarchy* from the mounted source
+# trees and drop them in the offline mirror. Otherwise pacman -Syw below
+# downloads the published versions from the omarchy network mirror.
+if [[ -d /omarchy-source && -d /omarchy-pkgs ]]; then
+  bash /builder/build-omarchy-packages.sh "$offline_mirror_dir"
+  LOCAL_OMARCHY_BUILD=1
+fi
 
-# Copy the Omarchy Plymouth theme to the ISO
-mkdir -p "$build_cache_dir/airootfs/usr/share/plymouth/themes/omarchy"
-cp -r "$build_cache_dir/airootfs/root/omarchy/default/plymouth/"* "$build_cache_dir/airootfs/usr/share/plymouth/themes/omarchy/"
-
-# Download and verify Node.js binary for offline installation
+# Node.js binary for offline mise install.
 NODE_DIST_URL="https://nodejs.org/dist/latest"
-
-# Get checksums and parse filename and SHA
 NODE_SHASUMS=$(curl -fsSL "$NODE_DIST_URL/SHASUMS256.txt")
 NODE_FILENAME=$(echo "$NODE_SHASUMS" | grep "linux-x64.tar.gz" | awk '{print $2}')
 NODE_SHA=$(echo "$NODE_SHASUMS" | grep "linux-x64.tar.gz" | awk '{print $1}')
-
-# Download the tarball
 curl -fsSL "$NODE_DIST_URL/$NODE_FILENAME" -o "/tmp/$NODE_FILENAME"
-
-# Verify SHA256 checksum
-echo "$NODE_SHA /tmp/$NODE_FILENAME" | sha256sum -c - || {
-    echo "ERROR: Node.js checksum verification failed!"
-    exit 1
-}
-
-# Copy to ISO
+echo "$NODE_SHA /tmp/$NODE_FILENAME" | sha256sum -c -
 mkdir -p "$build_cache_dir/airootfs/opt/packages/"
 cp "/tmp/$NODE_FILENAME" "$build_cache_dir/airootfs/opt/packages/"
 
-# Add our additional packages to packages.x86_64
-arch_packages=(linux-t2 git gum jq openssl plymouth tzupdate)
-printf '%s\n' "${arch_packages[@]}" >>"$build_cache_dir/packages.x86_64"
+# Packages installed into the live ISO environment itself (NOT the target system).
+# The selected omarchy-settings package is needed here so its post_install hook
+# drops Omarchy's plymouthd.conf into /etc/plymouth before mkarchiso builds the
+# live initramfs.
+arch_packages=(linux-t2 git gum jq openssl plymouth ttfx tzupdate omarchy-keyring "$OMARCHY_SETTINGS_PACKAGE" lvm2 cryptsetup parted)
+printf '%s\n' "${arch_packages[@]}" >> "$build_cache_dir/packages.x86_64"
 
-# Build list of all the packages needed for the offline mirror
-all_packages=($(cat "$build_cache_dir/packages.x86_64"))
-all_packages+=($(grep -v '^#' "$build_cache_dir/airootfs/root/omarchy/install/omarchy-base.packages" | grep -v '^$'))
-all_packages+=($(grep -v '^#' "$build_cache_dir/airootfs/root/omarchy/install/omarchy-other.packages" | grep -v '^$'))
-all_packages+=($(grep -v '^#' /builder/archinstall.packages | grep -v '^$'))
+# The live ISO boots linux-t2 (see airootfs/etc/mkinitcpio.d/linux-t2.preset), so
+# stock linux is a second kernel nobody boots: ~147MB of ISO, plus its own archiso
+# initramfs, copied into both the ISO tree and the size-constrained FAT EFI image.
+#
+# It cannot just be deleted — releng's broadcom-wl hard-depends on it, and it is
+# the only releng package that does, so pacman would drag the kernel straight back
+# in. broadcom-wl is a prebuilt module for stock linux and cannot load on the
+# kernel we boot, so it has done nothing since we started booting T2 anyway. The
+# install is entirely offline and the live environment needs no Wi-Fi driver.
+#
+# Anchored so linux-t2 and linux-firmware are untouched.
+sed -i -E '/^(linux|broadcom-wl)$/d' "$build_cache_dir/packages.x86_64"
 
-# Download all the packages to the offline mirror inside the ISO
+# Build the offline mirror: everything pacstrap might want during the target
+# install. With --local-source, the omarchy* packages we just built are
+# already in the mirror and we filter them out below. Without it, pacman -Syw
+# pulls the published omarchy* from the network mirror like any other package.
+if [[ -d /omarchy-source ]]; then
+  base_pkg_lists=(/omarchy-source/install/omarchy-base.packages /omarchy-source/install/omarchy-other.packages)
+  setup_form=/omarchy-source/install/provisioning/setup-form.sh
+else
+  # Pull the same package lists out of the freshly-downloaded Omarchy runtime
+  # package so we don't need a local checkout in the non-local-source path.
+  bootstrap_cache_dir=/tmp/omarchy-pkg-bootstrap
+  rm -rf "$bootstrap_cache_dir" /tmp/offlinedb-bootstrap /tmp/omarchy-pkglists
+  mkdir -p "$bootstrap_cache_dir" /tmp/offlinedb-bootstrap
+  pacman --config /configs/pacman-online-${OMARCHY_MIRROR}.conf --noconfirm -Syw "$OMARCHY_RUNTIME_PACKAGE" --cachedir "$bootstrap_cache_dir" --dbpath /tmp/offlinedb-bootstrap >/dev/null
+  omarchy_pkg=$(find "$bootstrap_cache_dir" -maxdepth 1 -type f -name "$OMARCHY_RUNTIME_PACKAGE-*.pkg.tar.zst" | sort | head -1)
+  if [[ -z $omarchy_pkg ]]; then
+    echo "ERROR: downloaded package for $OMARCHY_RUNTIME_PACKAGE not found in $bootstrap_cache_dir" >&2
+    exit 1
+  fi
+  mkdir -p /tmp/omarchy-pkglists
+  bsdtar -xf "$omarchy_pkg" -C /tmp/omarchy-pkglists usr/share/omarchy/install/omarchy-base.packages usr/share/omarchy/install/omarchy-other.packages
+  base_pkg_lists=(/tmp/omarchy-pkglists/usr/share/omarchy/install/omarchy-base.packages /tmp/omarchy-pkglists/usr/share/omarchy/install/omarchy-other.packages)
+  # Extracted on its own, tolerating a miss: bsdtar exits non-zero for a member
+  # it can't find, so asking for this alongside the package lists would abort the
+  # build here (set -e) with a bare "Not found in archive" instead of the
+  # actionable error below.
+  bsdtar -xf "$omarchy_pkg" -C /tmp/omarchy-pkglists usr/share/omarchy/install/provisioning/setup-form.sh 2>/dev/null || true
+  setup_form=/tmp/omarchy-pkglists/usr/share/omarchy/install/provisioning/setup-form.sh
+fi
+
+mkdir -p "$build_cache_dir/airootfs/usr/share/omarchy-iso"
+cp "${base_pkg_lists[0]}" "$build_cache_dir/airootfs/usr/share/omarchy-iso/omarchy-base.packages"
+cp "${base_pkg_lists[1]}" "$build_cache_dir/airootfs/usr/share/omarchy-iso/omarchy-other.packages"
+
+# The configurator's setup form comes from the runtime this ISO bundles, so the
+# installer and the first-boot setup that finishes a deferred install can never
+# disagree. A runtime predating the split ships no such file, which would leave
+# the configurator with no prompts at all.
+if [[ ! -f $setup_form ]]; then
+  if [[ -d /omarchy-source ]]; then
+    echo "ERROR: the --local-source checkout ships no install/provisioning/setup-form.sh" >&2
+    remedy="Update the checkout to a revision carrying the shared setup form."
+  else
+    echo "ERROR: $OMARCHY_RUNTIME_PACKAGE does not ship install/provisioning/setup-form.sh" >&2
+    remedy="Publish a runtime carrying the shared setup form, or build with --local-source against a checkout that has it."
+  fi
+  echo "       The configurator sources its prompts from that file, so this ISO" >&2
+  echo "       would boot into an installer with no questions to ask." >&2
+  echo "       $remedy" >&2
+  exit 1
+fi
+cp "$setup_form" "$build_cache_dir/airootfs/usr/share/omarchy-iso/setup-form.sh"
+
+# Collect every package we want available in the offline mirror.
+declare -a all_packages
+mapfile -t all_packages < <(
+  {
+    cat "$build_cache_dir/packages.x86_64"
+    grep -hv '^#\|^$' "${base_pkg_lists[@]}"
+    grep -hv '^#\|^$' /builder/archinstall.packages
+    # Always include the selected Omarchy packages so the target install can
+    # find the runtime and companion packages in the offline mirror.
+    printf '%s\n' "$OMARCHY_RUNTIME_PACKAGE" "$OMARCHY_SETTINGS_PACKAGE" "$OMARCHY_NVIM_PACKAGE"
+  } | sort -u
+)
+
+# With --local-source we already built these omarchy* packages directly into
+# the mirror; strip them from the pacman -Syw list so it doesn't try to fetch
+# the published versions on top.
+if [[ -n ${LOCAL_OMARCHY_BUILD:-} ]]; then
+  mapfile -t all_packages < <(
+    printf '%s\n' "${all_packages[@]}" |
+      grep -Fxv \
+        -e "$OMARCHY_RUNTIME_PACKAGE" \
+        -e "$OMARCHY_SETTINGS_PACKAGE" \
+        -e "$OMARCHY_NVIM_PACKAGE" || true
+  )
+fi
+
 mkdir -p /tmp/offlinedb
-pacman --config /configs/pacman-online.conf --noconfirm -Syw "${all_packages[@]}" --cachedir $offline_mirror_dir/ --dbpath /tmp/offlinedb
-repo-add --new "$offline_mirror_dir/offline.db.tar.gz" "$offline_mirror_dir/"*.pkg.tar.zst
+download_offline_packages() {
+  pacman --config /configs/pacman-online-${OMARCHY_MIRROR}.conf --noconfirm -Syw \
+    "${all_packages[@]}" --cachedir "$offline_mirror_dir/" --dbpath /tmp/offlinedb --needed
+}
+
+# A repository may occasionally republish a package without changing its
+# filename. Pacman detects that the persistent cached copy no longer matches
+# the refreshed repository checksum and deletes it, but still fails the
+# transaction. Retry once so the now-missing package is downloaded.
+if ! download_offline_packages; then
+  echo "Offline package download failed; retrying after pacman cleaned invalid cached files..." >&2
+  download_offline_packages
+fi
+
+# Resolve the exact filenames chosen by the same synced package databases used
+# for the download. Pruning by this transaction (rather than merely keeping the
+# newest version of every cached package name) removes packages that have left
+# the lists or dependency closure, such as an old Electron major version.
+if ! resolved_package_files="$(
+  pacman --config "/configs/pacman-online-${OMARCHY_MIRROR}.conf" --noconfirm \
+    --dbpath /tmp/offlinedb -S --print --print-format '%f' "${all_packages[@]}"
+)"; then
+  echo "ERROR: could not resolve the package files required by the offline mirror" >&2
+  exit 1
+fi
+mapfile -t required_package_files <<< "$resolved_package_files"
+
+# The online transaction intentionally excludes packages built from the local
+# checkouts. Add those exact artifacts back to the keep-set after verifying
+# that the local build left exactly one file for each selected package name.
+if [[ -n ${LOCAL_OMARCHY_BUILD:-} ]]; then
+  for local_package_name in \
+    "$OMARCHY_RUNTIME_PACKAGE" "$OMARCHY_SETTINGS_PACKAGE" "$OMARCHY_NVIM_PACKAGE"; do
+    local_package_file=""
+    for candidate in "$offline_mirror_dir/$local_package_name-"*.pkg.tar.*; do
+      [[ -f $candidate && $candidate != *.sig ]] || continue
+      read -r candidate_name _ < <(pacman -Qp "$candidate" 2>/dev/null) || continue
+      [[ $candidate_name == "$local_package_name" ]] || continue
+      if [[ -n $local_package_file ]]; then
+        echo "ERROR: multiple local builds found for $local_package_name" >&2
+        exit 1
+      fi
+      local_package_file="${candidate##*/}"
+    done
+    if [[ -z $local_package_file ]]; then
+      echo "ERROR: local build not found for $local_package_name" >&2
+      exit 1
+    fi
+    required_package_files+=("$local_package_file")
+  done
+fi
+
+printf '%s\n' "${required_package_files[@]}" |
+  bash /builder/prune-offline-mirror.sh "$offline_mirror_dir"
 
-# Create a symlink to the offline mirror instead of duplicating it.
-# mkarchiso needs packages at /var/cache/omarchy/mirror/offline in the container,
-# but they're actually in $build_cache_dir/airootfs/var/cache/omarchy/mirror/offline
+# Rebuild the offline repo db from scratch so size/checksum/depends entries
+# always reflect only the package files selected for this build.
+rm -f "$offline_mirror_dir"/offline.db* "$offline_mirror_dir"/offline.files*
+repo-add "$offline_mirror_dir/offline.db.tar.gz" "$offline_mirror_dir/"*.pkg.tar.zst
+
+# mkarchiso expects the mirror at /var/cache/omarchy/mirror/offline inside the
+# container (the airootfs path); symlink rather than duplicate.
 mkdir -p /var/cache/omarchy/mirror
-ln -s "$offline_mirror_dir" "/var/cache/omarchy/mirror/offline"
+ln -sf "$offline_mirror_dir" /var/cache/omarchy/mirror/offline
+
+# Denominator for the install dashboard's progress bar. Resolving the mirror's
+# own package lists against the mirror we just indexed, with an empty local db,
+# is the question pacstrap asks at install time — same resolver, same repo, same
+# lists — so no hand-kept constant can drift.
+#
+# It over-counts by ~1 in 925: archinstall.packages lists both amd-ucode and
+# intel-ucode because the mirror must contain either. phases.py records expected
+# and actual in the timing JSON, so growing drift shows up in acceptance runs.
+# The early-bootstrap set is already inside this closure, so restating it would
+# only add a second list to drift.
+resolve_expected_packages() {
+  local resolve_root=/tmp/omarchy-expected-packages
+  local resolved
+  local -a targets
+
+  rm -rf "$resolve_root"
+  mkdir -p "$resolve_root/var/lib/pacman"
+
+  mapfile -t targets < <(
+    {
+      grep -hv '^#\|^$' /builder/archinstall.packages
+      # Read the shipped copy, which is what _runtime_package_list reads at
+      # install time, not the build-time source it came from.
+      grep -hv '^#\|^$' \
+        "$build_cache_dir/airootfs/usr/share/omarchy-iso/omarchy-base.packages"
+      printf '%s\n' "$OMARCHY_RUNTIME_PACKAGE" "$OMARCHY_SETTINGS_PACKAGE" \
+        "$OMARCHY_NVIM_PACKAGE"
+    } | sort -u
+  )
+
+  pacman --config "$build_cache_dir/pacman-offline.conf" \
+    --root "$resolve_root" --dbpath "$resolve_root/var/lib/pacman" \
+    --noconfirm -Sy >/dev/null || return 1
+
+  # Capture before counting: no pipefail here, so a pacman failure inside a
+  # pipeline would become a plausible partial count, which never trips the
+  # dashboard's fallback.
+  resolved="$(pacman --config "$build_cache_dir/pacman-offline.conf" \
+    --root "$resolve_root" --dbpath "$resolve_root/var/lib/pacman" \
+    --noconfirm -S --print --print-format '%n' "${targets[@]}")" || return 1
+
+  printf '%s\n' "$resolved" | sort -u | grep -c .
+}
+
+# Worth failing the build over: -S --print only aborts when a target is missing
+# from the offline repo, which would fail pacstrap the same way. A count that
+# merely looks wrong is not — the dashboard falls back without the file.
+if ! expected_packages="$(resolve_expected_packages)"; then
+  echo "ERROR: could not resolve the target package count from the offline mirror." >&2
+  echo "       pacman -S --print aborts the whole transaction if any single target" >&2
+  echo "       is missing, so this almost certainly means pacstrap would fail the" >&2
+  echo "       same way at install time." >&2
+  exit 1
+fi
+if (( expected_packages < 600 || expected_packages > 2000 )); then
+  echo "WARNING: resolved target package count $expected_packages is outside the" >&2
+  echo "         expected 600-2000 range; shipping no denominator so the install" >&2
+  echo "         dashboard falls back to its time-based curve." >&2
+else
+  printf '%s\n' "$expected_packages" \
+    >"$build_cache_dir/airootfs/usr/share/omarchy-iso/expected-packages"
+  echo "Target install resolves to $expected_packages packages."
+fi
 
-# Copy the pacman.conf to the ISO's /etc directory so the live environment uses our
-# same config when booted
-cp $build_cache_dir/pacman.conf "$build_cache_dir/airootfs/etc/pacman.conf"
+# Live ISO uses the same offline pacman.conf.
+cp "$build_cache_dir/pacman-offline.conf" "$build_cache_dir/airootfs/etc/pacman.conf"
 
-# Finally, we assemble the entire ISO
-mkarchiso -v -w "$build_cache_dir/work/" -o "/out/" "$build_cache_dir/"
+# Build the ISO.
+mkarchiso -v -w "$build_cache_dir/work/" -o /out/ "$build_cache_dir/"
 
-# Fix ownership of output files to match host user
-if [ -n "$HOST_UID" ] && [ -n "$HOST_GID" ]; then
-    chown -R "$HOST_UID:$HOST_GID" /out/
+# Match host UID/GID on output.
+if [[ -n $HOST_UID && -n $HOST_GID ]]; then
+  chown -R "$HOST_UID:$HOST_GID" /out/
 fi

builder/build-omarchy-packages.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# Build Omarchy packages from mounted source (/omarchy-source + /omarchy-pkgs)
+# and place the resulting .pkg.tar.zst files in the offline mirror.
+
+set -e
+
+offline_mirror_dir="$1"
+if [[ -z $offline_mirror_dir ]]; then
+  echo "Usage: build-omarchy-packages.sh <offline-mirror-dir>" >&2
+  exit 1
+fi
+
+if [[ ! -d /omarchy-source ]]; then
+  echo "ERROR: /omarchy-source not mounted (pass --local-source or set OMARCHY_SOURCE_PATH)" >&2
+  exit 1
+fi
+if [[ ! -d /omarchy-pkgs ]]; then
+  echo "ERROR: /omarchy-pkgs not mounted (set OMARCHY_PKGS_PATH or place ../omarchy-pkgs)" >&2
+  exit 1
+fi
+
+work_dir=/tmp/omarchy-pkg-build
+rm -rf "$work_dir"
+mkdir -p "$work_dir"
+
+if ! id builder &>/dev/null; then
+  useradd -m -s /bin/bash builder
+fi
+echo 'builder ALL=(ALL) NOPASSWD: /usr/bin/pacman' > /etc/sudoers.d/99-omarchy-pkg-builder
+chmod 440 /etc/sudoers.d/99-omarchy-pkg-builder
+chown builder:builder "$work_dir"
+
+pacman -Sy --noconfirm
+
+: "${OMARCHY_RUNTIME_PACKAGE:=omarchy-dev}"
+: "${OMARCHY_SETTINGS_PACKAGE:=omarchy-settings-dev}"
+: "${OMARCHY_NVIM_PACKAGE:=omarchy-nvim}"
+
+packages=(
+  "$OMARCHY_SETTINGS_PACKAGE"
+  "$OMARCHY_RUNTIME_PACKAGE"
+  "$OMARCHY_NVIM_PACKAGE"
+)
+
+# Local-source packages must replace every cached build of the same package,
+# even when the checkout's generated pkgver sorts below a published build.
+# Otherwise the later generic cache pruning can silently keep edge instead.
+for pkg in "${packages[@]}"; do
+  rm -f "$offline_mirror_dir/$pkg-"*.pkg.tar.*
+done
+
+for pkg in "${packages[@]}"; do
+  echo "----------------------------------------"
+  echo "Building $pkg"
+  echo "----------------------------------------"
+  pkg_work="$work_dir/$pkg"
+  if [[ ! -d "/omarchy-pkgs/pkgbuilds/$pkg" ]]; then
+    echo "ERROR: package source not found: /omarchy-pkgs/pkgbuilds/$pkg" >&2
+    exit 1
+  fi
+  cp -a "/omarchy-pkgs/pkgbuilds/$pkg" "$pkg_work"
+  chown -R builder:builder "$pkg_work"
+
+  su builder -c "
+    cd '$pkg_work' &&
+    PKGDEST='$work_dir' \
+    OMARCHY_SRC=/omarchy-source \
+    makepkg --noconfirm --skippgpcheck --skipchecksums --nodeps -f
+  "
+done
+
+mkdir -p "$offline_mirror_dir"
+for package_file in "$work_dir"/*.pkg.tar.zst; do
+  destination="$offline_mirror_dir/$(basename "$package_file")"
+
+  # A cached signature belongs to the previously downloaded or locally built
+  # package. Keeping it beside a newly built package makes pacman reject the
+  # otherwise valid local-source build.
+  rm -f "$destination" "$destination.sig"
+  mv "$package_file" "$destination"
+done
+
+echo
+echo "Built Omarchy packages, placed in $offline_mirror_dir:"
+ls "$offline_mirror_dir"/omarchy*.pkg.tar.zst | sed 's|^|  |'

builder/omarchy.gpg

@@ -0,0 +1,13 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mDMEaLAsIhYJKwYBBAHaRw8BAQdAYmKmrWMlfpdIPh3QzvEMzzxdNd/kqDl/Bj8H
+mCavKji0Gk9tYXJjaHkgPHBrZ3NAb21hcmNoeS5vcmc+iJAEExYKADgWIQRA37Yw
+/0K8/7BHBGzwE07mgMrFcQUCaLAsIgIbAwULCQgHAgYVCgkICwIEFgIDAQIeAQIX
+gAAKCRDwE07mgMrFcRF2AQCjjvjgju/kowkN69nenqqRnE+v2MrHmWh2wU0ugIt9
+3gD/bXGugWc5J1vqoT+5aCnJAtfRRmHEfsrAiFgjduB+VA24OARosCwiEgorBgEE
+AZdVAQUBAQdAJoU73WdgxE/pEYK5ofyRvQDs1IFRdfJHV9j4Jm+tuDUDAQgHiHgE
+GBYKACAWIQRA37Yw/0K8/7BHBGzwE07mgMrFcQUCaLAsIgIbDAAKCRDwE07mgMrF
+cYXsAQC5eBEGK0xKsGwtnDDVeNAapx32dpvLgJ94W4DtIpdLlwEA85cSsTiBMuGy
+6kwYmHzqw7oFx3VYGXdMNl0SMKzvJA4=
+=G7wU
+-----END PGP PUBLIC KEY BLOCK-----

builder/prune-offline-mirror.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+
+set -euo pipefail
+
+offline_mirror_dir="${1:-}"
+if [[ -z $offline_mirror_dir ]]; then
+  echo "Usage: prune-offline-mirror.sh <offline-mirror-dir>" >&2
+  exit 1
+fi
+if [[ ! -d $offline_mirror_dir ]]; then
+  echo "ERROR: offline mirror directory not found: $offline_mirror_dir" >&2
+  exit 1
+fi
+
+# Read the exact package filenames selected by pacman on stdin. Validate the
+# complete selection before deleting anything: an empty/partial resolution must
+# never turn a warm-cache build into a broken mirror.
+declare -A required=()
+while IFS= read -r filename; do
+  [[ -n $filename ]] || continue
+  if [[ $filename == */* || $filename != *.pkg.tar.* || $filename == *.sig ]]; then
+    echo "ERROR: invalid required package filename: $filename" >&2
+    exit 1
+  fi
+  required["$filename"]=1
+done
+
+if (( ${#required[@]} == 0 )); then
+  echo "ERROR: refusing to prune the offline mirror with an empty package selection" >&2
+  exit 1
+fi
+
+missing=()
+for filename in "${!required[@]}"; do
+  [[ -f "$offline_mirror_dir/$filename" ]] || missing+=("$filename")
+done
+if (( ${#missing[@]} > 0 )); then
+  echo "ERROR: refusing to prune; selected packages are missing from the mirror:" >&2
+  printf '  %s\n' "${missing[@]}" >&2
+  exit 1
+fi
+
+stale=()
+while IFS= read -r -d '' package_file; do
+  filename="${package_file##*/}"
+  [[ -n ${required[$filename]+x} ]] || stale+=("$package_file")
+done < <(
+  find "$offline_mirror_dir" -maxdepth 1 -type f \
+    -name '*.pkg.tar.*' ! -name '*.sig' -print0
+)
+
+if (( ${#stale[@]} > 0 )); then
+  echo "Pruning package archives not selected for the offline mirror:"
+  for package_file in "${stale[@]}"; do
+    echo "  $(basename "$package_file")"
+    rm -f -- "$package_file" "$package_file.sig"
+  done
+fi
+
+# A failed or interrupted download can leave a signature without its archive.
+# It cannot be indexed and only wastes space in the ISO.
+while IFS= read -r -d '' signature_file; do
+  [[ -f ${signature_file%.sig} ]] || rm -f -- "$signature_file"
+done < <(
+  find "$offline_mirror_dir" -maxdepth 1 -type f \
+    -name '*.pkg.tar.*.sig' -print0
+)

configs/airootfs/etc/mkinitcpio.d/linux-t2.preset

@@ -0,0 +1,18 @@
+# mkinitcpio preset file for the 'linux-t2' package on archiso
+#
+# The filename is the pkgbase, and that is load-bearing. Kernel packages ship
+# nothing in /boot — they only install usr/lib/modules/<kver>/vmlinuz — so
+# mkinitcpio's alpm hook sources /etc/mkinitcpio.d/<pkgbase>.preset and copies
+# THAT package's kernel to whatever ALL_kver names (is_kernelcopy in
+# /usr/share/libalpm/scripts/mkinitcpio). Named linux.preset, this pointed the
+# stock kernel at the T2 filenames, so the ISO booted stock Arch while every
+# boot entry said linux-t2 and T2 Macs got no keyboard or trackpad.
+#
+# releng ships its own linux.preset for the stock kernel; leave it alone.
+
+PRESETS=('archiso')
+
+ALL_kver='/boot/vmlinuz-linux-t2'
+archiso_config='/etc/mkinitcpio.conf.d/archiso.conf'
+
+archiso_image="/boot/initramfs-linux-t2.img"

configs/airootfs/etc/mkinitcpio.d/linux.preset

@@ -1,9 +0,0 @@
-# mkinitcpio preset file for the 'linux' package on archiso
-
-PRESETS=('archiso')
-
-ALL_kver='/boot/vmlinuz-linux-t2'
-archiso_config='/etc/mkinitcpio.conf.d/archiso.conf'
-
-archiso_image="/boot/initramfs-linux-t2.img"
-

configs/airootfs/etc/modprobe.d/blacklist-applesmc.conf

@@ -0,0 +1,3 @@
+# linux-t2 ships for every machine, and on a pre-T2 Mac its applesmc oopses
+# registering the keyboard-backlight LED, wedging udev. Nothing here needs the SMC.
+blacklist applesmc

configs/airootfs/etc/modprobe.d/blacklist-panther-lake-audio.conf

@@ -0,0 +1,14 @@
+# Fix Panther Lake audio: blacklist SOF modules that conflict with HDA drivers
+# (prevents boot issues on Dell XPS 2026 and similar Panther Lake systems)
+blacklist snd_sof_pci_intel_ptl
+blacklist snd_sof_pci_intel_lnl
+blacklist snd_sof_pci_intel_mtl
+blacklist snd_sof_intel_hda_generic
+blacklist snd_sof_intel_hda_common
+blacklist snd_sof_intel_hda
+blacklist snd_sof_pci
+blacklist snd_sof
+blacklist soundwire_intel
+blacklist snd_soc_cs35l56_sdw
+blacklist snd_soc_cs35l56
+blacklist snd_soc_skl_hda_dsp

configs/airootfs/etc/pacman.d/hooks/omarchy-root-shell.hook

@@ -0,0 +1,21 @@
+# remove from airootfs!
+#
+# Mirror omarchy-settings' /etc/skel shell defaults into /root so the live ISO
+# console has the same bashrc, starship prompt, and aliases as an installed
+# Omarchy system. Fires during airootfs pacstrap (when omarchy-settings is
+# installed); the "remove from airootfs" magic string causes
+# zzzz99-remove-custom-hooks-from-airootfs.hook to delete this file before
+# the squashfs is built, so no runtime hook remains.
+
+[Trigger]
+Operation = Install
+Operation = Upgrade
+Type = Package
+Target = omarchy-settings
+
+[Action]
+Description = Mirroring /etc/skel shell defaults into /root for the live ISO...
+When = PostTransaction
+Depends = coreutils
+Depends = omarchy-settings
+Exec = /bin/sh -c 'install -d -m 0700 /root/.config && for f in .bashrc .bash_profile; do [ -f "/etc/skel/$f" ] && install -m 0644 "/etc/skel/$f" "/root/$f"; done; [ -f /etc/skel/.config/starship.toml ] && install -m 0644 /etc/skel/.config/starship.toml /root/.config/starship.toml; true'

configs/airootfs/root/.automated_script.sh

@@ -1,135 +1,131 @@
 #!/usr/bin/env bash
+#
+# Live ISO entry point on tty1: set up the live VT, run the configurator
+# wizard, then hand off to the Python install orchestrator. Mirrors the
+# stream/env contract from the previously-working installer:
+#   - stdout teed to /var/log/omarchy-install.log (CSI-stripped) AND to tty
+#   - stderr direct to /dev/tty so gum (which draws its TUI on stderr)
+#     renders correctly
+#   - CLICOLOR_FORCE/FORCE_COLOR so gum emits ANSI even with stdout piped
+#   - COLUMNS/LINES so gum picks up real terminal size
 set -euo pipefail
 
-use_omarchy_helpers() {
-  export OMARCHY_PATH="/root/omarchy"
-  export OMARCHY_INSTALL="/root/omarchy/install"
-  export OMARCHY_INSTALL_LOG_FILE="/var/log/omarchy-install.log"
-  source /root/omarchy/install/helpers/all.sh
-}
+[[ $(tty) == /dev/tty1 ]] || exit 0
 
-run_configurator() {
-  set_tokyo_night_colors
-  ./configurator
-  export OMARCHY_USER="$(jq -r '.users[0].username' user_credentials.json)"
-}
-
-install_arch() {
-  clear_logo
-  gum style --foreground 3 --padding "1 0 0 $PADDING_LEFT" "Installing..."
-  echo
-
-  touch /var/log/omarchy-install.log
-
-  start_log_output
-  install_base_system 2>&1 | sed -u 's/\x1b\[[0-9;]*[a-zA-Z]//g' >>/var/log/omarchy-install.log
-  stop_log_output
-}
-
-install_omarchy() {
-  chroot_bash -lc "sudo pacman -S --noconfirm --needed gum" >/dev/null
-  chroot_bash -lc "source /home/$OMARCHY_USER/.local/share/omarchy/install.sh || bash"
-
-  # Reboot if requested by installer
-  if [[ -f /mnt/var/tmp/omarchy-install-completed ]]; then
-    reboot
-  fi
-}
-
-# Set Tokyo Night color scheme for the terminal
-set_tokyo_night_colors() {
-  if [[ $(tty) == "/dev/tty"* ]]; then
-    # Tokyo Night color palette
-    echo -en "\e]P01a1b26" # black (background)
-    echo -en "\e]P1f7768e" # red
-    echo -en "\e]P29ece6a" # green
-    echo -en "\e]P3e0af68" # yellow
-    echo -en "\e]P47aa2f7" # blue
-    echo -en "\e]P5bb9af7" # magenta
-    echo -en "\e]P67dcfff" # cyan
-    echo -en "\e]P7a9b1d6" # white
-    echo -en "\e]P8414868" # bright black
-    echo -en "\e]P9f7768e" # bright red
-    echo -en "\e]PA9ece6a" # bright green
-    echo -en "\e]PBe0af68" # bright yellow
-    echo -en "\e]PC7aa2f7" # bright blue
-    echo -en "\e]PDbb9af7" # bright magenta
-    echo -en "\e]PE7dcfff" # bright cyan
-    echo -en "\e]PFc0caf5" # bright white (foreground)
-
-    # Set default foreground and background
-    echo -en "\033[0m"
-    clear
-  fi
-}
-
-install_base_system() {
-  # Initialize and populate the keyring
-  pacman-key --init
-  pacman-key --populate archlinux
-
-  # Sync the offline database so pacman can find packages
-  pacman -Sy --noconfirm
-
-  # Ensure that no mounts exist from past install attempts
-  findmnt -R /mnt >/dev/null && umount -R /mnt
-
-  # Install using files generated by the ./configurator
-  # Skip NTP and WKD sync since we're offline (keyring is pre-populated in ISO)
-  archinstall \
-    --config user_configuration.json \
-    --creds user_credentials.json \
-    --silent \
-    --skip-ntp \
-    --skip-wkd
-
-  # After archinstall sets up the base system but before our installer runs,
-  # we need to ensure the offline pacman.conf is in place
-  cp /etc/pacman.conf /mnt/etc/pacman.conf
-
-  # Mount the offline mirror so it's accessible in the chroot
-  mkdir -p /mnt/var/cache/omarchy/mirror/offline
-  mount --bind /var/cache/omarchy/mirror/offline /mnt/var/cache/omarchy/mirror/offline
-
-  # Mount the packages dir so it's accessible in the chroot
-  mkdir -p /mnt/opt/packages
-  mount --bind /opt/packages /mnt/opt/packages
-
-  # No need to ask for sudo during the installation (omarchy itself responsible for removing after install)
-  mkdir -p /mnt/etc/sudoers.d
-  cat >/mnt/etc/sudoers.d/99-omarchy-installer <<EOF
-root ALL=(ALL:ALL) NOPASSWD: ALL
-%wheel ALL=(ALL:ALL) NOPASSWD: ALL
-$OMARCHY_USER ALL=(ALL:ALL) NOPASSWD: ALL
-EOF
-  chmod 440 /mnt/etc/sudoers.d/99-omarchy-installer
-
-  # Copy the local omarchy repo to the user's home directory
-  mkdir -p /mnt/home/$OMARCHY_USER/.local/share/
-  cp -r /root/omarchy /mnt/home/$OMARCHY_USER/.local/share/
-
-  chown -R 1000:1000 /mnt/home/$OMARCHY_USER/.local/
-
-  # Ensure all necessary scripts are executable
-  find /mnt/home/$OMARCHY_USER/.local/share/omarchy -type f -path "*/bin/*" -exec chmod +x {} \;
-  chmod +x /mnt/home/$OMARCHY_USER/.local/share/omarchy/boot.sh 2>/dev/null || true
-  chmod +x /mnt/home/$OMARCHY_USER/.local/share/omarchy/default/waybar/indicators/screen-recording.sh 2>/dev/null || true
-}
-
-chroot_bash() {
-  HOME=/home/$OMARCHY_USER \
-    arch-chroot -u $OMARCHY_USER /mnt/ \
-    env OMARCHY_CHROOT_INSTALL=1 \
-    OMARCHY_USER_NAME="$(<user_full_name.txt)" \
-    OMARCHY_USER_EMAIL="$(<user_email_address.txt)" \
-    USER="$OMARCHY_USER" \
-    HOME="/home/$OMARCHY_USER" \
-    /bin/bash "$@"
-}
-
-if [[ $(tty) == "/dev/tty1" ]]; then
-  use_omarchy_helpers
-  run_configurator
-  install_arch
-  install_omarchy
+export OMARCHY_MIRROR="$(cat /root/omarchy_mirror)"
+if [[ -f /root/omarchy_iso_ref ]]; then
+  export OMARCHY_ISO_REF="$(cat /root/omarchy_iso_ref)"
 fi
+if [[ -f /usr/share/omarchy-iso/package-targets ]]; then
+  # shellcheck disable=SC1091
+  source /usr/share/omarchy-iso/package-targets
+  export OMARCHY_RUNTIME_PACKAGE OMARCHY_SETTINGS_PACKAGE OMARCHY_NVIM_PACKAGE
+fi
+export OMARCHY_PATH=/usr/share/omarchy
+export OMARCHY_INSTALL=$OMARCHY_PATH/install
+export OMARCHY_INSTALL_LOG_FILE=/var/log/omarchy-install.log
+if [[ -f /usr/share/omarchy-iso/install-debug ]]; then
+  export OMARCHY_INSTALL_DEBUG=1
+fi
+
+# Tokyo Night palette so the live VT matches the installed look.
+set_tokyo_night_colors() {
+  echo -en "\e]P01a1b26"; echo -en "\e]P1f7768e"; echo -en "\e]P29ece6a"
+  echo -en "\e]P3e0af68"; echo -en "\e]P47aa2f7"; echo -en "\e]P5bb9af7"
+  echo -en "\e]P67dcfff"; echo -en "\e]P7a9b1d6"; echo -en "\e]P8414868"
+  echo -en "\e]P9f7768e"; echo -en "\e]PA9ece6a"; echo -en "\e]PBe0af68"
+  echo -en "\e]PC7aa2f7"; echo -en "\e]PDbb9af7"; echo -en "\e]PE7dcfff"
+  echo -en "\e]PFc0caf5"
+  echo -en "\033[0m"
+  clear
+}
+set_tokyo_night_colors
+
+mkdir -p /var/log
+touch "$OMARCHY_INSTALL_LOG_FILE"
+
+export COLUMNS=$(tput cols)
+export LINES=$(tput lines)
+exec > >(tee >(sed -u 's/\x1b\[[0-9;?]*[A-Za-z]//g' >>"$OMARCHY_INSTALL_LOG_FILE") 2>/dev/null) 2>/dev/tty
+export CLICOLOR_FORCE=1
+export FORCE_COLOR=1
+
+if [[ ${OMARCHY_INSTALL_DEBUG:-} == "1" ]]; then
+  echo "=== Omarchy ISO debug build ==="
+  [[ -f /usr/share/omarchy-iso/build-info ]] && cat /usr/share/omarchy-iso/build-info
+  pacman -Q omarchy-settings omarchy-keyring 2>/dev/null || true
+  echo "================================"
+fi
+
+# Warm the page cache for the bundled packages while the user works through the
+# wizard. The install reads ~3GB out of the offline mirror, and pacman consumes
+# it at only ~33MB/s, so on media slower than that the install is read-bound and
+# every byte cached here is a byte it never waits for. On faster media this costs
+# nothing but otherwise-idle bandwidth: the medium is untouched while the user
+# types, and the target disk it writes to later is a different device.
+#
+# Clean page cache only, so the kernel reclaims it under pressure instead of
+# OOMing, and a budget so small machines never evict what was just warmed.
+# Set OMARCHY_NO_PREFETCH=1 to A/B the same ISO with this disabled.
+warm_offline_mirror() {
+  local mirror=/var/cache/omarchy/mirror/offline
+  local budget_kb spent_kb=0 size_kb path
+
+  [[ ${OMARCHY_NO_PREFETCH:-} == 1 ]] && return 0
+  [[ -d $mirror ]] || return 0
+
+  budget_kb=$(($(awk '/^MemAvailable:/ { print $2 }' /proc/meminfo) / 2))
+  ((budget_kb > 262144)) || return 0
+
+  # Largest first: the install reads most of the mirror, so when the budget
+  # cannot cover all of it this still front-loads the bytes that dominate.
+  while read -r size_kb path; do
+    ((spent_kb + size_kb > budget_kb)) && continue
+    cat -- "$path" >/dev/null 2>&1 || true
+    spent_kb=$((spent_kb + size_kb))
+  done < <(du -k "$mirror"/*.pkg.tar.zst 2>/dev/null | sort -rn)
+}
+
+warm_offline_mirror &
+warm_pid=$!
+trap 'kill "$warm_pid" 2>/dev/null' EXIT
+
+cd /root
+# Autoinstall: a cidata drive carrying the configurator's own output files
+# stands in for the wizard. omarchy-cidata-load copies them into /root and
+# everything downstream runs the ordinary path against ordinary inputs.
+if /usr/local/bin/omarchy-cidata-load; then
+  echo "Autoinstall configuration found on cidata drive; skipping the configurator."
+  export OMARCHY_UI_INTERACTIVE=no
+else
+  ./configurator
+fi
+
+# Deferred-provisioning installs skip the celebration/reboot prompt and reboot on
+# their own — the owner completes setup at first boot. Signalled by the config's
+# defer_provisioning flag (interactive) or the defer-provisioning marker (cidata).
+# Parse the flag with jq (the same JSON semantics the orchestrator uses) rather
+# than a line regex, so a reformatted config can't read as a direct install.
+if [[ -f /root/defer-provisioning ]] ||
+  [[ "$(jq -r '.omarchy_install.defer_provisioning // false' /root/user_configuration.json 2>/dev/null)" == "true" ]]; then
+  export OMARCHY_UI_DEFER_PROVISIONING=yes
+fi
+
+# The foreground dashboard is now the sole visible install UI owner. It starts
+# the actual installer as a non-interactive child, logs child output, waits for
+# completion, then renders the final installed-time/reboot prompt itself.
+export OMARCHY_DASHBOARD_TTY="$(tty)"
+rm -f /run/omarchy-install/state.json
+/usr/local/bin/omarchy-install-dashboard \
+  "$OMARCHY_INSTALL_LOG_FILE" \
+  /run/omarchy-install/state.json \
+  -- \
+  /usr/local/bin/omarchy-iso-install \
+    --config /root/user_configuration.json \
+    --creds /root/user_credentials.json \
+    --full-name-file /root/user_full_name.txt \
+    --email-file /root/user_email_address.txt \
+    --encrypt-file /root/user_encrypt_installation.txt \
+    --authorized-keys-file /root/authorized_keys \
+    --tailscale-authkey-file /root/tailscale_authkey \
+    --defer-provisioning-file /root/defer-provisioning

configs/airootfs/usr/local/bin/omarchy-cidata-load

@@ -0,0 +1,70 @@
+#!/bin/bash
+#
+# Autoinstall: a drive labeled cidata (the cloud-init NoCloud label, so Proxmox,
+# libvirt and Packer all know how to attach one) carrying the configurator's own
+# output files stands in for the wizard. Copy those files into /root and
+# everything downstream runs the ordinary path against ordinary inputs.
+#
+# Exits 0 when an autoinstall drive was loaded and the configurator can be
+# skipped. The required pair is the same one the orchestrator treats as
+# mandatory; the rest are optional there too, so don't be stricter here.
+# Anything less than the pair means this isn't an autoinstall drive, and the
+# caller falls back to the wizard.
+#
+# A `defer-provisioning` marker file stands in for user_credentials.json: deferred-provisioning
+# installs defer user creation to first boot, so imaging rigs ship no credentials.
+#
+# The optional argument prefixes every path the script touches; tests use it to
+# run against a sandbox instead of the live system.
+
+set -uo pipefail
+
+root=${1:-}
+by_label=$root/dev/disk/by-label
+dest=$root/root
+mnt=$root/run/cidata
+
+# The by-label symlinks come from udev, and on a fast boot this can run before
+# device enumeration has finished. Wait for the queue to drain instead of
+# racing it and silently dropping a headless install into the wizard.
+udevadm settle 2>/dev/null || true
+
+device=""
+for label in cidata CIDATA; do
+  [[ -e $by_label/$label ]] && { device=$by_label/$label; break; }
+done
+[[ -n $device ]] || exit 1
+
+mkdir -p "$mnt"
+mount -o ro "$device" "$mnt" || exit 1
+
+# Clear any inputs a previous load in this live session left in /root before
+# copying the current drive: a stale `defer-provisioning` marker or credentials file would
+# otherwise force a fresh drive back into deferred provisioning or hand it an old
+# LUKS passphrase. The interactive wizard writes these same names, but a
+# cidata load always precedes it, so nothing of the user's is discarded here.
+optional_inputs=(user_credentials.json defer-provisioning user_full_name.txt user_email_address.txt user_encrypt_installation.txt authorized_keys tailscale_authkey)
+for file in user_configuration.json "${optional_inputs[@]}"; do
+  rm -f "$dest/$file"
+done
+
+loaded=1
+if [[ -f $mnt/user_configuration.json ]] && [[ -f $mnt/user_credentials.json || -f $mnt/defer-provisioning ]]; then
+  files=("$mnt"/user_configuration.json)
+  for file in "${optional_inputs[@]}"; do
+    [[ -f $mnt/$file ]] && files+=("$mnt/$file")
+  done
+  if cp "${files[@]}" "$dest"/; then
+    loaded=0
+  else
+    # A partial copy must not leave files behind: the wizard cleans up only
+    # what it writes itself, so a half-copied authorized_keys would leak into
+    # the interactive install that follows.
+    for file in "${files[@]}"; do
+      rm -f "$dest/${file##*/}"
+    done
+  fi
+fi
+
+umount "$mnt"
+exit $loaded

configs/airootfs/usr/local/bin/omarchy-install-dashboard

@@ -0,0 +1,888 @@
+#!/usr/bin/env bash
+# Foreground Omarchy ISO install UI supervisor.
+#
+# This process is the only owner of the visible install UI. It launches the
+# actual installer as a non-interactive child, sends child output to the support
+# log, renders progress while the child runs, then renders the final installed
+# time + reboot prompt itself. There is deliberately no background dashboard.
+set -euo pipefail
+
+usage() {
+  echo "Usage: $0 <log-file> <state-file> -- <installer command...>" >&2
+  exit 2
+}
+
+(( $# >= 4 )) || usage
+LOG_FILE="$1"
+STATE_FILE="$2"
+shift 2
+[[ ${1:-} == "--" ]] || usage
+shift
+(( $# > 0 )) || usage
+INSTALL_CMD=("$@")
+
+TTY_PATH="${OMARCHY_DASHBOARD_TTY:-/dev/tty}"
+LOGO_PATH="${OMARCHY_PATH:-/usr/share/omarchy}/logo.txt"
+
+# Autoinstall has no one at the keyboard, and every prompt this dashboard owns
+# reads from the TTY, so each would hang forever. Suppress them here rather than
+# in the scripts they live in: this process is the only owner of the visible UI.
+interactive() { [[ ${OMARCHY_UI_INTERACTIVE:-} != "no" ]]; }
+
+CSI=$'\033['
+RESET="${CSI}0m"
+DIM="${CSI}2m"
+HIDE_CURSOR="${CSI}?25l"
+SHOW_CURSOR="${CSI}?25h"
+CLEAR="${CSI}2J${CSI}H"
+CLEAR_LINE="${CSI}2K"
+CLEAR_TO_END="${CSI}J"
+GREEN="${CSI}32m"
+WHITE="${CSI}37m"
+RED="${CSI}31m"
+DARK="${CSI}90m"
+
+# The dashboard owns the final reboot prompt now, so keep the gum confirm
+# styling that used to come from install/helpers/presentation.sh.
+export GUM_CONFIRM_PROMPT_FOREGROUND="${GUM_CONFIRM_PROMPT_FOREGROUND:-6}"
+export GUM_CONFIRM_SELECTED_FOREGROUND="${GUM_CONFIRM_SELECTED_FOREGROUND:-0}"
+export GUM_CONFIRM_SELECTED_BACKGROUND="${GUM_CONFIRM_SELECTED_BACKGROUND:-2}"
+export GUM_CONFIRM_UNSELECTED_FOREGROUND="${GUM_CONFIRM_UNSELECTED_FOREGROUND:-7}"
+export GUM_CONFIRM_UNSELECTED_BACKGROUND="${GUM_CONFIRM_UNSELECTED_BACKGROUND:-0}"
+
+child_pid=""
+child_pgid=""
+
+tips=(
+  "Super + Space opens the Omarchy menu for apps, settings, and more"
+  "Super + K shows all the key bindings"
+  "Super is the Windows or command key on your keyboard"
+  "Use Xournal++ to sign PDFs"
+  "Share files with phones and laptops using LocalSend"
+  "Turn any website into an app with Install > Web App in the menu"
+  "Super + Return opens a terminal, Super + Shift + Return the browser"
+  "Edit images with Pinta, videos with Kdenlive, docs with LibreOffice"
+  "Super + Ctrl + Print grabs text off the screen with OCR"
+  "Print takes a screenshot, Alt + Print records the screen"
+  "Set a reminder with Super + Ctrl + R"
+  "Switch themes from Style > Theme in the Omarchy menu"
+  "Double-click the menu bar to make it transparent"
+  "Run a full Windows VM via Install > Windows in the menu"
+  "Super + Ctrl + V opens the clipboard manager"
+  "Super + 1 through 0 switches workspaces, add Shift to bring the window"
+  "Super + Print picks a color from anywhere on screen"
+  "Keep the system fresh with Update in the Omarchy menu"
+)
+
+cleanup() {
+  printf '%s%s' "$RESET" "$SHOW_CURSOR" >"$TTY_PATH" 2>/dev/null || true
+}
+
+dashboard_log() {
+  printf '[dashboard] %s\n' "$*" >>"$LOG_FILE" 2>/dev/null || true
+}
+
+stop_child() {
+  [[ -n ${child_pid:-} ]] || return 0
+  if kill -0 "$child_pid" 2>/dev/null; then
+    if [[ -n ${child_pgid:-} ]]; then
+      kill -- -"$child_pgid" 2>/dev/null || true
+    fi
+    kill "$child_pid" 2>/dev/null || true
+    for _ in {1..20}; do
+      kill -0 "$child_pid" 2>/dev/null || break
+      sleep 0.05
+    done
+    if kill -0 "$child_pid" 2>/dev/null; then
+      [[ -n ${child_pgid:-} ]] && kill -9 -- -"$child_pgid" 2>/dev/null || true
+      kill -9 "$child_pid" 2>/dev/null || true
+    fi
+  fi
+  wait "$child_pid" 2>/dev/null || true
+}
+
+interrupt() {
+  local code="$1"
+  stop_child
+  cleanup
+  exit "$code"
+}
+
+trap cleanup EXIT
+trap 'interrupt 130' INT
+trap 'interrupt 143' TERM
+
+term_size() { stty size 2>/dev/null <"$TTY_PATH" || printf '24 80\n'; }
+term_cols() { local size; size="$(term_size)"; printf '%s\n' "${size#* }"; }
+
+repeat() {
+  local char="$1" count="$2" out="" i
+  for ((i=0; i<count; i++)); do out+="$char"; done
+  printf '%s' "$out"
+}
+
+logo_width() {
+  if [[ -f $LOGO_PATH ]]; then
+    # The logo is drawn in box-drawing glyphs, three bytes each in UTF-8, so
+    # awk's `length` returns 197 rather than 81 unless the locale happens to be
+    # UTF-8 — and a width wider than the console makes left_padding clamp to
+    # zero, which puts the logo flush left. Count bytes deliberately (LC_ALL=C)
+    # and drop the continuation bytes instead, so the answer is columns in every
+    # locale rather than only in the ones that have a charset.
+    LC_ALL=C awk '
+      { gsub(/[\200-\277]/, ""); if (length > max) max = length }
+      END { print max+0 }
+    ' "$LOGO_PATH"
+  else
+    printf '81\n'
+  fi
+}
+
+logo_height() {
+  if [[ -f $LOGO_PATH ]]; then
+    wc -l <"$LOGO_PATH"
+  else
+    printf '1\n'
+  fi
+}
+
+LOGO_WIDTH="$(logo_width)"
+LOGO_HEIGHT="$(logo_height)"
+(( LOGO_WIDTH > 0 )) || LOGO_WIDTH=81
+(( LOGO_HEIGHT > 0 )) || LOGO_HEIGHT=1
+CONTENT_WIDTH="$LOGO_WIDTH"
+# Rows the progress screen occupies: logo, blank, title, blank, bar, blank, tip.
+PROGRESS_HEIGHT=$((LOGO_HEIGHT + 6))
+TOP_ROW=1
+DYNAMIC_ROW=$((LOGO_HEIGHT + 3))
+LAST_SIZE=""
+LAST_PM=10
+# The finish screen mirrors the greeter's frame — logo, blank, one line, gap,
+# one button — so the last thing the installer shows matches the first. It runs
+# one row taller: `gum confirm` always paints prompt/blank/button and clears all
+# three, so the button cannot sit closer than two rows under a title we drew.
+FINISH_HEIGHT=$((LOGO_HEIGHT + 5))
+FINISH_TOP_ROW=2
+
+# ── Install progress ─────────────────────────────────────────────────────────
+#
+# Position = max(floor, work), both non-decreasing, in per-mille of the bar.
+#
+#   floor  lo + (span-1) * t / (t+tau), on time since this process saw the
+#          phase. Asymptotic, so it approaches the band end without reaching it.
+#          tau is a shape constant, not a duration prediction.
+#   work   packages installed / PKG_TOTAL, for the package phase only (~85% of
+#          the install). libalpm makes one directory per package under
+#          <target>/var/lib/pacman/local; the denominator comes from
+#          build-iso.sh, so there is no second package list to drift.
+#
+# Per-mille because a whole-percent asymptote over a 2-point band has two
+# reachable values and stops moving. No give-up predicate: two discontinuous
+# curves behind a monotonic clamp freeze. With no signal the floor alone still
+# finishes the band.
+EXPECTED_PACKAGES_FILE="${OMARCHY_EXPECTED_PACKAGES_FILE:-/usr/share/omarchy-iso/expected-packages}"
+PKG_TOTAL=0
+if [[ -r $EXPECTED_PACKAGES_FILE ]]; then
+  read -r PKG_TOTAL _ <"$EXPECTED_PACKAGES_FILE" 2>/dev/null || PKG_TOTAL=0
+fi
+[[ $PKG_TOTAL =~ ^[0-9]+$ ]] || PKG_TOTAL=0
+# A wrong denominator is worse than none: it never triggers the fallback.
+(( PKG_TOTAL < 300 || PKG_TOTAL > 5000 )) && PKG_TOTAL=0
+
+PKG_BONUS_MAX_PM=100   # cap on how far the bar may run ahead of the count
+PKG_TAIL_PM=40         # band held back so a stalled bar has somewhere to go
+PKG_FLOOR_TAU=900      # with a work signal, time is only a backstop until the
+                       # first package, so slow it until it cannot outrun data
+
+POS=10                 # position, per-mille, monotonic
+PROGRESS_PM=10
+NOW=0                  # monotonic seconds, refreshed once per frame
+DASH_T0=0
+PHASE_NAME=""          # last phase this process observed
+PHASE_T0=0             # NOW when it was first observed
+PHASE_LO=10            # POS on entry, for an unknown phase with no index
+PKG_DB_DIR=""
+PKG_COUNT=0
+PKG_BASE=-1            # package count when the phase started
+PKG_SEEN=0             # running max of packages since PKG_BASE
+PKG_LAST_CHANGE=0
+PKG_BONUS=0
+
+# Monotonic clock: tzupdate and systemd-timesyncd can step the wall clock
+# mid-install, which would jump every time-driven band to its ceiling.
+set_now() {
+  local up rest
+  if read -r up rest </proc/uptime 2>/dev/null && [[ $up == [0-9]* ]]; then
+    NOW=${up%%.*}
+  else
+    NOW=$EPOCHSECONDS
+  fi
+  return 0
+}
+
+left_padding() {
+  local width="${1:-$CONTENT_WIDTH}" cols pad
+  cols="$(term_cols)"
+  pad=$(( (cols - width) / 2 ))
+  (( pad < 0 )) && pad=0
+  printf '%*s' "$pad" ''
+}
+
+visible_len() {
+  local text="$1"
+  text="$(printf '%b' "$text" | sed -E $'s/\x1b\\[[0-9;?]*[A-Za-z]//g')"
+  printf '%s' "${#text}"
+}
+
+blank_line() { printf '\r%s\n' "$CLEAR_LINE"; }
+
+line_at() {
+  local width="${1:-$CONTENT_WIDTH}" indent="${2:-0}"
+  shift 2
+  printf '\r%s%s%*s' "$CLEAR_LINE" "$(left_padding "$width")" "$indent" ''
+  printf '%b' "$*"
+}
+
+center() {
+  local text="$1" width="${2:-$CONTENT_WIDTH}" len inner_pad
+  len="$(visible_len "$text")"
+  inner_pad=$(( (width - len) / 2 ))
+  (( inner_pad < 0 )) && inner_pad=0
+  printf '\r%s%s%*s%b%s\n' "$CLEAR_LINE" "$(left_padding "$width")" "$inner_pad" '' "$text" "$RESET"
+}
+
+render_logo() {
+  local pad
+  pad="$(left_padding "$LOGO_WIDTH")"
+  if [[ -f $LOGO_PATH ]]; then
+    while IFS= read -r line; do
+      printf '\r%s%s%b%s%b\n' "$CLEAR_LINE" "$pad" "$GREEN" "$line" "$RESET"
+    done <"$LOGO_PATH"
+  else
+    center "${GREEN}Omarchy${RESET}" "$CONTENT_WIDTH"
+  fi
+}
+
+progress_bar() {
+  local pm="$1" width="${2:-34}" filled empty
+  (( pm < 0 )) && pm=0
+  (( pm > 1000 )) && pm=1000
+  filled=$(( pm * width / 1000 ))
+  empty=$(( width - filled ))
+  printf '%s%s%s%s%s' "$WHITE" "$(repeat █ "$filled")" "$DARK" "$(repeat ░ "$empty")" "$RESET"
+}
+
+# Packages libalpm has finished installing. local/ holds one directory per
+# package and nothing else in it is a directory, so */ is exact. One glob, no
+# forks: this runs twice a second while the disk is saturated.
+count_packages() {
+  local -a entries
+  PKG_COUNT=0
+  [[ -n $PKG_DB_DIR ]] || return 0
+  entries=("$PKG_DB_DIR"/*/)
+  # Unmatched globs expand to the pattern; nullglob stays off script-wide.
+  if (( ${#entries[@]} == 1 )) && [[ ! -d ${entries[0]} ]]; then
+    return 0
+  fi
+  PKG_COUNT=${#entries[@]}
+  return 0
+}
+
+# Sets PROGRESS_PM. Never call in a command substitution: POS, the phase timer
+# and the package counters must survive between frames. Print nothing — output
+# here would land on the TTY between the cursor escape and the bar.
+install_progress() {
+  local phase finished index total target
+  local lo hi tau span t pos work gap n pkg_signal=0
+  local -a state
+
+  PROGRESS_PM=$POS
+  [[ -f $STATE_FILE ]] || return 0
+
+  mapfile -t state < <(jq -r '
+    (.current_phase // "Starting installation"),
+    ((.finished_at // 0) | tonumber? // 0 | floor),
+    ((.current_index // -1) | tonumber? // -1 | floor),
+    ((.total_phases // 0) | tonumber? // 0 | floor),
+    (.target // "/mnt")
+  ' "$STATE_FILE" 2>/dev/null)
+  (( ${#state[@]} == 5 )) || return 0
+  phase="${state[0]}" finished="${state[1]}"
+  index="${state[2]}" total="${state[3]}" target="${state[4]}"
+  [[ -n $target ]] || target="/mnt"
+
+  if (( finished > 0 )) || [[ $phase == "Installation complete" ]]; then
+    POS=1000
+    PROGRESS_PM=1000
+    return 0
+  fi
+
+  # Transitions are observed here rather than read from the state file, which
+  # keeps wall clock out of the dashboard entirely.
+  if [[ $phase != "$PHASE_NAME" ]]; then
+    PHASE_NAME="$phase"
+    PHASE_T0=$NOW
+    PHASE_LO=$POS
+    PKG_BASE=-1
+    PKG_SEEN=0
+    PKG_BONUS=0
+    PKG_LAST_CHANGE=$NOW
+  fi
+
+  # Bands in per-mille, plus tau. The tail bands are wide relative to what they
+  # cost on NVMe: run_system_finalizer can DKMS-build a driver and
+  # finalize_limine_boot rebuilds every UKI, so they vary most on real hardware.
+  # Over-allotting costs a step at a boundary; under-allotting costs a stall.
+  case "$phase" in
+    "Starting installation")      lo=10  hi=25   tau=5   ;;
+    "Preparing live environment") lo=25  hi=50   tau=25  ;;
+    "Preparing install target")   lo=50  hi=65   tau=20  ;;
+    "Installing Arch + Omarchy")  lo=65  hi=700  tau=150 pkg_signal=1 ;;
+    "Configuring hibernation")    lo=700 hi=720  tau=10  ;;
+    "Configuring system")         lo=720 hi=850  tau=120 ;;
+    "Staging provisioning")          lo=850 hi=855  tau=5   ;;
+    "Finalizing Limine boot")     lo=855 hi=950  tau=90  ;;
+    "Finalizing user")            lo=950 hi=978  tau=30  ;;
+    "Configuring login")          lo=978 hi=988  tau=5   ;;
+    "Configuring DNS resolver")   lo=988 hi=994  tau=5   ;;
+    "Validating boot setup")      lo=994 hi=998  tau=5   ;;
+    "Creating factory snapshot")  lo=998 hi=1000 tau=5   ;;
+    *)
+      # Unknown names used to inherit a 1->99 sweep. Derive an even band from
+      # the published index instead; with no index, a bounded slice, so a
+      # renamed phase degrades to one cell rather than a runaway.
+      if (( total >= 2 && index >= 0 && index < total )); then
+        lo=$(( 10 + 990 * index / total ))
+        hi=$(( 10 + 990 * (index + 1) / total ))
+      else
+        lo=$PHASE_LO
+        hi=$(( PHASE_LO + 30 ))
+      fi
+      tau=60
+      ;;
+  esac
+
+  (( pkg_signal && PKG_TOTAL > 0 )) || pkg_signal=0
+  (( pkg_signal )) && tau=$PKG_FLOOR_TAU
+
+  t=$(( NOW - PHASE_T0 ))
+  (( t < 0 )) && t=0
+  span=$(( hi - lo ))
+  (( span < 2 )) && span=2
+  (( tau < 1 )) && tau=1
+
+  pos=$(( lo + (span - 1) * t / (t + tau) ))
+
+  if (( pkg_signal )); then
+    PKG_DB_DIR="$target/var/lib/pacman/local"
+    count_packages
+    # Baseline on first sight: a target that already holds packages would
+    # otherwise pin the bar at the band ceiling for the whole phase.
+    (( PKG_BASE < 0 )) && PKG_BASE=$PKG_COUNT
+    n=$(( PKG_COUNT - PKG_BASE ))
+    (( n < 0 )) && n=0
+    # Running max: a reinstalled package briefly drops its version-stamped dir.
+    if (( n > PKG_SEEN )); then
+      PKG_SEEN=$n
+      PKG_LAST_CHANGE=$NOW
+    fi
+    gap=$(( NOW - PKG_LAST_CHANGE ))
+    (( gap < 0 )) && gap=0
+    (( gap > PKG_BONUS_MAX_PM )) && gap=$PKG_BONUS_MAX_PM
+    (( gap > PKG_BONUS )) && PKG_BONUS=$gap
+    work=$(( lo + (span - 1 - PKG_TAIL_PM) * PKG_SEEN / PKG_TOTAL + PKG_BONUS ))
+    (( work > pos )) && pos=$work
+  fi
+
+  (( pos > hi - 1 )) && pos=$(( hi - 1 ))
+  (( pos > POS )) && POS=$pos
+  (( POS > 1000 )) && POS=1000
+  PROGRESS_PM=$POS
+  return 0
+}
+
+# One tip per 8 seconds, in order. On elapsed time, not a frame counter: a frame
+# is 0.5s of sleep plus a render, which stretches under pacstrap I/O — on the
+# machine where the tips, not the bar, are carrying liveness.
+current_tip() {
+  printf '%s' "${tips[$(( (NOW - DASH_T0) / 8 % ${#tips[@]} ))]}"
+}
+
+# Vertically center a block of the given height, echoing the row it starts on.
+# Both screens here center the way the configurator's greeter centers its
+# welcome, so the install opens, runs, and closes on the same composition
+# rather than stacking each frame from row one.
+centered_top_row() {
+  local height="$1" rows top
+  rows="$(term_size)"
+  rows="${rows%% *}"
+  [[ $rows =~ ^[0-9]+$ ]] || rows=24
+  top=$(( (rows - height) / 2 ))
+  (( top < 0 )) && top=0
+  printf '%d' "$(( top + 1 ))"
+}
+
+measure_progress_layout() {
+  LAST_SIZE="$(term_size)"
+  TOP_ROW="$(centered_top_row "$PROGRESS_HEIGHT")"
+  DYNAMIC_ROW=$(( TOP_ROW + LOGO_HEIGHT + 1 ))
+}
+
+render_static() {
+  measure_progress_layout
+  printf '%s%s%d;1H' "$CLEAR" "$CSI" "$TOP_ROW"
+  render_logo
+  blank_line
+}
+
+render_dynamic() {
+  local pm
+  # The console can still resize under us (the framebuffer settles late in VMs).
+  # Horizontal padding is recomputed every frame anyway, but the logo is drawn
+  # once, so redraw the static half at the new center rather than leave the
+  # centered layout stranded against a stale geometry.
+  [[ "$(term_size)" == "$LAST_SIZE" ]] || render_static
+  set_now
+  install_progress
+  pm=$PROGRESS_PM
+  [[ $pm =~ ^[0-9]+$ ]] || pm=$LAST_PM
+  (( pm > 1000 )) && pm=1000
+  # POS is monotone by construction; this is a guard, not the mechanism.
+  (( pm < LAST_PM )) && pm=$LAST_PM
+  LAST_PM=$pm
+
+  printf '%s%d;1H' "$CSI" "$DYNAMIC_ROW"
+  center "Installing Omarchy" "$CONTENT_WIDTH"
+  blank_line
+  line_at "$CONTENT_WIDTH" $(( (CONTENT_WIDTH - 34) / 2 )) ""
+  progress_bar "$pm" 34
+  printf '\n'
+  blank_line
+  center "${DIM}Tip:${RESET} ${GREEN}$(current_tip)${RESET}" "$CONTENT_WIDTH"
+  printf '%s' "$CLEAR_TO_END"
+}
+
+install_duration() {
+  local path line duration
+
+  if [[ -f $STATE_FILE ]]; then
+    duration="$(jq -r '
+      ((.started_at // 0) | tonumber? // 0) as $started
+      | ((.finished_at // 0) | tonumber? // 0) as $finished
+      | if $started <= 0 or $finished <= 0 or $finished < $started then empty
+        else (($finished - $started) | round) as $secs
+          | if $secs >= 3600 then "\($secs / 3600 | floor)h \($secs % 3600 / 60 | floor)m \($secs % 60)s"
+            else "\($secs / 60 | floor)m \($secs % 60)s"
+            end
+        end
+    ' "$STATE_FILE" 2>/dev/null || true)"
+    [[ -n $duration ]] && { printf '%s' "$duration"; return 0; }
+  fi
+
+  for path in /mnt/var/log/omarchy-install.log "$LOG_FILE"; do
+    [[ -f $path ]] || continue
+    for prefix in Total Omarchy; do
+      line="$(grep "^$prefix:" "$path" 2>/dev/null | tail -n 1 || true)"
+      [[ -n $line ]] || continue
+      duration="${line#*:}"
+      duration="${duration#${duration%%[![:space:]]*}}"
+      [[ -n $duration ]] && { printf '%s' "$duration"; return 0; }
+    done
+  done
+  return 0
+}
+
+render_finish() {
+  local duration effect_canvas_width
+  duration="$(install_duration || true)"
+  duration="${duration:-Complete}"
+  # ttfx centers its text two columns right of plain centering, so hand it a
+  # canvas two columns narrower and the animated logo lands exactly on the
+  # static one left_padding already drew. Otherwise the logo jumps a column
+  # sideways when the effect starts and again when it ends.
+  effect_canvas_width="$(term_cols)"
+  (( effect_canvas_width > 2 )) && effect_canvas_width=$((effect_canvas_width - 2))
+
+  # Set before anything that can fail, so reboot_prompt still lands on the
+  # button row even if the logo or the effect below never renders.
+  FINISH_TOP_ROW="$(centered_top_row "$FINISH_HEIGHT")"
+
+  {
+    printf '%s%s%s%d;1H' "$SHOW_CURSOR" "$CLEAR" "$CSI" "$FINISH_TOP_ROW"
+    render_logo
+    blank_line
+    center "Installed Omarchy in ${duration}" "$CONTENT_WIDTH"
+    blank_line
+  } >"$TTY_PATH"
+
+  if [[ -f $LOGO_PATH ]]; then
+    # Reuse mode restores a saved cursor before moving up over its input. Save
+    # this anchor so the effect redraws the same logo rows shown above.
+    printf '%s%d;1H\0337' "$CSI" "$((FINISH_TOP_ROW + LOGO_HEIGHT))" >"$TTY_PATH"
+    # Laseretch runs ~4s at 260fps, so the 8s cap is a stuck-process guard rather
+    # than a trim. --xterm-colors keeps the whole effect in the 256-index palette
+    # the way the greeter does, since the console reduces indexed codes well and
+    # truecolor ones badly, and it settles on indexed 2 — the green gum already
+    # drew the logo in above, so the send-off ends on the frame it started from
+    # instead of recoloring it. The laser and sparks keep their own hot palette.
+    timeout 8s ttfx -i "$LOGO_PATH" \
+      --canvas-width "$effect_canvas_width" \
+      --anchor-text c \
+      --frame-rate 260 \
+      --reuse-canvas \
+      --xterm-colors \
+      laseretch \
+      --final-gradient-stops 2 \
+      >"$TTY_PATH" 2>/dev/null || dashboard_log "logo effect skipped (ttfx exited $?)"
+    printf '%s%d;1H' "$CSI" "$((FINISH_TOP_ROW + LOGO_HEIGHT + 5))" >"$TTY_PATH"
+  fi
+}
+
+reboot_prompt() {
+  local prompt_pad
+
+  # Nobody to confirm; the OMARCHY_UI_AUTO_REBOOT check at the call site still
+  # applies, so setting both stops on the finish screen without a keyboard.
+  interactive || return 0
+
+  # gum paints its prompt row at the cursor and the button two rows under it, so
+  # anchor on the row right below the title to put the button as close to it as
+  # gum allows. FINISH_HEIGHT budgets for the same three rows.
+  printf '%s%d;1H%s' "$CSI" "$((FINISH_TOP_ROW + LOGO_HEIGHT + 2))" "$CLEAR_LINE" >"$TTY_PATH"
+
+  prompt_pad=$(( ( $(term_cols) - 18 ) / 2 ))
+  (( prompt_pad < 0 )) && prompt_pad=0
+  gum confirm \
+    --padding "0 0 0 $prompt_pad" \
+    --show-help=false \
+    --default \
+    --affirmative "Reboot Now" \
+    --negative "" \
+    "" <"$TTY_PATH" >"$TTY_PATH" 2>&1
+}
+
+truncate_for_width() {
+  local text="$1" width="$2"
+  if (( ${#text} > width )); then
+    printf '%s…' "${text:0:$((width - 1))}"
+  else
+    printf '%s' "$text"
+  fi
+}
+
+render_failure_log_tail() {
+  # The caller passes the rows it spent above this point that the constant below
+  # does not know about, so the tail gives way rather than pushing the top of
+  # the screen off a short console.
+  local reserved="${1:-0}" rows lines width line tail_log label
+  rows=$(term_size)
+  rows=${rows%% *}
+  lines=$((rows - LOGO_HEIGHT - 18 - reserved))
+  (( lines < 6 )) && lines=6
+  (( lines > 14 )) && lines=14
+  width=$((CONTENT_WIDTH - 4))
+  (( width < 40 )) && width=40
+
+  tail_log="${OMARCHY_FAILURE_TAIL_LOG:-}"
+  if [[ -z $tail_log ]]; then
+    if [[ -f /mnt/var/log/omarchy-install.log ]]; then
+      tail_log=/mnt/var/log/omarchy-install.log
+    else
+      tail_log="$LOG_FILE"
+    fi
+  fi
+  [[ -f $tail_log ]] || return 0
+
+  label="Last log lines:"
+  [[ $tail_log == /mnt/* ]] && label="Last target log lines:"
+  line_at "$CONTENT_WIDTH" 2 "${DIM}${label}${RESET}"
+  printf '\n'
+  tail -n "$lines" "$tail_log" 2>/dev/null | while IFS= read -r line; do
+    line_at "$CONTENT_WIDTH" 2 "$(truncate_for_width "$line" "$width")"
+    printf '\n'
+  done
+}
+
+find_log_uploader() {
+  local candidate
+  for candidate in omarchy-upload-log /usr/local/bin/omarchy-upload-log /usr/bin/omarchy-upload-log /mnt/usr/bin/omarchy-upload-log; do
+    if [[ $candidate == */* ]]; then
+      [[ -x $candidate ]] && { printf '%s' "$candidate"; return 0; }
+    elif command -v "$candidate" >/dev/null 2>&1; then
+      command -v "$candidate"
+      return 0
+    fi
+  done
+  return 1
+}
+
+prompt_enter() {
+  printf '\nPress Enter to continue…' >"$TTY_PATH"
+  IFS= read -r _ <"$TTY_PATH" || true
+}
+
+upload_failure_log() {
+  local uploader
+  printf '%s%s' "$SHOW_CURSOR" "$CLEAR" >"$TTY_PATH" 2>/dev/null || true
+  if uploader=$(find_log_uploader); then
+    "$uploader" install >"$TTY_PATH" 2>&1 || true
+  else
+    {
+      echo "No log uploader is available in this environment."
+      echo "Install log: $LOG_FILE"
+      [[ -f /mnt/var/log/omarchy-install.log ]] && echo "Target log: /mnt/var/log/omarchy-install.log"
+    } >"$TTY_PATH"
+  fi
+  prompt_enter
+}
+
+view_failure_log() {
+  printf '%s%s' "$SHOW_CURSOR" "$CLEAR" >"$TTY_PATH" 2>/dev/null || true
+  if command -v less >/dev/null 2>&1 && [[ -f $LOG_FILE ]]; then
+    less "$LOG_FILE" <"$TTY_PATH" >"$TTY_PATH" 2>&1 || true
+  else
+    tail -n 200 "$LOG_FILE" >"$TTY_PATH" 2>&1 || true
+    prompt_enter
+  fi
+}
+
+# A failure the medium explains is worth saying before the log tail, because
+# the tail is where "invalid or corrupted package" already scrolled past
+# without ever naming the USB stick it came off.
+diagnose_media() {
+  local logs=("$LOG_FILE")
+
+  [[ -f /mnt/var/log/omarchy-install.log ]] && logs+=(/mnt/var/log/omarchy-install.log)
+  [[ -n ${OMARCHY_FAILURE_TAIL_LOG:-} ]] && logs+=("$OMARCHY_FAILURE_TAIL_LOG")
+
+  omarchy-install-diagnose-media "${logs[@]}" 2>/dev/null
+}
+
+# Rows the diagnosis occupies, its leading blank included.
+media_diagnosis_rows() {
+  local diagnosis="$1"
+
+  if [[ -z $diagnosis ]]; then
+    printf '0\n'
+  else
+    printf '%s\n' "$(( $(grep -c '' <<<"$diagnosis") + 1 ))"
+  fi
+}
+
+render_media_diagnosis() {
+  local diagnosis="$1" line first=1
+
+  [[ -n $diagnosis ]] || return 0
+  blank_line
+  while IFS= read -r line; do
+    # A blank line inside the diagnosis is deliberate: it separates what
+    # happened from what to do about it, so it is drawn rather than skipped.
+    if [[ -z $line ]]; then
+      blank_line
+      continue
+    fi
+    if (( first )); then
+      center "${RED}$(truncate_for_width "$line" "$CONTENT_WIDTH")${RESET}" "$CONTENT_WIDTH"
+      first=0
+    else
+      center "$(truncate_for_width "$line" "$CONTENT_WIDTH")" "$CONTENT_WIDTH"
+    fi
+  done <<<"$diagnosis"
+}
+
+render_failure() {
+  local status="$1" state_summary="${2:-}" media_diagnosis="${3:-}" line
+  printf '%s%s' "$SHOW_CURSOR" "$CLEAR"
+  blank_line
+  render_logo
+  blank_line
+  center "${RED}Omarchy installation stopped${RESET}" "$CONTENT_WIDTH"
+  center "Installer exited with status $status" "$CONTENT_WIDTH"
+
+  render_media_diagnosis "$media_diagnosis"
+
+  if [[ -n $state_summary ]]; then
+    blank_line
+    while IFS= read -r line; do
+      [[ -n $line ]] || continue
+      center "${DIM}$(truncate_for_width "$line" "$CONTENT_WIDTH")${RESET}" "$CONTENT_WIDTH"
+    done <<<"$state_summary"
+  fi
+
+  blank_line
+  render_failure_log_tail "$(media_diagnosis_rows "$media_diagnosis")"
+  blank_line
+  center "${DIM}Get help at https://omarchy.org/discord${RESET}" "$CONTENT_WIDTH"
+  blank_line
+}
+
+failure_menu() {
+  local choice uploader
+
+  [[ ${OMARCHY_UI_FAILURE_ACTION:-} == "exit" ]] && return 0
+  # The failure screen and log tail have already rendered; exit with the
+  # installer's status instead of blocking on a menu nobody can answer.
+  interactive || return 0
+
+  while true; do
+    uploader=""
+    uploader=$(find_log_uploader || true)
+    if [[ -n $uploader ]]; then
+      choice=$(gum choose \
+        --height 6 \
+        --header "What would you like to do?" \
+        "Upload log for support" \
+        "View full log" \
+        "Drop to shell" \
+        "Reboot" \
+        "Power off" \
+        <"$TTY_PATH" 2>"$TTY_PATH") || choice="Drop to shell"
+    else
+      choice=$(gum choose \
+        --height 5 \
+        --header "What would you like to do?" \
+        "View full log" \
+        "Drop to shell" \
+        "Reboot" \
+        "Power off" \
+        <"$TTY_PATH" 2>"$TTY_PATH") || choice="Drop to shell"
+    fi
+
+    case "$choice" in
+      "Upload log for support")
+        upload_failure_log
+        render_failure "${failure_status:-1}" "${failure_summary:-}" "${failure_media_diagnosis:-}" >"$TTY_PATH" 2>/dev/null || true
+        ;;
+      "View full log")
+        view_failure_log
+        render_failure "${failure_status:-1}" "${failure_summary:-}" "${failure_media_diagnosis:-}" >"$TTY_PATH" 2>/dev/null || true
+        ;;
+      "Reboot")
+        reboot 2>/dev/null || systemctl reboot 2>/dev/null || true
+        ;;
+      "Power off")
+        poweroff 2>/dev/null || systemctl poweroff 2>/dev/null || true
+        ;;
+      "Drop to shell"|"")
+        return 0
+        ;;
+    esac
+  done
+}
+
+sanitize_child_output() {
+  # Archinstall is only a library subsystem in Omarchy's installer. Its own
+  # post-install success/reboot banner can be buffered until process exit and
+  # appear after an Omarchy failure, which makes the unified log contradictory.
+  # Keep that third-party banner out of Omarchy's support log; the raw
+  # archinstall log is still uploaded separately by omarchy-upload-log.
+  sed -u \
+    -e $'s/\x1b\\[[0-9;?]*[A-Za-z]//g' \
+    -e '/^Activating systemd-timesyncd for time synchronization using Arch Linux and ntp.org NTP servers$/d' \
+    -e '/^Enabling service systemd-timesyncd$/d' \
+    -e '/^Setting password for root$/d' \
+    -e '/^Updating \/mnt\/etc\/fstab$/d' \
+    -e '/^Syncing the system\.\.\.$/d' \
+    -e '/^Installation completed without any errors\.$/d' \
+    -e '/^Log files temporarily available at \/var\/log\/archinstall\.$/d' \
+    -e '/^You may reboot when ready\.$/d'
+}
+
+launch_child() {
+  mkdir -p "$(dirname "$LOG_FILE")"
+  # Child is non-interactive. All visible UI belongs to this supervisor.
+  PYTHONUNBUFFERED=1 setsid "${INSTALL_CMD[@]}" </dev/null > >(sanitize_child_output >>"$LOG_FILE") 2>&1 &
+  child_pid=$!
+  child_pgid=$child_pid
+}
+
+[[ -e $TTY_PATH ]] || exit 2
+printf '%s' "$HIDE_CURSOR" >"$TTY_PATH"
+render_static >"$TTY_PATH"
+set_now
+DASH_T0=$NOW
+PHASE_T0=$NOW
+PKG_LAST_CHANGE=$NOW
+launch_child
+
+while jobs -pr | grep -qx "$child_pid"; do
+  render_dynamic >"$TTY_PATH" 2>/dev/null || true
+  sleep 0.5
+done
+
+set +e
+wait "$child_pid"
+status=$?
+set -e
+child_pid=""
+child_pgid=""
+
+dashboard_log "installer child exited with status $status"
+
+if (( status == 0 )); then
+  # finished_at lands microseconds before the child exits, so the 0.5s poll
+  # rarely renders a full bar before the finish screen replaces it.
+  render_dynamic >"$TTY_PATH" 2>/dev/null || true
+  sleep 0.4
+fi
+
+if (( status != 0 )); then
+  failure_status="$status"
+  failure_summary=""
+  if [[ -f $STATE_FILE ]]; then
+    failure_summary="$(jq -r '
+      (.current_phase // empty | "last installer phase: \(.)"),
+      ((.phases // []) | map(select(.status == "failed")) | last // empty
+        | "failed phase: \(.name): \(.error)")
+    ' "$STATE_FILE" 2>/dev/null || true)"
+    if [[ -n $failure_summary ]]; then
+      while IFS= read -r line; do
+        [[ -n $line ]] && dashboard_log "$line"
+      done <<<"$failure_summary"
+    fi
+  fi
+  failure_media_diagnosis="$(diagnose_media || true)"
+  render_failure "$failure_status" "$failure_summary" "$failure_media_diagnosis" >"$TTY_PATH" 2>/dev/null || true
+  # Recorded after the screen is drawn, not before: the log tail on that screen
+  # reads this same file, and the diagnosis printed twice reads as two findings.
+  if [[ -n $failure_media_diagnosis ]]; then
+    while IFS= read -r line; do
+      [[ -n $line ]] && dashboard_log "$line"
+    done <<<"$failure_media_diagnosis"
+  fi
+  failure_menu
+  exit "$failure_status"
+fi
+
+# Deferred-provisioning installs finish silently and reboot on their own — the
+# owner completes setup (and sees the send-off) at first boot, so the "Installed
+# Omarchy in ..." celebration and the Reboot Now prompt belong to a direct
+# install only.
+if [[ ${OMARCHY_UI_DEFER_PROVISIONING:-} == "yes" ]]; then
+  printf '%s' "$CLEAR" >"$TTY_PATH" 2>/dev/null || true
+  [[ ${OMARCHY_UI_AUTO_REBOOT:-} == "no" ]] && exit 0
+  reboot 2>/dev/null || systemctl reboot 2>/dev/null || true
+  exit 0
+fi
+
+set +e
+render_finish
+finish_render_status=$?
+set -e
+if (( finish_render_status != 0 )); then
+  dashboard_log "finish screen render failed with status $finish_render_status; using fallback"
+  {
+    printf '%s%s' "$SHOW_CURSOR" "$CLEAR"
+    printf '\nFinished installing\n\n'
+  } >"$TTY_PATH" 2>/dev/null || true
+fi
+
+if reboot_prompt; then
+  if [[ ${OMARCHY_UI_AUTO_REBOOT:-} == "no" ]]; then
+    exit 0
+  fi
+  printf '%s' "$CLEAR" >"$TTY_PATH" 2>/dev/null || true
+  reboot 2>/dev/null || systemctl reboot 2>/dev/null || true
+fi
+
+exit 0

configs/airootfs/usr/local/bin/omarchy-install-diagnose-media

@@ -0,0 +1,124 @@
+#!/bin/bash
+#
+# Say whether an install failure was the install medium, and say it in words
+# that name the fix.
+#
+# The ISO's offline mirror is bind-mounted onto the target's package cache for
+# the duration of pacstrap (see _mount_offline_package_cache), so a package
+# pacman calls corrupt under that path is a byte that came off the medium --
+# nothing else ever writes there. That much is certain, and it is the part
+# worth saying out loud, because the failure screen otherwise ends at "get help
+# at discord" with the word USB nowhere on it.
+#
+# What is not certain is which way the medium failed. Bytes written wrong and
+# bytes read wrong produce the same checksum mismatch, and pacstrap runs with
+# --noconfirm, which answers yes to pacman's "delete it?" and unlinks the
+# package through the bind mount before anything here can weigh it. So the
+# usual verdict names the medium and gives both remedies in the order worth
+# trying. When the package does survive, its checksum in the mirror's database
+# tells the two apart, and then this says which.
+#
+# Prints the diagnosis on stdout, one line per line, headline first. Exits 1
+# with no output when there is nothing here to diagnose, so the caller can ask
+# unconditionally.
+
+set -uo pipefail
+
+TARGET_PACKAGE_CACHE="${OMARCHY_TARGET_PACKAGE_CACHE:-/mnt/var/cache/pacman/pkg}"
+OFFLINE_MIRROR="${OMARCHY_OFFLINE_MIRROR:-/var/cache/omarchy/mirror/offline}"
+
+if (( $# == 0 )); then
+  echo "Usage: omarchy-install-diagnose-media <log-file>..." >&2
+  exit 2
+fi
+
+# Only packages under the target cache count. A corrupt package anywhere else
+# was not read off this ISO, and guessing wrong here sends someone to buy a USB
+# stick they did not need.
+corrupt_package() {
+  local log match package=""
+
+  for log in "$@"; do
+    [[ -f $log ]] || continue
+    match=$(sed -n "s|.*${TARGET_PACKAGE_CACHE}/\([^ ]*\) is corrupted.*|\1|p" "$log" | tail -n 1)
+    [[ -n $match ]] && package="$match"
+  done
+
+  printf '%s' "$package"
+}
+
+expected_checksum() {
+  local package="$1" reader
+
+  [[ -f $OFFLINE_MIRROR/offline.db ]] || return 1
+
+  if command -v bsdtar >/dev/null 2>&1; then
+    reader=(bsdtar -xOf "$OFFLINE_MIRROR/offline.db")
+  else
+    reader=(tar -xOzf "$OFFLINE_MIRROR/offline.db")
+  fi
+
+  # repo-add writes %FILENAME% before %SHA256SUM% in every desc record, so the
+  # name in hand when a checksum arrives is the name it belongs to. The wanted
+  # name comes through the environment rather than -v, which would read a
+  # backslash in a package version as an escape sequence.
+  "${reader[@]}" 2>/dev/null | want="$package" awk '
+    BEGIN { want = ENVIRON["want"] }
+    $0 == "%FILENAME%" { getline name; next }
+    $0 == "%SHA256SUM%" { getline sha; if (name == want) { print sha; exit } }
+  '
+}
+
+actual_checksum() {
+  local package="$1" sum
+
+  [[ -f $OFFLINE_MIRROR/$package ]] || return 1
+  sum=$(sha256sum "$OFFLINE_MIRROR/$package" 2>/dev/null) || return 1
+  printf '%s' "${sum%% *}"
+}
+
+package=$(corrupt_package "$@")
+if [[ -z $package ]]; then
+  exit 1
+fi
+
+# The name reaches a terminal, and a package version may legally hold a
+# backslash that the renderer would read as an escape. Strip anything a package
+# filename has no business containing before printing it.
+display_package="${package//[^A-Za-z0-9._+:@%-]/}"
+
+expected=$(expected_checksum "$package")
+actual=$(actual_checksum "$package")
+
+# The package name goes on a line of its own throughout. Names run past fifty
+# characters and the screen is only as wide as the logo, so a name sharing a
+# line with the sentence that explains it truncates the explanation away. The
+# blank line after it separates what happened from what to do about it.
+if [[ -n $expected && -n $actual ]]; then
+  if [[ $expected == "$actual" ]]; then
+    # Intact now, so the bytes were misread rather than written wrong, and
+    # re-downloading fixes neither of the things that could have done it.
+    echo "The install medium was misread"
+    echo "This package is intact on this ISO, so the download and the write were fine:"
+    echo "$display_package"
+    echo
+    echo "Try another USB port or another stick, and test this machine's memory"
+  else
+    echo "The install medium is damaged"
+    echo "This package no longer matches the checksum it was built with:"
+    echo "$display_package"
+    echo
+    echo "Re-download the ISO, verify it with sha256sum, and write the USB again"
+    echo "If a verified ISO fails here too, the USB stick itself is the problem"
+  fi
+  exit 0
+fi
+
+# The usual case: pacman deleted the package it rejected, so the medium is the
+# answer but the manner of its failure is not recoverable from here.
+echo "The install medium is damaged or misread"
+echo "pacman rejected this package, read straight off this ISO:"
+echo "$display_package"
+echo
+echo "Verify your download with sha256sum, then write the USB again"
+echo "If the download verifies, the stick or this machine's memory is at fault"

configs/airootfs/usr/local/bin/omarchy-iso-cleanup-disk

@@ -0,0 +1,47 @@
+#!/bin/bash
+#
+# Clean up any holders / mounts / LVM / crypt devices on the install disk
+# before archinstall starts wiping. Idempotent — called once per install attempt
+# from the orchestrator's cleanup_disk phase.
+#
+# Ported verbatim from .automated_script.sh's cleanup_install_disk(). Kept in
+# bash because lsblk / findmnt / lvm / cryptsetup are all easier to drive
+# here than from Python.
+
+set -uo pipefail
+
+if [[ ${1:-} == --protected ]]; then
+  target="${2:-}"
+  [[ -n $target ]] || { echo "Usage: $0 --protected <target>" >&2; exit 1; }
+  findmnt -R "$target" >/dev/null 2>&1 && umount -R "$target" || true
+  exit 0
+fi
+
+disk="${1:-}"
+[[ -n $disk && -b $disk ]] || { echo "Need a block device argument; got '$disk'" >&2; exit 1; }
+
+echo "Cleaning up existing holders on install disk: $disk"
+findmnt -R /mnt >/dev/null && umount -R /mnt || true
+
+while read -r dev; do
+  [[ -b $dev ]] || continue
+  swapoff "$dev" 2>/dev/null || true
+  while read -r target; do
+    [[ -n $target ]] && umount "$target" 2>/dev/null || true
+  done < <(findmnt -rn -S "$dev" -o TARGET 2>/dev/null || true)
+done < <(lsblk -rnpo PATH "$disk")
+
+while read -r dev type; do
+  [[ $type == disk || $type == part || $type == crypt ]] || continue
+  while read -r vg; do
+    [[ -n $vg ]] && vgchange -an "$vg" 2>/dev/null || true
+  done < <(pvs --noheadings -o vg_name "$dev" 2>/dev/null | awk '{$1=$1; print}' | sort -u)
+done < <(lsblk -rnpo PATH,TYPE "$disk")
+
+while read -r dev type; do
+  [[ $type == crypt ]] && cryptsetup close "$dev" 2>/dev/null || true
+done < <(lsblk -rnpo PATH,TYPE "$disk")
+
+blockdev --flushbufs "$disk" 2>/dev/null || true
+partprobe "$disk" 2>/dev/null || true
+udevadm settle || true

configs/airootfs/usr/local/bin/omarchy-iso-install

@@ -0,0 +1,27 @@
+#!/bin/bash
+#
+# Live-ISO entry point for the Omarchy install orchestrator. Invoked from
+# /root/.automated_script.sh after the configurator wizard has produced its
+# user_*.json / user_*.txt files. The outer shim owns install logging.
+
+set -eEo pipefail
+
+# Parse our args; convert to env vars before exec'ing Python so archinstall's
+# own argparse (which runs at module import time inside the orchestrator)
+# doesn't choke on flags it doesn't recognize.
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --config)               export OMARCHY_INSTALL_CONFIG="$2"; shift 2 ;;
+    --creds)                export OMARCHY_INSTALL_CREDS="$2"; shift 2 ;;
+    --full-name-file)       export OMARCHY_INSTALL_FULL_NAME_FILE="$2"; shift 2 ;;
+    --email-file)           export OMARCHY_INSTALL_EMAIL_FILE="$2"; shift 2 ;;
+    --encrypt-file)         export OMARCHY_INSTALL_ENCRYPT_FILE="$2"; shift 2 ;;
+    --authorized-keys-file) export OMARCHY_INSTALL_AUTHORIZED_KEYS_FILE="$2"; shift 2 ;;
+    --tailscale-authkey-file) export OMARCHY_INSTALL_TAILSCALE_AUTHKEY_FILE="$2"; shift 2 ;;
+    --defer-provisioning-file)             export OMARCHY_INSTALL_DEFER_PROVISIONING_FILE="$2"; shift 2 ;;
+    *)                      echo "omarchy-iso-install: unknown arg $1" >&2; exit 2 ;;
+  esac
+done
+
+cd /usr/share/omarchy-iso
+exec python -m orchestrator.main

configs/airootfs/usr/share/omarchy-iso/disk-partitioning.sh

@@ -0,0 +1,131 @@
+# Disk partitioning helpers, shared by the ISO configurator and its tests.
+#
+# The rule here is: never predict a partition number. parted fills the lowest
+# free GPT slot, not "highest existing + 1", so any disk whose numbering has a
+# hole — exactly what deleting a partition to free space leaves behind, which
+# is what our own partition tool tells the user to do — hands back a number we
+# did not choose. Everything below reads back what was actually created.
+#
+# Sourced, not executed. The configurator defines abort() and
+# disk_abort_hook(); tests get the plain fallbacks.
+
+# Partitions this run created, in creation order. rollback_created_parts()
+# undoes exactly these and nothing else.
+created_parts=()
+
+# Set by create_partition() instead of being printed: a command substitution
+# would run it in a subshell and lose the created_parts bookkeeping.
+created_partition_number=""
+
+# Compute partition device path, handling NVMe/mmcblk's pN naming.
+partition_path() {
+  local _disk="$1" _num="$2"
+  if [[ "$_disk" == *nvme* || "$_disk" == *mmcblk* ]]; then
+    echo "${_disk}p${_num}"
+  else
+    echo "${_disk}${_num}"
+  fi
+}
+
+# Partition numbers as the on-disk GPT reports them. parted rather than lsblk
+# on purpose: this is the table parted itself is about to modify, so discovery
+# never depends on the kernel having re-read the partition table yet — and the
+# same code works against an image file in tests, where lsblk sees nothing.
+partition_numbers() {
+  parted -ms "$1" unit B print 2>/dev/null | tail -n +3 | cut -d: -f1
+}
+
+partition_size_bytes() {
+  parted -ms "$1" unit B print 2>/dev/null |
+    awk -F: -v n="$2" '$1 == n { gsub(/B/, "", $4); print $4; exit }'
+}
+
+# Fail loudly. The former version looped over sleep and returned its status,
+# so a device that never appeared was indistinguishable from one that did.
+wait_for_device() {
+  local i
+  for i in $(seq 1 10); do
+    [[ -b "$1" ]] && return 0
+    udevadm settle 2>/dev/null || true
+    sleep 1
+  done
+  return 1
+}
+
+_disk_abort() {
+  if declare -F disk_abort_hook >/dev/null; then
+    disk_abort_hook "$1"
+  elif declare -F abort >/dev/null; then
+    abort "$1"
+  fi
+  echo "Error: $1" >&2
+  exit 1
+}
+
+# Run a disk-writing command, fold its stderr into stdout, and abort on a
+# non-zero exit. The fold matters: .automated_script.sh tees stdout into
+# /var/log/omarchy-install.log but sends stderr straight to the tty (gum draws
+# its TUI there), so an unwrapped failure leaves no trace in the log the user
+# uploads — and the configurator's next screen clears it off the display too.
+disk_step() {
+  local desc="$1"
+  shift
+  local output status=0
+  output=$("$@" 2>&1) || status=$?
+  [[ -n $output ]] && printf '%s\n' "$output"
+  (( status == 0 )) && return 0
+  _disk_abort "$desc failed (exit $status)"
+}
+
+# Create one partition and report the number parted actually assigned.
+# Returns non-zero without touching created_parts if anything looks wrong;
+# the caller decides how loudly to fail.
+create_partition() {
+  local disk="$1" start="$2" end="$3" fstype="$4" name="$5"
+  local before after num actual want tolerance
+
+  created_partition_number=""
+
+  # Lexicographic sort on both sides: comm needs its inputs ordered the same
+  # way it compares them, and `sort -n` (1, 2, 10) is not that order.
+  before=$(partition_numbers "$disk" | sort)
+
+  parted --script "$disk" mkpart primary "$fstype" "${start}B" "${end}B" || return 1
+  partprobe "$disk" 2>/dev/null || true
+  udevadm settle 2>/dev/null || true
+
+  after=$(partition_numbers "$disk" | sort)
+  num=$(comm -13 <(printf '%s\n' "$before") <(printf '%s\n' "$after") | head -1)
+  [[ -n $num ]] || return 1
+
+  # The number must be genuinely new. This is the safety property that keeps a
+  # numbering mistake from ever formatting a partition somebody else is using;
+  # it is cheaper and more reliable than sniffing the target for signatures,
+  # which would false-positive on remnants left in freed space.
+  grep -qx "$num" <<<"$before" && return 1
+
+  actual=$(partition_size_bytes "$disk" "$num")
+  [[ -n $actual ]] || return 1
+  want=$((end - start))
+  tolerance=$((1024 * 1024))
+  (( actual >= want - tolerance && actual <= want + tolerance )) || return 1
+
+  parted --script "$disk" name "$num" "$name" || true
+
+  created_parts+=("$num")
+  created_partition_number="$num"
+}
+
+# Undo the partitions this run created, highest number first. Scoped strictly
+# to created_parts: without this, a failed install leaves the user's freed
+# space occupied by orphans, and the retry reports "not enough free space"
+# with no way to connect that to what just happened.
+rollback_created_parts() {
+  local disk="$1" n
+  (( ${#created_parts[@]} > 0 )) || return 0
+  for n in $(printf '%s\n' "${created_parts[@]}" | sort -rn); do
+    parted --script "$disk" rm "$n" >/dev/null 2>&1 || true
+  done
+  partprobe "$disk" 2>/dev/null || true
+  created_parts=()
+}

configs/airootfs/usr/share/omarchy-iso/orchestrator/archinstall_adapter.py

@@ -0,0 +1,246 @@
+"""Thin compatibility wall around the archinstall Python library.
+
+ONLY this module imports from archinstall. Everything else uses these helpers.
+If archinstall's API churns, the blast radius is contained here.
+
+Tested against archinstall 4.4 (Python 3.14).
+
+The canonical call sequence (mirrored from archinstall.scripts.guided.py) is:
+
+    FilesystemHandler(disk_config).perform_filesystem_operations()
+    with Installer(mountpoint, disk_config, kernels=, silent=) as inst:
+        # guided.py:84-85 SKIPS this for DiskLayoutType.Pre_mount — pre-mounted
+        # configs do their own mounting before the Installer context opens.
+        if disk_config.config_type != DiskLayoutType.Pre_mount:
+            inst.mount_ordered_layout()
+        inst.sanity_check(offline=, skip_ntp=, skip_wkd=)
+        inst.generate_key_files()                     # encrypted only
+        inst.set_mirrors(handler, mirror_config, on_target=False)
+        inst.minimal_installation(...)                # base + linux pacstrap
+        inst.set_mirrors(handler, mirror_config, on_target=True)
+        inst.setup_swap(algo=...)
+        inst.create_users(users)
+        inst.add_additional_packages(packages)
+        inst.set_timezone(tz)
+        inst.activate_time_synchronization()
+        inst.set_user_password(root_user)
+        inst.enable_service(services)
+        inst.genfstab()
+
+Our orchestrator installs Omarchy's Limine files directly instead of invoking
+archinstall's bootloader helper, so EFI paths and efibootmgr labels are ours
+from the start.
+"""
+
+from __future__ import annotations
+
+import importlib
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+# Imports are top-level so a missing/incompatible archinstall surfaces at
+# orchestrator startup, not deep inside a phase.
+from archinstall.lib.args import ArchConfig, ArchConfigHandler
+from archinstall.lib.authentication.authentication_handler import AuthenticationHandler
+from archinstall.lib.disk.filesystem import FilesystemHandler
+from archinstall.lib.disk.utils import get_parent_device_path, get_unique_path_for_device, udev_sync
+from archinstall.lib.hardware import SysInfo
+from archinstall.lib.installer import Installer
+from archinstall.lib.mirror.mirror_handler import MirrorListHandler
+from archinstall.lib.models import Bootloader
+from archinstall.lib.models.device import DiskLayoutType, EncryptionType
+from archinstall.lib.models.users import User
+
+from .ui import info
+
+
+def load_arch_config(config_path: Path, creds_path: Path) -> ArchConfigHandler:
+    """Build an ArchConfigHandler from on-disk JSON.
+
+    archinstall's ArchConfigHandler reads --config / --creds from sys.argv
+    via argparse at construction time (lib/args.py:_parse_args). It does
+    NOT consult env vars for these paths. We can't pass them on our real
+    argv because the wrapper strips them before exec'ing Python (so other
+    archinstall arg-parsing code doesn't choke on our flags), so we hand
+    archinstall a synthetic argv just for this call.
+    """
+    import sys
+    saved_argv = sys.argv
+    sys.argv = [
+        saved_argv[0] if saved_argv else "omarchy-iso-install",
+        "--config", str(config_path),
+        "--creds", str(creds_path),
+    ]
+    try:
+        return ArchConfigHandler()
+    finally:
+        sys.argv = saved_argv
+
+
+def make_mirror_handler(offline: bool = True) -> MirrorListHandler:
+    return MirrorListHandler(offline=offline, verbose=False)
+
+
+def perform_filesystem_operations(arch_config: ArchConfig) -> None:
+    """Partition, format, encrypt. archinstall's FilesystemHandler is its own
+    object (separate from Installer) so we run it before opening the
+    Installer context manager.
+
+    parted's partition-table commit races udev: the disk wipe and the first
+    BLKPG partition registration trigger probes that briefly hold the disk
+    open, and the kernel then refuses to register the remaining partitions
+    (_ped.IOException: "Partition(s) ... have been written, but we have been
+    unable to inform the kernel"). The table is written correctly when that
+    happens — only the kernel's view is stale — so settle udev and redo the
+    operations. The wipe/partition/format sequence is idempotent."""
+    if not arch_config.disk_config:
+        raise RuntimeError("disk_config missing from arch config")
+
+    handler = FilesystemHandler(arch_config.disk_config)
+
+    # archinstall's perform_filesystem_operations defaults to a ~4.5s
+    # "5...4...3...2...1" countdown (FilesystemHandler._final_warning) before it
+    # wipes the disk. That warning is meant for its interactive TUI; in our
+    # orchestrated install it renders nowhere and just sleeps. Suppress it when
+    # the running archinstall still takes the flag — newer releases dropped both
+    # the countdown and the parameter, so only pass it when it's accepted.
+    fs_kwargs = (
+        {"show_countdown": False}
+        if _method_accepts(handler.perform_filesystem_operations, "show_countdown")
+        else {}
+    )
+
+    attempts = 3
+    for attempt in range(1, attempts + 1):
+        udev_sync()
+        try:
+            handler.perform_filesystem_operations(**fs_kwargs)
+            return
+        except Exception as exc:
+            if attempt == attempts or "unable to inform the kernel" not in str(exc):
+                raise
+            info(f"› partition commit lost a udev race (attempt {attempt}/{attempts}); retrying")
+
+
+@contextmanager
+def open_installer(
+    arch_config: ArchConfig,
+    mountpoint: Path,
+    silent: bool = True,
+) -> Iterator[Installer]:
+    """Yield an open Installer; ensures __exit__ runs even on exception so
+    /mnt is left clean for a retry."""
+    if not arch_config.disk_config:
+        raise RuntimeError("disk_config missing from arch config")
+    with Installer(
+        mountpoint,
+        arch_config.disk_config,
+        kernels=arch_config.kernels,
+        silent=silent,
+    ) as installer:
+        yield installer
+
+
+def is_encrypted(arch_config: ArchConfig) -> bool:
+    disk = arch_config.disk_config
+    if not disk or not disk.disk_encryption:
+        return False
+    return disk.disk_encryption.encryption_type != EncryptionType.NO_ENCRYPTION
+
+
+def is_pre_mount(arch_config: ArchConfig) -> bool:
+    return bool(
+        arch_config.disk_config
+        and arch_config.disk_config.config_type == DiskLayoutType.Pre_mount
+    )
+
+
+def bootloader_enabled(arch_config: ArchConfig) -> bool:
+    bl = arch_config.bootloader_config
+    return bool(bl and bl.bootloader != Bootloader.NO_BOOTLOADER)
+
+
+def is_limine(arch_config: ArchConfig) -> bool:
+    bl = arch_config.bootloader_config
+    return bool(bl and bl.bootloader == Bootloader.Limine)
+
+
+def has_uefi() -> bool:
+    return SysInfo.has_uefi()
+
+
+def parent_device_path(dev_path: Path) -> Path:
+    return get_parent_device_path(dev_path)
+
+
+def unique_device_path(dev_path: Path) -> Path | None:
+    return get_unique_path_for_device(dev_path)
+
+
+def _application_handler():
+    """Return archinstall's application handler across archinstall versions."""
+    module = importlib.import_module("archinstall.lib.applications.application_handler")
+    handler = getattr(module, "application_handler", None)
+    if handler is not None and callable(getattr(handler, "install_applications", None)):
+        return handler
+
+    handler_class = getattr(module, "ApplicationHandler", None)
+    if handler_class is None:
+        raise RuntimeError("archinstall application handler is unavailable")
+    try:
+        handler = handler_class()
+    except TypeError as exc:
+        raise RuntimeError("archinstall ApplicationHandler cannot be constructed") from exc
+    if not callable(getattr(handler, "install_applications", None)):
+        raise RuntimeError("archinstall ApplicationHandler has no install_applications method")
+    return handler
+
+
+def _method_accepts(method, name: str) -> bool:
+    """Return whether a bound archinstall method accepts a named argument.
+
+    Do not use inspect.signature here: Python 3.14 may evaluate archinstall's
+    lazy annotations, and some archinstall releases annotate with names that are
+    only imported under TYPE_CHECKING.
+    """
+    fn = getattr(method, "__func__", method)
+    code = getattr(fn, "__code__", None)
+    if code is None:
+        return True
+
+    positional = code.co_varnames[:code.co_argcount]
+    kwonly = code.co_varnames[code.co_argcount:code.co_argcount + code.co_kwonlyargcount]
+    return name in (*positional, *kwonly)
+
+
+def _method_accepts_users(method) -> bool:
+    return _method_accepts(method, "users")
+
+
+def install_applications(installer: Installer, arch_config: ArchConfig) -> None:
+    """Install archinstall application selections such as PipeWire audio.
+
+    The configurator still writes archinstall's audio_config. We own phase
+    ordering now, but should not silently drop archinstall's hardware-aware
+    application installers (SOF/ALSA firmware detection, PipeWire packages,
+    Bluetooth selections, etc.).
+    """
+    app_config = arch_config.app_config
+    if not app_config:
+        return
+
+    users = arch_config.auth_config.users if arch_config.auth_config else None
+    handler = _application_handler()
+    install_applications_method = handler.install_applications
+    if _method_accepts_users(install_applications_method):
+        install_applications_method(installer, app_config, users)
+    else:
+        install_applications_method(installer, app_config)
+
+
+def root_user(arch_config: ArchConfig) -> User | None:
+    auth = arch_config.auth_config
+    if not auth or not auth.root_enc_password:
+        return None
+    return User("root", auth.root_enc_password, False)

configs/airootfs/usr/share/omarchy-iso/orchestrator/command.py

@@ -0,0 +1,54 @@
+r"""Reading text out of the commands the installer shells out to.
+
+Firmware and filesystem metadata reach the orchestrator as command output, and
+neither is obliged to be UTF-8: an HP ProBook's NVRAM held a legacy BBS entry
+whose device path began `BBS(HD,\x80\x7f\xff\x04`, efibootmgr printed those
+bytes verbatim, and subprocess's strict text decoding turned a boot entry
+nothing here reads into a failed install.
+
+So capture() replaces what it cannot decode, and the boot-entry parsing that
+reads its output stays tolerant on purpose: an entry's text is its label and its
+device path together, and the junk lives in the path, so refusing one would abort
+the install this exists to let finish. Nothing mangled reaches efibootmgr from
+there either way — only four-digit ASCII boot numbers become arguments, and a
+boot order is filtered through the entries that parsed — so a label that loses a
+byte costs a stale entry left behind rather than a broken system.
+
+An identifier is the other case entirely: require_text() refuses a UUID or a
+device name that came through mangled, because that one is written into fstab and
+the kernel cmdline, or handed to mount.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+REPLACEMENT = "\ufffd"
+
+
+def capture(cmd: list[str], *, check: bool = False) -> subprocess.CompletedProcess:
+    """Run cmd and return it with stdout/stderr decoded, bad bytes replaced."""
+    return subprocess.run(
+        cmd,
+        check=check,
+        capture_output=True,
+        text=True,
+        errors="replace",
+    )
+
+
+def require_text(value: str, what: str) -> str:
+    """Refuse a value the installed system depends on if bytes were replaced in it.
+
+    Validation reads these back from the same command that wrote them, so a
+    mangled UUID agrees with itself and ships a machine that cannot find its
+    root at boot. Stopping here says why while someone is still watching.
+    """
+    if REPLACEMENT in value:
+        raise RuntimeError(f"{what} is not valid text: {value!r}")
+    return value
+
+
+def capture_identifier(cmd: list[str], what: str) -> str:
+    """Capture a single value the installed system will depend on."""
+    return require_text(capture(cmd, check=True).stdout.strip(), what)

configs/airootfs/usr/share/omarchy-iso/orchestrator/context.py

@@ -0,0 +1,210 @@
+"""Install context: parsed configurator output, invocation paths, and a
+mutable `state` dict for objects that live across phases (e.g., the
+archinstall config handler and mirror list handler)."""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class InstallContext:
+    config_path: Path
+    creds_path: Path
+    full_name: str
+    email: str
+    encrypt: bool
+    authorized_keys_path: Path | None
+    tailscale_authkey_path: Path | None
+
+    user_configuration: dict
+    user_credentials: dict
+    arch_config_path: Path
+    omarchy_install: dict[str, Any]
+    defer_provisioning: bool = False
+
+    target: Path = Path("/mnt")
+    omarchy_path: Path = Path("/usr/share/omarchy")
+    state_dir: Path = Path("/run/omarchy-install")
+    log_path: Path = Path("/var/log/omarchy-install.log")
+    target_log_path: Path = Path("/mnt/var/log/omarchy-install.log")
+
+    # Mutable per-run state shared across phases (e.g., 'arch_config_handler',
+    # 'mirror_handler'). Phases populate as needed; later phases read.
+    state: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_env(cls) -> "InstallContext":
+        config_str = os.environ.get("OMARCHY_INSTALL_CONFIG")
+        creds_str = os.environ.get("OMARCHY_INSTALL_CREDS")
+        if not config_str or not creds_str:
+            raise RuntimeError("OMARCHY_INSTALL_CONFIG and OMARCHY_INSTALL_CREDS must be set")
+
+        config_path = Path(config_str)
+        creds_path = Path(creds_str)
+        user_configuration = json.loads(config_path.read_text())
+        omarchy_install = user_configuration.get("omarchy_install") or _default_omarchy_install(user_configuration)
+
+        # Deferred provisioning: the whole system installs but user creation is deferred to
+        # first boot. Selected by the configurator (omarchy_install.defer_provisioning) or by
+        # an `defer-provisioning` marker file on an autoinstall drive, which also replaces the
+        # user_credentials.json requirement.
+        defer_provisioning_marker = _optional_path(os.environ.get("OMARCHY_INSTALL_DEFER_PROVISIONING_FILE"))
+        defer_provisioning = bool(omarchy_install.get("defer_provisioning")) or defer_provisioning_marker is not None
+        omarchy_install["defer_provisioning"] = defer_provisioning
+
+        if creds_path.exists():
+            user_credentials = json.loads(creds_path.read_text())
+        elif defer_provisioning:
+            user_credentials = {"users": []}
+        else:
+            raise RuntimeError(f"credentials file missing: {creds_path}")
+
+        if defer_provisioning:
+            # Deferred provisioning promises no account until first boot. A supplied
+            # credentials file (a rig handing over its LUKS passphrase) must
+            # not smuggle in users or a root password.
+            encryption_password = user_credentials.get("encryption_password")
+            user_credentials = {"users": []}
+            if encryption_password:
+                user_credentials["encryption_password"] = encryption_password
+
+        arch_configuration = dict(user_configuration)
+        arch_configuration.pop("omarchy_install", None)
+
+        if defer_provisioning:
+            # The userless invariant covers the archinstall config too: a
+            # combined/legacy config could carry account authentication that
+            # archinstall would still act on (users, a root password). Strip
+            # every such field so no account is created before first boot.
+            _strip_account_fields(arch_configuration)
+
+        state_dir = Path(os.environ.get("OMARCHY_INSTALL_STATE_DIR", "/run/omarchy-install"))
+        state_dir.mkdir(parents=True, exist_ok=True)
+
+        if defer_provisioning:
+            # Encrypted deferred-provisioning installs have no user password to protect LUKS
+            # with. Generate a throwaway passphrase (staged for first-boot
+            # re-key by the stage_provisioning_state phase) and hand it to archinstall
+            # through both places it may look: the disk_encryption block and
+            # the credentials file.
+            _inject_provisioning_encryption_password(arch_configuration, user_credentials)
+            creds_path = state_dir / "provisioning-user_credentials.json"
+            creds_path.write_text(json.dumps(user_credentials, indent=2) + "\n")
+            creds_path.chmod(0o600)
+
+        arch_config_path = state_dir / "archinstall-user_configuration.json"
+        arch_config_path.write_text(json.dumps(arch_configuration, indent=2) + "\n")
+
+        ctx = cls(
+            config_path=config_path,
+            creds_path=creds_path,
+            full_name=_read_text(os.environ.get("OMARCHY_INSTALL_FULL_NAME_FILE")),
+            email=_read_text(os.environ.get("OMARCHY_INSTALL_EMAIL_FILE")),
+            encrypt=_read_text(os.environ.get("OMARCHY_INSTALL_ENCRYPT_FILE")).lower() in ("true", "yes", "1"),
+            authorized_keys_path=_optional_path(os.environ.get("OMARCHY_INSTALL_AUTHORIZED_KEYS_FILE")),
+            tailscale_authkey_path=_optional_path(os.environ.get("OMARCHY_INSTALL_TAILSCALE_AUTHKEY_FILE")),
+            user_configuration=user_configuration,
+            user_credentials=user_credentials,
+            arch_config_path=arch_config_path,
+            omarchy_install=omarchy_install,
+            defer_provisioning=defer_provisioning,
+            state_dir=state_dir,
+        )
+        disk_config = user_configuration.get("disk_config", {})
+        target_mount = omarchy_install.get("target_mount") or disk_config.get("mountpoint")
+        if target_mount:
+            ctx.target = Path(target_mount)
+        return ctx
+
+    @property
+    def username(self) -> str:
+        users = self.user_credentials.get("users") or []
+        if users:
+            return users[0]["username"]
+        if self.defer_provisioning:
+            return ""
+        raise RuntimeError("user_credentials.json contains no users")
+
+    @property
+    def mode(self) -> str:
+        if mode := self.omarchy_install.get("mode"):
+            return mode
+        cfg_type = self.user_configuration.get("disk_config", {}).get("config_type")
+        return "protected" if cfg_type == "pre_mounted_config" else "full_disk"
+
+    @property
+    def is_protected(self) -> bool:
+        return self.mode == "protected"
+
+
+def _strip_account_fields(arch_configuration: dict) -> None:
+    """Remove every field archinstall reads to create users or set a root
+    password, so it cannot ship a hidden provisioning account.
+    Encryption material lives elsewhere (disk_config.disk_encryption) and is
+    untouched."""
+    for key in ("!users", "!root-password", "root_enc_password", "users"):
+        arch_configuration.pop(key, None)
+
+    auth = arch_configuration.get("auth_config")
+    if isinstance(auth, dict):
+        for key in ("users", "root_enc_password"):
+            auth.pop(key, None)
+
+
+def _inject_provisioning_encryption_password(arch_configuration: dict, user_credentials: dict) -> None:
+    """Ensure an encrypted deferred-provisioning install has a LUKS passphrase archinstall can
+    use. Reuse one the input already carries (an autoinstall rig may supply
+    its own); otherwise generate a throwaway. Mutates the disk_encryption
+    block in place — arch_configuration shares it with user_configuration, so
+    the stage_provisioning_state phase can read the effective passphrase back."""
+    disk_encryption = (arch_configuration.get("disk_config") or {}).get("disk_encryption")
+    if disk_encryption is None:
+        return
+
+    password = disk_encryption.get("encryption_password") or user_credentials.get("encryption_password")
+    if not password:
+        password = secrets.token_urlsafe(24)
+
+    disk_encryption["encryption_password"] = password
+    user_credentials["encryption_password"] = password
+
+
+def _default_omarchy_install(user_configuration: dict) -> dict[str, Any]:
+    disk_config = user_configuration.get("disk_config", {})
+    mode = "protected" if disk_config.get("config_type") == "pre_mounted_config" else "full_disk"
+    return {
+        "mode": mode,
+        "target_mount": disk_config.get("mountpoint") or "/mnt",
+        "boot": {
+            "esp_mount": "/boot",
+            "esp_path": "/EFI/limine",
+            "efi_binary": "limine_x64.efi",
+            "enable_fallback": mode == "full_disk",
+        },
+        "storage": {},
+    }
+
+
+def _optional_path(path: str | None) -> Path | None:
+    """A path the caller always passes but that need not exist. The live ISO
+    passes --authorized-keys-file on every install; only autoinstall drives put
+    a file there."""
+    if not path:
+        return None
+    p = Path(path)
+    return p if p.exists() else None
+
+
+def _read_text(path: str | None) -> str:
+    if not path:
+        return ""
+    p = Path(path)
+    if not p.exists():
+        return ""
+    return p.read_text().strip()

configs/airootfs/usr/share/omarchy-iso/orchestrator/keyboard.py

@@ -0,0 +1,54 @@
+"""Offline target keyboard configuration.
+
+archinstall's set_keyboard_language boots the installed system in a
+systemd-nspawn container just to run localectl. systemd-firstboot --root
+produces the part of that output Omarchy actually consumes — KEYMAP for the
+console plus the XKB* settings in vconsole.conf that omarchy's
+detect-keyboard-layout.sh copies into Hyprland's kb_layout — without booting
+anything. The Xorg 00-keyboard.conf that localectl also writes is not
+generated: nothing on an Omarchy system reads it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .command import capture
+
+
+def configure_keyboard(target: Path, language: str) -> bool:
+    """Write the console keymap into a mounted target without booting it.
+
+    Returns False for layouts localectl doesn't know, matching archinstall:
+    warn and keep the default. Every layout the configurator offers is known;
+    the guard is for the kb_layout an autoinstall drive can name freely.
+    """
+    if not language.strip():
+        return True
+
+    result = capture(["localectl", "--no-pager", "list-keymaps"])
+    if result.returncode != 0:
+        detail = result.stderr.strip() or "localectl returned an error"
+        raise RuntimeError(f"Unable to list keyboard layouts: {detail}")
+    if language.lower() not in {layout.lower() for layout in result.stdout.splitlines()}:
+        return False
+
+    # systemd-firstboot --force rewrites vconsole.conf wholesale, dropping the
+    # FONT= line archinstall's set_vconsole wrote earlier.
+    vconsole_path = target / "etc" / "vconsole.conf"
+    font = None
+    if vconsole_path.exists():
+        font = next(
+            (line for line in vconsole_path.read_text().splitlines() if line.startswith("FONT=")),
+            None,
+        )
+
+    result = capture(["systemd-firstboot", f"--root={target}", f"--keymap={language}", "--force"])
+    if result.returncode != 0:
+        detail = result.stderr.strip() or "systemd-firstboot returned an error"
+        raise RuntimeError(f"Unable to configure keyboard layout {language}: {detail}")
+
+    if font:
+        vconsole_path.write_text(vconsole_path.read_text() + font + "\n")
+
+    return True

configs/airootfs/usr/share/omarchy-iso/orchestrator/main.py

@@ -0,0 +1,111 @@
+"""Omarchy install orchestrator.
+
+Single tool that owns the full install phase ordering, with archinstall used as
+a library subsystem (not as the top-level installer).
+
+The live-ISO wrapper consumes CLI args and passes configuration paths via
+OMARCHY_INSTALL_* environment variables before Python starts. This keeps
+archinstall's import-time CLI parsing from seeing Omarchy-specific flags.
+"""
+
+from __future__ import annotations
+
+import sys
+from .context import InstallContext
+from .phases import PhaseError, run
+from .ui import error, info
+
+
+def build_phases(ctx: InstallContext):
+    """Phase order. Each entry is (display name, callable taking InstallContext).
+
+    The ordering is the whole point of this orchestrator: package-install
+    hooks (limine-mkinitcpio-hook, in particular) and useradd happen at
+    points where their prerequisites are guaranteed to be in place.
+
+    Full-disk and protected installs use the same phase sequence. The
+    configurator only changes the JSON input: full-disk asks archinstall to
+    create/mount the layout, while protected provides an already-mounted target
+    and the partition details Omarchy needs for boot/fstab generation.
+    """
+    from .phases_impl import (
+        prepare_live,
+        prepare_install_target,
+        arch_install_system,
+        configure_hibernation,
+        run_system_finalizer,
+        stage_provisioning_state,
+        finalize_limine_boot,
+        run_chroot_finalizer,
+        configure_dns_resolver,
+        configure_login,
+        configure_ssh_access,
+        configure_tailscale,
+        validate_boot,
+        create_factory_snapshot,
+    )
+
+    return [
+        ("Preparing live environment", prepare_live),
+        ("Preparing install target",   prepare_install_target),
+        ("Installing Arch + Omarchy",  arch_install_system),
+        ("Configuring hibernation",    configure_hibernation),
+        ("Configuring system",         run_system_finalizer),
+        # Before finalize_limine_boot: the deferred-provisioning cryptkey drop-in and keyfile
+        # must be in place for the final UKI build.
+        ("Staging provisioning",          stage_provisioning_state),
+        ("Finalizing Limine boot",     finalize_limine_boot),
+        ("Finalizing user",            run_chroot_finalizer),
+        ("Configuring login",          configure_login),
+        ("Configuring SSH access",     configure_ssh_access),
+        ("Configuring Tailscale",      configure_tailscale),
+        ("Configuring DNS resolver",   configure_dns_resolver),
+        ("Validating boot setup",      validate_boot),
+        ("Creating factory snapshot",  create_factory_snapshot),
+    ]
+
+
+def main() -> int:
+    try:
+        ctx = InstallContext.from_env()
+    except RuntimeError as e:
+        error(f"Configuration error: {e}")
+        return 2
+
+    who = ctx.username or "deferred provisioning (user created at first boot)"
+    info(f"Installing Omarchy for {who} → {ctx.target}")
+
+    from .phases_impl import (
+        boost_cpu_governor,
+        cleanup_bind_mounts,
+        cleanup_protected_state,
+        cleanup_target_hook_masks,
+        restore_cpu_governors,
+    )
+
+    governors = boost_cpu_governor()
+
+    success = False
+    try:
+        try:
+            run(ctx, build_phases(ctx))
+            success = True
+        except PhaseError:
+            error("Installation halted.")
+            return 1
+        except KeyboardInterrupt:
+            error("Installation interrupted.")
+            return 130
+
+        info("Installation complete.")
+        return 0
+    finally:
+        restore_cpu_governors(governors)
+        cleanup_bind_mounts(ctx)
+        cleanup_target_hook_masks(ctx)
+        if not success:
+            cleanup_protected_state(ctx)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

configs/airootfs/usr/share/omarchy-iso/orchestrator/phases.py

@@ -0,0 +1,105 @@
+"""Phase state machine. Each phase is a (name, callable) pair; callables take
+the InstallContext and either return cleanly or raise to abort the install."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import traceback
+from collections.abc import Callable
+from pathlib import Path
+
+from .context import InstallContext
+from .ui import error, info
+
+
+PhaseFn = Callable[[InstallContext], None]
+
+
+class PhaseError(Exception):
+    """Raised when a phase fails. Wrapped with the phase name."""
+
+
+def run(ctx: InstallContext, phases: list[tuple[str, PhaseFn]]) -> None:
+    ctx.state_dir.mkdir(parents=True, exist_ok=True)
+    state_path = ctx.state_dir / "state.json"
+    state = {
+        "started_at": time.time(),
+        # The dashboard counts packages under <target>/var/lib/pacman/local;
+        # publish the path rather than have the UI assume /mnt.
+        "target": str(ctx.target),
+        "total_phases": len(phases),
+        "current_index": 0,
+        "current_phase": "Starting installation",
+        "phases": [],
+    }
+    _write_state(state_path, state)
+
+    for index, (name, fn) in enumerate(phases):
+        state["current_index"] = index
+        state["current_phase"] = name
+        state["phase_started_at"] = time.time()
+        _write_state(state_path, state)
+
+        info(f"› {name}")
+        started = time.time()
+        try:
+            fn(ctx)
+        except Exception as exc:  # noqa: BLE001
+            elapsed = time.time() - started
+            state["phases"].append({
+                "name": name,
+                "status": "failed",
+                "elapsed": elapsed,
+                "error": str(exc),
+            })
+            _write_state(state_path, state)
+
+            error(f"Phase '{name}' failed after {elapsed:.1f}s: {exc}")
+            traceback.print_exc()
+            raise PhaseError(f"phase {name} failed: {exc}") from exc
+
+        elapsed = time.time() - started
+        state["phases"].append({"name": name, "status": "ok", "elapsed": elapsed})
+        _write_state(state_path, state)
+
+    state["current_index"] = max(len(phases) - 1, 0)
+    state["current_phase"] = "Installation complete"
+    state["finished_at"] = time.time()
+    # Expected vs actual for the bar's denominator, so drift is visible in
+    # acceptance runs rather than only by watching a bar creep.
+    state["installed_packages"] = _installed_package_count(ctx.target)
+    state["expected_packages"] = _expected_package_count()
+    _write_state(state_path, state)
+
+    timing_path = ctx.target / "var" / "log" / "omarchy-install-timing.json"
+    timing_path.parent.mkdir(parents=True, exist_ok=True)
+    _write_state(timing_path, state)
+
+
+def _installed_package_count(target: Path) -> int:
+    """Packages libalpm installed into the target — one directory each under
+    local/, which is what the dashboard counts live."""
+    local_db = target / "var" / "lib" / "pacman" / "local"
+    try:
+        with os.scandir(local_db) as entries:
+            return sum(1 for entry in entries if entry.is_dir())
+    except OSError:
+        return 0
+
+
+def _expected_package_count() -> int:
+    path = Path("/usr/share/omarchy-iso/expected-packages")
+    try:
+        return int(path.read_text().split()[0])
+    except (OSError, ValueError, IndexError):
+        return 0
+
+
+def _write_state(path: Path, state: dict) -> None:
+    # Dashboard polls this file while phases update it. Write atomically so the
+    # reader never observes a truncated/partial JSON document and resets UI.
+    tmp = path.with_name(f".{path.name}.tmp")
+    tmp.write_text(json.dumps(state, indent=2, default=str))
+    tmp.replace(path)

configs/airootfs/usr/share/omarchy-iso/orchestrator/ui.py

@@ -0,0 +1,28 @@
+"""Orchestrator progress lines.
+
+These land in the install log, not on a screen: omarchy-install-dashboard owns
+the visible UI, captures the orchestrator's stdout into the support log, and
+strips CSI sequences on the way in. The colouring was therefore never seen by
+anyone, while gum charged a Go process start per line for it. Plain writes keep
+the same indented shape at no cost.
+
+Flush every line: pacstrap and arch-chroot inherit this fd, so buffering here
+would reorder our lines against theirs in the log.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def _emit(text: str) -> None:
+    sys.stdout.write(f"\n    {text}\n")
+    sys.stdout.flush()
+
+
+def info(text: str) -> None:
+    _emit(text)
+
+
+def error(text: str) -> None:
+    _emit(text)

configs/efiboot/loader/entries/01-archiso-x86_64-linux.conf

@@ -2,4 +2,4 @@ title    Omarchy (x86_64, UEFI)
 sort-key 01
 linux    /%INSTALL_DIR%/boot/x86_64/vmlinuz-linux-t2
 initrd   /%INSTALL_DIR%/boot/x86_64/initramfs-linux-t2.img
-options  archisobasedir=%INSTALL_DIR% archisosearchuuid=%ARCHISO_UUID% quiet splash
+options  archisobasedir=%INSTALL_DIR% archisosearchuuid=%ARCHISO_UUID% quiet splash xe.enable_panel_replay=0 initramfs_async=0

configs/grub/grub.cfg

@@ -54,13 +54,13 @@ timeout_style=hidden
 
 menuentry "Omarchy (%ARCH%, ${archiso_platform})" --class arch --class gnu-linux --class gnu --class os --id 'archlinux' {
     set gfxpayload=keep
-    linux /%INSTALL_DIR%/boot/%ARCH%/vmlinuz-linux-t2 archisobasedir=%INSTALL_DIR% archisosearchuuid=%ARCHISO_UUID% quiet splash
+    linux /%INSTALL_DIR%/boot/%ARCH%/vmlinuz-linux-t2 archisobasedir=%INSTALL_DIR% archisosearchuuid=%ARCHISO_UUID% quiet splash xe.enable_panel_replay=0 initramfs_async=0
     initrd /%INSTALL_DIR%/boot/%ARCH%/initramfs-linux-t2.img
 }
 
 menuentry "Omarchy with speakup screen reader (%ARCH%, ${archiso_platform})" --hotkey s --class arch --class gnu-linux --class gnu --class os --id 'archlinux-accessibility' {
     set gfxpayload=keep
-    linux /%INSTALL_DIR%/boot/%ARCH%/vmlinuz-linux-t2 archisobasedir=%INSTALL_DIR% archisosearchuuid=%ARCHISO_UUID% accessibility=on
+    linux /%INSTALL_DIR%/boot/%ARCH%/vmlinuz-linux-t2 archisobasedir=%INSTALL_DIR% archisosearchuuid=%ARCHISO_UUID% accessibility=on xe.enable_panel_replay=0 initramfs_async=0
     initrd /%INSTALL_DIR%/boot/%ARCH%/initramfs-linux-t2.img
 }
 
@@ -104,6 +104,3 @@ menuentry 'System restart' --class reboot --class restart {
 }
 
 
-# GRUB init tune for accessibility
-play 600 988 1 1319 4
-

configs/grub/loopback.cfg

@@ -30,13 +30,13 @@ timeout_style=hidden
 
 menuentry "Omarchy (%ARCH%, ${archiso_platform})" --class arch --class gnu-linux --class gnu --class os --id 'archlinux' {
     set gfxpayload=keep
-    linux /%INSTALL_DIR%/boot/%ARCH%/vmlinuz-linux-t2 archisobasedir=%INSTALL_DIR% img_dev=UUID=${archiso_img_dev_uuid} img_loop="${iso_path}" quiet splash
+    linux /%INSTALL_DIR%/boot/%ARCH%/vmlinuz-linux-t2 archisobasedir=%INSTALL_DIR% img_dev=UUID=${archiso_img_dev_uuid} img_loop="${iso_path}" quiet splash xe.enable_panel_replay=0 initramfs_async=0
     initrd /%INSTALL_DIR%/boot/%ARCH%/initramfs-linux-t2.img
 }
 
 menuentry "Omarchy with speakup screen reader (%ARCH%, ${archiso_platform})" --hotkey s --class arch --class gnu-linux --class gnu --class os --id 'archlinux-accessibility' {
     set gfxpayload=keep
-    linux /%INSTALL_DIR%/boot/%ARCH%/vmlinuz-linux-t2 archisobasedir=%INSTALL_DIR% img_dev=UUID=${archiso_img_dev_uuid} img_loop="${iso_path}" accessibility=on
+    linux /%INSTALL_DIR%/boot/%ARCH%/vmlinuz-linux-t2 archisobasedir=%INSTALL_DIR% img_dev=UUID=${archiso_img_dev_uuid} img_loop="${iso_path}" accessibility=on xe.enable_panel_replay=0 initramfs_async=0
     initrd /%INSTALL_DIR%/boot/%ARCH%/initramfs-linux-t2.img
 }
 

configs/pacman-offline.conf

@@ -0,0 +1,25 @@
+#
+# /etc/pacman.conf
+#
+# See the pacman.conf(5) manpage for option and repository directives
+[options]
+HoldPkg     = pacman glibc
+Architecture = auto
+NoProgressBar
+ParallelDownloads = 5
+
+# By default, pacman accepts packages signed by keys that its local keyring
+# trusts (see pacman-key and its man page), as well as unsigned packages.
+SigLevel    = Required DatabaseOptional
+LocalFileSigLevel = Optional
+
+# No signature checks for the offline mirror: it ships inside the ISO, whose
+# integrity is already covered by the airootfs sha512 and the ISO signature.
+# "Optional TrustAll" is NOT a bypass — Optional verifies whenever a .sig file
+# exists (they all do), and pacstrap verifies against the LIVE keyring (pacman
+# -r relocates the root but not GpgDir). That made installs depend on archiso's
+# slow boot-time pacman-init.service having finished, which stalled or failed
+# pacstrap on real hardware with "required key missing from keyring".
+[offline]
+SigLevel = Never
+Server = file:///var/cache/omarchy/mirror/offline/

configs/pacman-online-edge.conf

@@ -15,26 +15,21 @@ LocalFileSigLevel = Optional
 
 [core]
 Server = https://mirror.omarchy.org/$repo/os/$arch
-Server = https://mirror.rackspace.com/archlinux/$repo/os/$arch
-Server = https://geo.mirror.pkgbuild.com/$repo/os/$arch
 Include = /etc/pacman.d/mirrorlist
 
 [extra]
 Server = https://mirror.omarchy.org/$repo/os/$arch
-Server = https://mirror.rackspace.com/archlinux/$repo/os/$arch
-Server = https://geo.mirror.pkgbuild.com/$repo/os/$arch
 Include = /etc/pacman.d/mirrorlist
 
 [multilib]
 Server = https://mirror.omarchy.org/$repo/os/$arch
-Server = https://mirror.rackspace.com/archlinux/$repo/os/$arch
-Server = https://geo.mirror.pkgbuild.com/$repo/os/$arch
 Include = /etc/pacman.d/mirrorlist
 
 [omarchy]
 SigLevel = Optional TrustAll
-Server = https://pkgs.omarchy.org/$arch
+Server = https://pkgs.omarchy.org/edge/$arch
 
 [arch-mact2]
+Server = https://mirror.funami.tech/arch-mact2/os/x86_64
 Server = https://github.com/NoaHimesaka1873/arch-mact2-mirror/releases/download/release
 SigLevel = Never

configs/pacman-online-rc.conf

@@ -0,0 +1,35 @@
+#
+# /etc/pacman.conf
+#
+# See the pacman.conf(5) manpage for option and repository directives
+
+[options]
+HoldPkg     = pacman glibc
+Architecture = auto
+ParallelDownloads = 5
+
+# By default, pacman accepts packages signed by keys that its local keyring
+# trusts (see pacman-key and its man page), as well as unsigned packages.
+SigLevel    = Required DatabaseOptional
+LocalFileSigLevel = Optional
+
+[core]
+Server = https://rc-mirror.omarchy.org/$repo/os/$arch
+Include = /etc/pacman.d/mirrorlist
+
+[extra]
+Server = https://rc-mirror.omarchy.org/$repo/os/$arch
+Include = /etc/pacman.d/mirrorlist
+
+[multilib]
+Server = https://rc-mirror.omarchy.org/$repo/os/$arch
+Include = /etc/pacman.d/mirrorlist
+
+[omarchy]
+SigLevel = Optional TrustAll
+Server = https://pkgs.omarchy.org/edge/$arch
+
+[arch-mact2]
+Server = https://mirror.funami.tech/arch-mact2/os/x86_64
+Server = https://github.com/NoaHimesaka1873/arch-mact2-mirror/releases/download/release
+SigLevel = Never

configs/pacman-online-stable.conf

@@ -0,0 +1,35 @@
+#
+# /etc/pacman.conf
+#
+# See the pacman.conf(5) manpage for option and repository directives
+
+[options]
+HoldPkg     = pacman glibc
+Architecture = auto
+ParallelDownloads = 5
+
+# By default, pacman accepts packages signed by keys that its local keyring
+# trusts (see pacman-key and its man page), as well as unsigned packages.
+SigLevel    = Required DatabaseOptional
+LocalFileSigLevel = Optional
+
+[core]
+Server = https://stable-mirror.omarchy.org/$repo/os/$arch
+Include = /etc/pacman.d/mirrorlist
+
+[extra]
+Server = https://stable-mirror.omarchy.org/$repo/os/$arch
+Include = /etc/pacman.d/mirrorlist
+
+[multilib]
+Server = https://stable-mirror.omarchy.org/$repo/os/$arch
+Include = /etc/pacman.d/mirrorlist
+
+[omarchy]
+SigLevel = Optional TrustAll
+Server = https://pkgs.omarchy.org/stable/$arch
+
+[arch-mact2]
+Server = https://mirror.funami.tech/arch-mact2/os/x86_64
+Server = https://github.com/NoaHimesaka1873/arch-mact2-mirror/releases/download/release
+SigLevel = Never

configs/pacman.conf

@@ -1,18 +0,0 @@
-#
-# /etc/pacman.conf
-#
-# See the pacman.conf(5) manpage for option and repository directives
-[options]
-HoldPkg     = pacman glibc
-Architecture = auto
-NoProgressBar
-ParallelDownloads = 5
-
-# By default, pacman accepts packages signed by keys that its local keyring
-# trusts (see pacman-key and its man page), as well as unsigned packages.
-SigLevel    = Required DatabaseOptional
-LocalFileSigLevel = Optional
-
-[offline]
-SigLevel = Optional TrustAll
-Server = file:///var/cache/omarchy/mirror/offline/

configs/profiledef.sh

@@ -10,17 +10,37 @@ install_dir="arch"
 buildmodes=('iso')
 bootmodes=('bios.syslinux' 'uefi.grub')
 arch="x86_64"
-pacman_conf="pacman.conf"
+pacman_conf="pacman-offline.conf"
 airootfs_image_type="squashfs"
-airootfs_image_tool_options=('-comp' 'xz' '-Xbcj' 'x86' '-b' '1M' '-Xdict-size' '1M')
+# Package archives in the offline mirror are already zstd-compressed. Storing
+# them in an outer stream saves little space but makes pacman decompress the
+# outer layer while hashing and extracting every package during installation.
+#
+# Everything else in the live root is zstd rather than xz. Squashfs decompresses
+# on the page-fault path through a single stream (CONFIG_SQUASHFS_DECOMP_SINGLE),
+# where xz manages ~100MB/s against zstd's ~900MB/s, and the live root is read
+# cold on every boot: kernel, plymouth, systemd, python, archinstall, gum. The
+# whole ISO grows well under a percent for it, and dropping the x86 BCJ filter
+# also removes one of the blockers listed in plans/aarch64-support.md.
+airootfs_image_tool_options=(
+  '-comp' 'zstd'
+  '-Xcompression-level' '19'
+  '-b' '1M'
+  '-action' 'uncompressed@subpathname(var/cache/omarchy/mirror/offline)'
+)
 bootstrap_tarball_compression=('zstd' '-c' '-T0' '--auto-threads=logical' '--long' '-19')
 file_permissions=(
   ["/etc/shadow"]="0:0:400"
   ["/root"]="0:0:750"
   ["/root/.automated_script.sh"]="0:0:755"
   ["/root/.gnupg"]="0:0:700"
-  ["/usr/local/bin/choose-mirror"]="0:0:755"
   ["/root/configurator"]="0:0:755"
-  ["/var/cache/omarchy/mirror/offline/"]="0:0:775"
+  ["/usr/local/bin/choose-mirror"]="0:0:755"
+  ["/usr/local/bin/omarchy-cidata-load"]="0:0:755"
+  ["/usr/local/bin/omarchy-iso-cleanup-disk"]="0:0:755"
+  ["/usr/local/bin/omarchy-install-dashboard"]="0:0:755"
+  ["/usr/local/bin/omarchy-install-diagnose-media"]="0:0:755"
+  ["/usr/local/bin/omarchy-iso-install"]="0:0:755"
   ["/usr/local/bin/omarchy-upload-log"]="0:0:755"
+  ["/var/cache/omarchy/mirror/offline/"]="0:0:775"
 )

configs/syslinux/archiso_pxe-linux.cfg

@@ -6,7 +6,7 @@ ENDTEXT
 MENU LABEL Omarchy install medium (x86_64, NBD)
 LINUX ::/%INSTALL_DIR%/boot/x86_64/vmlinuz-linux-t2
 INITRD ::/%INSTALL_DIR%/boot/x86_64/initramfs-linux-t2.img
-APPEND archisobasedir=%INSTALL_DIR% archisosearchuuid=%ARCHISO_UUID% archiso_nbd_srv=${pxeserver} cms_verify=y
+APPEND archisobasedir=%INSTALL_DIR% archisosearchuuid=%ARCHISO_UUID% archiso_nbd_srv=${pxeserver} cms_verify=y initramfs_async=0
 SYSAPPEND 3
 
 LABEL arch64_nfs
@@ -17,7 +17,7 @@ ENDTEXT
 MENU LABEL Omarchy install medium (x86_64, NFS)
 LINUX ::/%INSTALL_DIR%/boot/x86_64/vmlinuz-linux-t2
 INITRD ::/%INSTALL_DIR%/boot/x86_64/initramfs-linux-t2.img
-APPEND archisobasedir=%INSTALL_DIR% archiso_nfs_srv=${pxeserver}:/run/archiso/bootmnt cms_verify=y
+APPEND archisobasedir=%INSTALL_DIR% archiso_nfs_srv=${pxeserver}:/run/archiso/bootmnt cms_verify=y initramfs_async=0
 SYSAPPEND 3
 
 LABEL arch64_http
@@ -28,5 +28,5 @@ ENDTEXT
 MENU LABEL Omarchy install medium (x86_64, HTTP)
 LINUX ::/%INSTALL_DIR%/boot/x86_64/vmlinuz-linux-t2
 INITRD ::/%INSTALL_DIR%/boot/x86_64/initramfs-linux-t2.img
-APPEND archisobasedir=%INSTALL_DIR% archiso_http_srv=http://${pxeserver}/ cms_verify=y
+APPEND archisobasedir=%INSTALL_DIR% archiso_http_srv=http://${pxeserver}/ cms_verify=y initramfs_async=0
 SYSAPPEND 3

configs/syslinux/archiso_sys-linux.cfg

@@ -6,7 +6,7 @@ ENDTEXT
 MENU LABEL Omarchy install medium (x86_64, BIOS)
 LINUX /%INSTALL_DIR%/boot/x86_64/vmlinuz-linux-t2
 INITRD /%INSTALL_DIR%/boot/x86_64/initramfs-linux-t2.img
-APPEND archisobasedir=%INSTALL_DIR% archisosearchuuid=%ARCHISO_UUID% quiet splash
+APPEND archisobasedir=%INSTALL_DIR% archisosearchuuid=%ARCHISO_UUID% quiet splash xe.enable_panel_replay=0 initramfs_async=0
 
 # Accessibility boot option
 LABEL arch64speech
@@ -17,4 +17,4 @@ ENDTEXT
 MENU LABEL Omarchy install medium (x86_64, BIOS) with ^speech
 LINUX /%INSTALL_DIR%/boot/x86_64/vmlinuz-linux-t2
 INITRD /%INSTALL_DIR%/boot/x86_64/initramfs-linux-t2.img
-APPEND archisobasedir=%INSTALL_DIR% archisosearchuuid=%ARCHISO_UUID% accessibility=on
+APPEND archisobasedir=%INSTALL_DIR% archisosearchuuid=%ARCHISO_UUID% accessibility=on xe.enable_panel_replay=0 initramfs_async=0

plans/aarch64-support.md

@@ -0,0 +1,178 @@
+# Plan: aarch64 (Generic UEFI ARM64) build for omarchy-iso
+
+## Context
+
+omarchy-iso currently produces a single x86_64 Arch Linux live ISO. The build is x86-baked from top to bottom — profile arch, package list filename, microcode, kernel choice (`linux-t2`), bootloader configs (BIOS syslinux + UEFI GRUB), squashfs BCJ filter, Node.js download URL, QEMU smoke-test, release filename, and CI runner.
+
+Target: a parallel **generic UEFI aarch64** ISO — boots on Ampere servers, AWS Graviton VMs, Snapdragon X laptops, ARM dev kits. Anything that exposes vanilla UEFI + ACPI. Apple Silicon (Asahi) and SBCs (U-Boot/rpi-firmware) are out of scope.
+
+**Assumption:** cross-repo dependencies are someone else's problem to land first. This plan only covers omarchy-iso. The hard prerequisites are listed up front so it's clear what blocks the first green build.
+
+---
+
+## Hard prerequisites (NOT in this plan, but block any green build)
+
+These exist outside omarchy-iso. Flagged for visibility — without them, nothing here boots:
+
+1. **aarch64 base packages must exist somewhere we can pacman from.** Vanilla Arch (`geo.mirror.pkgbuild.com`) is x86_64-only — there is no `core/os/aarch64`. The realistic source is **Arch Linux ARM** (`mirror.archlinuxarm.org`) for `core`/`extra`/`alarm`/`aur`. Decision required: target Arch Linux ARM as the aarch64 base distribution.
+2. **`pkgs.omarchy.org/{stable,edge}/aarch64/`** must serve a real repo. Probed today, both return 404. omarchy-pkgs already has multi-arch build support per its README, so this is a publish step, not a port.
+3. **Omarchy ISO architecture guard** must allow supported architectures or scope any x86_64-only checks behind an explicit guard.
+4. **archinstall + Limine** must work end-to-end on aarch64. archinstall supports it; Limine supports aarch64 UEFI. Worth a manual verification before committing to this bootloader path on ARM.
+
+---
+
+## Approach
+
+Add an `--arch aarch64` flag to `bin/omarchy-iso-make`. Branch on it everywhere x86_64 is currently assumed. Don't fork the profile directory — overlay arch-specific files at build time so the two architectures share one source of truth.
+
+Output artifact naming already uses no arch suffix until release-time renaming, so two parallel builds coexist cleanly.
+
+---
+
+## Concrete changes
+
+### 1. Build entrypoint — `bin/omarchy-iso-make`
+
+- Add `--arch x86_64|aarch64` flag (default `x86_64` for backward compat).
+- Pass `OMARCHY_ARCH` env var into the container.
+- Switch the docker image / platform per arch:
+  - x86_64: `archlinux/archlinux:latest` (unchanged)
+  - aarch64: `archlinuxarm/archlinuxarm:latest` (or `menci/archlinuxarm` — pick whichever publishes a recent multi-arch image), with `--platform linux/arm64`. Native arm64 host preferred; QEMU emulation works but is slow.
+- Don't change pacman cache mount on the host: pacman keeps per-arch subdirs, so the cache is safe to share.
+
+### 2. Profile — `configs/profiledef.sh`
+
+Change `arch` and the squashfs BCJ filter at runtime. Either:
+- Keep one `profiledef.sh` and have `builder/build-iso.sh` `sed` the arch line + BCJ filter (`x86` → `arm`) before `mkarchiso` runs, **or**
+- Source `OMARCHY_ARCH` directly inside `profiledef.sh` (mkarchiso sources this file with bash, so env access is fine).
+
+`bootmodes` also needs to drop `bios.syslinux` for aarch64 (BIOS boot is x86-only) — `bootmodes=('uefi.grub')` on ARM.
+
+### 3. Build script — `builder/build-iso.sh`
+
+- **Line 56–57**: Node.js URL grep. Branch on `OMARCHY_ARCH`:
+  - `x86_64` → `linux-x64.tar.gz`
+  - `aarch64` → `linux-arm64.tar.gz`
+- **Line 73**: package additions. Drop `linux-t2` for aarch64 (T2-only x86 kernel) — use plain `linux`. Write to `packages.${OMARCHY_ARCH}` instead of hardcoded `packages.x86_64`.
+- **Line 77**: read same `packages.${OMARCHY_ARCH}` for offline mirror enumeration.
+- **archiso releng overlay** (`cp -r /archiso/configs/releng/*`): the upstream `releng` profile ships only `packages.x86_64`. For aarch64, copy `packages.x86_64` to `packages.aarch64` and prune obviously x86-only entries (`memtest86+`, `intel-ucode`, `amd-ucode`, `edk2-shell` x64 binary, `syslinux`). Land this as a small fixup step in `build-iso.sh` rather than a full fork of `releng`.
+
+### 4. archinstall package list — `builder/archinstall.packages`
+
+Drop microcode for aarch64 — `intel-ucode` and `amd-ucode` don't exist for ARM. Either:
+- Two lists (`archinstall.packages.x86_64`, `archinstall.packages.aarch64`), or
+- One list with sentinel comments and a filter step in `build-iso.sh:80` that drops microcode lines when `OMARCHY_ARCH=aarch64`.
+
+The second is less duplication for one-line drift.
+
+### 5. Bootloader configs
+
+aarch64 has no BIOS — only UEFI. Drop the syslinux path entirely on ARM.
+
+- **Skip on aarch64**: `configs/syslinux/*` (BIOS syslinux), `configs/grub/*` references to `shellx64.efi`/`shellia32.efi` (lines 81–85 of `grub.cfg`).
+- **`configs/efiboot/loader/loader.conf`**: change `default 01-archiso-x86_64-linux.conf` to a per-arch entry. Either two loader.conf files (selected by build-iso.sh) or rename the entry generically (`01-archiso-linux.conf`) and keep one file.
+- **`configs/efiboot/loader/entries/01-archiso-x86_64-linux.conf`**: produce an aarch64 sibling (`01-archiso-aarch64-linux.conf`) at build time — same template, drop microcode initrd lines, swap title. The kernel/initrd paths use `%ARCH%` already in `grub.cfg` but are hardcoded `x86_64` in this file (line 3–4).
+- **`configs/grub/grub.cfg` and `loopback.cfg`**: remove or guard the x86_64 conditionals. The `%ARCH%` placeholder gets substituted by mkarchiso from `profiledef.sh:arch`, so the kernel/initrd paths flip automatically. Manually-written `grub_cpu == 'x86_64'` blocks (lines 34–39, 68, 81–85) should drop on aarch64 builds — easiest done with a build-time sed for the aarch64 path, or by extracting them into a separate `grub-x86_64.cfg.fragment` only included on x86 builds.
+
+The cleanest cut: keep one `grub.cfg` shared, strip the x86 shell/memtest fragments at build time when `OMARCHY_ARCH=aarch64`. Don't fork the file.
+
+### 6. mkinitcpio preset — `configs/airootfs/etc/mkinitcpio.d/linux-t2.preset`
+
+Names `vmlinuz-linux-t2` and `initramfs-linux-t2.img`. The filename is the pkgbase and the alpm hook keys off it, so aarch64 does not rename this file — it simply does not ship it, and releng's own `linux.preset` covers the stock kernel. Drop `linux-t2` from `arch_packages` on aarch64 and the boot entries point at `vmlinuz-linux` / `initramfs-linux.img`.
+
+### 7. Configurator — `configs/airootfs/root/configurator`
+
+Lines 320–325:
+```bash
+if lspci -nn 2>/dev/null | grep -q "106b:180[12]"; then
+  kernel_choice="linux-t2"
+else
+  kernel_choice="linux"
+fi
+```
+T2 detection is harmless on aarch64 (`lspci` returns no match), so `kernel_choice` falls through to `linux`. **No change strictly required**, but clearer to wrap the lspci probe in `[[ $(uname -m) == "x86_64" ]]` so the intent reads correctly. Cheap.
+
+The archinstall JSON's `mirror_config.custom_servers` (lines 422–424) points at `mirror.omarchy.org`, `mirror.rackspace.com/archlinux`, `geo.mirror.pkgbuild.com` — none of these serve aarch64. For aarch64 the list must be `mirror.archlinuxarm.org` and friends. Branch the JSON template on `OMARCHY_ARCH` (or `uname -m` at runtime, since this file runs on the live ISO).
+
+### 8. pacman configs — `configs/pacman-online-{stable,rc,edge,offline}.conf`
+
+The `$arch` placeholder is pacman-resolved (matches `Architecture = auto`), so `https://stable-mirror.omarchy.org/$repo/os/$arch` adapts automatically — **as long as the mirror serves aarch64**. The omarchy mirror is the bottleneck (prerequisite #2). The `arch-mact2` repo is x86-only by definition; gate it behind arch on aarch64 builds (drop the section).
+
+### 9. Smoke-test scripts — `bin/omarchy-iso-boot`, `bin/omarchy-vm`
+
+Detect arch from the ISO filename (or accept a flag) and switch:
+- x86_64: `qemu-system-x86_64`, `/usr/share/edk2/x64/OVMF_CODE.4m.fd` + `OVMF_VARS.4m.fd` (unchanged).
+- aarch64: `qemu-system-aarch64`, `-machine virt -cpu max`, `/usr/share/edk2/aarch64/QEMU_CODE.fd` + `QEMU_VARS.fd` (Arch package: `edk2-armvirt`).
+
+Both scripts hardcode the OVMF path; small, mechanical fix.
+
+### 10. Release script — `bin/omarchy-iso-release:52`
+
+```bash
+latest_iso=$(\ls -t "$BUILD_RELEASE_PATH"/*${OMARCHY_ARCH}-"$ISO_REF".iso | head -n1)
+```
+Hardcoded `x86_64` glob. Take an arch arg, or do `*${OMARCHY_ARCH}-${ISO_REF}.iso`. The ISO filename already contains arch (set by archiso from `profiledef.sh`), so this just needs the glob parameterized.
+
+### 11. CI — `.github/workflows/nightly-build.yml`
+
+Add a matrix:
+```yaml
+strategy:
+  matrix:
+    arch: [x86_64, aarch64]
+    include:
+      - arch: x86_64
+        runner: ubuntu-latest
+      - arch: aarch64
+        runner: ubuntu-24.04-arm   # GitHub-hosted ARM runner, GA
+```
+Pass `--arch ${{ matrix.arch }}` to the build. Upload artifacts named per-arch.
+
+If GitHub-hosted ARM runners aren't available on this org's plan, fall back to QEMU emulation on `ubuntu-latest` (slow, ~3-4× build time) or self-hosted.
+
+---
+
+## Files to modify (summary)
+
+Code:
+- `bin/omarchy-iso-make` — add `--arch` flag, branch docker image/platform
+- `bin/omarchy-iso-boot` — branch QEMU binary + OVMF path
+- `bin/omarchy-vm` — same as iso-boot
+- `bin/omarchy-iso-release` — parameterize ISO glob
+- `builder/build-iso.sh` — main branching: Node.js URL, package list filename, releng overlay fixups, kernel package
+- `builder/archinstall.packages` — filter microcode on aarch64 (sentinel comments + filter step)
+- `configs/profiledef.sh` — env-driven `arch` + BCJ filter + bootmodes
+- `configs/efiboot/loader/loader.conf` — per-arch default entry
+- `configs/efiboot/loader/entries/01-archiso-x86_64-linux.conf` — generate aarch64 sibling at build time
+- `configs/grub/grub.cfg`, `loopback.cfg` — strip x86-only fragments on aarch64
+- `configs/airootfs/etc/mkinitcpio.d/linux-t2.preset` — omit on aarch64 (drop linux-t2 there; releng's linux.preset covers the stock kernel)
+- `configs/airootfs/root/configurator` — branch archinstall JSON mirror list on `uname -m`; optionally guard lspci T2 probe
+- `.github/workflows/nightly-build.yml` — matrix x86_64/aarch64
+
+No new files unless we go the dual-list route on archinstall.packages or efiboot loader entries; preferred path is build-time templating to keep one source of truth.
+
+---
+
+## Verification
+
+**Local (host is x86_64):**
+1. `bin/omarchy-iso-make --arch x86_64` — must produce a byte-similar ISO to today's nightly (smoke test for regressions in the refactor).
+2. `bin/omarchy-iso-make --arch aarch64` — succeeds (slow under QEMU binfmt; expect 30-60 min).
+3. `bin/omarchy-iso-boot release/omarchy-*-aarch64-*.iso` — boots to the configurator under `qemu-system-aarch64 -machine virt`. Walk through the picker, confirm archinstall lays down a working system, reboot into the installed system.
+4. Live-iso shell: `pacman -Sy && pacman -Si linux` returns an aarch64 package from `mirror.archlinuxarm.org`.
+
+**On real hardware (post green QEMU run):**
+- AWS Graviton VM (`c7g.medium`, dd ISO to a volume, attach as boot) — fastest cloud check, no hardware needed.
+- One physical ARM64 UEFI box if available (Ampere dev kit, Snapdragon X laptop, etc.) — the long pole.
+
+**CI:**
+- Both matrix legs go green on a manual `workflow_dispatch` before merging.
+- Nightly produces both ISOs as artifacts.
+
+---
+
+## Open risks (call out before implementation)
+
+1. **mkarchiso on aarch64 is less-trodden ground.** It accepts `arch="aarch64"`, but the upstream Arch project doesn't dogfood it. Expect to file/patch around small bugs in archiso's helper scripts. Keep the archiso submodule pin tight so a regression doesn't surprise nightly.
+2. **Limine + LUKS + Btrfs + Snapper on aarch64** — every one of these works individually on ARM, but the combination is what omarchy ships. Worth one manual end-to-end pass before declaring done.
+3. **Apple T2 / linux-t2 / `arch-mact2` repo** are silently dropped on aarch64; users mistakenly trying to install the aarch64 ISO on a T2 Mac will get an obviously-wrong result. The configurator could refuse to install when arch mismatch is detected, but that's outside this plan.

plans/consumer-secure-boot.md

@@ -0,0 +1,407 @@
+# Consumer Secure Boot Plan: Microsoft Shim + MOK + UKI
+
+## Goal
+
+Support Omarchy installs on consumer laptops that ship with UEFI Secure Boot enabled and trust the Microsoft UEFI CA, without requiring users to disable Secure Boot.
+
+This plan targets normal consumer hardware, especially Windows dual-boot machines. OEM-controlled hardware with Omarchy-owned firmware keys is a separate path.
+
+## Current State (August 2026)
+
+Where the repo stands today, and what that changes about this plan:
+
+- The ISO builds with `bootmodes=('bios.syslinux' 'uefi.grub')` (`configs/profiledef.sh`): an unsigned GRUB as `BOOTX64.EFI` loading an unsigned kernel and initramfs. Firmware that trusts only the Microsoft UEFI CA rejects the ISO at the first stage, so Secure Boot must be disabled today.
+- The vendored mkarchiso already supports a `uefi.systemd-boot` bootmode (mutually exclusive with `uefi.grub`), so the live-ISO half of `shim -> systemd-boot -> UKI` needs no archiso surgery — a bootmode switch plus signing.
+- The installed system already boots a UKI: the orchestrator's `finalize_limine_boot` phase has mkinitcpio build the UKI onto the ESP, and `validate_boot` asserts it exists. "Build an installed UKI" is no longer new work; the new work is signing that UKI and choosing a second stage that enforces signatures.
+- Kernel updates already regenerate the UKI through the target's mkinitcpio pacman hooks. The update flow below reduces to adding a signing step and fallback retention to machinery that exists.
+
+The critical path is external: the Microsoft-signed shim. That requires an EV code-signing certificate for the Omarchy org, a shim built from a reviewed upstream release with Omarchy SBAT identity and NX compatibility, and a `shim-review` submission — historically weeks to months of calendar time, with standing obligations afterward (SBAT revocation response, resubmission when the embedded cert or shim version changes). Start it first; every phase below except release signing can proceed in parallel on dev test keys in QEMU.
+
+## Core Architecture
+
+Use a Microsoft-signed first-stage shim, then boot only signed Omarchy-controlled artifacts.
+
+```text
+Firmware Secure Boot
+  -> Microsoft-signed Omarchy shim
+    -> MokManager when key enrollment is pending
+    -> signed second-stage boot manager
+      -> signed Unified Kernel Image (UKI)
+        -> encrypted Omarchy root
+```
+
+For the installed OS, use machine-local Machine Owner Key (MOK) signing for UKIs generated during install and later kernel updates.
+
+## Why MOK For Installed Systems
+
+Omarchy's installed UKI is machine-specific because it includes or depends on install-time data such as:
+
+- Kernel command line for encrypted root.
+- Initramfs generated for the installed system.
+- Kernel package version selected at install or update time.
+
+We must not ship Omarchy's private release signing key on the ISO or installed system. Therefore:
+
+1. The official ISO is signed by Omarchy release infrastructure.
+2. During install, generate a machine-local Secure Boot keypair.
+3. Enroll the public certificate through MokManager.
+4. Sign installed UKIs and update-generated UKIs with the local private key.
+5. Store the local private key only on the encrypted installed root, never on the ESP.
+
+This preserves offline tamper resistance for `/boot` while avoiding any central private key on user machines.
+
+## Scope Constraints
+
+- UEFI only.
+- Microsoft UEFI CA trust path only for consumer machines.
+- No custom firmware key enrollment for v1 consumer installs.
+- No TPM auto-unlock for Omarchy root in v1.
+- No attempt to modify Windows BitLocker protectors or TPM ownership.
+- Secure Boot mode uses signed UKIs only; no unsigned external kernel, initramfs, or command line files.
+- Secure Boot mode may use a different boot manager than the current Limine path until Limine has a proven verified-boot story.
+
+## Bootloader Decision
+
+Installed systems already boot a UKI through Limine, so the boot *artifact* needs no change. But signing Limine as an EFI binary is not sufficient if Limine will then load unsigned payloads or take direction from an unsigned `limine.conf`. For v1 Secure Boot support, use a boot path with a small, enforceable verification surface:
+
+```text
+shim -> systemd-boot -> signed UKI
+```
+
+Policy:
+
+- Keep Limine as the normal non-Secure-Boot bootloader unless we later prove Limine enforces signed payloads correctly.
+- Use systemd-boot only for Secure Boot installs if that is the fastest reliable path.
+- Boot only UKIs with embedded command line and initramfs.
+- Disable or avoid unsigned boot entry editing in Secure Boot mode.
+
+If later validation proves Limine can enforce signed payloads behind shim, this plan can swap the second stage while keeping the shim, MOK, UKI, and signing architecture.
+
+## Required Artifacts
+
+### Omarchy Shim Artifacts
+
+These are release artifacts, not generated on normal developer machines:
+
+- `shimx64.efi`, signed by Microsoft UEFI CA.
+- `mmx64.efi` / MokManager artifact compatible with the shim.
+- Optional `fbx64.efi` fallback artifact if needed by the selected shim packaging.
+- Shim SBAT metadata owned by Omarchy.
+- Omarchy public release certificate embedded in shim.
+
+Do not depend on another distribution's shim as a permanent product strategy. Omarchy needs its own shim submission, SBAT identity, revocation path, and release process.
+
+### Omarchy Signing Material
+
+Release infrastructure owns:
+
+- Omarchy Secure Boot release private key, stored offline or in an HSM-backed CI secret store.
+- Omarchy Secure Boot release public certificate, embedded in shim and shipped for verification.
+
+Installed systems own:
+
+- Machine-local MOK private key, stored on encrypted root with `0600` permissions.
+- Machine-local MOK public certificate, enrolled through MokManager.
+
+Private keys must never be committed to this repo.
+
+## Build-Time Flow
+
+Add a Secure Boot-capable ISO build mode.
+
+```text
+bin/omarchy-iso-make --secure-boot
+```
+
+Build behavior:
+
+1. Switch the UEFI bootmode from `uefi.grub` to `uefi.systemd-boot` in `configs/profiledef.sh` (mkarchiso forbids running both). BIOS syslinux stays as-is; Secure Boot is UEFI-only.
+2. Add Microsoft-signed Omarchy shim artifacts to the ISO UEFI boot path.
+3. Build the live environment boot payload as a UKI.
+4. Sign the live UKI with the Omarchy release key in official builds.
+5. Sign any second-stage EFI binary with the Omarchy release key.
+6. Assert that every Secure Boot UEFI entry uses the signed shim path.
+7. Assert that no unsigned kernel/initramfs path is offered in Secure Boot UEFI mode.
+
+Local developer builds should support a dev-signing mode for QEMU validation:
+
+```text
+OMARCHY_SECURE_BOOT_SIGNING_MODE=dev
+```
+
+Dev mode creates local test keys and is only expected to boot in QEMU firmware enrolled with those test keys. It must not be presented as Microsoft Secure Boot compatible.
+
+## Installed-System Flow
+
+When the live installer detects Secure Boot enabled:
+
+1. Show a Secure Boot explanation before disk mutation.
+2. If Windows is detected, follow the shipped dual-boot BitLocker policy (decrypt, not suspend — see the configurator's existing checks) and warn the user to have the recovery key available.
+3. Install Omarchy's shim to its own ESP directory, for example `EFI/Omarchy`.
+4. Do not modify `EFI/Microsoft`.
+5. Generate a machine-local MOK keypair under the installed encrypted root.
+6. Build an installed UKI with embedded kernel, initramfs, command line, and OS release data.
+7. Sign the installed UKI with the machine-local MOK private key.
+8. Sign the selected second-stage boot manager with the machine-local MOK private key, unless it is release-signed and expected to remain static.
+9. Schedule public certificate enrollment with `mokutil --import`.
+10. Tell the user they must complete MokManager enrollment on the next reboot.
+11. Preserve current firmware boot order by default on dual-boot machines.
+
+Expected first reboot sequence after install:
+
+```text
+Firmware -> Omarchy shim -> MokManager -> user enrolls Omarchy machine key -> reboot -> Omarchy shim -> signed boot manager -> signed UKI -> LUKS unlock
+```
+
+## Kernel Update Flow
+
+Secure Boot installs need deterministic UKI regeneration and signing after kernel or initramfs changes.
+
+The regeneration half already exists: the target's mkinitcpio pacman hooks rebuild the UKI on kernel or initramfs changes. Add the signing half — a hook ordered after the UKI build that:
+
+1. Signs the freshly built UKI with the machine-local MOK private key.
+2. Writes it atomically to the ESP.
+3. Keeps at least one previously booted signed UKI as fallback.
+
+Failure policy:
+
+- If signing fails, do not replace the currently bootable UKI.
+- If ESP space is low, keep the current UKI and fail loudly.
+- If the local signing key is missing, block the update from producing an unsigned boot artifact.
+
+## File Changes
+
+### `bin/omarchy-iso-make`
+
+Add flags:
+
+```text
+--secure-boot       build Secure Boot-capable ISO flavor
+--secure-boot-dev   build with local test keys for QEMU only
+```
+
+Pass mode and signing configuration into the Docker build environment.
+
+### `builder/build-iso.sh`
+
+Add Secure Boot build support:
+
+- Copy shim artifacts into the UEFI boot path.
+- Build live UKI.
+- Sign live UKI and second-stage EFI artifact.
+- Fail official Secure Boot builds if release signing material is unavailable.
+- Write `/root/omarchy_secure_boot_mode` into the live environment.
+- Assert that Secure Boot boot entries do not point at unsigned payloads.
+
+### `builder/secure-boot/`
+
+Add non-secret Secure Boot build inputs:
+
+- Public release certificate.
+- SBAT template.
+- Artifact manifest with expected shim/MokManager checksums.
+- Developer test-key generation script for QEMU only.
+
+Do not store private keys in this directory.
+
+### `configs/airootfs/root/configurator`
+
+Add Secure Boot detection and UX:
+
+- Detect UEFI Secure Boot state through efivars and/or `mokutil --sb-state`.
+- Detect Windows through ESP vendor paths and partition metadata (the dual-boot path's `detect_windows_esp` and BitLocker checks already exist — extend, don't duplicate).
+- Explain one-time MokManager enrollment.
+- Write `secure_boot.sh` with simple shell state for the install orchestrator.
+
+Example state:
+
+```bash
+SECURE_BOOT_ENABLED=true
+SECURE_BOOT_INSTALL=true
+SECURE_BOOT_BOOTLOADER=systemd-boot
+SECURE_BOOT_UKI=true
+SECURE_BOOT_MOK_COMMON_NAME="Omarchy Machine Owner Key"
+```
+
+### `configs/airootfs/usr/share/omarchy-iso/orchestrator/`
+
+Add Secure Boot install support to the install phases:
+
+- Read the `secure_boot.sh` state the configurator wrote.
+- When `SECURE_BOOT_INSTALL=true`, install the shim boot path and the enforcing second stage instead of (or in front of) the plain Limine setup in `_configure_limine_boot`.
+- Generate the machine-local MOK keypair on the installed encrypted root.
+- Sign the UKI that `finalize_limine_boot` already builds.
+- Schedule MOK enrollment with `mokutil --import`.
+- Install the UKI signing hook alongside the existing mkinitcpio hooks.
+- Preserve dual-boot firmware boot order unless explicitly promoted.
+- Extend `validate_boot` to assert the UKI on the ESP carries a valid signature.
+
+### Target System Files
+
+Add installed files similar to:
+
+```text
+/etc/omarchy/secure-boot.conf
+/etc/kernel/cmdline
+/etc/pacman.d/hooks/90-omarchy-uki.hook
+/usr/local/sbin/omarchy-build-uki
+/usr/local/sbin/omarchy-sign-uki
+/boot/EFI/Omarchy/shimx64.efi
+/boot/EFI/Omarchy/mmx64.efi
+/boot/EFI/Omarchy/systemd-bootx64.efi
+/boot/EFI/Linux/omarchy-linux.efi
+/boot/EFI/Linux/omarchy-linux-fallback.efi
+```
+
+Exact paths can change during implementation, but signed boot artifacts must stay under Omarchy-owned ESP directories.
+
+## Package Requirements
+
+Live ISO and installed Secure Boot path need tools for:
+
+- Building UKIs.
+- Signing PE/COFF EFI binaries.
+- Importing MOK certificates.
+- Inspecting Secure Boot state.
+
+Candidate packages:
+
+```text
+sbsigntools
+efitools
+mokutil
+openssl
+systemd
+```
+
+Validate Arch package availability before implementation. Do not assume an official Arch `shim-signed` package exists.
+
+## Dual-Boot Policy
+
+On Windows dual-boot machines:
+
+- Never modify Windows boot files.
+- Never clear or change TPM state.
+- Never change BitLocker protectors.
+- Preserve existing firmware default boot order by default.
+- Warn that adding a boot entry or changing ESP contents can trigger BitLocker recovery.
+- Follow the shipped dual-boot policy: tell users to turn BitLocker off in Windows and let the drive finish decrypting before installing (the configurator already enforces this; suspending alone proved insufficient — see #105).
+
+If the user chooses to make Omarchy first in boot order, capture the old `BootOrder` and provide rollback guidance.
+
+## Security Model
+
+Protected against:
+
+- Offline replacement of unsigned kernels on the ESP.
+- Offline modification of initramfs or kernel command line when UKI signature verification is enforced.
+- Accidental boot of unsigned Omarchy boot payloads in Secure Boot mode.
+
+Not protected against in v1:
+
+- A compromised running root user signing malicious future UKIs with the local MOK key.
+- Evil-maid attacks that trick the user into enrolling a malicious MOK.
+- Attacks requiring TPM-measured boot or remote attestation.
+
+Mitigations:
+
+- Store local private key only on encrypted root.
+- Make MokManager enrollment instructions explicit and brand-specific.
+- Display expected certificate fingerprint before reboot.
+- Keep release signing key outside shipped media.
+- Keep SBAT metadata current for revocation response.
+
+## QEMU Validation
+
+Use QEMU with OVMF Secure Boot enabled and test keys enrolled.
+
+Test matrix:
+
+1. Secure Boot ISO boots with test shim/test db in OVMF.
+2. Unsigned live UKI fails to boot.
+3. Tampered live UKI fails to boot.
+4. Secure Boot install completes to empty disk.
+5. First installed boot enters MokManager enrollment flow.
+6. After MOK enrollment, installed Omarchy boots and prompts for LUKS unlock.
+7. Tampered installed UKI fails to boot.
+8. Kernel update regenerates and signs a new UKI.
+9. Failed signing leaves previous UKI bootable.
+10. Dual-boot disk with Windows-style ESP preserves `EFI/Microsoft` and boot order.
+
+QEMU cannot fully prove Microsoft production trust. Hardware validation is required with firmware that trusts Microsoft UEFI CA and has Secure Boot enabled.
+
+## Hardware Validation
+
+Minimum hardware tests:
+
+1. Microsoft Secure Boot enabled laptop boots official Secure Boot ISO.
+2. Windows dual-boot install preserves Windows boot.
+3. BitLocker-decrypted install boots both OSes cleanly afterward.
+4. BitLocker-active install warning is visible before any disk mutation.
+5. Installed Omarchy boots only after MOK enrollment.
+6. Secure Boot remains enabled after install.
+7. Kernel update boots with newly signed UKI.
+8. Manually tampered UKI is rejected.
+9. Firmware boot order is preserved unless user opted to promote Omarchy.
+
+## Rollout Plan
+
+### Phase 1: Research And Decisions
+
+- Kick off the EV certificate purchase and `shim-review` submission prep immediately — this is the calendar-bound item that gates Phase 4, and nothing else depends on it being done first.
+- Confirm shim submission requirements and timeline.
+- Confirm selected second-stage boot manager (systemd-boot unless Limine's signature enforcement is proven).
+- ~~Confirm UKI generation mechanism on Arch~~ — resolved: mkinitcpio already builds the installed UKI today.
+- Confirm package availability for signing and MOK workflows.
+- Decide local MOK key storage and update-hook policy.
+- Decide the DKMS/out-of-tree module signing story (see Open Questions — this is a v1 blocker, not a nice-to-have).
+
+### Phase 2: Dev Secure Boot In QEMU
+
+- Add dev keys and QEMU OVMF Secure Boot harness.
+- Build a dev-signed live UKI.
+- Boot ISO in QEMU with test keys.
+- Prove unsigned and tampered payload rejection.
+
+### Phase 3: Installed UKI + MOK Flow
+
+- Generate local MOK key during install.
+- Build and sign installed UKI.
+- Schedule MokManager enrollment.
+- Boot installed system in QEMU after enrollment.
+- Add kernel update hook and fallback UKI handling.
+
+### Phase 4: Official Shim And Release Signing
+
+- Build Omarchy shim with SBAT metadata and embedded release cert.
+- Submit shim artifacts for Microsoft signing.
+- Integrate signed shim artifacts into official build pipeline.
+- Add release signing with HSM/offline key handling.
+
+### Phase 5: Consumer Dual-Boot UX
+
+- Add Secure Boot and BitLocker warnings to configurator.
+- Preserve Windows boot order by default.
+- Add MOK enrollment instructions and certificate fingerprint display.
+- Validate on real Windows hardware.
+
+## Acceptance Criteria
+
+- Official Secure Boot ISO boots on Microsoft Secure Boot hardware without disabling Secure Boot.
+- Secure Boot install does not ship or expose Omarchy release private keys.
+- Installed Omarchy boots through shim after MOK enrollment.
+- Installed Omarchy root remains LUKS-encrypted and passphrase-unlocked.
+- Kernel updates produce signed UKIs automatically.
+- Tampered UKIs fail to boot.
+- Windows ESP contents are preserved.
+- Windows boot order is preserved by default.
+- Secure Boot mode never offers an unsigned kernel/initramfs boot entry.
+
+## Open Questions
+
+- Whether Limine can enforce signature verification on the UKIs and config it loads; if not proven, Secure Boot installs use systemd-boot as the second stage while non-Secure-Boot installs keep Limine.
+- Whether the local MOK private key should be encrypted with a user-supplied passphrase or stored root-only on encrypted root.
+- How to support signed out-of-tree kernel modules, especially proprietary GPU drivers or DKMS packages. **This must be answered for v1:** once Secure Boot is enforcing, unsigned modules will not load, and NVIDIA laptops are exactly the consumer hardware this plan targets. The module signing hook must sign with the machine-local MOK alongside the UKI.
+- How snapshot booting (factory reset restores from Btrfs snapshots) should work when each bootable kernel must be a signed UKI.
+- Whether official builds should always be Secure Boot-capable or ship a separate Secure Boot ISO flavor.
+- What user-facing recovery path should exist if MOK enrollment is skipped or fails.

test/all

@@ -0,0 +1,16 @@
+#!/bin/bash
+#
+# Fast, VM-free tests only. The integration scenarios that boot the ISO in
+# QEMU live in test/integration.d/ and run via ./test/integration.
+
+set -euo pipefail
+
+ROOT=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)
+
+for test in "$ROOT"/test/unit/*-test.sh; do
+  printf '==> %s\n' "${test#$ROOT/}"
+  bash "$test"
+done
+
+printf '==> test/unit/test_*.py\n'
+python3 -m unittest discover -t "$ROOT" -s "$ROOT/test/unit"

test/integration

@@ -0,0 +1,95 @@
+#!/bin/bash
+#
+# Integration runner: boots an ISO's installed system in QEMU and runs the
+# scenarios in test/integration.d/ against it. The unattended cidata install
+# happens once per ISO and is saved as a reusable base image; every scenario
+# then boots a throwaway overlay of that base.
+#
+# Usage: test/integration [release/omarchy.iso] [scenario ...] [options]
+#
+#   scenario       Basename of a test/integration.d/<scenario>-test.sh file;
+#                  all scenarios run when none are named
+#   --reuse-base   Skip the install if a saved base image exists
+#   --port PORT    Host port forwarded to guest SSH (default 2322)
+#   --memory MB    VM memory (default 8192)
+#   --timeout SECS Install timeout (default 2400)
+#   --no-preview   Do not open the collected screenshots in imv
+
+set -euo pipefail
+
+ROOT=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)
+
+ISO=""
+REUSE_BASE=false
+SCENARIOS=()
+
+export OMARCHY_INTEGRATION_SSH_PORT=2322
+export OMARCHY_INTEGRATION_MEMORY=8192
+export OMARCHY_INTEGRATION_INSTALL_TIMEOUT=2400
+export OMARCHY_INTEGRATION_NO_PREVIEW=false
+
+while (($#)); do
+  case "$1" in
+    --reuse-base) REUSE_BASE=true ;;
+    --no-preview) OMARCHY_INTEGRATION_NO_PREVIEW=true ;;
+    --port) OMARCHY_INTEGRATION_SSH_PORT="$2"; shift ;;
+    --memory) OMARCHY_INTEGRATION_MEMORY="$2"; shift ;;
+    --timeout) OMARCHY_INTEGRATION_INSTALL_TIMEOUT="$2"; shift ;;
+    -*) echo "Unknown option: $1" >&2; exit 1 ;;
+    *)
+      if [[ $1 == *.iso ]]; then
+        ISO="$1"
+      else
+        SCENARIOS+=("$ROOT/test/integration.d/$1-test.sh")
+      fi
+      ;;
+  esac
+  shift
+done
+
+if [[ -z $ISO && -t 0 ]]; then
+  ISO=$(ls -t "$ROOT"/release/*.iso 2>/dev/null | gum choose --header "Select ISO to test")
+fi
+
+if [[ ! -f ${ISO:-} ]]; then
+  echo "No ISO to test. Pass one explicitly or put it in release/." >&2
+  exit 1
+fi
+
+if (( ${#SCENARIOS[@]} == 0 )); then
+  SCENARIOS=("$ROOT"/test/integration.d/*-test.sh)
+else
+  for scenario in "${SCENARIOS[@]}"; do
+    if [[ $(basename "$scenario") == "base-test.sh" || ! -f $scenario ]]; then
+      echo "No such scenario: $scenario" >&2
+      exit 1
+    fi
+  done
+fi
+
+omarchy-pkg-add qemu-full edk2-ovmf socat imagemagick tesseract tesseract-data-eng mtools
+
+export OMARCHY_INTEGRATION_ISO
+OMARCHY_INTEGRATION_ISO=$(realpath "$ISO")
+
+# The install phase runs in this process; scenarios run in their own so each
+# gets its own VM lifecycle, cleanup trap, and run directory.
+SCENARIO=install
+source "$ROOT/test/integration.d/base-test.sh"
+
+if $REUSE_BASE && base_image_ready; then
+  log "Reusing existing base image: $BASE_DISK"
+else
+  install_phase
+fi
+
+status=0
+for scenario in "${SCENARIOS[@]}"; do
+  [[ $(basename "$scenario") == "base-test.sh" ]] && continue
+  printf '\033[1;35m==> %s\033[0m\n' "${scenario#$ROOT/}"
+  # env -u: a SCENARIO exported by the caller (or leaked from this process)
+  # must not override the name each scenario derives from its own $0.
+  env -u SCENARIO bash "$scenario" || status=1
+done
+
+exit $status

test/integration.d/base-test.sh

@@ -0,0 +1,572 @@
+#!/bin/bash
+#
+# Shared harness for the integration scenarios in test/integration.d/: QEMU
+# lifecycle, QMP screendump + OCR console driving, virtual keystrokes, guest
+# SSH, cidata autoinstall, and the reusable base-image contract. Source this
+# from a scenario; ./test/integration exports the configuration and ensures
+# the base image exists before any scenario runs.
+
+set -euo pipefail
+
+ROOT=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd)
+
+ISO="$OMARCHY_INTEGRATION_ISO"
+SSH_PORT="${OMARCHY_INTEGRATION_SSH_PORT:-2322}"
+MEMORY="${OMARCHY_INTEGRATION_MEMORY:-8192}"
+INSTALL_TIMEOUT="${OMARCHY_INTEGRATION_INSTALL_TIMEOUT:-2400}"
+NO_PREVIEW="${OMARCHY_INTEGRATION_NO_PREVIEW:-false}"
+BOOT_TIMEOUT=600
+
+GUEST_USER="omarchy"
+GUEST_PASSWORD="omarchy"
+GUEST_HOSTNAME="omarchy-test"
+
+SCENARIO="${SCENARIO:-$(basename "${0%-test.sh}")}"
+
+OVMF_CODE="/usr/share/edk2/x64/OVMF_CODE.4m.fd"
+OVMF_VARS_TEMPLATE="/usr/share/edk2/x64/OVMF_VARS.4m.fd"
+
+BASE_DIR="$ROOT/test-runs/$(basename "$ISO" .iso)-integration"
+RUN_DIR="$BASE_DIR/runs/$(date +%Y%m%d-%H%M%S)-$SCENARIO"
+BASE_DISK="$BASE_DIR/base.qcow2"
+BASE_OVMF="$BASE_DIR/OVMF_VARS.4m.fd"
+ACTIVE_OVMF="$BASE_OVMF"
+SSH_KEY="$BASE_DIR/id_ed25519"
+CIDATA_IMG="$BASE_DIR/cidata.img"
+HTTP_PORT=$((SSH_PORT + 1))
+HTTP_PID=""
+
+mkdir -p "$BASE_DIR" "$RUN_DIR"
+
+QMP_SOCK=$(mktemp -u "${TMPDIR:-/tmp}/omarchy-integration-qmp.XXXXXX.sock")
+PIDFILE="$RUN_DIR/qemu.pid"
+
+FAILURES=0
+
+log() {
+  printf '\033[1;35m==> %s\033[0m\n' "$1"
+}
+
+check() {
+  local description="$1"
+  shift
+
+  if "$@" >/dev/null 2>&1; then
+    printf 'ok - %s\n' "$description"
+  else
+    printf 'not ok - %s\n' "$description"
+    ((FAILURES += 1))
+  fi
+}
+
+finish() {
+  if ((FAILURES == 0)); then
+    log "$SCENARIO passed. Artifacts: $RUN_DIR"
+  else
+    log "$SCENARIO FAILED: $FAILURES assertion(s). Artifacts: $RUN_DIR"
+    exit 1
+  fi
+}
+
+base_image_ready() {
+  [[ -f $BASE_DISK && -f $BASE_OVMF && -f $SSH_KEY ]]
+}
+
+# ---------------------------------------------------------------- vm control
+
+vm_running() {
+  [[ -f $PIDFILE ]] && kill -0 "$(cat "$PIDFILE")" 2>/dev/null
+}
+
+qmp() {
+  printf '{"execute":"qmp_capabilities"}\n{"execute":%s}\n' "$1" |
+    timeout 5 socat -t 2 - "UNIX-CONNECT:$QMP_SOCK" 2>/dev/null || true
+}
+
+screendump() {
+  qmp "\"screendump\", \"arguments\": {\"filename\": \"$1\"}" >/dev/null
+}
+
+capture_console() {
+  local name="$1" shot="$RUN_DIR/.capture.ppm"
+
+  sleep 1
+  screendump "$shot"
+  [[ -s $shot ]] || return 0
+  magick "$shot" "$RUN_DIR/$name.png" 2>/dev/null || true
+  rm -f "$shot"
+}
+
+stop_vm() {
+  vm_running || return 0
+
+  if ! ssh_guest "echo $GUEST_PASSWORD | sudo -S systemctl poweroff" >/dev/null 2>&1; then
+    qmp '"system_powerdown"' >/dev/null
+  fi
+
+  local waited=0
+  while vm_running && ((waited < 15)); do
+    sleep 1
+    ((waited += 1))
+  done
+
+  if vm_running; then
+    qmp '"quit"' >/dev/null
+    sleep 1
+  fi
+
+  if vm_running; then
+    kill "$(cat "$PIDFILE")" 2>/dev/null || true
+    sleep 1
+  fi
+}
+
+open_screenshots() {
+  local entry
+  local -a screenshots=()
+
+  while IFS= read -r -d '' entry; do
+    screenshots+=("${entry#* }")
+  done < <(
+    find "$RUN_DIR" -type f \( -name "success-*.png" -o -name "failure-*.png" \) -printf '%T@ %p\0' |
+      sort -zn
+  )
+
+  (( ${#screenshots[@]} > 0 )) || return 0
+
+  log "Visual review: ${#screenshots[@]} screenshots in $RUN_DIR"
+  [[ $NO_PREVIEW == "true" ]] && return 0
+
+  if command -v imv >/dev/null && [[ -n ${WAYLAND_DISPLAY:-}${DISPLAY:-} ]]; then
+    setsid -f imv "${screenshots[@]}" >/dev/null 2>&1
+  fi
+}
+
+cleanup() {
+  local status=$?
+
+  [[ -n $HTTP_PID ]] && kill "$HTTP_PID" 2>/dev/null || true
+  vm_running && log "Stopping test VM"
+  stop_vm
+  rm -f "$RUN_DIR/.screen.ppm" "$RUN_DIR/.screen.png"
+  open_screenshots
+  rmdir "$RUN_DIR" 2>/dev/null || true
+
+  return $status
+}
+trap cleanup EXIT
+
+start_vm() {
+  local disk="$1" serial="$2"
+  shift 2
+
+  qemu-system-x86_64 \
+    -cpu host -enable-kvm -machine q35,accel=kvm \
+    -smp "$(nproc)" \
+    -m "$MEMORY" \
+    -drive if=pflash,format=raw,readonly=on,file="$OVMF_CODE" \
+    -drive if=pflash,format=raw,file="$ACTIVE_OVMF" \
+    -drive file="$disk",format=qcow2,if=none,id=drive0 \
+    -device virtio-blk-pci,drive=drive0,bootindex=1 \
+    -device virtio-vga \
+    -display none \
+    -usb -device usb-tablet \
+    -netdev user,id=net0,hostfwd=tcp:127.0.0.1:$SSH_PORT-:22 \
+    -device virtio-net-pci,netdev=net0 \
+    -qmp "unix:$QMP_SOCK,server,nowait" \
+    -serial "file:$serial" \
+    -pidfile "$PIDFILE" \
+    -daemonize \
+    "$@"
+}
+
+# Boot a throwaway overlay of the installed base. The disk gets a per-run
+# overlay; the firmware vars need the same isolation or NVRAM state would
+# leak between runs.
+start_vm_from_base() {
+  qemu-img create -f qcow2 -b "$BASE_DISK" -F qcow2 "$RUN_DIR/run.qcow2" >/dev/null
+  cp "$BASE_OVMF" "$RUN_DIR/OVMF_VARS.4m.fd"
+  ACTIVE_OVMF="$RUN_DIR/OVMF_VARS.4m.fd"
+  start_vm "$RUN_DIR/run.qcow2" "$RUN_DIR/serial.log"
+}
+
+# ------------------------------------------------------------ console driver
+
+ocr_screen() {
+  local shot="$RUN_DIR/.screen.ppm" prepped="$RUN_DIR/.screen.png"
+
+  screendump "$shot"
+  [[ -s $shot ]] || return 0
+  magick "$shot" -colorspace gray -negate -resize 150% "$prepped" 2>/dev/null || return 0
+  tesseract "$prepped" - --psm 6 2>/dev/null || true
+}
+
+wait_for_screen() {
+  local text="$1" timeout="$2" waited=0 slug
+
+  until ocr_screen | grep -qi "$text"; do
+    if ! vm_running; then
+      echo "VM exited while waiting for screen: $text" >&2
+      return 1
+    fi
+
+    if ((waited >= timeout)); then
+      slug=${text,,}
+      slug=${slug// /-}
+      slug=${slug//[^a-z0-9-]/}
+      capture_console "failure-waiting-for-$slug"
+      echo "Timed out after ${timeout}s waiting for screen: $text" >&2
+      return 1
+    fi
+
+    sleep 3
+    ((waited += 3))
+  done
+
+  sleep 1
+}
+
+press() {
+  local part json=""
+  local -a parts
+
+  IFS='-' read -ra parts <<<"$1"
+  for part in "${parts[@]}"; do
+    json+="{\"type\":\"qcode\",\"data\":\"$part\"},"
+  done
+
+  qmp "\"send-key\", \"arguments\": {\"keys\": [${json%,}]}" >/dev/null
+}
+
+type_text() {
+  local text="$1" ch i
+
+  for ((i = 0; i < ${#text}; i++)); do
+    ch=${text:i:1}
+    case "$ch" in
+      [a-z0-9]) press "$ch" ;;
+      [A-Z]) press "shift-${ch,,}" ;;
+      " ") press spc ;;
+      .) press dot ;;
+      ,) press comma ;;
+      -) press minus ;;
+      _) press shift-minus ;;
+      /) press slash ;;
+      :) press shift-semicolon ;;
+      "&") press shift-7 ;;
+      "=") press equal ;;
+      "?") press shift-slash ;;
+      "!") press shift-1 ;;
+      "~") press shift-grave_accent ;;
+      @) press shift-2 ;;
+      *) echo "type_text: unsupported character: $ch" >&2; return 1 ;;
+    esac
+    sleep 0.05
+  done
+}
+
+# --------------------------------------------------------------------- guest
+
+ssh_guest() {
+  ssh -i "$SSH_KEY" -p "$SSH_PORT" \
+    -o BatchMode=yes \
+    -o IdentitiesOnly=yes \
+    -o StrictHostKeyChecking=no \
+    -o UserKnownHostsFile=/dev/null \
+    -o ConnectTimeout=5 \
+    -o LogLevel=ERROR \
+    "$GUEST_USER@127.0.0.1" "$@"
+}
+
+ssh_sudo() {
+  ssh_guest "echo $GUEST_PASSWORD | sudo -S -p '' bash -c $(printf %q "$1")"
+}
+
+wait_for_ssh() {
+  local timeout="$1" failure_name="${2:-failure-ssh-timeout}" waited=0
+
+  while ! ssh_guest true 2>/dev/null; do
+    if ! vm_running; then
+      echo "VM exited while waiting for SSH" >&2
+      return 1
+    fi
+
+    if ((waited >= timeout)); then
+      capture_console "$failure_name"
+      echo "Timed out after ${timeout}s waiting for SSH" >&2
+      return 1
+    fi
+
+    sleep 5
+    ((waited += 5))
+  done
+}
+
+# Authorize SSH the way a person would when the guest has no key yet (or a
+# reset just scrubbed it): console login on a spare TTY, then a bootstrap
+# script fetched from a throwaway host HTTP server.
+bootstrap_ssh() {
+  log "Authorizing SSH access via console login"
+
+  mkdir -p "$BASE_DIR/www"
+  cat >"$BASE_DIR/www/bootstrap" <<EOF
+mkdir -p ~/.ssh && chmod 700 ~/.ssh
+echo "$(cat "$SSH_KEY.pub")" >>~/.ssh/authorized_keys
+chmod 600 ~/.ssh/authorized_keys
+echo "$GUEST_PASSWORD" | sudo -S ufw allow from 10.0.2.2 to any port 22 proto tcp
+echo "$GUEST_PASSWORD" | sudo -S systemctl enable --now sshd.service
+EOF
+
+  (cd "$BASE_DIR/www" && exec python3 -m http.server "$HTTP_PORT" --bind 127.0.0.1 >/dev/null 2>&1) &
+  HTTP_PID=$!
+
+  local waited=0
+  while true; do
+    press ctrl-alt-f3
+    sleep 4
+    ocr_screen | grep -qi "login:" && break
+    ((waited += 8))
+
+    if ((waited >= 300)); then
+      capture_console "failure-console-timeout"
+      echo "Timed out waiting for a console login prompt" >&2
+      return 1
+    fi
+    sleep 4
+  done
+
+  type_text "$GUEST_USER"
+  press ret
+  wait_for_screen "Password" 60
+  type_text "$GUEST_PASSWORD"
+  press ret
+  sleep 3
+
+  type_text "curl -fsS http://10.0.2.2:$HTTP_PORT/bootstrap -o /tmp/bs && bash /tmp/bs"
+  press ret
+
+  wait_for_ssh 360 "failure-bootstrap-ssh-timeout"
+  capture_console "success-bootstrap-ssh"
+
+  kill "$HTTP_PID" 2>/dev/null || true
+  HTTP_PID=""
+  press ctrl-alt-f1
+}
+
+# ---------------------------------------------------------- cidata autoinstall
+
+# The configurator's own output files, synthesized for the 40G virtio disk the
+# VM boots from. Sizing mirrors the configurator: 1MiB gap, 2GiB ESP, the rest
+# btrfs minus the GPT backup reserve.
+build_cidata() {
+  local dir="$BASE_DIR/cidata" hash
+  local disk_bytes=$((40 * 1024 * 1024 * 1024))
+  local mib=$((1024 * 1024)) gib=$((1024 * 1024 * 1024))
+  local boot_start=$mib boot_size=$((2 * gib))
+  local main_start=$((boot_size + boot_start))
+  local main_size=$((disk_bytes - main_start - mib))
+
+  rm -rf "$dir"
+  mkdir -p "$dir"
+
+  hash=$(openssl passwd -6 "$GUEST_PASSWORD")
+
+  cat >"$dir/user_credentials.json" <<EOF
+{
+    "root_enc_password": $(jq -Rn --arg v "$hash" '$v'),
+    "users": [
+        {
+            "enc_password": $(jq -Rn --arg v "$hash" '$v'),
+            "groups": [],
+            "sudo": true,
+            "username": "$GUEST_USER"
+        }
+    ]
+}
+EOF
+
+  cat >"$dir/user_configuration.json" <<EOF
+{
+    "app_config": null,
+    "archinstall-language": "English",
+    "auth_config": {},
+    "audio_config": { "audio": "pipewire" },
+    "bootloader_config": { "bootloader": "Limine", "uki": false, "removable": false },
+    "custom_commands": [],
+    "omarchy_install": {
+        "mode": "full_disk",
+        "defer_provisioning": false,
+        "target_mount": "/mnt",
+        "boot": {
+            "esp_mount": "/boot",
+            "esp_path": "/EFI/limine",
+            "efi_binary": "limine_x64.efi",
+            "enable_fallback": true
+        },
+        "storage": { "kernel": "linux" }
+    },
+    "disk_config": {
+        "config_type": "default_layout",
+        "device_modifications": [
+            {
+                "device": "/dev/vda",
+                "partitions": [
+                    {
+                        "btrfs": [],
+                        "dev_path": null,
+                        "flags": [ "boot", "esp" ],
+                        "fs_type": "fat32",
+                        "mount_options": [],
+                        "mountpoint": "/boot",
+                        "obj_id": "ea21d3f2-82bb-49cc-ab5d-6f81ae94e18d",
+                        "size": { "sector_size": { "unit": "B", "value": 512 }, "unit": "B", "value": $boot_size },
+                        "start": { "sector_size": { "unit": "B", "value": 512 }, "unit": "B", "value": $boot_start },
+                        "status": "create",
+                        "type": "primary"
+                    },
+                    {
+                        "btrfs": [
+                            { "mountpoint": "/", "name": "@" },
+                            { "mountpoint": "/home", "name": "@home" },
+                            { "mountpoint": "/var/log", "name": "@log" },
+                            { "mountpoint": "/var/cache/pacman/pkg", "name": "@pkg" }
+                        ],
+                        "dev_path": null,
+                        "flags": [],
+                        "fs_type": "btrfs",
+                        "mount_options": [ "compress=zstd" ],
+                        "mountpoint": null,
+                        "obj_id": "8c2c2b92-1070-455d-b76a-56263bab24aa",
+                        "size": { "sector_size": { "unit": "B", "value": 512 }, "unit": "B", "value": $main_size },
+                        "start": { "sector_size": { "unit": "B", "value": 512 }, "unit": "B", "value": $main_start },
+                        "status": "create",
+                        "type": "primary"
+                    }
+                ],
+                "wipe": true
+            }
+        ]
+    },
+    "hostname": "$GUEST_HOSTNAME",
+    "kernels": [ "linux" ],
+    "network_config": { "type": "iso" },
+    "ntp": true,
+    "parallel_downloads": 8,
+    "script": null,
+    "services": [],
+    "swap": true,
+    "timezone": "UTC",
+    "locale_config": { "kb_layout": "us", "sys_enc": "UTF-8", "sys_lang": "en_US.UTF-8" },
+    "mirror_config": {
+        "custom_repositories": [],
+        "custom_servers": [
+            {"url": "https://mirror.omarchy.org/\$repo/os/\$arch"},
+            {"url": "https://mirror.rackspace.com/archlinux/\$repo/os/\$arch"},
+            {"url": "https://geo.mirror.pkgbuild.com/\$repo/os/\$arch"}
+        ],
+        "mirror_regions": {},
+        "optional_repositories": []
+    },
+    "packages": [
+        "base-devel",
+        "git",
+        "omarchy-keyring",
+        "$SETTINGS_PACKAGE",
+        "$RUNTIME_PACKAGE"
+    ],
+    "profile_config": { "gfx_driver": null, "greeter": null, "profile": {} },
+    "version": "3.0.9"
+}
+EOF
+
+  echo "Omarchy Test" >"$dir/user_full_name.txt"
+  echo "test@omarchy.org" >"$dir/user_email_address.txt"
+  echo "false" >"$dir/user_encrypt_installation.txt"
+  cp "$SSH_KEY.pub" "$dir/authorized_keys"
+
+  rm -f "$CIDATA_IMG"
+  truncate -s 4M "$CIDATA_IMG"
+  mkfs.vfat -n CIDATA "$CIDATA_IMG" >/dev/null
+  mcopy -i "$CIDATA_IMG" "$dir"/* ::/
+}
+
+# The dev/local ISO installs the -dev packages; a stable ISO the plain ones.
+detect_packages() {
+  RUNTIME_PACKAGE=omarchy-dev
+  SETTINGS_PACKAGE=omarchy-settings-dev
+  if [[ $(basename "$ISO") != *dev* && $(basename "$ISO") != *local* && $(basename "$ISO") != *pr* ]]; then
+    RUNTIME_PACKAGE=omarchy
+    SETTINGS_PACKAGE=omarchy-settings
+  fi
+}
+
+install_phase() {
+  log "Installing $(basename "$ISO") unattended via cidata (headless)"
+
+  [[ -f $SSH_KEY ]] || ssh-keygen -t ed25519 -N "" -q -C "omarchy-integration" -f "$SSH_KEY"
+  detect_packages
+  build_cidata
+
+  # Build under a staging name: the finished base is promoted only after a
+  # clean shutdown, so a failed install can never pass for a reusable base.
+  rm -f "$BASE_DISK" "$BASE_DISK.building"
+  qemu-img create -f qcow2 "$BASE_DISK.building" 40G >/dev/null
+  cp "$OVMF_VARS_TEMPLATE" "$BASE_OVMF"
+  ACTIVE_OVMF="$BASE_OVMF"
+
+  start_vm "$BASE_DISK.building" "$RUN_DIR/install-serial.log" \
+    -drive "file=$ISO,media=cdrom,if=none,format=raw,id=cdrom0" \
+    -device ide-cd,drive=cdrom0,bootindex=2 \
+    -drive "file=$CIDATA_IMG,format=raw,if=none,id=cidata" \
+    -device usb-storage,drive=cidata
+
+  log "Waiting for the unattended install to finish (timeout ${INSTALL_TIMEOUT}s)"
+  local waited=0 text progress_name
+  while true; do
+    # An unattended install reboots on its own; SSH answering means the
+    # installed system is up (cidata's authorized_keys enables sshd).
+    if ssh_guest true 2>/dev/null; then
+      log "Install finished and rebooted into the installed system."
+      capture_console "success-install-first-boot"
+      break
+    fi
+
+    text=$(ocr_screen)
+
+    if grep -qi "Reboot Now" <<<"$text"; then
+      log "Install finished. Confirming the reboot prompt."
+      capture_console "success-install-reboot"
+      press ret
+    fi
+
+    if grep -qi "installation stopped" <<<"$text"; then
+      capture_console "failure-install-stopped"
+      echo "Install failed — screenshot saved to $RUN_DIR" >&2
+      return 1
+    fi
+
+    if ! vm_running; then
+      echo "VM exited during install" >&2
+      return 1
+    fi
+
+    if ((waited >= INSTALL_TIMEOUT)); then
+      capture_console "failure-install-timeout"
+      echo "Timed out after ${INSTALL_TIMEOUT}s waiting for install" >&2
+      return 1
+    fi
+
+    if ((waited % 120 == 0)); then
+      printf -v progress_name 'success-install-progress-%04ds' "$waited"
+      capture_console "$progress_name"
+      echo "    ... installing (${waited}s)"
+    fi
+
+    sleep 10
+    ((waited += 10))
+  done
+
+  log "Installed system is up. Saving base image."
+  stop_vm
+  mv "$BASE_DISK.building" "$BASE_DISK"
+}

test/integration.d/factory-reset-test.sh

@@ -0,0 +1,287 @@
+#!/bin/bash
+#
+# Factory reset on a shared ESP: proves omarchy-system-factory-reset hands a
+# machine on without destroying a dual-boot setup (basecamp/omarchy#6847).
+# Dresses the installed ESP up as a dual-boot machine (Windows + a foreign
+# Linux, exactly what the reset must not destroy), runs a real factory reset,
+# and walks the first-boot setup that follows.
+#
+# Staging asserts the Windows and foreign Linux entries and their ESP payload
+# survive, the old Omarchy identity (entry + directory) is gone, and a fresh
+# Omarchy entry exists. First boot asserts provisioning completes, the machine
+# identity changed, and the foreign entries are still intact afterwards.
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+FOREIGN_ID="fedcfedcfedcfedcfedcfedcfedcfedc"
+
+base_image_ready || { echo "No base image; run this through ./test/integration" >&2; exit 1; }
+
+# --------------------------------------------------------------- esp fixture
+
+# Dress the ESP up as a shared dual-boot ESP: a Windows entry, and a second
+# Linux installation cloned from the real Omarchy entry so its shape is
+# exactly what limine-entry-tool writes, under a foreign machine-id with its
+# own boot directory and byte-identical UKIs (so the cloned entry hashes
+# stay valid).
+fixture_shared_esp() {
+  OLD_ID=$(ssh_guest "cat /etc/machine-id" | tr -d '\r\n')
+  [[ $OLD_ID =~ ^[0-9a-f]{32}$ ]] || { echo "unexpected machine-id: $OLD_ID" >&2; return 1; }
+
+  ssh_sudo "cp /boot/limine.conf /boot/limine.conf.pretest" >/dev/null
+  ssh_sudo "
+    set -euo pipefail
+    awk '/^\//{block=1} block' /boot/limine.conf |
+      sed -e 's/$OLD_ID/$FOREIGN_ID/g' \
+          -e 's|/EFI/Linux/omarchy_|/EFI/Linux/foreign_|g' \
+          -e 's|^/\(+\{0,1\}\)\([^/+]\)|/\1Foreign \2|' >/tmp/foreign-entries
+    grep -q 'machine-id=$FOREIGN_ID' /tmp/foreign-entries
+    for uki in /boot/EFI/Linux/omarchy_*.efi; do
+      cp \"\$uki\" \"\${uki/omarchy_/foreign_}\"
+    done
+    cat >>/boot/limine.conf <<'CONF'
+
+/Windows
+    protocol: efi
+    path: boot():/EFI/Microsoft/Boot/bootmgfw.efi
+CONF
+    cat /tmp/foreign-entries >>/boot/limine.conf
+    mkdir -p /boot/$FOREIGN_ID /boot/EFI/Microsoft/Boot
+    echo foreign-payload >/boot/$FOREIGN_ID/marker
+    echo windows-payload >/boot/EFI/Microsoft/Boot/bootmgfw.efi
+  " >/dev/null
+
+  ssh_sudo "cat /boot/limine.conf" >"$RUN_DIR/limine.conf.fixtured"
+  log "ESP fixtured as a shared dual-boot ESP (old machine-id $OLD_ID)"
+}
+
+# ------------------------------------------------------------- reset driver
+
+# Drive the interactive reset through a pty on the guest: `script` supplies
+# the terminal gum needs, a fifo feeds it answers on our schedule, and the
+# typescript lands in /tmp/reset.out for the polling below.
+start_reset() {
+  # script hands the pty over at 0x0 when its own stdin is not a terminal,
+  # which crashes gum's text input; give it a real size first. setsid keeps
+  # both processes alive after this ssh session hangs up.
+  ssh_guest "
+    rm -f /tmp/reset.in /tmp/reset.out
+    mkfifo /tmp/reset.in
+    setsid bash -c 'exec 3<>/tmp/reset.in && sleep 3600' >/dev/null 2>&1 &
+    setsid script -qefc 'stty rows 35 cols 130; sudo -S -p \"\" omarchy-system-factory-reset' /tmp/reset.out \
+      </tmp/reset.in >/dev/null 2>&1 &
+  "
+  sleep 2
+  ssh_guest "printf '%s\n' '$GUEST_PASSWORD' >/tmp/reset.in"
+}
+
+reset_output() {
+  ssh_guest "sed 's/\x1b\[[0-9;?]*[A-Za-z]//g; s/\x1b\][^\x07]*\x07//g' /tmp/reset.out 2>/dev/null" || true
+}
+
+wait_for_reset_output() {
+  local text="$1" timeout="$2" waited=0
+
+  until reset_output | grep -qi "$text"; do
+    if reset_output | grep -qE "^Error:|COMMAND_EXIT_CODE"; then
+      reset_output >"$RUN_DIR/reset.out"
+      echo "The factory reset failed before reaching: $text" >&2
+      reset_output | grep -E "^Error:" >&2 || true
+      return 1
+    fi
+    if ((waited >= timeout)); then
+      reset_output >"$RUN_DIR/reset.out"
+      echo "Timed out after ${timeout}s waiting for reset output: $text" >&2
+      return 1
+    fi
+    sleep 3
+    ((waited += 3))
+  done
+}
+
+reset_phase() {
+  log "Booting reset VM from base image overlay"
+
+  start_vm_from_base
+  wait_for_ssh "$BOOT_TIMEOUT"
+
+  fixture_shared_esp
+
+  log "Running omarchy-system-factory-reset"
+  start_reset
+  wait_for_reset_output "Type 'reset' to continue" 60
+  capture_console "success-reset-confirm"
+  ssh_guest "printf 'reset\r' >/tmp/reset.in"
+
+  # Staging clones @factory, rebuilds the UKI in a chroot, and reworks the
+  # ESP; only then does the reboot prompt appear.
+  wait_for_reset_output "Reboot to complete the reset" 900
+  reset_output >"$RUN_DIR/reset.out"
+  log "Reset staged. Asserting on the shared ESP before rebooting."
+
+  check "windows entry survives staging" \
+    ssh_sudo "grep -q '^/Windows' /boot/limine.conf"
+  check "windows boot payload survives staging" \
+    ssh_sudo "grep -q windows-payload /boot/EFI/Microsoft/Boot/bootmgfw.efi"
+  check "foreign linux entry survives staging" \
+    ssh_sudo "grep -q 'machine-id=$FOREIGN_ID' /boot/limine.conf"
+  check "foreign boot directory survives staging" \
+    ssh_sudo "grep -q foreign-payload /boot/$FOREIGN_ID/marker"
+  check "foreign UKI survives staging" \
+    ssh_sudo "test -f /boot/EFI/Linux/foreign_linux.efi"
+  check "old omarchy entry is removed by staging" \
+    ssh_sudo "! grep -q 'machine-id=$OLD_ID' /boot/limine.conf"
+  check "old omarchy boot directory is removed by staging" \
+    ssh_sudo "! test -e /boot/$OLD_ID"
+  check "a fresh omarchy entry exists after staging" \
+    ssh_sudo "grep -o 'machine-id=[0-9a-f]\{32\}' /boot/limine.conf | grep -qv 'machine-id=$FOREIGN_ID'"
+
+  ssh_sudo "cat /boot/limine.conf" >"$RUN_DIR/limine.conf.staged" || true
+  ssh_sudo "cat /var/log/omarchy-system-factory-reset.log" >"$RUN_DIR/factory-reset.log" || true
+  capture_console "success-reset-staged"
+
+  if ((FAILURES > 0)); then
+    log "Staging assertions failed; keeping the VM off the reboot path."
+    return 1
+  fi
+
+  # Decline the prompt's reboot; reboot deliberately so the ssh session
+  # closing cannot race the answer.
+  ssh_guest "printf 'n' >/tmp/reset.in"
+  sleep 2
+  log "Rebooting into the factory first boot"
+  ssh_sudo "systemctl reboot" || true
+}
+
+# --------------------------------------------------------------- first boot
+
+# Answer whichever setup screens the factory first boot presents. The form's
+# exact steps depend on what the reset deferred, so dispatch on the screen
+# actually showing instead of scripting a fixed sequence.
+drive_first_boot() {
+  log "Driving the factory first-boot setup"
+
+  # The reset must leave a bootable default: the machine has to reach the
+  # first-boot greeter on its own. A numeric default_entry pointing at a
+  # moved entry parks Limine at the menu instead — catch that explicitly,
+  # then boot the Omarchy entry by hand so the rest of the flow still runs.
+  if wait_for_screen "Opinionated" 120 2>/dev/null; then
+    printf 'ok - %s\n' "the machine boots into first-boot setup unattended"
+  else
+    if ocr_screen | grep -qi "Omarchy Bootloader"; then
+      printf 'not ok - %s\n' "the machine boots into first-boot setup unattended (parked at the Limine menu)"
+      ((FAILURES += 1))
+      capture_console "failure-firstboot-parked-at-menu"
+      log "Selecting the Omarchy entry manually to continue the run"
+      press down; sleep 1; press down; sleep 1; press down; sleep 1
+      press ret
+      wait_for_screen "Opinionated" 600
+    else
+      echo "Neither the greeter nor the Limine menu appeared" >&2
+      return 1
+    fi
+  fi
+  capture_console "success-firstboot-00-greeter"
+  press ret
+
+  local waited=0 text step
+  local -A answered=()
+  while true; do
+    text=$(ocr_screen)
+    step=""
+
+    if grep -qi "look right" <<<"$text"; then
+      capture_console "success-firstboot-03-review"
+      press ret
+      break
+    elif grep -qi "keyboard layout" <<<"$text"; then
+      step="keyboard"; [[ -v answered[$step] ]] || { capture_console "success-firstboot-01-keyboard"; press ret; }
+    elif grep -qi "Username" <<<"$text"; then
+      step="username"; [[ -v answered[$step] ]] || { type_text "$GUEST_USER"; press ret; }
+    elif grep -qi "Conf *irm" <<<"$text"; then
+      step="confirm"; [[ -v answered[$step] ]] || { type_text "$GUEST_PASSWORD"; press ret; }
+    elif grep -qi "Password" <<<"$text"; then
+      step="password"; [[ -v answered[$step] ]] || { type_text "$GUEST_PASSWORD"; press ret; }
+    elif grep -qi "Full name" <<<"$text"; then
+      step="fullname"; [[ -v answered[$step] ]] || { type_text "Omarchy Test"; press ret; }
+    elif grep -qi "Email address" <<<"$text"; then
+      step="email"; [[ -v answered[$step] ]] || { type_text "test@omarchy.org"; capture_console "success-firstboot-02-form"; press ret; }
+    elif grep -qi "Hostname" <<<"$text"; then
+      step="hostname"; [[ -v answered[$step] ]] || { type_text "$GUEST_HOSTNAME"; press ret; }
+    elif grep -qi "Timezone" <<<"$text"; then
+      step="timezone"; [[ -v answered[$step] ]] || press ret
+    fi
+    [[ -n $step ]] && answered[$step]=1
+
+    if ! vm_running; then
+      echo "VM exited during first-boot setup" >&2
+      return 1
+    fi
+    if ((waited >= 600)); then
+      capture_console "failure-firstboot-form-timeout"
+      echo "Timed out driving the first-boot form" >&2
+      return 1
+    fi
+    sleep 3
+    ((waited += 3))
+  done
+
+  capture_console "success-firstboot-04-finalizing"
+}
+
+first_boot_phase() {
+  drive_first_boot
+
+  # Finalization can still be running when the console appears; the pending
+  # flag clearing is the definitive end of provisioning. The reset scrubbed
+  # users, host keys, and sshd state, so SSH has to be re-authorized first.
+  bootstrap_ssh
+
+  log "Waiting for provisioning to finish"
+  local waited=0 rc
+  while true; do
+    rc=0
+    ssh_guest "test -f /var/lib/omarchy/provisioning/pending" 2>/dev/null || rc=$?
+    (( rc == 0 || rc == 255 )) || break
+    if ((waited >= 900)); then
+      capture_console "failure-provisioning-timeout"
+      echo "Timed out waiting for first-boot provisioning to complete" >&2
+      return 1
+    fi
+    sleep 10
+    ((waited += 10))
+  done
+
+  local new_id
+  new_id=$(ssh_guest "cat /etc/machine-id" | tr -d '\r\n')
+
+  check "provisioning completed on first boot" \
+    ssh_guest "! test -f /var/lib/omarchy/provisioning/pending"
+  # A well-formed identity, and not one we already know: an empty or echoed
+  # ID would make the boot-entry grep below match the wrong entry.
+  check "the reset minted a fresh machine identity" \
+    bash -c "[[ '$new_id' =~ ^[0-9a-f]{32}\$ && '$new_id' != '$OLD_ID' && '$new_id' != '$FOREIGN_ID' ]]"
+  check "windows entry survives the first boot" \
+    ssh_sudo "grep -q '^/Windows' /boot/limine.conf"
+  check "windows boot payload survives the first boot" \
+    ssh_sudo "grep -q windows-payload /boot/EFI/Microsoft/Boot/bootmgfw.efi"
+  check "foreign linux entry survives the first boot" \
+    ssh_sudo "grep -q 'machine-id=$FOREIGN_ID' /boot/limine.conf"
+  check "foreign boot directory survives the first boot" \
+    ssh_sudo "grep -q foreign-payload /boot/$FOREIGN_ID/marker"
+  check "foreign UKI survives the first boot" \
+    ssh_sudo "test -f /boot/EFI/Linux/foreign_linux.efi"
+  check "old omarchy identity never returns" \
+    ssh_sudo "! grep -q 'machine-id=$OLD_ID' /boot/limine.conf"
+  check "the new identity owns a boot entry" \
+    ssh_sudo "grep -q 'machine-id=$new_id' /boot/limine.conf"
+
+  ssh_sudo "cat /boot/limine.conf" >"$RUN_DIR/limine.conf.final" || true
+  capture_console "success-final"
+}
+
+# ---------------------------------------------------------------------- main
+
+reset_phase
+first_boot_phase
+finish

test/unit/cidata-load-test.sh

@@ -0,0 +1,224 @@
+#!/bin/bash
+#
+# Unit tests for omarchy-cidata-load. The script takes a path prefix, so every
+# case runs against a throwaway sandbox with mount/umount/udevadm stubbed out:
+# "mounting" copies the fake drive's contents into the mountpoint, and every
+# stub logs its invocation so the cases can assert what was (not) called.
+
+set -euo pipefail
+
+ROOT=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd)
+CIDATA_LOAD="$ROOT/configs/airootfs/usr/local/bin/omarchy-cidata-load"
+
+pass() {
+  printf 'ok - %s\n' "$1"
+}
+
+fail() {
+  local description="$1"
+  local detail="${2:-}"
+
+  [[ -n $detail ]] && printf '%s\n' "$detail" >&2
+  printf 'not ok - %s\n' "$description" >&2
+  exit 1
+}
+
+work=$(mktemp -d)
+trap 'chmod -R u+w "$work"; rm -rf "$work"' EXIT
+
+stub_dir="$work/stubs"
+mkdir -p "$stub_dir"
+
+cat >"$stub_dir/udevadm" <<'STUB'
+#!/bin/bash
+printf 'udevadm %s\n' "$*" >>"$TEST_LOG"
+STUB
+
+cat >"$stub_dir/mount" <<'STUB'
+#!/bin/bash
+printf 'mount %s\n' "$*" >>"$TEST_LOG"
+[[ ${MOUNT_FAIL:-} == 1 ]] && exit 32
+device=$3 mountpoint=$4
+cp -a "$(readlink -f "$device")"/. "$mountpoint"/
+STUB
+
+cat >"$stub_dir/umount" <<'STUB'
+#!/bin/bash
+printf 'umount %s\n' "$*" >>"$TEST_LOG"
+STUB
+
+chmod +x "$stub_dir"/*
+
+new_sandbox() {
+  sandbox=$(mktemp -d "$work/sandbox.XXXXXX")
+  mkdir -p "$sandbox/dev/disk/by-label" "$sandbox/root" "$sandbox/media"
+  export TEST_LOG="$sandbox/calls.log"
+  : >"$TEST_LOG"
+}
+
+attach_drive() {
+  ln -s "$sandbox/media" "$sandbox/dev/disk/by-label/$1"
+}
+
+run_load() {
+  PATH="$stub_dir:$PATH" "$CIDATA_LOAD" "$sandbox"
+}
+
+write_required_pair() {
+  echo '{"disk_config": {}}' >"$sandbox/media/user_configuration.json"
+  echo '{"users": []}' >"$sandbox/media/user_credentials.json"
+}
+
+# No cidata drive attached: fall back to the wizard without mounting anything.
+new_sandbox
+! run_load || fail "no drive exits non-zero"
+! grep -q '^mount ' "$TEST_LOG" || fail "no drive mounts nothing"
+pass "no drive falls back to the wizard"
+
+# The probe must wait for udev to finish enumerating before concluding there
+# is no drive.
+grep -q '^udevadm settle$' "$TEST_LOG" || fail "probe settles udev first"
+pass "probe settles udev first"
+
+# A drive with the full file set: everything lands in /root and the drive is
+# unmounted afterwards.
+new_sandbox
+attach_drive cidata
+write_required_pair
+echo "Jeff" >"$sandbox/media/user_full_name.txt"
+echo "jeff@example.com" >"$sandbox/media/user_email_address.txt"
+echo "false" >"$sandbox/media/user_encrypt_installation.txt"
+echo 'ssh-ed25519 AAAA jeff@host' >"$sandbox/media/authorized_keys"
+echo 'tskey-auth-kFAKEKEY' >"$sandbox/media/tailscale_authkey"
+run_load || fail "full file set loads"
+for file in user_configuration.json user_credentials.json user_full_name.txt user_email_address.txt user_encrypt_installation.txt authorized_keys tailscale_authkey; do
+  [[ -f $sandbox/root/$file ]] || fail "full file set copies $file"
+done
+grep -q '^umount ' "$TEST_LOG" || fail "full file set unmounts the drive"
+pass "full file set loads, copies everything, and unmounts"
+
+# The uppercase label variant some tools produce works too.
+new_sandbox
+attach_drive CIDATA
+write_required_pair
+run_load || fail "uppercase CIDATA label loads"
+pass "uppercase CIDATA label loads"
+
+# The required pair alone is a valid autoinstall drive; the optional files
+# stay optional.
+new_sandbox
+attach_drive cidata
+write_required_pair
+run_load || fail "required pair alone loads"
+[[ ! -e $sandbox/root/authorized_keys ]] || fail "required pair alone copies no optional files"
+pass "required pair alone loads without optional files"
+
+# Optional files are copied individually when present.
+new_sandbox
+attach_drive cidata
+write_required_pair
+echo 'ssh-ed25519 AAAA jeff@host' >"$sandbox/media/authorized_keys"
+run_load || fail "required pair plus authorized_keys loads"
+[[ -f $sandbox/root/authorized_keys ]] || fail "authorized_keys is copied when present"
+[[ ! -e $sandbox/root/user_full_name.txt ]] || fail "absent optional files are not copied"
+[[ ! -e $sandbox/root/tailscale_authkey ]] || fail "absent tailscale_authkey is not copied"
+pass "present optional files are copied, absent ones skipped"
+
+# A defer-provisioning marker replaces user_credentials.json: deferred-provisioning installs
+# creation to first boot, so imaging rigs ship no credentials at all.
+new_sandbox
+attach_drive cidata
+echo '{"disk_config": {}}' >"$sandbox/media/user_configuration.json"
+: >"$sandbox/media/defer-provisioning"
+run_load || fail "config plus defer-provisioning marker loads"
+[[ -f $sandbox/root/defer-provisioning ]] || fail "defer-provisioning marker is copied"
+[[ ! -e $sandbox/root/user_credentials.json ]] || fail "defer-provisioning drive copies no credentials"
+pass "defer-provisioning marker stands in for credentials"
+
+# The defer-provisioning marker and credentials can coexist (rig supplies its own LUKS
+# passphrase in the credentials file); both are copied.
+new_sandbox
+attach_drive cidata
+write_required_pair
+: >"$sandbox/media/defer-provisioning"
+run_load || fail "defer-provisioning marker plus credentials loads"
+[[ -f $sandbox/root/defer-provisioning && -f $sandbox/root/user_credentials.json ]] || fail "both defer-provisioning marker and credentials are copied"
+pass "defer-provisioning marker plus credentials copies both"
+
+# An defer-provisioning marker without the configuration is still not an autoinstall drive.
+new_sandbox
+attach_drive cidata
+: >"$sandbox/media/defer-provisioning"
+! run_load || fail "defer-provisioning marker alone is not an autoinstall drive"
+[[ ! -e $sandbox/root/defer-provisioning ]] || fail "defer-provisioning marker alone copies nothing"
+pass "defer-provisioning marker alone falls back to the wizard"
+
+# Stale deferred-provisioning inputs from a previous load in the same session are cleared before
+# the current drive is copied: a normal drive must not inherit an old defer-provisioning
+# marker or credentials.
+new_sandbox
+attach_drive cidata
+write_required_pair
+: >"$sandbox/root/defer-provisioning"                       # leftover from a prior deferred-provisioning load
+echo 'old-keys' >"$sandbox/root/authorized_keys"
+run_load || fail "normal drive after a stale defer-provisioning load loads"
+[[ ! -e $sandbox/root/defer-provisioning ]] || fail "stale defer-provisioning marker is cleared"
+[[ ! -e $sandbox/root/authorized_keys ]] || fail "stale optional inputs are cleared"
+pass "stale deferred-provisioning inputs are cleared before loading a normal drive"
+
+# A drive that isn't an autoinstall drive at all still clears stale inputs so
+# the wizard that follows doesn't inherit them.
+new_sandbox
+attach_drive cidata
+echo '{"disk_config": {}}' >"$sandbox/media/user_configuration.json" # half a pair
+: >"$sandbox/root/defer-provisioning"
+! run_load || fail "half-pair drive still falls back"
+[[ ! -e $sandbox/root/defer-provisioning ]] || fail "stale defer-provisioning marker cleared even on fallback"
+pass "stale inputs are cleared even when falling back to the wizard"
+
+# Half the required pair is not an autoinstall drive: unmount and fall back.
+new_sandbox
+attach_drive cidata
+echo '{"disk_config": {}}' >"$sandbox/media/user_configuration.json"
+! run_load || fail "half the required pair exits non-zero"
+[[ ! -e $sandbox/root/user_configuration.json ]] || fail "half the required pair copies nothing"
+grep -q '^umount ' "$TEST_LOG" || fail "half the required pair still unmounts"
+pass "half the required pair falls back and unmounts"
+
+# An empty drive labeled cidata is not an autoinstall drive either.
+new_sandbox
+attach_drive cidata
+! run_load || fail "empty drive exits non-zero"
+grep -q '^umount ' "$TEST_LOG" || fail "empty drive still unmounts"
+pass "empty drive falls back and unmounts"
+
+# A drive that will not mount falls back rather than failing the boot.
+new_sandbox
+attach_drive cidata
+write_required_pair
+! MOUNT_FAIL=1 run_load || fail "mount failure exits non-zero"
+! grep -q '^umount ' "$TEST_LOG" || fail "mount failure has nothing to unmount"
+pass "mount failure falls back to the wizard"
+
+# A copy failure must not report a loaded drive: the install would start with
+# missing inputs. Fall back and let the wizard produce them instead.
+new_sandbox
+attach_drive cidata
+write_required_pair
+chmod 555 "$sandbox/root"
+! run_load 2>/dev/null || fail "copy failure exits non-zero"
+grep -q '^umount ' "$TEST_LOG" || fail "copy failure still unmounts"
+pass "copy failure falls back and unmounts"
+
+# A partial copy must clean up after itself: the wizard removes only what it
+# writes, so anything the loader left behind would leak into the interactive
+# install that follows.
+new_sandbox
+attach_drive cidata
+write_required_pair
+echo 'ssh-ed25519 AAAA jeff@host' >"$sandbox/media/authorized_keys"
+mkdir "$sandbox/root/user_credentials.json"
+! run_load 2>/dev/null || fail "partial copy exits non-zero"
+[[ ! -e $sandbox/root/user_configuration.json ]] || fail "partial copy removes what it copied"
+[[ ! -e $sandbox/root/authorized_keys ]] || fail "partial copy leaves no authorized_keys behind"
+pass "partial copy cleans up what it copied"

test/unit/install-media-diagnosis-test.sh

@@ -0,0 +1,452 @@
+#!/bin/bash
+#
+# Unit tests for omarchy-install-diagnose-media and the failure screen that
+# renders it. Every case builds a throwaway offline mirror -- a package file
+# and a real repo-add-shaped offline.db naming its sha256 -- so the three
+# verdicts are told apart by the same evidence the live ISO has.
+
+set -euo pipefail
+
+ROOT=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd)
+DIAGNOSE="$ROOT/configs/airootfs/usr/local/bin/omarchy-install-diagnose-media"
+DASHBOARD="$ROOT/configs/airootfs/usr/local/bin/omarchy-install-dashboard"
+PACKAGE="npth-1.8-1-x86_64.pkg.tar.zst"
+TARGET_CACHE="/mnt/var/cache/pacman/pkg"
+
+pass() {
+  printf 'ok - %s\n' "$1"
+}
+
+fail() {
+  local description="$1"
+  local detail="${2:-}"
+
+  [[ -n $detail ]] && printf '%s\n' "$detail" >&2
+  printf 'not ok - %s\n' "$description" >&2
+  exit 1
+}
+
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+
+mirror="$work/mirror"
+mkdir -p "$mirror"
+
+# repo-add writes one desc record per package, %FILENAME% before %SHA256SUM%.
+# Building a real gzipped tar of that shape keeps the parser honest.
+write_mirror_db() {
+  local checksum="$1" filename="${2:-$PACKAGE}" staging="$work/db"
+
+  rm -rf "$staging"
+  mkdir -p "$staging/npth-1.8-1"
+  {
+    printf '%%FILENAME%%\n%s\n\n' "$filename"
+    printf '%%NAME%%\nnpth\n\n'
+    printf '%%VERSION%%\n1.8-1\n\n'
+    printf '%%SHA256SUM%%\n%s\n\n' "$checksum"
+  } >"$staging/npth-1.8-1/desc"
+
+  # A second package proves the lookup matches on name rather than on order.
+  mkdir -p "$staging/zlib-1.3-1"
+  {
+    printf '%%FILENAME%%\nzlib-1.3-1-x86_64.pkg.tar.zst\n\n'
+    printf '%%NAME%%\nzlib\n\n'
+    printf '%%SHA256SUM%%\n%s\n\n' "$(printf 'f%.0s' {1..64})"
+  } >"$staging/zlib-1.3-1/desc"
+
+  tar -czf "$mirror/offline.db" -C "$staging" npth-1.8-1 zlib-1.3-1
+}
+
+write_log() {
+  local log="$1" path="${2:-$TARGET_CACHE/$PACKAGE}"
+
+  {
+    echo "[dashboard] checking package integrity..."
+    echo "[dashboard] :: File $path is corrupted (invalid or corrupted package)."
+    echo "[dashboard] error: failed to commit transaction (invalid or corrupted package)"
+    echo "[dashboard] ==> ERROR: Failed to install packages to new root"
+  } >"$log"
+}
+
+diagnose() {
+  OMARCHY_OFFLINE_MIRROR="$mirror" OMARCHY_TARGET_PACKAGE_CACHE="$TARGET_CACHE" \
+    "$DIAGNOSE" "$@"
+}
+
+log="$work/install.log"
+write_log "$log"
+
+# The medium was written wrong: the package on the ISO no longer hashes to what
+# the build recorded for it.
+printf 'a package, but damaged\n' >"$mirror/$PACKAGE"
+write_mirror_db "$(printf '0%.0s' {1..64})"
+
+set +e
+output=$(diagnose "$log")
+status=$?
+set -e
+
+(( status == 0 )) || fail "a checksum mismatch is diagnosed" "exit status $status"
+[[ $(head -n 1 <<<"$output") == "The install medium is damaged" ]] ||
+  fail "a checksum mismatch is diagnosed" "$output"
+grep -qF "$PACKAGE" <<<"$output" ||
+  fail "the diagnosis names the package" "$output"
+grep -qF "no longer matches the checksum" <<<"$output" ||
+  fail "the diagnosis says the checksum disagrees" "$output"
+grep -qF "sha256sum" <<<"$output" ||
+  fail "the diagnosis says how to verify a fresh download" "$output"
+pass "a checksum mismatch says the medium is damaged and names the package"
+
+# The medium reads clean now, so the bytes were misread rather than written
+# wrong. Re-downloading fixes nothing, and the advice has to say so.
+write_mirror_db "$(sha256sum "$mirror/$PACKAGE" | cut -d " " -f 1)"
+
+set +e
+output=$(diagnose "$log")
+status=$?
+set -e
+
+(( status == 0 )) || fail "an intact package is still diagnosed" "exit status $status"
+[[ $(head -n 1 <<<"$output") == "The install medium was misread" ]] ||
+  fail "an intact package is diagnosed as a misread" "$output"
+grep -qF "another USB port" <<<"$output" ||
+  fail "a misread points at the hardware" "$output"
+if grep -qF "Re-download" <<<"$output"; then
+  fail "a misread does not send anyone to re-download" "$output"
+fi
+pass "an intact package on the medium is diagnosed as a misread, not a bad download"
+
+# The usual case. pacstrap runs with --noconfirm, which answers yes to pacman's
+# "delete it?" and unlinks the package through the bind mount, so by the time
+# anything here looks there is nothing left to weigh. The verdict must name the
+# medium without claiming a comparison it never made, and must offer both
+# remedies: a bad write and a bad read leave identical evidence.
+rm "$mirror/$PACKAGE"
+
+set +e
+output=$(diagnose "$log")
+status=$?
+set -e
+
+(( status == 0 )) || fail "a deleted package is still diagnosed" "exit status $status"
+[[ $(head -n 1 <<<"$output") == "The install medium is damaged or misread" ]] ||
+  fail "a deleted package is diagnosed without over-claiming" "$output"
+grep -qF "read straight off this ISO" <<<"$output" ||
+  fail "a deleted package still names the medium" "$output"
+grep -qF "sha256sum" <<<"$output" ||
+  fail "a deleted package offers the download remedy" "$output"
+grep -qF "memory is at fault" <<<"$output" ||
+  fail "a deleted package offers the hardware remedy too" "$output"
+if grep -qF "no longer matches the checksum" <<<"$output"; then
+  fail "a deleted package claims no comparison" "$output"
+fi
+pass "a deleted package names the medium without claiming which way it failed"
+
+# A record with no %SHA256SUM% must not borrow the next record's, which would
+# compare a real file against another package's checksum.
+printf 'a package, but damaged\n' >"$mirror/$PACKAGE"
+staging="$work/db"
+rm -rf "$staging"
+mkdir -p "$staging/npth-1.8-1" "$staging/zlib-1.3-1"
+printf '%%FILENAME%%\n%s\n\n%%NAME%%\nnpth\n\n' "$PACKAGE" >"$staging/npth-1.8-1/desc"
+{
+  printf '%%FILENAME%%\nzlib-1.3-1-x86_64.pkg.tar.zst\n\n'
+  printf '%%SHA256SUM%%\n%s\n\n' "$(sha256sum "$mirror/$PACKAGE" | cut -d " " -f 1)"
+} >"$staging/zlib-1.3-1/desc"
+tar -czf "$mirror/offline.db" -C "$staging" npth-1.8-1 zlib-1.3-1
+
+set +e
+output=$(diagnose "$log")
+set -e
+
+[[ $(head -n 1 <<<"$output") == "The install medium is damaged or misread" ]] ||
+  fail "a record without a checksum borrows nobody else's" "$output"
+pass "a record without a checksum borrows nobody else's"
+
+# A package version may legally hold a backslash. It must not reach a terminal
+# as an escape sequence, and awk must look it up literally rather than as one.
+escaped='demo-1\033[2J-1-x86_64.pkg.tar.zst'
+write_log "$work/escaped.log" "$TARGET_CACHE/$escaped"
+printf 'a package, but damaged\n' >"$mirror/$escaped"
+write_mirror_db "$(printf '0%.0s' {1..64})" "$escaped"
+
+set +e
+output=$(diagnose "$work/escaped.log")
+set -e
+
+# The dashboard renders these lines through printf %b, which turns a surviving
+# backslash into whatever escape it spells. None may reach it.
+if grep -qF '\' <<<"$output"; then
+  fail "a backslash in a package name never reaches the renderer" "$(cat -v <<<"$output")"
+fi
+grep -qF "demo-1033" <<<"$output" ||
+  fail "the sanitized name still identifies the package" "$output"
+# The database record is found despite the backslash, so the verdict is the
+# mismatch rather than the one that means no comparison could be made.
+[[ $(head -n 1 <<<"$output") == "The install medium is damaged" ]] ||
+  fail "a backslash in a package name is looked up literally" "$output"
+pass "a backslash in a package name is looked up literally and never rendered as an escape"
+rm "$mirror/$escaped"
+
+# The live ISO has bsdtar through pacman's libarchive, but the tar fallback is
+# the one that runs if that ever stops being true.
+printf 'a package, but damaged\n' >"$mirror/$PACKAGE"
+write_mirror_db "$(sha256sum "$mirror/$PACKAGE" | cut -d " " -f 1)"
+no_bsdtar="$work/no-bsdtar"
+mkdir -p "$no_bsdtar"
+for tool in sed awk tar gzip sha256sum cat grep head tail cut printf; do
+  command -v "$tool" >/dev/null && ln -sf "$(command -v "$tool")" "$no_bsdtar/$tool"
+done
+
+set +e
+output=$(PATH="$no_bsdtar" diagnose "$log")
+set -e
+
+[[ $(head -n 1 <<<"$output") == "The install medium was misread" ]] ||
+  fail "the tar fallback reads the database when bsdtar is absent" "$output"
+pass "the tar fallback reads the database when bsdtar is absent"
+
+printf 'a package, but damaged\n' >"$mirror/$PACKAGE"
+write_mirror_db "$(printf '0%.0s' {1..64})"
+
+# A corrupt package that was never read off this ISO is somebody else's
+# problem. Guessing here sends people to buy a USB stick they did not need.
+write_log "$work/elsewhere.log" "/var/tmp/build/$PACKAGE"
+
+set +e
+output=$(diagnose "$work/elsewhere.log")
+status=$?
+set -e
+
+(( status == 1 )) || fail "corruption outside the target cache is not diagnosed" "exit $status: $output"
+[[ -z $output ]] || fail "corruption outside the target cache prints nothing" "$output"
+pass "corruption outside the target cache is not blamed on the medium"
+
+# An ordinary failure has no media diagnosis, and the caller asks
+# unconditionally, so silence has to be the answer.
+printf 'error: something else went wrong entirely\n' >"$work/other.log"
+
+set +e
+output=$(diagnose "$work/other.log")
+status=$?
+set -e
+
+(( status == 1 )) || fail "an unrelated failure is not diagnosed" "exit $status: $output"
+[[ -z $output ]] || fail "an unrelated failure prints nothing" "$output"
+pass "an unrelated failure produces no diagnosis"
+
+set +e
+output=$(diagnose "$work/does-not-exist.log")
+status=$?
+set -e
+
+(( status == 1 )) || fail "a missing log is not diagnosed" "exit $status: $output"
+pass "a missing log produces no diagnosis"
+
+# End to end: the dashboard runs a failing installer and the diagnosis has to
+# reach both the screen and the support log, above the tail it explains.
+#
+# The screen goes through a real pty rather than a file. The dashboard's exit
+# handler reopens its TTY with a truncating redirect, which does nothing to a
+# character device and empties a regular file, so a file would capture nothing.
+stubs="$work/stubs"
+mkdir -p "$stubs"
+{
+  echo '#!/bin/bash'
+  echo "OMARCHY_OFFLINE_MIRROR='$mirror' OMARCHY_TARGET_PACKAGE_CACHE='$TARGET_CACHE' exec '$DIAGNOSE' \"\$@\""
+} >"$stubs/omarchy-install-diagnose-media"
+chmod +x "$stubs/omarchy-install-diagnose-media"
+
+state_file="$work/state.json"
+screen="$work/screen"
+
+# A ten-line logo, the height of the real one. Without it the dashboard falls
+# back to a single centred word and the screen can never be tall enough to
+# overflow, which is exactly the case worth testing.
+omarchy_share="$work/share"
+mkdir -p "$omarchy_share"
+# 81 columns wide, like the real logo: the dashboard takes its content width
+# from the logo, and a narrow one would truncate every line under test.
+{
+  printf 'LOGO TOP ROW%*s\n' 69 ''
+  for n in 2 3 4 5 6 7 8 9; do printf 'logo row %s%*s\n' "$n" 71 ''; done
+  printf 'logo bottom row%*s\n' 66 ''
+} >"$omarchy_share/logo.txt"
+
+run_dashboard() {
+  local install_log="$1"
+
+  # A real failure carries the failed phase as well as the current one, and
+  # that second summary line is another row the screen has to find space for.
+  cat >"$state_file" <<'STATE'
+{"current_phase": "Installing Arch + Omarchy",
+ "phases": [{"name": "Installing Arch + Omarchy", "status": "failed",
+             "error": "Pacstrap failed. See /var/log/archinstall.log"}]}
+STATE
+  : >"$screen"
+  script -qefc "stty rows 40 cols 120; PATH='$stubs:$PATH' OMARCHY_PATH='$omarchy_share' OMARCHY_UI_INTERACTIVE=no OMARCHY_UI_FAILURE_ACTION=exit OMARCHY_FAILURE_TAIL_LOG='$install_log' '$DASHBOARD' '$install_log' '$state_file' -- bash -c 'exit 1'" \
+    "$screen" >/dev/null 2>&1
+}
+
+visible_screen() {
+  # Carriage returns as well as escapes: the pty ends every line with one, and
+  # a row that looks blank still carries it.
+  sed -E $'s/\x1b\\[[0-9;?]*[A-Za-z]//g; s/\r//g' "$screen"
+}
+
+dashboard_log="$work/dashboard.log"
+write_log "$dashboard_log"
+
+# A real install log is longer than the tail can show, so the tail actually
+# spends its whole budget. A short one hides an over-tall screen.
+{
+  for n in $(seq 1 20); do printf '[dashboard] installing package %s\n' "$n"; done
+  cat "$dashboard_log"
+} >"$dashboard_log.padded"
+mv "$dashboard_log.padded" "$dashboard_log"
+
+# State the case rather than inheriting whichever verdict the previous one left
+# behind: this is the shape a real install fails in, with pacman having deleted
+# the package it rejected.
+rm -f "$mirror/$PACKAGE"
+write_mirror_db "$(printf '0%.0s' {1..64})"
+
+set +e
+run_dashboard "$dashboard_log"
+dashboard_status=$?
+set -e
+
+(( dashboard_status == 1 )) ||
+  fail "the dashboard still exits with the installer's status" "exit $dashboard_status"
+visible_screen | grep -qF "The install medium is damaged" ||
+  fail "the failure screen shows the diagnosis" "$(visible_screen | tail -n 25)"
+visible_screen | grep -qF "$PACKAGE" ||
+  fail "the failure screen names the package" "$(visible_screen | tail -n 25)"
+grep -qF "[dashboard] The install medium is damaged" "$dashboard_log" ||
+  fail "the diagnosis is written to the support log" "$(tail -n 20 "$dashboard_log")"
+
+# Once on the screen. The log tail rendered underneath reads the same file the
+# diagnosis is recorded in, and the same finding printed twice reads as two.
+headline_count=$(visible_screen | grep -cF "The install medium is damaged or misread" || true)
+(( headline_count == 1 )) ||
+  fail "the diagnosis appears once on the screen" "found $headline_count times"
+
+# The renderer used to drop blank lines, so the break has to be checked where
+# it matters: on the screen, not only in the text the helper produced.
+package_row=$(visible_screen | grep -nF "$PACKAGE" | grep -v "dashboard" | head -n 1 | cut -d: -f1)
+[[ -n $package_row ]] ||
+  fail "the screen names the package on its own row" "$(visible_screen | tail -n 25)"
+next_row=$(visible_screen | sed -n "$((package_row + 1))p")
+[[ -z ${next_row// /} ]] ||
+  fail "the screen breaks after the package" "next row was: $next_row"
+pass "the dashboard renders the diagnosis once, with the break, and logs it"
+
+# The diagnosis costs rows the log tail's budget knew nothing about, so a
+# screen carrying one scrolled its own logo off the top of the console. The
+# tail gives those rows back now, which is visible as a shorter tail: count the
+# filler lines it reaches, with a diagnosis and without one.
+#
+# Asserting the logo is still on screen would be the direct test, and it cannot
+# be written here: this reads the output stream, which keeps every row ever
+# emitted whether or not it stayed visible. Only a terminal emulator could tell
+# the difference, so the mechanism is what gets checked.
+tail_filler_rows() {
+  visible_screen | grep -c "installing package" || true
+}
+
+with_diagnosis=$(tail_filler_rows)
+
+# The same log line for line, differing only in the one path that decides
+# whether there is a diagnosis at all. Two differently shaped logs would show
+# different amounts of filler for reasons that have nothing to do with the
+# budget, and the comparison would prove nothing.
+elsewhere_log="$work/elsewhere-padded.log"
+write_log "$elsewhere_log" "/var/tmp/build/$PACKAGE"
+{
+  for n in $(seq 1 20); do printf '[dashboard] installing package %s\n' "$n"; done
+  cat "$elsewhere_log"
+} >"$elsewhere_log.padded"
+mv "$elsewhere_log.padded" "$elsewhere_log"
+
+set +e
+run_dashboard "$elsewhere_log"
+set -e
+without_diagnosis=$(tail_filler_rows)
+
+(( with_diagnosis < without_diagnosis )) ||
+  fail "the tail gives up rows to the diagnosis" \
+    "with: $with_diagnosis, without: $without_diagnosis"
+pass "the log tail gives up rows to the diagnosis so the screen still fits"
+
+# The screen is only as wide as the logo and the dashboard truncates to it with
+# an ellipsis. Every sentence has to survive that, whatever the package is
+# called, or the advice arrives with its second half cut off.
+long_package="linux-firmware-nvidia-tegra-20250917.0e800e46-1-any.pkg.tar.zst"
+long_log="$work/long.log"
+write_log "$long_log" "$TARGET_CACHE/$long_package"
+
+check_widths() {
+  local label="$1" line
+  while IFS= read -r line; do
+    (( ${#line} <= 81 )) ||
+      fail "no diagnosis line outruns the screen ($label)" "${#line} chars: $line"
+  done < <(diagnose "$long_log")
+}
+
+# The package line and the remedy that follows it are two different thoughts,
+# so a blank line separates them in every verdict.
+check_break() {
+  local label="$1" package="$2" out
+  out=$(diagnose "$long_log")
+  local -a lines
+  mapfile -t lines <<<"$out"
+
+  local i
+  for i in "${!lines[@]}"; do
+    [[ ${lines[i]} == "$package" ]] || continue
+    [[ -z ${lines[i + 1]-x} ]] ||
+      fail "a break follows the package ($label)" "$out"
+    [[ -n ${lines[i + 2]-} ]] ||
+      fail "the remedy follows the break ($label)" "$out"
+    return 0
+  done
+  fail "the package is on a line of its own ($label)" "$out"
+}
+
+# All three verdicts, since each writes its own sentences.
+rm -f "$mirror/$long_package"
+check_widths "deleted"
+check_break "deleted" "$long_package"
+printf 'these are not the bytes that were built\n' >"$mirror/$long_package"
+write_mirror_db "$(printf '0%.0s' {1..64})" "$long_package"
+check_widths "damaged"
+check_break "damaged" "$long_package"
+write_mirror_db "$(sha256sum "$mirror/$long_package" | cut -d " " -f 1)" "$long_package"
+check_widths "misread"
+check_break "misread" "$long_package"
+rm -f "$mirror/$long_package"
+pass "no diagnosis line outruns the screen, even with a long package name"
+pass "a break separates the package from the remedy in every verdict"
+
+# A failure with no media explanation must leave the screen as it was, rather
+# than gaining a banner or an empty gap where the diagnosis would go.
+printf 'error: something else went wrong entirely\n' >"$work/plain.log"
+
+set +e
+run_dashboard "$work/plain.log"
+set -e
+
+if visible_screen | grep -qF "install medium"; then
+  fail "an unrelated failure gets no media banner" "$(visible_screen | tail -n 25)"
+fi
+visible_screen | grep -qF "Omarchy installation stopped" ||
+  fail "an unrelated failure still renders the normal failure screen" "$(visible_screen | tail -n 25)"
+pass "an unrelated failure renders the failure screen unchanged"
+
+# The failure menu redraws the screen after uploading or viewing the log, and a
+# redraw that drops the diagnosis loses it exactly when someone went looking.
+# Those paths need gum and a person at the keyboard, so they are checked here.
+missing_redraw=$(grep -n 'render_failure "' "$DASHBOARD" | grep -v 'failure_media_diagnosis' || true)
+[[ -z $missing_redraw ]] ||
+  fail "every failure-screen redraw carries the diagnosis" "$missing_redraw"
+pass "every failure-screen redraw carries the diagnosis"

test/unit/iso-release-checksum-test.sh

@@ -0,0 +1,175 @@
+#!/bin/bash
+#
+# Unit tests for the checksum sidecar omarchy-iso-release writes and
+# omarchy-iso-upload ships. Both scripts derive everything from their own
+# location and their argument, so each case runs against a throwaway sandbox
+# with the real script copied in and rclone/sign/upload stubbed out.
+
+set -euo pipefail
+
+ROOT=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd)
+
+pass() {
+  printf 'ok - %s\n' "$1"
+}
+
+fail() {
+  local description="$1"
+  local detail="${2:-}"
+
+  [[ -n $detail ]] && printf '%s\n' "$detail" >&2
+  printf 'not ok - %s\n' "$description" >&2
+  exit 1
+}
+
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+
+# omarchy-iso-release resolves its release directory from the script's own
+# path, so relocating the script is what points it at the sandbox.
+sandbox="$work/repo"
+mkdir -p "$sandbox/bin" "$sandbox/release" "$work/stubs"
+cp "$ROOT/bin/omarchy-iso-release" "$sandbox/bin/"
+printf 'not really an iso\n' >"$sandbox/release/omarchy-2099.01.01-x86_64-quattro.iso"
+
+cat >"$work/stubs/omarchy-iso-sign" <<'STUB'
+#!/bin/bash
+printf 'signature\n' >"$1.sig"
+STUB
+
+cat >"$work/stubs/omarchy-iso-upload" <<'STUB'
+#!/bin/bash
+printf 'upload %s\n' "$*" >>"$TEST_LOG"
+STUB
+
+# Log one argument per field rather than "$*": the point of several cases below
+# is that a path survives as a single argument, which "$*" cannot show.
+cat >"$work/stubs/rclone" <<'STUB'
+#!/bin/bash
+printf 'rclone'
+printf '|%s' "$@"
+printf '\n'
+[[ -n ${RCLONE_FAIL_ON:-} && $* == *"$RCLONE_FAIL_ON"* ]] && exit 1
+exit 0
+STUB
+
+chmod +x "$work/stubs"/*
+
+export TEST_LOG="$work/log"
+: >"$TEST_LOG"
+
+run_upload() {
+  PATH="$work/stubs:$PATH" "$ROOT/bin/omarchy-iso-upload" "$@" >"$work/rclone-log" 2>"$work/upload-err"
+}
+
+PATH="$work/stubs:$PATH" "$sandbox/bin/omarchy-iso-release" --no-make 9.9.9 >/dev/null
+
+release_iso="$sandbox/release/omarchy-9.9.9.iso"
+checksum_file="$release_iso.sha256"
+
+[[ -f $checksum_file ]] ||
+  fail "release writes a checksum beside the ISO" "missing: $checksum_file"
+pass "release writes a checksum beside the ISO"
+
+# The name in the file has to be the ISO alone. A build path in there verifies
+# only on the release machine, which is the one machine that never needs it.
+expected="$(sha256sum "$release_iso" | cut -d " " -f 1)  omarchy-9.9.9.iso"
+actual="$(cat "$checksum_file")"
+[[ $actual == "$expected" ]] ||
+  fail "the checksum names the ISO alone" "expected: $expected"$'\n'"actual:   $actual"
+pass "the checksum names the ISO alone"
+
+(cd "$sandbox/release" && sha256sum -c --status omarchy-9.9.9.iso.sha256) ||
+  fail "sha256sum -c verifies the ISO from its own directory"
+pass "sha256sum -c verifies the ISO from its own directory"
+
+# The whole point of the sidecar is catching bytes that changed after release,
+# so prove it fails on bytes that changed after release.
+printf 'corrupted\n' >>"$release_iso"
+if (cd "$sandbox/release" && sha256sum -c --status omarchy-9.9.9.iso.sha256 2>/dev/null); then
+  fail "sha256sum -c rejects a corrupted ISO"
+fi
+pass "sha256sum -c rejects a corrupted ISO"
+
+# An unreadable ISO must stop the release rather than publish an empty digest
+# beside a stale sidecar from the previous one.
+stale="$sandbox/release/omarchy-8.8.8.iso.sha256"
+printf 'deadbeef  omarchy-8.8.8.iso\n' >"$stale"
+rm "$sandbox/release/omarchy-2099.01.01-x86_64-quattro.iso"
+printf 'not really an iso\n' >"$sandbox/release/omarchy-2099.01.02-x86_64-quattro.iso"
+cp "$sandbox/release/omarchy-2099.01.02-x86_64-quattro.iso" "$sandbox/release/omarchy-8.8.8.iso"
+chmod 000 "$sandbox/release/omarchy-8.8.8.iso"
+
+set +e
+PATH="$work/stubs:$PATH" "$sandbox/bin/omarchy-iso-release" --no-make 8.8.8 >/dev/null 2>&1
+release_status=$?
+set -e
+chmod 644 "$sandbox/release/omarchy-8.8.8.iso"
+
+(( release_status != 0 )) ||
+  fail "release stops when the ISO cannot be checksummed" "exit status was 0"
+[[ "$(cat "$stale")" == "deadbeef  omarchy-8.8.8.iso" ]] ||
+  fail "a failed checksum leaves no half-written sidecar" "$(cat "$stale")"
+pass "release stops when the ISO cannot be checksummed"
+
+# Uploading: both sidecars go up with the ISO, and a missing one is skipped
+# rather than handed to rclone as a path that does not exist.
+export HOME="$work/home"
+mkdir -p "$HOME/.config/rclone"
+: >"$HOME/.config/rclone/rclone.conf"
+
+# A space in the path is the case that tells a quoted argument from an unquoted
+# one, so every upload case runs from a directory that has one.
+mkdir -p "$work/release builds"
+upload_iso="$work/release builds/omarchy-9.9.9.iso"
+printf 'not really an iso\n' >"$upload_iso"
+printf 'signature\n' >"$upload_iso.sig"
+printf 'checksum\n' >"$upload_iso.sha256"
+
+run_upload "$upload_iso"
+
+for suffix in "" ".sig" ".sha256"; do
+  grep -qxF "rclone|copy|$upload_iso$suffix|Omarchy:omarchy/|-P" "$work/rclone-log" ||
+    fail "upload ships the ISO, its signature and its checksum, path spaces intact" \
+      "$(cat "$work/rclone-log")"
+done
+pass "upload ships the ISO, its signature and its checksum, path spaces intact"
+
+rm "$upload_iso.sig"
+run_upload "$upload_iso"
+
+if grep -qF ".sig" "$work/rclone-log"; then
+  fail "upload skips a sidecar that is not there" "$(cat "$work/rclone-log")"
+fi
+grep -qF "$upload_iso.sha256" "$work/rclone-log" ||
+  fail "upload still ships the checksum without a signature" "$(cat "$work/rclone-log")"
+pass "upload skips a sidecar that is not there"
+
+# A failed copy has to fail the upload even when a later copy succeeds, or a
+# release reports success having published an ISO nobody can download.
+printf 'signature\n' >"$upload_iso.sig"
+set +e
+RCLONE_FAIL_ON=".sig" run_upload "$upload_iso"
+upload_status=$?
+set -e
+(( upload_status != 0 )) ||
+  fail "a failed sidecar copy fails the upload" "$(cat "$work/rclone-log")"
+grep -qF "$upload_iso.sha256" "$work/rclone-log" ||
+  fail "a failed sidecar copy still attempts the rest" "$(cat "$work/rclone-log")"
+pass "a failed sidecar copy fails the upload without skipping the rest"
+
+set +e
+RCLONE_FAIL_ON="omarchy-9.9.9.iso" run_upload "$upload_iso"
+upload_status=$?
+set -e
+(( upload_status != 0 )) ||
+  fail "a failed ISO copy fails the upload" "$(cat "$work/rclone-log")"
+pass "a failed ISO copy fails the upload"
+
+# Publishing an ISO nobody can verify is the thing this change exists to stop,
+# so the uploader says so out loud rather than exiting quietly.
+rm "$upload_iso.sha256"
+run_upload "$upload_iso"
+grep -qF "nobody can verify" "$work/upload-err" ||
+  fail "upload warns when there is no checksum to publish" "$(cat "$work/upload-err")"
+pass "upload warns when there is no checksum to publish"

test/unit/partition-numbering-test.sh

@@ -0,0 +1,131 @@
+#!/bin/bash
+#
+# create_partition() must report the number parted actually assigned, never a
+# predicted one. The regression this pins: the configurator used to compute
+# "highest existing partition + 1", while parted fills the lowest free GPT
+# slot. Any disk whose numbering has a hole — what deleting a partition to
+# free space leaves behind — then had every later command (cryptsetup, mkfs,
+# mount) pointed at device nodes that did not exist, surfacing much later as
+# "protected mode: /mnt is not a mountpoint".
+#
+# parted operates on image files directly, so this needs no root, no loop
+# devices, and no real disk.
+
+set -uo pipefail
+
+ROOT=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd)
+LIB="$ROOT/configs/airootfs/usr/share/omarchy-iso/disk-partitioning.sh"
+
+if ! command -v parted >/dev/null 2>&1; then
+  echo "SKIP: parted is not installed"
+  exit 0
+fi
+
+# shellcheck source=../configs/airootfs/usr/share/omarchy-iso/disk-partitioning.sh
+source "$LIB"
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+IMG="$WORK/disk.img"
+MIB=$((1024 * 1024))
+failures=0
+
+check() {
+  local label="$1" expected="$2" actual="$3"
+  if [[ $expected == "$actual" ]]; then
+    printf '  ok   %s\n' "$label"
+  else
+    printf '  FAIL %s: expected %s, got %s\n' "$label" "$expected" "$actual"
+    failures=$((failures + 1))
+  fi
+}
+
+# parted reports a partition's size inclusive of both endpoints, so it lands
+# one sector above (end - start). Same slack create_partition allows.
+check_size() {
+  local label="$1" want="$2" actual="${3:-0}" delta
+  delta=$((actual - want))
+  (( delta < 0 )) && delta=$((-delta))
+  if (( delta <= MIB )); then
+    printf '  ok   %s\n' "$label"
+  else
+    printf '  FAIL %s: expected ~%s, got %s\n' "$label" "$want" "$actual"
+    failures=$((failures + 1))
+  fi
+}
+
+# parted's end position is inclusive, so partitions laid back to back overlap
+# by a sector and are refused. Leave a MiB between them.
+mkpart_mib() {
+  parted --script "$IMG" mkpart "$1" "$2" "$(($3 * MIB))B" "$(($4 * MIB))B"
+}
+
+# A disk with holes: four partitions, then delete the middle two. Slots 2 and
+# 3 are free while the highest number in use is 4 — the shape of the reported
+# failure, where the user deleted a partition to make room.
+build_holey_disk() {
+  rm -f "$IMG"
+  truncate -s 4G "$IMG"
+  parted --script "$IMG" mklabel gpt
+  mkpart_mib one ext4 1 200
+  mkpart_mib two ext4 201 400
+  mkpart_mib three ext4 401 600
+  mkpart_mib four ext4 601 800
+  parted --script "$IMG" rm 2
+  parted --script "$IMG" rm 3
+  created_parts=()
+}
+
+echo "==> numbering on a disk with holes"
+build_holey_disk
+check "existing numbers" "1 4" "$(partition_numbers "$IMG" | sort | tr '\n' ' ' | sed 's/ $//')"
+
+create_partition "$IMG" "$((1000 * MIB))" "$((1200 * MIB))" fat32 OMARCHY_EFI
+check "create_partition succeeded (esp)" "0" "$?"
+esp_num="$created_partition_number"
+check "esp took the lowest free slot" "2" "$esp_num"
+
+# Starts a MiB past the ESP, the way run_partition_decide aligns ROOT_START_B
+# up from EFI_END_B + 1.
+create_partition "$IMG" "$((1201 * MIB))" "$((2000 * MIB))" btrfs OMARCHY_ROOT
+check "create_partition succeeded (root)" "0" "$?"
+root_num="$created_partition_number"
+check "root took the next free slot" "3" "$root_num"
+
+# The old prediction. If either of these ever matches again, the regression is
+# back: the highest number in use was 4, so the guess would have been 5 and 6.
+check "esp is not the predicted number" "not-5" "$([[ $esp_num == 5 ]] && echo 5 || echo not-5)"
+check "root is not the predicted number" "not-6" "$([[ $root_num == 6 ]] && echo 6 || echo not-6)"
+
+check "both creations tracked for rollback" "2 3" "${created_parts[*]}"
+check_size "esp size" "$((200 * MIB))" "$(partition_size_bytes "$IMG" "$esp_num")"
+check_size "root size" "$((799 * MIB))" "$(partition_size_bytes "$IMG" "$root_num")"
+
+echo "==> rollback reclaims only what this run created"
+rollback_created_parts "$IMG"
+check "created partitions removed" "1 4" "$(partition_numbers "$IMG" | sort | tr '\n' ' ' | sed 's/ $//')"
+check "rollback list cleared" "0" "${#created_parts[@]}"
+
+echo "==> numbering on a disk without holes"
+rm -f "$IMG"
+truncate -s 4G "$IMG"
+parted --script "$IMG" mklabel gpt
+mkpart_mib one ext4 1 200
+mkpart_mib two ext4 201 400
+created_parts=()
+
+create_partition "$IMG" "$((1000 * MIB))" "$((1200 * MIB))" fat32 OMARCHY_EFI
+check "appends when there is no hole" "3" "$created_partition_number"
+
+echo "==> a refused creation stays out of the rollback list"
+created_parts=()
+create_partition "$IMG" "$((100 * MIB))" "$((300 * MIB))" ext4 OVERLAP
+check "overlapping creation failed" "1" "$?"
+check "nothing tracked" "0" "${#created_parts[@]}"
+
+if (( failures > 0 )); then
+  printf '\n%d check(s) failed\n' "$failures"
+  exit 1
+fi
+printf '\nall checks passed\n'

test/unit/test_command_capture.py

@@ -0,0 +1,129 @@
+#!/usr/bin/python
+
+"""Undecodable bytes in command output, and where tolerating them stops.
+
+The orchestrator reads firmware and filesystem metadata out of commands whose
+output is not required to be UTF-8: noise in a boot entry must not stop an
+install, while a mangled identifier must stop one. These tests run stand-in
+commands emitting the bytes two HP firmwares actually put in a legacy BBS entry,
+so they exercise the decode itself rather than a mocked result.
+"""
+
+import os
+import sys
+import tempfile
+import types
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT / "configs/airootfs/usr/share/omarchy-iso"))
+
+# phases_impl imports the archinstall adapter at module scope, which pulls in
+# the archinstall library that only exists on the live ISO.
+sys.modules.setdefault(
+    "orchestrator.archinstall_adapter",
+    types.ModuleType("orchestrator.archinstall_adapter"),
+)
+
+from orchestrator import phases_impl  # noqa: E402
+from orchestrator.command import capture, capture_identifier  # noqa: E402
+
+# Boot0000 is the entry that aborted the install: raw bytes inside a BBS device
+# path, in a legacy entry nothing in the installer reads. 0x80 and 0xe0 are the
+# bytes two different HP firmwares emitted.
+EFIBOOTMGR_OUTPUT = (
+    b"BootCurrent: 0003\n"
+    b"Timeout: 0 seconds\n"
+    b"BootOrder: 2001,0003,0000\n"
+    b"Boot0000* Notebook Hard Drive\tBBS(HD,\x80\x7f\xff\x04\xe0\x7f,)\n"
+    b"Boot0003* Omarchy\tHD(1,GPT,0d9c9d4f)/File(\\EFI\\limine\\BOOTX64.EFI)\n"
+    b"Boot2001* USB Drive (UEFI)\tRC\n"
+)
+
+
+class CommandCaptureTest(unittest.TestCase):
+    def setUp(self):
+        self.bin_dir = None
+
+    def fake_bin(self) -> Path:
+        """A directory at the front of PATH, made once per test."""
+        if self.bin_dir is None:
+            tmp = tempfile.TemporaryDirectory()
+            self.addCleanup(tmp.cleanup)
+            self.bin_dir = Path(tmp.name)
+            path = os.environ["PATH"]
+            self.addCleanup(os.environ.__setitem__, "PATH", path)
+            os.environ["PATH"] = f"{self.bin_dir}:{path}"
+        return self.bin_dir
+
+    def fake_script(self, name: str, body: str) -> None:
+        script = self.fake_bin() / name
+        script.write_text(f"#!/bin/sh\n{body}\n")
+        script.chmod(0o755)
+
+    def fake_command(self, name: str, output: bytes) -> None:
+        """A command printing exactly these bytes, undecodable ones included."""
+        payload = self.fake_bin() / f"{name}.out"
+        payload.write_bytes(output)
+        self.fake_script(name, f'cat "{payload}"')
+
+    def fake_findmnt(self, source: bytes) -> None:
+        """A findmnt answering per column, so the phase gets as far as SOURCE."""
+        payload = self.fake_bin() / "findmnt.source"
+        payload.write_bytes(source)
+        self.fake_script(
+            "findmnt",
+            'case "$2" in\n'
+            "  FSTYPE) echo btrfs ;;\n"
+            "  OPTIONS) echo rw,subvol=/@ ;;\n"
+            f'  SOURCE) cat "{payload}" ;;\n'
+            "esac",
+        )
+
+    def test_undecodable_bytes_are_replaced_rather_than_raised(self):
+        self.fake_command("omarchy-not-utf8", b"before\x80after\n")
+        self.assertEqual(capture(["omarchy-not-utf8"]).stdout, "before�after\n")
+
+    def test_efibootmgr_entries_parse_around_a_legacy_bbs_entry(self):
+        self.fake_command("efibootmgr", EFIBOOTMGR_OUTPUT)
+
+        state = phases_impl._read_efibootmgr()
+
+        self.assertEqual(state["order"], ["2001", "0003", "0000"])
+        self.assertEqual(phases_impl._find_label_entries(state["entries"], "Omarchy"), ["0003"])
+        self.assertTrue(state["entries"]["0000"].startswith("Notebook Hard Drive"))
+
+    def test_a_mangled_identifier_stops_the_install_rather_than_reaching_fstab(self):
+        # _validate_pre_mounted_filesystems reads the UUID back from this same
+        # command, so a replaced byte would agree with itself all the way to a
+        # machine that cannot find its root.
+        self.fake_command("blkid", b"1a2b3c4d-\x80-dead-beef\n")
+
+        with self.assertRaises(RuntimeError) as raised:
+            phases_impl._blkid_uuid("/dev/sda2")
+
+        self.assertIn("the UUID of /dev/sda2 is not valid text", str(raised.exception))
+
+    def test_a_mangled_btrfs_device_is_never_handed_to_mount(self):
+        # create_factory_snapshot mounts this device and deletes subvolumes
+        # under it; a replaced byte must stop the phase before that, not turn
+        # into an opaque mount failure.
+        self.fake_findmnt(source=b"/dev/sda\xe02[/@]")
+        ctx = types.SimpleNamespace(target=Path("/mnt"), state_dir=Path("/run/omarchy"))
+
+        with mock.patch.object(phases_impl, "info"), self.assertRaises(RuntimeError) as raised:
+            phases_impl.create_factory_snapshot(ctx)
+
+        self.assertIn("is not valid text", str(raised.exception))
+
+    def test_a_clean_identifier_is_returned_unchanged(self):
+        self.fake_command("blkid", b"1a2b3c4d-0e5f-dead-beef\n")
+        self.assertEqual(
+            capture_identifier(["blkid"], "the UUID"), "1a2b3c4d-0e5f-dead-beef"
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

test/unit/test_configure_ssh_access.py

@@ -0,0 +1,153 @@
+"""Unit tests for the orchestrator's configure_ssh_access phase.
+
+The phase touches the target only through the filesystem and arch-chroot, so
+the tests run it against a temp directory with subprocess.run recorded and the
+ufw side effect (writing user.rules) simulated by the fake.
+"""
+
+import stat
+import sys
+import tempfile
+import types
+import unittest
+from pathlib import Path
+from subprocess import CompletedProcess
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "configs/airootfs/usr/share/omarchy-iso"))
+
+# phases_impl imports the archinstall adapter at module scope, which pulls in
+# the archinstall library that only exists on the live ISO. configure_ssh_access
+# never touches it, so stub the adapter out before the import.
+sys.modules["orchestrator.archinstall_adapter"] = types.ModuleType("orchestrator.archinstall_adapter")
+
+from orchestrator import phases_impl  # noqa: E402
+
+UFW_RULE = "-A ufw-user-input -p tcp --dport 22 -j ACCEPT\n"
+
+
+class ConfigureSshAccessTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.target = Path(self.tmp.name)
+        self.calls = []
+
+        info_patch = mock.patch.object(phases_impl, "info")
+        info_patch.start()
+        self.addCleanup(info_patch.stop)
+
+        run_patch = mock.patch.object(phases_impl.subprocess, "run", side_effect=self.fake_run)
+        run_patch.start()
+        self.addCleanup(run_patch.stop)
+
+        self.ufw_writes_rule = True
+
+    def fake_run(self, cmd, **kwargs):
+        self.calls.append(cmd)
+        if cmd[2] == "ufw":
+            if self.ufw_writes_rule:
+                rules = self.target / "etc" / "ufw" / "user.rules"
+                rules.parent.mkdir(parents=True, exist_ok=True)
+                rules.write_text(UFW_RULE)
+            # ufw cannot reach netfilter inside a chroot and exits non-zero
+            # even when it recorded the rule; the phase must not trust this.
+            return CompletedProcess(cmd, 1)
+        return CompletedProcess(cmd, 0)
+
+    def ctx(self, authorized_keys=None):
+        authorized_keys_path = None
+        if authorized_keys is not None:
+            authorized_keys_path = self.target / "authorized_keys"
+            authorized_keys_path.write_text(authorized_keys)
+        return types.SimpleNamespace(target=self.target, username="jeff", authorized_keys_path=authorized_keys_path, defer_provisioning=False)
+
+    def configure(self, **kwargs):
+        phases_impl.configure_ssh_access(self.ctx(**kwargs))
+
+    def authorized_keys(self):
+        return self.target / "home" / "jeff" / ".ssh" / "authorized_keys"
+
+    def chrooted(self, program):
+        return [cmd for cmd in self.calls if cmd[:2] == ["arch-chroot", str(self.target)] and cmd[2] == program]
+
+    def test_no_authorized_keys_is_a_no_op(self):
+        self.configure()
+        self.assertEqual(self.calls, [])
+        self.assertFalse((self.target / "home" / "jeff" / ".ssh").exists())
+
+    def test_installs_keys_one_per_line(self):
+        self.configure(authorized_keys="ssh-ed25519 AAAA jeff@host\nssh-rsa BBBB jeff@work\n")
+        self.assertEqual(self.authorized_keys().read_text(), "ssh-ed25519 AAAA jeff@host\nssh-rsa BBBB jeff@work\n")
+
+    def test_drops_blank_lines_and_comments(self):
+        self.configure(authorized_keys="# work laptop\n\n  ssh-ed25519 AAAA jeff@host  \n")
+        self.assertEqual(self.authorized_keys().read_text(), "ssh-ed25519 AAAA jeff@host\n")
+
+    def test_keys_with_options_pass_through(self):
+        key = 'command="/usr/bin/true",no-pty ssh-ed25519 AAAA jeff@host'
+        self.configure(authorized_keys=f"{key}\n")
+        self.assertEqual(self.authorized_keys().read_text(), f"{key}\n")
+
+    def test_ssh_dir_is_private(self):
+        self.configure(authorized_keys="ssh-ed25519 AAAA jeff@host\n")
+        mode = stat.S_IMODE((self.target / "home" / "jeff" / ".ssh").stat().st_mode)
+        self.assertEqual(mode, 0o700)
+
+    def test_authorized_keys_is_private(self):
+        self.configure(authorized_keys="ssh-ed25519 AAAA jeff@host\n")
+        self.assertEqual(stat.S_IMODE(self.authorized_keys().stat().st_mode), 0o600)
+
+    def test_chowns_ssh_dir_to_the_user(self):
+        self.configure(authorized_keys="ssh-ed25519 AAAA jeff@host\n")
+        self.assertEqual(self.chrooted("chown"), [
+            ["arch-chroot", str(self.target), "chown", "-R", "jeff:jeff", "/home/jeff/.ssh"],
+        ])
+
+    def test_enables_sshd(self):
+        self.configure(authorized_keys="ssh-ed25519 AAAA jeff@host\n")
+        self.assertEqual(self.chrooted("systemctl"), [
+            ["arch-chroot", str(self.target), "systemctl", "enable", "sshd.service"],
+        ])
+
+    def test_allows_ssh_through_ufw_despite_chroot_exit_status(self):
+        self.configure(authorized_keys="ssh-ed25519 AAAA jeff@host\n")
+        self.assertEqual(self.chrooted("ufw"), [
+            ["arch-chroot", str(self.target), "ufw", "allow", "ssh"],
+        ])
+
+    def test_fails_when_ufw_does_not_record_the_rule(self):
+        self.ufw_writes_rule = False
+        with self.assertRaisesRegex(RuntimeError, "allow rule for port 22"):
+            self.configure(authorized_keys="ssh-ed25519 AAAA jeff@host\n")
+
+    def test_empty_file_fails_the_phase(self):
+        with self.assertRaisesRegex(RuntimeError, "contains no SSH keys"):
+            self.configure(authorized_keys="")
+
+    def test_blank_only_file_fails_the_phase(self):
+        with self.assertRaisesRegex(RuntimeError, "contains no SSH keys"):
+            self.configure(authorized_keys="\n   \n")
+
+    def test_comment_only_file_fails_the_phase(self):
+        with self.assertRaisesRegex(RuntimeError, "contains no SSH keys"):
+            self.configure(authorized_keys="# no keys here\n")
+
+
+class OptionalPathTest(unittest.TestCase):
+    def test_unset_and_missing_paths_are_none(self):
+        from orchestrator.context import _optional_path
+
+        self.assertIsNone(_optional_path(None))
+        self.assertIsNone(_optional_path(""))
+        self.assertIsNone(_optional_path("/does/not/exist/authorized_keys"))
+
+    def test_existing_path_is_returned(self):
+        from orchestrator.context import _optional_path
+
+        with tempfile.NamedTemporaryFile() as f:
+            self.assertEqual(_optional_path(f.name), Path(f.name))
+
+
+if __name__ == "__main__":
+    unittest.main()

test/unit/test_configure_tailscale.py

@@ -0,0 +1,164 @@
+"""Unit tests for the orchestrator's configure_tailscale phase.
+
+Same harness as the SSH access tests: the phase touches the target only
+through the filesystem and arch-chroot, so it runs against a temp directory
+with subprocess.run recorded and the ufw side effect (writing user.rules)
+simulated by the fake.
+"""
+
+import stat
+import sys
+import tempfile
+import types
+import unittest
+from pathlib import Path
+from subprocess import CompletedProcess
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "configs/airootfs/usr/share/omarchy-iso"))
+
+# phases_impl imports the archinstall adapter at module scope, which pulls in
+# the archinstall library that only exists on the live ISO. configure_tailscale
+# never touches it, so stub the adapter out before the import.
+sys.modules["orchestrator.archinstall_adapter"] = types.ModuleType("orchestrator.archinstall_adapter")
+
+from orchestrator import phases_impl  # noqa: E402
+
+UFW_RULE = "-A ufw-user-input -i tailscale0 -j ACCEPT\n"
+
+
+class ConfigureTailscaleTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.target = Path(self.tmp.name)
+        self.calls = []
+
+        info_patch = mock.patch.object(phases_impl, "info")
+        info_patch.start()
+        self.addCleanup(info_patch.stop)
+
+        run_patch = mock.patch.object(phases_impl.subprocess, "run", side_effect=self.fake_run)
+        run_patch.start()
+        self.addCleanup(run_patch.stop)
+
+        self.ufw_writes_rule = True
+
+    def fake_run(self, cmd, **kwargs):
+        self.calls.append(cmd)
+        if cmd[2] == "ufw":
+            if self.ufw_writes_rule:
+                rules = self.target / "etc" / "ufw" / "user.rules"
+                rules.parent.mkdir(parents=True, exist_ok=True)
+                rules.write_text(UFW_RULE)
+            # ufw cannot reach netfilter inside a chroot and exits non-zero
+            # even when it recorded the rule; the phase must not trust this.
+            return CompletedProcess(cmd, 1)
+        return CompletedProcess(cmd, 0)
+
+    def ctx(self, authkey=None, tailscale_installed=True):
+        authkey_path = None
+        if authkey is not None:
+            authkey_path = self.target / "tailscale_authkey"
+            authkey_path.write_text(authkey)
+        if tailscale_installed:
+            binary = self.target / "usr" / "bin" / "tailscale"
+            binary.parent.mkdir(parents=True, exist_ok=True)
+            binary.touch()
+        return types.SimpleNamespace(target=self.target, tailscale_authkey_path=authkey_path)
+
+    def configure(self, **kwargs):
+        phases_impl.configure_tailscale(self.ctx(**kwargs))
+
+    def staged_key(self):
+        return self.target / "etc" / "tailscale" / "authkey"
+
+    def unit(self):
+        return self.target / "etc" / "systemd" / "system" / "omarchy-tailscale-join.service"
+
+    def chrooted(self, program):
+        return [cmd for cmd in self.calls if cmd[:2] == ["arch-chroot", str(self.target)] and cmd[2] == program]
+
+    def test_no_authkey_is_a_no_op(self):
+        self.configure()
+        self.assertEqual(self.calls, [])
+        self.assertFalse((self.target / "etc" / "tailscale").exists())
+
+    def test_stages_the_key(self):
+        self.configure(authkey="tskey-auth-kFAKEKEY\n")
+        self.assertEqual(self.staged_key().read_text(), "tskey-auth-kFAKEKEY\n")
+
+    def test_drops_blank_lines_and_comments(self):
+        self.configure(authkey="# reusable, tagged\n\n  tskey-auth-kFAKEKEY  \n")
+        self.assertEqual(self.staged_key().read_text(), "tskey-auth-kFAKEKEY\n")
+
+    def test_key_dir_and_file_are_root_private(self):
+        self.configure(authkey="tskey-auth-kFAKEKEY\n")
+        self.assertEqual(stat.S_IMODE((self.target / "etc" / "tailscale").stat().st_mode), 0o700)
+        self.assertEqual(stat.S_IMODE(self.staged_key().stat().st_mode), 0o600)
+
+    def test_installs_the_join_unit(self):
+        self.configure(authkey="tskey-auth-kFAKEKEY\n")
+        text = self.unit().read_text()
+        self.assertIn("ConditionPathExists=/etc/tailscale/authkey", text)
+        # The key must not outlive a successful join, the unit must not run
+        # again after one, and cleanup must be sequenced after the join
+        # succeeds -- inside the script, not in ExecStartPost.
+        self.assertIn(
+            "ExecStart=/usr/bin/sh -c 'until tailscale up --auth-key file:/etc/tailscale/authkey;"
+            " do sleep 15; done; rm -f /etc/tailscale/authkey;"
+            " systemctl disable omarchy-tailscale-join.service'",
+            text,
+        )
+
+    def test_join_unit_does_not_hold_up_boot(self):
+        # A Type=oneshot wanted by multi-user.target holds the whole boot
+        # (SDDM included) hostage until the join finishes or times out --
+        # target units implicitly gain After= for their Wants=.
+        self.configure(authkey="tskey-auth-kFAKEKEY\n")
+        text = self.unit().read_text()
+        self.assertIn("Type=simple", text)
+        self.assertNotIn("Type=oneshot", text)
+        self.assertNotIn("TimeoutStartSec", text)
+
+    def test_unit_avoids_systemd_variable_expansion(self):
+        self.configure(authkey="tskey-auth-kFAKEKEY\n")
+        self.assertNotIn("$", self.unit().read_text())
+
+    def test_enables_tailscaled_and_the_join(self):
+        self.configure(authkey="tskey-auth-kFAKEKEY\n")
+        self.assertEqual(self.chrooted("systemctl"), [
+            ["arch-chroot", str(self.target), "systemctl", "enable",
+             "tailscaled.service", "omarchy-tailscale-join.service"],
+        ])
+
+    def test_allows_tailnet_traffic_through_ufw_despite_chroot_exit_status(self):
+        self.configure(authkey="tskey-auth-kFAKEKEY\n")
+        self.assertEqual(self.chrooted("ufw"), [
+            ["arch-chroot", str(self.target), "ufw", "allow", "in", "on", "tailscale0"],
+        ])
+
+    def test_fails_when_ufw_does_not_record_the_rule(self):
+        self.ufw_writes_rule = False
+        with self.assertRaisesRegex(RuntimeError, "allow rule for tailscale0"):
+            self.configure(authkey="tskey-auth-kFAKEKEY\n")
+
+    def test_fails_when_tailscale_is_not_on_the_target(self):
+        with self.assertRaisesRegex(RuntimeError, "not installed on the target"):
+            self.configure(authkey="tskey-auth-kFAKEKEY\n", tailscale_installed=False)
+
+    def test_empty_file_fails_the_phase(self):
+        with self.assertRaisesRegex(RuntimeError, "contains no auth key"):
+            self.configure(authkey="")
+
+    def test_comment_only_file_fails_the_phase(self):
+        with self.assertRaisesRegex(RuntimeError, "contains no auth key"):
+            self.configure(authkey="# no key here\n")
+
+    def test_multiple_keys_fail_the_phase(self):
+        with self.assertRaisesRegex(RuntimeError, "expected exactly one"):
+            self.configure(authkey="tskey-auth-kONE\ntskey-auth-kTWO\n")
+
+
+if __name__ == "__main__":
+    unittest.main()

test/unit/test_keyboard.py

@@ -0,0 +1,84 @@
+#!/usr/bin/python
+
+import re
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT / "configs/airootfs/usr/share/omarchy-iso"))
+
+from orchestrator import keyboard as KEYBOARD  # noqa: E402
+
+# The layout list lives in the Omarchy runtime now, shared verbatim with the
+# first-boot owner setup; build-iso.sh vendors it onto the ISO. Read it from
+# wherever this checkout can see a runtime, and skip the coverage test rather
+# than fail when none is around (a bare CI checkout of just this repo).
+SETUP_FORM_CANDIDATES = (
+    Path("/omarchy-source/install/provisioning/setup-form.sh"),
+    ROOT.parent / "omarchy/install/provisioning/setup-form.sh",
+    Path("/usr/share/omarchy/install/provisioning/setup-form.sh"),
+)
+
+
+def supported_keymaps():
+    for candidate in SETUP_FORM_CANDIDATES:
+        if not candidate.is_file():
+            continue
+        block = re.search(
+            r"OMARCHY_KEYBOARD_LAYOUTS=\$'(.*?)'\n", candidate.read_text(), re.DOTALL
+        )
+        assert block, f"no layout list in {candidate}"
+        return [line.split("|", 1)[1] for line in block.group(1).splitlines()]
+    return None
+
+
+SUPPORTED_KEYMAPS = supported_keymaps()
+
+
+class KeyboardConfigurationTest(unittest.TestCase):
+    def target(self, directory: str) -> Path:
+        target = Path(directory)
+        (target / "etc").mkdir()
+        (target / "etc/vconsole.conf").write_text(
+            "KEYMAP=us\nFONT=default8x16\n"
+        )
+        return target
+
+    def test_writes_keymap_and_xkb_settings_and_preserves_font(self):
+        # XKBLAYOUT is load-bearing: omarchy's detect-keyboard-layout.sh copies
+        # it into Hyprland's kb_layout on the installed system.
+        with tempfile.TemporaryDirectory() as directory:
+            target = self.target(directory)
+            self.assertTrue(KEYBOARD.configure_keyboard(target, "us"))
+            lines = (target / "etc/vconsole.conf").read_text().splitlines()
+            self.assertIn("KEYMAP=us", lines)
+            self.assertIn("XKBLAYOUT=us", lines)
+            self.assertEqual(lines.count("FONT=default8x16"), 1)
+
+    def test_all_configurator_keymaps_are_known_to_localectl(self):
+        if SUPPORTED_KEYMAPS is None:
+            self.skipTest("no Omarchy runtime checkout to read the layout list from")
+        for keymap in SUPPORTED_KEYMAPS:
+            with self.subTest(keymap=keymap), tempfile.TemporaryDirectory() as directory:
+                target = self.target(directory)
+                self.assertTrue(KEYBOARD.configure_keyboard(target, keymap))
+                lines = (target / "etc/vconsole.conf").read_text().splitlines()
+                self.assertIn(f"KEYMAP={keymap}", lines)
+                self.assertEqual(lines.count("FONT=default8x16"), 1)
+
+    def test_unknown_and_empty_keymaps_match_archinstall_behavior(self):
+        for keymap, expected in (("definitely-not-a-keymap", False), ("", True)):
+            with self.subTest(keymap=keymap), tempfile.TemporaryDirectory() as directory:
+                target = self.target(directory)
+                self.assertEqual(KEYBOARD.configure_keyboard(target, keymap), expected)
+                self.assertEqual(
+                    (target / "etc/vconsole.conf").read_text(),
+                    "KEYMAP=us\nFONT=default8x16\n",
+                )
+
+
+if __name__ == "__main__":
+    unittest.main()

test/unit/test_offline_mirror_pruning.py

@@ -0,0 +1,79 @@
+#!/usr/bin/python
+
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+PRUNER = ROOT / "builder/prune-offline-mirror.sh"
+
+
+class OfflineMirrorPruningTest(unittest.TestCase):
+    def run_pruner(self, mirror: Path, required: list[str]):
+        return subprocess.run(
+            ["bash", str(PRUNER), str(mirror)],
+            input="".join(f"{filename}\n" for filename in required),
+            capture_output=True,
+            text=True,
+        )
+
+    def add_file(self, mirror: Path, filename: str):
+        (mirror / filename).write_bytes(b"package")
+
+    def test_keeps_only_exactly_selected_package_archives(self):
+        with tempfile.TemporaryDirectory() as directory:
+            mirror = Path(directory)
+            keep = "keep-2.0-1-x86_64.pkg.tar.zst"
+            other = "other-1.0-1-any.pkg.tar.zst"
+            stale_version = "keep-1.0-1-x86_64.pkg.tar.zst"
+            removed_package = "removed-1.0-1-x86_64.pkg.tar.zst"
+            orphan_signature = "interrupted-1.0-1-x86_64.pkg.tar.zst.sig"
+
+            for filename in (keep, other, stale_version, removed_package):
+                self.add_file(mirror, filename)
+            for filename in (keep, stale_version, removed_package):
+                self.add_file(mirror, f"{filename}.sig")
+            self.add_file(mirror, orphan_signature)
+            self.add_file(mirror, "offline.db.tar.gz")
+
+            result = self.run_pruner(mirror, [keep, other])
+
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertEqual(
+                {path.name for path in mirror.iterdir()},
+                {keep, f"{keep}.sig", other, "offline.db.tar.gz"},
+            )
+            self.assertIn(stale_version, result.stdout)
+            self.assertIn(removed_package, result.stdout)
+
+    def test_missing_selection_aborts_before_deleting_anything(self):
+        with tempfile.TemporaryDirectory() as directory:
+            mirror = Path(directory)
+            cached = "cached-1.0-1-x86_64.pkg.tar.zst"
+            self.add_file(mirror, cached)
+
+            result = self.run_pruner(
+                mirror, ["missing-1.0-1-x86_64.pkg.tar.zst"]
+            )
+
+            self.assertNotEqual(result.returncode, 0)
+            self.assertTrue((mirror / cached).exists())
+            self.assertIn("selected packages are missing", result.stderr)
+
+    def test_empty_selection_aborts_before_deleting_anything(self):
+        with tempfile.TemporaryDirectory() as directory:
+            mirror = Path(directory)
+            cached = "cached-1.0-1-x86_64.pkg.tar.zst"
+            self.add_file(mirror, cached)
+
+            result = self.run_pruner(mirror, [])
+
+            self.assertNotEqual(result.returncode, 0)
+            self.assertTrue((mirror / cached).exists())
+            self.assertIn("empty package selection", result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()

test/unit/test_provisioning_state.py

@@ -0,0 +1,440 @@
+"""Unit tests for deferred-provisioning install support in the orchestrator.
+
+Covers the InstallContext deferred-provisioning plumbing (marker file, credential-less input,
+throwaway LUKS passphrase injection) and the stage_provisioning_state /
+create_factory_snapshot / configure_login phases against a temp target with
+subprocess mocked out.
+"""
+
+import json
+import os
+import sys
+import tempfile
+import types
+import unittest
+from pathlib import Path
+from subprocess import CompletedProcess
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "configs/airootfs/usr/share/omarchy-iso"))
+
+sys.modules.setdefault(
+    "orchestrator.archinstall_adapter", types.ModuleType("orchestrator.archinstall_adapter")
+)
+
+from orchestrator import phases_impl  # noqa: E402
+from orchestrator.context import InstallContext  # noqa: E402
+
+
+class ContextDeferProvisioningTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.dir = Path(self.tmp.name)
+        self.state_dir = self.dir / "state"
+
+        self.env = {
+            "OMARCHY_INSTALL_CONFIG": str(self.dir / "user_configuration.json"),
+            "OMARCHY_INSTALL_CREDS": str(self.dir / "user_credentials.json"),
+            "OMARCHY_INSTALL_STATE_DIR": str(self.state_dir),
+        }
+
+    def write_config(self, config):
+        (self.dir / "user_configuration.json").write_text(json.dumps(config))
+
+    def write_creds(self, creds):
+        (self.dir / "user_credentials.json").write_text(json.dumps(creds))
+
+    def from_env(self, **extra_env):
+        env = {**self.env, **extra_env}
+        with mock.patch.dict(os.environ, env, clear=False):
+            for key in ("OMARCHY_INSTALL_DEFER_PROVISIONING_FILE",):
+                if key not in env:
+                    os.environ.pop(key, None)
+            return InstallContext.from_env()
+
+    def base_config(self, defer_provisioning=None, disk_encryption=None):
+        config = {
+            "disk_config": {"config_type": "default_layout"},
+            "omarchy_install": {"mode": "full_disk", "target_mount": "/mnt"},
+        }
+        if defer_provisioning is not None:
+            config["omarchy_install"]["defer_provisioning"] = defer_provisioning
+        if disk_encryption is not None:
+            config["disk_config"]["disk_encryption"] = disk_encryption
+        return config
+
+    def test_defer_provisioning_flag_from_config(self):
+        self.write_config(self.base_config(defer_provisioning=True))
+        ctx = self.from_env()
+        self.assertTrue(ctx.defer_provisioning)
+        self.assertEqual(ctx.user_credentials, {"users": []})
+        self.assertEqual(ctx.username, "")
+
+    def test_marker_file_arms_deferred_provisioning_without_credentials(self):
+        self.write_config(self.base_config())
+        marker = self.dir / "defer_provisioning"
+        marker.touch()
+        ctx = self.from_env(OMARCHY_INSTALL_DEFER_PROVISIONING_FILE=str(marker))
+        self.assertTrue(ctx.defer_provisioning)
+        self.assertTrue(ctx.omarchy_install["defer_provisioning"])
+
+    def test_absent_marker_file_is_not_deferred_provisioning(self):
+        self.write_config(self.base_config())
+        self.write_creds({"users": [{"username": "jeff"}]})
+        ctx = self.from_env(OMARCHY_INSTALL_DEFER_PROVISIONING_FILE=str(self.dir / "missing-defer_provisioning"))
+        self.assertFalse(ctx.defer_provisioning)
+        self.assertEqual(ctx.username, "jeff")
+
+    def test_missing_credentials_without_defer_provisioning_raises(self):
+        self.write_config(self.base_config())
+        with self.assertRaisesRegex(RuntimeError, "credentials file missing"):
+            self.from_env()
+
+    def test_deferred_provisioning_generates_throwaway_luks_passphrase(self):
+        self.write_config(self.base_config(defer_provisioning=True, disk_encryption={
+            "encryption_type": "luks", "partitions": ["x"],
+        }))
+        ctx = self.from_env()
+
+        password = ctx.user_configuration["disk_config"]["disk_encryption"]["encryption_password"]
+        self.assertTrue(password)
+        self.assertEqual(ctx.user_credentials["encryption_password"], password)
+
+        # archinstall reads both files from disk; the injected passphrase must
+        # be present in each.
+        arch_config = json.loads(ctx.arch_config_path.read_text())
+        self.assertEqual(
+            arch_config["disk_config"]["disk_encryption"]["encryption_password"], password
+        )
+        synthesized = json.loads(ctx.creds_path.read_text())
+        self.assertEqual(synthesized["encryption_password"], password)
+
+    def test_deferred_provisioning_reuses_rig_supplied_passphrase(self):
+        self.write_config(self.base_config(defer_provisioning=True, disk_encryption={
+            "encryption_type": "luks", "partitions": ["x"],
+        }))
+        self.write_creds({"users": [], "encryption_password": "rig-secret"})
+        ctx = self.from_env()
+        self.assertEqual(
+            ctx.user_configuration["disk_config"]["disk_encryption"]["encryption_password"],
+            "rig-secret",
+        )
+
+    def test_deferred_provisioning_discards_account_material(self):
+        # A rig credentials file must not smuggle in users or a root password.
+        self.write_config(self.base_config(defer_provisioning=True))
+        self.write_creds({
+            "users": [{"username": "backdoor", "enc_password": "x", "sudo": True}],
+            "root_enc_password": "x",
+            "encryption_password": "rig-secret",
+        })
+        ctx = self.from_env()
+        self.assertEqual(ctx.user_credentials["users"], [])
+        self.assertNotIn("root_enc_password", ctx.user_credentials)
+        self.assertEqual(ctx.user_credentials["encryption_password"], "rig-secret")
+        synthesized = json.loads(ctx.creds_path.read_text())
+        self.assertEqual(synthesized["users"], [])
+        self.assertNotIn("root_enc_password", synthesized)
+
+    def test_defer_provisioning_strips_account_fields(self):
+        config = self.base_config(defer_provisioning=True)
+        config["!users"] = [{"username": "rig"}]
+        config["!root-password"] = "hunter2"
+        config["root_enc_password"] = "x"
+        config["auth_config"] = {"users": [{"username": "rig"}], "root_enc_password": "x"}
+        self.write_config(config)
+        ctx = self.from_env()
+
+        arch_config = json.loads(ctx.arch_config_path.read_text())
+        for key in ("!users", "!root-password", "root_enc_password", "users"):
+            self.assertNotIn(key, arch_config)
+        self.assertEqual(arch_config["auth_config"], {})
+
+    def test_deferred_provisioning_unencrypted_touches_nothing(self):
+        self.write_config(self.base_config(defer_provisioning=True))
+        ctx = self.from_env()
+        self.assertNotIn("encryption_password", ctx.user_credentials)
+
+
+def make_ctx(target, **overrides):
+    defaults = dict(
+        target=target,
+        defer_provisioning=True,
+        encrypt=False,
+        username="",
+        omarchy_install={"mode": "full_disk", "defer_provisioning": True, "storage": {}},
+        user_configuration={"disk_config": {}},
+        user_credentials={"users": []},
+        state_dir=target / "state",
+        authorized_keys_path=None,
+    )
+    defaults.update(overrides)
+    return types.SimpleNamespace(**defaults)
+
+
+class StageProvisioningStateTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.target = Path(self.tmp.name) / "mnt"
+        self.target.mkdir()
+
+        info_patch = mock.patch.object(phases_impl, "info")
+        info_patch.start()
+        self.addCleanup(info_patch.stop)
+
+        # A fake bundled Node tarball on the "live ISO".
+        self.packages = Path(self.tmp.name) / "opt-packages"
+        self.packages.mkdir()
+        (self.packages / "node-v24.0.0-linux-x64.tar.gz").write_bytes(b"node")
+        node_patch = mock.patch.object(phases_impl, "NODE_PACKAGES_DIR", self.packages)
+        node_patch.start()
+        self.addCleanup(node_patch.stop)
+
+    def install_runtime_provisioning_support(self):
+        service = self.target / "usr/share/omarchy/install/provisioning/omarchy-provision-owner.service"
+        service.parent.mkdir(parents=True, exist_ok=True)
+        service.write_text("[Unit]\n")
+        setup_bin = self.target / "usr/bin/omarchy-provision-owner"
+        setup_bin.parent.mkdir(parents=True, exist_ok=True)
+        setup_bin.write_text("#!/bin/bash\n")
+
+    def provisioning_dir(self):
+        return self.target / "var/lib/omarchy/provisioning"
+
+    def test_normal_install_stages_only_the_node_tarball(self):
+        ctx = make_ctx(self.target, defer_provisioning=False)
+        phases_impl.stage_provisioning_state(ctx)
+
+        self.assertTrue((self.provisioning_dir() / "packages/node-v24.0.0-linux-x64.tar.gz").exists())
+        self.assertFalse((self.provisioning_dir() / "pending").exists())
+        self.assertFalse((self.target / "etc/systemd/system/omarchy-provision-owner.service").exists())
+
+    def test_deferred_provisioning_against_runtime_without_support_fails_clearly(self):
+        ctx = make_ctx(self.target)
+        with self.assertRaisesRegex(RuntimeError, "does not ship"):
+            phases_impl.stage_provisioning_state(ctx)
+
+    def test_deferred_provisioning_without_node_tarball_fails(self):
+        for tarball in self.packages.glob("*.tar.gz"):
+            tarball.unlink()
+        self.install_runtime_provisioning_support()
+        ctx = make_ctx(self.target)
+        with self.assertRaisesRegex(RuntimeError, "Node tarball"):
+            phases_impl.stage_provisioning_state(ctx)
+
+    def test_missing_node_tarball_fails_normal_installs_too(self):
+        # The stash is what makes a later factory reset work offline.
+        for tarball in self.packages.glob("*.tar.gz"):
+            tarball.unlink()
+        ctx = make_ctx(self.target, defer_provisioning=False)
+        with self.assertRaisesRegex(RuntimeError, "Node tarball"):
+            phases_impl.stage_provisioning_state(ctx)
+
+    def test_deferred_provisioning_arms_first_boot_setup(self):
+        self.install_runtime_provisioning_support()
+        ctx = make_ctx(self.target)
+        phases_impl.stage_provisioning_state(ctx)
+
+        self.assertTrue((self.provisioning_dir() / "pending").exists())
+        self.assertTrue((self.target / "etc/systemd/system/omarchy-provision-owner.service").exists())
+        link = self.target / "etc/systemd/system/multi-user.target.wants/omarchy-provision-owner.service"
+        self.assertTrue(link.is_symlink())
+        self.assertEqual(
+            os.readlink(link), "/etc/systemd/system/omarchy-provision-owner.service"
+        )
+        # Unencrypted: no LUKS staging.
+        self.assertFalse((self.provisioning_dir() / "luks-key").exists())
+
+    def test_deferred_provisioning_encrypted_stages_luks_auto_unlock(self):
+        self.install_runtime_provisioning_support()
+        ctx = make_ctx(
+            self.target,
+            user_configuration={"disk_config": {"disk_encryption": {
+                "encryption_type": "luks",
+                "encryption_password": "throwaway-secret",
+            }}},
+        )
+        phases_impl.stage_provisioning_state(ctx)
+
+        # Byte-for-byte the slot passphrase — no trailing newline.
+        self.assertEqual((self.provisioning_dir() / "luks-key").read_text(), "throwaway-secret")
+        keyfile = self.target / "etc/omarchy/provisioning.key"
+        self.assertEqual(keyfile.read_text(), "throwaway-secret")
+        self.assertEqual(keyfile.stat().st_mode & 0o777, 0o600)
+
+        cmdline = (self.target / "etc/limine-entry-tool.d/99-omarchy-provisioning-unlock.conf").read_text()
+        self.assertIn("cryptkey=rootfs:/etc/omarchy/provisioning.key", cmdline)
+        files = (self.target / "etc/mkinitcpio.conf.d/99-omarchy-provisioning-key.conf").read_text()
+        self.assertIn("FILES+=(/etc/omarchy/provisioning.key)", files)
+
+    def test_deferred_provisioning_pre_encrypted_without_passphrase_fails(self):
+        self.install_runtime_provisioning_support()
+        ctx = make_ctx(
+            self.target,
+            omarchy_install={"mode": "protected", "defer_provisioning": True, "storage": {"luks_uuid": "abc"}},
+        )
+        with self.assertRaisesRegex(RuntimeError, "passphrase"):
+            phases_impl.stage_provisioning_state(ctx)
+
+
+class ConfigureLoginDeferProvisioningTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.target = Path(self.tmp.name)
+        self.calls = []
+
+        run_patch = mock.patch.object(
+            phases_impl.subprocess, "run",
+            side_effect=lambda cmd, **kw: (self.calls.append(cmd), CompletedProcess(cmd, 0))[1],
+        )
+        run_patch.start()
+        self.addCleanup(run_patch.stop)
+
+    def test_deferred_provisioning_login_leaves_user_state_to_first_boot(self):
+        ctx = make_ctx(self.target, encrypt=True)
+        phases_impl.configure_login(ctx)
+
+        self.assertTrue((self.target / "etc/sddm.conf.d/99-omarchy-login.conf").exists())
+        self.assertFalse((self.target / "etc/sddm.conf.d/autologin.conf").exists())
+        self.assertFalse((self.target / "var/lib/sddm/state.conf").exists())
+        self.assertTrue(any("sddm.service" in cmd for cmd in self.calls))
+
+    def test_normal_encrypted_login_still_autologs_in(self):
+        ctx = make_ctx(self.target, defer_provisioning=False, encrypt=True, username="jeff")
+        phases_impl.configure_login(ctx)
+
+        autologin = (self.target / "etc/sddm.conf.d/autologin.conf").read_text()
+        self.assertIn("User=jeff", autologin)
+        state = (self.target / "var/lib/sddm/state.conf").read_text()
+        self.assertIn("User=jeff", state)
+
+
+class ConfigureSshAccessDeferProvisioningTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.target = Path(self.tmp.name) / "mnt"
+        self.target.mkdir()
+
+        info_patch = mock.patch.object(phases_impl, "info")
+        info_patch.start()
+        self.addCleanup(info_patch.stop)
+
+        def fake_run(cmd, **kwargs):
+            self.calls.append(cmd)
+            if "ufw" in cmd:
+                rules = self.target / "etc/ufw/user.rules"
+                rules.parent.mkdir(parents=True, exist_ok=True)
+                rules.write_text("-A ufw-user-input -p tcp --dport 22 -j ACCEPT\n")
+            return CompletedProcess(cmd, 0)
+
+        self.calls = []
+        run_patch = mock.patch.object(phases_impl.subprocess, "run", side_effect=fake_run)
+        run_patch.start()
+        self.addCleanup(run_patch.stop)
+
+    def test_deferred_provisioning_stages_keys_for_first_boot(self):
+        keys = Path(self.tmp.name) / "authorized_keys"
+        keys.write_text("ssh-ed25519 AAAA rig@host\n")
+        ctx = make_ctx(self.target, authorized_keys_path=keys)
+
+        phases_impl.configure_ssh_access(ctx)
+
+        staged = self.target / "var/lib/omarchy/provisioning/authorized_keys"
+        self.assertEqual(staged.read_text(), "ssh-ed25519 AAAA rig@host\n")
+        self.assertEqual(staged.stat().st_mode & 0o777, 0o600)
+        # No user yet — nothing under /home, no chown.
+        self.assertFalse((self.target / "home").exists())
+        self.assertFalse(any("chown" in cmd for cmd in self.calls))
+        # The door is still opened for first boot.
+        self.assertTrue(any("sshd.service" in cmd for cmd in self.calls))
+
+
+class CreateFactorySnapshotTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.target = Path(self.tmp.name) / "mnt"
+        self.target.mkdir()
+        self.state_dir = Path(self.tmp.name) / "state"
+        self.state_dir.mkdir()
+
+        info_patch = mock.patch.object(phases_impl, "info")
+        info_patch.start()
+        self.addCleanup(info_patch.stop)
+
+        self.findmnt = {
+            "FSTYPE": "btrfs",
+            "OPTIONS": "rw,noatime,compress=zstd:3,subvol=/@",
+            "SOURCE": "/dev/mapper/omarchy_root[/@]",
+        }
+        self.calls = []
+
+        def fake_run(cmd, **kwargs):
+            self.calls.append(cmd)
+            if cmd[0] == "findmnt":
+                return CompletedProcess(cmd, 0, stdout=self.findmnt[cmd[2]] + "\n", stderr="")
+            if cmd[0] == "mount":
+                # Simulate the top level containing @.
+                (Path(cmd[-1]) / "@").mkdir(parents=True, exist_ok=True)
+            return CompletedProcess(cmd, 0, stdout="", stderr="")
+
+        run_patch = mock.patch.object(phases_impl.subprocess, "run", side_effect=fake_run)
+        run_patch.start()
+        self.addCleanup(run_patch.stop)
+
+    def ctx(self):
+        return make_ctx(self.target, defer_provisioning=False, state_dir=self.state_dir)
+
+    def test_snapshots_root_as_factory(self):
+        phases_impl.create_factory_snapshot(self.ctx())
+
+        top = str(self.state_dir / "factory-top")
+        self.assertIn(["mount", "-o", "subvolid=5", "/dev/mapper/omarchy_root", top], self.calls)
+        self.assertIn(
+            ["btrfs", "subvolume", "snapshot", f"{top}/@", f"{top}/@factory"],
+            self.calls,
+        )
+        self.assertIn(
+            ["btrfs", "property", "set", "-ts", f"{top}/@factory", "ro", "true"],
+            self.calls,
+        )
+        self.assertIn(["umount", top], self.calls)
+
+    def test_factory_snapshot_scrubs_provisioning_credentials(self):
+        # Simulate the snapshot carrying deployment credentials; the scrub
+        # must drop them before the snapshot goes read-only.
+        top = self.state_dir / "factory-top"
+        factory = top / "@factory"
+        secrets = [
+            factory / "var/lib/omarchy/provisioning/authorized_keys",
+            factory / "etc/tailscale/authkey",
+            factory / "etc/omarchy/provisioning.key",
+        ]
+        keep = factory / "var/lib/omarchy/provisioning/groups"
+        for path in [*secrets, keep]:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text("secret")
+
+        phases_impl.create_factory_snapshot(self.ctx())
+
+        for path in secrets:
+            self.assertFalse(path.exists(), path)
+        self.assertTrue(keep.exists())
+
+    def test_non_btrfs_target_skips(self):
+        self.findmnt["FSTYPE"] = "ext4"
+        phases_impl.create_factory_snapshot(self.ctx())
+        self.assertFalse(any(cmd[0] == "mount" for cmd in self.calls))
+
+    def test_non_subvol_root_skips(self):
+        self.findmnt["OPTIONS"] = "rw,noatime"
+        phases_impl.create_factory_snapshot(self.ctx())
+        self.assertFalse(any(cmd[0] == "mount" for cmd in self.calls))
+
+
+if __name__ == "__main__":
+    unittest.main()