config.example.yaml

# Archwright configuration.
#
# Copy to config.yaml and edit:   cp config.example.yaml config.yaml
# config.yaml is gitignored so your real machine config stays out of git.
#
# Any value may reference an environment variable using dollar-brace VAR syntax;
# it is substituted from the environment when the config is loaded (an unset
# variable is an error, and a doubled dollar sign is a literal one). Only values
# are expanded — keys and comments are left untouched, so a literal `$` in a
# comment is fine. Keeps secrets and per-machine values out of the file.
#
# --- imports (optional) -----------------------------------------------------
# Pull in and merge other configs underneath this one, so a machine-specific
# file stays tiny on top of a shared base. Each entry is a local path (resolved
# next to THIS file), a github shorthand (pin it with @ref), or a raw URL.
# Imports merge base-first, importer-wins: keys set here override imported ones,
# and later imports override earlier. See the README for the full merge rules
# and `archwright render` (resolve + merge to a single flat file). Omit for a
# plain standalone config like the rest of this example.
# imports:
#   - archwright.base.yaml                                  # sibling, same dir/repo
#   - github.com/AdamJHall/dotfiles/archwright.kde.yaml@v1  # pinned to a ref
#   - https://example.com/teams/shared.yaml                 # raw URL

system:
  hostname: arch-box
  timezone: Australia/Adelaide   # see: timedatectl list-timezones
  locale: en_AU.UTF-8            # default LANG; enabled by the installer
  locales:                       # additional locales to also enable in /etc/locale.gen
    - en_US.UTF-8
  keymap: us                     # console keymap; see: localectl list-keymaps
  # ntp: true                    # enable NTP time sync (default true when omitted)

user:
  name: adam
  shell: /usr/bin/zsh
  # Supplementary groups. `wheel` gives sudo (configured in stage 50).
  groups: [wheel]

# --- stage selection (optional) ---------------------------------------------
# Skip stages without emptying their config blocks (the persisted equivalent of
# the repeatable --skip flag). Match by stage name or its numeric order — see
# `archwright list-stages`. The --only flag, when given, overrides this.
# stages:
#   disable: [plymouth, grub-theme]

# --- disk layout ------------------------------------------------------------
# `layout` selects the partitioning strategy (default: lvm when omitted, so older
# configs keep working). Exactly the matching sub-block must be present.
# (Phase A renders this into an archinstall config and runs archinstall.)
#
#   lvm    ESP + one LVM volume group across the listed PVs -> root mounted at /
#   btrfs  ESP + a single btrfs root carrying subvolumes (snapshot-friendly)
#   plain  ESP + a single ext4/xfs root partition, no LVM
#
# `swap.type` (default: swapfile):
#   swapfile   post-install /swapfile of `swap.size` (the only LVM-compatible option;
#              archinstall 4.x can't format a raw swap partition in an LVM layout)
#   zram       compressed RAM swap (archinstall's own zram); no on-disk swap, `size` ignored
#   partition  a real linux-swap partition (only valid for plain/btrfs layouts)
#   none       no swap
#
# LVM example below. Disk 1 (the `esp.device`) is partitioned ESP + remainder-as-PV;
# any other PVs listed are consumed as a single full-disk partition.
#
#   nvme0n1p1  <esp.size>   FAT32  -> /boot (EFI System Partition)
#   nvme0n1p2  remainder    LVM PV
#   sda        whole disk   LVM PV
#   sdb        whole disk   LVM PV
disks:
  layout: lvm                   # lvm (default) | btrfs | plain
  esp:
    device: /dev/sda
    size: 4GiB
  swap:
    type: swapfile              # swapfile (default) | zram | partition | none
    size: 4GiB                  # used by swapfile/partition; match RAM for hibernation
  lvm:
    vg: vg0
    lv: root
    filesystem: xfs
    pvs:
      - /dev/sda2            # remainder disk with the partition of the ESP device
      - /dev/sdb             # whole second disk
      - /dev/sdc             # whole second disk
    # --- multiple logical volumes (optional) ---
    # Instead of lv+filesystem above, carve several LVs in the VG — e.g. a
    # fixed-size root plus a /home that takes the rest. Set either lv+filesystem
    # OR volumes, not both. Exactly one volume omits `size` (it gets the rest of
    # the VG) and exactly one is mounted at `/` (the root).
    # volumes:
    #   - { name: root, mountpoint: /,     filesystem: xfs,  size: 64GiB }
    #   - { name: home, mountpoint: /home, filesystem: ext4 }   # rest of the VG

  # --- btrfs alternative (set layout: btrfs) ---
  # On btrfs, prefer swap.type zram or partition — a swapfile needs a dedicated
  # nocow/no-compress subvolume, so it is not emitted for this layout.
  # btrfs:
  #   device: /dev/nvme0n1     # the single disk holding the btrfs root
  #   compress: zstd           # -> compress=zstd mount option (e.g. zstd or zstd:3)
  #   snapshots: snapper       # snapper | none (snapper setup itself is left to a hook)
  #   subvolumes:
  #     - { name: "@",     mountpoint: / }
  #     - { name: "@home", mountpoint: /home }
  #     - { name: "@log",  mountpoint: /var/log }

  # --- plain alternative (set layout: plain) ---
  # plain:
  #   device: /dev/nvme0n1     # single disk: ESP + one root partition, no LVM
  #   filesystem: ext4         # ext4 | xfs

  # --- optional LUKS disk encryption ---
  # Omit this block for no encryption (the default). The LUKS passphrase is the
  # same install password archwright already collects — it is NOT stored here.
  # encryption:
  #   type: lvm_on_luks        # lvm_on_luks: encrypt the PV partitions, LVM on top
  #                            #   (requires the lvm layout; archinstall limits this
  #                            #   to at most 2 PVs)
  #                            # luks: encrypt the single root partition
  #                            #   (requires the plain or btrfs layout)

