alexion/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Trim verbose comments to concise, self-contained notes

Browse Source 
Cut restated "what", domain-glossary framing, cross-file consumption
narration, and against-alternative justification from in-file comments;
keep only non-obvious "why" and load-bearing pointers. Drop the
`generateCompletions` line (a no-op restatement of the upstream default)
and its comment.
This commit is contained in:
alexion
2026-07-19 07:47:54 -04:00
parent 7a07e8458f
commit 644ed2ae7b
11 changed files with 62 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
flake.nix
View File

@@ -1,11 +1,11 @@
{ {
description = "Alexion's NixOS configuration — one flake for every Host"; description = "Alexion's NixOS configuration — one flake for every host";
inputs = { inputs = {
# Base channel: nixos-unstable (rolling, but gated by the NixOS test suite). # Base channel.
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
# Fresher-than-base packages, reachable per-package as `unstable.<name>`. # Fresher packages, reachable per-package as `unstable.<name>`.
nixpkgs-unstable.url = "github:nixos/nixpkgs/nixpkgs-unstable"; nixpkgs-unstable.url = "github:nixos/nixpkgs/nixpkgs-unstable";
# Latest stable release, reachable per-package as `stable.<name>`. # Latest stable release, reachable per-package as `stable.<name>`.
@@ -16,22 +16,20 @@
inputs.nixpkgs.follows = "nixpkgs"; inputs.nixpkgs.follows = "nixpkgs";
}; };
# Neovim configured declaratively in Nix. Must follow our nixpkgs so its # Follows our nixpkgs so its plugins build against the same package set.
# plugins build against the same package set.
nixvim = { nixvim = {
url = "github:nix-community/nixvim"; url = "github:nix-community/nixvim";
inputs.nixpkgs.follows = "nixpkgs"; inputs.nixpkgs.follows = "nixpkgs";
}; };
# Declarative disk partitioning. Each Host declares its own layout; a Host # Declarative disk partitioning; each host declares its own layout.
# that preserves an existing pool simply declares none.
disko = { disko = {
url = "github:nix-community/disko"; url = "github:nix-community/disko";
inputs.nixpkgs.follows = "nixpkgs"; inputs.nixpkgs.follows = "nixpkgs";
}; };
# CachyOS kernel + binary cache. Deliberately NOT following our nixpkgs, so the # CachyOS kernel and binary cache. Pins its own nixpkgs so its cache stays
# chaotic cache stays usable and the kernel is fetched rather than compiled. # usable and the kernel is fetched from it.
chaotic.url = "github:chaotic-cx/nyx/nyxpkgs-unstable"; chaotic.url = "github:chaotic-cx/nyx/nyxpkgs-unstable";
}; };
@@ -42,13 +40,13 @@
my = import ./lib { inherit lib inputs self; }; my = import ./lib { inherit lib inputs self; };
in in
{ {
# The trimmed helper lib: the Auto-loader, the host-builder, the script-from-file helper. # Helper functions for discovering and building hosts.
lib = my; lib = my;
# Every Host under hosts/ is auto-discovered and built. # Every host under hosts/ is discovered and built.
nixosConfigurations = my.mkHosts (self + "/hosts"); nixosConfigurations = my.mkHosts (self + "/hosts");
# `nix flake check` builds each Host's toplevel — the primary test seam. # `nix flake check` builds each host's toplevel.
checks.x86_64-linux = lib.mapAttrs ( checks.x86_64-linux = lib.mapAttrs (
_name: host: host.config.system.build.toplevel _name: host: host.config.system.build.toplevel
) self.nixosConfigurations; ) self.nixosConfigurations;

24
hosts/neogaia/default.nix
View File

@@ -1,8 +1,6 @@
{ pkgs, ... }: { pkgs, ... }:
# neogaia — Dell XPS 13 9380 laptop. # neogaia — Dell XPS 13 9380 laptop.
# # Disk layout is in ./disk.nix; `fileSystems` are derived from it, none declared here.
# The disk layout lives in ./disk.nix (disko); the resulting `fileSystems` are
# derived from it, so none are declared by hand here.
{ {
imports = [ imports = [
./hardware-configuration.nix ./hardware-configuration.nix
@@ -11,44 +9,34 @@
system.stateVersion = "26.05"; system.stateVersion = "26.05";
# systemd-boot on the EFI system partition disko creates. The initrd prompts # systemd-boot on the EFI system partition.
# for the LUKS passphrase (disko wires up boot.initrd.luks.devices), so a
# normal boot unlocks the encrypted root.
boot.loader.systemd-boot.enable = true; boot.loader.systemd-boot.enable = true;
boot.loader.efi.canTouchEfiVariables = true; boot.loader.efi.canTouchEfiVariables = true;
# neogaia runs the CachyOS kernel, selected per-Host via boot.kernelPackages.
boot.kernelPackages = pkgs.linuxPackages_cachyos; boot.kernelPackages = pkgs.linuxPackages_cachyos;
# Intel CPU microcode updates for the XPS 13's Core i7-8565U.
hardware.cpu.intel.updateMicrocode = true; hardware.cpu.intel.updateMicrocode = true;
# Redistributable firmware — carries the ath10k blobs the QCA6174 wifi needs. # Redistributable firmware for the QCA6174 wifi (ath10k blobs).
hardware.enableRedistributableFirmware = true; hardware.enableRedistributableFirmware = true;
# Swap is RAM-backed zram rather than an on-disk partition. # RAM-backed swap; no on-disk swap partition.
zramSwap.enable = true; zramSwap.enable = true;
# NetworkManager drives the wifi so it can be joined from the console. # So wifi can be joined from the console.
networking.networkmanager.enable = true; networking.networkmanager.enable = true;
# An SSH daemon so the rest of the setup can be driven over the network. # So setup can be driven over the network.
services.openssh.enable = true; services.openssh.enable = true;
# fish as the login shell. # fish as the login shell.
modules.fish.enable = true; modules.fish.enable = true;
modules.fish.defaultShell = true; modules.fish.defaultShell = true;
# tmux as the terminal multiplexer.
modules.tmux.enable = true; modules.tmux.enable = true;
# Neovim, configured declaratively via nixvim.
modules.nvim.enable = true; modules.nvim.enable = true;
# Claude Code, Anthropic's CLI, installed via home-manager.
modules.claude-code.enable = true; modules.claude-code.enable = true;
# Locale preferences for the base system.
time.timeZone = "America/New_York"; time.timeZone = "America/New_York";
i18n.defaultLocale = "en_GB.UTF-8"; i18n.defaultLocale = "en_GB.UTF-8";
console.keyMap = "us"; console.keyMap = "us";

12
hosts/neogaia/disk.nix
View File

@@ -1,13 +1,7 @@
{ ... }: { ... }:
# neogaia's disk layout, declared with disko and interpreted by the disko module # neogaia's disk layout for disko: one NVMe disk, GPT, with an EFI system
# the host-builder wires in. This is a per-Host concern: another Host declares a # partition and a LUKS container holding btrfs subvolumes. No swap partition;
# different `disko.devices` (or none, preserving an existing pool by importing it). # swap is zram. disko derives `fileSystems` and `boot.initrd.luks.devices` from this.
#
# One NVMe disk, GPT: an EFI system partition for systemd-boot, and a LUKS
# container holding a btrfs filesystem with subvolumes. Swap is zram (RAM-backed),
# so there is deliberately no on-disk swap partition. disko derives the matching
# `fileSystems.*` and `boot.initrd.luks.devices.*` from this, so a normal boot
# prompts for the passphrase in the initrd and unlocks the encrypted root.
{ {
disko.devices.disk.main = { disko.devices.disk.main = {
type = "disk"; type = "disk";

3
hosts/neogaia/hardware-configuration.nix
View File

@@ -1,6 +1,5 @@
{ lib, modulesPath, ... }: { lib, modulesPath, ... }:
# Placeholder hardware profile for the XPS 13: the host platform and the initrd # Placeholder: regenerate with nixos-generate-config on the target machine.
# modules the machine needs to evaluate and boot.
{ {
imports = [ (modulesPath + "/installer/scan/not-detected.nix") ]; imports = [ (modulesPath + "/installer/scan/not-detected.nix") ];

15
lib/default.nix
View File

@@ -13,10 +13,8 @@ let
mapAttrsToList mapAttrsToList
; ;
# --- Auto-loader --------------------------------------------------------- # Recursively collect every `.nix` file under `dir` as a flat list, for a
# Recursively collect every `.nix` file under `dir`, returned as a flat list # module's `imports`.
# of paths suitable for a module `imports`: a directory recurses, a `.nix`
# file is taken, anything else is skipped.
collectNixFiles = collectNixFiles =
dir: dir:
flatten ( flatten (
@@ -34,10 +32,9 @@ let
) (builtins.readDir dir) ) (builtins.readDir dir)
); );
# --- Host-builder -------------------------------------------------------- # Build one host: every module is imported unconditionally (inert until its
# Build one Host: every Module is imported unconditionally (inert until its # `enable` flag is set), alongside home-manager, chaotic, the shared base, and
# `enable` flag is set), alongside home-manager, chaotic, the shared base, # the host's own directory.
# and the Host's own directory.
mkHost = mkHost =
{ {
hostName, hostName,
@@ -61,7 +58,7 @@ let
]; ];
}; };
# Discover every Host (a subdirectory of `hostsDir`) and build each one. # Discover every host (a subdirectory of `hostsDir`) and build each one.
mkHosts = mkHosts =
hostsDir: hostsDir:
let let

19
modules/claude-code/claude-code.nix
View File

@@ -3,19 +3,14 @@
lib, lib,
... ...
}: }:
# Claude Code — Anthropic's CLI — for the primary user, configured declaratively # Claude Code for the primary user, configured through home-manager, which ships
# through home-manager. home-manager ships the package and manages ~/.claude: # the package and manages ~/.claude. Login credentials are left unmanaged so they
# the global agent instructions (./CLAUDE.md), the skills tree (./skills), the # survive rebuilds.
# attention-bell hook (./hooks), and settings.json (the model and the hook
# wiring). Login credentials are left unmanaged so they survive rebuilds;
# signing in without a browser, as needed over the console or SSH, is covered in
# ./authentication.md.
let let
cfg = config.modules.claude-code; cfg = config.modules.claude-code;
user = config.user.name; user = config.user.name;
# Rings the terminal bell so tmux flags the background pane; wired to both the # Rings the terminal bell so tmux flags the background pane.
# end of a turn and attention notifications below.
bellHook = [ bellHook = [
{ {
hooks = [ hooks = [
@@ -37,12 +32,10 @@ in
# Global agent instructions, rendered to ~/.claude/CLAUDE.md. # Global agent instructions, rendered to ~/.claude/CLAUDE.md.
context = ./CLAUDE.md; context = ./CLAUDE.md;
# One directory per skill, each carrying its SKILL.md, symlinked under # One directory per skill, symlinked under ~/.claude/skills.
# ~/.claude/skills.
skills = ./skills; skills = ./skills;
# Installed executable at ~/.claude/hooks/attention-bell.sh, where the # Installed at ~/.claude/hooks/attention-bell.sh, referenced by the settings below.
# settings hooks reference it.
hooks."attention-bell.sh" = builtins.readFile ./hooks/attention-bell.sh; hooks."attention-bell.sh" = builtins.readFile ./hooks/attention-bell.sh;
settings = { settings = {

7
modules/example.nix
View File

@@ -1,12 +1,11 @@
{ config, lib, ... }: { config, lib, ... }:
# The Auto-loader reference example. Every real Module copies this shape: it is # Reference example for the module shape: imported unconditionally, but inert
# imported unconditionally but its body stays inert until a Host sets the # until a host sets its `enable` flag.
# `enable` flag, so each Host reads as a checklist of `enable = true` lines.
let let
cfg = config.modules.example; cfg = config.modules.example;
in in
{ {
options.modules.example.enable = lib.mkEnableOption "the Auto-loader reference example Module"; options.modules.example.enable = lib.mkEnableOption "the reference example module";
config = lib.mkIf cfg.enable { config = lib.mkIf cfg.enable {
environment.etc."skeleton-example".text = "This Module is enabled.\n"; environment.etc."skeleton-example".text = "This Module is enabled.\n";

26
modules/fish/fish.nix
View File

@@ -4,10 +4,7 @@
pkgs, pkgs,
... ...
}: }:
# fish for the primary user, configured natively through home-manager. Wires the # fish for the primary user, configured through home-manager.
# done and bang-bang plugins, a fastfetch greeting, a bat-backed manpager, helper
# functions, the eza aliases, and vi-style command-line editing. Set fish as the
# default login shell by also turning on `modules.fish.defaultShell`.
let let
cfg = config.modules.fish; cfg = config.modules.fish;
user = config.user.name; user = config.user.name;
@@ -24,28 +21,21 @@ in
}; };
config = lib.mkIf cfg.enable { config = lib.mkIf cfg.enable {
# System-level fish: registers it in /etc/shells and installs vendor # System-level fish registers it in /etc/shells and installs vendor completions.
# completions.
programs.fish.enable = true; programs.fish.enable = true;
users.users.${user}.shell = lib.mkIf cfg.defaultShell pkgs.fish; users.users.${user}.shell = lib.mkIf cfg.defaultShell pkgs.fish;
home-manager.users.${user} = { home-manager.users.${user} = {
home.packages = with pkgs; [ home.packages = with pkgs; [
eza # modern ls with git awareness and icons; backs the ls aliases eza # backs the ls/la/ll aliases
bat # syntax-highlighting cat/pager; backs the manpager below bat # backs the manpager
fastfetch # system-info banner printed as the shell greeting fastfetch # the shell greeting
wget # non-interactive HTTP downloader; backs the wget abbreviation wget # backs the wget abbreviation
]; ];
programs.fish = { programs.fish = {
enable = true; enable = true;
# Relied-on upstream defaults, pinned so a future change can't silently
# alter behaviour.
generateCompletions = true;
# Prefer abbreviations over aliases when other modules wire up fish
# shortcuts, matching the abbreviation-first style below.
preferAbbrs = true; preferAbbrs = true;
plugins = [ plugins = [
@@ -94,7 +84,6 @@ in
}; };
functions = { functions = {
# Run fastfetch as the welcome message.
fish_greeting = "fastfetch"; fish_greeting = "fastfetch";
history = { history = {
@@ -114,8 +103,7 @@ in
}; };
}; };
# Read from a real fish file, which home-manager renders into # Rendered by home-manager into ~/.config/fish/config.fish.
# ~/.config/fish/config.fish.
interactiveShellInit = builtins.readFile ./config.fish; interactiveShellInit = builtins.readFile ./config.fish;
}; };
}; };

14
modules/nvim/nvim.nix
View File

@@ -5,12 +5,8 @@
inputs, inputs,
... ...
}: }:
# Neovim for the primary user, configured declaratively through nixvim. Options, # Neovim for the primary user, configured declaratively through nixvim. The
# keymaps, and plugin settings are typed Nix; the imperative remainder (the # imperative remainder (colorscheme, Neogit blame autocmd) lives in ./config.lua.
# colorscheme call and the Neogit blame-toggle autocmd) lives in ./config.lua.
# Plugins come from nixpkgs — no plugin manager and no runtime cloning — and
# treesitter grammars are built by Nix, so no compiler is needed at runtime. git
# backs the git plugins; ripgrep and fd back the picker.
let let
cfg = config.modules.nvim; cfg = config.modules.nvim;
user = config.user.name; user = config.user.name;
@@ -32,7 +28,7 @@ in
]; ];
globals.mapleader = " "; globals.mapleader = " ";
globals.clipboard = "osc52"; # neovim's built-in OSC 52 provider, no external binary needed globals.clipboard = "osc52"; # built-in OSC 52 provider, no external binary needed
opts = { opts = {
clipboard = "unnamedplus"; clipboard = "unnamedplus";
@@ -180,8 +176,8 @@ in
}; };
}; };
# gbprod/nord.nvim; nixvim's colorschemes.nord is a different plugin. Set # gbprod/nord.nvim (nixvim's colorschemes.nord is a different plugin);
# up in ./config.lua. # set up in ./config.lua.
extraPlugins = [ pkgs.vimPlugins.gbprod-nord ]; extraPlugins = [ pkgs.vimPlugins.gbprod-nord ];
extraConfigLua = builtins.readFile ./config.lua; extraConfigLua = builtins.readFile ./config.lua;

10
modules/tmux/tmux.nix
View File

@@ -3,10 +3,8 @@
lib, lib,
... ...
}: }:
# tmux for the primary user, configured natively through home-manager. The # tmux for the primary user, configured through home-manager. Settings without a
# settings home-manager exposes as options are set here; every setting it has # home-manager option are read from ./extra.conf.
# no option for is read verbatim from ./extra.conf. No tmux plugin manager is
# used.
let let
cfg = config.modules.tmux; cfg = config.modules.tmux;
user = config.user.name; user = config.user.name;
@@ -21,8 +19,8 @@ in
prefix = "C-Space"; prefix = "C-Space";
keyMode = "vi"; keyMode = "vi";
mouse = true; mouse = true;
baseIndex = 1; # windows and panes count from 1. baseIndex = 1;
clock24 = true; # 24-hour clock in the clock-mode overlay. clock24 = true;
escapeTime = 10; # short Esc delay so exiting insert mode in nvim isn't laggy. escapeTime = 10; # short Esc delay so exiting insert mode in nvim isn't laggy.
historyLimit = 10000; historyLimit = 10000;
terminal = "tmux-256color"; terminal = "tmux-256color";

25
system/default.nix
View File

@@ -5,13 +5,12 @@
inputs, inputs,
... ...
}: }:
# The Skeleton's shared base config: the pieces every Host carries regardless of # Shared base config carried by every host.
# which Modules it enables — overlays, the `user`, flakes, and home-manager.
let let
inherit (lib) mkOption types; inherit (lib) mkOption types;
user = config.user; user = config.user;
# Instantiate an extra nixpkgs source for the same platform as the base pkgs. # Args to instantiate an extra nixpkgs source on the base platform.
pinArgs = prev: { pinArgs = prev: {
inherit (prev.stdenv.hostPlatform) system; inherit (prev.stdenv.hostPlatform) system;
config.allowUnfree = true; config.allowUnfree = true;
@@ -23,7 +22,7 @@ in
type = types.str; type = types.str;
default = "alexion"; default = "alexion";
description = '' description = ''
The primary interactive user this Host is built for. Drives both the The primary interactive user this host is built for. Drives both the
system account and the home-manager user in lockstep. system account and the home-manager user in lockstep.
''; '';
}; };
@@ -35,9 +34,8 @@ in
}; };
config = { config = {
# Base is nixos-unstable; reach a package fresher with `unstable.<name>` or # Reach fresher packages with `unstable.<name>` or pin with `stable.<name>`.
# pin it rock-solid with `stable.<name>`. chaotic's overlay is added by its # chaotic's overlay is added by its own module, not here.
# own NixOS module, imported by the host-builder.
nixpkgs.overlays = [ nixpkgs.overlays = [
(_final: prev: { (_final: prev: {
unstable = import inputs.nixpkgs-unstable (pinArgs prev); unstable = import inputs.nixpkgs-unstable (pinArgs prev);
@@ -46,22 +44,21 @@ in
]; ];
nixpkgs.config.allowUnfree = true; nixpkgs.config.allowUnfree = true;
# Flakes + a baseline so `nixos-rebuild switch` works from the console. # Flakes, so `nixos-rebuild switch` works from the console.
nix.settings.experimental-features = [ nix.settings.experimental-features = [
"nix-command" "nix-command"
"flakes" "flakes"
]; ];
# The chaotic binary cache, so the CachyOS kernel is substituted rather than # chaotic's binary cache, so the CachyOS kernel is fetched rather than
# compiled. Appended with the `extra-` options so cache.nixos.org and any # compiled. The `extra-` prefix keeps cache.nixos.org alongside it.
# other substituter are kept alongside it.
nix.settings.extra-substituters = [ "https://nyx-cache.chaotic.cx/" ]; nix.settings.extra-substituters = [ "https://nyx-cache.chaotic.cx/" ];
nix.settings.extra-trusted-public-keys = [ nix.settings.extra-trusted-public-keys = [
"nyx-cache.chaotic.cx:dJxTrgMC3V3cFfyIiBQDQorG6k1LsqurH/srpMSq7qk=" "nyx-cache.chaotic.cx:dJxTrgMC3V3cFfyIiBQDQorG6k1LsqurH/srpMSq7qk="
]; ];
environment.systemPackages = [ pkgs.git ]; environment.systemPackages = [ pkgs.git ];
# Primary user, in wheel. No password is set here. # Primary user, in the wheel group. No password set here.
users.users.${user.name} = { users.users.${user.name} = {
isNormalUser = true; isNormalUser = true;
description = user.description; description = user.description;
@@ -69,8 +66,8 @@ in
}; };
# home-manager as a NixOS module: one `nixos-rebuild switch` builds the # home-manager as a NixOS module: one `nixos-rebuild switch` builds the
# system and the user environment atomically, sharing the system's pkgs # system and user environment together, sharing the system's pkgs and
# (with our overlays) and installing user packages into the system profile. # installing user packages into the system profile.
home-manager = { home-manager = {
useGlobalPkgs = true; useGlobalPkgs = true;
useUserPackages = true; useUserPackages = true;