Files
nixos-setup/GUIDELINES.md
T
2026-06-28 15:35:11 -04:00

5.7 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 — ZERO EXCEPTIONS

DO NOT RUN ANY OF THESE COMMANDS AT ANY TIME, FOR ANY REASON:

nixos-rebuild switch / test / build / dry-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
docker/podman build

Why:

  • These commands take 20–40+ minutes
  • They consume significant CPU/RAM on the user's machine
  • They can block the user from their own work
  • They can break the live system if something is wrong
  • The user MUST control when and what gets built

Your job: Make correct edits to source files. The user validates and runs builds themselves.

Even if the user says "go ahead": Do NOT run these. Your role is to write good Nix, not execute it.

❌ 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 rules and hold yourself accountable to them. These are not suggestions — they are non-negotiable.


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/

When In Doubt

If you are unsure whether a command is safe, assume it is not safe and don't run it.

Instead: describe what you would do and ask the user for permission.


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

If you want to verify syntax without triggering a build, these are safe:

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

But even these are optional. The user will validate by running nh os switch themselves.

Golden rule: When in doubt, don't run anything. Just describe your changes.


Commit / Branch / Git Policy

  • Do NOT commit changes or create branches unless the user explicitly asks
  • Do NOT git add, git commit, or git push autonomously
  • You may run git add only if required for a Nix evaluation (e.g., new files must be tracked for flakes)
  • Describe what you changed in your final message so the user can review before committing