Let's help our agent friends a little to understand the Omarchy code base

This should eradicate the first failed auth attempt after
sleep/hibernation

AGENTS.md

@@ -0,0 +1,62 @@
+# Style
+
+- Two spaces for indentation, no tabs
+- Use Bash syntax for conditionals: `[[ -f $file ]]`, not `[ -f "$file" ]`
+
+# Command Naming
+
+All commands start with `omarchy-`. Prefixes indicate purpose:
+
+- `cmd-` - check if commands exist, misc utility commands
+- `pkg-` - package management helpers
+- `hw-` - hardware detection (return exit codes for use in conditionals)
+- `refresh-` - copy default config to user's `~/.config/`
+- `restart-` - restart a component
+- `launch-` - open applications
+- `install-` - install optional software
+- `setup-` - interactive setup wizards
+- `toggle-` - toggle features on/off
+- `theme-` - theme management
+- `update-` - update components
+
+# Helper Commands
+
+Use these instead of raw shell commands:
+
+- `omarchy-cmd-missing` / `omarchy-cmd-present` - check for commands
+- `omarchy-pkg-missing` / `omarchy-pkg-present` - check for packages
+- `omarchy-pkg-add` - install packages (handles both pacman and AUR)
+- `omarchy-hw-asus-rog` - detect ASUS ROG hardware (and similar `hw-*` commands)
+
+# Config Structure
+
+- `config/` - default configs copied to `~/.config/`
+- `default/themed/*.tpl` - templates with `{{ variable }}` placeholders for theme colors
+- `themes/*/colors.toml` - theme color definitions (accent, background, foreground, color0-15)
+
+# Refresh Pattern
+
+To copy a default config to user config with automatic backup:
+
+```bash
+omarchy-refresh-config hypr/hyprlock.conf
+```
+
+This copies `~/.local/share/omarchy/config/hypr/hyprlock.conf` to `~/.config/hypr/hyprlock.conf`.
+
+# Migrations
+
+To create a new migration, run `omarchy-dev-add-migration --no-edit`. This creates a migration file named after the unix timestamp of the last commit.
+
+Migration format:
+- No shebang line
+- Start with an `echo` describing what the migration does
+
+Example:
+```bash
+echo "Disable fingerprint in hyprlock if fingerprint auth is not configured"
+
+if omarchy-cmd-missing fprintd-list || ! fprintd-list "$USER" 2>/dev/null | grep -q "finger"; then
+  sed -i 's/fingerprint:enabled = .*/fingerprint:enabled = false/' ~/.config/hypr/hyprlock.conf
+fi
+```

bin/omarchy-hibernation-setup

@@ -59,9 +59,10 @@ echo "HOOKS+=(resume)" | sudo tee "$MKINITCPIO_CONF" >/dev/null
 
 # Configure suspend-then-hibernate
 echo "Configuring suspend-then-hibernate"
-sudo mkdir -p /etc/systemd/logind.conf.d /etc/systemd/sleep.conf.d
+sudo mkdir -p /etc/systemd/logind.conf.d /etc/systemd/sleep.conf.d /usr/lib/systemd/system-sleep
 sudo cp "$OMARCHY_PATH/default/systemd/lid.conf" /etc/systemd/logind.conf.d/
 sudo cp "$OMARCHY_PATH/default/systemd/hibernate.conf" /etc/systemd/sleep.conf.d/
+sudo cp -p "$OMARCHY_PATH/default/systemd/system-sleep/keyboard-backlight" /usr/lib/systemd/system-sleep/
 
 # Regenerate initramfs
 echo "Regenerating initramfs..."

bin/omarchy-setup-fingerprint

@@ -58,11 +58,13 @@ EOF
 add_hyprlock_fingerprint_icon() {
   print_info "Adding fingerprint icon to hyprlock placeholder text..."
   sed -i 's/placeholder_text = .*/placeholder_text = <span> Enter Password 󰈷 <\/span>/' ~/.config/hypr/hyprlock.conf
+  sed -i 's/fingerprint:enabled = .*/fingerprint:enabled = true/' ~/.config/hypr/hyprlock.conf
 }
 
 remove_hyprlock_fingerprint_icon() {
   print_info "Removing fingerprint icon from hyprlock placeholder text..."
   sed -i 's/placeholder_text = .*/placeholder_text = Enter Password/' ~/.config/hypr/hyprlock.conf
+  sed -i 's/fingerprint:enabled = .*/fingerprint:enabled = false/' ~/.config/hypr/hyprlock.conf
 }
 
 remove_pam_config() {

config/hypr/hyprlock.conf

@@ -39,5 +39,5 @@ input-field {
 }
 
 auth {
-    fingerprint:enabled = true
+    fingerprint:enabled = false
 }

default/systemd/system-sleep/keyboard-backlight

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# Turn off keyboard backlight before hibernate to prevent hang on power-off.
+# The ASUS keyboard controller can block S4 shutdown if LEDs are active.
+
+if [[ $1 == "pre" && $2 == "hibernate" ]]; then
+  device=""
+  for candidate in /sys/class/leds/*kbd_backlight*; do
+    if [[ -e "$candidate" ]]; then
+      device="$(basename "$candidate")"
+      break
+    fi
+  done
+
+  if [[ -n "$device" ]]; then
+    brightnessctl -d "$device" set 0 >/dev/null 2>&1
+  fi
+fi

migrations/1770372978.sh

@@ -0,0 +1,5 @@
+echo "Disable fingerprint in hyprlock if fingerprint auth is not configured"
+
+if omarchy-cmd-missing fprintd-list || ! fprintd-list "$USER" 2>/dev/null | grep -q "finger"; then
+  sed -i 's/fingerprint:enabled = .*/fingerprint:enabled = false/' ~/.config/hypr/hyprlock.conf
+fi