Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0005: authentic Omarchy port with a declared mutable island

Status: accepted (2026-07-06)

Context

The desktop target is Omarchy (basecamp/omarchy), an Arch product. ward-os rode omarchy-nix, a third-party flake frozen at an Omarchy 1.x snapshot with a dormant upstream - it silently inherited abandoned choices. Re-expressing all of Omarchy as nix attrsets is the opposite failure: maximal contortion.

Decision

Vendor upstream basecamp/omarchy hash-pinned via fetchFromGitHub (tag + sha in omarchy/UPSTREAM), patch out the Arch machinery (omarchy/PATCHES.md), prune the rest (omarchy/prune.list). ~/.local/share/omarchy is a read-only symlink into the store. ~/.config/omarchy/current/{theme,background} are real mutable symlinks in persisted $HOME - the DECLARED MUTABLE ISLAND - so instant theme switching works exactly like upstream. Config files under the island are rendered copies, not store symlinks, so upstream’s sed-style theme tooling works. The flake declares the default; activation seeds the island if absent; trellis gate reports current-vs-declared as a promotable knob.

Alternatives considered

  • omarchy-nix: frozen pin, dormant upstream - the lesson this reverses.
  • Full nix re-expression: breaks upstream’s own tooling and every future diff.
  • Symlink-farm the island into the store: kills instant switching.

Consequences

New Omarchy releases land as one reviewed diff-and-refresh PR. The island is the only deliberately mutable config surface; everything else is store-backed.