// Patterns for this nix-config flake repository. Use when editing .nix files, adding packages, creating modules, or debugging flake issues.
Use when a Steam, Proton, Wine, Lutris, or Heroic game misbehaves on Linux — crashes at launch, black screen, missing DLSS / Ray Tracing / Path Tracing / DLSS-RR / Frame Generation, anti-cheat failures, shader stutter, controller or HDR or Wayland-fullscreen problems, intro-video failures ("Failed to create SourceReader", MF_E_UNEXPECTED), NVAPI "Unknown function ID" log spam, gamescope dedup black-screens, vkd3d swapchain crashes. Especially before patching or forking DXVK, vkd3d-proton, dxvk-nvapi, gamescope, Wine, or Proton; before reading RE Engine, Unreal, Unity, Source 2, id Tech, or Decima logs; or when a game is mentioned with NVIDIA Blackwell, NixOS, niri, gamescope, proton-cachyos, GE-Proton, or proton-tkg. Triggers on phrases like "won't launch", "RT/PT grayed out", "Proton fix for", "/WineDetectionEnabled", "ProtonDB", "VKD3D_CONFIG", "PROTON_USE_WAYLAND", or any moment the impulse is "let me read the Proton/Wine/vkd3d source" before checking community fixes.
Builds NixOS installer ISOs for hosts using the autoInstaller module. Use when creating installer USBs, adding new hosts to the installer system, or troubleshooting installer issues.
Configures Home Assistant dashboards and automations on ultraviolet. Use when editing HA dashboards, Bubble Cards, YAML configs, or using hass-cli.
| name | writing-nix-config |
| description | Patterns for this nix-config flake repository. Use when editing .nix files, adding packages, creating modules, or debugging flake issues. |
| Rule | Why |
|---|---|
Run update after changes | Nothing takes effect until rebuilt |
Run git add before nix flake check | Flakes only see git-tracked files |
Use lib.fakeHash for unknown hashes | Nix will tell you the real hash on build failure |
| Wrong | Right |
|---|---|
Running nix flake check on new files without git add | git add <file> first |
| Editing config and expecting immediate effect | Run update to rebuild |
| Guessing SHA256 hashes | Use lib.fakeHash, build, copy real hash from error |
| Adding package only to overlay | Also add to pkgs/default.nix |
update # Rebuild current system
nix flake check # Validate flake
nix build .#<package> # Build package
nix eval .#nixosConfigurations.<host>.config.<option> # Check config value
# pkgs/<name>/default.nix
{ lib, stdenv, fetchFromGitHub, ... }:
stdenv.mkDerivation rec {
pname = "name";
version = "1.0.0";
src = fetchFromGitHub {
owner = "...";
repo = "...";
rev = "v${version}";
hash = "sha256-AAAA..."; # Use lib.fakeHash first, nix will tell you real hash
};
meta = with lib; {
description = "...";
license = licenses.mit;
platforms = platforms.all;
};
}
Then add to pkgs/default.nix and overlays/default.nix.
# home-manager/<app>/default.nix
{ pkgs, lib, ... }: {
home.packages = [ pkgs.app ];
# Or use programs.<app> if module exists
programs.app = {
enable = true;
settings = { ... };
};
}
Then import in home-manager/common.nix or platform-specific file.
# 1. Add to secrets/secrets.nix
"secrets/hosts/<host>/<name>.age".publicKeys = keys.<host>;
# 2. Declare in host config
age.secrets."<name>" = {
file = ../../secrets/hosts/<host>/<name>.age;
owner = "<service-user>";
mode = "0400";
};
# 3. Create the secret
agenix -e secrets/hosts/<host>/<name>.age
| Host | Platform | Notes |
|---|---|---|
| ninuan | macOS | Primary dev, Aerospace WM |
| ultraviolet | NixOS | Headless server |
| bluedesert | NixOS | Headless server |
| echelon | NixOS | Headless server |