current build

This commit is contained in:
ari committed 2026-06-21 00:11:14 -04:00
1 parent 842ac07091
commit c031fc7ae1
11 files changed
+401 -1

No files matched your search

+141
View File
@@ -0,0 +1,141 @@
# 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