Nix-Vibe public snapshot (squashed history)

2026-09-19 13:56:12 +01:00
commit aee8fb1e9b
119 changed files with 18895 additions and 0 deletions
@@ -0,0 +1,92 @@
+# 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