# Agent Guide

## Directory Structure

```
/etc/nixos/
├── flake.nix                    # Main flake configuration
├── flake.lock                   # Locked versions
├── AGENTS.md                    # This file
├── treefmt.nix                  # Code formatting config
├── qemu.nix                     # QEMU testing config
│
├── systems/                     # System configurations by architecture
│   ├── aarch64-linux/
│   │   ├── macbook-pro-nixos/   # Apple Silicon MacBook
│   │   │   ├── default.nix
│   │   │   ├── boot.nix
│   │   │   ├── services.nix     # logind, gdm, gnome, flatpak, etc.
│   │   │   ├── filesystems.nix
│   │   │   ├── hardware-configuration.nix
│   │   │   └── firmware/        # Asahi firmware
│   │   └── pi5/                 # Raspberry Pi 5
│   │       ├── default.nix
│   │       ├── boot.nix
│   │       ├── adguard.nix
│   │       └── sops.nix
│   ├── x86_64-linux/
│   │   ├── matt-nixos/          # Desktop AMD system
│   │   │   ├── default.nix
│   │   │   ├── boot.nix
│   │   │   ├── filesystems.nix
│   │   │   ├── sops.nix
│   │   │   └── services/
│   │   │       ├── lsfg-vk/
│   │   │       ├── ratbagd/
│   │   │       └── restic/
│   │   ├── allyx/               # ASUS ROG Ally X
│   │   │   ├── default.nix
│   │   │   └── boot.nix
│   │   ├── nuc-nixos/           # Intel NUC
│   │   ├── jallen-nas/          # NAS server
│   │   └── iso-minimal/
│   └── aarch64-darwin/
│       └── macbook-pro/         # macOS (nix-darwin)
│
├── homes/                       # Home-manager configurations
│   ├── aarch64-linux/
│   │   └── matt@macbook-pro-nixos/
│   │       └── default.nix
│   ├── x86_64-linux/
│   └── aarch64-darwin/
│
├── modules/                     # Shared modules
│   ├── nixos/                   # NixOS system modules
│   ├── home/                    # Home-manager modules
│   └── darwin/                  # nix-darwin modules
│
├── packages/                    # Custom package overlays
│   ├── omnissa/
│   ├── bcachefs/
│   ├── raspberrypi/
│   ├── comfyui/
│   ├── homeassistant/
│   ├── librepods-beta/
│   └── ...
│
└── secrets/                     # SOPS secrets
    ├── secrets.yaml             # Master key config
    └── *-secrets.yaml          # Per-host secrets
```

## System Configurations

### macbook-pro-nixos (Apple Silicon MacBook)
- **Path**: `systems/aarch64-linux/macbook-pro-nixos/`
- **Key files**:
  - `services.nix:72-81` - logind/sleep settings
  - `default.nix` - main config, imports all parts
  - `boot.nix` - systemd-boot, kernel params
- **Features**: Asahi Linux, GNOME, Hyprland option, battery management

### matt-nixos (AMD Desktop)
- **Path**: `systems/x86_64-linux/matt-nixos/`
- **Features**: AMD GPU (LACT), GNOME, gaming, Lanzaboote

### allyx (ASUS ROG Ally X)
- **Path**: `systems/x86_64-linux/allyx/`
- **Features**: Jovian NixOS, Steam, handheld-daemon, AMD GPU

### pi5 (Raspberry Pi 5)
- **Path**: `systems/aarch64-linux/pi5/`
- **Features**: Headless, AdGuard, Docker, static IP, UEFI boot

### jallen-nas (NAS Server)
- **Path**: `systems/x86_64-linux/jallen-nas/`
- **Features**: Headless, VPN, bcachefs, restic backups

## NixOS Modules (`modules/nixos/`)

### Desktop Environments
- `desktop/gnome/default.nix` - GNOME configuration
- `desktop/hyprland/default.nix` - Hyprland configuration
- `desktop/cosmic/default.nix` - Cosmic DE configuration

### Hardware
- `hardware/amd/default.nix` - AMD GPU (LACT)
- `hardware/nvidia/default.nix` - NVIDIA GPU
- `hardware/battery/default.nix` - Battery management
- `hardware/raspberry-pi/` - Raspberry Pi support

### Boot & System
- `boot/common/` - Common boot settings
- `boot/lanzaboote/` - Lanzaboote (secure boot)
- `boot/systemd-boot/` - Systemd-boot config
- `boot/plymouth/` - Plymouth splash screen

### Networking
- `network/default.nix` - Network configuration (hostname, firewall, NM)
- `network/options.nix` - Network module options

### Other Services
- `headless/default.nix` - Headless server config (watchdog, no suspend)
- `gaming/default.nix` - Steam, Gamescope, Gamemode
- `programs/default.nix` - System programs (nix-index, gnupg, etc.)

## Home-Manager Modules (`modules/home/`)

### Programs
- `programs/waybar/` - Wayland bar
- `programs/hyprland/` - Hyprland config
- `programs/kitty/` - Kitty terminal
- `programs/wofi/` - Wofi launcher
- `programs/wlogout/` - Logout menu
- `programs/btop/` - System monitor
- `programs/git/` - Git configuration
- `programs/zsh/` - Zsh configuration
- `programs/mako/` - Notification daemon

