Skip to content

Manual: say first boot encrypts unless the installer recorded a decline - #112

Merged
scottjones merged 1 commit into
omacom:mainfrom
only21mil:manual-first-boot-encrypts
Nov 9, 2026
Merged

scottjones merged 1 commit into
omacom:mainfrom
only21mil:manual-first-boot-encrypts

Conversation

@only21mil

Copy link
Copy Markdown
Contributor

Problem

The Encryption and passwords page says: "A Mac that was not asked to encrypt is never touched. The conversion needs a marker the installer writes and refuses to run without it." The Boot chain page says the same: "The unit requires a pending marker written by the installer and refuses to run without it, so a Mac installed without encryption is never touched." The install pages agree: first boot converts the root to LUKS "if you asked for it" (Install on a Mac) or "if the installer asked for it" (How an install works).

The code does the opposite. When /boot/efi/omarchy/install.conf is missing, the encrypt hook takes it as encrypt=1 (omarchy_mac_encrypt_read_conf in files/usr/lib/omarchy/initcpio/omarchy-mac-encrypt), and first boot records format=1 and encrypt=1 (consume_install_conf in omarchy-mac-first-boot; mac-first-boot-test.sh requires it). Only encrypt=0 keeps a fresh image plaintext. The marker the hook does require is the image's own: pending and deferred-steps in /var/lib/omarchy/mac-first-boot. The installer doesn't write it.

So an owner who said no to encryption, but whose installer failed to save that choice, gets an encrypted disk, while the manual says that can't happen.

Change

Docs only. One passage on each of four pages now describes what the code does:

  • 04-security.md: the first boot encrypts unless the installer recorded a no, and encrypts if the record is missing. A no holds through a factory reset. Only a freshly written image converts, so an installed Mac is never touched.
  • 10-boot.md: the unit converts only a fresh image (pending plus deferred-steps). It converts unless install.conf sets encrypt=0, and a missing file means encrypt. The decline is recorded as phase=declined in /boot/omarchy/encrypt.state, so it outlives that file and a factory reset (reopen_encrypt_state in lib/factory-reset.sh leaves it).
  • 02-install.md and 09-install-flow.md: first boot converts the root unless the installer recorded a no (encrypt=0).

Scope and approval

There are no code changes, because the code and its tests already agree on the default. Only the manual was wrong. The initramfs hook's help() text already says "absent or encrypt=1", so it stays. There's no omarchy-mac version bump because no package behaviour changes. Nothing boot-critical changes, so no cold-boot evidence applies. No other passage on these pages changes.

Verification

  • python3 mac-manual/diagrams/gen.py, then git status --porcelain -- mac-manual/diagrams: exit 0 with no diff, on base and candidate.
  • python3 mac-manual/build.py with markdown==3.7: "built 14 pages into mac-manual/dist", exit 0, on base and candidate. The builder checks every link.
  • .github/scripts/check-scope and .github/scripts/check-architecture-gates: exit 0.
  • A diff of the base and candidate dist/ trees changes only security/, boot/, install/ and install-flow/.
  • Each new claim was read against the code: omarchy_mac_encrypt_read_conf, omarchy_mac_encrypt_fresh_image, the declined branch and omarchy_mac_encrypt_write_state in the hook, consume_install_conf in omarchy-mac-first-boot, and reopen_encrypt_state in lib/factory-reset.sh.

The Encryption and passwords page built from main, before this change:

Encryption and passwords page on main, saying the conversion needs a marker the installer writes

The same page built from this branch:

Encryption and passwords page on this branch, saying the first boot encrypts unless the installer recorded a no

The Boot chain page's Encryption section built from main:

Boot chain Encryption section on main, saying the unit requires a pending marker written by the installer

The same section built from this branch:

Boot chain Encryption section on this branch, naming the fresh-image marker, the encrypt=0 decline and its record

The Install on a Mac page's last install step, from main and then from this branch:

Install page on main: first boot converts the root to LUKS if you asked for it

Install page on this branch: first boot converts the root to LUKS unless the installer recorded that you said no

The How an install works page's First boot list, from main and then from this branch:

How an install works on main: converts to LUKS if the installer asked for it

How an install works on this branch: converts to LUKS unless the installer recorded encrypt=0

Not checked

  • An install with encryption declined, or with install.conf missing, on a real Mac. These claims rest on the code paths and tests named above.
  • The package and integration suites. This change touches neither.

Prior PRs

None make this change. #13 and #69 add text next to these passages but don't change them.

Generated with Claude Opus 5.5 and GPT-6.1 Sol in T3 Code Nightly

…ecline

The security and boot pages said the conversion needs a marker the
installer writes, so a Mac not asked to encrypt is never touched, and the
install and install-flow summaries said it converts only if asked. The
encrypt hook treats a missing install.conf as encrypt=1, and only
encrypt=0, recorded as phase=declined on Boot, keeps a fresh image
plaintext. What keeps an installed Mac untouched is the image's own
first-boot marker and deferred-steps file, not anything the installer
writes. The decline also survives a factory reset (reopen_encrypt_state).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@scottjones scottjones left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, it reads clearly. We checked every statement against omarchy-mac-encrypt and they all hold: a missing install.conf means encrypt, encrypt=0 is recorded as phase=declined and skips encryption, and factory reset keeps the decline. The installer's InstallConf.swift writes encrypt=0, so the two sides agree.

@only21mil

Copy link
Copy Markdown
Contributor Author

Note

🤖 Opus 5.5 replying on behalf of Victor.

@scottjones, thank you for checking every statement against omarchy-mac-encrypt. Confirming that the installer's InstallConf.swift writes encrypt=0 closes the one side this PR couldn't see from this repo, so the manual now matches both ends.

@scottjones
scottjones merged commit 8147a62 into omacom:main Nov 9, 2026
4 of 5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants