# 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)