# Agent Guidelines — nixos-setup Rules and best practices for any AI agent working in this repository. Read this file before making any changes. --- ## Mandatory First Step — Always Present a Plan Before making **any** change to this repository, you MUST present a short plan to the user and wait for their approval. This applies to every task, no matter how small. Your plan must include: 1. **What** you intend to change (files, options, packages) 2. **Why** the change is needed 3. **How** you will do it (which files you will edit, in what order) 4. **What you will NOT do** (e.g., "I will not run any builds") Only after the user approves the plan may you proceed with edits. --- ## 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 / boot / install skyg hm switch / build nix build docker/podman build nixos-anywhere ``` The only exception is lightweight operations like ``` nh os switch --dry nix flake check ``` **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 run `skyg remote install` or nixos-anywhere — ZERO EXCEPTIONS This wipes every disk in `hosts/.disko.nix`. A second run is as destructive as the first. Always make the user run it. Do not invoke it, even with `--force-wipe`, even if asked. ### ❌ 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. ### ❌ 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. ### ❌ NEVER edit files inside `hosts/*/hardware-configuration/` These are generated by `nixos-generate-config` and split into `boot.nix` / `file-system.nix`. They reflect physical hardware — edits will be overwritten and can render a system unbootable. The `# Clanker ! Do not modify this file!` header is not a suggestion. ### ❌ NEVER add top-level config to a host's `default.nix` that belongs in a sub-file Every host folder follows a standard layout. Put config in the file that matches its scope: | Config type | File | | --------------------- | ------------------------- | | Hardware / firmware | `hardware.nix` | | Systemd / boot loader | `systemd.nix` | | Packages | `packages.nix` | | Networking / firewall | `networking.nix` | | Services (few) | `services.nix` | | Services (many) | `services/.nix` | | Home-manager | `home/default.nix` | | Generated hardware | `hardware-configuration/` | Don't dump unrelated options into `default.nix` — split them into the right file. ### KEEP EVERYTHING CONCISE, shorter concise comments are preferable, less jargon and more common words. --- ## 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/` - `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. - **Keep ABOUTME.md current:** whenever you add, remove, or rename files, options, commands, or behaviour in a folder, check that folder's `ABOUTME.md` still matches reality and update it as part of the same change. If you discover an existing `ABOUTME.md` that is stale (dead file/option/command references, missing entries, wrong paths), fix it in the same way. - 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. ```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 File Structure Each host is a folder under `hosts//`. The folder must contain at minimum a `default.nix`. Split larger hosts into focused files: ``` hosts// ├── default.nix # skyg options, top-level settings, display manager ├── hardware.nix # Host-specific hardware (fwupd, kernel params, firmware) ├── systemd.nix # Boot loader, systemd targets/services, tmp, swap ├── packages.nix # environment.systemPackages (extract when > ~10 packages) ├── services.nix # Flat service configs (when < ~3 services) ├── services/ │ ├── default.nix # imports all service files │ ├── .nix # One file per service (when > ~3 services) ├── networking.nix # Firewall, Tailscale, NFS mounts, hosts ├── home/ │ └── default.nix # home-manager users. block └── hardware-configuration/ # Generated — DO NOT TOUCH ├── default.nix ├── boot.nix └── file-system.nix ``` ### 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/default.nix` (non-slim mode) - 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 services.displayManager.dms-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 If you want to verify syntax **without triggering a build**, these are safe: ```bash # Check Nix expression syntax only (fast, safe, no eval) nix-instantiate --parse .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