# --- mirrors ----------------------------------------------------------------
# Optional: run reflector in the live ISO before archinstall, so pacstrap (and
# the installed system, which inherits the mirrorlist) use fast, recent mirrors.
# Omit the section, or set reflector: false, to skip it.
mirrors:
  reflector: true
  countries: [AU]              # --country; omit for worldwide
  latest: 20                   # --latest N most-recently-synced
  fastest: 10                  # --fastest N by measured download rate
  sort: rate                   # rate | age | score | delay | country
  protocols: [https]           # --protocol

# --- software ---------------------------------------------------------------
# Custom pacman repositories. Configured in Phase A's post-install chroot (so a
# custom kernel can be installed before first boot) and persisted into the system.
# Each field is optional — use what a repo needs:
#   key/keyserver : import + locally sign the repo signing key (pacman-key)
#   setup         : a root shell snippet (no sudo) for repos that ship a maintained
#                   installer (e.g. CachyOS, which detects x86-64-v3/v4 CPU
#                   features) — avoids pinning versioned keyring/mirrorlist URLs
#   server/include: the line written into the repo's pacman.conf section
repos:
  - name: cachyos
    setup: |
      curl -fsSL https://mirror.cachyos.org/cachyos-repo.tar.xz | tar -xJ -C /tmp
      cd /tmp/cachyos-repo && ./cachyos-repo.sh --install
  # Example of a purely declarative repo (no script):
  # - name: chaotic-aur
  #   key: 3056513887B78AEB
  #   keyserver: keyserver.ubuntu.com
  #   include: /etc/pacman.d/chaotic-mirrorlist

# The COMPLETE Phase-A pacstrap set, rendered verbatim — nothing is added in
# code. It must list everything the installed system needs at first boot.
# preflight warns about recommended-but-absent entries but never re-adds them.
# Most software belongs in `packages` below (installed in Phase B).
pacstrap:
  - base-devel                   # needed by Phase B to build the AUR helper
  - git                          # same
  - zsh                          # the user's login shell (user.shell)
  - sudo                         # Phase B runs as the user via sudo
  - networkmanager               # network at first boot
  - efibootmgr                   # UEFI boot entry management
  - intel-ucode                  # CPU microcode (or amd-ucode); folded into initramfs

packages:                        # official-repo packages (pacman -S --needed)
  - base-devel
  - git
  - vim
  - alacritty
  - dolphin
  - plasma-meta
  - plasma-login-manager
  - starship
  - fzf

