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

142 lines
4.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
```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/<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:
```nix
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:
```bash
# 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