# AGENTS.md — Nix-Vibe AI Agent Instructions

A Nix Flakes-based multi-host NixOS + Home Manager configuration repository.

## Quick Reference

- **Build/Test**: `nix flake check` (must `git add` new files first)
- **Task runner**: `just` (see `justfile`) — `just` deploys a host + restarts quickshell, `just check`, `just dry-build`, `just test`, `just restart-qs`
- **Format**: `nixpkgs-fmt .` (or `nix fmt` — the flake defines a `nixpkgs-fmt` formatter)
- **Dev shell**: `nix develop` (provides `sops`, `age`, `nixpkgs-fmt`)
- **Apply**: `sudo nixos-rebuild switch --flake .#<hostname>`
- **Test (no activation)**: `sudo nixos-rebuild test --flake .#<hostname>`
- **Remote apply**: `nixos-rebuild switch --target-host <host> --flake .#<hostname> --use-remote-sudo`
- **Dry-build**: `nixos-rebuild dry-build --flake .#<hostname>`

## Architecture

| Directory | Purpose |
|-----------|---------|
| `hosts/<name>/` | Per-machine configs (`configuration.nix`, `disko-config.nix`, `hardware-configuration.nix`) |
| `modules/core/` | Shared NixOS modules (common, fonts, settings, sops, podman, dev, users, management, known-hosts) |
| `modules/desktop/` | GUI desktop modules and app-specific modules |
| `modules/hardware/` | Hardware-specific modules (fingerprint, nvidia) |
| `modules/services/` | Service modules (immich, jellyfin, ntfy, paperless, immich-proxy) |
| `modules/storage/` | Disk configuration via Disko |
| `home-manager/modules/` | Shared Home Manager modules (zsh, gnome, firefox, kitty, etc.) |
| `home-manager/users/` | Per-user Home Manager configs |
| `flake.nix` | Entry point — defines `nixosConfigurations` via `mkNixosSystem` helper |

Host overview and software inventory: see [README.md](./README.md).

## Critical Rules

### Style
- **Language**: Nix — follow conventions used in the `nixpkgs` repository.
- **Formatter**: `nixpkgs-fmt .` (run before every commit).

### Git & Flakes
- **NEW FILES MUST BE STAGED** (`git add`) before `nix flake check` or `nixos-rebuild`. Flake evaluation only sees Git-tracked files.
- Do NOT commit until `nix flake check` AND a dry-build pass.

### Module Pattern
- New service modules follow the pattern: `lib.mkEnableOption` for `enable` + `lib.mkIf config.services.<name>.enable { ... }`.
- Example: [modules/services/immich.nix](./modules/services/immich.nix)

### Secrets
- Secrets are managed via [SOPS + age](./docs/sops-secrets.md) in `secrets.yaml`.
- Reference in host configs as `sops.secrets."<path>" = { ... };`.
- Rendered config files (e.g. container env files) use `sops.templates` — see [docs/sops-secrets.md](./docs/sops-secrets.md).

### Sudo
- Passwordless sudo is granted to **`petere` only** via `security.sudo.extraRules` (NOPASSWD) in `modules/core/common.nix`. All other wheel users must enter a password for `sudo`.

### Zsh
- `programs.zsh.enable = true` must be set in NixOS config for Zsh users.
- Shared Zsh config uses `home-manager.sharedModules` in `flake.nix` — do NOT use `home.file.".zshrc"`.

### Servers vs Desktops
- Servers (`richmond-server`, `homeserver-1`, `mcf-server`) use `serverOverlays` (lightweight).
- Desktops/laptops use `desktopOverlays` (`stable` without CUDA) by default.
- Only `x1carbon` uses the full `overlays` set with CUDA, NDI, stable packages (OBS Studio).

### Deprecated Options
- Pay attention to warnings about deprecated options during `nix flake check` or `nixos-rebuild`. Refer to NixOS/Home Manager release notes for updated options. Keeping configurations current prevents surprises on channel updates.

### Homepage Dashboard (gethomepage.dev)
- Dashboard definition for homeserver-1 lives in `hosts/homeserver-1/homepage.nix` (imported by the host config), NOT in `configuration.nix`.
- Full guide for adding machines/tabs/services: [docs/homepage-dashboard.md](./docs/homepage-dashboard.md).
- Widget group names MUST be unique — the credentialed proxy resolves config by leaf group name; duplicate names cause one machine's stats to render on another's tiles.
- Every Glances widget tile needs a `metric` field (`info`, `cpu`, `memory`, `fs:/`, `process`, ...) and `version = 4`; omitting `metric` throws `t.metric is undefined`.
- Tailscale widget `deviceid` must be the **numeric** device ID (from the Tailscale API), not the `...CNTRL` value.
- API keys are injected as `HOMEPAGE_VAR_*` env vars from the SOPS secret `homeserver-1/homepage-env` — never hardcode keys in `homepage.nix`.
- After editing `homepage.nix`, if changes don't appear after rebuild, restart the service: `sudo systemctl restart homepage-dashboard` (config files are only read at service start).
- Homepage is exposed on Tailscale only (port 8082).

## Post-Modification Workflow

1. Update `README.md` software inventory and host overview if relevant
2. When adding a new host, add it to the Host Reference table in `.github/skills/nix-flake-rebuild/SKILL.md` (informational; the dry-build loop is dynamic)
3. `git add` all modified/new files
4. `nix flake check`
5. `nixos-rebuild dry-build --flake .#<hostname>` for affected hosts
6. Commit only after both checks pass

## Documentation

- [README.md](./README.md) — Full architecture, host roles, and entry point for all docs
- [docs/software-inventory.md](./docs/software-inventory.md) — Cross-reference matrix of software per host
- [docs/installation.md](./docs/installation.md) — nixos-anywhere deployment guide
- [docs/sops-secrets.md](./docs/sops-secrets.md) — SOPS/age secrets management
- [docs/borg-backup-setup.md](./docs/borg-backup-setup.md) — BorgBackup server setup (deprecated - migrated to Backrest)
- [docs/homepage-dashboard.md](./docs/homepage-dashboard.md) — Homepage dashboard: adding machines, tabs & services