Files
2026-09-25 14:51:13 -04:00

254 lines
9.7 KiB
Markdown
Raw Permalink 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.
---
## 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