Files
nixos-setup/GUIDELINES.md
T
2026-06-26 16:07:47 -04:00

5.0 KiB
Raw Blame History

Agent Guidelines — nixos-setup

Rules and best practices for any AI agent working in this repository. Read this file before making any changes.


Hard Rules — Never Break These

❌ NEVER run builds or system switches

Do NOT run any of the following, ever:

nixos-rebuild switch / test / build
nh os switch / test / build
skyg os switch / test / build
skyg remote switch / test / build
skyg hm switch / build
nix build
nix flake check

These commands take 20–40+ minutes, consume significant CPU/RAM, and can break a live system. The user runs these themselves after reviewing changes. Your job is to make correct edits to the source files — not to apply them.

❌ NEVER edit flake.lock by hand

This file is managed exclusively by nix flake update. Editing it manually will corrupt the lock file and break all builds.

❌ NEVER edit *.hardware-configuration.nix files

These are generated by nixos-generate-config and reflect the physical hardware. Edits will be overwritten on the next hardware scan and can render a system unbootable.

❌ NEVER touch secrets

Do not read, write, or delete files in secrets/. Encrypted .age files must only be managed with agenix via the skyg secrets commands. Do not modify secrets.nix unless the user explicitly asks and explains the full context.

❌ NEVER add imports = [...] to host files

Host files (hosts/<hostname>.nix) do not use imports. All modules are composed through the makeNixOs call in flake.nix via modules/main.nix. Adding imports to a host file breaks the composition model.

❌ NEVER modify GUIDELINES.md unless explicitly requested by the user, you must live and die by these and hold yourself accountable to them!


Safe Operations

These are always safe to perform without asking:

  • Reading any .nix, .md, or config file
  • Editing host files (hosts/<hostname>.nix) to add/remove packages or options
  • Editing module files in modules/
  • ABOUTME.md should be seen as the 'living memory' of a folder, it should contain general information about what's in the folder and capture decisions made at the time of development the features.
  • Adding new packages to pkgs/
  • Editing configs in configs/

NixOS Conventions in This Repo

Option Namespace

All custom options live under skyg.*. Never introduce options under any other top-level namespace. Check modules/lib.nix for the full skyg.* structure.

# Correct
skyg.nixos.desktop.enable = true;
skyg.nixos.server.services.comfyui.enable = true;

# Wrong — do not invent new top-level attrs
myOptions.desktop.enable = true;

Enable/Disable Pattern

All modules follow lib.mkIf cfg.enable { ... }. Always gate config behind an enable option. Default should be false unless the feature is universally required.

Host Files vs Shared Modules

  • Host-specific (one machine only): goes in hosts/<hostname>.nix
  • Shared (multiple hosts): goes in the appropriate modules/nixos/ or modules/core/ submodule
  • When in doubt, keep it in the host file and extract later if reuse emerges

Package Placement

  • Packages needed on all desktops → modules/nixos/desktop/packages.nix
  • Packages for one host only → environment.systemPackages in the host file
  • Custom/third-party packages not in nixpkgs → pkgs/<name>/default.nix with an overlay in modules/core/default.nix

Home Manager

Home Manager config lives inside home-manager.users.<name> blocks. Do not mix system-level and HM-level options. The HM entry point is modules/home/default.nix.

Greeter

Both desktop hosts (fwbook, hl-fwdesk) use DankMaterialShell greeter via:

programs.dank-material-shell.greeter = {
  enable = true;
  compositor.name = "niri";
  configHome = "/home/<username>";
};

Do not configure services.greetd manually on these hosts — the DMS module handles it.


Navigation Tips

Question Where to look
What hosts exist? hosts/ + docs/hosts/README.md
What does a skyg.* option do? modules/ — find the defining .nix file
What flake inputs are available? Top of flake.nix
What binary caches are configured? modules/core/nix-substituters.nix
What secrets exist? secrets.nix (lists files + authorized keys)
What custom packages exist? pkgs/
Full API reference docs/modules/README.md
Host details (ports, services, hardware) docs/hosts/README.md

Validation Without Building

After making changes you can verify syntax without running a build:

# Check Nix expression syntax only (fast, safe)
nix-instantiate --parse <file>.nix

# Check the flake structure without building
nix flake show --no-build 2>/dev/null

Even these are optional — the user will validate by running nh os switch themselves.


Commit / Branch Policy

  • Do NOT commit changes or create branches unless the user explicitly asks
  • Do NOT git add, git commit, or git push autonomously
  • Describe what you changed in your final message so the user can review before committing