Trim over-commented Chunk 3+/4 work

A pass over the install scripts, dev-tools commands, and Hyprland Lua
files that I had stuffed with explain-everything preambles. Most of
those rationales (which files ship where, why hyprctl setenv doesn't
suffice, etc.) belong in commit messages or PR descriptions, not in
code people have to read forever. Kept the few comments that document
genuinely non-obvious behaviour: the keybind-env reason for hl.env in
envs.lua, why the runtime PAM seds stay scripted in
increase-lockout-limit, the chroot/--now distinction in chroot.sh, and
the dev-pkg-test split-install reason.

bin/omarchy-dev-link

@@ -7,11 +7,10 @@
 
 set -euo pipefail
 
+# Sudo wipes HYPRLAND_INSTANCE_SIGNATURE, so the live-session refresh below
+# can't reach hyprctl. Run as user; we sudo internally for the conf write.
 if [[ $EUID -eq 0 ]]; then
-  echo "Error: run omarchy-dev-link as your user, not under sudo. The script" >&2
+  echo "Error: run omarchy-dev-link as your user, not under sudo." >&2
-  echo "       will prompt for sudo when it needs to write /etc/omarchy.conf." >&2
-  echo "       (Invoking under sudo wipes HYPRLAND_INSTANCE_SIGNATURE so the" >&2
-  echo "       live-session refresh can't reach hyprctl.)" >&2
   exit 1
 fi
 
@@ -37,7 +36,6 @@ target=$(realpath -e "$1" 2>/dev/null) || {
   exit 1
 }
 
-# Sanity: looks like an omarchy-installer checkout?
 for required in bin default shell; do
   if [[ ! -d "$target/$required" ]]; then
     echo "Warning: $target/$required not found — does this look like an omarchy-installer checkout?" >&2
@@ -47,12 +45,9 @@ done
 echo "Pointing Omarchy at $target"
 printf 'export OMARCHY_PATH="%s"\n' "$target" | sudo tee /etc/omarchy.conf >/dev/null
 
-# Update the current shell so the rest of this script and anything spawned
-# from it see the new path.
 export OMARCHY_PATH="$target"
 export PATH="$target/bin:$PATH"
 
-# Update the live Hyprland session if one is running.
 if command -v hyprctl >/dev/null 2>&1 && hyprctl version &>/dev/null; then
   hyprctl setenv OMARCHY_PATH "$target" >/dev/null
   hyprctl setenv PATH "$PATH" >/dev/null

bin/omarchy-dev-pkg-test

@@ -48,7 +48,7 @@ trap 'rm -rf "$build_dir"' EXIT
 
 cp -a "$PKGBUILD_DIR/." "$build_dir/"
 
-# Mark the build with a versioned dev pkgver so pacman -Q makes the source obvious.
+# pkgver=dev.<sha>[.dirty] so pacman -Q makes the source obvious.
 short_sha=$(git -C "$CHECKOUT" rev-parse --short HEAD 2>/dev/null || echo "local")
 dirty=""
 if [[ -d "$CHECKOUT/.git" ]] && [[ -n "$(git -C "$CHECKOUT" status --porcelain)" ]]; then
@@ -65,11 +65,9 @@ echo
 cd "$build_dir"
 OMARCHY_SRC="$CHECKOUT" makepkg -s --skipchecksums --noconfirm "${@:3}"
 