### Desktop
- `desktop/gnome/` - GNOME settings
- `desktop/stylix/` - Stylix theming

### Services
- `services/sops/` - SOPS integration

## Custom Packages (`packages/`)

- `omnissa/` - Omnissa Horizon client
- `bcachefs/` - Bcachefs tools
- `raspberrypi/` - Raspberry Pi firmware/tools
- `comfyui/` - ComfyUI packages
- `homeassistant/` - Home Assistant components
- `librepods-beta/` - LibrePODS beta (AirPods support)

## Common Patterns

### Enable a desktop environment
```nix
${namespace}.desktop.gnome.enable = true;
${namespace}.desktop.hyprland.enable = true;
```

### Enable SOPS
```nix
${namespace}.sops.enable = true;
```

### Enable headless mode
```nix
${namespace}.headless.enable = true;
```

### System imports
```nix
imports = [
  ./boot.nix
  ./filesystems.nix
  ./hardware-configuration.nix
  ./services.nix
];
```

### Namespace options (flake.nix:253)
```nix
namespace = "mjallen";
```

## SOPS Secrets

Secrets are encrypted with SOPS. Each system has its own secrets file:
- `secrets/mac-secrets.yaml` - macbook-pro-nixos
- `secrets/pi5-secrets.yaml` - pi5
- `secrets/allyx-secrets.yaml` - allyx
- `secrets/nuc-secrets.yaml` - nuc-nixos
- `secrets/nas-secrets.yaml` - jallen-nas

## Flake Inputs (flake.nix)

Key inputs:
- `nixpkgs-unstable` - Unstable channel
- `nixpkgs-stable` - Stable channel (25.11)
- `home-manager-unstable` - Home-manager
- `nixos-apple-silicon` - Apple Silicon support
- `nixos-hardware` - Common hardware configs
- `disko` - Disk partitioning
- `sops-nix` - Secrets management
- `lanzaboote` - Secure boot
- `jovian` - Steam Deck support (allyx)

## Lib Module (`lib/`)

Custom utility library exposed via `lib.mjallen.*` through Snowfall Lib. Used for creating modules and managing versions.

### Directory Structure
```
lib/
├── default.nix          # Entry point: exports module, file, versioning
├── README.md            # Detailed documentation
├── module/              # Module creation helpers
│   └── default.nix
├── file/                # File/path utilities
│   └── default.nix
└── versioning/          # Multi-source version pinning
    └── default.nix
```

### Module Utilities (`lib.mjallen.module`)

**`mkModule`** - Create NixOS service modules with standardized options:
```nix
lib.mjallen.module.mkModule {
  config, name, description, options, moduleConfig, domain ? "services"
}
```
Standard options: `enable`, `port`, `reverseProxy`, `firewall`, `createUser`, `configureDb`, `redis`, `puid`, `pgid`, `timeZone`, etc.

**`mkContainerService`** - For Podman/OCI containers (auto-generates container definition):
```nix
lib.mjallen.module.mkContainerService {
  config, name, image, internalPort, description, options, volumes, environment
}
```

**`mkSopsEnvFile`** - Generate SOPS secrets + template env-file:
```nix
lib.mjallen.module.mkSopsEnvFile {
  secrets, name, content, restartUnit, owner, group, mode, sopsFile
}
```

**Option Helpers:**
- `mkOpt type default description` - Standard option
- `mkBoolOpt default description` - Boolean option
- `mkReverseProxyOpt name` - Caddy reverse proxy sub-options

**Convenience Shorthands:**
- `enabled` = `{ enable = true; }`
- `disabled` = `{ enable = false; }`

### Home Manager Utilities

**`mkHomeModule`** - Create Home Manager modules:
```nix
lib.mjallen.module.mkHomeModule {
  config, domain, name, description, options, moduleConfig
}
```

### File Utilities (`lib.mjallen.file`)

- `readFile path` - Read file contents
- `pathExists path` - Check if path exists
- `safeImport path default` - Safe Nix import
- `getFile relativePath` - Get path relative to flake root
- `importModulesRecursive path` - Recursively discover Nix modules
- `scanSystems systemsPath` - Discover system configurations
- `filterNixOSSystems systems` - Filter for Linux systems
- `filterDarwinSystems systems` - Filter for macOS systems
- `scanHomes homesPath` - Parse home-manager configurations

### Versioning Utilities (`lib.mjallen.versioning`)

For packages with `version.json` (multi-variant source pinning):

- `selectVariant spec variantName system` - Select variant from spec
- `render value variables` - Template substitution (`${var}`)
- `mkSrc pkgs comp variables` - Build single source
- `mkAllSources pkgs selected` - Build all sources for selected variant

See `lib/versioning/default.nix` for full API and `docs/version.schema.json` for schema.

### Usage in Packages

Create `packages/<name>/version.json` with variant definitions, then use:
```nix
let
  versioning = inputs.self.lib.mjallen.versioning;
  spec = inputs.self.lib.mjallen.file.readFile ./version.json;
  selected = versioning.selectVariant spec variantName system;
  sources = versioning.mkAllSources pkgs selected;
in
# Use sources.componentName for each source
```