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
dots config push.autoSetupRemote true

• 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.
• push.autoSetupRemote is the important one for later: a fresh clone's first push otherwise fails with "the current branch master has no upstream branch" — this makes first pushes (and therefore dotsync) just work on every new machine.

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.

Docking & clamshell mode (lid closed, external monitor as the only screen) — when a big screen enters the picture:

1. Fill in MONITOR2 = "DP-3" (or whatever hyprctl monitors calls it) in variables.lua, and give it a block in monitors.lua with its mode/position/scale.
2. Don't assign it workspaces if it's a clamshell-only screen — workspaces 1–5 migrate to it automatically once the internal panel is off. Per-monitor workspace splits are for genuinely dual-screen desks.
3. Add conditional lid handling so the internal panel turns off when the lid closes — but only when docked. Two scripts plus two binds (check hyprctl devices for the switch name; mirror the lid-open values from your monitors.lua MONITOR1 block):

# ~/.local/bin/lid-close  (chmod +x)
#!/bin/sh
# Disable internal panel ONLY when the external monitor is connected
if hyprctl monitors | grep -q "DP-3"; then
    hyprctl eval 'hl.monitor({ output = "eDP-1", disabled = true })'
fi

# ~/.local/bin/lid-open  (chmod +x)
#!/bin/sh
# Always restore the internal panel on lid open (harmless if already on)
hyprctl eval 'hl.monitor({ output = "eDP-1", mode = "preferred", position = "auto-right", scale = 1.33 })'

-- binds.lua — Clamshell: conditional panel kill/restore
hl.bind("switch:on:Lid Switch",  hl.dsp.exec_cmd("~/.local/bin/lid-close"), { locked = true })
hl.bind("switch:off:Lid Switch", hl.dsp.exec_cmd("~/.local/bin/lid-open"),  { locked = true })

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.

Pull first — the function lives in the repo now, so on any machine set up after July 2026 it should simply arrive:

dots pull
type dotsync

If fish prints the function — done, skip to the test below. If "not found", paste this whole block into the terminal and press Enter (order matters: funcsave on the last line is what creates the file on disk — you can't dots add it before this exists):

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

Either way, finish with a live-fire test — this proves the whole chain (function → commit → push) on this machine:

dotsync first sync from 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 undocked: suspends → reopen → lock screen, display comes back (conditional lid scripts doing their job)
• docked + lid closed internal panel dies, workspaces consolidate onto the external — and Meta+1 goes somewhere you can see
• dotsync test commits & pushes clean, no upstream complaints (proven in T-2, but fly it again)