Files
nixos-setup/GUIDELINES.md
T
2026-06-21 00:11:14 -04:00

4.8 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.


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/
  • Creating or updating documentation in docs/ or ABOUTME.md / GUIDELINES.md
  • 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