-# Install separately so we can pass --overwrite='*' to pacman. In dev mode
+# Install separately so we can pass --overwrite='*' (makepkg -i can't).
-# the package commonly conflicts with files left behind by previous
+# Dev builds frequently conflict with files left behind by previous
-# script-installed Omarchy versions (plymouth themes, /etc drop-ins,
+# script-installed Omarchy versions; the build is the authoritative state.
-# sudoers, etc.). makepkg -i forwards a fixed set of flags to pacman and
-# doesn't expose --overwrite.
 built_pkg=$(ls -t "$build_dir"/*.pkg.tar.* 2>/dev/null | grep -v '\.sig$' | head -1)
 if [[ -z $built_pkg ]]; then
   echo "Error: no built package found in $build_dir" >&2

bin/omarchy-dev-status

@@ -4,7 +4,6 @@
 # omarchy:group=dev
 
 if [[ -f /etc/omarchy.conf ]]; then
-  # Source in a subshell so we don't mutate the caller's env.
   configured=$(
     OMARCHY_PATH=
     # shellcheck disable=SC1091

bin/omarchy-dev-unlink

@@ -6,8 +6,7 @@
 set -euo pipefail
 
 if [[ $EUID -eq 0 ]]; then
-  echo "Error: run omarchy-dev-unlink as your user, not under sudo. The script" >&2
+  echo "Error: run omarchy-dev-unlink as your user, not under sudo." >&2
-  echo "       will prompt for sudo when it needs to remove /etc/omarchy.conf." >&2
   exit 1
 fi
 
@@ -30,13 +29,11 @@ fi
 sudo rm -f /etc/omarchy.conf
 echo "Removed /etc/omarchy.conf"
 
-# Update the current shell.
 export OMARCHY_PATH=/usr/share/omarchy
-# Drop the prepended checkout bin/ from PATH if present.
+# Drop the checkout bin/ that dev-link prepended.
 PATH=$(printf '%s' "$PATH" | tr ':' '\n' | grep -vFx "$(dirname "$0")" | paste -sd:)
 export PATH
 
-# Update the live Hyprland session.
 if command -v hyprctl >/dev/null 2>&1 && hyprctl version &>/dev/null; then
   hyprctl setenv OMARCHY_PATH /usr/share/omarchy >/dev/null
   hyprctl setenv PATH "$PATH" >/dev/null

bin/omarchy-update-system-pkgs

@@ -7,13 +7,9 @@ set -e
 
 echo -e "\e[32m\nUpdate system packages\e[0m"
 
-# Transition --overwrite: the Omarchy 4 package refactor moves files that
+# Transition --overwrite: previous script-installed Omarchy wrote these paths
-# previous Omarchy installs wrote as unowned files (via install scripts) into
+# as unowned files; pacman would refuse the omarchy-settings upgrade on first
-# the omarchy-settings package. Pacman would otherwise refuse to install
+# encounter. Drop each entry once the transition release is the baseline.
-# omarchy-settings on the first upgrade because the paths "exist in
-# filesystem". Limited to the exact paths the package now owns; remove the
-# corresponding --overwrite entry once the transition release is everyone's
-# baseline.
 sudo pacman -Syyu --noconfirm \
   --overwrite '/etc/docker/daemon.json' \
   --overwrite '/etc/gnupg/dirmngr.conf' \

config/hypr/hyprland.lua

@@ -1,10 +1,6 @@
 -- Learn how to configure Hyprland: https://wiki.hypr.land/Configuring/Start/
 
--- Force re-evaluation of Omarchy modules on every hyprctl reload. Lua caches
+-- Drop cached omarchy modules so hyprctl reload re-reads them from disk.
--- already-required modules in package.loaded, so without this clear, changes
--- to default/hypr/*.lua (and user ~/.config/hypr/*.lua) in a checkout wouldn't
--- take effect after `hyprctl reload` even though hyprland.lua re-runs.
--- Cheap: package.loaded is small.
 for k in pairs(package.loaded) do
   if k:match("^default%.hypr") or k:match("^hypr%.") then
     package.loaded[k] = nil

default/hypr/envs.lua

@@ -24,21 +24,13 @@ hl.env("XDG_SESSION_DESKTOP", "Hyprland")
 -- Use XCompose file.
 hl.env("XCOMPOSEFILE", paths.home .. "/.XCompose")
 
--- Propagate OMARCHY_PATH and PATH to processes spawned by Hyprland (keybinds,
+-- hyprctl setenv doesn't reach keybind dispatcher env; use hl.env.
--- dispatchers, autostart). hyprctl setenv doesn't reach the env captured for
--- bind exec at config-load time, so omarchy-dev-link reaches this via
--- hyprctl reload re-running envs.lua with the new paths.omarchy_path.
 hl.env("OMARCHY_PATH", paths.omarchy_path)
 
--- Prepend $OMARCHY_PATH/bin to PATH, deduping any prior occurrence so
--- reloads don't accumulate duplicates.
 local bin_dir = paths.omarchy_path .. "/bin"
-local current_path = os.getenv("PATH") or "/usr/local/bin:/usr/bin"
 local kept = {}
-for entry in current_path:gmatch("[^:]+") do
+for entry in (os.getenv("PATH") or "/usr/local/bin:/usr/bin"):gmatch("[^:]+") do
-  if entry ~= bin_dir then
+  if entry ~= bin_dir then table.insert(kept, entry) end
-    table.insert(kept, entry)
-  end
 end
 table.insert(kept, 1, bin_dir)
 hl.env("PATH", table.concat(kept, ":"))

default/hypr/paths.lua

@@ -4,18 +4,14 @@
 
 local home = os.getenv("HOME")
 
--- Resolve OMARCHY_PATH with omarchy-dev-link awareness. If /etc/omarchy.conf
+-- /etc/omarchy.conf wins over process env so dev-link survives stale sessions.
--- exists it wins over the process env, so dev-link takes effect even when
--- Hyprland's own env is stale (the launching session never re-read the conf).
 local function read_dev_link_omarchy_path()
   local f = io.open("/etc/omarchy.conf", "r")
   if not f then return nil end
   local value
   for line in f:lines() do
     local v = line:match('^%s*export%s+OMARCHY_PATH=%s*"?([^"\n]+)"?')
-    if v and #v > 0 then
+    if v and #v > 0 then value = v end
-      value = v
-    end
   end
   f:close()
   return value

etc/profile.d/omarchy.sh

@@ -1,14 +1,7 @@
-# Source /etc/omarchy.conf first so dev-link or other system overrides can
-# pre-set OMARCHY_PATH (and anything else) before the defaults run.
-# install.sh's script-mode export still wins because /etc/omarchy.conf uses
-# the same :- guard.
 [ -f /etc/omarchy.conf ] && . /etc/omarchy.conf
 export OMARCHY_PATH="${OMARCHY_PATH:-/usr/share/omarchy}"
 
-# Prepend $OMARCHY_PATH/bin if it exists. In normal package mode this is a
+# omarchy-dev-link: prepend checkout bin/ so it shadows /usr/bin/omarchy-*.
-# no-op: bins ship to /usr/bin (already on PATH), and /usr/share/omarchy/bin
-# doesn't exist. When omarchy-dev-link is active OMARCHY_PATH points at a
-# local checkout, whose bin/ then overrides the /usr/bin copies.
 case ":$PATH:" in
   *":$OMARCHY_PATH/bin:"*) ;;
   *) [ -d "$OMARCHY_PATH/bin" ] && export PATH="$OMARCHY_PATH/bin:$PATH" ;;

install/config/docker.sh

@@ -1,7 +1,3 @@
-# Docker config files ship via omarchy-settings. This script only handles
-# runtime side: reload systemd-resolved so the new drop-in takes effect and
-# add the current user to the docker group. docker.socket enable lives in
-# install/config/enable-services.sh.
 sudo systemctl restart systemd-resolved
 sudo usermod -aG docker ${USER}
 sudo systemctl daemon-reload

install/config/enable-services.sh

@@ -1,12 +1,7 @@
-# Central place for unconditional service enables. Services that should NOT
+# _only variant skips --now to avoid starting iwd/docker/power-profiles-daemon
-# be started during install (sddm, ufw) live in their own scripts. Hardware-
+# during install (existing iwd would be interrupted; the others should defer
-# gated services (t2fanrd, intel_lpmd, thermald, omarchy-nvme-suspend-fix)
+# to first boot). sddm, ufw, and hardware-gated services stay in their own
-# also live with their detection.
+# scripts.
-#
-# Two variants:
-#   chrootable_systemctl_enable      -> enable + start now (safe to start)
-#   chrootable_systemctl_enable_only -> enable only (don't risk starting during
-#                                       install)
 chrootable_systemctl_enable      bluetooth.service
 chrootable_systemctl_enable      cups.service
 chrootable_systemctl_enable      cups-browsed.service

install/config/fast-shutdown.sh

@@ -1,5 +1 @@
-# The two faster-shutdown drop-ins
-# (etc/systemd/system.conf.d/10-faster-shutdown.conf,
-#  etc/systemd/system/user@.service.d/10-faster-shutdown.conf)
-# ship via omarchy-settings. Reload systemd so the new drop-ins take effect.
 sudo systemctl daemon-reload

install/config/gpg.sh

@@ -1,4 +1,2 @@
-# etc/gnupg/dirmngr.conf ships via omarchy-settings. Restart dirmngr so it
-# picks up the new keyserver list and timeout.
 sudo gpgconf --kill dirmngr || true
 sudo gpgconf --launch dirmngr || true

install/config/hardware/bluetooth.sh

@@ -1,5 +1,3 @@
-# bluetooth.service enable lives in install/config/enable-services.sh.
-
 # Persist last power state across reboots (default AutoEnable=true overrides it)
 sudo sed -i 's/^#\?AutoEnable=.*/AutoEnable=false/' /etc/bluetooth/main.conf
 

install/config/increase-file-watchers.sh

@@ -1,3 +1 @@
-# etc/sysctl.d/90-omarchy-file-watchers.conf ships via omarchy-settings.
-# Apply the new sysctl values immediately.
 sudo sysctl --system >/dev/null 2>&1

install/config/increase-lockout-limit.sh

@@ -1,15 +1,9 @@
-# The faillock.conf side ships via the omarchy-settings etc-overrides
+# /etc/pam.d/{system-auth,sddm-autologin} are upstream-owned and the changes
-# (deny = 10). The two PAM file edits below remain a script because
+# are insertions, not full-file overrides, so they stay scripted.
-# /etc/pam.d/system-auth and /etc/pam.d/sddm-autologin are upstream-owned
-# and the changes are insertions, not full-file overrides.
-
-# Increase lockout limit to 10 and decrease timeout to 2 minutes
 sudo sed -i 's|^\(auth\s\+required\s\+pam_faillock.so\)\s\+preauth.*$|\1 preauth silent deny=10 unlock_time=120|' "/etc/pam.d/system-auth"
 sudo sed -i 's|^\(auth\s\+\[default=die\]\s\+pam_faillock.so\)\s\+authfail.*$|\1 authfail deny=10 unlock_time=120|' "/etc/pam.d/system-auth"
 
-# Ensure lockout limit is reset on restart.
+# Drop both lines before re-adding authsucc so reruns don't duplicate it.
-# Delete BOTH the preauth and authsucc pam_faillock lines before re-adding
-# authsucc, so re-running the installer doesn't duplicate the authsucc line.
 sudo sed -i '/pam_faillock\.so preauth/d'  /etc/pam.d/sddm-autologin
 sudo sed -i '/pam_faillock\.so authsucc/d' /etc/pam.d/sddm-autologin
 sudo sed -i '/auth.*pam_permit\.so/a auth        required    pam_faillock.so authsucc' /etc/pam.d/sddm-autologin

install/config/mimetypes.sh

@@ -1,10 +1,5 @@
-# Most MIME default mappings now ship as config/mimeapps.list (via /etc/skel
-# for new users; existing users keep their own). This script handles the
-# runtime side: refresh applications, set Chromium as the system default web
-# browser (omarchy-install-browser overrides if the user picks something
-# else later), and wire HEY.desktop as the mailto handler — HEY.desktop is
-# generated by install/packaging/webapps.sh at install time so it can't
-# live in /etc/skel/.config/mimeapps.list.
 omarchy-refresh-applications
 xdg-settings set default-web-browser chromium.desktop
+# HEY.desktop is generated by install/packaging/webapps.sh, so the mapping
+# can't ship as a static /etc/skel/.config/mimeapps.list entry.
 xdg-mime default HEY.desktop x-scheme-handler/mailto

install/config/powerprofilesctl-rules.sh

@@ -1,8 +1,5 @@
-# The udev rule (/etc/udev/rules.d/99-omarchy-power-profile.rules) ships via
+# Remove the pre-rename legacy path on every run (idempotent vs the one-shot
-# omarchy-settings. power-profiles-daemon.service enable lives in
+# migration, which only fires once per user).
-# install/config/enable-services.sh. This script just reloads udev so the
-# rule takes effect and removes the pre-rename legacy path (idempotent for
-# re-install/downgrade tests).
 sudo rm -f /etc/udev/rules.d/99-power-profile.rules
 sudo udevadm control --reload 2>/dev/null
 sudo udevadm trigger --subsystem-match=power_supply 2>/dev/null

install/config/wifi-powersave-rules.sh

@@ -1,8 +1,5 @@
-# The udev rule (/etc/udev/rules.d/99-omarchy-wifi-powersave.rules) ships via
+# Remove the pre-rename legacy path on every run (idempotent vs the one-shot
-# omarchy-settings. This script just reloads udev so the rule takes effect
+# migration, which only fires once per user).
-# without waiting for a reboot.
-# Also remove the pre-rename legacy path in case the old installer ran since
-# the one-shot migration completed (idempotency for re-install/downgrade tests).
 sudo rm -f /etc/udev/rules.d/99-wifi-powersave.rules
 sudo udevadm control --reload
 sudo udevadm trigger --subsystem-match=power_supply

install/helpers/chroot.sh

@@ -7,14 +7,12 @@ chrootable_systemctl_enable() {
   fi
 }
 
-# Like chrootable_systemctl_enable but never passes --now, so the service is
+# Like chrootable_systemctl_enable but never passes --now. Use for services
-# only enabled for the next boot. Use for services that are either already
+# we shouldn't (re)start mid-install (iwd interrupts the network; docker and
-# running (and re-starting would interrupt the install — iwd) or that shouldn't
+# power-profiles-daemon should defer to first boot).
-# auto-start during install (docker, power-profiles-daemon).
 chrootable_systemctl_enable_only() {
   sudo systemctl enable $1
 }
 
-# Export the functions so they're available in subshells
 export -f chrootable_systemctl_enable
 export -f chrootable_systemctl_enable_only