omarchy-config/instructions.md

Implementation Instructions for Codex

Goal

Improve the installer's robustness while preserving behavior on a fresh Omarchy installation.

1. Make system updates optional (High Priority)

Current behavior:

yay -Syu --noconfirm

Problem: - Fresh Omarchy installs are already up to date. - Adds unnecessary install time. - Can fail because of mirrors or package updates. - Makes installs less reproducible.

Required change: - Do not update the system by default. - Introduce an environment variable:

UPDATE_SYSTEM=1 ./install.sh

Behavior: - If UPDATE_SYSTEM=1, run:

yay -Syu --noconfirm

• Otherwise skip the full upgrade.

---

2. Verify required commands exist (High Priority)

Before any installation begins, verify required tools exist.

Minimum:

• yay
• git
• systemctl
• fc-cache
• flatpak

Example:

command -v yay >/dev/null || {
    echo "yay is required."
    exit 1
}

Fail early with clear error messages.

---

3. Install packages individually (High Priority)

Current behavior: - One package failure aborts the installer because of set -e.

Desired behavior: - Continue installing remaining packages. - Report failures at the end.

Pseudo-code:

failed_packages=()

for pkg in "${packages[@]}"; do
    if ! yay -S --needed --noconfirm "$pkg"; then
        failed_packages+=("$pkg")
    fi
done

Print a summary if any packages failed.

---

4. Remove duplicate packages (Medium Priority)

Some packages currently appear in multiple package lists.

Deduplicate package sources so each package exists only once.

---

5. Improve service enabling (Medium Priority)

Current implementation checks service existence before enabling.

Instead:

sudo systemctl enable SERVICE || true

or use a more reliable existence check.

Goal: - Never abort because one optional service is unavailable.

---

6. Document directory symlink behavior (Low Priority)

Entire config directories are symlinked.

This is acceptable, but document that: - Future Omarchy config additions inside those directories will not appear automatically. - This is an intentional trade-off.

No implementation change required unless desired.

---

7. Consider copying fonts instead of symlinking (Low Priority)

Current behavior: - Font directory is symlinked.

Consider: - Copying fonts into the user's font directory. - Run fc-cache -fv afterward.

If symlinks are kept, document why.

---

8. Verify Flathub exists before Flatpak installs (Medium Priority)

Before installing Flatpak packages, ensure the Flathub remote exists.

If missing: - Add Flathub automatically. - Continue installation.

---

9. Do not distribute the Git metadata (Low Priority)

When publishing releases or ZIP archives: - Exclude the .git directory. - Ship only the working tree.

No installer changes required.

---

Desired Characteristics

The installer should remain:

• idempotent
• safe to rerun
• backup existing configs
• continue after non-critical failures
• easy to understand
• optimized for fresh Omarchy installations

The default install path should be fast, deterministic, and require minimal user interaction.