# 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/.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/.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. ```nix # 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/.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//default.nix` with an overlay in `modules/core/default.nix` ### Home Manager Home Manager config lives inside `home-manager.users.` 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: ```nix programs.dank-material-shell.greeter = { enable = true; compositor.name = "niri"; configHome = "/home/"; }; ``` 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: ```bash # Check Nix expression syntax only (fast, safe) nix-instantiate --parse .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