nix-update

name	nix-update
description	Guides updating, adding, or refactoring Nix code in this dotfiles repository. Use this skill whenever the user wants to add a new package, configure a program, create a NixOS/Home Manager module, modify a host, add a service, or make any change to .nix files in the repo. Also trigger when the user asks about the repo's Nix architecture or where something should go.

Nix Update Skill

Repository Architecture

This is a multi-host NixOS + Home Manager dotfiles repo. Each host is a self-contained flake under hosts/<hostname>/:

hosts/
  lapdog/       # ThinkPad X1 2-in-1, primary dev machine
  chungus/      # Desktop AI/compute workstation (RTX 4090, 64 GB RAM)
  mini/         # Always-on home server (many services, aka. dogdot)
  inspiron7520/ # Secondary machine (unused)

Each host flake contains:

• flake.nix — inputs and outputs (nixpkgs unstable, home-manager, etc.)
• configuration.nix — NixOS system config
• hardware.nix — bootloader, GPU, filesystem mounts (autogenerated, do not modify it)
• home.nix — Home Manager config for user dog
• services/ — modular service files (especially on mini and chungus)

Shared Modules

modules/home-manager/ is imported by all hosts and contains reusable Home Manager modules:

modules/home-manager/
  default.nix          # Aggregates everything; sets up dog.* options
  dog.nix              # User-level options (dotfilesPath, etc.)
  lib/
    default.nix        # Reusable Nix helper functions (dog-lib)
    bubblewrap-ai.nix  # Helper for sandboxed AI apps
  programs/            # Per-app configs (emacs, firefox, git, i3, wezterm…)
  presets/             # Grouped presets (linux.nix, xorg.nix)
  services/            # Shared service modules

modules/flakes/ — standalone Nix flakes used as local inputs (e.g., custom packages/derivations). Use this location when creating a new derivation for a package that doesn't exist in nixpkgs.

.config/ — application config files tracked directly in the repo (bare repo pattern, $HOME as work tree).

Reusable Library Functions

Add reusable Nix helper functions to:

modules/home-manager/lib/default.nix

The library is exposed to all modules via dog-lib (set in _module.args). Current helpers: dotfilesSymlink (out-of-store symlink into the repo), bubblewrapAi (sandboxed AI app wrapper).

When you find yourself writing the same pattern more than once, or when a new helper would simplify multiple modules, add it to dog-lib here.

Making Changes

Where to Put Things

What you're doing	Where it goes
New per-app Home Manager config	modules/home-manager/programs/<app>.nix, then import in programs/default.nix
New reusable preset (group of programs)	modules/home-manager/presets/
Host-specific NixOS config	hosts/<hostname>/configuration.nix
Host-specific Home Manager config	hosts/<hostname>/home.nix
New mini service	hosts/mini/services/<service>.nix
New derivation / custom package	modules/flakes/<name>/ as a standalone flake
Reusable Nix helper function	modules/home-manager/lib/default.nix
App config file (non-nix)	.config/<app>/ tracked in the repo

Adding Services on chungus

When adding a long-running service on chungus that should not be interrupted (e.g. a compute job, media server, or persistent API), check hosts/chungus/services/auto-suspend.nix and consider adding a matching autosuspend check so the machine doesn't suspend while that service is active. Existing checks cover GPU utilisation, llama-server, AI ports (8080/9090), and remote SSH — add an ActiveConnection, ExternalCommand, or Users check as appropriate.

Offer Reusable Modules

When a change is host-specific but would clearly benefit other hosts, suggest extracting it into modules/home-manager/ rather than duplicating it. Ask the user if they want to share it.

Validation

Always validate changes before reporting them as done.

After any .nix file change, format the Nix files before validation:

make format-nix

Check a specific host flake:

nix flake check ./hosts/<hostname>/

Build the system (lapdog or mini only — see permissions below):

# Build NixOS system
nix build ./hosts/<hostname>#nixosConfigurations.<hostname>.config.system.build.toplevel

# Build Home Manager config
nix build ./hosts/<hostname>#homeConfigurations.dog.activationPackage

Run nix flake check first; build only if the change is substantial or something might silently be broken at evaluation time.

Permissions

You are authorized to build the following hosts locally for verification:

• lapdog
• mini

You are forbidden from building:

• chungus
• inspiron7520

You are forbidden from running nixos-rebuild switch, nixos-rebuild boot, home-manager switch, or any command that activates a new generation. Only the user performs these actions manually. Your role ends at building/validating.

Reading Flake Inputs

Flake inputs are pinned and symlinked to /etc/nix/inputs/ on the current machine. Read these for reference when you need to understand available options, module interfaces, or upstream source code:

Input	Path
nixpkgs	/etc/nix/inputs/nixpkgs/
home-manager	/etc/nix/inputs/home-manager/
llm-agents	/etc/nix/inputs/llm-agents/

Other inputs (e.g., my-niri, nur, musnix) are also available under /etc/nix/inputs/. Use these sources to check option names, module signatures, and package availability rather than guessing.