Home

One flake that builds a NixOS desktop, a nix-darwin Mac, standalone home-manager profiles for any machine with Nix, a disposable agent VM, and a set of project templates.

Contents

Doc	Read it when
Getting started	Putting the repo on a new machine, or forking it
Workflow	Day-to-day: editing, rebuilding, updating, rolling back
Architecture	You want to know how the flake, hosts, modules and home profiles fit together
System modules	Looking up what a file in modules/ owns
Services	Media stack, VPN namespace, local LLMs, backups, mounts, ports
Desktop	Hyprland, keybinds, the Quickshell bar, lock/idle, recording, dictation
Theming	themectl, palette format, templates, adding a theme
Development	Languages, editors, templates, tool flakes, the agent VM, foreign binaries
Scripts & commands	Every dots-* command, themectl, voxtype, fish abbrevs
Troubleshooting	Something broke — known failure modes and rough edges
Nix cheatsheet	Quick command reference, mostly for starting projects

Neovim has its own doc: config/nvim/README.md.

These files are the source of truth. The wiki is generated from them on every push to main — edit here, not there.

The shape of it

flake.nix ──┬─ nixosConfigurations.nixos ── hosts/nixos + modules/* + home-manager(desktop)
            ├─ nixosConfigurations.claude-vm ── hosts/claude-vm (qemu, no home-manager)
            ├─ darwinConfigurations.mac ── hosts/darwin + home-manager(desktop → darwin profile)
            ├─ homeConfigurations.<user>@{linux,linux-desktop,aarch64-linux,mac}
            ├─ templates.{zig,rust,haskell,c,python,lisp,beam,typst,latex}
            └─ formatter (nixfmt-tree)

home/home.nix ── profiles/base.nix           always
             ├── profiles/linux-desktop.nix  Linux + profile "desktop"
             └── profiles/darwin.nix         macOS

config/  ── symlinked live into ~/.config (edit, no rebuild)
config/themes/ + themectl ── rendered into ~/.local/state/dots/theme/

Three rules

1. git add before nix sees it. The flake is a git checkout; untracked files do not exist to Nix.
2. One owner per path. A config directory is either a live symlink into config/ or managed by a home-manager module, never both.
3. Edits under config/ are live; edits to .nix and scripts/ need a rebuild. Scripts are packaged with writeShellApplication, so the installed copy is a store path.

---

_{Source: docs/README.md}