omarchy-iso/plans/oem-install.md

OEM Install + Factory Reset Plan

Goal

An install mode that installs the entire system but defers user account setup to first boot. On first power-on the machine asks for the user, creates it, and lands in the already-installed system — the classic OEM out-of-box experience. The same machinery doubles as a "reset computer" option for wiping a machine before selling it.

Core idea: "OEM state" as a first-class system state

Define one canonical state — fully installed, no user, setup pending — and make both paths produce it:

• ISO OEM mode ends the install in OEM state instead of creating the user.
• Reset returns a running machine to OEM state.

OEM state is: a fully installed system plus /var/lib/omarchy/oem/ containing:

File	Purpose
pending	Flag that arms the first-boot setup service
packages/node-v*.tar.gz	Node tarball copied off the ISO's /opt/packages (~30MB) so omarchy-finalize-user works offline at first boot
groups	Deferred usermod -aG groups written by system setup (see below)
luks-key	Throwaway LUKS passphrase for encrypted installs, staged for auto-unlock until first-boot re-key

Why the seam is nearly clean already

Everything in the orchestrator through finalize_limine_boot is user-independent except five touch points:

1. installer.create_users — useradd + password (root gets the same password).
2. Three usermod -aG calls inside omarchy-setup-system's scripts (config/docker.sh, hardware/input-group.sh, hardware/apple/fix-t2.sh — docker/input/video). This is the only reason omarchy-setup-system requires the user to exist (its getent check).
3. run_chroot_finalizer → omarchy-finalize-user as the user. Already offline-safe: /etc/skel does the heavy seeding at useradd time, omarchy-mise-install writes lazy wrappers, and the only external artifact is the bundled Node tarball from /opt/packages (install/user/mise.sh).
4. configure_login — SDDM state.conf and the encrypted-install autologin.
5. Encryption — the user's password is the LUKS passphrase.

Nothing in hardware setup, Limine, hibernation, snapper, or package installation cares who the user is.

First boot: omarchy-oem-setup.service

Ships in the omarchy runtime package (so reset can arm it without the ISO):

• ConditionPathExists=/var/lib/omarchy/oem/pending
• Before=display-manager.service, conflicts getty@tty1, TUI on tty1.
• Runs the user form extracted from the configurator (Step 2: username, password, full name, email). The configurator is bash+gum, so the form moves into a runtime-shipped omarchy-oem-setup script that reuses the exact ISO look (logo, Tokyo Night VT palette).

Then it does what the ISO would have done:

1. useradd with wheel + the groups from /var/lib/omarchy/oem/groups, set user + root password.
2. omarchy-finalize-user as the user, with a setup context that points at the stashed Node tarball (a sibling of the existing iso-chroot context).
3. The configure_login writes: SDDM state.conf, autologin for encrypted installs.
4. If luks-key exists: cryptsetup luksChangeKey to the user's password, delete the stash, remove the auto-unlock keyfile, rebuild initramfs.
5. Git identity from the form (the OMARCHY_USER_NAME/OMARCHY_USER_EMAIL path in install/user/git.sh).
6. Remove /var/lib/omarchy/oem/, hand off to SDDM.

The user lands in their session exactly like a normal install.

Encryption: keep it, Pop!_OS-style

Do not force OEM installs unencrypted. Install encrypted with a generated throwaway passphrase, stage a keyfile so boot auto-unlocks during the OEM window, and have first-boot setup re-key to the user's chosen password (step 4 above). Limine and mkinitcpio don't care what the passphrase is. This preserves encrypted-by-default without the machine builder ever knowing the end user's password.

ISO-side changes (this repo)

• Configurator: an OEM choice in the install-mode step that skips Step 2 (user), plus a cidata oem marker file that replaces the user_credentials.json requirement — that's what actual OEM imaging rigs will use via autoinstall.
• Orchestrator: oem: true in the omarchy_install JSON. Swaps the three user phases (create_users inside arch_install_system, run_chroot_finalizer, the user parts of configure_login) for a "stage OEM state" phase that writes /var/lib/omarchy/oem/ and enables omarchy-oem-setup.service in the target. InstallContext.username needs an OEM-safe fallback (creds are absent).
• Factory snapshot: at the end of every install (not just OEM), take a read-only snapshot of @ kept at the top level as @factory — outside snapper's .snapshots, so cleanup timers and the Limine snapshot menu never touch it. Zero bytes at creation; grows only with drift. This is what makes reset a true factory reset.

Runtime-side changes (omarchy repo)

• omarchy-oem-setup + omarchy-oem-setup.service (the OOBE above).
• omarchy-system-factory-reset (below).
• Relax omarchy-setup-system: when the install user doesn't exist yet, the three usermod -aG scripts append to /var/lib/omarchy/oem/groups instead of failing the getent check.

Reset: omarchy-system-factory-reset

Behind a very explicit confirmation (typed, not y/n):

1. Point the default subvolume at a writable snapshot of @factory; stage a next-boot wipe unit.
2. On reboot: recreate @home (subvolume delete/create — instant, no rm -rf), clear @log, delete snapper snapshots, reset machine-id, SSH host keys, NetworkManager connections, Tailscale state, SDDM state; run fstrim.
3. Re-arm OEM state: pending flag, groups, Node tarball (kept from install or re-fetched into @factory at install time), and on encrypted machines a throwaway LUKS re-key — the buyer never needs the seller's passphrase.

Next boot is the same OOBE as a fresh OEM install. User-installed packages and /etc drift are gone, which is what "wipe and sell" actually promises.

Machines installed before @factory existed get a degraded reset — keep the current system, wipe users/state only — with that caveat surfaced in the confirmation.

Honest limitations (document these)

• On unencrypted disks this is deletion, not forensic erasure. fstrim helps on SSDs; offer cryptsetup reencrypt or blkdiscard + reinstall for the paranoid.
• luksChangeKey changes the passphrase but not the volume key; freed extents remain readable to someone with raw-device access and the new passphrase. Same remedy as above.
• A reset machine boots with day-one packages until it updates — same as a fresh install.

Sequencing

The OOBE lives in the omarchy runtime package, but the ISO's OEM phase depends on it existing. So:

1. Ship the runtime side first (omarchy-oem-setup, service, reset command, omarchy-setup-system relaxation).
2. ISO OEM mode then asserts the service file exists in the target before offering the mode.
3. Factory snapshot can land with either half; reset requires both.

Validation

• VM: OEM install (encrypted + unencrypted) → reboot → OOBE → session; verify LUKS passphrase is the user's, throwaway key gone, groups applied, omarchy-finalize-user state marker present.
• VM: normal install → use system → omarchy-system-factory-reset → OOBE as new user; verify no trace of prior user (home, NM connections, tailscale, machine-id, host keys, snapper snapshots).
• Autoinstall: cidata drive with oem marker and no credentials → unattended OEM install.
• Negative: OEM ISO built against a runtime package lacking the service fails the install with a clear error, not a user-less boot loop.