254 lines
9.7 KiB
Markdown
254 lines
9.7 KiB
Markdown
# 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/<profile>.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/<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.
|
||
|
||
### ❌ 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/<name>.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/<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.
|
||
- **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/<hostname>/`. The folder must contain at minimum
|
||
a `default.nix`. Split larger hosts into focused files:
|
||
|
||
```
|
||
hosts/<hostname>/
|
||
├── 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
|
||
│ ├── <service>.nix # One file per service (when > ~3 services)
|
||
├── networking.nix # Firewall, Tailscale, NFS mounts, hosts
|
||
├── home/
|
||
│ └── default.nix # home-manager users.<name> 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/<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/default.nix` (non-slim mode)
|
||
- 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
|
||
services.displayManager.dms-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:
|
||
|
||
```bash
|
||
# 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
|