Updatet README.md; Added AGENTS.md

AGENTS.md

@@ -0,0 +1,117 @@
+# AGENTS.md
+
+A guide for AI coding agents working in this Nix flake repository.
+
+## Project Overview
+
+Multi-host Nix flake managing NixOS desktops, macOS via nix-darwin, and a home server cluster — all sharing a common Home Manager configuration. Secrets are encrypted with sops-nix + age.
+
+## Key Commands
+
+```fish
+# Apply config on current host (works on any machine)
+nix-switch   # alias for: sudo nixos-rebuild switch --flake ~/.config/nix#(hostname -s)
+             #        or: sudo darwin-rebuild switch --flake .#(hostname -s)
+
+# Check flake without building (NixOS) / eval toplevel (macOS)
+nix-check
+
+# Validate flake inputs and locks
+nix flake check --no-build
+
+# Format Nix files
+nixfmt <file>    # managed via nixvim, runs nixfmt
+
+# Enter dev shell if defined
+nix develop
+```
+
+## Repo Layout
+
+```
+flake.nix                  # Entry point — defines all hosts via mkSystem
+hosts/<hostname>/          # Per-host configuration.nix + hardware-configuration.nix
+nixos/                     # Shared NixOS system modules (audio, fonts, sops, tailscale…)
+nixos/roles/               # Optional services (Gitea, Matrix, Vaultwarden, AdGuard…)
+darwin/                    # macOS-only system modules (fonts, homebrew, yabai, sketchybar)
+home/                      # Shared Home Manager config (all hosts, both platforms)
+home/desktop/              # Desktop-only home modules — Linux (hyprland/niri, waybar, rofi…)
+home/desktop/sketchybar/   # macOS-only bar config
+home/neovim/               # nixvim configuration split by plugin
+assets/                    # Wallpapers and avatar images — do not modify programmatically
+secrets/                   # age-encrypted secrets — never edit .age files directly
+```
+
+## Hosts
+
+| Hostname | Platform | Type | Notes |
+|---|---|---|---|
+| cyper-desktop | NixOS x86_64 | Desktop | Primary Linux workstation |
+| cyper-mac | macOS x86_64 | Desktop | nix-darwin + Homebrew |
+| cyper-controller | NixOS x86_64 | Server | Runs all roles/services |
+| cyper-node-1 | NixOS x86_64 | Server | `isServer = true` |
+| cyper-node-2 | NixOS x86_64 | Server | `isServer = true` |
+
+## mkSystem Convention
+
+All hosts are built via `mkSystem` in `flake.nix`. Key flags:
+
+- `isDarwin = true` → uses `darwin.lib.darwinSystem` + darwin modules
+- `isServer = true` → skips desktop/GUI modules; both flags are passed as `specialArgs` to all modules via `sharedSpecialArgs`
+
+Guard platform-specific code with:
+
+```nix
+if isDarwin then { ... } else { ... }
+if isServer then { ... } else { ... }
+```
+
+## Home Manager
+
+A single `home/` tree is shared by all hosts. Desktop-only modules live under `home/desktop/` and are conditionally included. The `isDarwin` and `isServer` flags are available as `specialArgs` inside Home Manager modules.
+
+## Secrets
+
+Managed with [sops-nix](https://github.com/Mic92/sops-nix) + age encryption.
+
+- **Never edit `.age` files directly** — use `sops secrets/secrets.yaml`
+- Age key must exist at `~/.config/sops/age/keys.txt` on every host
+- Public keys are declared in `secrets/keys.txt.age` and `.sops.yaml` (if present)
+- Secrets are referenced in Nix via `config.sops.secrets.<name>.path`
+
+## Conventions
+
+- **Formatter:** `nixfmt` (run via nixvim; apply before committing)
+- **No `hardware-configuration.nix` edits** — these are machine-generated; regenerate with `nixos-generate-config` if needed
+- **Homebrew** is managed declaratively via `darwin/homebrew.nix` — do not run `brew install` manually
+- **Catppuccin** theming is applied system-wide via `home/catppuccin.nix` and `nixos/catppuccin.nix`; keep theme tokens consistent across modules
+- **Shell is Fish** — shell aliases and functions live in `home/shell.nix`; use fish syntax
+
+## Adding a New Host
+
+1. Create `hosts/<hostname>/configuration.nix` (and `hardware-configuration.nix` for NixOS)
+2. Add an entry to `nixosConfigurations` (or `darwinConfigurations`) in `flake.nix` via `mkSystem`
+3. Add the host to the machines table in `README.md` and this file
+
+## Adding a New Role/Service
+
+1. Create `nixos/roles/<service>.nix`
+2. Import it in the relevant host's `configuration.nix` or in `nixos/default.nix` behind an `isServer` guard
+3. Add any required secrets to `secrets/secrets.yaml` via `sops`
+
+## PR Checklist
+
+- [ ] `nix flake check --no-build` passes
+- [ ] `nixfmt` applied to changed `.nix` files
+- [ ] No hardcoded paths or usernames — use `primaryUser` / `hostName` from `specialArgs`
+- [ ] Secrets referenced via sops, not inlined
+- [ ] `hardware-configuration.nix` untouched unless intentional
+- [ ] README and AGENTS.md updated if hosts, roles, or structure changed
+
+## Gotchas
+
+- `primaryUser` is defined in `flake.nix` and injected everywhere via `sharedSpecialArgs` — never hardcode the username
+- `home-manager.backupFileExtension = "backup"` is set globally; conflicts create `.backup` files rather than erroring
+- The `l` fish function calls a Groq LLM (`llama-3.3-70b-versatile`) and pipes output through `glow` — it requires `$GROQ_API_KEY` to be set as a file path
+- sketchybar lives under `home/desktop/sketchybar/` but is macOS-only; hyprland/niri are Linux-only
+- `nix-switch` uses `hostname -s` at runtime — the hostname must match a key in `nixosConfigurations` / `darwinConfigurations`