Setup guide

How a fresh CachyOS/Arch machine becomes one of mine. Everything is driven by just — run just from the repo root to list every recipe (full list in the justfile reference).

Fresh machine

git clone git@github.com:rdlu/dotfiles.git ~/.dotfiles
cd ~/.dotfiles

just full-auto       # base packages, languages, CLI tools, fish, yazi, fastfetch
just full-auto-gui   # the above + kitty + the niri/Noctalia graphical stack

full-auto chains: packages → dev-setup → cli-tools → fish-shell → helix-editor → yazi-file-manager → fastfetch. The packages step is interactive — it pauses so you can review /etc/xdg/reflector/reflector.conf and add the Chaotic AUR include to /etc/pacman.conf.

On a host that loads the audio-production category, also add this under [options] in /etc/pacman.conf. zam-plugins pulls in zam-plugins-standalone, which ships one launcher entry per plugin (17 of them) that clutter the app launcher; the plugins and standalone binaries are unaffected. Reinstall the package afterwards to drop already-installed entries:

NoExtract   = usr/share/applications/com.zamaudio.*

If you are not running full-auto, run just packages first: it sets up Flatpak/Flathub, reflector mirrors, the Chaotic AUR repository, and the paru AUR helper that every other recipe uses.

The stow model

Configuration is deployed as symlinks with GNU Stow (--dotfiles mode: dot-foo in the repo becomes ~/.foo).

• Base packages (stowed on every machine): home git idea scripts terminal lazyvim vim systemd niri
• Host overlays in hosts/<hostname>/ (stowed only on the matching machine): display layout, thermal sensors, machine-specific tools. The two hosts are daisy (AMD) and xps (Intel).

just stow         # symlink base + this host's overlay (auto-detected)
just stow-check   # dry-run: show what would change, touch nothing
just unstow       # remove all symlinks (host overlay first, then base)

--no-folding is used so base and host overlays can both populate shared directories (~/.config/mise, ~/.local/share/applications) without tree-folding conflicts.

Services

just services-enable

Enables the expected systemd user services (mpd, mpd-mpris, syncthing if installed, solaar) and Noctalia, the niri session shell (bar, notifications, lock, idle), which starts with the graphical session.

Tool versions: pacman + mise

Two deliberate layers:

• pacman/paru installs tools available in the repos (just cli-tools).
• mise pins versions for languages and tools not in the repos: shared config in terminal/dot-config/mise/config.toml, per-host additions in hosts/<hostname>/dot-config/mise/conf.d/<hostname>.toml.

Day to day

just update   # paru -Syu, mise upgrade, fisher, yazi plugins, nvim Lazy sync
just doctor   # health check: tools, login shell, host overlay, services, symlinks

Docs

This site itself is part of the repo:

just docs-setup   # one-time: install hugo, pandoc, typst and the fonts
just docs         # regenerate markdown from configs, build HTML site + PDFs
just docs-serve   # live-preview the site while editing

tools/gen-docs.py (Python stdlib, no deps) re-reads tmux.conf, binds.kdl, and the justfile and rewrites the generated blocks in the markdown. Hugo with the vendored Hextra theme builds the HTML site from site/, which mounts docs/ as its content, into site/public/; GitHub Pages serves it at dotfiles.dlu.one. Each page starts with Hugo front matter (title, linkTitle for the sidebar, weight for its order) and keeps its own # H1, which only the PDFs show. pandoc + Typst render the PDFs into docs/pdf/, which the site links directly; tools/pandoc-docs.lua drops the front matter there. The just recipes are thin shims over the equivalent mise tasks (mise run docs, etc.).