# Kernels. `base` is what archinstall pacstraps for a bootable baseline (it MUST
# be in the live ISO's official repos — the custom `repos:` above are only set up
# later in the chroot — so a custom kernel like linux-cachyos belongs in
# `packages`, NOT `base`). `packages` are extra kernels installed in Phase A from
# the repos above, so first boot can already run them.
kernel:
  base: [linux]                  # pacstrapped baseline; official-repo kernels only
  packages: [linux-cachyos, linux-cachyos-headers]   # extra kernels (installed in the chroot)
  default: linux-cachyos         # GRUB default entry; must be in base ∪ packages
  replace_stock: true            # remove the stock `linux` kernel after install
                                 # (redundant if you set base to your kernel directly)

# The COMPLETE set of flatpak remotes — nothing is added implicitly, so list
# every remote your apps install from (including Flathub).
flatpak_remotes:
  - { name: flathub, url: https://flathub.org/repo/flathub.flatpakrepo }
  # - { name: flathub-beta, url: https://flathub.org/beta-repo/flathub-beta.flatpakrepo }

flatpaks:                        # each app names its remote: "remote:appid"
  - flathub:com.spotify.Client   # (remote must be declared in flatpak_remotes above)
  - flathub:org.mozilla.firefox
  - flathub:com.stremio.Stremio

aur:                             # built via the AUR helper (see aur_helper)
  - 1password
  - 1password-cli

aur_helper: yay                  # yay (default) | paru — installed in Phase B, used for `aur`

# --- bootloader -------------------------------------------------------------
# Which bootloader Phase A installs (via archinstall) and Phase B configures.
# Empty (or `grub`) keeps today's behaviour. `systemd-boot` is reverse-engineered
# and VM-validation-pending (no grub.cfg; cmdline edits go to /etc/kernel/cmdline,
# and `bootctl update` replaces grub-mkconfig).
bootloader:
  kind: grub                     # grub | systemd-boot

# --- boot splash / theming --------------------------------------------------
# Plymouth is installed and configured by archinstall in Phase A: it adds the
# initramfs hook, appends "quiet splash" to the kernel cmdline and sets the theme.
# theme must be one of archinstall's built-in themes (custom themes unsupported):
#   bgrt | fade-in | glow | script | solar | spinner | spinfinity | tribar | text | details
plymouth:
  theme: spinner

grub:
  theme:
    source: vinceliuice          # vinceliuice | url | none
    name: tela                   # vinceliuice theme name (tela|stylish|vimix|whitesur|slaze)
    # screen: 4k                 # vinceliuice only: 1080p|2k|4k|ultrawide|ultrawide2k (default 1080p)
    # background: https://raw.githubusercontent.com/you/dotfiles/main/background.jpg
    #                            # vinceliuice only: local path or http(s) URL to a custom
    #                            # background image. A raw URL is order-safe; a local path
    #                            # must already exist when stage 60 runs (before dotfiles).
    # url: https://example.com/theme.tar.gz   # used when source: url

# --- desktop ----------------------------------------------------------------
# Which desktop environment Phase B themes. Empty or `kde` runs the KDE stage
# below; any other value makes that stage a clean no-op — route that DE's setup
# through `hooks` and your dotfiles instead (only KDE has a built-in stage).
desktop:
  environment: kde               # kde | gnome | hyprland | sway | none

kde:
  # The Plasma global theme, written to kdeglobals as LookAndFeelPackage. Plasma
  # applies it on next login (since 5.24), pulling in the theme's color scheme,
  # cursor, icons, fonts, etc. — no running session needed. Wallpaper is not set
  # here (it lives in the per-host appletsrc); set it manually or via dotfiles.
  look_and_feel: org.kde.breezedark.desktop

# --- dotfiles ---------------------------------------------------------------
# The dotfiles stage (80) applies your dotfiles via a selectable manager. The
# manager defaults to `chezmoi`, so `manager:` is optional; `repo:` is required
# for any manager other than `none`.
#
#   manager:
#     chezmoi  (default) — chezmoi init --apply <repo>, or `chezmoi apply` when
#                          ~/.local/share/chezmoi is already initialized.
#     yadm               — yadm clone <repo>, or `yadm pull` when already cloned.
#     bare-git           — classic bare repo at ~/.dotfiles with --work-tree=$HOME.
#     none               — skip dotfiles entirely (clean no-op).
dotfiles:
  repo: https://github.com/AdamJHall/dotfiles
  # manager: chezmoi

# --- post-dotfiles setup ----------------------------------------------------
# Runs after the dotfiles stage (stage 85). For things a dotfiles repo references but can't
# vendor: oh-my-zsh + its custom plugins, tmux's TPM, theme repos.
#
# `steps` is an ordered list — each entry is either a `clone` or a `command`, and
# they run top to bottom. Order matters: a clone that lands inside another clone's
# tree (the oh-my-zsh custom plugins) must come after it, and a command that must
# precede a clone just goes earlier in the list.
#
# Each clone is idempotent — skipped if its `dest` already exists (or `git pull`ed
# when `update: true`), so the stage is safe to re-run. `~` expands to the user's
# home. A `command` is a shell snippet (the escape hatch for non-clone installers).
#
# We clone oh-my-zsh itself rather than running its installer: the installer
# refuses to run when ~/.oh-my-zsh exists (not re-runnable) and also tries to
# chsh/launch zsh — whereas the shell is set by `user.shell` and the .zshrc comes
# from your dotfiles repo.
setup:
  steps:
    # oh-my-zsh itself FIRST — the custom plugins below clone into its tree.
    - clone:
        url: https://github.com/ohmyzsh/ohmyzsh
        dest: ~/.oh-my-zsh
    # oh-my-zsh custom plugins
    - clone: { url: https://github.com/Aloxaf/fzf-tab, dest: ~/.oh-my-zsh/custom/plugins/fzf-tab }
    - clone: { url: https://github.com/zsh-users/zsh-autosuggestions, dest: ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions }
    - clone: { url: https://github.com/zsh-users/zsh-syntax-highlighting, dest: ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting }
    - clone: { url: https://github.com/joshskidmore/zsh-fzf-history-search, dest: ~/.oh-my-zsh/custom/plugins/zsh-fzf-history-search }
    - clone: { url: https://github.com/zsh-users/zsh-completions, dest: ~/.oh-my-zsh/custom/plugins/zsh-completions }
    - clone: { url: https://github.com/catppuccin/zsh-syntax-highlighting, dest: ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting-catppuccin }
    # tmux plugin manager + theme (then press prefix+I in tmux to install the rest)
    - clone: { url: https://github.com/tmux-plugins/tpm, dest: ~/.config/tmux/plugins/tpm }
    - clone: { url: https://github.com/catppuccin/tmux, dest: ~/.config/tmux/plugins/tmux }
    # Example of a non-clone installer (runs in place, between/after clones):
    # - command: curl -sS https://starship.rs/install.sh | sh -s -- -y

# --- services (optional) ----------------------------------------------------
# systemd units to `systemctl enable` last (after dotfiles + setup) so they
# start on the next boot. `enable` is system units (enabled as root); `user` is
# per-user units (enabled with `systemctl --user`). The .service suffix is
# optional. Units are enabled, not started underneath the current session — the
# common case is a login/display-manager unit that takes over after reboot.
# services:
#   enable:
#     - plasmalogin.service   # SDDM/Plasma login on next boot
#     - bluetooth.service
#   user:
#     - syncthing.service

# --- hooks (optional) -------------------------------------------------------
# Run your own commands at lifecycle points instead of writing a Go stage — the
# general escape hatch for snap/cargo/gsettings/etc. `at` is one of the global
# points (pre-install, post-install, pre-bootstrap, post-bootstrap) or a per-stage
# point before:<stage> / after:<stage> (stage by name; see `archwright list-stages`).
# Each hook sets exactly one of `run` (an inline shell snippet) or `script` (a path
# to a script file). Optional: `root` to run privileged, `env` for extra variables,
# `dir` for the working directory. Hooks are dry-run-aware like everything else.
# hooks:
#   - name: rust toolchain
#     at: after:packages
#     run: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
#   - name: enable bluetooth
#     at: post-bootstrap
#     root: true
#     run: systemctl enable --now bluetooth
#   - name: provision
#     at: post-bootstrap
#     script: ~/bin/provision.sh   # path to a script; `~` expands to $HOME. Existence is
#                                  # NOT checked at validate time (an earlier hook/stage may
#                                  # create it), so a missing path fails only when it runs.
#     dir: ~/work                   # working directory; `~` expands to $HOME
#     env:
#       PROFILE: desktop