1. Download the latest CachyOS ISO from cachyos.org and flash it to a USB stick (Ventoy, or dd if you're feeling brave).
2. Boot the new machine from USB (usually F2/F12/Esc at power-on for the boot menu; disable Secure Boot if it complains).
3. In the CachyOS installer, when asked for a desktop, choose Hyprland — this pulls in the cachyos-hypr-noctalia dots that everything below assumes.
4. Finish the install, reboot into the new system, connect to Wi-Fi, and open kitty.
5. Full system update before anything else:

sudo pacman -Syu

New machine, new SSH key. Generate one and hand the public half to GitHub.

ssh-keygen -t ed25519 -C "eddie@$(hostname)"
cat ~/.ssh/id_ed25519.pub

Copy the whole ssh-ed25519 ... line, then on github.com: Settings → SSH and GPG keys → New SSH key, paste, name it after the machine.

Verify the handshake:

ssh -T git@github.com

Clone the bare repo, set up the dots alias, and check your config out over the stock dots.

git clone --bare git@github.com:YOURUSER/dotfiles.git $HOME/.dotfiles
alias -s dots '/usr/bin/git --git-dir=$HOME/.dotfiles --work-tree=$HOME'
dots checkout -f
dots config status.showUntrackedFiles no

• checkout -f deliberately overwrites the fresh install's default configs with yours — that's the point.
• The alias -s saves permanently in fish, so dots works in every future terminal.

Different laptop = possibly different display name. Do this before logging out, or the workspace rules point at a ghost monitor (you know the error notification by heart).

hyprctl monitors

Note the output name (e.g. eDP-1). Then:

nano ~/.config/hypr/config/variables.lua

• Set MONITOR1 = "eDP-1" (or whatever hyprctl monitors said).
• Leave MONITOR2/MONITOR3 as "" until real screens exist for them.

Also glance at ~/.config/hypr/config/monitors.lua — a different panel may want a different mode and scale than the old machine (check resolution options in the hyprctl monitors output).

Now log out and back in. This is the moment: your binds, workspaces, resize submaps, UK keyboard, natural scrolling, bar and theme should all appear.

CachyOS doesn't ship an AUR helper by default. Build yay once, use it forever:

sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/yay.git /tmp/yay
cd /tmp/yay
makepkg -si
cd ~

Sanity check:

yay --version

The dotfiles brought ~/.pkglist.txt (everything explicitly installed) and ~/.aurlist.txt (the AUR subset). Repo packages first — this filters the AUR names out so pacman doesn't choke (fish syntax):

sudo pacman -S --needed - < (grep -vxFf ~/.aurlist.txt ~/.pkglist.txt | psub)

Then the AUR ones (Sublime, Slack, and friends) with yay:

yay -S --needed - < ~/.aurlist.txt

The dotfiles repo can't touch /etc — restore those from your tracked ~/etc-backup/ folder:

sudo cp ~/etc-backup/logind.conf /etc/systemd/logind.conf
sudo systemctl restart systemd-logind

That's the lid closes → suspend behaviour. Then re-check the lock half in Noctalia: Super + Z → Lock Screen → Behaviour → Lock on suspend (the setting travels with your Noctalia config, but verify — one lid-close test tells you everything).

• If the old machine ran hypridle: systemctl --user enable --now hypridle.service
• If you'd switched login to noctalia-greeter/greetd: that's a re-install on this machine (greeter package, setup script, /etc/greetd/config.toml from etc-backup, then systemctl disable sddm && systemctl enable greetd). If you never left SDDM, skip.

Check whether it came along with the repo:

type dotsync

If fish prints the function — done, skip ahead. If "not found", paste this whole block into the terminal and press Enter (the final line saves it permanently):

function dotsync -d "Commit and push dotfile changes"
    pacman -Qqe > ~/.pkglist.txt
    pacman -Qqem > ~/.aurlist.txt
    dots add -u
    if test (count $argv) -gt 0
        dots commit -m "$argv"
    else
        dots commit -m "sync: "(date '+%Y-%m-%d %H:%M')
    end
    dots push
end
funcsave dotsync

Then make sure the function itself is tracked, so no future machine has to do this step:

dots add ~/.config/fish/functions/dotsync.fish
dotsync restore dotsync on new machine

• Wallpapers — the Noctalia setting travelled, the image files didn't. Copy them into the folder Noctalia expects (check Settings → Wallpaper for the path), then re-pick via the wallpaper panel. Palette-from-wallpaper re-themes everything automatically.
• Chrome — sign in; synced PWAs restore the --app-id targets your keybinds use. (--app=URL style binds just work with no sign-in.)
• Slack / Sublime — sign in / add licence.
• Ark — should be back via the package list; right-click a zip in Dolphin to confirm Extract entries.

Then fly the test circuit — thirty seconds, touches everything we ever debugged:

• Super+2 switches workspace; Super+Shift+4 moves a window there — no red error notification
• Super+←/→ combo resize binds / submap behave
• Shift+3 types £ (kb_layout gb)
• two-finger scroll natural scrolling on the touchpad
• Slack keybind launches and tiles (and isn't fighting the scratchpad key)
• close the lid suspends → reopen → lock screen
• dotsync test commits & pushes clean